Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/api/src/idempotency/shared-store-client.ts
T
2026-07-08 16:15:37 +02:00

201 lines
7.7 KiB
TypeScript

/**
* 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<string, string> | 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<PersistedEntry | null> => {
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;
},
},
};
}