@voyantjs/workflows-orchestrator-cloudflare 0.28.3 → 0.30.0

package/src/event-handler.ts

@@ -0,0 +1,302 @@
+// HTTP handler for `POST /api/events` — the synchronous event-ingest
+// endpoint. Loads the registered manifest from KV, runs the pure
+// `routeEvent` from `@voyantjs/workflows-orchestrator`, and forwards
+// each match into the existing `/trigger` DO surface with a derived
+// idempotencyKey.
+//
+// Response shape mirrors `IngestEventResponse` from
+// `@voyantjs/workflows/driver`:
+//
+//   { ok: true,  eventId, matches: [...] }
+//   { ok: false, reason: "manifest_not_registered" | ... }
+//
+// Architecture: docs/architecture/workflows-runtime-architecture.md §15.
+
+import { deriveStableEventId } from "@voyantjs/workflows/events"
+import type { WorkflowManifest } from "@voyantjs/workflows/protocol"
+import { routeEvent } from "@voyantjs/workflows-orchestrator"
+
+import type { CfManifestStore } from "./manifest-kv-store.js"
+import type { DurableObjectNamespaceLike } from "./worker.js"
+
+const ALLOWED_ENVS = new Set(["production", "preview", "development"])
+
+export interface EventHandlerDeps<Id = unknown> {
+  /** KV-backed manifest store (read-only path here). */
+  manifestStore: CfManifestStore
+  /** DO namespace used to forward each match to the run DO. */
+  runDO: DurableObjectNamespaceLike<Id>
+  /** id generator for new triggers; defaults to `run_<random>`. */
+  idGenerator?: () => string
+  /** Injectable clock. */
+  now?: () => number
+  /** Tenant metadata stamped on every triggered run. */
+  tenantMeta?: {
+    tenantId: string
+    projectId: string
+    organizationId: string
+    tenantScript?: string
+  }
+  /** Optional logger. */
+  logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void
+}
+
+const DEFAULT_TENANT_META = {
+  tenantId: "default",
+  projectId: "default",
+  organizationId: "default",
+}
+
+interface IngestEnvelope {
+  name: string
+  data: unknown
+  metadata?: Record<string, unknown> & { eventId?: string }
+  emittedAt: string
+}
+
+interface IngestRequestBody {
+  environment: string
+  envelope: IngestEnvelope
+  idempotencyKey?: string
+}
+
+export async function handleIngestEvent<Id>(
+  req: Request,
+  deps: EventHandlerDeps<Id>,
+): Promise<Response> {
+  // Body parse + validate.
+  let raw: unknown
+  try {
+    raw = await req.json()
+  } catch (err) {
+    return json(400, {
+      error: "invalid_json",
+      message: err instanceof Error ? err.message : String(err),
+    })
+  }
+  const validation = validateBody(raw)
+  if (!validation.ok) return json(400, validation.error)
+  const body = validation.body
+
+  // Manifest lookup.
+  const manifestEnvelope = await deps.manifestStore.getCurrent(body.environment)
+  if (!manifestEnvelope) {
+    return json(200, {
+      ok: false,
+      reason: "manifest_not_registered",
+      message: `No manifest is registered for environment "${body.environment}".`,
+    })
+  }
+  const manifest = manifestEnvelope.manifest as unknown as WorkflowManifest
+
+  // Event id derivation — use the caller-stamped one when present, fall
+  // back to a content-derived id so external callers without a forwarder
+  // still get sensible idempotency.
+  const eventId = body.envelope.metadata?.eventId ?? (await deriveStableEventId(body.envelope))
+
+  // Route through the manifest's filters.
+  const routed = routeEvent({
+    manifest,
+    envelope: {
+      name: body.envelope.name,
+      data: body.envelope.data,
+      metadata: body.envelope.metadata,
+      emittedAt: body.envelope.emittedAt,
+    },
+    eventId,
+    idempotencyOverride: body.idempotencyKey,
+  })
+
+  // Forward each match into the existing /trigger DO route.
+  const matches: unknown[] = []
+  let anyTriggered = false
+  let anyFailed = false
+  const tenantMeta = deps.tenantMeta ?? DEFAULT_TENANT_META
+
+  for (const entry of routed) {
+    if (entry.status === "skipped") {
+      matches.push({
+        filterId: entry.filterId,
+        status: "skipped",
+        reason: entry.reason,
+        details: entry.details,
+      })
+      continue
+    }
+
+    const runId = `idem-${entry.targetWorkflowId}-${entry.idempotencyKey}`
+    const triggerPayload = {
+      runId,
+      workflowId: entry.targetWorkflowId,
+      workflowVersion: "v1",
+      input: entry.input,
+      tenantMeta,
+      environment: body.environment,
+      idempotencyKey: entry.idempotencyKey,
+      triggeredBy: {
+        kind: "event" as const,
+        eventId,
+        eventType: body.envelope.name,
+        filterId: entry.filterId,
+      },
+    }
+
+    try {
+      const forward = new Request("https://do-internal/trigger", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(triggerPayload),
+      })
+      const id = deps.runDO.idFromName(runId)
+      const stub = deps.runDO.get(id)
+      const resp = await stub.fetch(forward)
+      if (resp.status >= 200 && resp.status < 300) {
+        matches.push({
+          filterId: entry.filterId,
+          targetWorkflowId: entry.targetWorkflowId,
+          runId,
+          idempotencyKey: entry.idempotencyKey,
+          status: "queued",
+        })
+        anyTriggered = true
+      } else {
+        const errBody = await safeReadText(resp)
+        deps.logger?.("error", "trigger DO failed", {
+          status: resp.status,
+          body: errBody.slice(0, 256),
+        })
+        matches.push({
+          filterId: entry.filterId,
+          targetWorkflowId: entry.targetWorkflowId,
+          status: "error",
+          reason: `do_returned_${resp.status}`,
+        })
+        anyFailed = true
+      }
+    } catch (err) {
+      deps.logger?.("error", "trigger forward threw", {
+        error: err instanceof Error ? err.message : String(err),
+      })
+      matches.push({
+        filterId: entry.filterId,
+        targetWorkflowId: entry.targetWorkflowId,
+        status: "error",
+        reason: err instanceof Error ? err.message : String(err),
+      })
+      anyFailed = true
+    }
+  }
+
+  if (matches.length > 0 && !anyTriggered && anyFailed) {
+    return json(502, {
+      ok: false,
+      reason: "trigger_failed_for_all_matches",
+      message: "every matched filter failed to trigger",
+    })
+  }
+
+  return json(200, { ok: true, eventId, matches })
+}
+
+// ---- Validation ----
+
+function validateBody(
+  raw: unknown,
+):
+  | { ok: true; body: IngestRequestBody }
+  | { ok: false; error: { error: string; message: string } } {
+  if (typeof raw !== "object" || raw === null) {
+    return { ok: false, error: { error: "invalid_body", message: "expected JSON object" } }
+  }
+  const r = raw as Record<string, unknown>
+
+  if (typeof r.environment !== "string" || !ALLOWED_ENVS.has(r.environment)) {
+    return {
+      ok: false,
+      error: {
+        error: "invalid_body",
+        message: `"environment" must be one of ${[...ALLOWED_ENVS].join(", ")}`,
+      },
+    }
+  }
+  if (typeof r.envelope !== "object" || r.envelope === null) {
+    return {
+      ok: false,
+      error: { error: "invalid_body", message: '"envelope" must be an object' },
+    }
+  }
+  const envelope = r.envelope as Record<string, unknown>
+  if (typeof envelope.name !== "string" || envelope.name.length === 0) {
+    return {
+      ok: false,
+      error: { error: "invalid_body", message: '"envelope.name" must be a non-empty string' },
+    }
+  }
+  if (typeof envelope.emittedAt !== "string" || envelope.emittedAt.length === 0) {
+    return {
+      ok: false,
+      error: {
+        error: "invalid_body",
+        message: '"envelope.emittedAt" must be an ISO timestamp string',
+      },
+    }
+  }
+  if (
+    envelope.metadata !== undefined &&
+    (typeof envelope.metadata !== "object" || envelope.metadata === null)
+  ) {
+    return {
+      ok: false,
+      error: {
+        error: "invalid_body",
+        message: '"envelope.metadata" must be an object when supplied',
+      },
+    }
+  }
+  if (r.idempotencyKey !== undefined && typeof r.idempotencyKey !== "string") {
+    return {
+      ok: false,
+      error: { error: "invalid_body", message: '"idempotencyKey" must be a string when supplied' },
+    }
+  }
+  return {
+    ok: true,
+    body: {
+      environment: r.environment,
+      envelope: {
+        name: envelope.name,
+        data: envelope.data,
+        metadata: envelope.metadata as Record<string, unknown> | undefined,
+        emittedAt: envelope.emittedAt,
+      },
+      idempotencyKey: r.idempotencyKey as string | undefined,
+    },
+  }
+}
+
+// ---- Internal helpers ----
+
+// Fallback id derivation lives in `@voyantjs/workflows/events`'s
+// `deriveStableEventId` and is used inline above — content-derived so
+// external callers (HTTP retries, third-party webhooks) dedupe naturally
+// across re-deliveries (architecture doc §15.2).
+
+async function safeReadText(resp: Response): Promise<string> {
+  try {
+    return await resp.text()
+  } catch {
+    return ""
+  }
+}
+
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "access-control-allow-origin": "*",
+      "access-control-allow-methods": "GET,POST,OPTIONS",
+      "access-control-allow-headers": "content-type, x-voyant-protocol",
+    },
+  })
+}

