@voyant-travel/workflows 0.107.10

package/src/protocol/index.ts

@@ -0,0 +1,483 @@
+// @voyant-travel/workflows/protocol
+//
+// Wire-protocol types shared with the orchestrator. Full contract
+// in docs/runtime-protocol.md; types here are exported so callers
+// (test harness, adapters, dashboards) can build and inspect wire
+// payloads without reaching into runtime internals.
+
+import type { JournalSlice, WaitpointResolutionEntry } from "../runtime/journal.js"
+
+export type ProtocolVersion = 1
+export const PROTOCOL_VERSION: ProtocolVersion = 1
+
+// Journal types: shape of the tenant-side view of a run's state.
+// Re-exported so orchestrators and tools can build/inspect journals
+// without reaching into the runtime subpath.
+export type {
+  CompensationJournalEntry,
+  JournalSlice,
+  StepJournalEntry,
+  WaitpointResolutionEntry,
+} from "../runtime/journal.js"
+
+export type ExecutionStatus =
+  | "CREATED"
+  | "QUEUED"
+  | "EXECUTING"
+  | "EXECUTING_WITH_WAITPOINTS"
+  | "SUSPENDED"
+  | "PENDING_CANCEL"
+  | "FINISHED"
+
+export type WaitpointKind = "DATETIME" | "EVENT" | "SIGNAL" | "RUN" | "MANUAL"
+
+export interface SerializedError {
+  category: "USER_ERROR" | "RUNTIME_ERROR"
+  code: string
+  message: string
+  name?: string
+  stack?: string
+  cause?: SerializedError
+  data?: Record<string, unknown>
+}
+
+export type PayloadLocation = "INLINE" | "EXTERNAL"
+
+export interface WorkflowManifest {
+  schemaVersion: 1
+  projectId: string
+  versionId: string
+  builtAt: number
+  builderVersion: string
+  capabilities: WorkflowReleaseCapabilities
+  workflows: WorkflowManifestEntry[]
+  eventFilters: EventFilterManifestEntry[]
+  diagnostics: WorkflowManifestDiagnostic[]
+  bundle?: WorkflowManifestBundle
+  bindings: Record<string, { type: "d1" | "r2" | "kv" | "queue"; name: string }>
+  environments: Record<string, { customDomain?: string }>
+}
+
+export interface WorkflowManifestEntry {
+  id: string
+  displayName?: string
+  description?: string
+  capabilities: WorkflowDefinitionCapabilities
+  version: string
+  inputSchema?: unknown
+  outputSchema?: unknown
+  concurrency?: ManifestConcurrencyPolicy
+  steps: ManifestStep[]
+  schedules: ManifestSchedule[]
+  defaultRuntime: "edge" | "node"
+  hasCompensation: boolean
+  sourceLocation: { file: string; line: number }
+}
+
+export interface WorkflowReleaseCapabilities {
+  trigger: boolean
+  events: boolean
+  schedules: boolean
+  rerun: boolean
+  resume: boolean
+  cancel: boolean
+  humanApproval: boolean
+  stepRerun: boolean
+}
+
+export interface WorkflowDefinitionCapabilities {
+  canTrigger: boolean
+  canRerun: boolean
+  canResume: boolean
+  canCancel: boolean
+  hasSchedules: boolean
+  supportsEvents: boolean
+  supportsHumanApproval: boolean
+  supportsStepRerun: boolean
+}
+
+export interface WorkflowManifestBundle {
+  artifactName?: string
+  sizeBytes?: number
+  hash?: string
+  hashAlgorithm?: "sha256" | "sha512" | (string & {})
+}
+
+export interface WorkflowBundleReference {
+  key?: string
+  url?: string
+  signedUrl?: string
+  hash?: string
+  hashAlgorithm?: "sha256" | "sha512" | (string & {})
+  sizeBytes?: number
+}
+
+export interface WorkflowPayloadReference {
+  location: PayloadLocation
+  key?: string
+  url?: string
+  hash?: string
+  hashAlgorithm?: "sha256" | "sha512" | (string & {})
+  sizeBytes?: number
+  contentType?: string
+}
+
+export interface WorkflowJournalReference {
+  location: PayloadLocation
+  key?: string
+  url?: string
+  hash?: string
+  hashAlgorithm?: "sha256" | "sha512" | (string & {})
+}
+
+export interface WorkflowManifestDiagnostic {
+  code: string
+  severity: "info" | "warning" | "error"
+  message: string
+  sourceLocation?: { file: string; line?: number; column?: number }
+}
+
+export interface ManifestConcurrencyPolicy {
+  key?: string
+  limit?: number
+  strategy?: "queue" | "cancel-in-progress" | "cancel-newest" | "round-robin"
+}
+
+export interface ManifestStep {
+  id: string
+  runtime: "edge" | "node"
+  hasCompensation: boolean
+  sourceLocation: { file: string; line: number }
+}
+
+export interface ManifestSchedule {
+  cron?: string
+  every?: string | number
+  at?: string
+  timezone?: string
+  input?: unknown
+  enabled?: boolean
+  overlap?: "skip" | "queue" | "allow"
+  environments?: ("production" | "preview" | "development")[]
+  name?: string
+}
+
+export interface EventFilterManifestEntry {
+  /** Stable id derived from `payloadHash` of the canonicalized declaration. */
+  id: string
+  /** Event name the filter targets — matches `EventEnvelope.name`. */
+  eventType: string
+  /**
+   * Optional structured `where` predicate. When absent, every event of the
+   * matching `eventType` fires the target workflow. Concrete shape lives in
+   * `@voyant-travel/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 `@voyant-travel/workflows/events` (`InputMapper`).
+   */
+  input?: unknown
+  /** Content-derived hash of the canonicalized declaration. */
+  payloadHash: string
+  /** Workflow id this filter triggers. */
+  targetWorkflowId: string
+}
+
+export interface WorkflowWaitpointSource {
+  clientWaitpointId: string
+  kind: WaitpointKind
+  meta: Record<string, unknown>
+  timeoutMs?: number
+}
+
+export interface WorkflowWaitpointSnapshot {
+  /** Framework-stable waitpoint id, usually the runtime client waitpoint id. */
+  id: string
+  /** Stable key Cloud can store and later address without re-deriving metadata. */
+  key: string
+  kind: WaitpointKind
+  eventName?: string
+  signalName?: string
+  tokenId?: string
+  expiresAt?: number
+  timeoutMs?: number
+  metadata: Record<string, unknown>
+}
+
+export type WorkflowWaitpointResumeTarget = WorkflowWaitpointSource | WorkflowWaitpointSnapshot
+
+export interface WorkflowActivationFreshness {
+  dispatchedAt: number
+  expiresAt?: number
+  attempt?: number
+  leaseId?: string
+}
+
+export type WorkflowActivationMetadata =
+  | {
+      kind: "initial"
+      workflowReleaseId?: string
+      releaseId?: string
+      bundle?: WorkflowBundleReference
+      freshness?: WorkflowActivationFreshness
+    }
+  | WorkflowResumeActivationMetadata
+
+export interface WorkflowResumeActivationMetadata {
+  kind: "resume"
+  workflowReleaseId?: string
+  releaseId?: string
+  bundle?: WorkflowBundleReference
+  journalRef?: WorkflowJournalReference
+  waitpoint: WorkflowWaitpointSnapshot
+  resumePayloadRef?: WorkflowPayloadReference
+  freshness?: WorkflowActivationFreshness
+}
+
+export interface ApplyWorkflowResumeInput {
+  journal: JournalSlice
+  waitpoints: readonly WorkflowWaitpointResumeTarget[]
+  waitpointId?: string
+  waitpointKey?: string
+  parkedAt?: number
+  payload?: unknown
+  payloadRef?: WorkflowPayloadReference
+  resolvedAt?: number
+  matchedEventId?: string
+  source?: WaitpointResolutionEntry["source"]
+}
+
+export type ApplyWorkflowResumeResult =
+  | {
+      ok: true
+      journal: JournalSlice
+      waitpoint: WorkflowWaitpointSnapshot
+      resolution: WaitpointResolutionEntry
+    }
+  | {
+      ok: false
+      code: "missing_waitpoint_selector" | "waitpoint_not_found"
+      message: string
+    }
+
+export function workflowWaitpointKey(waitpoint: WorkflowWaitpointResumeTarget): string {
+  if (isWorkflowWaitpointSnapshot(waitpoint)) return waitpoint.key
+  return `${waitpoint.kind}:${waitpoint.clientWaitpointId}`
+}
+
+export function snapshotWorkflowWaitpoint(
+  waitpoint: WorkflowWaitpointResumeTarget,
+  parkedAt = Date.now(),
+): WorkflowWaitpointSnapshot {
+  const metadata = {
+    ...(isWorkflowWaitpointSnapshot(waitpoint) ? waitpoint.metadata : waitpoint.meta),
+  }
+  const timeoutMs = waitpoint.timeoutMs
+  const wakeAt = typeof metadata.wakeAt === "number" ? metadata.wakeAt : undefined
+  const expiresAt = isWorkflowWaitpointSnapshot(waitpoint)
+    ? waitpoint.expiresAt
+    : (wakeAt ??
+      (typeof timeoutMs === "number" && timeoutMs > 0 ? parkedAt + timeoutMs : undefined))
+
+  const snapshot: WorkflowWaitpointSnapshot = {
+    id: workflowWaitpointId(waitpoint),
+    key: workflowWaitpointKey(waitpoint),
+    kind: waitpoint.kind,
+    metadata,
+  }
+  if (typeof timeoutMs === "number") snapshot.timeoutMs = timeoutMs
+  if (typeof expiresAt === "number") snapshot.expiresAt = expiresAt
+  if (waitpoint.kind === "EVENT") {
+    const eventName = isWorkflowWaitpointSnapshot(waitpoint)
+      ? waitpoint.eventName
+      : typeof metadata.eventType === "string"
+        ? metadata.eventType
+        : undefined
+    if (eventName) snapshot.eventName = eventName
+  }
+  if (waitpoint.kind === "SIGNAL") {
+    const signalName = isWorkflowWaitpointSnapshot(waitpoint)
+      ? waitpoint.signalName
+      : typeof metadata.signalName === "string"
+        ? metadata.signalName
+        : undefined
+    if (signalName) snapshot.signalName = signalName
+  }
+  if (waitpoint.kind === "MANUAL") {
+    const tokenId = isWorkflowWaitpointSnapshot(waitpoint)
+      ? waitpoint.tokenId
+      : typeof metadata.tokenId === "string"
+        ? metadata.tokenId
+        : undefined
+    if (tokenId) snapshot.tokenId = tokenId
+  }
+  return snapshot
+}
+
+export function applyWorkflowResumeToJournal(
+  input: ApplyWorkflowResumeInput,
+): ApplyWorkflowResumeResult {
+  if (!input.waitpointId && !input.waitpointKey) {
+    return {
+      ok: false,
+      code: "missing_waitpoint_selector",
+      message: "resume requires waitpointId or waitpointKey",
+    }
+  }
+
+  const matched = input.waitpoints.find((waitpoint) => {
+    if (input.waitpointId && workflowWaitpointId(waitpoint) === input.waitpointId) return true
+    return (
+      input.waitpointKey !== undefined && workflowWaitpointKey(waitpoint) === input.waitpointKey
+    )
+  })
+
+  if (!matched) {
+    const selector = input.waitpointId
+      ? `waitpointId=${input.waitpointId}`
+      : `waitpointKey=${input.waitpointKey}`
+    return {
+      ok: false,
+      code: "waitpoint_not_found",
+      message: `no pending waitpoint matches ${selector}`,
+    }
+  }
+
+  const journal = structuredClone(input.journal) as JournalSlice
+  const resolution: WaitpointResolutionEntry = {
+    kind: matched.kind,
+    resolvedAt: input.resolvedAt ?? Date.now(),
+    source: input.source ?? "live",
+  }
+  if ("payload" in input) resolution.payload = input.payload
+  if (input.payloadRef) resolution.payloadRef = input.payloadRef
+  if (input.matchedEventId) resolution.matchedEventId = input.matchedEventId
+  journal.waitpointsResolved[workflowWaitpointId(matched)] = resolution
+
+  return {
+    ok: true,
+    journal,
+    waitpoint: snapshotWorkflowWaitpoint(matched, input.parkedAt ?? resolution.resolvedAt),
+    resolution,
+  }
+}
+
+function workflowWaitpointId(waitpoint: WorkflowWaitpointResumeTarget): string {
+  return isWorkflowWaitpointSnapshot(waitpoint) ? waitpoint.id : waitpoint.clientWaitpointId
+}
+
+function isWorkflowWaitpointSnapshot(
+  waitpoint: WorkflowWaitpointResumeTarget,
+): waitpoint is WorkflowWaitpointSnapshot {
+  return "id" in waitpoint
+}
+
+// WebSocket stream events — full union in docs/runtime-protocol.md §6.2.
+export type StreamEvent =
+  | {
+      kind: "step.started"
+      eventId: string
+      at: number
+      stepId: string
+      runtime: "edge" | "node"
+      machine?: string
+    }
+  | {
+      kind: "step.ok"
+      eventId: string
+      at: number
+      stepId: string
+      attempt: number
+      durationMs: number
+      output?: unknown
+    }
+  | {
+      kind: "step.err"
+      eventId: string
+      at: number
+      stepId: string
+      attempt: number
+      error: SerializedError
+    }
+  | { kind: "step.skipped"; eventId: string; at: number; stepId: string; reason: string }
+  | {
+      kind: "step.compensated"
+      eventId: string
+      at: number
+      stepId: string
+      status: "ok" | "err"
+      error?: SerializedError
+    }
+  | {
+      kind: "waitpoint.registered"
+      eventId: string
+      at: number
+      waitpointId: string
+      waitpointKind: WaitpointKind
+      meta: Record<string, unknown>
+    }
+  | {
+      kind: "waitpoint.resolved"
+      eventId: string
+      at: number
+      waitpointId: string
+      payload?: unknown
+      source: "live" | "inbox" | "replay"
+    }
+  | { kind: "metadata.changed"; eventId: string; at: number; metadata: Record<string, unknown> }
+  | {
+      kind: "stream.chunk"
+      eventId: string
+      at: number
+      streamId: string
+      chunk: unknown
+      encoding: "json" | "text" | "base64"
+      final: boolean
+    }
+  | {
+      kind: "log"
+      eventId: string
+      at: number
+      level: "info" | "warn" | "error"
+      message: string
+      stepId?: string
+      data?: object
+    }
+  | { kind: "version.rebased"; eventId: string; at: number; fromVersion: string; toVersion: string }
+  | { kind: "run.cancelled"; eventId: string; at: number; reason?: string }
+  | {
+      kind: "run.finished"
+      eventId: string
+      at: number
+      status: string
+      output?: unknown
+      error?: SerializedError
+    }
+
+// Shared envelope for journal events written by the orchestrator,
+// the tenant worker, or a node-runtime container. Concrete `kind`
+// discriminants are owned by the emitting layer.
+export interface JournalEventEnvelope<TKind extends string = string, TData = unknown> {
+  eventId: string
+  runId: string
+  createdAt: number
+  kind: TKind
+  data: TData
+  snapshotId?: string
+  writtenBy: "orchestrator" | "tenant" | "node"
+}
+
+export interface PublicAccessTokenClaims {
+  sub: "pat"
+  tenantId: string
+  environment: "production" | "preview" | "development"
+  scope: ("read" | "trigger" | "cancel")[]
+  target:
+    | { kind: "run"; runId: string }
+    | { kind: "workflow"; workflowId: string }
+    | { kind: "tag"; tag: string }
+  exp: number
+}

