@voyantjs/workflows 0.28.3 → 0.29.0

package/src/http-ingest.ts

@@ -0,0 +1,299 @@
+// Optional HTTP ingest adapter — mounts `/api/manifests` and `/api/events`
+// on a Hono-shaped app, forwarding into a `WorkflowDriver`.
+//
+// Self-host Mode 2 deployments mount this when external emitters need to
+// fire events into the runtime (storefront BFF, third-party webhooks,
+// sibling-process pairs across machines). voyant-cloud always mounts it
+// at its HTTP boundary.
+//
+// Transport-agnostic: takes a minimal `HttpAppLike` interface so the SDK
+// stays a leaf package (no `hono` dep). `@voyantjs/voyant-hono`'s `Hono`
+// instance satisfies the shape via TypeScript structural compat.
+//
+// Architecture: docs/architecture/workflows-runtime-architecture.md §15.4.
+
+import type { IngestEventArgs, WorkflowDriver } from "./driver.js"
+import type { EnvironmentName } from "./types.js"
+
+const ALLOWED_ENVS = new Set<EnvironmentName>(["production", "preview", "development"])
+
+// ---- Public types ----
+
+/**
+ * Minimum interface a Hono-shaped app exposes that we use. `app.post(...)`
+ * and `app.get(...)` register handlers; the handler signature mirrors
+ * Hono's `Context`-style callback for portability — we only read the
+ * request body and request params via the framework's response helpers.
+ */
+export interface HttpAppLike {
+  post(path: string, handler: HttpHandler): unknown
+  get(path: string, handler: HttpHandler): unknown
+}
+
+/**
+ * Minimum context shape we read off Hono. Restricted to body parsing,
+ * route params, and JSON response helpers.
+ */
+export interface HttpContextLike {
+  req: {
+    json(): Promise<unknown>
+    param(name: string): string | undefined
+    header(name: string): string | undefined
+    raw: Request
+  }
+  json(body: unknown, status?: number): Response
+  text(body: string, status?: number): Response
+  status(code: number): unknown
+}
+
+export type HttpHandler = (ctx: HttpContextLike) => Promise<Response> | Response
+
+export interface MountHttpIngestAdapterOptions {
+  /**
+   * Driver the adapter forwards into. Typically the same instance
+   * `createApp({ workflows: { driver } })` constructed.
+   */
+  driver: WorkflowDriver
+  /** Mount path. Defaults to `"/api/workflows"`. */
+  basePath?: string
+  /**
+   * Optional auth check. Receives the original `Request` and returns
+   * `void` on success / throws on failure. Reuse
+   * `createBearerVerifier(...)` from `@voyantjs/workflows/auth` for the
+   * canonical bearer-token shape.
+   */
+  verifyRequest?: (req: Request) => void | Promise<void>
+}
+
+// ---- Mount ----
+
+/**
+ * Mount the adapter onto a Hono-shaped app. Registers:
+ *
+ *   POST {basePath}/events                         → driver.ingestEvent
+ *   POST {basePath}/manifests                      → driver.registerManifest
+ *   GET  {basePath}/manifests/:env                 → driver.getManifest
+ *
+ * Returns the mounted base path so callers can log it.
+ */
+export function mountHttpIngestAdapter(
+  app: HttpAppLike,
+  opts: MountHttpIngestAdapterOptions,
+): string {
+  const base = (opts.basePath ?? "/api/workflows").replace(/\/$/, "")
+
+  app.post(`${base}/events`, async (ctx) => {
+    if (opts.verifyRequest) {
+      try {
+        await opts.verifyRequest(ctx.req.raw)
+      } catch (err) {
+        return ctx.json({ error: "unauthorized", message: errMessage(err) }, 401)
+      }
+    }
+
+    let raw: unknown
+    try {
+      raw = await ctx.req.json()
+    } catch (err) {
+      return ctx.json({ error: "invalid_json", message: errMessage(err) }, 400)
+    }
+    const validation = validateIngestBody(raw)
+    if (!validation.ok) return ctx.json(validation.error, 400)
+
+    const args: IngestEventArgs = {
+      environment: validation.body.environment,
+      envelope: validation.body.envelope,
+      idempotencyKey: validation.body.idempotencyKey,
+    }
+    const result = await opts.driver.ingestEvent(args)
+    if (!result.ok && result.reason === "manifest_not_registered") {
+      return ctx.json(result, 200)
+    }
+    if (!result.ok) {
+      return ctx.json(result, 502)
+    }
+    return ctx.json(result, 200)
+  })
+
+  app.post(`${base}/manifests`, async (ctx) => {
+    if (opts.verifyRequest) {
+      try {
+        await opts.verifyRequest(ctx.req.raw)
+      } catch (err) {
+        return ctx.json({ error: "unauthorized", message: errMessage(err) }, 401)
+      }
+    }
+    let raw: unknown
+    try {
+      raw = await ctx.req.json()
+    } catch (err) {
+      return ctx.json({ error: "invalid_json", message: errMessage(err) }, 400)
+    }
+    const validation = validateRegisterBody(raw)
+    if (!validation.ok) return ctx.json(validation.error, 400)
+    try {
+      const result = await opts.driver.registerManifest({
+        environment: validation.body.environment,
+        manifest: validation.body.manifest as never, // structurally compatible
+      })
+      return ctx.json({ ok: true, versionId: result.versionId }, 200)
+    } catch (err) {
+      return ctx.json({ error: "register_failed", message: errMessage(err) }, 500)
+    }
+  })
+
+  app.get(`${base}/manifests/:env`, async (ctx) => {
+    if (opts.verifyRequest) {
+      try {
+        await opts.verifyRequest(ctx.req.raw)
+      } catch (err) {
+        return ctx.json({ error: "unauthorized", message: errMessage(err) }, 401)
+      }
+    }
+    const env = ctx.req.param("env")
+    if (!env || !ALLOWED_ENVS.has(env as EnvironmentName)) {
+      return ctx.json(
+        {
+          error: "invalid_environment",
+          message: `environment must be one of ${[...ALLOWED_ENVS].join(", ")}`,
+        },
+        400,
+      )
+    }
+    const manifest = await opts.driver.getManifest({ environment: env as EnvironmentName })
+    if (!manifest) {
+      return ctx.json({ error: "not_found", environment: env }, 404)
+    }
+    return ctx.json({ environment: env, versionId: manifest.versionId, manifest }, 200)
+  })
+
+  return base
+}
+
+// ---- Validation ----
+
+interface IngestBody {
+  environment: EnvironmentName
+  envelope: {
+    name: string
+    data: unknown
+    metadata?: Record<string, unknown> & { eventId?: string }
+    emittedAt: string
+  }
+  idempotencyKey?: string
+}
+
+function validateIngestBody(
+  raw: unknown,
+): { ok: true; body: IngestBody } | { 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 as EnvironmentName)) {
+    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 as EnvironmentName,
+      envelope: {
+        name: envelope.name,
+        data: envelope.data,
+        metadata: envelope.metadata as Record<string, unknown> | undefined,
+        emittedAt: envelope.emittedAt,
+      },
+      idempotencyKey: r.idempotencyKey as string | undefined,
+    },
+  }
+}
+
+interface RegisterBody {
+  environment: EnvironmentName
+  manifest: Record<string, unknown> & { versionId: string }
+}
+
+function validateRegisterBody(
+  raw: unknown,
+): { ok: true; body: RegisterBody } | { 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 as EnvironmentName)) {
+    return {
+      ok: false,
+      error: {
+        error: "invalid_body",
+        message: `"environment" must be one of ${[...ALLOWED_ENVS].join(", ")}`,
+      },
+    }
+  }
+  if (typeof r.manifest !== "object" || r.manifest === null) {
+    return { ok: false, error: { error: "invalid_body", message: '"manifest" must be an object' } }
+  }
+  const manifest = r.manifest as Record<string, unknown>
+  if (typeof manifest.versionId !== "string" || manifest.versionId.length === 0) {
+    return {
+      ok: false,
+      error: {
+        error: "invalid_body",
+        message: '"manifest.versionId" must be a non-empty string',
+      },
+    }
+  }
+  return {
+    ok: true,
+    body: {
+      environment: r.environment as EnvironmentName,
+      manifest: manifest as Record<string, unknown> & { versionId: string },
+    },
+  }
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/protocol/index.ts

