@classytic/arc 2.41.1 → 2.44.0

package/dist/idempotency/index.mjs

@@ -1,10 +1,15 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { n as requireSingleHeaderValue } from "../headers-BIXWKrzQ.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-dW71XVWL.mjs";
-import { t as createIdempotencyResult } from "../interface-YzIbF7Ii.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { d as createDomainError } from "../errors-CW4anJBy.mjs";
+import { n as requireSingleHeaderValue } from "../headers-DKZQKL-Z.mjs";
+import { i as requestRequiresIdempotencyKey, n as idempotencyConfigProblem, r as requestDedupedByHandler, t as declaresIdempotencyFence } from "../requirement-Bu50QALH.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-Coj9RhOZ.mjs";
+import { n as createIdempotencyResult, r as operationIdentity, t as resolveIdempotencyTiming } from "../timing-CntavTlR.mjs";
+import { n as acquireIdempotencyKey, r as releaseIdempotencyLock } from "../acquire-BozJ-9yt.mjs";
+import { ARC_ERROR_CODES } from "@classytic/repo-core/errors";
 import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
+import { IdempotencyError, fingerprintRequest } from "@classytic/repo-core/idempotency";
 import { update } from "@classytic/repo-core/update";
 //#region src/idempotency/repository-idempotency-adapter.ts
 /**
@@ -60,20 +65,12 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 	}
 	return {
 		name: "repository",
+		completionReleasesLock: true,
 		async get(key) {
 			const doc = await safeGetOne(eq(idField, key));
 			if (!doc) return void 0;
 			assertKeyIdentity("get", doc, key);
-			if (!doc.result) return void 0;
-			if (new Date(doc.expiresAt) < /* @__PURE__ */ new Date()) return void 0;
-			return {
-				key,
-				statusCode: doc.result.statusCode,
-				headers: doc.result.headers,
-				body: doc.result.body,
-				createdAt: new Date(doc.createdAt),
-				expiresAt: new Date(doc.expiresAt)
-			};
+			return completedResult(doc, key);
 		},
 		async set(key, result) {
 			const doc = await r.findOneAndUpdate(eq(idField, key), update({
@@ -81,7 +78,9 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 					result: {
 						statusCode: result.statusCode,
 						headers: result.headers,
-						body: result.body
+						body: result.body,
+						...result.bodyEncoding ? { bodyEncoding: result.bodyEncoding } : {},
+						...result.requestFingerprint ? { requestFingerprint: result.requestFingerprint } : {}
 					},
 					createdAt: result.createdAt,
 					expiresAt: result.expiresAt
@@ -94,6 +93,67 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 			});
 			if (doc) assertKeyIdentity("set", doc, key);
 		},
+		async setIfLocked(key, requestId, result) {
+			const doc = await r.findOneAndUpdate(and(eq(idField, key), eq("lock.requestId", requestId), gt("lock.expiresAt", /* @__PURE__ */ new Date())), update({
+				set: {
+					result: {
+						statusCode: result.statusCode,
+						headers: result.headers,
+						body: result.body,
+						...result.requestFingerprint ? { requestFingerprint: result.requestFingerprint } : {},
+						...result.bodyEncoding ? { bodyEncoding: result.bodyEncoding } : {}
+					},
+					createdAt: result.createdAt,
+					expiresAt: result.expiresAt
+				},
+				unset: ["lock"]
+			}), { returnDocument: "after" });
+			if (!doc) return false;
+			assertKeyIdentity("setIfLocked", doc, key);
+			return true;
+		},
+		async acquire(key, requestId, lockTtlMs) {
+			for (let attempt = 0; attempt < 2; attempt++) {
+				const now = /* @__PURE__ */ new Date();
+				let doc = null;
+				try {
+					doc = await r.findOneAndUpdate(and(eq(idField, key), or(exists("result.statusCode", false), lt("expiresAt", now)), or(exists("lock", false), lt("lock.expiresAt", now))), update({
+						set: {
+							lock: {
+								requestId,
+								expiresAt: new Date(now.getTime() + lockTtlMs)
+							},
+							expiresAt: new Date(now.getTime() + defaultTtlMs)
+						},
+						unset: ["result"],
+						setOnInsert: {
+							[idField]: key,
+							createdAt: now
+						}
+					}), {
+						upsert: true,
+						returnDocument: "after"
+					});
+				} catch (err) {
+					if (!isDuplicateKeyError(err)) throw err;
+				}
+				if (doc) {
+					assertKeyIdentity("acquire", doc, key);
+					return { status: "acquired" };
+				}
+				const existing = await safeGetOne(eq(idField, key));
+				if (existing) {
+					assertKeyIdentity("acquire", existing, key);
+					const result = completedResult(existing, key);
+					if (result) return {
+						status: "completed",
+						result
+					};
+					if (existing.lock && new Date(existing.lock.expiresAt) > /* @__PURE__ */ new Date()) return { status: "locked" };
+				}
+			}
+			return { status: "locked" };
+		},
 		async tryLock(key, requestId, ttlMs) {
 			const now = /* @__PURE__ */ new Date();
 			const lockExpiresAt = new Date(now.getTime() + ttlMs);
@@ -135,11 +195,12 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 			return (await r.deleteMany(startsWith(idField, prefix, "sensitive"))).deletedCount ?? 0;
 		},
 		async findByPrefix(prefix) {
-			const doc = await safeGetOne(and(startsWith(idField, prefix, "sensitive"), exists("result", true), gt("expiresAt", /* @__PURE__ */ new Date())));
-			if (!doc?.result) return void 0;
+			const doc = await safeGetOne(and(startsWith(idField, prefix, "sensitive"), exists("result.statusCode", true), gt("expiresAt", /* @__PURE__ */ new Date())));
+			if (!doc || !isCompleted(doc)) return void 0;
 			if (!String(doc[idField] ?? "").startsWith(prefix)) throw new IdempotencyStoreMisconfiguredError("findByPrefix", prefix, doc[idField]);
 			return {
 				key: String(doc[idField] ?? prefix),
+				...doc.result.requestFingerprint ? { requestFingerprint: doc.result.requestFingerprint } : {},
 				statusCode: doc.result.statusCode,
 				headers: doc.result.headers,
 				body: doc.result.body,
@@ -150,10 +211,33 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 		async close() {}
 	};
 }
+/** The row's unexpired completed response, or `undefined`. */
+function completedResult(doc, key) {
+	if (!isCompleted(doc)) return void 0;
+	if (new Date(doc.expiresAt) < /* @__PURE__ */ new Date()) return void 0;
+	return {
+		key,
+		...doc.result.requestFingerprint ? { requestFingerprint: doc.result.requestFingerprint } : {},
+		statusCode: doc.result.statusCode,
+		headers: doc.result.headers,
+		body: doc.result.body,
+		...doc.result.bodyEncoding ? { bodyEncoding: doc.result.bodyEncoding } : {},
+		createdAt: new Date(doc.createdAt),
+		expiresAt: new Date(doc.expiresAt)
+	};
+}
+/**
+* A row holds a completed response only when it has a status code. A lock-only row can read back
+* with `result: {}` (a nested path in a mongoose schema); replaying that would answer nothing.
+*/
+function isCompleted(doc) {
+	return typeof doc.result?.statusCode === "number";
+}
 //#endregion
 //#region src/idempotency/stores/memory.ts
 var MemoryIdempotencyStore = class {
 	name = "memory";
+	completionReleasesLock = true;
 	results = /* @__PURE__ */ new Map();
 	locks = /* @__PURE__ */ new Map();
 	ttlMs;
@@ -178,12 +262,41 @@ var MemoryIdempotencyStore = class {
 		return result;
 	}
 	async set(key, result) {
+		this.writeResult(key, result);
+	}
+	writeResult(key, result) {
 		if (this.results.size >= this.maxEntries) this.evictOldest();
 		this.results.set(key, {
 			...result,
 			key
 		});
 	}
+	async setIfLocked(key, requestId, result) {
+		const lock = this.locks.get(key);
+		if (!lock || lock.requestId !== requestId || lock.expiresAt.getTime() <= Date.now()) return false;
+		this.writeResult(key, result);
+		this.locks.delete(key);
+		return true;
+	}
+	async acquire(key, requestId, lockTtlMs) {
+		const result = this.results.get(key);
+		if (result) {
+			if (Date.now() <= new Date(result.expiresAt).getTime()) return {
+				status: "completed",
+				result
+			};
+			this.results.delete(key);
+		}
+		const lock = this.locks.get(key);
+		if (lock && Date.now() <= new Date(lock.expiresAt).getTime()) return { status: "locked" };
+		this.locks.set(key, {
+			key,
+			requestId,
+			lockedAt: /* @__PURE__ */ new Date(),
+			expiresAt: new Date(Date.now() + lockTtlMs)
+		});
+		return { status: "acquired" };
+	}
 	async tryLock(key, requestId, ttlMs) {
 		const existing = this.locks.get(key);
 		if (existing) {
@@ -266,42 +379,23 @@ var MemoryIdempotencyStore = class {
 //#endregion
 //#region src/idempotency/idempotencyPlugin.ts
 /**
-* Idempotency — duplicate-request protection for mutations.
-*
-* AUTH ORDER MATTERS: `idempotency.middleware` must run AFTER authentication
-* in the preHandler chain, so the fingerprint includes the real caller and a
-* key cannot replay another user's response. `createCrudRouter` wires this for
-* mutation routes; custom routes do it themselves:
-* `preHandler: [fastify.authenticate, fastify.idempotency.middleware]`.
-*
-* GUARANTEE — best-effort effectively-once, NOT exactly-once. A distributed
-* lock makes concurrent same-key requests 409, the key includes a body+caller
-* fingerprint (a different body under one key is its own operation), and a
-* completed result replays. The business effect is not exactly-once, because
-* the domain write and the idempotency record are different systems:
-* - a crash after the DB write but before the record (preSerialization) lets a
-*   retry re-execute;
-* - a handler outrunning `lockTimeoutMs` can overlap its own retry — size that
-*   above the slowest protected handler.
+* Completion replay for mutations. Authentication, permission and tenant preparation must
+* precede the middleware: principal/scope identity isolates keys; fingerprints reject reuse
+* with changed input. Built-in stores fence completion against an expired/replaced lock.
 *
-* Where re-execution is unacceptable: write the record in the SAME transaction
-* as the business write (the store contract is exported), or make the handler
-* naturally idempotent (upsert, compare-and-set).
+* A crash between the business write and completion, or a handler outliving its lease, can
+* repeat effects. Use domain idempotency (`dedup: 'handler'`) with a shared transaction or
+* intrinsic uniqueness where replay protection alone is insufficient. See wiki/plugins.md.
 */
 const HEADER_IDEMPOTENCY_REPLAYED = "x-idempotency-replayed";
 const HEADER_IDEMPOTENCY_KEY = "x-idempotency-key";
-/**
-* Cap recursion depth in body fingerprinting. Real APIs almost never exceed
-* ~10 levels; the cap is generous so well-formed payloads are unaffected,
-* yet low enough to stop a `{"a":{"a":{...thousands deep...}}}` stack bomb.
-*/
-const MAX_FINGERPRINT_DEPTH = 32;
 const idempotencyPlugin = async (fastify, opts = {}) => {
-	const { enabled = false, headerName = "idempotency-key", ttlMs = 864e5, lockTimeoutMs = 3e4, methods = [
+	const { enabled = false, headerName = "idempotency-key", methods = [
 		"POST",
 		"PUT",
 		"PATCH"
 	], include, exclude, repository, store: explicitStore, retryAfterSeconds = 1, namespace, selfCheck = true } = opts;
+	const { ttlMs, lockTimeoutMs } = resolveIdempotencyTiming(opts.ttlMs, opts.lockTimeoutMs);
 	const store = repository ? repositoryAsIdempotencyStore(repository, ttlMs) : explicitStore ?? new MemoryIdempotencyStore({ ttlMs });
 	/**
 	* Who owns the store's lifecycle — arc closes ONLY what arc built.
@@ -319,6 +413,10 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 	* (host-owned) is never touched.
 	*/
 	const ownsStore = !explicitStore;
+	if (enabled && (typeof store.setIfLocked !== "function" || store.supportsFencedCompletion === false)) {
+		if (!opts.allowUnfencedCompletion) throw new Error("[arc idempotency] Store must implement atomic setIfLocked completion fencing. Upgrade the store or explicitly allowUnfencedCompletion during migration.");
+		fastify.log.warn("Idempotency completion is unfenced: an expired request can overwrite another owner's response. Upgrade the custom store's setIfLocked implementation.");
+	}
 	if (enabled && selfCheck) {
 		const probeSuffix = createHash("sha256").update(`${process.pid}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 12);
 		const probeKeyA = `__arc_idempotency_selfcheck__:${probeSuffix}:a`;
@@ -337,6 +435,10 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		}
 	}
 	if (!enabled) {
+		fastify.addHook("onRoute", (route) => {
+			if (!declaresIdempotencyFence(route.config)) return;
+			throw new Error(`[arc] ${String(route.method)} ${route.url} declares config.idempotency.required, but the idempotency plugin is disabled — its key would be accepted and never deduplicated. Enable idempotencyPlugin({ enabled: true }) or drop the declaration.`);
+		});
 		fastify.decorate("idempotency", {
 			invalidate: async () => {},
 			has: async () => false,
@@ -346,6 +448,7 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		fastify.decorateRequest("idempotencyKey", void 0);
 		fastify.decorateRequest("idempotencyReplayed", false);
 		fastify.decorateRequest("_idempotencyFullKey", void 0);
+		fastify.decorateRequest("_idempotencyFingerprint", void 0);
 		fastify.log?.debug?.("Idempotency plugin disabled");
 		return;
 	}
@@ -353,10 +456,12 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 	fastify.decorateRequest("idempotencyKey", void 0);
 	fastify.decorateRequest("idempotencyReplayed", false);
 	fastify.decorateRequest("_idempotencyFullKey", void 0);
+	fastify.decorateRequest("_idempotencyFingerprint", void 0);
 	/**
 	* Check if this request should use idempotency
 	*/
 	function shouldApplyIdempotency(request) {
+		if (requestRequiresIdempotencyKey(request)) return true;
 		if (!methodSet.has(request.method)) return false;
 		const url = request.url;
 		if (exclude?.some((pattern) => pattern.test(url))) return false;
@@ -364,76 +469,77 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		return true;
 	}
 	/**
-	* Normalize body for consistent hashing (sort keys recursively).
+	* The OPERATION this key names — namespace, method, URL and caller. The body is NOT part of
+	* it: the same key with a different body is the same operation asked twice, which is refused
+	* (see `bodyFingerprint`), never executed again under a fresh storage key.
 	*
-	* Recursion is bounded by `MAX_FINGERPRINT_DEPTH` to defeat a deep-nesting
-	* DoS: an attacker who sends a 1 MB JSON body of nested `{"a":{"a":...}}`
-	* would otherwise blow the call stack inside this hot path. The cap
-	* exceeds any sensible API shape (real bodies are <10 levels deep) while
-	* still being well under V8's default stack budget. At the limit we
-	* substitute a sentinel string so the hash still differs from siblings
-	* but recursion stops — the request is fingerprinted as if everything
-	* beyond the cap were `"<truncated>"`.
+	* Must run AFTER auth has populated `request.user`, or every caller shares `anon`.
 	*/
-	function normalizeBody(obj, depth = 0) {
-		if (obj === null || typeof obj !== "object") return obj;
-		if (depth >= MAX_FINGERPRINT_DEPTH) try {
-			return `<deep:${createHash("sha256").update(JSON.stringify(obj)).digest("hex").slice(0, 16)}>`;
-		} catch {
-			return "<truncated>";
-		}
-		if (Array.isArray(obj)) return obj.map((item) => normalizeBody(item, depth + 1));
-		const sorted = {};
-		const keys = Object.keys(obj).sort();
-		for (const key of keys) sorted[key] = normalizeBody(obj[key], depth + 1);
-		return sorted;
+	function operationIdentity$1(request) {
+		const user = request.user;
+		return operationIdentity(`${request.method}:${request.url}`, request.scope, user?.id ?? user?._id, namespace);
 	}
 	/**
-	* Generate a fingerprint for the request (for key generation).
-	* Includes caller identity so the same idempotency key from different
-	* users doesn't replay one user's response to another.
-	*
-	* IMPORTANT: This must be called AFTER auth has populated request.user,
-	* otherwise userId falls back to 'anon' and cross-user replay is possible.
+	* `fingerprintRequest` from `@classytic/repo-core/idempotency` — the ONE body fingerprint
+	* every layer uses. A body too deep to fingerprint is refused, not truncated.
 	*/
-	function getRequestFingerprint(request) {
-		let bodyHash = "nobody";
-		if (request.body && typeof request.body === "object") {
-			const normalized = normalizeBody(request.body);
-			const bodyString = JSON.stringify(normalized);
-			bodyHash = createHash("sha256").update(bodyString).digest("hex").substring(0, 16);
-			if (request.log?.debug) request.log.debug({ bodyHash }, "Generated body hash");
+	function bodyFingerprint(request) {
+		try {
+			return fingerprintRequest(request.body ?? null);
+		} catch (err) {
+			if (err instanceof IdempotencyError && err.code === "UNFINGERPRINTABLE") throw createDomainError(ARC_ERROR_CODES.IDEMPOTENCY_BODY_UNFINGERPRINTABLE, err.message, 400);
+			throw err;
 		}
-		const user = request.user;
-		const userId = user?.id ?? user?._id ?? "anon";
-		return `${namespace ? `n=${namespace}:` : ""}${request.method}:${request.url}:${bodyHash}:u=${userId}`;
+	}
+	function replay(request, reply, cached, fingerprint) {
+		if (cached.requestFingerprint && cached.requestFingerprint !== fingerprint) throw createDomainError(ARC_ERROR_CODES.IDEMPOTENCY_KEY_REUSED, `Idempotency key '${request.idempotencyKey}' was already used for a different request body. Use a new key for a new request.`, 422);
+		request.idempotencyReplayed = true;
+		reply.header(HEADER_IDEMPOTENCY_REPLAYED, "true");
+		reply.header(HEADER_IDEMPOTENCY_KEY, request.idempotencyKey);
+		for (const [key, value] of Object.entries(cached.headers)) {
+			const name = key.toLowerCase();
+			const liveBudget = name.startsWith("x-ratelimit-") || name.startsWith("ratelimit-") || name === "retry-after";
+			if (!name.startsWith("x-idempotency") && !(liveBudget && reply.hasHeader(name))) reply.header(key, value);
+		}
+		reply.code(cached.statusCode).send(cached.bodyEncoding === "base64" && typeof cached.body === "string" ? Buffer.from(cached.body, "base64") : cached.body);
 	}
 	const idempotencyMiddleware = async (request, reply) => {
-		if (!shouldApplyIdempotency(request)) return;
 		const idempotencyKey = requireSingleHeaderValue(request.headers, headerName)?.trim();
+		if (!idempotencyKey && requestRequiresIdempotencyKey(request)) throw createDomainError(ARC_ERROR_CODES.IDEMPOTENCY_KEY_REQUIRED, `This operation requires an '${headerName}' header, stable across retries of the same request.`, 400);
+		if (requestDedupedByHandler(request)) {
+			if (idempotencyKey) request.idempotencyKey = idempotencyKey;
+			return;
+		}
+		if (!shouldApplyIdempotency(request)) return;
 		if (!idempotencyKey) return;
 		request.idempotencyKey = idempotencyKey;
-		const fullKey = `${idempotencyKey}:${getRequestFingerprint(request)}`;
-		const cached = await store.get(fullKey);
-		if (cached) {
-			request.idempotencyReplayed = true;
-			reply.header(HEADER_IDEMPOTENCY_REPLAYED, "true");
-			reply.header(HEADER_IDEMPOTENCY_KEY, idempotencyKey);
-			for (const [key, value] of Object.entries(cached.headers)) if (!key.startsWith("x-idempotency")) reply.header(key, value);
-			reply.code(cached.statusCode).send(cached.body);
-			return;
+		const fullKey = `${idempotencyKey}:${operationIdentity$1(request)}`;
+		const requestFingerprint = bodyFingerprint(request);
+		const acquisition = await acquireIdempotencyKey(store, fullKey, request.id, lockTimeoutMs);
+		if (acquisition.status === "completed") {
+			replay(request, reply, acquisition.result, requestFingerprint);
+			return reply;
 		}
-		if (!await store.tryLock(fullKey, request.id, lockTimeoutMs)) {
+		if (acquisition.status === "locked") {
 			reply.code(409).header("Retry-After", retryAfterSeconds.toString()).send({
-				error: "Request with this idempotency key is already in progress",
-				code: "IDEMPOTENCY_CONFLICT",
-				retryAfter: retryAfterSeconds
+				code: ARC_ERROR_CODES.IDEMPOTENCY_CONFLICT,
+				message: "Request with this idempotency key is already in progress",
+				status: 409,
+				meta: { retryAfter: retryAfterSeconds }
 			});
-			return;
+			return reply;
 		}
 		request._idempotencyFullKey = fullKey;
+		request._idempotencyFingerprint = requestFingerprint;
 		reply.header(HEADER_IDEMPOTENCY_KEY, idempotencyKey);
 	};
+	fastify.addHook("onRoute", (route) => {
+		const problem = idempotencyConfigProblem(route.config);
+		if (problem) throw new Error(`[arc] ${String(route.method)} ${route.url}: config.idempotency: ${problem}.`);
+		if (!declaresIdempotencyFence(route.config)) return;
+		if ((Array.isArray(route.preHandler) ? route.preHandler : [route.preHandler]).includes(idempotencyMiddleware)) return;
+		throw new Error(`[arc] ${String(route.method)} ${route.url} declares config.idempotency.required but its preHandler does not run fastify.idempotency.middleware, so a retry would execute twice. Add it after authentication: preHandler: [fastify.authenticate, fastify.idempotency.middleware].`);
+	});
 	fastify.decorate("idempotency", {
 		invalidate: async (key) => {
 			await store.deleteByPrefix(`${key}:`);
@@ -442,14 +548,20 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 			return !!await store.findByPrefix(`${key}:`);
 		},
 		middleware: idempotencyMiddleware,
-		store
+		store,
+		allowUnfencedCompletion: opts.allowUnfencedCompletion === true,
+		ttlMs,
+		lockTimeoutMs
 	});
-	fastify.addHook("preSerialization", async (request, reply, payload) => {
-		if (request.idempotencyReplayed) return payload;
+	const recordedResponses = /* @__PURE__ */ new WeakSet();
+	/** Completed through `setIfLocked` — the lock is already gone when the store says so. */
+	const fencedCompletions = /* @__PURE__ */ new WeakSet();
+	async function recordResponse(request, reply, payload, binary = false) {
+		if (request.idempotencyReplayed || recordedResponses.has(request)) return;
 		const fullKey = request._idempotencyFullKey;
-		if (!fullKey) return payload;
+		if (!fullKey) return;
 		const statusCode = reply.statusCode;
-		if (statusCode < 200 || statusCode >= 300) return payload;
+		if (statusCode < 200 || statusCode >= 300) return;
 		const headersToCache = {};
 		const excludeHeaders = /* @__PURE__ */ new Set([
 			"content-length",
@@ -461,21 +573,28 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		]);
 		const rawHeaders = reply.getHeaders();
 		for (const [key, value] of Object.entries(rawHeaders)) if (!excludeHeaders.has(key.toLowerCase()) && typeof value === "string") headersToCache[key] = value;
-		let body;
-		try {
-			body = typeof payload === "string" ? JSON.parse(payload) : payload;
-		} catch {
-			body = payload;
-		}
-		const result = createIdempotencyResult(statusCode, body, headersToCache, ttlMs);
-		await store.set(fullKey, result);
+		const body = binary && Buffer.isBuffer(payload) ? payload.toString("base64") : payload;
+		const completion = {
+			...createIdempotencyResult(statusCode, body, headersToCache, ttlMs, request._idempotencyFingerprint),
+			...binary ? { bodyEncoding: "base64" } : {}
+		};
+		if (store.setIfLocked && store.supportsFencedCompletion !== false) {
+			if (!await store.setIfLocked(fullKey, request.id, completion)) throw createDomainError(ARC_ERROR_CODES.IDEMPOTENCY_CONFLICT, "This request lost its idempotency lease before completion; its effect may have been applied. Retry the same key to retrieve the current owner's result.", 409);
+			fencedCompletions.add(request);
+		} else await store.set(fullKey, completion);
+		recordedResponses.add(request);
+	}
+	fastify.addHook("onSend", async (request, reply, payload) => {
+		if (!request._idempotencyFullKey || request.idempotencyReplayed || recordedResponses.has(request) || reply.statusCode < 200 || reply.statusCode >= 300) return payload;
+		if (payload !== null && payload !== void 0 && typeof payload !== "string" && !Buffer.isBuffer(payload)) throw new Error("[arc idempotency] Streaming responses require config.idempotency.dedup: 'handler' and a domain-owned completion record.");
+		await recordResponse(request, reply, payload, Buffer.isBuffer(payload));
 		return payload;
 	});
 	fastify.addHook("onResponse", async (request) => {
 		if (request.idempotencyReplayed) return;
 		const fullKey = request._idempotencyFullKey;
 		if (!fullKey) return;
-		await store.unlock(fullKey, request.id);
+		await releaseIdempotencyLock(store, fullKey, request.id, fencedCompletions.has(request));
 	});
 	fastify.addHook("onClose", async () => {
 		if (ownsStore) await store.close?.();
@@ -491,4 +610,4 @@ var idempotencyPlugin_default = fp(idempotencyPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { IdempotencyStoreMisconfiguredError, MemoryIdempotencyStore, createIdempotencyResult, idempotencyPlugin_default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn, repositoryAsIdempotencyStore };
+export { IdempotencyStoreMisconfiguredError, MemoryIdempotencyStore, createIdempotencyResult, idempotencyPlugin_default as idempotencyPlugin, repositoryAsIdempotencyStore };

package/dist/idempotency/redis.d.mts

@@ -1,3 +1,3 @@
 
-import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-Bzi1y3F9.mjs";
+import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-BDgv9Glw.mjs";
 export { type IoredisLike, type RedisClient, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, type UpstashRedisLike, ioredisAsIdempotencyClient, upstashAsIdempotencyClient };

package/dist/idempotency/redis.mjs

@@ -1,32 +1,56 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { t as acquireBySteps } from "../acquire-BozJ-9yt.mjs";
+import { createHash } from "node:crypto";
 //#region src/idempotency/stores/redis.ts
+/**
+* Redis Idempotency Store
+*
+* Durable idempotency store using Redis.
+* Suitable for multi-instance deployments.
+*
+* @example
+* import { createClient } from 'redis';
+* import { RedisIdempotencyStore } from '@classytic/arc/idempotency';
+*
+* const redis = createClient({ url: process.env.REDIS_URL });
+* await redis.connect();
+*
+* await fastify.register(idempotencyPlugin, {
+*   store: new RedisIdempotencyStore({ client: redis }),
+* });
+*/
 var RedisIdempotencyStore = class {
 	name = "redis";
+	supportsFencedCompletion;
+	/** The fenced completion script deletes the lock; it needs `eval`, as fencing does. */
+	completionReleasesLock;
 	client;
 	prefix;
 	lockPrefix;
 	ttlMs;
 	constructor(options) {
 		this.client = options.client;
+		this.supportsFencedCompletion = typeof options.client.eval === "function";
+		this.completionReleasesLock = this.supportsFencedCompletion;
 		this.prefix = options.prefix ?? "idem:";
 		this.lockPrefix = options.lockPrefix ?? "idem:lock:";
+		if (this.prefix.match(/\{([^}]+)\}/)?.[1] !== this.lockPrefix.match(/\{([^}]+)\}/)?.[1]) throw new Error("Redis idempotency prefixes must use the same Redis Cluster hash tag or neither may use one.");
 		this.ttlMs = options.ttlMs ?? 864e5;
 	}
 	resultKey(key) {
-		return `${this.prefix}${key}`;
+		return `${this.prefix}${key}:{${createHash("sha256").update(key).digest("hex")}}`;
 	}
 	lockKey(key) {
-		return `${this.lockPrefix}${key}`;
+		return `${this.lockPrefix}${key}:{${createHash("sha256").update(key).digest("hex")}}`;
 	}
 	async get(key) {
-		const data = await this.client.get(this.resultKey(key));
+		return this.parseResult(await this.client.get(this.resultKey(key)));
+	}
+	parseResult(data) {
 		if (!data) return void 0;
 		try {
 			const result = JSON.parse(data);
-			if (new Date(result.expiresAt) < /* @__PURE__ */ new Date()) {
-				await this.delete(key);
-				return;
-			}
+			if (new Date(result.expiresAt) < /* @__PURE__ */ new Date()) return;
 			return {
 				...result,
 				createdAt: new Date(result.createdAt),
@@ -51,6 +75,42 @@ var RedisIdempotencyStore = class {
 			NX: true
 		}) === "OK";
 	}
+	async acquire(key, requestId, lockTtlMs) {
+		const client = this.client;
+		if (typeof client.eval !== "function") return acquireBySteps(this, key, requestId, lockTtlMs);
+		const reply = await client.eval(`
+      local done = redis.call("get", KEYS[2])
+      if done then return {1, done} end
+      if redis.call("set", KEYS[1], ARGV[1], "NX", "PX", ARGV[2]) then return {2} end
+      return {0}
+    `, 2, this.lockKey(key), this.resultKey(key), requestId, Math.max(1, Math.ceil(lockTtlMs)));
+		const tag = Number(reply?.[0]);
+		if (tag === 2) return { status: "acquired" };
+		if (tag === 1) {
+			const result = this.parseResult(reply?.[1] ?? null);
+			if (result) return {
+				status: "completed",
+				result
+			};
+			return await this.tryLock(key, requestId, lockTtlMs) ? { status: "acquired" } : { status: "locked" };
+		}
+		return { status: "locked" };
+	}
+	async setIfLocked(key, requestId, result) {
+		if (typeof this.client.eval !== "function") throw new Error("Redis idempotency fenced completion requires eval; proxy eval through your Redis client adapter.");
+		const ttlMs = new Date(result.expiresAt).getTime() - Date.now();
+		if (ttlMs <= 0) return false;
+		const saved = await this.client.eval(`
+      if redis.call("get", KEYS[1]) ~= ARGV[1] then return 0 end
+      redis.call("set", KEYS[2], ARGV[2], "PX", ARGV[3])
+      redis.call("del", KEYS[1])
+      return 1
+    `, 2, this.lockKey(key), this.resultKey(key), requestId, JSON.stringify({
+			key,
+			...result
+		}), ttlMs);
+		return Number(saved) === 1;
+	}
 	async unlock(key, requestId) {
 		const luaScript = `
       if redis.call("get", KEYS[1]) == ARGV[1] then
@@ -70,14 +130,19 @@ var RedisIdempotencyStore = class {
 		await this.client.del([this.resultKey(key), this.lockKey(key)]);
 	}
 	async deleteByPrefix(prefix) {
-		const resultKeys = await this.scanByPrefix(this.resultKey(prefix));
-		const lockKeys = await this.scanByPrefix(this.lockKey(prefix));
+		const resultKeys = await this.scanByPrefix(`${this.prefix}${prefix}`);
+		const lockKeys = await this.scanByPrefix(`${this.lockPrefix}${prefix}`);
 		const allKeys = [...resultKeys, ...lockKeys];
 		if (allKeys.length === 0) return 0;
-		return this.client.del(allKeys);
+		let removed = 0;
+		for (let offset = 0; offset < allKeys.length; offset += 100) {
+			const counts = await Promise.all(allKeys.slice(offset, offset + 100).map((key) => this.client.del(key)));
+			removed += counts.reduce((sum, count) => sum + count, 0);
+		}
+		return removed;
 	}
 	async findByPrefix(prefix) {
-		const keys = await this.scanByPrefix(this.resultKey(prefix));
+		const keys = await this.scanByPrefix(`${this.prefix}${prefix}`);
 		if (keys.length === 0) return void 0;
 		const BATCH_SIZE = 10;
 		const now = /* @__PURE__ */ new Date();