@voyant-travel/workflows-orchestrator 0.107.10

package/src/http-step-handler.ts

@@ -0,0 +1,112 @@
+import { PROTOCOL_VERSION } from "@voyant-travel/workflows/protocol"
+import type { StepHandler, WorkflowStepRequest, WorkflowStepResponse } from "./types.js"
+
+interface StepHandlerError {
+  error: string
+  message: string
+  details?: unknown
+}
+
+export interface HttpStepTarget {
+  url: string
+  fetch(request: Request): Promise<Response>
+  label?: string
+}
+
+export interface HttpStepHandlerDeps {
+  /**
+   * Resolve the transport target for this workflow-step invocation.
+   * Adapters can map `tenantMeta.tenantScript` to a dispatch-namespace
+   * binding, a service URL, or a local proxy.
+   */
+  resolveTarget: (req: WorkflowStepRequest) => HttpStepTarget | Promise<HttpStepTarget>
+  /** Optional HMAC signer for the X-Voyant-Dispatch-Auth header. */
+  sign?: (body: string, req: WorkflowStepRequest) => Promise<string> | string
+  /** Optional logger for step-level observability. */
+  logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void
+}
+
+/**
+ * Build a StepHandler that serializes WorkflowStepRequest over HTTP.
+ * The concrete transport target is adapter-specific; the request/response
+ * mapping is shared across Cloudflare, Node, and future adapters.
+ */
+export function createHttpStepHandler(deps: HttpStepHandlerDeps): StepHandler {
+  return async (req: WorkflowStepRequest, stepOpts) => {
+    const body = JSON.stringify(req)
+    const headers: Record<string, string> = {
+      "content-type": "application/json; charset=utf-8",
+      "x-voyant-protocol": String(PROTOCOL_VERSION),
+    }
+    if (deps.sign) {
+      headers["x-voyant-dispatch-auth"] = await deps.sign(body, req)
+    }
+
+    const target = await deps.resolveTarget(req)
+    deps.logger?.("info", "http-step: invoking tenant step", {
+      target: target.label ?? target.url,
+      runId: req.runId,
+      workflowId: req.workflowId,
+      invocation: req.invocationCount,
+    })
+
+    let response: Response
+    try {
+      response = await target.fetch(
+        new Request(target.url, {
+          method: "POST",
+          headers,
+          body,
+          signal: stepOpts?.signal,
+        }),
+      )
+    } catch (err) {
+      deps.logger?.("error", "http-step: tenant fetch threw", {
+        target: target.label ?? target.url,
+        runId: req.runId,
+        error: err instanceof Error ? err.message : String(err),
+      })
+      return {
+        status: 502,
+        body: {
+          error: "tenant_unreachable",
+          message: err instanceof Error ? err.message : String(err),
+        },
+      }
+    }
+
+    const text = await response.text()
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      return {
+        status: 502,
+        body: {
+          error: "tenant_invalid_response",
+          message: `tenant returned non-JSON body (HTTP ${response.status})`,
+        },
+      }
+    }
+
+    if (response.status !== 200) {
+      return { status: response.status, body: toErrorBody(parsed, response.status) }
+    }
+    return { status: 200, body: parsed as WorkflowStepResponse }
+  }
+}
+
+function toErrorBody(parsed: unknown, fallbackStatus: number): StepHandlerError {
+  if (
+    parsed !== null &&
+    typeof parsed === "object" &&
+    typeof (parsed as { error?: unknown }).error === "string" &&
+    typeof (parsed as { message?: unknown }).message === "string"
+  ) {
+    return parsed as StepHandlerError
+  }
+  return {
+    error: "tenant_error",
+    message: `tenant returned HTTP ${fallbackStatus}`,
+  }
+}

package/src/in-memory-store.ts