@@ -83,11 +83,26 @@ export interface ManifestSchedule {
 }
 
 export interface EventFilterManifestEntry {
+  /** Stable id derived from `payloadHash` of the canonicalized declaration. */
   id: string
+  /** Event name the filter targets — matches `EventEnvelope.name`. */
   eventType: string
-  scope?: string
-  matchExpression?: string
+  /**
+   * Optional structured `where` predicate. When absent, every event of the
+   * matching `eventType` fires the target workflow. Concrete shape lives in
+   * `@voyantjs/workflows/events` (`PredicateExpr`); the protocol declares
+   * it as an opaque object so old orchestrators that don't understand the
+   * shape don't have to evaluate it.
+   */
+  where?: unknown
+  /**
+   * Optional input mapper. When absent, the workflow input = `envelope.data`.
+   * Concrete shape lives in `@voyantjs/workflows/events` (`InputMapper`).
+   */
+  input?: unknown
+  /** Content-derived hash of the canonicalized declaration. */
   payloadHash: string
+  /** Workflow id this filter triggers. */
   targetWorkflowId: string
 }
 

package/src/runtime/ctx.ts

@@ -3,6 +3,7 @@
 // The executor owns the waitpoint-pending queue and the callbacks
 // into the orchestrator; ctx is a thin shell that delegates.
 
