@voyantjs/workflows-orchestrator-cloudflare 0.6.7

package/src/cf-container-runner.ts

@@ -0,0 +1,298 @@
+// Cloudflare Container-backed step runner for `runtime: "node"`.
+//
+// Given a Durable Object namespace that proxies a Cloudflare Container
+// class (the `@cloudflare/containers` pattern), this factory returns a
+// `StepRunner` the workflows handler can wire via its `nodeStepRunner`
+// dep. The returned runner:
+//
+//   1. Serializes the step identity + input into a compact request.
+//   2. Picks a container by deterministic id (`<runId>:<stepId>` so
+//      parallel step invocations land on distinct instances).
+//   3. POSTs the request to `/step` on that container via `fetch`
+//      through the DO namespace binding.
+//   4. Reads the container's response — which *is* a `StepJournalEntry`
+//      (status, output/error, timestamps) — and returns it verbatim.
+//
+// The container side is expected to:
+//   - import the tenant workflow bundle,
+//   - expose `POST /step` that accepts `{ workflowId, workflowVersion,
+//     stepId, attempt, input, envVars? }` and runs the step body,
+//   - return a `StepJournalEntry` JSON.
+//
+// The container entry point is a short adapter around
+// `@voyantjs/workflows/handler`'s `executeWorkflowStep` with the
+// workflow registry already loaded. See
+// `apps/workflows-node-step-container/` for the reference image.
+
+import type { StepJournalEntry } from "@voyantjs/workflows/handler";
+import type { StepRunner } from "@voyantjs/workflows/handler";
+
+/**
+ * Minimal subset of `DurableObjectNamespace` that the runner actually
+ * uses. Matches the shape exposed by `@cloudflare/containers`'
+ * `getContainer(namespace, id).fetch()` pattern — we keep it local so
+ * tests can pass a stub.
+ */
+export interface ContainerNamespaceLike {
+  idFromName(name: string): { toString(): string };
+  get(id: { toString(): string }): { fetch(request: Request): Promise<Response> };
+}
+
+export interface BundleLocation {
+  /**
+   * Short-lived signed URL the container uses to fetch the bundle
+   * from R2. Expected TTL is minutes, not hours — scoped tightly to
+   * the specific `<projectId>/<workflowVersion>/container.mjs` key.
+   */
+  url: string;
+  /**
+   * SHA-256 hex of the bundle bytes, computed at deploy time and
+   * stored alongside the bundle. The container verifies the
+   * downloaded bytes match this hash before importing — both as an
+   * integrity check and as a pin preventing stale-cache confusion.
+   * Accepts both plain hex and `sha256:<hex>` formats.
+   */
+  hash: string;
+}
+
+export interface CfContainerRunnerDeps {
+  /**
+   * DO namespace backing the Cloudflare Container class. Typically
+   * `env.NODE_STEP_POOL` wired in wrangler.jsonc to a `Container`-
+   * extending class (from `@cloudflare/containers`).
+   */
+  namespace: ContainerNamespaceLike;
+  /**
+   * Resolve a signed R2 URL + manifest hash for the bundle the
+   * container should import for this dispatch. Called on every
+   * invocation (cache in the resolver if URL minting is expensive).
+   *
+   * If omitted, the dispatch payload has no `bundle` field and the
+   * container must have its bundle baked into the image (via the
+   * `WORKFLOW_BUNDLE` env var). Multi-tenant production uses the
+   * resolver; single-tenant / dev images can skip it.
+   */
+  resolveBundle?: (args: {
+    runId: string;
+    workflowId: string;
+    workflowVersion: string;
+    projectId: string;
+    organizationId: string;
+  }) => Promise<BundleLocation> | BundleLocation;
+  /**
+   * Base URL presented to the container. The container's Worker
+   * proxy only inspects the path, so this is cosmetic — defaults to
+   * `https://node-step.voyant.internal`.
+   */
+  baseUrl?: string;
+  /**
+   * Optional HMAC signer for the `X-Voyant-Step-Auth` header so the
+   * container can verify the request came from a Voyant orchestrator.
+   * Shape matches `createHmacSigner` from `@voyantjs/workflows/auth`.
+   */
+  sign?: (body: string) => Promise<string> | string;
+  /** Optional structured logger. */
+  logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+  /**
+   * Build the container-addressing id for a given step invocation.
+   * Default: `"<runId>:<attempt>:<stepId>"` — deterministic and
+   * parallel-safe (distinct step invocations get distinct
+   * containers, so the CF addressing model isolates them).
+   */
+  containerId?: (args: {
+    runId: string;
+    workflowId: string;
+    workflowVersion: string;
+    stepId: string;
+    attempt: number;
+  }) => string;
+}
+
+interface StepDispatchPayload {
+  runId: string;
+  workflowId: string;
+  workflowVersion: string;
+  projectId: string;
+  organizationId: string;
+  stepId: string;
+  attempt: number;
+  input: unknown;
+  options: {
+    machine?: string;
+    timeout?: string | number;
+  };
+  /** Signed R2 URL + hash for the bundle to import. Absent when the
+   *  container is single-tenant (bundle baked into the image). */
+  bundle?: BundleLocation;
+  /**
+   * Journal slice at dispatch time. The container uses it to
+   * short-circuit already-completed steps on body replay and to stop
+   * the drive cleanly after the target step. Passed as opaque JSON
+   * here; the container knows how to consume it.
+   */
+  journal?: unknown;
+}
+
+/**
+ * Build a `StepRunner` that dispatches each step invocation to a
+ * Cloudflare Container in the given namespace.
+ *
+ * Wire this into the orchestrator's step handler:
+ *
+ *   createStepHandler({
+ *     nodeStepRunner: createCfContainerStepRunner({
+ *       namespace: env.NODE_STEP_POOL,
+ *     }),
+ *   });
+ *
+ * Steps that declare `runtime: "node"` will route through here;
+ * `runtime: "edge"` (or unset) continues to run inline.
+ */
+export function createCfContainerStepRunner(deps: CfContainerRunnerDeps): StepRunner {
+  const baseUrl = deps.baseUrl ?? "https://node-step.voyant.internal";
+  const idOf =
+    deps.containerId
+      ?? (({ runId, attempt, stepId }) => `${runId}:${attempt}:${stepId}`);
+
+  return async ({
+    stepId,
+    attempt,
+    input,
+    stepCtx,
+    runId,
+    workflowId,
+    workflowVersion,
+    projectId,
+    organizationId,
+    options,
+    journal,
+  }): Promise<StepJournalEntry> => {
+    const startedAt = Date.now();
+    let bundle: BundleLocation | undefined;
+    if (deps.resolveBundle) {
+      try {
+        bundle = await deps.resolveBundle({
+          runId,
+          workflowId,
+          workflowVersion,
+          projectId,
+          organizationId,
+        });
+      } catch (err) {
+        deps.logger?.("error", "cf-container: resolveBundle threw", {
+          runId,
+          stepId,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        return failed(attempt, startedAt, "BUNDLE_RESOLVE_FAILED", err);
+      }
+    }
+    const payload: StepDispatchPayload = {
+      runId,
+      workflowId,
+      workflowVersion,
+      projectId,
+      organizationId,
+      stepId,
+      attempt,
+      input,
+      options: {
+        machine: options.machine,
+        timeout:
+          typeof options.timeout === "string" || typeof options.timeout === "number"
+            ? (options.timeout as string | number)
+            : undefined,
+      },
+      bundle,
+      journal,
+    };
+    const body = JSON.stringify(payload);
+    const headers: Record<string, string> = {
+      "content-type": "application/json; charset=utf-8",
+    };
+    if (deps.sign) {
+      headers["x-voyant-step-auth"] = await deps.sign(body);
+    }
+
+    const id = deps.namespace.idFromName(
+      idOf({ runId, workflowId, workflowVersion, stepId, attempt }),
+    );
+    const stub = deps.namespace.get(id);
+    const request = new Request(`${baseUrl}/step`, {
+      method: "POST",
+      headers,
+      body,
+      signal: stepCtx.signal,
+    });
+
+    deps.logger?.("info", "cf-container: dispatching step", {
+      runId,
+      workflowId,
+      stepId,
+      attempt,
+    });
+
+    let response: Response;
+    try {
+      response = await stub.fetch(request);
+    } catch (err) {
+      deps.logger?.("error", "cf-container: fetch threw", {
+        runId,
+        stepId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return failed(attempt, startedAt, "CONTAINER_DISPATCH_FAILED", err);
+    }
+
+    const text = await response.text();
+    if (response.status !== 200) {
+      deps.logger?.("warn", "cf-container: non-200 response", {
+        runId,
+        stepId,
+        status: response.status,
+        body: text.slice(0, 500),
+      });
+      return failed(
+        attempt,
+        startedAt,
+        "CONTAINER_HTTP_ERROR",
+        new Error(`container returned HTTP ${response.status}: ${text}`),
+      );
+    }
+    try {
+      const entry = JSON.parse(text) as StepJournalEntry;
+      // Trust the container's own timestamps; they reflect the actual
+      // step body execution, not the dispatch round-trip.
+      return entry;
+    } catch (err) {
+      return failed(
+        attempt,
+        startedAt,
+        "CONTAINER_INVALID_RESPONSE",
+        new Error(`container returned non-JSON body: ${String(err)}`),
+      );
+    }
+  };
+}
+
+function failed(
+  attempt: number,
+  startedAt: number,
+  code: string,
+  err: unknown,
+): StepJournalEntry {
+  const e = err instanceof Error ? err : new Error(String(err));
+  return {
+    attempt,
+    status: "err",
+    startedAt,
+    finishedAt: Date.now(),
+    error: {
+      category: "RUNTIME_ERROR",
+      code,
+      message: e.message,
+      name: e.name,
+      stack: e.stack,
+    },
+  };
+}

package/src/dispatch-handler.ts

@@ -0,0 +1,53 @@
+// Builds a `StepHandler` (the thing the orchestrator calls on every
+// invocation) by routing the request through a Workers-for-Platforms
+// dispatch namespace to the tenant's bundled Worker.
+//
+// The tenant Worker is expected to mount `@voyantjs/workflows/handler`
+// at `POST /__voyant/workflow-step` (see docs/runtime-protocol.md §2.1).
+
+import {
+  createHttpStepHandler,
+  type StepHandler,
+  type WorkflowStepRequest,
+} from "@voyantjs/workflows-orchestrator";
+import type { DispatchNamespaceLike } from "./types.js";
+
+export interface DispatchHandlerDeps {
+  dispatcher: DispatchNamespaceLike;
+  /** Optional HMAC signer for the X-Voyant-Dispatch-Auth header. */
+  sign?: (body: string) => Promise<string> | string;
+  /** Optional logger for step-level observability. */
+  logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+  /** Base URL to present to the tenant. Defaults to `https://tenant.voyant.internal`. */
+  baseUrl?: string;
+}
+
+/**
+ * The dispatcher binding expects a name corresponding to the tenant
+ * script slot. `createDispatchStepHandler` binds the step handler to
+ * a specific tenant script; different tenants need different handlers
+ * (trivial via `createDispatchStepHandler(...)` with the script name
+ * resolved from the run's tenantMeta).
+ */
+export function createDispatchStepHandler(
+  tenantScript: string,
+  deps: DispatchHandlerDeps,
+): StepHandler {
+  const baseUrl = deps.baseUrl ?? "https://tenant.voyant.internal";
+  return createHttpStepHandler({
+    sign: deps.sign
+      ? (body) => deps.sign!(body)
+      : undefined,
+    logger: deps.logger,
+    resolveTarget(_req: WorkflowStepRequest) {
+      const binding = deps.dispatcher.get(tenantScript);
+      return {
+        url: `${baseUrl}/__voyant/workflow-step`,
+        label: tenantScript,
+        fetch(request: Request) {
+          return binding.fetch(request);
+        },
+      };
+    },
+  });
+}

package/src/do-store.ts

@@ -0,0 +1,39 @@
+// A RunRecordStore backed by `DurableObjectStorage`. In production
+// this is the DO's transactional KV; in tests, any
+// DurableObjectStorageLike (e.g. in-memory Map wrapper) works.
+//
+// Layout: one run record per DO. Stored under the fixed key
+// `record`. The adapter assumes one DO per runId, so "list" scans a
+// single key. If a caller wants multi-run listing they should go
+// through the global run index (lives in voyant-cloud's Postgres,
+// not here).
+
+import type { RunRecord, RunRecordStore } from "@voyantjs/workflows-orchestrator";
+import type { DurableObjectStorageLike } from "./types.js";
+
+const RECORD_KEY = "record";
+
+export function createDurableObjectRunStore(
+  storage: DurableObjectStorageLike,
+): RunRecordStore {
+  return {
+    async get(id) {
+      const r = await storage.get<RunRecord>(RECORD_KEY);
+      if (!r || r.id !== id) return undefined;
+      return r;
+    },
+
+    async save(record) {
+      await storage.put<RunRecord>(RECORD_KEY, record);
+      return record;
+    },
+
+    async list(filter = {}) {
+      const r = await storage.get<RunRecord>(RECORD_KEY);
+      if (!r) return [];
+      if (filter.workflowId && r.workflowId !== filter.workflowId) return [];
+      if (filter.status && r.status !== filter.status) return [];
+      return [r];
+    },
+  };
+}

package/src/durable-object.ts

@@ -0,0 +1,224 @@
+// The WorkflowRunDO — one Durable Object per run. Holds the
+// RunRecord in storage, drives the run through the tenant via a
+// dispatch-namespace StepHandler, exposes a tiny HTTP surface to
+// the outer Worker, and schedules DO alarms for DATETIME waitpoints
+// so `ctx.sleep(...)` wakes back up.
+//
+// Routes:
+//   POST /trigger      { ...TriggerPayload }        → RunRecord
+//   POST /resume       { injection }                → RunRecord | error
+//   POST /cancel       { reason? }                  → RunRecord | error
+//   GET  /get                                       → RunRecord | 404
+//
+// Alarm entry point: handleDurableObjectAlarm(deps). Fired by the CF
+// runtime at the wake time scheduled by setAlarm; resolves due
+// DATETIME waitpoints, re-drives, and reschedules if needed.
+//
+// Callers should treat the HTTP surface as an implementation detail;
+// the public surface is the outer Worker's /api/* routes.
+
+import {
+  applyWaitpointInjection,
+  cancel as orchestratorCancel,
+  driveUntilPaused,
+  resume as orchestratorResume,
+  trigger as orchestratorTrigger,
+  type PendingWaitpoint,
+  type RunRecord,
+  type StepHandler,
+} from "@voyantjs/workflows-orchestrator";
+import type {
+  CancelPayload,
+  DurableObjectStorageLike,
+  ResumePayload,
+  TriggerPayload,
+} from "./types.js";
+import { createDurableObjectRunStore } from "./do-store.js";
+
+export interface DurableObjectDeps {
+  storage: DurableObjectStorageLike;
+  /**
+   * Resolve the StepHandler to use for a given tenant script. Called
+   * with the tenantScript (from the trigger payload) so the DO can
+   * route to the correct tenant Worker. In production this closes
+   * over the dispatch namespace; in tests it returns a mock.
+   */
+  resolveStepHandler: (tenantScript: string) => StepHandler;
+  now?: () => number;
+}
+
+export async function handleDurableObjectRequest(
+  req: Request,
+  deps: DurableObjectDeps,
+): Promise<Response> {
+  const url = new URL(req.url);
+  const store = createDurableObjectRunStore(deps.storage);
+
+  if (req.method === "POST" && url.pathname === "/trigger") {
+    const payload = (await req.json()) as TriggerPayload;
+    const handler = deps.resolveStepHandler(payload.tenantMeta.tenantScript);
+    const record = await orchestratorTrigger(
+      {
+        workflowId: payload.workflowId,
+        workflowVersion: payload.workflowVersion,
+        input: payload.input,
+        tenantMeta: payload.tenantMeta,
+        environment: payload.environment,
+        tags: payload.tags,
+        runId: payload.runId,
+      },
+      { store, handler, now: deps.now },
+    );
+    await reconcileAlarm(record, store, deps);
+    return json(200, record);
+  }
+
+  if (req.method === "POST" && url.pathname === "/resume") {
+    const payload = (await req.json()) as ResumePayload;
+    const existing = await store.get((await getStoredRunId(store)) ?? "");
+    if (!existing) return json(404, { error: "not_found", message: "no run stored in this DO" });
+    const handler = deps.resolveStepHandler(existing.tenantMeta.tenantScript ?? "");
+    const out = await orchestratorResume(
+      { runId: existing.id, injection: payload.injection },
+      { store, handler, now: deps.now },
+    );
+    if (!out.ok) {
+      const status = out.status === "not_found" ? 404 : out.status === "no_match" ? 400 : 409;
+      return json(status, { error: out.status, message: out.message });
+    }
+    await reconcileAlarm(out.record, store, deps);
+    return json(200, out.record);
+  }
+
+  if (req.method === "POST" && url.pathname === "/cancel") {
+    const payload = (await req.json()) as CancelPayload;
+    const existing = await store.get((await getStoredRunId(store)) ?? "");
+    if (!existing) return json(404, { error: "not_found", message: "no run stored in this DO" });
+    const handler = deps.resolveStepHandler(existing.tenantMeta.tenantScript ?? "");
+    const out = await orchestratorCancel(
+      { runId: existing.id, reason: payload.reason },
+      { store, handler, now: deps.now },
+    );
+    if (!out.ok) {
+      const status = out.status === "not_found" ? 404 : 409;
+      return json(status, { error: out.status, message: out.message });
+    }
+    await reconcileAlarm(out.record, store, deps);
+    return json(200, out.record);
+  }
+
+  if (req.method === "GET" && url.pathname === "/get") {
+    const existing = await store.get((await getStoredRunId(store)) ?? "");
+    if (!existing) return json(404, { error: "not_found" });
+    return json(200, existing);
+  }
+
+  return json(404, { error: "route_not_found", path: url.pathname });
+}
+
+/**
+ * Fire this from your DO's `alarm()` method. Walks pending
+ * waitpoints, resolves every DATETIME whose `wakeAt` is <= now,
+ * re-drives the run, and reschedules the next alarm if the run
+ * parked on another DATETIME.
+ */
+export async function handleDurableObjectAlarm(
+  deps: DurableObjectDeps,
+): Promise<void> {
+  const store = createDurableObjectRunStore(deps.storage);
+  const existingId = await getStoredRunId(store);
+  if (!existingId) return;
+  const record = await store.get(existingId);
+  if (!record) return;
+  if (record.status !== "waiting") {
+    await deps.storage.deleteAlarm?.();
+    return;
+  }
+
+  const now = (deps.now ?? (() => Date.now()))();
+  const stillPending: PendingWaitpoint[] = [];
+  let resolvedAny = false;
+  for (const wp of record.pendingWaitpoints) {
+    const wakeAt = typeof wp.meta.wakeAt === "number" ? wp.meta.wakeAt : undefined;
+    if (wp.kind === "DATETIME" && wakeAt !== undefined && wakeAt <= now) {
+      record.journal.waitpointsResolved[wp.clientWaitpointId] = {
+        kind: "DATETIME",
+        resolvedAt: now,
+        source: "replay",
+      };
+      resolvedAny = true;
+    } else {
+      stillPending.push(wp);
+    }
+  }
+  record.pendingWaitpoints = stillPending;
+  if (!resolvedAny) {
+    // Spurious alarm — nothing due. Persist and reconcile.
+    await store.save(record);
+    await reconcileAlarm(record, store, deps);
+    return;
+  }
+
+  record.status = "running";
+  const handler = deps.resolveStepHandler(record.tenantMeta.tenantScript ?? "");
+  await driveUntilPaused(record, { handler, now: deps.now });
+  await store.save(record);
+  await reconcileAlarm(record, store, deps);
+}
+
+/**
+ * Look at the record's pending waitpoints; if any are DATETIME,
+ * stamp a `wakeAt` into meta (if not already set) and schedule the
+ * earliest via `setAlarm`. Clears any prior alarm when the run is
+ * terminal or has no DATETIME waitpoints left.
+ */
+async function reconcileAlarm(
+  record: RunRecord,
+  store: ReturnType<typeof createDurableObjectRunStore>,
+  deps: DurableObjectDeps,
+): Promise<void> {
+  const now = (deps.now ?? (() => Date.now()))();
+  if (record.status !== "waiting") {
+    await deps.storage.deleteAlarm?.();
+    return;
+  }
+  let earliest: number | undefined;
+  let dirty = false;
+  for (const wp of record.pendingWaitpoints) {
+    if (wp.kind !== "DATETIME") continue;
+    let wakeAt = typeof wp.meta.wakeAt === "number" ? wp.meta.wakeAt : undefined;
+    if (wakeAt === undefined) {
+      const ms = wp.timeoutMs ?? (typeof wp.meta.durationMs === "number" ? wp.meta.durationMs : 0);
+      wakeAt = now + ms;
+      wp.meta.wakeAt = wakeAt;
+      dirty = true;
+    }
+    earliest = earliest === undefined ? wakeAt : Math.min(earliest, wakeAt);
+  }
+  if (dirty) await store.save(record);
+  if (earliest !== undefined) {
+    await deps.storage.setAlarm?.(earliest);
+  } else {
+    await deps.storage.deleteAlarm?.();
+  }
+}
+
+/**
+ * One DO holds one run, keyed by `record`. Returns the id of that
+ * stored run, if any.
+ */
+async function getStoredRunId(store: ReturnType<typeof createDurableObjectRunStore>): Promise<string | undefined> {
+  const all = await store.list();
+  return all[0]?.id;
+}
+
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  });
+}
+
+// Re-exported for callers building their own DO class via composition.
+export { applyWaitpointInjection, driveUntilPaused };
+export type { RunRecord };

package/src/index.ts

@@ -0,0 +1,55 @@
+// @voyantjs/workflows-orchestrator-cloudflare
+//
+// Cloudflare Worker + Durable Object adapter for @voyantjs/workflows-orchestrator.
+// Composes the protocol-agnostic state machine in @voyantjs/workflows-orchestrator
+// with a DO-backed run store and a dispatch-namespace step handler.
+//
+// Typical wrangler.jsonc layout:
+//
+//   {
+//     "name": "voyant-orchestrator",
+//     "main": "src/worker.ts",
+//     "compatibility_date": "2025-01-01",
+//     "durable_objects": {
+//       "bindings": [
+//         { "name": "WORKFLOW_RUN_DO", "class_name": "WorkflowRunDO" }
+//       ]
+//     },
+//     "dispatch_namespaces": [
+//       { "binding": "DISPATCHER", "namespace": "voyant-tenants" }
+//     ],
+//     "migrations": [
+//       { "tag": "v1", "new_sqlite_classes": ["WorkflowRunDO"] }
+//     ]
+//   }
+//
+// See docs/runtime-protocol.md §2 and docs/design.md §6 for the
+// design this adapter implements.
+
+export * from "./types.js";
+export { createDurableObjectRunStore } from "./do-store.js";
+export {
+  createDispatchStepHandler,
+  type DispatchHandlerDeps,
+} from "./dispatch-handler.js";
+export {
+  handleDurableObjectRequest,
+  handleDurableObjectAlarm,
+  type DurableObjectDeps,
+} from "./durable-object.js";
+export {
+  handleWorkerRequest,
+  type WorkerFetchDeps,
+  type DurableObjectNamespaceLike,
+} from "./worker.js";
+export {
+  createCfContainerStepRunner,
+  type BundleLocation,
+  type CfContainerRunnerDeps,
+  type ContainerNamespaceLike,
+} from "./cf-container-runner.js";
+export {
+  createR2Presigner,
+  type R2PresignerOptions,
+  type PresignArgs,
+} from "./r2-sign.js";