@beignet/core 0.0.1 → 0.0.3

package/src/idempotency/index.ts

@@ -0,0 +1,767 @@
+/**
+ * @beignet/core/idempotency
+ *
+ * Idempotency primitives for retry-safe commands, webhooks, and jobs.
+ */
+
+/**
+ * Value or promise of that value.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Primitive value accepted inside an idempotency scope object.
+ */
+export type IdempotencyScopeValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined;
+
+/**
+ * Logical scope for idempotency keys.
+ *
+ * String scopes are used as-is. Object scopes are normalized by sorting keys and
+ * joining key/value pairs so adapters can build stable storage keys.
+ */
+export type IdempotencyScope = string | Record<string, IdempotencyScopeValue>;
+
+/**
+ * Scope mode that HTTP hooks can use when deriving an idempotency scope.
+ */
+export type IdempotencyScopeMode =
+  | "global"
+  | "actor"
+  | "tenant"
+  | "actor-tenant";
+
+/**
+ * Contract metadata for idempotency-aware routes.
+ */
+export interface IdempotencyMeta {
+  /**
+   * Whether this operation requires an idempotency key at the HTTP boundary.
+   *
+   * This is metadata for hooks, docs, and generated OpenAPI. Use cases should
+   * still call `runIdempotently(...)` for workflows that must be retry-safe.
+   */
+  required?: boolean;
+
+  /**
+   * Header that carries the idempotency key.
+   *
+   * Default: "idempotency-key".
+   */
+  header?: string;
+
+  /**
+   * How to scope idempotency keys when an HTTP hook derives the scope.
+   *
+   * Default: "global".
+   */
+  scope?: IdempotencyScopeMode;
+
+  /**
+   * Time-to-live for reserved and completed keys.
+   */
+  ttlSec?: number;
+}
+
+/**
+ * Input for reserving an idempotency key.
+ */
+export interface IdempotencyReserveInput {
+  /**
+   * Operation namespace, usually a use-case or route name.
+   */
+  namespace: string;
+  /**
+   * Client-provided idempotency key.
+   */
+  key: string;
+  /**
+   * Logical scope for this key.
+   */
+  scope?: IdempotencyScope;
+  /**
+   * Fingerprint of the logical command payload.
+   */
+  fingerprint: string;
+  /**
+   * Optional key time-to-live in seconds.
+   */
+  ttlSec?: number;
+}
+
+/**
+ * Result of reserving an idempotency key.
+ */
+export type IdempotencyReservation =
+  | {
+      status: "reserved";
+      namespace: string;
+      key: string;
+      scopeKey: string;
+      fingerprint: string;
+      reservedAt: Date;
+      expiresAt: Date | null;
+    }
+  | {
+      status: "replay";
+      namespace: string;
+      key: string;
+      scopeKey: string;
+      fingerprint: string;
+      result: unknown;
+      reservedAt: Date;
+      completedAt: Date;
+      expiresAt: Date | null;
+    }
+  | {
+      status: "inProgress";
+      namespace: string;
+      key: string;
+      scopeKey: string;
+      fingerprint: string;
+      reservedAt: Date;
+      expiresAt: Date | null;
+    }
+  | {
+      status: "conflict";
+      namespace: string;
+      key: string;
+      scopeKey: string;
+      storedFingerprint: string;
+      receivedFingerprint: string;
+      reservedAt: Date;
+      completedAt?: Date;
+      expiresAt: Date | null;
+    };
+
+/**
+ * Input for marking an idempotency key complete.
+ */
+export interface IdempotencyCompleteInput {
+  /**
+   * Operation namespace.
+   */
+  namespace: string;
+  /**
+   * Client-provided idempotency key.
+   */
+  key: string;
+  /**
+   * Logical scope for this key.
+   */
+  scope?: IdempotencyScope;
+  /**
+   * Fingerprint that must match the reserved operation.
+   */
+  fingerprint: string;
+  /**
+   * Result to replay for future matching requests.
+   */
+  result?: unknown;
+}
+
+/**
+ * Input for releasing or marking a failed idempotency reservation.
+ */
+export interface IdempotencyFailInput {
+  /**
+   * Operation namespace.
+   */
+  namespace: string;
+  /**
+   * Client-provided idempotency key.
+   */
+  key: string;
+  /**
+   * Logical scope for this key.
+   */
+  scope?: IdempotencyScope;
+  /**
+   * Fingerprint that must match the reserved operation.
+   */
+  fingerprint: string;
+  /**
+   * Error that caused the protected operation to fail.
+   */
+  error?: unknown;
+}
+
+/**
+ * App-facing idempotency port.
+ */
+export interface IdempotencyPort {
+  /**
+   * Atomically reserve a key for work, replay an already completed result, or
+   * report that the key is in progress/conflicting.
+   */
+  reserve(input: IdempotencyReserveInput): Promise<IdempotencyReservation>;
+
+  /**
+   * Mark a reserved key as complete and store the result that may be replayed.
+   */
+  complete(input: IdempotencyCompleteInput): Promise<void>;
+
+  /**
+   * Release or mark a reserved key after the protected work fails.
+   */
+  fail(input: IdempotencyFailInput): Promise<void>;
+}
+
+/**
+ * Options for reserving an idempotency key around a protected operation.
+ */
+export interface RunIdempotentlyOptions<Result>
+  extends IdempotencyReserveInput {
+  /**
+   * Protected operation to run after the key is reserved.
+   */
+  run: () => MaybePromise<Result>;
+  /**
+   * Replay behavior for completed matching reservations.
+   *
+   * Defaults to returning the stored result. Use `"error"` when callers need to
+   * distinguish replay from first execution.
+   */
+  replay?: "return" | "error";
+}
+
+/**
+ * Options for `createIdempotencyFingerprint(...)`.
+ */
+export interface CreateIdempotencyFingerprintOptions {
+  /**
+   * Omit values from the fingerprint input. Use this for the idempotency key
+   * itself or other request metadata that does not define the logical command.
+   *
+   * String paths can be top-level keys (`"idempotencyKey"`) or dotted paths
+   * (`"metadata.requestId"`). Array paths avoid ambiguity when keys contain
+   * dots.
+   */
+  omit?: readonly (string | readonly string[])[];
+}
+
+/**
+ * In-memory idempotency store for tests and local examples.
+ */
+export interface MemoryIdempotencyStore extends IdempotencyPort {
+  /**
+   * Current store entries.
+   */
+  readonly entries: readonly MemoryIdempotencyEntry[];
+  /**
+   * Remove all entries.
+   */
+  clear(): void;
+}
+
+/**
+ * Snapshot entry from the memory idempotency store.
+ */
+export interface MemoryIdempotencyEntry {
+  /**
+   * Operation namespace.
+   */
+  namespace: string;
+  /**
+   * Client-provided idempotency key.
+   */
+  key: string;
+  /**
+   * Normalized scope key.
+   */
+  scopeKey: string;
+  /**
+   * Fingerprint of the logical command payload.
+   */
+  fingerprint: string;
+  /**
+   * Memory store status.
+   */
+  status: "in-progress" | "completed";
+  /**
+   * Stored result for completed entries.
+   */
+  result?: unknown;
+  /**
+   * Reservation timestamp.
+   */
+  reservedAt: Date;
+  /**
+   * Completion timestamp.
+   */
+  completedAt?: Date;
+  /**
+   * Expiration timestamp, or null for no expiration.
+   */
+  expiresAt: Date | null;
+}
+
+/**
+ * Error thrown when an idempotency key is reused with a different fingerprint.
+ */
+export class IdempotencyConflictError extends Error {
+  readonly namespace: string;
+  readonly key: string;
+  readonly scopeKey: string;
+  readonly storedFingerprint: string;
+  readonly receivedFingerprint: string;
+
+  constructor(args: {
+    namespace: string;
+    key: string;
+    scopeKey: string;
+    storedFingerprint: string;
+    receivedFingerprint: string;
+  }) {
+    super(
+      `Idempotency key "${args.key}" conflicts with a different payload in namespace "${args.namespace}".`,
+    );
+    this.name = "IdempotencyConflictError";
+    this.namespace = args.namespace;
+    this.key = args.key;
+    this.scopeKey = args.scopeKey;
+    this.storedFingerprint = args.storedFingerprint;
+    this.receivedFingerprint = args.receivedFingerprint;
+  }
+}
+
+/**
+ * Error thrown when an idempotency key is already reserved by in-progress work.
+ */
+export class IdempotencyInProgressError extends Error {
+  readonly namespace: string;
+  readonly key: string;
+  readonly scopeKey: string;
+
+  constructor(args: { namespace: string; key: string; scopeKey: string }) {
+    super(
+      `Idempotency key "${args.key}" is already in progress in namespace "${args.namespace}".`,
+    );
+    this.name = "IdempotencyInProgressError";
+    this.namespace = args.namespace;
+    this.key = args.key;
+    this.scopeKey = args.scopeKey;
+  }
+}
+
+/**
+ * Error thrown when replay is disabled for a completed idempotency key.
+ */
+export class IdempotencyReplayError extends Error {
+  readonly namespace: string;
+  readonly key: string;
+  readonly scopeKey: string;
+
+  constructor(args: { namespace: string; key: string; scopeKey: string }) {
+    super(
+      `Idempotency key "${args.key}" already completed in namespace "${args.namespace}".`,
+    );
+    this.name = "IdempotencyReplayError";
+    this.namespace = args.namespace;
+    this.key = args.key;
+    this.scopeKey = args.scopeKey;
+  }
+}
+
+/**
+ * Error thrown when fingerprint input cannot be canonicalized.
+ */
+export class IdempotencyFingerprintError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IdempotencyFingerprintError";
+  }
+}
+
+type CanonicalValue =
+  | null
+  | string
+  | number
+  | boolean
+  | readonly CanonicalValue[]
+  | { readonly [key: string]: CanonicalValue };
+
+type MemoryRecord = MemoryIdempotencyEntry;
+
+function assertNonEmptyString(name: string, value: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+}
+
+function assertTtl(ttlSec: number | undefined): void {
+  if (ttlSec === undefined) return;
+  if (!Number.isInteger(ttlSec) || ttlSec <= 0) {
+    throw new Error("ttlSec must be a positive integer when provided");
+  }
+}
+
+function normalizeScopeValue(value: IdempotencyScopeValue): string {
+  if (value === undefined) return "";
+  if (value === null) return "null";
+  return String(value);
+}
+
+/**
+ * Normalize an idempotency scope into a stable string.
+ */
+export function normalizeIdempotencyScope(
+  scope: IdempotencyScope | undefined,
+): string {
+  if (scope === undefined) return "global";
+  if (typeof scope === "string") return scope;
+
+  return Object.keys(scope)
+    .sort()
+    .map((key) => `${key}:${normalizeScopeValue(scope[key])}`)
+    .join("|");
+}
+
+/**
+ * Create the stable storage key for an idempotency operation.
+ */
+export function createIdempotencyStorageKey(input: {
+  namespace: string;
+  key: string;
+  scope?: IdempotencyScope;
+}): string {
+  assertNonEmptyString("namespace", input.namespace);
+  assertNonEmptyString("key", input.key);
+
+  return [
+    input.namespace,
+    normalizeIdempotencyScope(input.scope),
+    input.key,
+  ].join("\u0000");
+}
+
+function resolveExpiresAt(ttlSec: number | undefined, now: Date): Date | null {
+  assertTtl(ttlSec);
+  return ttlSec === undefined ? null : new Date(now.getTime() + ttlSec * 1000);
+}
+
+function isExpired(entry: MemoryRecord, now: Date): boolean {
+  return entry.expiresAt !== null && entry.expiresAt.getTime() <= now.getTime();
+}
+
+function reservationFromRecord(
+  record: MemoryRecord,
+  receivedFingerprint: string,
+): IdempotencyReservation {
+  if (record.fingerprint !== receivedFingerprint) {
+    return {
+      status: "conflict",
+      namespace: record.namespace,
+      key: record.key,
+      scopeKey: record.scopeKey,
+      storedFingerprint: record.fingerprint,
+      receivedFingerprint,
+      reservedAt: record.reservedAt,
+      completedAt: record.completedAt,
+      expiresAt: record.expiresAt,
+    };
+  }
+
+  if (record.status === "completed" && record.completedAt) {
+    return {
+      status: "replay",
+      namespace: record.namespace,
+      key: record.key,
+      scopeKey: record.scopeKey,
+      fingerprint: record.fingerprint,
+      result: record.result,
+      reservedAt: record.reservedAt,
+      completedAt: record.completedAt,
+      expiresAt: record.expiresAt,
+    };
+  }
+
+  return {
+    status: "inProgress",
+    namespace: record.namespace,
+    key: record.key,
+    scopeKey: record.scopeKey,
+    fingerprint: record.fingerprint,
+    reservedAt: record.reservedAt,
+    expiresAt: record.expiresAt,
+  };
+}
+
+/**
+ * Create an in-memory idempotency store for tests and local examples.
+ *
+ * The memory store is process-local and not suitable for multi-process
+ * production deployments.
+ */
+export function createMemoryIdempotencyStore(): MemoryIdempotencyStore {
+  const records = new Map<string, MemoryRecord>();
+
+  return {
+    get entries() {
+      return [...records.values()];
+    },
+
+    async reserve(input) {
+      assertNonEmptyString("namespace", input.namespace);
+      assertNonEmptyString("key", input.key);
+      assertNonEmptyString("fingerprint", input.fingerprint);
+      assertTtl(input.ttlSec);
+
+      const now = new Date();
+      const storageKey = createIdempotencyStorageKey(input);
+      const existing = records.get(storageKey);
+
+      if (existing && !isExpired(existing, now)) {
+        return reservationFromRecord(existing, input.fingerprint);
+      }
+
+      if (existing) {
+        records.delete(storageKey);
+      }
+
+      const record: MemoryRecord = {
+        namespace: input.namespace,
+        key: input.key,
+        scopeKey: normalizeIdempotencyScope(input.scope),
+        fingerprint: input.fingerprint,
+        status: "in-progress",
+        reservedAt: now,
+        expiresAt: resolveExpiresAt(input.ttlSec, now),
+      };
+
+      records.set(storageKey, record);
+
+      return {
+        status: "reserved",
+        namespace: record.namespace,
+        key: record.key,
+        scopeKey: record.scopeKey,
+        fingerprint: record.fingerprint,
+        reservedAt: record.reservedAt,
+        expiresAt: record.expiresAt,
+      };
+    },
+
+    async complete(input) {
+      assertNonEmptyString("namespace", input.namespace);
+      assertNonEmptyString("key", input.key);
+      assertNonEmptyString("fingerprint", input.fingerprint);
+
+      const storageKey = createIdempotencyStorageKey(input);
+      const existing = records.get(storageKey);
+      if (!existing || existing.fingerprint !== input.fingerprint) return;
+
+      existing.status = "completed";
+      existing.result = input.result;
+      existing.completedAt = new Date();
+    },
+
+    async fail(input) {
+      assertNonEmptyString("namespace", input.namespace);
+      assertNonEmptyString("key", input.key);
+      assertNonEmptyString("fingerprint", input.fingerprint);
+
+      const storageKey = createIdempotencyStorageKey(input);
+      const existing = records.get(storageKey);
+      if (!existing || existing.fingerprint !== input.fingerprint) return;
+      if (existing.status === "completed") return;
+
+      records.delete(storageKey);
+    },
+
+    clear() {
+      records.clear();
+    },
+  };
+}
+
+/**
+ * Run an operation behind an idempotency reservation.
+ *
+ * The flow is: reserve the key, replay completed matching results, reject
+ * in-progress/conflicting keys, run the operation for new reservations, then
+ * complete or fail the reservation. Callers are responsible for choosing a
+ * namespace, scope, key, and fingerprint that match their business operation.
+ */
+export async function runIdempotently<Result>(
+  idempotency: IdempotencyPort,
+  options: RunIdempotentlyOptions<Result>,
+): Promise<Result> {
+  const operation = {
+    namespace: options.namespace,
+    key: options.key,
+    scope: options.scope,
+    fingerprint: options.fingerprint,
+    ttlSec: options.ttlSec,
+  };
+  const reservation = await idempotency.reserve(operation);
+
+  switch (reservation.status) {
+    case "replay": {
+      if (options.replay === "error") {
+        throw new IdempotencyReplayError(reservation);
+      }
+      return reservation.result as Result;
+    }
+    case "inProgress": {
+      throw new IdempotencyInProgressError(reservation);
+    }
+    case "conflict": {
+      throw new IdempotencyConflictError(reservation);
+    }
+    case "reserved": {
+      try {
+        const result = await options.run();
+        await idempotency.complete({
+          namespace: operation.namespace,
+          key: operation.key,
+          scope: operation.scope,
+          fingerprint: operation.fingerprint,
+          result,
+        });
+        return result;
+      } catch (error) {
+        await idempotency.fail({
+          namespace: operation.namespace,
+          key: operation.key,
+          scope: operation.scope,
+          fingerprint: operation.fingerprint,
+          error,
+        });
+        throw error;
+      }
+    }
+  }
+}
+
+function normalizeOmitPath(
+  path: string | readonly string[],
+): readonly string[] {
+  if (typeof path === "string") return path.split(".").filter(Boolean);
+  return path.map(String);
+}
+
+function shouldOmitPath(
+  path: readonly string[],
+  omit: readonly (string | readonly string[])[],
+): boolean {
+  return omit.some((entry) => {
+    const omitPath = normalizeOmitPath(entry);
+    if (omitPath.length !== path.length) return false;
+    return omitPath.every((segment, index) => segment === path[index]);
+  });
+}
+
+function canonicalize(
+  value: unknown,
+  options: CreateIdempotencyFingerprintOptions,
+  path: readonly string[],
+  seen: WeakSet<object>,
+): CanonicalValue | undefined {
+  if (shouldOmitPath(path, options.omit ?? [])) {
+    return undefined;
+  }
+
+  if (value === undefined || typeof value === "function") {
+    return undefined;
+  }
+
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new IdempotencyFingerprintError(
+        "Cannot fingerprint non-finite numeric values.",
+      );
+    }
+    return value;
+  }
+
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(
+      (item, index) =>
+        canonicalize(item, options, [...path, String(index)], seen) ?? null,
+    );
+  }
+
+  if (typeof value === "object") {
+    if (seen.has(value)) {
+      throw new IdempotencyFingerprintError(
+        "Cannot fingerprint circular values.",
+      );
+    }
+    seen.add(value);
+
+    const result: Record<string, CanonicalValue> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      const nestedValue = canonicalize(
+        (value as Record<string, unknown>)[key],
+        options,
+        [...path, key],
+        seen,
+      );
+      if (nestedValue !== undefined) {
+        result[key] = nestedValue;
+      }
+    }
+
+    seen.delete(value);
+    return result;
+  }
+
+  throw new IdempotencyFingerprintError(
+    `Cannot fingerprint value of type "${typeof value}".`,
+  );
+}
+
+function bytesToHex(bytes: ArrayBuffer): string {
+  return [...new Uint8Array(bytes)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Create a SHA-256 fingerprint from a canonicalized value.
+ *
+ * Object keys are sorted, `undefined` and functions are omitted, `Date` values
+ * become ISO strings, BigInts become strings, and circular or non-finite values
+ * throw. Exact omit paths may be supplied as dotted strings or string arrays.
+ */
+export async function createIdempotencyFingerprint(
+  value: unknown,
+  options: CreateIdempotencyFingerprintOptions = {},
+): Promise<string> {
+  if (!globalThis.crypto?.subtle) {
+    throw new IdempotencyFingerprintError(
+      "Cannot create an idempotency fingerprint because Web Crypto is unavailable.",
+    );
+  }
+
+  const canonical = canonicalize(value, options, [], new WeakSet());
+  const json = JSON.stringify(canonical ?? null);
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(json),
+  );
+
+  return `sha256:${bytesToHex(digest)}`;
+}