@bratsos/workflow-engine-host-node 0.2.2

package/README.md

@@ -0,0 +1,120 @@
+# @bratsos/workflow-engine-host-node
+
+Node.js host for the [`@bratsos/workflow-engine`](../workflow-engine) command kernel. Provides process loops, signal handling, and continuous job processing.
+
+## Installation
+
+```bash
+npm install @bratsos/workflow-engine-host-node
+```
+
+## Quick Start
+
+```typescript
+import { createKernel } from "@bratsos/workflow-engine/kernel";
+import { createNodeHost } from "@bratsos/workflow-engine-host-node";
+import { createPrismaJobQueue } from "@bratsos/workflow-engine";
+
+const kernel = createKernel({ /* ... */ });
+const jobTransport = createPrismaJobQueue(prisma);
+
+const host = createNodeHost({
+  kernel,
+  jobTransport,
+  workerId: "worker-1",
+});
+
+await host.start();
+```
+
+## API
+
+### `createNodeHost(config): NodeHost`
+
+Creates a new Node host instance.
+
+### `NodeHostConfig`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `kernel` | `Kernel` | required | Kernel instance to dispatch commands to |
+| `jobTransport` | `JobTransport` | required | Job transport for dequeue/complete/suspend/fail |
+| `workerId` | `string` | required | Unique worker identifier |
+| `orchestrationIntervalMs` | `number` | `10_000` | Interval for claim/poll/reap/flush orchestration tick |
+| `jobPollIntervalMs` | `number` | `1_000` | Interval for polling job queue when empty |
+| `staleLeaseThresholdMs` | `number` | `60_000` | Time before a job lease is considered stale |
+| `maxClaimsPerTick` | `number` | `10` | Max pending runs to claim per orchestration tick |
+| `maxSuspendedChecksPerTick` | `number` | `10` | Max suspended stages to poll per tick |
+| `maxOutboxFlushPerTick` | `number` | `100` | Max outbox events to flush per tick |
+
+### `NodeHost`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `start()` | `Promise<void>` | Start polling loops and register SIGTERM/SIGINT handlers |
+| `stop()` | `Promise<void>` | Graceful shutdown -- clears timers and signal handlers |
+| `getStats()` | `HostStats` | Runtime statistics |
+
+### `HostStats`
+
+```typescript
+interface HostStats {
+  workerId: string;
+  jobsProcessed: number;
+  orchestrationTicks: number;
+  isRunning: boolean;
+  uptimeMs: number;
+}
+```
+
+## How It Works
+
+The host runs two concurrent loops:
+
+1. **Orchestration timer** (every `orchestrationIntervalMs`):
+   - `run.claimPending` -- claim pending runs, enqueue first-stage jobs
+   - `stage.pollSuspended` -- check if suspended stages are ready to resume
+   - `lease.reapStale` -- release stale job leases from crashed workers
+   - `outbox.flush` -- publish pending events through EventSink
+
+2. **Job processing loop** (continuous):
+   - Dequeue next job from `jobTransport`
+   - Dispatch `job.execute` to the kernel
+   - On completion: mark complete, dispatch `run.transition`
+   - On suspension: mark suspended with next poll time
+   - On failure: mark failed with retry flag
+   - Sleep `jobPollIntervalMs` when queue is empty
+
+Signal handlers (`SIGTERM`, `SIGINT`) automatically call `stop()` for graceful shutdown.
+
+## Worker Process Pattern
+
+```typescript
+// worker.ts
+import { host } from "./setup";
+
+await host.start();
+// Host runs until SIGTERM/SIGINT or host.stop() is called
+```
+
+```bash
+npx tsx worker.ts
+```
+
+## Multi-Worker
+
+Multiple workers can share the same database. Each needs a unique `workerId`:
+
+```typescript
+// worker-1
+createNodeHost({ kernel, jobTransport, workerId: "worker-1" });
+
+// worker-2
+createNodeHost({ kernel, jobTransport, workerId: "worker-2" });
+```
+
+Run claiming uses `FOR UPDATE SKIP LOCKED` in PostgreSQL to prevent race conditions.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { Kernel, JobTransport } from '@bratsos/workflow-engine/kernel';
+
+/**
+ * Node Host for Workflow Engine Command Kernel
+ *
+ * Wraps the environment-agnostic kernel with Node.js process loops,
+ * signal handling, and job processing. The host dispatches kernel
+ * commands on intervals and manages the job dequeue/execute cycle.
+ *
+ * The kernel remains unaware of process state — all timers, signals,
+ * and loop pacing live here.
+ */
+
+interface NodeHostConfig {
+    /** Kernel instance to dispatch commands to. */
+    kernel: Kernel;
+    /** Job transport for dequeue/complete/suspend/fail. */
+    jobTransport: JobTransport;
+    /** Unique worker identifier. */
+    workerId: string;
+    /** Orchestration poll interval in milliseconds (default: 10_000). */
+    orchestrationIntervalMs?: number;
+    /** Job dequeue poll interval when queue is empty (default: 1_000). */
+    jobPollIntervalMs?: number;
+    /** Stale lease threshold in milliseconds (default: 60_000). */
+    staleLeaseThresholdMs?: number;
+    /** Max pending runs to claim per orchestration 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;
+}
+interface HostStats {
+    workerId: string;
+    jobsProcessed: number;
+    orchestrationTicks: number;
+    isRunning: boolean;
+    uptimeMs: number;
+}
+interface NodeHost {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStats(): HostStats;
+}
+declare function createNodeHost(config: NodeHostConfig): NodeHost;
+
+export { type HostStats, type NodeHost, type NodeHostConfig, createNodeHost };

package/dist/index.js

@@ -0,0 +1,162 @@
+// src/host.ts
+var NodeHostImpl = class {
+  running = false;
+  jobsProcessed = 0;
+  orchestrationTicks = 0;
+  startTime = 0;
+  orchestrationTimer = null;
+  signalHandlers = [];
+  kernel;
+  jobTransport;
+  workerId;
+  orchestrationIntervalMs;
+  jobPollIntervalMs;
+  staleLeaseThresholdMs;
+  maxClaimsPerTick;
+  maxSuspendedChecksPerTick;
+  maxOutboxFlushPerTick;
+  constructor(config) {
+    this.kernel = config.kernel;
+    this.jobTransport = config.jobTransport;
+    this.workerId = config.workerId;
+    this.orchestrationIntervalMs = config.orchestrationIntervalMs ?? 1e4;
+    this.jobPollIntervalMs = config.jobPollIntervalMs ?? 1e3;
+    this.staleLeaseThresholdMs = config.staleLeaseThresholdMs ?? 6e4;
+    this.maxClaimsPerTick = config.maxClaimsPerTick ?? 10;
+    this.maxSuspendedChecksPerTick = config.maxSuspendedChecksPerTick ?? 10;
+    this.maxOutboxFlushPerTick = config.maxOutboxFlushPerTick ?? 100;
+  }
+  // --------------------------------------------------------------------------
+  // Lifecycle
+  // --------------------------------------------------------------------------
+  async start() {
+    if (this.running) return;
+    this.running = true;
+    this.startTime = Date.now();
+    this.orchestrationTimer = setInterval(
+      () => void this.orchestrationTick(),
+      this.orchestrationIntervalMs
+    );
+    void this.orchestrationTick();
+    void this.processJobs();
+    const onSignal = () => void this.stop();
+    this.signalHandlers = [
+      { signal: "SIGTERM", handler: onSignal },
+      { signal: "SIGINT", handler: onSignal }
+    ];
+    for (const { signal, handler } of this.signalHandlers) {
+      process.once(signal, handler);
+    }
+  }
+  async stop() {
+    if (!this.running) return;
+    this.running = false;
+    if (this.orchestrationTimer) {
+      clearInterval(this.orchestrationTimer);
+      this.orchestrationTimer = null;
+    }
+    for (const { signal, handler } of this.signalHandlers) {
+      process.removeListener(signal, handler);
+    }
+    this.signalHandlers = [];
+  }
+  getStats() {
+    return {
+      workerId: this.workerId,
+      jobsProcessed: this.jobsProcessed,
+      orchestrationTicks: this.orchestrationTicks,
+      isRunning: this.running,
+      uptimeMs: this.running ? Date.now() - this.startTime : 0
+    };
+  }
+  // --------------------------------------------------------------------------
+  // Orchestration timer
+  // --------------------------------------------------------------------------
+  async orchestrationTick() {
+    try {
+      this.orchestrationTicks++;
+      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
+        });
+      }
+      await this.kernel.dispatch({
+        type: "lease.reapStale",
+        staleThresholdMs: this.staleLeaseThresholdMs
+      });
+      await this.kernel.dispatch({
+        type: "outbox.flush",
+        maxEvents: this.maxOutboxFlushPerTick
+      });
+    } catch (error) {
+      console.error("[NodeHost] Orchestration tick error:", error);
+    }
+  }
+  // --------------------------------------------------------------------------
+  // Job processing loop
+  // --------------------------------------------------------------------------
+  async processJobs() {
+    while (this.running) {
+      try {
+        const job = await this.jobTransport.dequeue();
+        if (!job) {
+          await this.sleep(this.jobPollIntervalMs);
+          continue;
+        }
+        const config = job.payload.config || {};
+        const result = await this.kernel.dispatch({
+          type: "job.execute",
+          idempotencyKey: `job:${job.jobId}:attempt:${job.attempt}`,
+          workflowRunId: job.workflowRunId,
+          workflowId: job.workflowId,
+          stageId: job.stageId,
+          config
+        });
+        this.jobsProcessed++;
+        if (result.outcome === "completed") {
+          await this.jobTransport.complete(job.jobId);
+          await this.kernel.dispatch({
+            type: "run.transition",
+            workflowRunId: job.workflowRunId
+          });
+        } else if (result.outcome === "suspended") {
+          const nextPollAt = result.nextPollAt ?? new Date(Date.now() + 6e4);
+          await this.jobTransport.suspend(job.jobId, nextPollAt);
+        } else if (result.outcome === "failed") {
+          const canRetry = job.attempt < (job.maxAttempts ?? 3);
+          await this.jobTransport.fail(
+            job.jobId,
+            result.error ?? "Unknown error",
+            canRetry
+          );
+        }
+      } catch (error) {
+        console.error("[NodeHost] Job processing error:", error);
+        await this.sleep(5e3);
+      }
+    }
+  }
+  // --------------------------------------------------------------------------
+  // Helpers
+  // --------------------------------------------------------------------------
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+function createNodeHost(config) {
+  return new NodeHostImpl(config);
+}
+
+export { createNodeHost };
+//# 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 * Node Host for Workflow Engine Command Kernel\n *\n * Wraps the environment-agnostic kernel with Node.js process loops,\n * signal handling, and job processing. The host dispatches kernel\n * commands on intervals and manages the job dequeue/execute cycle.\n *\n * The kernel remains unaware of process state — all timers, signals,\n * and loop pacing live here.\n */\n\nimport type { JobTransport, Kernel } from \"@bratsos/workflow-engine/kernel\";\n\n// ============================================================================\n// Public interfaces\n// ============================================================================\n\nexport interface NodeHostConfig {\n  /** Kernel instance to dispatch commands to. */\n  kernel: Kernel;\n\n  /** Job transport for dequeue/complete/suspend/fail. */\n  jobTransport: JobTransport;\n\n  /** Unique worker identifier. */\n  workerId: string;\n\n  /** Orchestration poll interval in milliseconds (default: 10_000). */\n  orchestrationIntervalMs?: number;\n\n  /** Job dequeue poll interval when queue is empty (default: 1_000). */\n  jobPollIntervalMs?: number;\n\n  /** Stale lease threshold in milliseconds (default: 60_000). */\n  staleLeaseThresholdMs?: number;\n\n  /** Max pending runs to claim per orchestration 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\nexport interface HostStats {\n  workerId: string;\n  jobsProcessed: number;\n  orchestrationTicks: number;\n  isRunning: boolean;\n  uptimeMs: number;\n}\n\nexport interface NodeHost {\n  start(): Promise<void>;\n  stop(): Promise<void>;\n  getStats(): HostStats;\n}\n\n// ============================================================================\n// Implementation\n// ============================================================================\n\nclass NodeHostImpl implements NodeHost {\n  private running = false;\n  private jobsProcessed = 0;\n  private orchestrationTicks = 0;\n  private startTime = 0;\n  private orchestrationTimer: ReturnType<typeof setInterval> | null = null;\n  private signalHandlers: { signal: string; handler: () => void }[] = [];\n\n  private readonly kernel: Kernel;\n  private readonly jobTransport: JobTransport;\n  private readonly workerId: string;\n  private readonly orchestrationIntervalMs: number;\n  private readonly jobPollIntervalMs: number;\n  private readonly staleLeaseThresholdMs: number;\n  private readonly maxClaimsPerTick: number;\n  private readonly maxSuspendedChecksPerTick: number;\n  private readonly maxOutboxFlushPerTick: number;\n\n  constructor(config: NodeHostConfig) {\n    this.kernel = config.kernel;\n    this.jobTransport = config.jobTransport;\n    this.workerId = config.workerId;\n    this.orchestrationIntervalMs = config.orchestrationIntervalMs ?? 10_000;\n    this.jobPollIntervalMs = config.jobPollIntervalMs ?? 1_000;\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  // --------------------------------------------------------------------------\n  // Lifecycle\n  // --------------------------------------------------------------------------\n\n  async start(): Promise<void> {\n    if (this.running) return;\n\n    this.running = true;\n    this.startTime = Date.now();\n\n    // Start orchestration timer\n    this.orchestrationTimer = setInterval(\n      () => void this.orchestrationTick(),\n      this.orchestrationIntervalMs,\n    );\n\n    // Immediate first tick\n    void this.orchestrationTick();\n\n    // Start job processing loop (runs until stop())\n    void this.processJobs();\n\n    // Signal handlers — use wrapper functions so we can remove them on stop\n    const onSignal = () => void this.stop();\n    this.signalHandlers = [\n      { signal: \"SIGTERM\", handler: onSignal },\n      { signal: \"SIGINT\", handler: onSignal },\n    ];\n    for (const { signal, handler } of this.signalHandlers) {\n      process.once(signal as NodeJS.Signals, handler);\n    }\n  }\n\n  async stop(): Promise<void> {\n    if (!this.running) return;\n\n    this.running = false;\n\n    if (this.orchestrationTimer) {\n      clearInterval(this.orchestrationTimer);\n      this.orchestrationTimer = null;\n    }\n\n    // Remove signal handlers to avoid leaks\n    for (const { signal, handler } of this.signalHandlers) {\n      process.removeListener(signal, handler);\n    }\n    this.signalHandlers = [];\n  }\n\n  getStats(): HostStats {\n    return {\n      workerId: this.workerId,\n      jobsProcessed: this.jobsProcessed,\n      orchestrationTicks: this.orchestrationTicks,\n      isRunning: this.running,\n      uptimeMs: this.running ? Date.now() - this.startTime : 0,\n    };\n  }\n\n  // --------------------------------------------------------------------------\n  // Orchestration timer\n  // --------------------------------------------------------------------------\n\n  private async orchestrationTick(): Promise<void> {\n    try {\n      this.orchestrationTicks++;\n\n      // 1. Claim pending runs → enqueue first-stage jobs\n      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      await this.kernel.dispatch({\n        type: \"lease.reapStale\",\n        staleThresholdMs: this.staleLeaseThresholdMs,\n      });\n\n      // 4. Flush outbox → publish pending events through EventSink\n      await this.kernel.dispatch({\n        type: \"outbox.flush\",\n        maxEvents: this.maxOutboxFlushPerTick,\n      });\n    } catch (error) {\n      // Orchestration errors are non-fatal — the next tick will retry\n      console.error(\"[NodeHost] Orchestration tick error:\", error);\n    }\n  }\n\n  // --------------------------------------------------------------------------\n  // Job processing loop\n  // --------------------------------------------------------------------------\n\n  private async processJobs(): Promise<void> {\n    while (this.running) {\n      try {\n        const job = await this.jobTransport.dequeue();\n\n        if (!job) {\n          await this.sleep(this.jobPollIntervalMs);\n          continue;\n        }\n\n        const config =\n          (job.payload as { config?: Record<string, unknown> }).config || {};\n\n        const result = await this.kernel.dispatch({\n          type: \"job.execute\",\n          idempotencyKey: `job:${job.jobId}:attempt:${job.attempt}`,\n          workflowRunId: job.workflowRunId,\n          workflowId: job.workflowId,\n          stageId: job.stageId,\n          config,\n        });\n\n        this.jobsProcessed++;\n\n        if (result.outcome === \"completed\") {\n          await this.jobTransport.complete(job.jobId);\n          await this.kernel.dispatch({\n            type: \"run.transition\",\n            workflowRunId: job.workflowRunId,\n          });\n        } else if (result.outcome === \"suspended\") {\n          const nextPollAt = result.nextPollAt ?? new Date(Date.now() + 60_000);\n          await this.jobTransport.suspend(job.jobId, nextPollAt);\n        } else if (result.outcome === \"failed\") {\n          const canRetry = job.attempt < (job.maxAttempts ?? 3);\n          await this.jobTransport.fail(\n            job.jobId,\n            result.error ?? \"Unknown error\",\n            canRetry,\n          );\n        }\n      } catch (error) {\n        // Job processing errors are non-fatal — back off and retry\n        console.error(\"[NodeHost] Job processing error:\", error);\n        await this.sleep(5_000);\n      }\n    }\n  }\n\n  // --------------------------------------------------------------------------\n  // Helpers\n  // --------------------------------------------------------------------------\n\n  private sleep(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\nexport function createNodeHost(config: NodeHostConfig): NodeHost {\n  return new NodeHostImpl(config);\n}\n"]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@bratsos/workflow-engine-host-node",
+  "version": "0.2.2",
+  "description": "Node.js 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": {
+    "@types/node": "^22",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "zod": "^4.1.12"
+  },
+  "engines": {
+    "node": ">=22.11.0"
+  }
+}