@bratsos/workflow-engine-host-serverless 0.2.2

package/README.md

@@ -0,0 +1,190 @@
+# @bratsos/workflow-engine-host-serverless
+
+Platform-agnostic serverless host for the [`@bratsos/workflow-engine`](../workflow-engine) command kernel. Works with Cloudflare Workers, AWS Lambda, Vercel Edge, Deno Deploy, and any stateless runtime.
+
+## Installation
+
+```bash
+npm install @bratsos/workflow-engine-host-serverless
+```
+
+## Quick Start
+
+```typescript
+import { createKernel } from "@bratsos/workflow-engine/kernel";
+import { createServerlessHost } from "@bratsos/workflow-engine-host-serverless";
+
+const kernel = createKernel({ /* ... */ });
+
+const host = createServerlessHost({
+  kernel,
+  jobTransport,
+  workerId: "my-worker",
+});
+
+// Handle a job from a queue message
+const result = await host.handleJob(msg);
+
+// Run maintenance from a cron trigger
+const tick = await host.runMaintenanceTick();
+```
+
+## API
+
+### `createServerlessHost(config): ServerlessHost`
+
+Creates a new serverless host instance.
+
+### `ServerlessHostConfig`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `kernel` | `Kernel` | required | Kernel instance to dispatch commands to |
+| `jobTransport` | `JobTransport` | required | Job transport for complete/suspend/fail lifecycle |
+| `workerId` | `string` | required | Unique worker identifier (e.g. function name) |
+| `staleLeaseThresholdMs` | `number` | `60_000` | Time before a job lease is considered stale |
+| `maxClaimsPerTick` | `number` | `10` | Max pending runs to claim per maintenance tick |
+| `maxSuspendedChecksPerTick` | `number` | `10` | Max suspended stages to poll per tick |
+| `maxOutboxFlushPerTick` | `number` | `100` | Max outbox events to flush per tick |
+
+### `ServerlessHost`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `handleJob(msg)` | `Promise<JobResult>` | Execute a single pre-dequeued job |
+| `processAvailableJobs(opts?)` | `Promise<ProcessJobsResult>` | Dequeue and process jobs |
+| `runMaintenanceTick()` | `Promise<MaintenanceTickResult>` | Run one bounded maintenance cycle |
+
+### `JobMessage`
+
+The shape of a job message passed to `handleJob()`:
+
+```typescript
+interface JobMessage {
+  jobId: string;
+  workflowRunId: string;
+  workflowId: string;
+  stageId: string;
+  attempt: number;
+  payload: Record<string, unknown>;
+}
+```
+
+### `JobResult`
+
+```typescript
+interface JobResult {
+  outcome: "completed" | "suspended" | "failed";
+  error?: string;
+}
+```
+
+### `ProcessJobsResult`
+
+```typescript
+interface ProcessJobsResult {
+  processed: number;
+  succeeded: number;
+  failed: number;
+}
+```
+
+### `MaintenanceTickResult`
+
+```typescript
+interface MaintenanceTickResult {
+  claimed: number;          // Pending runs claimed
+  suspendedChecked: number; // Suspended stages polled
+  staleReleased: number;    // Stale leases released
+  eventsFlushed: number;    // Outbox events published
+}
+```
+
+## Platform Integration Examples
+
+### Cloudflare Workers (Queue + Cron)
+
+```typescript
+import { createServerlessHost } from "@bratsos/workflow-engine-host-serverless";
+
+export default {
+  // Queue consumer -- process jobs from Cloudflare Queue
+  async queue(batch, env, ctx) {
+    const host = createServerlessHost({ kernel, jobTransport, workerId: "cf-worker" });
+
+    for (const msg of batch.messages) {
+      const result = await host.handleJob(msg.body);
+
+      if (result.outcome === "failed") {
+        msg.retry();
+      } else {
+        msg.ack();
+      }
+    }
+  },
+
+  // Cron trigger -- run maintenance
+  async scheduled(event, env, ctx) {
+    const host = createServerlessHost({ kernel, jobTransport, workerId: "cf-worker" });
+    ctx.waitUntil(host.runMaintenanceTick());
+  },
+};
+```
+
+### AWS Lambda (SQS + EventBridge)
+
+```typescript
+import { createServerlessHost } from "@bratsos/workflow-engine-host-serverless";
+
+// SQS handler -- process jobs
+export async function jobHandler(event) {
+  const host = createServerlessHost({ kernel, jobTransport, workerId: "lambda-worker" });
+
+  for (const record of event.Records) {
+    const msg = JSON.parse(record.body);
+    await host.handleJob(msg);
+  }
+}
+
+// EventBridge handler -- maintenance cron
+export async function maintenanceHandler() {
+  const host = createServerlessHost({ kernel, jobTransport, workerId: "lambda-worker" });
+  return host.runMaintenanceTick();
+}
+```
+
+### Vercel Edge (API Route + Cron)
+
+```typescript
+import { createServerlessHost } from "@bratsos/workflow-engine-host-serverless";
+
+// POST /api/process-job
+export async function POST(request: Request) {
+  const host = createServerlessHost({ kernel, jobTransport, workerId: "vercel-worker" });
+  const result = await host.processAvailableJobs({ maxJobs: 5 });
+  return Response.json(result);
+}
+
+// GET /api/cron/maintenance (Vercel Cron)
+export async function GET() {
+  const host = createServerlessHost({ kernel, jobTransport, workerId: "vercel-worker" });
+  const tick = await host.runMaintenanceTick();
+  return Response.json(tick);
+}
+```
+
+## How It Works
+
+Unlike the Node host, the serverless host has **no loops, timers, or signal handlers**. Every method is a single stateless invocation:
+
+- **`handleJob(msg)`** -- Dispatches `job.execute` to the kernel, then marks the job complete/suspended/failed via `jobTransport`. On completion, also dispatches `run.transition` to advance the workflow.
+
+- **`processAvailableJobs(opts?)`** -- Dequeues up to `maxJobs` (default: 1) from the job transport and processes each via `handleJob`. Safe for edge runtimes with CPU limits.
+
+- **`runMaintenanceTick()`** -- Runs one bounded pass of all orchestration duties: `run.claimPending`, `stage.pollSuspended`, `lease.reapStale`, `outbox.flush`.
+
+Consumers wire platform-specific glue (queue ack/retry, `waitUntil`, cron triggers) around these methods.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { Kernel, JobTransport } from '@bratsos/workflow-engine/kernel';
+
+/**
+ * Serverless Host for Workflow Engine Command Kernel
+ *
+ * Platform-agnostic host for serverless environments (Cloudflare Workers,
+ * AWS Lambda, Vercel Edge, Deno Deploy, etc.). Unlike the Node host, there
+ * are no timers, loops, or signal handlers — every method is a single
+ * stateless invocation.
+ *
+ * Consumers wire platform-specific glue (queue ack/retry, waitUntil,
+ * cron triggers) around these methods.
+ */
+
+interface ServerlessHostConfig {
+    /** Kernel instance to dispatch commands to. */
+    kernel: Kernel;
+    /** Job transport for complete/suspend/fail lifecycle. */
+    jobTransport: JobTransport;
+    /** Unique worker identifier (e.g. function name, worker name). */
+    workerId: string;
+    /** Stale lease threshold in milliseconds (default: 60_000). */
+    staleLeaseThresholdMs?: number;
+    /** Max pending runs to claim per maintenance tick (default: 10). */
+    maxClaimsPerTick?: number;
+    /** Max suspended stages to check per tick (default: 10). */
+    maxSuspendedChecksPerTick?: number;
+    /** Max outbox events to flush per tick (default: 100). */
+    maxOutboxFlushPerTick?: number;
+}
+/** Message shape representing a job to execute. Matches DequeueResult fields. */
+interface JobMessage {
+    jobId: string;
+    workflowRunId: string;
+    workflowId: string;
+    stageId: string;
+    attempt: number;
+    maxAttempts?: number;
+    payload: Record<string, unknown>;
+}
+interface JobResult {
+    outcome: "completed" | "suspended" | "failed";
+    error?: string;
+}
+interface ProcessJobsResult {
+    processed: number;
+    succeeded: number;
+    failed: number;
+}
+interface MaintenanceTickResult {
+    claimed: number;
+    suspendedChecked: number;
+    staleReleased: number;
+    eventsFlushed: number;
+}
+interface ServerlessHost {
+    /** Execute a single pre-dequeued job. Returns outcome so consumer can ack/retry. */
+    handleJob(msg: JobMessage): Promise<JobResult>;
+    /**
+     * Dequeue and process jobs from the jobTransport.
+     * Defaults to 1 job per call (safe for edge runtimes with CPU limits).
+     * Pass maxJobs for longer-running environments like Lambda.
+     */
+    processAvailableJobs(opts?: {
+        maxJobs?: number;
+    }): Promise<ProcessJobsResult>;
+    /** Run one bounded maintenance tick (claim, poll, reap, flush). */
+    runMaintenanceTick(): Promise<MaintenanceTickResult>;
+}
+declare function createServerlessHost(config: ServerlessHostConfig): ServerlessHost;
+
+export { type JobMessage, type JobResult, type MaintenanceTickResult, type ProcessJobsResult, type ServerlessHost, type ServerlessHostConfig, createServerlessHost };

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/host.ts
+var ServerlessHostImpl = class {
+  kernel;
+  jobTransport;
+  workerId;
+  staleLeaseThresholdMs;
+  maxClaimsPerTick;
+  maxSuspendedChecksPerTick;
+  maxOutboxFlushPerTick;
+  constructor(config) {
+    this.kernel = config.kernel;
+    this.jobTransport = config.jobTransport;
+    this.workerId = config.workerId;
+    this.staleLeaseThresholdMs = config.staleLeaseThresholdMs ?? 6e4;
+    this.maxClaimsPerTick = config.maxClaimsPerTick ?? 10;
+    this.maxSuspendedChecksPerTick = config.maxSuspendedChecksPerTick ?? 10;
+    this.maxOutboxFlushPerTick = config.maxOutboxFlushPerTick ?? 100;
+  }
+  async handleJob(msg) {
+    const config = msg.payload.config || {};
+    const result = await this.kernel.dispatch({
+      type: "job.execute",
+      idempotencyKey: `job:${msg.jobId}:attempt:${msg.attempt}`,
+      workflowRunId: msg.workflowRunId,
+      workflowId: msg.workflowId,
+      stageId: msg.stageId,
+      config
+    });
+    if (result.outcome === "completed") {
+      await this.jobTransport.complete(msg.jobId);
+      await this.kernel.dispatch({
+        type: "run.transition",
+        workflowRunId: msg.workflowRunId
+      });
+      return { outcome: "completed" };
+    }
+    if (result.outcome === "suspended") {
+      const nextPollAt = result.nextPollAt ?? new Date(Date.now() + 6e4);
+      await this.jobTransport.suspend(msg.jobId, nextPollAt);
+      return { outcome: "suspended" };
+    }
+    const canRetry = msg.attempt < (msg.maxAttempts ?? 3);
+    await this.jobTransport.fail(
+      msg.jobId,
+      result.error ?? "Unknown error",
+      canRetry
+    );
+    return { outcome: "failed", error: result.error };
+  }
+  async processAvailableJobs(opts) {
+    const maxJobs = opts?.maxJobs ?? 1;
+    let processed = 0;
+    let succeeded = 0;
+    let failed = 0;
+    while (processed < maxJobs) {
+      const job = await this.jobTransport.dequeue();
+      if (!job) break;
+      const result = await this.handleJob({
+        jobId: job.jobId,
+        workflowRunId: job.workflowRunId,
+        workflowId: job.workflowId,
+        stageId: job.stageId,
+        attempt: job.attempt,
+        maxAttempts: job.maxAttempts,
+        payload: job.payload
+      });
+      processed++;
+      if (result.outcome === "failed") {
+        failed++;
+      } else {
+        succeeded++;
+      }
+    }
+    return { processed, succeeded, failed };
+  }
+  async runMaintenanceTick() {
+    const claimResult = await this.kernel.dispatch({
+      type: "run.claimPending",
+      workerId: this.workerId,
+      maxClaims: this.maxClaimsPerTick
+    });
+    const pollResult = await this.kernel.dispatch({
+      type: "stage.pollSuspended",
+      maxChecks: this.maxSuspendedChecksPerTick
+    });
+    for (const workflowRunId of pollResult.resumedWorkflowRunIds) {
+      await this.kernel.dispatch({
+        type: "run.transition",
+        workflowRunId
+      });
+    }
+    const reapResult = await this.kernel.dispatch({
+      type: "lease.reapStale",
+      staleThresholdMs: this.staleLeaseThresholdMs
+    });
+    const flushResult = await this.kernel.dispatch({
+      type: "outbox.flush",
+      maxEvents: this.maxOutboxFlushPerTick
+    });
+    return {
+      claimed: claimResult.claimed.length,
+      suspendedChecked: pollResult.checked,
+      staleReleased: reapResult.released,
+      eventsFlushed: flushResult.published
+    };
+  }
+};
+function createServerlessHost(config) {
+  return new ServerlessHostImpl(config);
+}
+
+export { createServerlessHost };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/host.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Serverless Host for Workflow Engine Command Kernel\n *\n * Platform-agnostic host for serverless environments (Cloudflare Workers,\n * AWS Lambda, Vercel Edge, Deno Deploy, etc.). Unlike the Node host, there\n * are no timers, loops, or signal handlers — every method is a single\n * stateless invocation.\n *\n * Consumers wire platform-specific glue (queue ack/retry, waitUntil,\n * cron triggers) around these methods.\n */\n\nimport type { JobTransport, Kernel } from \"@bratsos/workflow-engine/kernel\";\n\n// ============================================================================\n// Public interfaces\n// ============================================================================\n\nexport interface ServerlessHostConfig {\n  /** Kernel instance to dispatch commands to. */\n  kernel: Kernel;\n\n  /** Job transport for complete/suspend/fail lifecycle. */\n  jobTransport: JobTransport;\n\n  /** Unique worker identifier (e.g. function name, worker name). */\n  workerId: string;\n\n  /** Stale lease threshold in milliseconds (default: 60_000). */\n  staleLeaseThresholdMs?: number;\n\n  /** Max pending runs to claim per maintenance tick (default: 10). */\n  maxClaimsPerTick?: number;\n\n  /** Max suspended stages to check per tick (default: 10). */\n  maxSuspendedChecksPerTick?: number;\n\n  /** Max outbox events to flush per tick (default: 100). */\n  maxOutboxFlushPerTick?: number;\n}\n\n/** Message shape representing a job to execute. Matches DequeueResult fields. */\nexport interface JobMessage {\n  jobId: string;\n  workflowRunId: string;\n  workflowId: string;\n  stageId: string;\n  attempt: number;\n  maxAttempts?: number;\n  payload: Record<string, unknown>;\n}\n\nexport interface JobResult {\n  outcome: \"completed\" | \"suspended\" | \"failed\";\n  error?: string;\n}\n\nexport interface ProcessJobsResult {\n  processed: number;\n  succeeded: number;\n  failed: number;\n}\n\nexport interface MaintenanceTickResult {\n  claimed: number;\n  suspendedChecked: number;\n  staleReleased: number;\n  eventsFlushed: number;\n}\n\nexport interface ServerlessHost {\n  /** Execute a single pre-dequeued job. Returns outcome so consumer can ack/retry. */\n  handleJob(msg: JobMessage): Promise<JobResult>;\n\n  /**\n   * Dequeue and process jobs from the jobTransport.\n   * Defaults to 1 job per call (safe for edge runtimes with CPU limits).\n   * Pass maxJobs for longer-running environments like Lambda.\n   */\n  processAvailableJobs(opts?: { maxJobs?: number }): Promise<ProcessJobsResult>;\n\n  /** Run one bounded maintenance tick (claim, poll, reap, flush). */\n  runMaintenanceTick(): Promise<MaintenanceTickResult>;\n}\n\n// ============================================================================\n// Implementation\n// ============================================================================\n\nclass ServerlessHostImpl implements ServerlessHost {\n  private readonly kernel: Kernel;\n  private readonly jobTransport: JobTransport;\n  private readonly workerId: string;\n  private readonly staleLeaseThresholdMs: number;\n  private readonly maxClaimsPerTick: number;\n  private readonly maxSuspendedChecksPerTick: number;\n  private readonly maxOutboxFlushPerTick: number;\n\n  constructor(config: ServerlessHostConfig) {\n    this.kernel = config.kernel;\n    this.jobTransport = config.jobTransport;\n    this.workerId = config.workerId;\n    this.staleLeaseThresholdMs = config.staleLeaseThresholdMs ?? 60_000;\n    this.maxClaimsPerTick = config.maxClaimsPerTick ?? 10;\n    this.maxSuspendedChecksPerTick = config.maxSuspendedChecksPerTick ?? 10;\n    this.maxOutboxFlushPerTick = config.maxOutboxFlushPerTick ?? 100;\n  }\n\n  async handleJob(msg: JobMessage): Promise<JobResult> {\n    const config =\n      (msg.payload as { config?: Record<string, unknown> }).config || {};\n\n    const result = await this.kernel.dispatch({\n      type: \"job.execute\",\n      idempotencyKey: `job:${msg.jobId}:attempt:${msg.attempt}`,\n      workflowRunId: msg.workflowRunId,\n      workflowId: msg.workflowId,\n      stageId: msg.stageId,\n      config,\n    });\n\n    if (result.outcome === \"completed\") {\n      await this.jobTransport.complete(msg.jobId);\n      await this.kernel.dispatch({\n        type: \"run.transition\",\n        workflowRunId: msg.workflowRunId,\n      });\n      return { outcome: \"completed\" };\n    }\n\n    if (result.outcome === \"suspended\") {\n      const nextPollAt = result.nextPollAt ?? new Date(Date.now() + 60_000);\n      await this.jobTransport.suspend(msg.jobId, nextPollAt);\n      return { outcome: \"suspended\" };\n    }\n\n    // failed\n    const canRetry = msg.attempt < (msg.maxAttempts ?? 3);\n    await this.jobTransport.fail(\n      msg.jobId,\n      result.error ?? \"Unknown error\",\n      canRetry,\n    );\n    return { outcome: \"failed\", error: result.error };\n  }\n\n  async processAvailableJobs(opts?: {\n    maxJobs?: number;\n  }): Promise<ProcessJobsResult> {\n    const maxJobs = opts?.maxJobs ?? 1;\n    let processed = 0;\n    let succeeded = 0;\n    let failed = 0;\n\n    while (processed < maxJobs) {\n      const job = await this.jobTransport.dequeue();\n      if (!job) break;\n\n      const result = await this.handleJob({\n        jobId: job.jobId,\n        workflowRunId: job.workflowRunId,\n        workflowId: job.workflowId,\n        stageId: job.stageId,\n        attempt: job.attempt,\n        maxAttempts: job.maxAttempts,\n        payload: job.payload,\n      });\n\n      processed++;\n      if (result.outcome === \"failed\") {\n        failed++;\n      } else {\n        succeeded++;\n      }\n    }\n\n    return { processed, succeeded, failed };\n  }\n\n  async runMaintenanceTick(): Promise<MaintenanceTickResult> {\n    // 1. Claim pending runs → enqueue first-stage jobs\n    const claimResult = await this.kernel.dispatch({\n      type: \"run.claimPending\",\n      workerId: this.workerId,\n      maxClaims: this.maxClaimsPerTick,\n    });\n\n    // 2. Poll suspended stages → resume if ready\n    const pollResult = await this.kernel.dispatch({\n      type: \"stage.pollSuspended\",\n      maxChecks: this.maxSuspendedChecksPerTick,\n    });\n    for (const workflowRunId of pollResult.resumedWorkflowRunIds) {\n      await this.kernel.dispatch({\n        type: \"run.transition\",\n        workflowRunId,\n      });\n    }\n\n    // 3. Reap stale leases → release crashed worker locks\n    const reapResult = await this.kernel.dispatch({\n      type: \"lease.reapStale\",\n      staleThresholdMs: this.staleLeaseThresholdMs,\n    });\n\n    // 4. Flush outbox → publish pending events through EventSink\n    const flushResult = await this.kernel.dispatch({\n      type: \"outbox.flush\",\n      maxEvents: this.maxOutboxFlushPerTick,\n    });\n\n    return {\n      claimed: claimResult.claimed.length,\n      suspendedChecked: pollResult.checked,\n      staleReleased: reapResult.released,\n      eventsFlushed: flushResult.published,\n    };\n  }\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\nexport function createServerlessHost(\n  config: ServerlessHostConfig,\n): ServerlessHost {\n  return new ServerlessHostImpl(config);\n}\n"]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@bratsos/workflow-engine-host-serverless",
+  "version": "0.2.2",
+  "description": "Platform-agnostic serverless host for @bratsos/workflow-engine command kernel",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alex Bratsos",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@bratsos/workflow-engine": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "zod": "^4.1.12"
+  }
+}