/** * SharedStore-backed implementation of the Prisma-shaped * `IdempotencyStorageClient` contract (Phase 03 #38, step 3). * * The idempotency layer (`createIdempotencyStore` + `withIdempotency`) * speaks a narrow Prisma-delegate interface: `idempotencyKey.{findUnique, * create, update, deleteMany, count}`. Production wires the real Prisma * client; tests wire `createMemoryIdempotencyStorageClient` (an * in-process Map). Neither is cross-replica-safe without Postgres. * * This module provides a third backend: the same contract on top of a * `SharedStore` (Redis in production, MemoryAdapter in dev/test). It lets * a deployment that already runs Redis get multi-replica idempotency * without a Postgres round-trip, and without the in-process Map's * single-process blind spot. * * It is opt-in — `app-dependencies.ts` selects it only when * `IDEMPOTENCY_BACKEND=shared-store`; the default stays Prisma. * * Atomicity: `create` maps to `set(..., { nx: true })`. A `false` return * (key already present) is surfaced as a Prisma-style `P2002` error so * `withIdempotency` detects the concurrent claim exactly as it does with * the real Prisma unique-constraint violation. * * Expiry: every entry is written with a Redis TTL derived from * `expiresAt`, so expired reservations self-evict. The `expiresAt` field * is also stored in the value so the contract's explicit expiry checks * (`deleteMany({ expiresAt: { lte } })`) keep working against the * MemoryAdapter, which honors TTL lazily on read. */ import type { SharedStore } from "@hivegrid/shared-store"; import type { IdempotencyStorageClient } from "./store.js"; type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }; type PersistedEntry = { scope: string; key: string; requestHash: string; responseStatus: number; responseBody: JsonValue | null; responseHeaders: Record | null; createdAt: number; expiresAt: number | null; }; const KEY_PREFIX = "idem"; /** Hex-encode so scope/key cannot contain the `:` delimiter or SharedStore-forbidden chars. */ function hex(value: string): string { return Buffer.from(value, "utf8").toString("hex"); } function suffixFor(scope: string, key: string): string { return `${KEY_PREFIX}:${hex(scope)}:${hex(key)}`; } function ttlSecondsUntil(expiresAt: number | null, now: () => number): number | undefined { if (expiresAt === null) return undefined; const seconds = Math.ceil((expiresAt - now()) / 1000); return seconds >= 1 ? seconds : 1; } export type SharedStoreIdempotencyClientOptions = { store: SharedStore; now?: () => number; }; export function createSharedStoreIdempotencyStorageClient( options: SharedStoreIdempotencyClientOptions, ): IdempotencyStorageClient { const { store } = options; const now = options.now ?? Date.now; // The factory prepends a namespace prefix to every suffix. `scan` // yields fully-prefixed keys, so derive the prefix once to strip it // back to a suffix `get`/`del` will accept. const prefix = store.key("x").slice(0, -1); const stripPrefix = (fullKey: string): string => fullKey.startsWith(prefix) ? fullKey.slice(prefix.length) : fullKey; const readEntry = async (suffix: string): Promise => { const raw = await store.get(suffix); if (raw === null) return null; try { return JSON.parse(raw) as PersistedEntry; } catch { // A corrupt value is treated as absent — the next claim re-creates it. return null; } }; async function* iterateEntries(): AsyncGenerator<{ suffix: string; entry: PersistedEntry }> { for await (const fullKey of store.scan(`${KEY_PREFIX}:*`)) { const suffix = stripPrefix(fullKey); const entry = await readEntry(suffix); if (entry) yield { suffix, entry }; } } return { idempotencyKey: { async findUnique({ where }) { const { scope, key } = where.idempotency_key_scope_key; const entry = await readEntry(suffixFor(scope, key)); if (!entry) return null; return { requestHash: entry.requestHash, responseStatus: entry.responseStatus, responseBody: entry.responseBody ?? null, responseHeaders: entry.responseHeaders ?? null, createdAt: entry.createdAt != null ? new Date(entry.createdAt) : null, expiresAt: entry.expiresAt != null ? new Date(entry.expiresAt) : null, }; }, async create({ data }) { const expiresAt = data.expiresAt ? data.expiresAt.getTime() : null; const entry: PersistedEntry = { scope: data.scope, key: data.key, requestHash: data.requestHash, responseStatus: data.responseStatus, responseBody: (data.responseBody ?? null) as JsonValue | null, responseHeaders: data.responseHeaders ?? null, createdAt: now(), expiresAt, }; const ttlSeconds = ttlSecondsUntil(expiresAt, now); const written = await store.set(suffixFor(data.scope, data.key), JSON.stringify(entry), { nx: true, ...(ttlSeconds !== undefined ? { ttlSeconds } : {}), }); if (!written) { // Mirror Prisma's unique-constraint violation so withIdempotency // recognises the concurrent claim and replays instead of erroring. throw Object.assign(new Error("Unique constraint failed on idempotency key"), { code: "P2002" }); } }, async update({ where, data }) { const { scope, key } = where.idempotency_key_scope_key; const suffix = suffixFor(scope, key); const existing = await readEntry(suffix); if (!existing) { throw new Error("Idempotency key reservation not found."); } const expiresAt = data.expiresAt ? data.expiresAt.getTime() : existing.expiresAt; const next: PersistedEntry = { ...existing, responseStatus: data.responseStatus, responseBody: (data.responseBody ?? null) as JsonValue | null, responseHeaders: data.responseHeaders ?? null, expiresAt, }; const ttlSeconds = ttlSecondsUntil(expiresAt, now); await store.set(suffix, JSON.stringify(next), ttlSeconds !== undefined ? { ttlSeconds } : undefined); }, async deleteMany(args) { const where = args?.where; // Targeted single-key delete — no scan needed. if (where?.scope && where?.key) { const suffix = suffixFor(where.scope, where.key); if (where.expiresAt?.lte) { const entry = await readEntry(suffix); const cutoff = where.expiresAt.lte.getTime(); if (entry && entry.expiresAt !== null && entry.expiresAt <= cutoff) { await store.del(suffix); } } else { await store.del(suffix); } return; } // Scope-wide (clear / prune) — enumerate. The entry set is bounded // by TTL so this stays cheap; it is never on the request hot path. const cutoff = where?.expiresAt?.lte ? where.expiresAt.lte.getTime() : null; for await (const { suffix, entry } of iterateEntries()) { if (where?.scope && entry.scope !== where.scope) continue; if (where?.key && entry.key !== where.key) continue; if (cutoff !== null && !(entry.expiresAt !== null && entry.expiresAt <= cutoff)) continue; await store.del(suffix); } }, async count(args) { const scope = args?.where?.scope; let total = 0; for await (const { entry } of iterateEntries()) { if (scope && entry.scope !== scope) continue; total += 1; } return total; }, }, }; }