@bratsos/workflow-engine-host-serverless 0.2.2 → 0.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Bratsos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -52,6 +52,7 @@ interface MaintenanceTickResult {
     suspendedChecked: number;
     staleReleased: number;
     eventsFlushed: number;
+    stuckReaped: number;
 }
 interface ServerlessHost {
     /** Execute a single pre-dequeued job. Returns outcome so consumer can ack/retry. */

package/dist/index.js

@@ -39,7 +39,8 @@ var ServerlessHostImpl = class {
       await this.jobTransport.suspend(msg.jobId, nextPollAt);
       return { outcome: "suspended" };
     }
-    const canRetry = msg.attempt < (msg.maxAttempts ?? 3);
+    const isGhostJob = result.error?.includes("ghost job discarded");
+    const canRetry = !isGhostJob && msg.attempt < (msg.maxAttempts ?? 3);
     await this.jobTransport.fail(
       msg.jobId,
       result.error ?? "Unknown error",
@@ -74,34 +75,69 @@ var ServerlessHostImpl = class {
     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
+    let claimed = 0;
+    let suspendedChecked = 0;
+    let staleReleased = 0;
+    let eventsFlushed = 0;
+    try {
+      const claimResult = await this.kernel.dispatch({
+        type: "run.claimPending",
+        workerId: this.workerId,
+        maxClaims: this.maxClaimsPerTick
       });
+      claimed = claimResult.claimed.length;
+    } catch (error) {
+      console.error("[ServerlessHost] run.claimPending error:", error);
+    }
+    try {
+      const pollResult = await this.kernel.dispatch({
+        type: "stage.pollSuspended",
+        maxChecks: this.maxSuspendedChecksPerTick
+      });
+      suspendedChecked = pollResult.checked;
+      for (const workflowRunId of pollResult.resumedWorkflowRunIds) {
+        await this.kernel.dispatch({
+          type: "run.transition",
+          workflowRunId
+        });
+      }
+    } catch (error) {
+      console.error("[ServerlessHost] stage.pollSuspended error:", error);
+    }
+    try {
+      const reapResult = await this.kernel.dispatch({
+        type: "lease.reapStale",
+        staleThresholdMs: this.staleLeaseThresholdMs
+      });
+      staleReleased = reapResult.released;
+    } catch (error) {
+      console.error("[ServerlessHost] lease.reapStale error:", error);
+    }
+    try {
+      const flushResult = await this.kernel.dispatch({
+        type: "outbox.flush",
+        maxEvents: this.maxOutboxFlushPerTick
+      });
+      eventsFlushed = flushResult.published;
+    } catch (error) {
+      console.error("[ServerlessHost] outbox.flush error:", error);
+    }
+    let stuckReaped = 0;
+    try {
+      const reapStuckResult = await this.kernel.dispatch({
+        type: "run.reapStuck",
+        stuckThresholdMs: Math.max(this.staleLeaseThresholdMs * 3, 5 * 6e4)
+      });
+      stuckReaped = reapStuckResult.failed;
+    } catch (error) {
+      console.error("[ServerlessHost] run.reapStuck error:", error);
     }
-    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
+      claimed,
+      suspendedChecked,
+      staleReleased,
+      eventsFlushed,
+      stuckReaped
     };
   }
 };

package/dist/index.js.map

@@ -1 +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"]}
+{"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  stuckReaped: 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 — ghost jobs should never be retried\n    const isGhostJob = result.error?.includes(\"ghost job discarded\");\n    const canRetry = !isGhostJob && 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    let claimed = 0;\n    let suspendedChecked = 0;\n    let staleReleased = 0;\n    let eventsFlushed = 0;\n\n    // 1. Claim pending runs → enqueue first-stage jobs\n    try {\n      const claimResult = await this.kernel.dispatch({\n        type: \"run.claimPending\",\n        workerId: this.workerId,\n        maxClaims: this.maxClaimsPerTick,\n      });\n      claimed = claimResult.claimed.length;\n    } catch (error) {\n      console.error(\"[ServerlessHost] run.claimPending error:\", error);\n    }\n\n    // 2. Poll suspended stages → resume if ready\n    try {\n      const pollResult = await this.kernel.dispatch({\n        type: \"stage.pollSuspended\",\n        maxChecks: this.maxSuspendedChecksPerTick,\n      });\n      suspendedChecked = pollResult.checked;\n      for (const workflowRunId of pollResult.resumedWorkflowRunIds) {\n        await this.kernel.dispatch({\n          type: \"run.transition\",\n          workflowRunId,\n        });\n      }\n    } catch (error) {\n      console.error(\"[ServerlessHost] stage.pollSuspended error:\", error);\n    }\n\n    // 3. Reap stale leases → release crashed worker locks\n    try {\n      const reapResult = await this.kernel.dispatch({\n        type: \"lease.reapStale\",\n        staleThresholdMs: this.staleLeaseThresholdMs,\n      });\n      staleReleased = reapResult.released;\n    } catch (error) {\n      console.error(\"[ServerlessHost] lease.reapStale error:\", error);\n    }\n\n    // 4. Flush outbox → publish pending events through EventSink\n    try {\n      const flushResult = await this.kernel.dispatch({\n        type: \"outbox.flush\",\n        maxEvents: this.maxOutboxFlushPerTick,\n      });\n      eventsFlushed = flushResult.published;\n    } catch (error) {\n      console.error(\"[ServerlessHost] outbox.flush error:\", error);\n    }\n\n    // 5. Reap stuck runs → fail runs with no activity past threshold\n    let stuckReaped = 0;\n    try {\n      const reapStuckResult = await this.kernel.dispatch({\n        type: \"run.reapStuck\",\n        stuckThresholdMs: Math.max(this.staleLeaseThresholdMs * 3, 5 * 60_000),\n      });\n      stuckReaped = reapStuckResult.failed;\n    } catch (error) {\n      console.error(\"[ServerlessHost] run.reapStuck error:\", error);\n    }\n\n    return {\n      claimed,\n      suspendedChecked,\n      staleReleased,\n      eventsFlushed,\n      stuckReaped,\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

@@ -1,10 +1,15 @@
 {
   "name": "@bratsos/workflow-engine-host-serverless",
-  "version": "0.2.2",
+  "version": "0.2.7",
   "description": "Platform-agnostic serverless host for @bratsos/workflow-engine command kernel",
   "type": "module",
   "license": "MIT",
   "author": "Alex Bratsos",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bratsos/workflow-engine",
+    "directory": "packages/workflow-engine-host-serverless"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -20,18 +25,18 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
-    "@bratsos/workflow-engine": "workspace:*"
+    "@bratsos/workflow-engine": "0.4.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "zod": "^4.1.12"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}