@@ -0,0 +1,44 @@
+// A pure in-memory RunRecordStore. Useful for tests and local-only
+// orchestrator harnesses. The production store is Postgres-backed
+// and lives in voyant-cloud.
+
+import type { OrchestratorRunStatus, RunRecord, RunRecordStore } from "./types.js"
+
+export function createInMemoryRunStore(): RunRecordStore {
+  const records = new Map<string, RunRecord>()
+  return {
+    async get(id) {
+      const r = records.get(id)
+      return r ? clone(r) : undefined
+    },
+    async save(record) {
+      records.set(record.id, clone(record))
+      return clone(record)
+    },
+    async tryInsert(record) {
+      // Atomic-by-construction: Map.has + Map.set inside a single
+      // microtask. Concurrent `tryInsert(idA)` calls all schedule on the
+      // same JS event loop and only the first one observes the slot
+      // empty — subsequent callers see the inserted record.
+      const existing = records.get(record.id)
+      if (existing) return { record: clone(existing), created: false }
+      records.set(record.id, clone(record))
+      return { record: clone(record), created: true }
+    },
+    async list(filter = {}) {
+      let out = [...records.values()].map(clone)
+      if (filter.workflowId) out = out.filter((r) => r.workflowId === filter.workflowId)
+      if (filter.status) out = out.filter((r) => r.status === filter.status)
+      out.sort((a, b) => b.startedAt - a.startedAt)
+      if (filter.limit !== undefined) out = out.slice(0, filter.limit)
+      return out
+    },
+  }
+}
+
+function clone<T>(value: T): T {
+  return structuredClone(value)
+}
+
+/** Keep the unused import happy — guards against accidental type-only drift. */
+export type { OrchestratorRunStatus }

package/src/index.ts

@@ -0,0 +1,73 @@
+// @voyant-travel/workflows-orchestrator
+//
+// Reference orchestrator for Voyant Workflows. Drives runs through
+// the tenant step handler over the v1 wire protocol. Transport- and
+// storage-agnostic: compose with a RunRecordStore of your choice
+// (in-memory for tests, Postgres-backed for production).
+//
+// See docs/runtime-protocol.md §2 + §5 for the contract this
+// implements and docs/design.md §6 for the broader orchestrator
+// state-machine design.
+
+export {
+  registerRunAbort,
+  signalRunAbort,
+  unregisterRunAbort,
+} from "./abort-registry.js"
+export {
+  type ConcurrencyRunHooks,
+  createInProcessConcurrencyCoordinator,
+  type InProcessConcurrencyCoordinator,
+  type RuntimeConcurrencyPolicy,
+  resolveConcurrencyKey,
+  WorkflowConcurrencyRejectedError,
+} from "./concurrency.js"
+export { applyWaitpointInjection, type DriveOptions, driveUntilPaused } from "./drive.js"
+export {
+  createInMemoryDriver,
+  type InMemoryDriverOptions,
+} from "./driver-inmemory.js"
+export {
+  type RouteEventArgs,
+  type RouterMatch,
+  routeEvent,
+} from "./event-router.js"
+export {
+  createHttpStepHandler,
+  type HttpStepHandlerDeps,
+  type HttpStepTarget,
+} from "./http-step-handler.js"
+export { createInMemoryRunStore } from "./in-memory-store.js"
+export { emptyJournal } from "./journal-helpers.js"
+export {
+  type CancelArgs,
+  cancel,
+  type OrchestratorDeps,
+  type ResumeArgs,
+  type ResumeDueAlarmsArgs,
+  resume,
+  resumeDueAlarms,
+  type TriggerArgs,
+  trigger,
+} from "./orchestrator.js"
+export {
+  type BuildResumeJournalInput,
+  type BuildResumeJournalResult,
+  type BuildSeededResumeJournalInput,
+  buildResumeJournal,
+  buildSeededResumeJournal,
+} from "./resume-run.js"
+export {
+  type CronSpec,
+  computeNextFire,
+  createScheduler,
+  manifestScheduleSources,
+  nextCronFire,
+  parseCron,
+  type SchedulableDeclaration,
+  type SchedulerDeps,
+  type SchedulerHandle,
+  type ScheduleSource,
+  toMs,
+} from "./schedule.js"
+export * from "./types.js"

package/src/journal-helpers.ts

@@ -0,0 +1,11 @@
+import type { JournalSlice } from "@voyant-travel/workflows/protocol"
+
+export function emptyJournal(): JournalSlice {
+  return {
+    stepResults: {},
+    waitpointsResolved: {},
+    compensationsRun: {},
+    metadataState: {},
+    streamsCompleted: {},
+  }
+}