package/src/index.ts

@@ -1,8 +1,8 @@
 // @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.
+// Composes the protocol-agnostic state machine with a DO-backed run
+// store and a pluggable step dispatcher (`StepDispatcher`).
 //
 // Typical wrangler.jsonc layout:
 //
@@ -15,14 +15,20 @@
 //         { "name": "WORKFLOW_RUN_DO", "class_name": "WorkflowRunDO" }
 //       ]
 //     },
-//     "dispatch_namespaces": [
-//       { "binding": "DISPATCHER", "namespace": "voyant-tenants" }
-//     ],
 //     "migrations": [
 //       { "tag": "v1", "new_sqlite_classes": ["WorkflowRunDO"] }
 //     ]
 //   }
 //
+// Pick a dispatcher in your DO's `deps()` based on where workflow
+// code lives:
+//   * createInlineDispatcher          — same Worker as the orchestrator
+//   * createServiceBindingDispatcher  — sibling Worker via service binding
+//   * createHttpDispatcher            — arbitrary HTTP endpoint
+//
+// Hosted multi-tenant providers implement custom dispatchers in their
+// own deployment code.
+//
 // See docs/runtime-protocol.md §2 and docs/design.md §6 for the
 // design this adapter implements.
 
@@ -33,15 +39,33 @@ export {
   createCfContainerStepRunner,
 } from "./cf-container-runner.js"
 export {
-  createDispatchStepHandler,
-  type DispatchHandlerDeps,
-} from "./dispatch-handler.js"
+  type CloudflareEdgeDriverOptions,
+  createCloudflareEdgeDriver,
+} from "./cloudflare-edge-driver.js"
+export {
+  createHttpDispatcher,
+  createInlineDispatcher,
+  createServiceBindingDispatcher,
+  type HttpDispatcherOptions,
+  type ServiceBindingDispatcherOptions,
+  type ServiceBindingLike,
+  type StepDispatcher,
+  type StepDispatcherContext,
+} from "./dispatchers.js"
 export { createDurableObjectRunStore } from "./do-store.js"
 export {
   type DurableObjectDeps,
   handleDurableObjectAlarm,
   handleDurableObjectRequest,
 } from "./durable-object.js"