+import type { ServiceResolver } from "../driver.js"
 import type { SerializedError } from "../protocol/index.js"
 import type { Duration, RetryPolicy, WaitpointKind } from "../types.js"
 import type {
@@ -132,10 +133,37 @@ export interface CtxBuildArgs {
   random: () => number
   /** Mutated as ctx.setRetry is called; each step option inherits. */
   retryOverride: { current: RetryPolicy | undefined }
+  /**
+   * Read-only service resolver exposed as `ctx.services`. When unset,
+   * `ctx.services.resolve(...)` throws with a clear message — workflows
+   * that don't need shared services keep working without configuration.
+   * Wired by the framework through `StepHandlerDeps.services` →
+   * `ExecuteWorkflowStepRequest.services` → here.
+   */
+  services?: ServiceResolver
+}
+
+/**
+ * Default resolver used when no container is plumbed through. Throws on
+ * `resolve(...)` so failures are visible at the call site instead of
+ * returning undefined; `has(...)` returns `false` so optional-dep
+ * patterns work cleanly.
+ */
+const NO_OP_SERVICE_RESOLVER: ServiceResolver = {
+  resolve<T>(name: string): T {
+    throw new Error(
+      `ctx.services.resolve("${name}"): no service container is wired into this workflow runtime. ` +
+        `Pass { services } to the driver factory (e.g. via createApp({ workflows: { driver } }))`,
+    )
+  },
+  has() {
+    return false
+  },
 }
 
 export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
   const { env, journal, callbacks, clock, random, retryOverride } = args
+  const services = args.services ?? NO_OP_SERVICE_RESOLVER
 
   // Per-ctx client-id counter. Reset on each ctx (= each invocation),
   // which means ids are stable relative to body execution order.
@@ -694,6 +722,7 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
     organization: env.organization,
     invocationCount: callbacks.invocationCount,
     signal: callbacks.abortSignal,
+    services,
     step,
     sleep,
     waitForEvent,

package/src/runtime/executor.ts

@@ -132,6 +132,13 @@ export interface ExecuteWorkflowStepRequest {
    * array so the at-end delivery keeps working.
    */
   onStreamChunk?: (chunk: StreamChunk) => void
+  /**
+   * Optional read-only service resolver, surfaced to the workflow body as
+   * `ctx.services`. Wired by the framework through
+   * `StepHandlerDeps.services` → here. When unset, `ctx.services.resolve(...)`
+   * throws with a clear message — see `runtime/ctx.ts`.
+   */
+  services?: import("../driver.js").ServiceResolver
 }
 
 export type ExecuteWorkflowStepResponse =
@@ -285,6 +292,7 @@ export async function executeWorkflowStep(
     clock,
     random,
     retryOverride,
+    services: req.services,
   })
 
   try {

package/src/trigger.ts

@@ -2,7 +2,7 @@
 // Authoritative contract in docs/sdk-surface.md §6.
 
 import type { Duration, EnvironmentName, RunStatus } from "./types.js"
-import type { EnvironmentContext, WorkflowHandle } from "./workflow.js"
+import type { WorkflowHandle } from "./workflow.js"
 
 // ---- workflows.* ----
 
@@ -112,28 +112,44 @@ export const workflows: WorkflowsClient = new Proxy({} as WorkflowsClient, {
 
 // ---- trigger.on ----
 
-export interface EventFilterHandle {
-  readonly id: string
-  readonly event: string
-}
+import { compileAndRegister } from "./events/compile.js"
+import type { InputMapper } from "./events/input-mapper.js"
+import type { PredicateExpr } from "./events/predicate.js"
+import type { EventFilterRuntimeEntry } from "./events/registry.js"
 
+/**
+ * Declarative binding from an event name to a target workflow. Authors call
+ * `trigger.on(eventName, declaration)` at module-load time; the framework
+ * collects the entries via the process-local registry (see
+ * `./events/registry.js`) and ships them in the manifest.
+ *
+ * `where` and `input` are structured DSLs (no callbacks) so the runtime
+ * can evaluate them anywhere — in-process for self-host, server-side for
+ * managed deployments. The previous `match` callback is no longer
+ * supported; registration throws if it's set.
+ */
 export interface EventFilterDeclaration<T> {
   target: WorkflowHandle<T, unknown>
-  match?: (payload: T, ctx: { environment: EnvironmentContext; project: { id: string } }) => boolean
-  scope?: string
-  input?: (payload: T) => unknown
+  /** Structured predicate; see `@voyantjs/workflows/events` `PredicateExpr`. */
+  where?: PredicateExpr
+  /** Structured input projection; see `@voyantjs/workflows/events` `InputMapper`. */
+  input?: InputMapper
 }
 
 export interface TriggerApi {
-  on<T = unknown>(event: string, filter: EventFilterDeclaration<T>): EventFilterHandle
+  /**
+   * Register an event filter targeting `event`. Returns the
+   * {@link EventFilterRuntimeEntry} so authors can drop it directly into
+   * `Module.eventFilters` / `Plugin.eventFilters` — the entry structurally
+   * satisfies core's `EventFilterDescriptor` (matching `id` + `eventType`)
+   * and carries the manifest payload `createApp()` needs to register with
+   * the driver.
+   */
+  on<T = unknown>(event: string, filter: EventFilterDeclaration<T>): EventFilterRuntimeEntry
 }
 
 export const trigger: TriggerApi = {
-  on<T>(_event: string, _filter: EventFilterDeclaration<T>): EventFilterHandle {
-    throw new Error(
-      "@voyantjs/workflows: trigger.on() must be collected by `voyant workflows build` and " +
-        "registered with the orchestrator at deploy time; it has no runtime behavior when " +
-        "called directly. See docs/sdk-surface.md §6.2.",
-    )
+  on<T>(event: string, filter: EventFilterDeclaration<T>): EventFilterRuntimeEntry {
+    return compileAndRegister(event, filter)
   },
 }

package/src/workflow.ts

@@ -2,6 +2,7 @@
 // Authoritative contract in docs/sdk-surface.md §2–§3.
 
 import type { Condition } from "./conditions.js"
+import type { ServiceResolver } from "./driver.js"
 import type {
   Duration,
   EnvironmentName,
@@ -158,6 +159,16 @@ export interface WorkflowContext<_TInput = unknown> {
   readonly invocationCount: number
   readonly signal: AbortSignal
 
+  /**
+   * Read-only view of the framework's service container. Step bodies resolve
+   * shared services (db, indexer, etc.) via `ctx.services.resolve("name")`.
+   * The framework wires this from `createApp()`'s `ModuleContainer` through
+   * `StepHandlerDeps.services`. When no container is plumbed (driver not
+   * configured with `services`, or in raw orchestrator tests), `resolve(...)`
+   * throws with a clear message and `has(...)` returns `false`.
+   */
+  readonly services: ServiceResolver
+
   step: StepApi
   sleep: (duration: Duration) => Promise<void>
   waitForEvent: WaitForEventApi