package/src/rate-limit/index.ts

@@ -0,0 +1,181 @@
+// @voyant-travel/workflows/rate-limit
+//
+// Reference rate limiter used by `ctx.step({ rateLimit: ... })`.
+//
+// A RateLimiter is a small interface: `acquire()` blocks (or throws,
+// depending on `onLimit`) until `units` are available under `key` for
+// a sliding window of `windowMs`. One shared limiter instance lives
+// per tenant Worker process — callers wire it into `createStepHandler`
+// via `{ rateLimiter: createInMemoryRateLimiter() }`.
+//
+// The in-memory impl is a token bucket: `capacity = limit`, refill
+// rate = `limit / windowMs`. It's suitable for local dev and
+// single-process deployments. Multi-region / sharded deployments
+// should swap in a Durable-Object or Redis-backed implementation that
+// shares state across isolates.
+
+import type { Duration } from "../types.js"
+
+export interface AcquireArgs {
+  /** Bucket key — usually a tenant id, a url host, a user id, etc. */
+  key: string
+  /** Maximum units the bucket can hold. */
+  limit: number
+  /** Units the current call consumes. */
+  units: number
+  /** Refill window in ms. `limit` tokens per `windowMs`. */
+  windowMs: number
+  /** `queue` → wait until capacity; `fail` → throw immediately. */
+  onLimit: "queue" | "fail"
+  /** Forwarded from the run; limiter observes aborts during queue waits. */
+  signal?: AbortSignal
+}
+
+export interface RateLimiter {
+  acquire(args: AcquireArgs): Promise<void>
+}
+
+/** Error thrown when `onLimit === "fail"` and the bucket is empty. */
+export class RateLimitExceededError extends Error {
+  readonly code = "RATE_LIMITED"
+  readonly retryAfterMs: number
+  constructor(key: string, retryAfterMs: number) {
+    super(`rate limit exceeded for key "${key}" (retry after ${retryAfterMs}ms)`)
+    this.name = "RateLimitExceededError"
+    this.retryAfterMs = retryAfterMs
+  }
+}
+
+interface Bucket {
+  tokens: number
+  capacity: number
+  refillPerMs: number
+  lastRefillAt: number
+}
+
+export interface InMemoryLimiterOptions {
+  /** Injectable clock, ms since epoch. Defaults to Date.now. */
+  now?: () => number
+  /** Injectable delay; defaults to setTimeout. Tests override this. */
+  delay?: (ms: number, signal?: AbortSignal) => Promise<void>
+}
+
+/**
+ * Token-bucket rate limiter held in-process. Independent buckets per
+ * `key`; bucket parameters (`capacity`, `refillPerMs`) come from the
+ * `limit` / `windowMs` of the first `acquire` call and are updated on
+ * subsequent calls that change them.
+ */
+export function createInMemoryRateLimiter(opts: InMemoryLimiterOptions = {}): RateLimiter {
+  const now = opts.now ?? (() => Date.now())
+  const delay = opts.delay ?? defaultDelay
+  const buckets = new Map<string, Bucket>()
+
+  return {
+    async acquire(args) {
+      if (args.units <= 0) return
+      if (args.limit <= 0) {
+        throw new Error(`rate-limit: "limit" must be > 0 (got ${args.limit}) for key "${args.key}"`)
+      }
+      if (args.windowMs <= 0) {
+        throw new Error(
+          `rate-limit: "windowMs" must be > 0 (got ${args.windowMs}) for key "${args.key}"`,
+        )
+      }
+      if (args.units > args.limit) {
+        // The step will never be admissible — short-circuit regardless
+        // of onLimit to avoid hanging indefinitely under queue mode.
+        throw new Error(
+          `rate-limit: units (${args.units}) > limit (${args.limit}) for key "${args.key}" — step can never be admitted`,
+        )
+      }
+
+      while (true) {
+        const bucket = refill(buckets, args, now())
+        if (bucket.tokens >= args.units) {
+          bucket.tokens -= args.units
+          return
+        }
+        const missing = args.units - bucket.tokens
+        const waitMs = Math.ceil(missing / bucket.refillPerMs)
+        if (args.onLimit === "fail") {
+          throw new RateLimitExceededError(args.key, waitMs)
+        }
+        await delay(waitMs, args.signal)
+        if (args.signal?.aborted) {
+          throw args.signal.reason ?? new Error("rate-limit: aborted while queued")
+        }
+      }
+    },
+  }
+}
+
+function refill(buckets: Map<string, Bucket>, args: AcquireArgs, nowMs: number): Bucket {
+  const refillPerMs = args.limit / args.windowMs
+  let b = buckets.get(args.key)
+  if (!b) {
+    b = {
+      tokens: args.limit,
+      capacity: args.limit,
+      refillPerMs,
+      lastRefillAt: nowMs,
+    }
+    buckets.set(args.key, b)
+    return b
+  }
+  // Re-parameterize if the caller changed limit / windowMs. Clamp
+  // tokens to the new capacity so a shrink doesn't leave stale excess.
+  if (b.capacity !== args.limit || b.refillPerMs !== refillPerMs) {
+    b.capacity = args.limit
+    b.refillPerMs = refillPerMs
+    if (b.tokens > b.capacity) b.tokens = b.capacity
+  }
+  const elapsed = Math.max(0, nowMs - b.lastRefillAt)
+  if (elapsed > 0) {
+    b.tokens = Math.min(b.capacity, b.tokens + elapsed * b.refillPerMs)
+    b.lastRefillAt = nowMs
+  }
+  return b
+}
+
+function defaultDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"))
+      return
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(signal?.reason ?? new Error("aborted"))
+    }
+    signal?.addEventListener("abort", onAbort, { once: true })
+  })
+}
+
+/** Normalize a Duration to milliseconds. Same units as `toMs` in ctx.ts. */
+export function durationToMs(d: Duration): number {
+  if (typeof d === "number") return d
+  const m = /^(\d+)(ms|s|m|h|d|w)$/.exec(d)
+  if (!m) throw new Error(`rate-limit: invalid duration "${d}"`)
+  const n = Number(m[1])
+  switch (m[2]) {
+    case "ms":
+      return n
+    case "s":
+      return n * 1_000
+    case "m":
+      return n * 60_000
+    case "h":
+      return n * 3_600_000
+    case "d":
+      return n * 86_400_000
+    case "w":
+      return n * 604_800_000
+    default:
+      throw new Error(`rate-limit: invalid duration "${d}"`)
+  }
+}