@voyantjs/workflows 0.0.0 → 0.6.8

package/src/protocol/index.ts

@@ -5,18 +5,18 @@
 // (test harness, adapters, dashboards) can build and inspect wire
 // payloads without reaching into runtime internals.
 
-export type ProtocolVersion = 1;
-export const PROTOCOL_VERSION: ProtocolVersion = 1;
+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,
-  CompensationJournalEntry,
-} from "../runtime/journal.js";
+} from "../runtime/journal.js"
 
 export type ExecutionStatus =
   | "CREATED"
@@ -25,109 +25,175 @@ export type ExecutionStatus =
   | "EXECUTING_WITH_WAITPOINTS"
   | "SUSPENDED"
   | "PENDING_CANCEL"
-  | "FINISHED";
+  | "FINISHED"
 
-export type WaitpointKind = "DATETIME" | "EVENT" | "SIGNAL" | "RUN" | "MANUAL";
+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>;
+  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 type PayloadLocation = "INLINE" | "EXTERNAL"
 
 export interface WorkflowManifest {
-  schemaVersion: 1;
-  projectId: string;
-  versionId: string;
-  builtAt: number;
-  builderVersion: string;
-  capabilities: string[];
-  workflows: WorkflowManifestEntry[];
-  eventFilters: EventFilterManifestEntry[];
-  bindings: Record<string, { type: "d1" | "r2" | "kv" | "queue"; name: string }>;
-  environments: Record<string, { customDomain?: string }>;
+  schemaVersion: 1
+  projectId: string
+  versionId: string
+  builtAt: number
+  builderVersion: string
+  capabilities: string[]
+  workflows: WorkflowManifestEntry[]
+  eventFilters: EventFilterManifestEntry[]
+  bindings: Record<string, { type: "d1" | "r2" | "kv" | "queue"; name: string }>
+  environments: Record<string, { customDomain?: string }>
 }
 
 export interface WorkflowManifestEntry {
-  id: string;
-  version: string;
-  inputSchema?: unknown;
-  outputSchema?: unknown;
-  steps: ManifestStep[];
-  schedules: ManifestSchedule[];
-  defaultRuntime: "edge" | "node";
-  hasCompensation: boolean;
-  sourceLocation: { file: string; line: number };
+  id: string
+  version: string
+  inputSchema?: unknown
+  outputSchema?: unknown
+  steps: ManifestStep[]
+  schedules: ManifestSchedule[]
+  defaultRuntime: "edge" | "node"
+  hasCompensation: boolean
+  sourceLocation: { file: string; line: number }
 }
 
 export interface ManifestStep {
-  id: string;
-  runtime: "edge" | "node";
-  hasCompensation: boolean;
-  sourceLocation: { file: string; line: number };
+  id: string
+  runtime: "edge" | "node"
+  hasCompensation: boolean
+  sourceLocation: { file: string; line: number }
 }
 
 export interface ManifestSchedule {
-  cron?: string;
-  every?: string;
-  at?: string;
-  timezone?: string;
-  environments?: ("production" | "preview" | "development")[];
-  name?: string;
+  cron?: string
+  every?: string
+  at?: string
+  timezone?: string
+  environments?: ("production" | "preview" | "development")[]
+  name?: string
 }
 
 export interface EventFilterManifestEntry {
-  id: string;
-  eventType: string;
-  scope?: string;
-  matchExpression?: string;
-  payloadHash: string;
-  targetWorkflowId: string;
+  id: string
+  eventType: string
+  scope?: string
+  matchExpression?: string
+  payloadHash: string
+  targetWorkflowId: string
 }
 
 // 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.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: "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: "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 };
+  | {
+      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";
+  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")[];
+  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;
+    | { kind: "tag"; tag: string }
+  exp: number
 }

package/src/rate-limit/index.ts

@@ -14,50 +14,50 @@
 // should swap in a Durable-Object or Redis-backed implementation that
 // shares state across isolates.
 
-import type { Duration } from "../types.js";
+import type { Duration } from "../types.js"
 
 export interface AcquireArgs {
   /** Bucket key — usually a tenant id, a url host, a user id, etc. */
-  key: string;
+  key: string
   /** Maximum units the bucket can hold. */
-  limit: number;
+  limit: number
   /** Units the current call consumes. */
-  units: number;
+  units: number
   /** Refill window in ms. `limit` tokens per `windowMs`. */
-  windowMs: number;
+  windowMs: number
   /** `queue` → wait until capacity; `fail` → throw immediately. */
-  onLimit: "queue" | "fail";
+  onLimit: "queue" | "fail"
   /** Forwarded from the run; limiter observes aborts during queue waits. */
-  signal?: AbortSignal;
+  signal?: AbortSignal
 }
 
 export interface RateLimiter {
-  acquire(args: AcquireArgs): Promise<void>;
+  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;
+  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;
+    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;
+  tokens: number
+  capacity: number
+  refillPerMs: number
+  lastRefillAt: number
 }
 
 export interface InMemoryLimiterOptions {
   /** Injectable clock, ms since epoch. Defaults to Date.now. */
-  now?: () => number;
+  now?: () => number
   /** Injectable delay; defaults to setTimeout. Tests override this. */
-  delay?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  delay?: (ms: number, signal?: AbortSignal) => Promise<void>
 }
 
 /**
@@ -66,117 +66,116 @@ export interface InMemoryLimiterOptions {
  * `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>();
+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.units <= 0) return
       if (args.limit <= 0) {
-        throw new Error(
-          `rate-limit: "limit" must be > 0 (got ${args.limit}) for key "${args.key}"`,
-        );
+        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());
+        const bucket = refill(buckets, args, now())
         if (bucket.tokens >= args.units) {
-          bucket.tokens -= args.units;
-          return;
+          bucket.tokens -= args.units
+          return
         }
-        const missing = args.units - bucket.tokens;
-        const waitMs = Math.ceil(missing / bucket.refillPerMs);
+        const missing = args.units - bucket.tokens
+        const waitMs = Math.ceil(missing / bucket.refillPerMs)
         if (args.onLimit === "fail") {
-          throw new RateLimitExceededError(args.key, waitMs);
+          throw new RateLimitExceededError(args.key, waitMs)
         }
-        await delay(waitMs, args.signal);
+        await delay(waitMs, args.signal)
         if (args.signal?.aborted) {
-          throw args.signal.reason ?? new Error("rate-limit: aborted while queued");
+          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);
+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;
+    }
+    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;
+    b.capacity = args.limit
+    b.refillPerMs = refillPerMs
+    if (b.tokens > b.capacity) b.tokens = b.capacity
   }
-  const elapsed = Math.max(0, nowMs - b.lastRefillAt);
+  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;
+    b.tokens = Math.min(b.capacity, b.tokens + elapsed * b.refillPerMs)
+    b.lastRefillAt = nowMs
   }
-  return b;
+  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;
+      reject(signal.reason ?? new Error("aborted"))
+      return
     }
     const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
+      signal?.removeEventListener("abort", onAbort)
+      resolve()
+    }, ms)
     const onAbort = () => {
-      clearTimeout(timer);
-      reject(signal?.reason ?? new Error("aborted"));
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
+      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]);
+  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}"`);
+    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}"`)
   }
 }