deepline 0.1.181 → 0.1.183

package/dist/bundling-sources/shared_libs/play-runtime/work-receipt-state-machine.ts

@@ -0,0 +1,437 @@
+export type WorkReceiptStateStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'skipped';
+
+export type WorkReceiptStateInput = {
+  status: WorkReceiptStateStatus;
+  runId?: string | null;
+  failureKind?: 'terminal' | 'repairable' | null;
+  leaseId?: string | null;
+  leaseOwnerRunId?: string | null;
+  leaseOwnerAttempt?: number | null;
+  leaseExpiresAt?: string | null;
+};
+
+export type WorkReceiptLeaseState =
+  | { kind: 'none' }
+  | {
+      kind: 'active';
+      leaseId: string;
+      ownerRunId: string;
+      ownerAttempt: number;
+      expiresAt: string;
+      expiresAtMs: number;
+    }
+  | {
+      kind: 'expired';
+      leaseId: string | null;
+      ownerRunId: string;
+      ownerAttempt: number;
+      expiresAt: string;
+      expiresAtMs: number;
+    }
+  | {
+      kind: 'invalid';
+      reason:
+        | 'missing_owner'
+        | 'missing_expiry'
+        | 'missing_lease_id'
+        | 'invalid_expiry';
+      leaseId: string | null;
+      ownerRunId: string | null;
+      expiresAt: string | null;
+    };
+
+export type WorkReceiptInvalidLeaseReason = Extract<
+  WorkReceiptLeaseState,
+  { kind: 'invalid' }
+>['reason'];
+
+export type WorkReceiptState =
+  | {
+      kind: 'pending';
+      terminal: false;
+      reusable: false;
+      lease: WorkReceiptLeaseState;
+    }
+  | {
+      kind: 'running';
+      terminal: false;
+      reusable: false;
+      lease: WorkReceiptLeaseState;
+    }
+  | {
+      kind: 'completed';
+      terminal: true;
+      reusable: true;
+      lease: WorkReceiptLeaseState;
+    }
+  | {
+      kind: 'skipped';
+      terminal: true;
+      reusable: true;
+      lease: WorkReceiptLeaseState;
+    }
+  | {
+      kind: 'failed';
+      terminal: true;
+      reusable: false;
+      lease: WorkReceiptLeaseState;
+    };
+
+export type WorkReceiptClaimDecision =
+  | { kind: 'claim' }
+  | { kind: 'reuse_terminal' }
+  | {
+      kind: 'blocked_active_lease';
+      status: WorkReceiptStateStatus;
+      ownerRunId: string | null;
+      leaseId: string | null;
+    }
+  | {
+      kind: 'blocked_running';
+      ownerRunId: string | null;
+      leaseId: string | null;
+    }
+  | {
+      kind: 'blocked_invalid_lease';
+      reason: WorkReceiptInvalidLeaseReason;
+      status: WorkReceiptStateStatus;
+    }
+  | { kind: 'blocked_failed' };
+
+export type WorkReceiptOwnerOperationDecision =
+  | { kind: 'allow' }
+  | {
+      kind: 'reject';
+      reason:
+        | 'missing_receipt'
+        | 'not_running'
+        | 'owner_mismatch'
+        | 'attempt_mismatch'
+        | 'lease_mismatch'
+        | 'missing_request_lease';
+    };
+
+export type WorkReceiptOwnerOperationInput = {
+  receipt: WorkReceiptStateInput | null;
+  ownerRunId?: string | null;
+  ownerRunAttempt?: number | null;
+  leaseId?: string | null;
+};
+
+function normalize(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function normalizeAttempt(value: number | null | undefined): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, Math.floor(value))
+    : 0;
+}
+
+export function classifyWorkReceiptLeaseState(
+  receipt: WorkReceiptStateInput,
+  nowMs: number,
+): WorkReceiptLeaseState {
+  const ownerRunId =
+    normalize(receipt.leaseOwnerRunId) ?? normalize(receipt.runId);
+  const leaseId = normalize(receipt.leaseId);
+  const expiresAt = normalize(receipt.leaseExpiresAt);
+  if (!leaseId && !expiresAt) {
+    return { kind: 'none' };
+  }
+  if (!ownerRunId) {
+    return {
+      kind: 'invalid',
+      reason: 'missing_owner',
+      leaseId,
+      ownerRunId,
+      expiresAt,
+    };
+  }
+  if (!expiresAt) {
+    return {
+      kind: 'invalid',
+      reason: 'missing_expiry',
+      leaseId,
+      ownerRunId,
+      expiresAt,
+    };
+  }
+  const expiresAtMs = Date.parse(expiresAt);
+  if (!Number.isFinite(expiresAtMs)) {
+    return {
+      kind: 'invalid',
+      reason: 'invalid_expiry',
+      leaseId,
+      ownerRunId,
+      expiresAt,
+    };
+  }
+  if (expiresAtMs <= nowMs) {
+    return {
+      kind: 'expired',
+      leaseId,
+      ownerRunId,
+      ownerAttempt: normalizeAttempt(receipt.leaseOwnerAttempt),
+      expiresAt,
+      expiresAtMs,
+    };
+  }
+  if (!leaseId) {
+    return {
+      kind: 'invalid',
+      reason: 'missing_lease_id',
+      leaseId,
+      ownerRunId,
+      expiresAt,
+    };
+  }
+  return {
+    kind: 'active',
+    leaseId,
+    ownerRunId,
+    ownerAttempt: normalizeAttempt(receipt.leaseOwnerAttempt),
+    expiresAt,
+    expiresAtMs,
+  };
+}
+
+export function classifyWorkReceiptState(
+  receipt: WorkReceiptStateInput,
+  nowMs: number,
+): WorkReceiptState {
+  const lease = classifyWorkReceiptLeaseState(receipt, nowMs);
+  switch (receipt.status) {
+    case 'pending':
+      return { kind: 'pending', terminal: false, reusable: false, lease };
+    case 'running':
+      return { kind: 'running', terminal: false, reusable: false, lease };
+    case 'completed':
+      return { kind: 'completed', terminal: true, reusable: true, lease };
+    case 'skipped':
+      return { kind: 'skipped', terminal: true, reusable: true, lease };
+    case 'failed':
+      return { kind: 'failed', terminal: true, reusable: false, lease };
+    default:
+      return assertNever(receipt.status);
+  }
+}
+
+export function decideWorkReceiptClaim(input: {
+  receipt: WorkReceiptStateInput | null;
+  claimantRunId?: string | null;
+  claimantRunAttempt?: number | null;
+  reclaimRunning?: boolean;
+  forceRefresh?: boolean;
+  forceFailedRefresh?: boolean;
+  nowMs: number;
+}): WorkReceiptClaimDecision {
+  if (!input.receipt) return { kind: 'claim' };
+  const state = classifyWorkReceiptState(input.receipt, input.nowMs);
+  if (state.reusable && input.forceRefresh !== true) {
+    return { kind: 'reuse_terminal' };
+  }
+  if (state.kind === 'failed' && input.forceRefresh !== true) {
+    if (input.forceFailedRefresh === true) {
+      return { kind: 'claim' };
+    }
+    const claimantRunId = normalize(input.claimantRunId);
+    const ownerRunId = normalize(input.receipt.runId);
+    const claimantRunAttempt = normalizeAttempt(input.claimantRunAttempt);
+    const ownerAttempt = normalizeAttempt(input.receipt.leaseOwnerAttempt);
+    if (
+      input.receipt.failureKind === 'repairable' &&
+      claimantRunId !== null &&
+      ownerRunId !== null &&
+      (claimantRunId !== ownerRunId || ownerAttempt < claimantRunAttempt)
+    ) {
+      return { kind: 'claim' };
+    }
+    return { kind: 'blocked_failed' };
+  }
+  if (state.kind === 'pending' || state.kind === 'running') {
+    if (state.lease.kind === 'active') {
+      if (
+        (state.kind !== 'running' ||
+          input.reclaimRunning === true ||
+          input.forceRefresh === true) &&
+        state.lease.ownerRunId !== null &&
+        state.lease.ownerRunId === normalize(input.claimantRunId) &&
+        state.lease.ownerAttempt < normalizeAttempt(input.claimantRunAttempt)
+      ) {
+        return { kind: 'claim' };
+      }
+      return {
+        kind: 'blocked_active_lease',
+        status: state.kind,
+        ownerRunId: state.lease.ownerRunId,
+        leaseId: state.lease.leaseId,
+      };
+    }
+    if (state.lease.kind === 'invalid') {
+      return {
+        kind: 'blocked_invalid_lease',
+        reason: state.lease.reason,
+        status: state.kind,
+      };
+    }
+    if (input.forceRefresh === true && input.reclaimRunning === true) {
+      return { kind: 'claim' };
+    }
+    if (state.kind === 'pending') {
+      return { kind: 'claim' };
+    }
+    if (
+      input.reclaimRunning === true &&
+      (state.lease.kind === 'expired' || state.lease.kind === 'none')
+    ) {
+      return { kind: 'claim' };
+    }
+    return {
+      kind: 'blocked_running',
+      ownerRunId:
+        state.lease.kind === 'expired'
+          ? state.lease.ownerRunId
+          : normalize(input.receipt.runId),
+      leaseId:
+        state.lease.kind === 'expired'
+          ? state.lease.leaseId
+          : normalize(input.receipt.leaseId),
+    };
+  }
+  if (
+    input.forceRefresh === true &&
+    (state.kind === 'completed' || state.kind === 'skipped')
+  ) {
+    if (state.lease.kind === 'active') {
+      if (
+        state.lease.ownerRunId !== null &&
+        state.lease.ownerRunId === normalize(input.claimantRunId) &&
+        state.lease.ownerAttempt < normalizeAttempt(input.claimantRunAttempt)
+      ) {
+        return { kind: 'claim' };
+      }
+      return {
+        kind: 'blocked_active_lease',
+        status: state.kind,
+        ownerRunId: state.lease.ownerRunId,
+        leaseId: state.lease.leaseId,
+      };
+    }
+    if (state.lease.kind === 'invalid') {
+      return {
+        kind: 'blocked_invalid_lease',
+        reason: state.lease.reason,
+        status: state.kind,
+      };
+    }
+  }
+  if (input.forceRefresh === true) {
+    return { kind: 'claim' };
+  }
+  return { kind: 'claim' };
+}
+
+function ownerRunIdForReceipt(receipt: WorkReceiptStateInput): string | null {
+  return normalize(receipt.leaseOwnerRunId) ?? normalize(receipt.runId);
+}
+
+function baseRunningOwnerDecision(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  if (!input.receipt) {
+    return { kind: 'reject', reason: 'missing_receipt' };
+  }
+  if (input.receipt.status !== 'running') {
+    return { kind: 'reject', reason: 'not_running' };
+  }
+  const ownerRunId = normalize(input.ownerRunId);
+  if (!ownerRunId || ownerRunIdForReceipt(input.receipt) !== ownerRunId) {
+    return { kind: 'reject', reason: 'owner_mismatch' };
+  }
+  if (
+    normalizeAttempt(input.receipt.leaseOwnerAttempt) !==
+    normalizeAttempt(input.ownerRunAttempt)
+  ) {
+    return { kind: 'reject', reason: 'attempt_mismatch' };
+  }
+  return { kind: 'allow' };
+}
+
+/**
+ * Law for complete/fail/skip. A terminal write may only be made by the
+ * running receipt owner for the same attempt. When the receipt has a lease id,
+ * the writer must also present that exact lease id; legacy unleased running
+ * receipts remain writable by their run+attempt owner during the migration.
+ */
+export function decideWorkReceiptTerminalWrite(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  const ownerDecision = baseRunningOwnerDecision(input);
+  if (ownerDecision.kind === 'reject') return ownerDecision;
+
+  const receiptLeaseId = normalize(input.receipt?.leaseId);
+  if (!receiptLeaseId) return { kind: 'allow' };
+  if (receiptLeaseId !== normalize(input.leaseId)) {
+    return { kind: 'reject', reason: 'lease_mismatch' };
+  }
+  return { kind: 'allow' };
+}
+
+/**
+ * Law for a single suspended receipt release. It uses the same ownership fence
+ * as terminal writes: only the running owner can release, and a leased receipt
+ * requires the exact lease id.
+ */
+export function decideWorkReceiptExactRelease(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  return decideWorkReceiptTerminalWrite(input);
+}
+
+/**
+ * Law for run-fatal teardown. The owner may release all of its still-running
+ * receipts for the same attempt without threading every per-receipt lease id.
+ * It must never match another run or another attempt.
+ */
+export function decideWorkReceiptOwnerRelease(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  return baseRunningOwnerDecision(input);
+}
+
+/**
+ * Law for heartbeat. Heartbeats are stricter than terminal writes: they renew a
+ * specific live lease, so both receipt and request must carry the same lease id.
+ */
+export function decideWorkReceiptHeartbeat(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  const ownerDecision = baseRunningOwnerDecision(input);
+  if (ownerDecision.kind === 'reject') return ownerDecision;
+
+  const requestLeaseId = normalize(input.leaseId);
+  if (!requestLeaseId) {
+    return { kind: 'reject', reason: 'missing_request_lease' };
+  }
+  if (normalize(input.receipt?.leaseId) !== requestLeaseId) {
+    return { kind: 'reject', reason: 'lease_mismatch' };
+  }
+  return { kind: 'allow' };
+}
+
+export function isReusableWorkReceiptState(
+  receipt: WorkReceiptStateInput,
+): boolean {
+  return receipt.status === 'completed' || receipt.status === 'skipped';
+}
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled work receipt state: ${String(value)}`);
+}

package/dist/bundling-sources/shared_libs/play-runtime/work-receipts.ts

@@ -1,3 +1,29 @@
+import { isReusableWorkReceiptState } from './work-receipt-state-machine';
+
+export type WorkReceiptFailureKind = 'terminal' | 'repairable';
+
+export const WORK_RECEIPT_FAILURE_KIND_CODE: Record<
+  WorkReceiptFailureKind,
+  number
+> = {
+  terminal: 0,
+  repairable: 1,
+};
+
+export function workReceiptFailureKindFromCode(
+  value: unknown,
+): WorkReceiptFailureKind {
+  return Number(value) === WORK_RECEIPT_FAILURE_KIND_CODE.repairable
+    ? 'repairable'
+    : 'terminal';
+}
+
+export function workReceiptFailureKindCode(
+  value: WorkReceiptFailureKind | null | undefined,
+): number {
+  return WORK_RECEIPT_FAILURE_KIND_CODE[value ?? 'terminal'];
+}
+
 export type WorkReceiptStatus =
   | 'pending'
   | 'running'
@@ -10,7 +36,12 @@ export type WorkReceipt = {
   status: WorkReceiptStatus;
   output?: unknown;
   error?: string | null;
+  failureKind?: WorkReceiptFailureKind | null;
   runId?: string | null;
+  leaseId?: string | null;
+  leaseOwnerRunId?: string | null;
+  leaseOwnerAttempt?: number | null;
+  leaseExpiresAt?: string | null;
   updatedAt?: string | null;
 };
 
@@ -18,26 +49,57 @@ export type WorkReceiptCommand = {
   playName: string;
   runId: string;
   key: string;
+  leaseId?: string | null;
+  runAttempt?: number | null;
+  leaseTtlMs?: number | null;
+  leaseAware?: boolean;
   reclaimRunning?: boolean;
   forceRefresh?: boolean;
+  forceFailedRefresh?: boolean;
 };
 
 export type WorkReceiptBatchClaimCommand = {
   playName: string;
   runId: string;
   keys: string[];
+  leaseAware?: boolean;
   reclaimRunning?: boolean;
   forceRefresh?: boolean;
+  forceFailedRefresh?: boolean;
+  runAttempt?: number | null;
+  leaseTtlMs?: number | null;
 };
 
 export type WorkReceiptBatchCompleteCommand = {
   playName: string;
-  receipts: Array<{ runId: string; key: string; output: unknown }>;
+  receipts: Array<{
+    runId: string;
+    key: string;
+    output: unknown;
+    leaseId?: string | null;
+    runAttempt?: number | null;
+  }>;
 };
 
 export type WorkReceiptBatchFailCommand = {
   playName: string;
-  receipts: Array<{ runId: string; key: string; error: string }>;
+  receipts: Array<{
+    runId: string;
+    key: string;
+    error: string;
+    failureKind?: WorkReceiptFailureKind | null;
+    leaseId?: string | null;
+    runAttempt?: number | null;
+  }>;
+};
+
+export type WorkReceiptBatchHeartbeatCommand = {
+  playName: string;
+  runId: string;
+  runAttempt?: number | null;
+  leaseId: string;
+  keys: string[];
+  leaseTtlMs?: number | null;
 };
 
 export type WorkReceiptGetCommand = {
@@ -58,6 +120,10 @@ export type WorkReceiptClaim =
       disposition: 'running';
       receipt: WorkReceipt;
     }
+  | {
+      disposition: 'blocked_active_lease';
+      receipt: WorkReceipt;
+    }
   | {
       disposition: 'failed';
       receipt: WorkReceipt;
@@ -74,11 +140,22 @@ export type WorkReceiptStore = {
   ): Promise<WorkReceipt | null>;
   completeReceipts?(
     input: WorkReceiptBatchCompleteCommand,
-  ): Promise<WorkReceipt[]>;
+  ): Promise<Array<WorkReceipt | null>>;
   failReceipt(
-    input: WorkReceiptCommand & { error: string },
+    input: WorkReceiptCommand & {
+      error: string;
+      failureKind?: WorkReceiptFailureKind | null;
+    },
+  ): Promise<WorkReceipt | null>;
+  failReceipts?(
+    input: WorkReceiptBatchFailCommand,
+  ): Promise<Array<WorkReceipt | null>>;
+  releaseReceipt?(
+    input: WorkReceiptCommand,
   ): Promise<WorkReceipt | null>;
-  failReceipts?(input: WorkReceiptBatchFailCommand): Promise<WorkReceipt[]>;
+  heartbeatReceipts?(
+    input: WorkReceiptBatchHeartbeatCommand,
+  ): Promise<Array<WorkReceipt | null>>;
 };
 
 const SCOPED_WORK_RECEIPT_KEY_VERSION = 'ctxv2';
@@ -122,5 +199,5 @@ export function scopedWorkReceiptKeyPrefix(input: {
 }
 
 export function isReusableWorkReceipt(receipt: WorkReceipt): boolean {
-  return receipt.status === 'completed' || receipt.status === 'skipped';
+  return isReusableWorkReceiptState(receipt);
 }

package/dist/bundling-sources/shared_libs/security/safe-outbound-fetch.ts

@@ -42,6 +42,12 @@ const TRANSPORT_OWNED_REQUEST_HEADERS = new Set([
   'x-forwarded-host',
   'x-forwarded-proto',
 ]);
+const CROSS_ORIGIN_REDIRECT_SAFE_HEADERS = new Set([
+  'accept',
+  'accept-language',
+  'content-language',
+  'content-type',
+]);
 
 function cloneHeaders(headers: RequestInit['headers']): Headers {
   return new Headers(headers);
@@ -57,6 +63,18 @@ function removeTransportOwnedHeaders(headers: Headers): void {
   }
 }
 
+function removeUnsafeCrossOriginRedirectHeaders(headers: Headers): void {
+  const namesToDelete: string[] = [];
+  for (const [name] of headers) {
+    if (!CROSS_ORIGIN_REDIRECT_SAFE_HEADERS.has(name.toLowerCase())) {
+      namesToDelete.push(name);
+    }
+  }
+  for (const name of namesToDelete) {
+    headers.delete(name);
+  }
+}
+
 function withContentLength(
   body: Buffer | string | undefined,
   headers: Headers,
@@ -222,14 +240,11 @@ function createRequest(
         response.on('error', reject);
         response.on('end', () => {
           resolve(
-            new Response(
-              noBodyResponse ? null : Buffer.concat(chunks),
-              {
-                status,
-                statusText: response.statusMessage,
-                headers: response.headers as HeadersInit,
-              },
-            ),
+            new Response(noBodyResponse ? null : Buffer.concat(chunks), {
+              status,
+              statusText: response.statusMessage,
+              headers: response.headers as HeadersInit,
+            }),
           );
         });
       },
@@ -248,7 +263,6 @@ function initForRedirect(
   from: URL,
   to: URL,
   status: number,
-  sensitiveHeaders: Iterable<string>,
 ): RequestInit {
   const headers = cloneHeaders(init.headers);
   let method = String(init.method ?? 'GET').toUpperCase();
@@ -265,12 +279,7 @@ function initForRedirect(
   }
 
   if (from.origin !== to.origin) {
-    deleteHeader(headers, 'authorization');
-    deleteHeader(headers, 'cookie');
-    deleteHeader(headers, 'proxy-authorization');
-    for (const header of sensitiveHeaders) {
-      deleteHeader(headers, header);
-    }
+    removeUnsafeCrossOriginRedirectHeaders(headers);
   }
 
   return {
@@ -290,7 +299,6 @@ export async function safeOutboundFetch(
   const redirectMode = init.redirect ?? 'follow';
   const maxRedirects = options.maxRedirects ?? 10;
   const maxResponseBytes = options.maxResponseBytes;
-  const sensitiveHeaders = options.sensitiveHeaders ?? [];
   const validateUrl = options.validateUrl;
   let currentUrl = assertPublicHttpUrl(input);
   let currentInit: RequestInit = { ...init, redirect: 'manual' };
@@ -348,7 +356,6 @@ export async function safeOutboundFetch(
       currentUrl,
       nextUrl,
       response.status,
-      sensitiveHeaders,
     );
     currentUrl = nextUrl;
   }