Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
refactor(idempotency): move the Idempotency-Key store into a shared module with an atomic claim
nirholas58e8cd09dffa
diff --git a/api/_lib/agents-v1/http.js b/api/_lib/agents-v1/http.jsindex b2b70e1bd..be9bccd43 100644--- a/api/_lib/agents-v1/http.js+++ b/api/_lib/agents-v1/http.js@@ -22,13 +22,21 @@// 500 with a sanitized message; the stable error codes are listed in// docs/api-reference.md.-import { createHash, randomUUID } from 'node:crypto';+import { randomUUID } from 'node:crypto';import { cors, readJson, setRateLimitHeaders } from '../http.js';import { authenticateBearer, extractBearer, getSessionUser, hasScope } from '../auth.js';import { checkCsrf } from '../csrf.js';import { limits, clientIp } from '../rate-limit.js';import { recordEvent } from '../usage.js';-import { acquireLock, cacheGet, cacheSet, releaseLock } from '../cache.js';+import { acquireLock, releaseLock } from '../cache.js';+import {+ IDEMPOTENCY_KEY_MAX,+ idempotencyStoreKey,+ normalizeIdempotencyKey,+ readIdempotent,+ sha256Hex,+ writeIdempotent,+} from '../idempotency.js';export class ApiError extends Error {/**@@ -204,7 +212,7 @@ export function defineRouter({ base, routes }) {const idem = writes && principal ? idempotencyKey(req, principal, route, body) : null;if (idem) {- const stored = await cacheGet(idem.key).catch(() => null);+ const stored = await readIdempotent(idem.key);if (stored) {if (stored.bodyHash !== idem.bodyHash) {throw apiError(422, 'idempotency_key_reused', 'This Idempotency-Key was already used with a different request body.');@@ -230,7 +238,7 @@ export function defineRouter({ base, routes }) {if (res.headersSent || res.writableEnded) return;const out = shape(ctx, result);if (ctx.idem) {- await cacheSet(ctx.idem.key, { ...out, bodyHash: ctx.idem.bodyHash }, IDEMPOTENCY_TTL_S).catch(() => {});+ await writeIdempotent(ctx.idem.key, { ...out, bodyHash: ctx.idem.bodyHash }).catch(() => {});}return send(res, out.status, out.body);} catch (err) {@@ -252,8 +260,6 @@ export function defineRouter({ base, routes }) {};}-const IDEMPOTENCY_TTL_S = 24 * 60 * 60;-function shape(ctx, result) {if (result && result[CREATED]) return { status: 201, body: { data: result.data, meta: meta(ctx) } };if (result && result.__page) {@@ -265,14 +271,18 @@ function shape(ctx, result) {return { status: 200, body: { data: result ?? null, meta: meta(ctx) } };}+// The store is shared with the MCP studio's idempotency_key (../idempotency.js).function idempotencyKey(req, principal, route, body) {- const raw = req.headers['idempotency-key'];- if (typeof raw !== 'string' || !raw.trim()) return null;- if (raw.length > 200) throw apiError(400, 'invalid_idempotency_key', 'Idempotency-Key must be at most 200 characters.');- const digest = (v) => createHash('sha256').update(v).digest('hex');+ let key;+ try {+ key = normalizeIdempotencyKey(req.headers['idempotency-key']);+ } catch {+ throw apiError(400, 'invalid_idempotency_key', `Idempotency-Key must be at most ${IDEMPOTENCY_KEY_MAX} characters.`);+ }+ if (!key) return null;return {- key: `v1:idem:${principal.userId}:${route.name}:${digest(raw.trim())}`,- bodyHash: digest(`${req.url}\n${JSON.stringify(body)}`),+ key: idempotencyStoreKey('v1', `${principal.userId}:${route.name}`, key),+ bodyHash: sha256Hex(`${req.url}\n${JSON.stringify(body)}`),};}diff --git a/api/_lib/cache.js b/api/_lib/cache.jsindex d275af7d2..0ee9381fe 100644--- a/api/_lib/cache.js+++ b/api/_lib/cache.js@@ -513,6 +513,38 @@ export async function acquireLock(key, ttlSeconds) {}}+/**+ * Store `value` under `key` only if nothing is there yet (Redis `SET NX EX`),+ * and say whether this caller's write is the one that landed. Unlike+ * acquireLock, the claim carries a real value, so whoever loses the race can+ * read what the winner recorded (the idempotency store claims a key and its job+ * handle in one command this way). With Redis unconfigured or unreachable it+ * degrades to the same check against per-instance memory.+ *+ * @param {string} key+ * @param {unknown} value+ * @param {number} ttlSeconds+ * @returns {Promise<boolean>}+ */+export async function cacheSetIfAbsent(key, value, ttlSeconds) {+ const claimInMemory = () => {+ if (memGet(key) !== null) return false;+ memSet(key, value, ttlSeconds);+ return true;+ };+ if (!redisConfigured()) return claimInMemory();+ try {+ const body = await encodeForWire(JSON.stringify(value));+ const res = await redisCmd(['SET', key, body, 'NX', 'EX', String(ttlSeconds)]);+ if (res !== 'OK') return false;+ memoPut(key, value);+ return true;+ } catch (err) {+ if (!err?.circuitOpen) warnThrottled('setIfAbsent', `[cache] SET NX failed, claiming in memory: ${err?.message}`);+ return claimInMemory();+ }+}+/*** Release a lock taken with acquireLock. Best-effort — a failed release just* leaves the lock to expire on its TTL.diff --git a/api/_lib/idempotency.js b/api/_lib/idempotency.jsnew file mode 100644index 000000000..2d2142a66--- /dev/null+++ b/api/_lib/idempotency.js@@ -0,0 +1,92 @@+// The shared idempotency store: one key, one outcome, for 24 hours.+//+// Two front doors use it:+// • HTTP the v1 agents API (./agents-v1/http.js) replays a write that carries+// an `Idempotency-Key` header.+// • MCP the free 3D studio (../_mcp-studio/jobs.js) hands a retried+// generation the job the first call started instead of a second job.+//+// A record lives in the shared cache (Redis, with per-instance memory as its+// degraded fallback), keyed by who is calling and a hash of the key they chose,+// so the raw key never appears in a key listing and two callers who pick the+// same key never meet.++import { createHash } from 'node:crypto';+import { cacheDel, cacheGetFresh, cacheSet, cacheSetIfAbsent } from './cache.js';++export const IDEMPOTENCY_TTL_S = 24 * 60 * 60;+export const IDEMPOTENCY_KEY_MAX = 200;++export function sha256Hex(value) {+ return createHash('sha256').update(String(value)).digest('hex');+}++/**+ * The trimmed key, or null when none was sent. Throws a coded error for a key+ * longer than IDEMPOTENCY_KEY_MAX, which each front door renders its own way.+ * @param {unknown} raw+ * @returns {string|null}+ */+export function normalizeIdempotencyKey(raw) {+ if (typeof raw !== 'string') return null;+ const key = raw.trim();+ if (!key) return null;+ if (key.length > IDEMPOTENCY_KEY_MAX) {+ throw Object.assign(new Error(`idempotency key must be at most ${IDEMPOTENCY_KEY_MAX} characters`), {+ code: 'invalid_idempotency_key',+ });+ }+ return key;+}++/**+ * Where a caller's key lives. `scope` names the surface (and, for HTTP, the+ * route) so one key can mean different things on different endpoints.+ * @param {string} scope+ * @param {string} caller+ * @param {string} key+ */+export function idempotencyStoreKey(scope, caller, key) {+ return `${scope}:idem:${caller}:${sha256Hex(key)}`;+}++/** Stable digest of a request's arguments, used to refuse a key reused for a different request. */+export function fingerprint(value) {+ return sha256Hex(stableStringify(value));+}++// JSON with sorted object keys, so `{a, b}` and `{b, a}` fingerprint the same.+function stableStringify(value) {+ if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;+ if (value && typeof value === 'object') {+ return `{${Object.keys(value)+ .filter((k) => value[k] !== undefined)+ .sort()+ .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)+ .join(',')}}`;+ }+ return JSON.stringify(value ?? null);+}++/** The record stored under a key, or null. Always a fresh read: a retry is waiting for it to change. */+export async function readIdempotent(storeKey) {+ return cacheGetFresh(storeKey).catch(() => null);+}++/**+ * Claim a key with its first record in one atomic command. True when this+ * caller won the key; false when a record was already there.+ */+export async function claimIdempotent(storeKey, record, ttlSeconds = IDEMPOTENCY_TTL_S) {+ return cacheSetIfAbsent(storeKey, record, ttlSeconds);+}++/** Replace the record under a key the caller already holds. */+export async function writeIdempotent(storeKey, record, ttlSeconds = IDEMPOTENCY_TTL_S) {+ await cacheSet(storeKey, record, ttlSeconds);+}++/** Give a key back, so the next request with it runs as new. */+export async function releaseIdempotent(storeKey) {+ await cacheDel(storeKey);+}diff --git a/tests/idempotency-store.test.js b/tests/idempotency-store.test.jsnew file mode 100644index 000000000..13c0076b0--- /dev/null+++ b/tests/idempotency-store.test.js@@ -0,0 +1,52 @@+// The shared idempotency store (api/_lib/idempotency.js) behind both the v1+// HTTP `Idempotency-Key` header and the MCP studio's idempotency_key. Runs over+// the real in-memory cache (no Redis in the test env).++import { describe, it, expect } from 'vitest';+import {+ claimIdempotent,+ fingerprint,+ IDEMPOTENCY_KEY_MAX,+ idempotencyStoreKey,+ normalizeIdempotencyKey,+ readIdempotent,+ releaseIdempotent,+ writeIdempotent,+} from '../api/_lib/idempotency.js';++describe('idempotency store', () => {+ it('normalizes keys and refuses one that is too long', () => {+ expect(normalizeIdempotencyKey(' task-1 ')).toBe('task-1');+ expect(normalizeIdempotencyKey('')).toBeNull();+ expect(normalizeIdempotencyKey(undefined)).toBeNull();+ expect(() => normalizeIdempotencyKey('x'.repeat(IDEMPOTENCY_KEY_MAX + 1))).toThrow(/at most/);+ });++ it('keys the store by caller, so two callers never share a record', () => {+ const a = idempotencyStoreKey('mcp-studio', 'caller-a', 'task-1');+ const b = idempotencyStoreKey('mcp-studio', 'caller-b', 'task-1');+ expect(a).not.toBe(b);+ expect(a).not.toContain('task-1');+ });++ it('keeps the v1 HTTP key layout', () => {+ expect(idempotencyStoreKey('v1', 'user-1:agents.create', 'k')).toMatch(/^v1:idem:user-1:agents\.create:[0-9a-f]{64}$/);+ });++ it('fingerprints arguments regardless of key order', () => {+ expect(fingerprint({ a: 1, b: { c: 2, d: 3 } })).toBe(fingerprint({ b: { d: 3, c: 2 }, a: 1 }));+ expect(fingerprint({ a: 1 })).not.toBe(fingerprint({ a: 2 }));+ });++ it('lets exactly one claim win, then reads, replaces and releases the record', async () => {+ const key = idempotencyStoreKey('test', 'caller', `claim-${Date.now()}`);+ expect(await claimIdempotent(key, { state: 'running', n: 1 })).toBe(true);+ expect(await claimIdempotent(key, { state: 'running', n: 2 })).toBe(false);+ expect(await readIdempotent(key)).toEqual({ state: 'running', n: 1 });+ await writeIdempotent(key, { state: 'done', n: 1 });+ expect((await readIdempotent(key)).state).toBe('done');+ await releaseIdempotent(key);+ expect(await readIdempotent(key)).toBeNull();+ expect(await claimIdempotent(key, { state: 'running', n: 3 })).toBe(true);+ });+});