Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,259 @@
import { describe, expect, it } from "vitest";
import { MemoryAdapter, createSharedStore } from "@toolctrl/shared-store";
import { createSharedStoreIdempotencyStorageClient } from "./shared-store-client.js";
import { createIdempotencyStore } from "./store.js";
function makeClient(now?: () => number) {
const store = createSharedStore({ namespace: "api", adapter: new MemoryAdapter() });
return { client: createSharedStoreIdempotencyStorageClient({ store, now }), store };
}
const SCOPE = "api:tenant:t1";
/**
* `IdempotencyStorageClient.findUnique` is typed via an intersection of
* the base Prisma contract and an extended delegate; TS resolves the
* call to the base overload, which omits `createdAt`. The SharedStore
* client always populates `createdAt`, so narrow the result here to read
* it in the assertions below.
*/
type WithCreatedAt = { createdAt?: Date | null; expiresAt?: Date | null };
describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract", () => {
it("round-trips a created entry through findUnique with Date fields", async () => {
const { client } = makeClient(() => 1_000);
await client.idempotencyKey.create({
data: {
scope: SCOPE,
key: "k1",
requestHash: "hash-1",
responseStatus: 201,
responseBody: { ok: true },
responseHeaders: { "x-test": "1" },
expiresAt: new Date(1_000 + 60_000),
},
});
const found = await client.idempotencyKey.findUnique({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "k1" } },
});
expect(found).not.toBeNull();
expect(found?.requestHash).toBe("hash-1");
expect(found?.responseStatus).toBe(201);
expect(found?.responseBody).toEqual({ ok: true });
expect(found?.responseHeaders).toEqual({ "x-test": "1" });
const withDates = found as WithCreatedAt | null;
expect(withDates?.createdAt).toBeInstanceOf(Date);
expect(withDates?.expiresAt?.getTime()).toBe(61_000);
});
it("returns null for an unknown key", async () => {
const { client } = makeClient();
const found = await client.idempotencyKey.findUnique({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "missing" } },
});
expect(found).toBeNull();
});
it("throws a Prisma-style P2002 when the same scope+key is claimed twice", async () => {
const { client } = makeClient();
const data = {
scope: SCOPE,
key: "dup",
requestHash: "h",
responseStatus: 0,
responseBody: null,
responseHeaders: null,
expiresAt: new Date(Date.now() + 60_000),
};
await client.idempotencyKey.create({ data });
await expect(client.idempotencyKey.create({ data })).rejects.toMatchObject({ code: "P2002" });
});
it("update overwrites the response and preserves createdAt", async () => {
const { client } = makeClient(() => 5_000);
await client.idempotencyKey.create({
data: {
scope: SCOPE,
key: "k2",
requestHash: "h",
responseStatus: 0,
responseBody: null,
responseHeaders: null,
expiresAt: new Date(5_000 + 60_000),
},
});
const before = await client.idempotencyKey.findUnique({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "k2" } },
});
await client.idempotencyKey.update({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "k2" } },
data: { responseStatus: 200, responseBody: { done: true }, responseHeaders: { h: "v" } },
});
const after = await client.idempotencyKey.findUnique({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "k2" } },
});
expect(after?.responseStatus).toBe(200);
expect(after?.responseBody).toEqual({ done: true });
expect((after as WithCreatedAt | null)?.createdAt?.getTime()).toBe(
(before as WithCreatedAt | null)?.createdAt?.getTime(),
);
});
it("update throws when the reservation does not exist", async () => {
const { client } = makeClient();
await expect(
client.idempotencyKey.update({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "ghost" } },
data: { responseStatus: 200 },
}),
).rejects.toThrow(/not found/i);
});
it("deleteMany with scope+key removes exactly that entry", async () => {
const { client } = makeClient();
const base = {
scope: SCOPE,
requestHash: "h",
responseStatus: 200,
responseBody: null,
responseHeaders: null,
expiresAt: new Date(Date.now() + 60_000),
};
await client.idempotencyKey.create({ data: { ...base, key: "a" } });
await client.idempotencyKey.create({ data: { ...base, key: "b" } });
await client.idempotencyKey.deleteMany?.({ where: { scope: SCOPE, key: "a" } });
expect(
await client.idempotencyKey.findUnique({ where: { idempotency_key_scope_key: { scope: SCOPE, key: "a" } } }),
).toBeNull();
expect(
await client.idempotencyKey.findUnique({ where: { idempotency_key_scope_key: { scope: SCOPE, key: "b" } } }),
).not.toBeNull();
});
it("deleteMany with expiresAt.lte only removes entries already past their expiry", async () => {
const { client } = makeClient(() => 10_000);
await client.idempotencyKey.create({
data: {
scope: SCOPE,
key: "fresh",
requestHash: "h",
responseStatus: 200,
responseBody: null,
responseHeaders: null,
expiresAt: new Date(10_000 + 60_000),
},
});
// Cut-off earlier than the entry's expiry → entry is kept.
await client.idempotencyKey.deleteMany?.({
where: { scope: SCOPE, key: "fresh", expiresAt: { lte: new Date(20_000) } },
});
expect(
await client.idempotencyKey.findUnique({ where: { idempotency_key_scope_key: { scope: SCOPE, key: "fresh" } } }),
).not.toBeNull();
});
it("deleteMany scoped to one scope leaves other scopes intact", async () => {
const { client } = makeClient();
const base = {
requestHash: "h",
responseStatus: 200,
responseBody: null,
responseHeaders: null,
expiresAt: new Date(Date.now() + 60_000),
};
await client.idempotencyKey.create({ data: { ...base, scope: "api:system", key: "x" } });
await client.idempotencyKey.create({ data: { ...base, scope: "api:tenant:other", key: "y" } });
await client.idempotencyKey.deleteMany?.({ where: { scope: "api:system" } });
expect(await client.idempotencyKey.count?.({ where: { scope: "api:system" } })).toBe(0);
expect(await client.idempotencyKey.count?.({ where: { scope: "api:tenant:other" } })).toBe(1);
});
it("count tallies only entries in the requested scope", async () => {
const { client } = makeClient();
const base = {
requestHash: "h",
responseStatus: 200,
responseBody: null,
responseHeaders: null,
expiresAt: new Date(Date.now() + 60_000),
};
await client.idempotencyKey.create({ data: { ...base, scope: SCOPE, key: "1" } });
await client.idempotencyKey.create({ data: { ...base, scope: SCOPE, key: "2" } });
await client.idempotencyKey.create({ data: { ...base, scope: "api:system", key: "3" } });
expect(await client.idempotencyKey.count?.({ where: { scope: SCOPE } })).toBe(2);
});
});
describe("createSharedStoreIdempotencyStorageClient — driven through createIdempotencyStore", () => {
it("stores then replays a successful operation", async () => {
const { client } = makeClient();
const idempotency = createIdempotencyStore({ client, scope: SCOPE });
const response = { status: 200, headers: {}, body: { value: 1 } };
const first = await idempotency.run("key-A", "fp-A", async () => response);
const second = await idempotency.run("key-A", "fp-A", async () => ({
status: 500,
headers: {},
body: { value: 999 },
}));
expect(first.type).toBe("stored");
expect(second.type).toBe("replay");
if (second.type === "replay") {
expect(second.response.body).toEqual({ value: 1 });
}
});
it("reports a conflict when the same key arrives with a different fingerprint", async () => {
const { client } = makeClient();
const idempotency = createIdempotencyStore({ client, scope: SCOPE });
await idempotency.run("key-B", "fp-1", async () => ({ status: 200, headers: {}, body: null }));
const conflict = await idempotency.run("key-B", "fp-2", async () => ({ status: 200, headers: {}, body: null }));
expect(conflict.type).toBe("conflict");
});
it("fans an invalidation out across two replicas sharing one adapter", async () => {
// Two SharedStore facades over one MemoryAdapter == two API replicas
// pointed at the same Redis. A claim on replica A must be visible to B.
const adapter = new MemoryAdapter();
const replicaA = createSharedStoreIdempotencyStorageClient({
store: createSharedStore({ namespace: "api", adapter }),
});
const replicaB = createSharedStoreIdempotencyStorageClient({
store: createSharedStore({ namespace: "api", adapter }),
});
const storeA = createIdempotencyStore({ client: replicaA, scope: SCOPE });
const storeB = createIdempotencyStore({ client: replicaB, scope: SCOPE });
const stored = await storeA.run("shared-key", "fp", async () => ({
status: 201,
headers: {},
body: { replica: "A" },
}));
const replayed = await storeB.run("shared-key", "fp", async () => ({
status: 500,
headers: {},
body: { replica: "B" },
}));
expect(stored.type).toBe("stored");
expect(replayed.type).toBe("replay");
if (replayed.type === "replay") {
expect(replayed.response.body).toEqual({ replica: "A" });
}
});
});
@@ -0,0 +1,200 @@
/**
* 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 "@toolctrl/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;
},
},
};
}
@@ -0,0 +1,238 @@
import { describe, expect, test, vi } from "vitest";
import { createApiIdempotencyScope, createIdempotencyStore, createMemoryIdempotencyStorageClient, createRequestFingerprint, normalizeIdempotencyKey, type StoredIdempotencyResponse } from "./store.js";
const response: StoredIdempotencyResponse = {
status: 201,
headers: { "content-type": "application/json", "x-request-id": "req_123" },
body: { ok: true, nested: { count: 1 } },
};
function fingerprint(parsedBody: unknown = { name: "Ada" }) {
return createRequestFingerprint({
method: "post",
route: "/v1/:tenant/entities/:entityId/rows/:rowId",
tenantId: "tenant_1",
entityId: "entity_1",
rowId: "row_1",
parsedBody: parsedBody as never,
});
}
describe("idempotency store", () => {
test("stores the first successful response for a valid key", async () => {
const store = createIdempotencyStore({ now: () => 1000 });
await expect(store.recordSuccess(" key_1 ", fingerprint(), response)).resolves.toEqual({
type: "stored",
response,
createdAt: 1000,
});
await expect(store.size()).resolves.toBe(1);
});
test("replays the stored response for the same key and fingerprint", async () => {
const store = createIdempotencyStore({ now: () => 1000 });
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
await expect(store.recordSuccess("key_1", requestFingerprint, { status: 500, headers: {}, body: { ok: false } })).resolves.toEqual({
type: "replay",
response,
createdAt: 1000,
});
});
test("rejects a repeated key with a changed body fingerprint", async () => {
const store = createIdempotencyStore({ now: () => 1000 });
const originalFingerprint = fingerprint({ name: "Ada" });
const changedFingerprint = fingerprint({ name: "Grace" });
await store.recordSuccess("key_1", originalFingerprint, response);
await expect(store.recordSuccess("key_1", changedFingerprint, response)).resolves.toEqual({
type: "conflict",
existingFingerprint: originalFingerprint,
receivedFingerprint: changedFingerprint,
createdAt: 1000,
});
});
test("isolates records by idempotency key", async () => {
const store = createIdempotencyStore();
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
await expect(store.peek("key_2", requestFingerprint)).resolves.toEqual({ type: "miss" });
});
test("isolates API idempotency keys by tenant scope", async () => {
const client = createMemoryIdempotencyStorageClient();
const tenantOneStore = createIdempotencyStore({ client, scope: createApiIdempotencyScope({ tenantId: "tenant_1" }) });
const tenantTwoStore = createIdempotencyStore({ client, scope: createApiIdempotencyScope({ tenantId: "tenant_2" }) });
const requestFingerprint = createRequestFingerprint({
method: "POST",
route: "/v1/entities/:entity/rows",
tenantId: "same-shape",
parsedBody: { name: "Ada" },
});
const first = await tenantOneStore.run("shared-key", requestFingerprint, async () => ({
...response,
body: { tenantId: "tenant_1" },
}));
const second = await tenantTwoStore.run("shared-key", requestFingerprint, async () => ({
...response,
body: { tenantId: "tenant_2" },
}));
expect(first.type).toBe("stored");
expect(second.type).toBe("stored");
expect(first.type === "stored" ? first.response.body : null).toEqual({ tenantId: "tenant_1" });
expect(second.type === "stored" ? second.response.body : null).toEqual({ tenantId: "tenant_2" });
});
test("bypasses malformed or missing idempotency keys", async () => {
const store = createIdempotencyStore();
const requestFingerprint = fingerprint();
expect(normalizeIdempotencyKey(undefined)).toBeNull();
expect(normalizeIdempotencyKey(" ")).toBeNull();
expect(normalizeIdempotencyKey("bad\nkey")).toBeNull();
await expect(store.recordSuccess(undefined, requestFingerprint, response)).resolves.toEqual({ type: "bypass" });
await expect(store.recordSuccess(" ", requestFingerprint, response)).resolves.toEqual({ type: "bypass" });
await expect(store.size()).resolves.toBe(0);
});
test("prunes old records by max age", async () => {
let now = 1000;
const store = createIdempotencyStore({ maxAgeMs: 10, now: () => now });
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
now = 1011;
await expect(store.peek("key_1", requestFingerprint)).resolves.toEqual({ type: "miss" });
await expect(store.size()).resolves.toBe(0);
});
test("caps growth by evicting the oldest entries when max entries is exceeded", async () => {
const store = createIdempotencyStore({ maxEntries: 1 });
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
await store.recordSuccess("key_2", requestFingerprint, response);
await expect(store.peek("key_1", requestFingerprint)).resolves.toEqual({ type: "miss" });
await expect(store.peek("key_2", requestFingerprint)).resolves.toMatchObject({ type: "replay" });
});
test("does not fingerprint credential headers or raw request bodies", () => {
const baseInput = {
method: "post",
route: "/v1/:tenant/entities/:entityId/rows",
tenantId: "tenant_1",
entityId: "entity_1",
parsedBody: { safe: true },
};
const withoutSecrets = createRequestFingerprint(baseInput);
const withSecrets = createRequestFingerprint({
...baseInput,
authorization: "Bearer secret-token",
"x-api-key": "secret-api-key",
rawBody: "plaintext secret body",
} as never);
expect(withSecrets).toBe(withoutSecrets);
expect(withSecrets).not.toContain("secret");
});
test("returns cloned response bodies instead of sharing mutable references", async () => {
const store = createIdempotencyStore();
const requestFingerprint = fingerprint();
const originalResponse: StoredIdempotencyResponse = {
status: 200,
headers: {},
body: { nested: { count: 1 } },
};
const stored = await store.recordSuccess("key_1", requestFingerprint, originalResponse);
originalResponse.body = { nested: { count: 99 } };
if (stored.type === "stored" && typeof stored.response.body === "object" && stored.response.body !== null && !Array.isArray(stored.response.body)) {
stored.response.body.nested = { count: 42 };
}
await expect(store.peek("key_1", requestFingerprint)).resolves.toMatchObject({
type: "replay",
response: { body: { nested: { count: 1 } } },
});
});
test("clear resets all stored idempotency records", async () => {
const store = createIdempotencyStore();
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
await store.clear();
await expect(store.size()).resolves.toBe(0);
await expect(store.peek("key_1", requestFingerprint)).resolves.toEqual({ type: "miss" });
});
test("runs operations through a structural persisted idempotency client", async () => {
const client = createMemoryIdempotencyStorageClient({ now: () => 1000 });
const findUnique = vi.spyOn(client.idempotencyKey, "findUnique");
const create = vi.spyOn(client.idempotencyKey, "create");
const update = vi.spyOn(client.idempotencyKey, "update");
const store = createIdempotencyStore({ client, now: () => 1000 });
const operation = vi.fn(async () => response);
const requestFingerprint = fingerprint();
await expect(store.run("key_1", requestFingerprint, operation)).resolves.toMatchObject({ type: "stored", response });
await expect(store.run("key_1", requestFingerprint, operation)).resolves.toMatchObject({ type: "replay", response });
expect(operation).toHaveBeenCalledTimes(1);
expect(findUnique).toHaveBeenCalled();
expect(create).toHaveBeenCalledWith({
data: expect.objectContaining({
scope: "api",
key: "key_1",
responseStatus: 0,
responseBody: null,
responseHeaders: null,
}),
});
expect(update).toHaveBeenCalledWith({
where: { idempotency_key_scope_key: { scope: "api", key: "key_1" } },
data: expect.objectContaining({
responseStatus: response.status,
responseBody: response.body,
responseHeaders: response.headers,
}),
});
});
test("reports an in-flight database reservation without running the operation", async () => {
const client = createMemoryIdempotencyStorageClient({ now: () => 1000 });
const store = createIdempotencyStore({ client, now: () => 1000 });
const requestFingerprint = fingerprint();
const requestHash = JSON.stringify(requestFingerprint);
await client.idempotencyKey.create({
data: {
scope: "api",
key: "key_reserved",
requestHash,
responseStatus: 0,
responseBody: null,
responseHeaders: null,
expiresAt: new Date(2000),
},
});
const operation = vi.fn(async () => response);
await expect(store.run("key_reserved", requestFingerprint, operation)).resolves.toMatchObject({ type: "in_progress" });
expect(operation).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,416 @@
import { createHash } from "node:crypto";
import { CatalogError, foundationErrors, withIdempotency, type IdempotencyClient } from "@toolctrl/foundation";
export type IdempotencyKey = string;
export type RequestFingerprint = string;
export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
export type StoredResponseStatus = number;
export type StoredResponseHeaders = Record<string, string>;
export type StoredResponseBody = JsonValue;
export type StoredIdempotencyResponse = {
status: StoredResponseStatus;
headers: StoredResponseHeaders;
body: StoredResponseBody;
};
export type IdempotencyFingerprintInput = {
method: string;
route: string;
tenantId?: string | null;
entityId?: string | null;
rowId?: string | null;
relationshipId?: string | null;
parsedBody?: JsonValue;
};
export type IdempotencyStoreOptions = {
client?: IdempotencyStorageClient;
maxAgeMs?: number;
maxEntries?: number;
now?: () => number;
scope?: string;
};
type StoredEntry = {
requestHash: string;
responseStatus: number;
responseBody: JsonValue | null;
responseHeaders: Record<string, string> | null;
createdAt?: Date | null;
expiresAt?: Date | null;
};
type IdempotencyKeyDelegate = IdempotencyClient["idempotencyKey"] & {
findUnique(args: { where: { idempotency_key_scope_key: { scope: string; key: string } } }): Promise<StoredEntry | null>;
deleteMany?(args?: { where?: { scope?: string; key?: string; expiresAt?: { lte?: Date } } }): Promise<unknown>;
count?(args?: { where?: { scope?: string } }): Promise<number>;
};
export type IdempotencyStorageClient = Omit<IdempotencyClient, "idempotencyKey"> & {
idempotencyKey: IdempotencyKeyDelegate;
};
export type IdempotencyStoreResult =
| { type: "stored"; response: StoredIdempotencyResponse; createdAt: number }
| { type: "replay"; response: StoredIdempotencyResponse; createdAt: number }
| { type: "conflict"; existingFingerprint: RequestFingerprint; receivedFingerprint: RequestFingerprint; createdAt: number }
| { type: "in_progress"; createdAt: number };
export type IdempotencyStore = {
recordSuccess: (
key: IdempotencyKey | null | undefined,
fingerprint: RequestFingerprint,
response: StoredIdempotencyResponse,
) => Promise<IdempotencyStoreResult | { type: "bypass" }>;
run: (
key: IdempotencyKey | null | undefined,
fingerprint: RequestFingerprint,
operation: () => Promise<StoredIdempotencyResponse>,
) => Promise<IdempotencyStoreResult | { type: "bypass"; response: StoredIdempotencyResponse }>;
peek: (
key: IdempotencyKey | null | undefined,
fingerprint: RequestFingerprint,
) => Promise<Exclude<IdempotencyStoreResult, { type: "stored" }> | { type: "miss" } | { type: "bypass" }>;
clear: () => Promise<void>;
size: () => Promise<number>;
prune: () => Promise<void>;
};
const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
const DEFAULT_MAX_ENTRIES = 1000;
const DEFAULT_SCOPE = "api";
export function normalizeIdempotencyKey(value: string | null | undefined): IdempotencyKey | null {
const trimmed = value?.trim();
if (!trimmed || trimmed.length > 255 || /[\u0000-\u001f\u007f]/u.test(trimmed)) {
return null;
}
return trimmed;
}
export function createRequestFingerprint(input: IdempotencyFingerprintInput): RequestFingerprint {
const safeInput = {
method: input.method.toUpperCase(),
route: input.route,
tenantId: input.tenantId ?? null,
entityId: input.entityId ?? null,
rowId: input.rowId ?? null,
relationshipId: input.relationshipId ?? null,
parsedBody: input.parsedBody ?? null,
};
return createHash("sha256").update(stableStringify(safeInput)).digest("hex");
}
export function createApiIdempotencyScope(input: Pick<IdempotencyFingerprintInput, "tenantId">): string {
return input.tenantId ? `${DEFAULT_SCOPE}:tenant:${input.tenantId}` : `${DEFAULT_SCOPE}:system`;
}
export function createIdempotencyStore(options: IdempotencyStoreOptions = {}): IdempotencyStore {
const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
const now = options.now ?? Date.now;
const scope = options.scope ?? DEFAULT_SCOPE;
const client = options.client ?? createMemoryIdempotencyStorageClient({ maxEntries: options.maxEntries ?? DEFAULT_MAX_ENTRIES, now });
const expiresAt = () => new Date(now() + maxAgeMs);
const findEntry = async (key: IdempotencyKey) => findStoredEntry(client, scope, key, now);
return {
async recordSuccess(key, fingerprint, response) {
const result = await this.run(key, fingerprint, async () => response);
if (result.type === "bypass") {
return { type: "bypass" };
}
return result;
},
async run(key, fingerprint, operation) {
const normalizedKey = normalizeIdempotencyKey(key);
if (normalizedKey === null) {
return { type: "bypass", response: cloneResponse(await operation()) };
}
try {
const createdAt = now();
const response = await withIdempotency(
{ scope, key: normalizedKey, fingerprint, expiresAt: expiresAt() },
createExpiringIdempotencyClient(client, now),
async () => {
const operationResponse = await operation();
return {
status: operationResponse.status,
body: cloneJson(operationResponse.body),
headers: { ...operationResponse.headers },
};
},
);
const storedResponse = normalizeStoredResponse({
status: response.status,
body: response.body ?? null,
headers: response.headers ?? {},
});
if (response.replayed) {
const existing = await findEntry(normalizedKey);
return { type: "replay", response: storedResponse, createdAt: entryCreatedAt(existing, createdAt) };
}
return { type: "stored", response: storedResponse, createdAt };
} catch (error) {
if (isIdempotencyConflictError(error)) {
const existing = await findEntry(normalizedKey);
return {
type: "conflict",
existingFingerprint: parseStoredFingerprint(existing?.requestHash) ?? "",
receivedFingerprint: fingerprint,
createdAt: entryCreatedAt(existing, now()),
};
}
if (isIdempotencyInProgressError(error)) {
const existing = await findEntry(normalizedKey);
return { type: "in_progress", createdAt: entryCreatedAt(existing, now()) };
}
throw error;
}
},
async peek(key, fingerprint) {
const normalizedKey = normalizeIdempotencyKey(key);
if (normalizedKey === null) {
return { type: "bypass" };
}
const existing = await findEntry(normalizedKey);
if (!existing) {
return { type: "miss" };
}
const requestHash = stableStringify(fingerprint);
if (existing.requestHash !== requestHash) {
return {
type: "conflict",
existingFingerprint: parseStoredFingerprint(existing.requestHash) ?? "",
receivedFingerprint: fingerprint,
createdAt: entryCreatedAt(existing, now()),
};
}
if (existing.responseStatus <= 0) {
return { type: "in_progress", createdAt: entryCreatedAt(existing, now()) };
}
return { type: "replay", response: normalizeStoredResponse(existing), createdAt: entryCreatedAt(existing, now()) };
},
async clear() {
await client.idempotencyKey.deleteMany?.({ where: { scope } });
},
async size() {
await this.prune();
return client.idempotencyKey.count?.({ where: { scope } }) ?? 0;
},
async prune() {
await client.idempotencyKey.deleteMany?.({ where: { scope, expiresAt: { lte: new Date(now()) } } });
},
};
}
export function createMemoryIdempotencyStorageClient(options: { maxEntries?: number; now?: () => number } = {}): IdempotencyStorageClient {
const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
const now = options.now ?? Date.now;
const rows = new Map<string, StoredEntry & { scope: string; key: string }>();
const rowKey = (scope: string, key: string) => `${scope}:${key}`;
const pruneOverflow = () => {
while (rows.size > maxEntries) {
const oldestKey = rows.keys().next().value as string | undefined;
if (!oldestKey) {
break;
}
rows.delete(oldestKey);
}
};
return {
idempotencyKey: {
async findUnique({ where }) {
return rows.get(rowKey(where.idempotency_key_scope_key.scope, where.idempotency_key_scope_key.key)) ?? null;
},
async create({ data }) {
const key = rowKey(data.scope, data.key);
if (rows.has(key)) {
throw Object.assign(new Error("Unique constraint failed on idempotency key"), { code: "P2002" });
}
rows.set(rowKey(data.scope, data.key), {
scope: data.scope,
key: data.key,
requestHash: data.requestHash,
responseStatus: data.responseStatus,
responseBody: data.responseBody ?? null,
responseHeaders: data.responseHeaders ?? null,
createdAt: new Date(now()),
expiresAt: data.expiresAt ?? null,
});
pruneOverflow();
},
async update({ where, data }) {
const key = rowKey(where.idempotency_key_scope_key.scope, where.idempotency_key_scope_key.key);
const existing = rows.get(key);
if (!existing) {
throw new Error("Idempotency key reservation not found.");
}
rows.set(key, {
...existing,
responseStatus: data.responseStatus,
responseBody: data.responseBody ?? null,
responseHeaders: data.responseHeaders ?? null,
expiresAt: data.expiresAt ?? existing.expiresAt ?? null,
});
},
async deleteMany(args) {
const where = args?.where;
for (const [key, row] of rows) {
if (where?.scope && row.scope !== where.scope) {
continue;
}
if (where?.key && row.key !== where.key) {
continue;
}
if (where?.expiresAt?.lte && (!row.expiresAt || row.expiresAt > where.expiresAt.lte)) {
continue;
}
rows.delete(key);
}
},
async count(args) {
const scope = args?.where?.scope;
return scope ? [...rows.values()].filter((row) => row.scope === scope).length : rows.size;
},
},
};
}
function createExpiringIdempotencyClient(client: IdempotencyStorageClient, now: () => number): IdempotencyClient {
return {
idempotencyKey: {
async findUnique(args) {
const existing = await client.idempotencyKey.findUnique(args);
if (existing?.expiresAt && existing.expiresAt.getTime() <= now()) {
await client.idempotencyKey.deleteMany?.({
where: {
scope: args.where.idempotency_key_scope_key.scope,
key: args.where.idempotency_key_scope_key.key,
expiresAt: { lte: new Date(now()) },
},
});
return null;
}
return existing;
},
create(args) {
return client.idempotencyKey.create(args);
},
update(args) {
return client.idempotencyKey.update(args);
},
async deleteMany(args) {
await client.idempotencyKey.deleteMany?.(args);
},
},
};
}
async function findStoredEntry(client: IdempotencyStorageClient, scope: string, key: IdempotencyKey, now: () => number) {
const existing = await client.idempotencyKey.findUnique({ where: { idempotency_key_scope_key: { scope, key } } });
if (existing?.expiresAt && existing.expiresAt.getTime() <= now()) {
await client.idempotencyKey.deleteMany?.({ where: { scope, key, expiresAt: { lte: new Date(now()) } } });
return null;
}
return existing;
}
function isIdempotencyConflictError(error: unknown) {
return error instanceof CatalogError && error.code === foundationErrors.idempotencyConflict.code;
}
function isIdempotencyInProgressError(error: unknown) {
return error instanceof CatalogError && error.code === foundationErrors.idempotencyInProgress.code;
}
function entryCreatedAt(entry: StoredEntry | null | undefined, fallback: number) {
return entry?.createdAt instanceof Date ? entry.createdAt.getTime() : fallback;
}
function normalizeStoredResponse(response: {
status?: number;
headers?: Record<string, string> | null;
body?: JsonValue | null;
responseStatus?: number;
responseHeaders?: Record<string, string> | null;
responseBody?: JsonValue | null;
}): StoredIdempotencyResponse {
return {
status: response.responseStatus ?? response.status ?? 200,
headers: { ...(response.responseHeaders ?? response.headers ?? {}) },
body: cloneJson(response.responseBody ?? response.body ?? null),
};
}
function parseStoredFingerprint(requestHash: string | undefined) {
if (!requestHash) {
return null;
}
try {
const parsed = JSON.parse(requestHash);
return typeof parsed === "string" ? parsed : null;
} catch {
return null;
}
}
function cloneResponse(response: StoredIdempotencyResponse): StoredIdempotencyResponse {
return {
status: response.status,
headers: { ...response.headers },
body: cloneJson(response.body),
};
}
function cloneJson<T extends JsonValue>(value: T): T {
return JSON.parse(JSON.stringify(value)) as T;
}
function stableStringify(value: JsonValue | Record<string, unknown>): string {
if (value === null || typeof value !== "object") {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map((item) => stableStringify(item)).join(",")}]`;
}
return `{${Object.keys(value)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableStringify((value as Record<string, JsonValue>)[key] ?? null)}`)
.join(",")}}`;
}