deepline 0.1.211 → 0.1.213

package/dist/bundling-sources/shared_libs/play-runtime/completed-receipt-cache.ts

@@ -0,0 +1,166 @@
+/**
+ * A completed receipt is an immutable cache fact. Execution coordination is a
+ * separate, short-lived concern and must never be represented by a "running"
+ * receipt.
+ */
+export type CompletedReceipt<T> = {
+  key: string;
+  output: T;
+  createdAt: string;
+  expiresAt?: string | null;
+};
+
+export type CompletedReceiptCache<T> = {
+  get(key: string): Promise<CompletedReceipt<T> | null>;
+  /**
+   * Insert only when the key is absent. On conflict, return the already stored
+   * immutable fact. Implementations should use INSERT ... ON CONFLICT DO
+   * NOTHING followed by a point read.
+   */
+  putIfAbsent(receipt: CompletedReceipt<T>): Promise<CompletedReceipt<T>>;
+};
+
+export type ReceiptExecutionLock = {
+  receiptKey: string;
+  ownerExecutionId: string;
+  expiresAt: string;
+};
+
+export type ReceiptExecutionLockStore = {
+  tryAcquire(input: {
+    receiptKey: string;
+    ownerExecutionId: string;
+    expiresAt: string;
+  }): Promise<ReceiptExecutionLock | null>;
+  release(input: {
+    receiptKey: string;
+    ownerExecutionId: string;
+  }): Promise<void>;
+};
+
+export type ReceiptMissCoordination =
+  | { kind: 'provider_idempotency' }
+  | {
+      kind: 'execution_lock';
+      store: ReceiptExecutionLockStore;
+      ownerExecutionId: string;
+      lockTtlMs: number;
+      waitTimeoutMs: number;
+      pollIntervalMs?: number;
+    };
+
+export class ReceiptExecutionLockTimeoutError extends Error {
+  constructor(receiptKey: string, waitTimeoutMs: number) {
+    super(
+      `Timed out waiting ${waitTimeoutMs}ms for receipt execution lock ${receiptKey}.`,
+    );
+    this.name = 'ReceiptExecutionLockTimeoutError';
+  }
+}
+
+const MAX_EXECUTION_LOCK_TTL_MS = 10 * 60_000;
+
+function assertBoundedLockPolicy(
+  policy: Extract<ReceiptMissCoordination, { kind: 'execution_lock' }>,
+): void {
+  if (
+    !Number.isFinite(policy.lockTtlMs) ||
+    policy.lockTtlMs <= 0 ||
+    policy.lockTtlMs > MAX_EXECUTION_LOCK_TTL_MS
+  ) {
+    throw new Error(
+      `Receipt execution lock TTL must be between 1 and ${MAX_EXECUTION_LOCK_TTL_MS}ms.`,
+    );
+  }
+  if (!Number.isFinite(policy.waitTimeoutMs) || policy.waitTimeoutMs <= 0) {
+    throw new Error('Receipt execution lock wait timeout must be positive.');
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function executeAndPublish<T>(input: {
+  receiptKey: string;
+  cache: CompletedReceiptCache<T>;
+  execute: () => Promise<T>;
+  now: () => number;
+  receiptTtlMs?: number | null;
+}): Promise<T> {
+  const output = await input.execute();
+  const now = input.now();
+  const receipt = await input.cache.putIfAbsent({
+    key: input.receiptKey,
+    output,
+    createdAt: new Date(now).toISOString(),
+    ...(input.receiptTtlMs
+      ? { expiresAt: new Date(now + input.receiptTtlMs).toISOString() }
+      : {}),
+  });
+  return receipt.output;
+}
+
+/**
+ * Execute one semantic operation against an immutable completed-receipt cache.
+ *
+ * Providers with native idempotency do not need a Deepline execution lock:
+ * concurrent misses may dispatch with the same provider idempotency key, then
+ * converge on the first immutable cache insert. A separate temporary lock is
+ * reserved for actions explicitly classified as dangerous non-idempotent side
+ * effects. Ordinary enrichment misses may do bounded duplicate work and
+ * converge on the first published receipt.
+ */
+export async function executeWithCompletedReceiptCache<T>(input: {
+  receiptKey: string;
+  cache: CompletedReceiptCache<T>;
+  missCoordination: ReceiptMissCoordination;
+  execute: () => Promise<T>;
+  now?: () => number;
+  receiptTtlMs?: number | null;
+}): Promise<T> {
+  const cached = await input.cache.get(input.receiptKey);
+  if (cached) return cached.output;
+
+  const now = input.now ?? Date.now;
+  if (input.missCoordination.kind === 'provider_idempotency') {
+    return await executeAndPublish({ ...input, now });
+  }
+
+  const policy = input.missCoordination;
+  assertBoundedLockPolicy(policy);
+  const deadline = now() + policy.waitTimeoutMs;
+  const pollIntervalMs = Math.max(1, policy.pollIntervalMs ?? 100);
+
+  while (true) {
+    const lock = await policy.store.tryAcquire({
+      receiptKey: input.receiptKey,
+      ownerExecutionId: policy.ownerExecutionId,
+      expiresAt: new Date(now() + policy.lockTtlMs).toISOString(),
+    });
+    if (lock) {
+      try {
+        // The previous owner may have published between our cache read and
+        // lock acquisition. Never execute after that terminal fact exists.
+        const afterAcquire = await input.cache.get(input.receiptKey);
+        if (afterAcquire) return afterAcquire.output;
+        return await executeAndPublish({ ...input, now });
+      } finally {
+        await policy.store.release({
+          receiptKey: input.receiptKey,
+          ownerExecutionId: policy.ownerExecutionId,
+        });
+      }
+    }
+
+    const completed = await input.cache.get(input.receiptKey);
+    if (completed) return completed.output;
+    if (now() >= deadline) {
+      throw new ReceiptExecutionLockTimeoutError(
+        input.receiptKey,
+        policy.waitTimeoutMs,
+      );
+    }
+    await sleep(Math.min(pollIntervalMs, Math.max(1, deadline - now())));
+  }
+}