+export {
+  type CfManifestEnvelope,
+  type CfManifestStore,
+  type CreateKvManifestStoreOptions,
+  createInMemoryKv,
+  createKvManifestStore,
+  type KvNamespaceLike,
+} from "./manifest-kv-store.js"
 export {
   createR2Presigner,
   type PresignArgs,

package/src/manifest-handler.ts

@@ -0,0 +1,113 @@
+// HTTP handlers for `/api/manifests*`. Mounted by the worker before the
+// existing `/api/runs/*` routes; both share the same auth.
+//
+//   POST /api/manifests              { environment, manifest } → { ok, versionId }
+//   GET  /api/manifests/:env                                   → manifest | 404
+//
+// Architecture: docs/architecture/workflows-runtime-architecture.md §8.2.
+
+import type { CfManifestStore } from "./manifest-kv-store.js"
+
+const ALLOWED_ENVS = new Set(["production", "preview", "development"])
+
+export interface ManifestHandlerDeps {
+  manifestStore: CfManifestStore
+  logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void
+}
+
+/**
+ * Handle `POST /api/manifests`. Body: `{ environment, manifest }`.
+ * `manifest.versionId` is the registered key. Returns `{ ok: true, versionId }`.
+ */
+export async function handleRegisterManifest(
+  req: Request,
+  deps: ManifestHandlerDeps,
+): Promise<Response> {
+  let body: unknown
+  try {
+    body = await req.json()
+  } catch (err) {
+    return json(400, {
+      error: "invalid_json",
+      message: err instanceof Error ? err.message : String(err),
+    })
+  }
+  if (typeof body !== "object" || body === null) {
+    return json(400, { error: "invalid_body", message: "expected JSON object" })
+  }
+
+  const { environment, manifest } = body as {
+    environment?: unknown
+    manifest?: unknown
+  }
+  if (typeof environment !== "string" || !ALLOWED_ENVS.has(environment)) {
+    return json(400, {
+      error: "invalid_body",
+      message: `"environment" must be one of ${[...ALLOWED_ENVS].join(", ")}`,
+    })
+  }
+  if (typeof manifest !== "object" || manifest === null) {
+    return json(400, { error: "invalid_body", message: '"manifest" must be an object' })
+  }
+  const versionId = (manifest as { versionId?: unknown }).versionId
+  if (typeof versionId !== "string" || versionId.length === 0) {
+    return json(400, {
+      error: "invalid_body",
+      message: '"manifest.versionId" must be a non-empty string',
+    })
+  }
+
+  try {
+    const result = await deps.manifestStore.registerManifest({
+      environment,
+      versionId,
+      manifest: manifest as Record<string, unknown>,
+    })
+    return json(200, { ok: true, versionId: result.versionId })
+  } catch (err) {
+    deps.logger?.("error", "manifest registration failed", {
+      environment,
+      versionId,
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return json(500, {
+      error: "register_failed",
+      message: err instanceof Error ? err.message : String(err),
+    })
+  }
+}
+
+/**
+ * Handle `GET /api/manifests/:env`. Returns the current manifest envelope
+ * or 404 if no manifest is registered.
+ */
+export async function handleGetManifest(
+  environment: string,
+  deps: ManifestHandlerDeps,
+): Promise<Response> {
+  if (!ALLOWED_ENVS.has(environment)) {
+    return json(400, {
+      error: "invalid_environment",
+      message: `environment must be one of ${[...ALLOWED_ENVS].join(", ")}`,
+    })
+  }
+  const envelope = await deps.manifestStore.getCurrent(environment)
+  if (!envelope) {
+    return json(404, { error: "not_found", environment })
+  }
+  return json(200, envelope)
+}
+
+// ---- Internal ----
+
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "access-control-allow-origin": "*",
+      "access-control-allow-methods": "GET,POST,OPTIONS",
+      "access-control-allow-headers": "content-type, x-voyant-protocol",
+    },
+  })
+}

