Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
+200
@@ -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;
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user