Skip to content

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.

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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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);
+ });
+});