package/src/manifest-kv-store.ts

@@ -0,0 +1,186 @@
+// KV-backed manifest store for the Cloudflare orchestrator.
+//
+// Mirrors the Mode 2 ManifestStore contract from
+// `@voyantjs/workflows-orchestrator-node`'s `createPostgresManifestStore`,
+// just against KV instead of Postgres. Both are consumed by their
+// respective driver factories — the orchestrator's `WorkflowDriver`
+// shape is identical.
+//
+// Layout in KV:
+//
+//   manifest:<environment>:<versionId>      → JSON-serialized manifest
+//   manifest:<environment>:current          → versionId of the active manifest
+//
+// Idempotent: same `(environment, versionId)` overwrite is fine.
+// Latest N versions retained via `pruneToVersions(env, n)`. KV is
+// eventually consistent (~60s globally), which is acceptable for the
+// manifest read path (manifests change at deploy boundaries, not per
+// event).
+
+// ---- Public types ----
+
+/**
+ * Structural view of a `WorkflowManifest` envelope. Mirrors the shape
+ * `@voyantjs/workflows-orchestrator-node`'s manifest store uses, declared
+ * locally so this package stays free of the Mode 2 dep.
+ */
+export interface CfManifestEnvelope {
+  environment: string
+  versionId: string
+  manifest: Record<string, unknown>
+}
+
+export interface CfManifestStore {
+  registerManifest(envelope: CfManifestEnvelope): Promise<{ versionId: string }>
+  getCurrent(environment: string): Promise<CfManifestEnvelope | null>
+  pruneToVersions(environment: string, keep: number): Promise<{ deleted: number }>
+}
+
+/**
+ * Subset of the CF KV namespace API we need. Declared structurally so
+ * tests can pass an in-memory fake without depending on
+ * `@cloudflare/workers-types`.
+ */
+export interface KvNamespaceLike {
+  get(key: string): Promise<string | null>
+  put(key: string, value: string, opts?: { metadata?: unknown }): Promise<void>
+  delete(key: string): Promise<void>
+  list(opts?: { prefix?: string; limit?: number; cursor?: string }): Promise<{
+    keys: Array<{ name: string; metadata?: unknown }>
+    list_complete?: boolean
+    cursor?: string
+  }>
+}
+
+export interface CreateKvManifestStoreOptions {
+  /** KV namespace binding from the worker's env. */
+  kv: KvNamespaceLike
+}
+
+// ---- Public factory ----
+
+/**
+ * Build a KV-backed `CfManifestStore`. Stateless — every call hits KV.
+ */
+export function createKvManifestStore(opts: CreateKvManifestStoreOptions): CfManifestStore {
+  const kv = opts.kv
+
+  return {
+    async registerManifest(envelope) {
+      const versionKey = manifestVersionKey(envelope.environment, envelope.versionId)
+      const currentKey = manifestCurrentKey(envelope.environment)
+
+      // Idempotent overwrite — same body produces the same byte content
+      // because manifests are content-addressed (versionId derives from
+      // a sha256 of the canonicalized manifest in the SDK).
+      await kv.put(versionKey, JSON.stringify(envelope.manifest))
+      await kv.put(currentKey, envelope.versionId)
+
+      return { versionId: envelope.versionId }
+    },
+
+    async getCurrent(environment) {
+      const currentKey = manifestCurrentKey(environment)
+      const versionId = await kv.get(currentKey)
+      if (!versionId) return null
+
+      const versionKey = manifestVersionKey(environment, versionId)
+      const raw = await kv.get(versionKey)
+      if (!raw) return null
+
+      let parsed: Record<string, unknown>
+      try {
+        parsed = JSON.parse(raw) as Record<string, unknown>
+      } catch {
+        return null
+      }
+      return {
+        environment,
+        versionId,
+        manifest: parsed,
+      }
+    },
+
+    async pruneToVersions(environment, keep) {
+      if (keep < 1) {
+        throw new Error(`pruneToVersions: keep must be >= 1, got ${keep}`)
+      }
+      // List every version key for this environment; sort so we can drop
+      // older entries. Lexicographic sort is fine because the SDK's
+      // versionId is a hex string of the same length, and KV's natural
+      // order is also lexicographic. For deterministic semantics we
+      // additionally fetch the `current` pointer and always keep that.
+      const prefix = `manifest:${environment}:`
+      const list = await kv.list({ prefix, limit: 1000 })
+      const versionKeys = list.keys.map((k) => k.name).filter((name) => !name.endsWith(":current"))
+
+      // Sort newest-first (lexicographic descending).
+      versionKeys.sort((a, b) => (a < b ? 1 : a > b ? -1 : 0))
+
+      const currentVersion = await kv.get(manifestCurrentKey(environment))
+      const currentKey = currentVersion
+        ? manifestVersionKey(environment, currentVersion)
+        : undefined
+
+      const keepers = new Set<string>()
+      if (currentKey) keepers.add(currentKey)
+      for (const k of versionKeys) {
+        if (keepers.size >= keep) break
+        keepers.add(k)
+      }
+
+      let deleted = 0
+      for (const k of versionKeys) {
+        if (keepers.has(k)) continue
+        await kv.delete(k)
+        deleted++
+      }
+      return { deleted }
+    },
+  }
+}
+
+// ---- Key helpers ----
+
+function manifestVersionKey(environment: string, versionId: string): string {
+  return `manifest:${environment}:${versionId}`
+}
+
+function manifestCurrentKey(environment: string): string {
+  return `manifest:${environment}:current`
+}
+
+// ---- In-memory KV fake (test-only) ----
+
+/**
+ * Tiny in-memory implementation of `KvNamespaceLike` for tests + the CF
+ * compliance suite run that doesn't go through wrangler. Mirrors the
+ * subset of CF KV semantics we use (list returns matching prefix in
+ * lexicographic order; get returns null for missing keys).
+ */
+export function createInMemoryKv(): KvNamespaceLike {
+  const map = new Map<string, string>()
+  return {
+    async get(key) {
+      return map.has(key) ? (map.get(key) as string) : null
+    },
+    async put(key, value) {
+      map.set(key, value)
+    },
+    async delete(key) {
+      map.delete(key)
+    },
+    async list(opts) {
+      const prefix = opts?.prefix ?? ""
+      const limit = opts?.limit ?? 1000
+      const matching = [...map.keys()]
+        .filter((k) => k.startsWith(prefix))
+        .sort()
+        .slice(0, limit)
+      return {
+        keys: matching.map((name) => ({ name })),
+        list_complete: true,
+      }
+    },
+  }
+}