deepline 0.1.79 → 0.1.80

package/dist/repo/apps/play-runner-workers/src/child-play-await.ts

@@ -0,0 +1,192 @@
+/**
+ * Child-play terminal await — the race between a Cloudflare Workflow
+ * `waitForEvent('child_play_terminal:...')` and a coordinator terminal-state
+ * poll, extracted from entry.ts so the runtime keeps a small, testable surface
+ * for "block until this child run reaches a terminal state".
+ *
+ * Behavior is identical to the inline implementation it replaces: arm the
+ * workflow event wait, race it against `pollParentChildTerminalState`, and
+ * resolve on whichever reports the child's terminal status first. The poll
+ * never resolves on a non-terminal/absent state (it returns a never-settling
+ * promise on timeout) so the event wait remains the primary path and the poll
+ * is a coordinator-side safety net for missed signals.
+ */
+
+export type WorkflowStepLike = {
+  waitForEvent: (
+    name: string,
+    options: { type: string; timeout: string },
+  ) => Promise<{ payload: unknown }>;
+};
+
+export type ChildTerminalCoordinator = {
+  readChildTerminalState(
+    parentRunId: string,
+    eventKey: string,
+    timeoutMs?: number,
+  ): Promise<{ data?: unknown } | null>;
+};
+
+export type ChildPlayTerminalWaitResult = {
+  output: unknown;
+  source: 'workflow_event' | 'parent_child_terminal_cache';
+  attempts?: number;
+  waitMs: number;
+};
+
+export interface AwaitChildTerminalInput {
+  parentRunId: string;
+  workflowStep: WorkflowStepLike | undefined;
+  workflowId: string;
+  playName: string;
+  key: string;
+  timeoutMs: number;
+  /** Coordinator binding for the terminal-state poll. Null disables the poll. */
+  coordinator: ChildTerminalCoordinator | null;
+  now: () => number;
+  /** SHA-256 hex digest helper (same canonical hash entry.ts uses). */
+  hashJson: (value: unknown) => Promise<string>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function workflowEventType(name: string): string {
+  const normalized = name
+    .trim()
+    .replace(/[^A-Za-z0-9_-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 100);
+  return normalized || 'deepline_event';
+}
+
+function integrationEventType(eventKey: string): string {
+  return workflowEventType(`integration_event_${eventKey}`);
+}
+
+function workflowTimeoutFromMs(timeoutMs: number): string {
+  const seconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+  return `${seconds} second${seconds === 1 ? '' : 's'}`;
+}
+
+function readChildTerminalPayload(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) return {};
+  const data = value.data;
+  return isRecord(data) ? data : value;
+}
+
+function extractChildPlayOutput(status: Record<string, unknown>): unknown {
+  const result = status.result;
+  if (isRecord(result) && 'output' in result) {
+    return result.output;
+  }
+  return result ?? null;
+}
+
+async function childPlayEventKey(input: {
+  key: string;
+  workflowId: string;
+  hashJson: (value: unknown) => Promise<string>;
+}): Promise<string> {
+  const readableKey = workflowEventType(input.key).slice(0, 40);
+  const digest = (
+    await input.hashJson({ key: input.key, workflowId: input.workflowId })
+  ).slice(0, 32);
+  return `child_play_${digest}_${readableKey}`;
+}
+
+async function pollParentChildTerminalState(input: {
+  coordinator: ChildTerminalCoordinator | null;
+  parentRunId: string;
+  eventKey: string;
+  timeoutMs: number;
+  now: () => number;
+}): Promise<{
+  source: 'parent_child_terminal_cache';
+  payload: Record<string, unknown>;
+  attempts: number;
+}> {
+  const { coordinator, parentRunId } = input;
+  if (!coordinator?.readChildTerminalState || !parentRunId) {
+    return await new Promise(() => undefined);
+  }
+  const startedAt = input.now();
+  let attempts = 0;
+  while (input.now() - startedAt < input.timeoutMs) {
+    attempts += 1;
+    const remainingMs = Math.max(
+      0,
+      input.timeoutMs - (input.now() - startedAt),
+    );
+    const waitMs = Math.min(remainingMs, 30_000);
+    const state = await coordinator
+      .readChildTerminalState(parentRunId, input.eventKey, waitMs)
+      .catch(() => null);
+    if (isRecord(state?.data)) {
+      return {
+        source: 'parent_child_terminal_cache',
+        payload: state.data,
+        attempts,
+      };
+    }
+  }
+  return await new Promise(() => undefined);
+}
+
+/**
+ * Block until the child run reaches a terminal state, via the workflow event
+ * wait raced against the coordinator terminal-state poll. Throws on a non-
+ * completed terminal status.
+ */
+export async function awaitChildTerminal(
+  input: AwaitChildTerminalInput,
+): Promise<ChildPlayTerminalWaitResult> {
+  if (!input.workflowStep) {
+    throw new Error(
+      'ctx.runPlay child waits require the cf-workflows runtime event scheduler.',
+    );
+  }
+  const waitStartedAt = input.now();
+  const eventKey = await childPlayEventKey({
+    key: input.key,
+    workflowId: input.workflowId,
+    hashJson: input.hashJson,
+  });
+  const eventPromise = input.workflowStep
+    .waitForEvent(`child_play_terminal:${eventKey}`, {
+      type: integrationEventType(eventKey),
+      timeout: workflowTimeoutFromMs(input.timeoutMs),
+    })
+    .then((event) => ({
+      source: 'workflow_event' as const,
+      payload: readChildTerminalPayload(event.payload),
+      attempts: undefined as number | undefined,
+    }));
+  const terminal = await Promise.race([
+    eventPromise,
+    pollParentChildTerminalState({
+      coordinator: input.coordinator,
+      parentRunId: input.parentRunId,
+      eventKey,
+      timeoutMs: Math.min(input.timeoutMs, 30_000),
+      now: input.now,
+    }),
+  ]);
+  const payload = terminal.payload;
+  const status = String(payload.status ?? '').toLowerCase();
+  if (status === 'completed') {
+    return {
+      output: extractChildPlayOutput(payload),
+      source: terminal.source,
+      attempts: terminal.attempts,
+      waitMs: input.now() - waitStartedAt,
+    };
+  }
+  const error = isRecord(payload.error) ? payload.error : null;
+  const message =
+    (typeof error?.message === 'string' && error.message.trim()) ||
+    (typeof payload.error === 'string' && payload.error.trim()) ||
+    `Child play ${input.playName} (${input.workflowId}) finished with status ${status || 'unknown'}.`;
+  throw new Error(message);
+}