@pikku/queue-pg-boss 0.12.3 → 0.12.5

package/CHANGELOG.md

@@ -1,3 +1,81 @@
+## 0.12.5
+
+### Patch Changes
+
+- 05aba57: fix(scheduler): prune orphaned recurring-task schedules on start
+
+  When a scheduled task is removed from code, its pg-boss schedule row survived and
+  kept producing jobs into a queue with no registered worker — the jobs piled up as
+  'created' forever and could flood the queue (thousands of stuck jobs). `start()`
+  now drops any `pikku-recurring-scheduled-task_*` schedule and queue that is no
+  longer registered, so task removals self-heal on the next boot.
+
+- Updated dependencies [a8022e5]
+  - @pikku/core@0.12.43
+
+## 0.12.4
+
+### Patch Changes
+
+- 92cd5b1: feat(workflow): workflow-owned step retries + stable invocationId
+
+  The workflow — not the queue — now owns step retry policy, and each step
+  invocation gets a stable idempotency key.
+  - **Default `retries: 5` with exponential backoff.** A step with no `retries`
+    previously inherited the queue's bare default (e.g. pg-boss `retry_limit 2`,
+    no backoff) so retries fired instantly and couldn't outlast a transient
+    outage. Retries now default to 5 with backoff, resolved at the workflow layer.
+  - **`retries: 0` is honored.** Dispatch previously passed `undefined` options
+    for `retries: 0`, letting the queue re-run a non-idempotent step up to its own
+    default. The resolved policy now always sets `attempts` (`retries: 0` →
+    `attempts: 1`), so the queue never second-guesses the workflow. The persisted
+    step retries and the dispatched `attempts` are resolved together so
+    "retries exhausted" and "no more redeliveries" are the same event.
+  - **`workflowStep.invocationId`** — a deterministic, dependency-free
+    `uuidv5(runId:stepName)` handed to every step. Unlike `stepId` (minted per
+    attempt), it is identical across retries, so a step can dedupe on it
+    (`ON CONFLICT (invocationId)`, Stripe idempotency keys, etc.).
+  - **queue-bullmq**: `mapPikkuJobToBull` now maps `backoff` (previously dropped,
+    so a step's backoff silently never applied on Redis), and `registerQueues`
+    throws a clear error when no logger is available (matching queue-pg-boss).
+  - **Dispatch failures are recoverable, not fatal.** A step is now marked
+    `scheduled` only _after_ it is successfully handed to its transport (queue or
+    scheduler) — a failed hand-off leaves it `pending` so a replay re-dispatches
+    it, instead of stranding it in `scheduled` (replay would pause forever on a
+    job that was never enqueued). A transport outage (e.g. pg-boss momentarily
+    down) is surfaced as a new `WorkflowDispatchException`, which the orchestrator
+    treats as transient: the run is left running and the orchestrator job is
+    rethrown for redelivery (it replays idempotently from the snapshot) rather
+    than the whole run being marked `failed`. The orchestrator job now also
+    carries its own retry policy, so this holds even when the orchestrator queue
+    is configured `retry_limit 0`. A genuine step error still fails the run.
+  - **Same step name can be invoked multiple times in one run.** Step rows are now
+    keyed per _invocation_: the Nth reach of a step name in a replay resolves to a
+    physical key (`name` for the first, `name#N` for repeats), so a literal
+    duplicate name no longer clobbers the earlier step's state. The first reach
+    keeps the bare name, so existing rows, graph-node matching and `invocationId`s
+    are unchanged. Ordinals are derived deterministically from DSL execution order
+    and reset each replay.
+  - **Step provenance (`fromStepName`) + graph cycles.** Every step now records
+    the predecessor it was scheduled from (`fromStepName`; entry steps have none),
+    persisted on the step row across all stores (in-memory, kysely, redis,
+    mongodb, cloudflare DO) and carried in the queued payload. The DSL wire
+    exposes the derived `fromInvocationId` (`uuidv5(runId:fromStepName)`) so
+    consumers get the stable predecessor key without a second persisted id —
+    `fromStepName` is the source of truth (it is replay-deterministic; `stepId`,
+    minted per row, is not). This makes the walked path reconstructable even when
+    a node is reached more than once: in `a → b → a → c` the second `a` is a
+    distinct ordinal instance (`a#1`) whose `fromStepName` is `b`.
+    The graph runner now supports **cycles**: a forward edge into an
+    already-started node still collapses to a single run (joins/diamonds are
+    unchanged), but a _back-edge_ — one whose target can reach its source — fires
+    a fresh ordinal instance, so a node can loop back to itself. Termination is
+    the graph's responsibility (branch routing must converge); the engine enforces
+    no visit cap.
+
+- Updated dependencies [92cd5b1]
+  - @pikku/core@0.12.38
+
 ## 0.12.0
 
 ## 0.12.3

package/dist/pg-boss-scheduler-service.js

@@ -1,6 +1,8 @@
 import { SchedulerService, parseDurationString } from '@pikku/core';
 import { pikkuState } from '@pikku/core/internal';
 import { runScheduledTask, getScheduledTasks } from '@pikku/core/scheduler';
+/** Prefix for pg-boss queues/schedules backing recurring scheduled tasks. */
+const RECURRING_TASK_PREFIX = 'pikku-recurring-scheduled-task_';
 /**
  * pg-boss scheduler service implementation
  * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL.
@@ -88,8 +90,10 @@ export class PgBossSchedulerService extends SchedulerService {
     async start() {
         const logger = pikkuState(null, 'package', 'singletonServices').logger;
         const scheduledTasks = getScheduledTasks();
+        const expectedCronNames = new Set();
         for (const [name, task] of scheduledTasks) {
-            const cronName = `pikku-recurring-scheduled-task_${name.replace(/[^a-zA-Z0-9_\-.]/g, '_')}`;
+            const cronName = `${RECURRING_TASK_PREFIX}${name.replace(/[^a-zA-Z0-9_\-.]/g, '_')}`;
+            expectedCronNames.add(cronName);
             await this.pgBoss.createQueue(cronName);
             await this.pgBoss.schedule(cronName, task.schedule, {
                 rpcName: name,
@@ -104,6 +108,25 @@ export class PgBossSchedulerService extends SchedulerService {
                 }
             });
         }
+        // Prune orphaned schedules. A task removed from code leaves its pg-boss
+        // schedule behind; with no worker registered it keeps producing jobs that
+        // pile up as 'created' forever (this is how a removed task flooded a queue
+        // with thousands of stuck jobs). Drop any recurring schedule + queue that's
+        // no longer registered so task removals self-heal on the next boot.
+        try {
+            const existing = await this.pgBoss.getSchedules();
+            for (const schedule of existing) {
+                if (schedule.name.startsWith(RECURRING_TASK_PREFIX) &&
+                    !expectedCronNames.has(schedule.name)) {
+                    await this.pgBoss.unschedule(schedule.name);
+                    await this.pgBoss.deleteQueue(schedule.name);
+                    logger.warn(`Pruned orphaned scheduled task queue: ${schedule.name}`);
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to prune orphaned scheduled tasks: ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     /**
      * Stop recurring scheduled tasks by unscheduling them from pg-boss.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/queue-pg-boss",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -8,18 +8,22 @@
   "type": "module",
   "scripts": {
     "tsc": "tsc",
+    "test": "bash run-tests.sh",
     "ncu": "npx npm-check-updates",
     "build": "tsc -b",
     "release": "npm run build && npm test",
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.9"
+    "@pikku/core": "^0.12.43"
   },
   "dependencies": {
     "pg-boss": "^12.14.0"
   },
   "devDependencies": {
     "typescript": "^5.9"
+  },
+  "exports": {
+    ".": "./dist/index.js"
   }
 }

package/run-tests.sh

@@ -1,3 +1,5 @@
 #!/bin/bash
 cd "$(dirname "$0")"
-node --loader tsx --test --experimental-test-coverage src/**/*.test.ts "$@"
+files=($(find src -type f -name "*.test.ts"))
+if [ ${#files[@]} -eq 0 ]; then echo "No test files found"; exit 0; fi
+node --import tsx --test "$@" "${files[@]}"

package/src/pg-boss-queue-service.test.ts

@@ -0,0 +1,51 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { mapPikkuJobToPgBoss } from './pg-boss-queue-service.js'
+
+// These guard the contract the workflow engine relies on: a step's resolved
+// retry policy (attempts + backoff) must survive translation into pg-boss
+// terms, so "workflow owns retries" actually reaches the queue.
+describe('mapPikkuJobToPgBoss — retry mapping', () => {
+  test('attempts → retryLimit (attempts - 1)', () => {
+    // Default policy: 5 retries → 6 attempts → retryLimit 5.
+    assert.equal(mapPikkuJobToPgBoss({ attempts: 6 }).retryLimit, 5)
+  })
+
+  test('attempts: 1 (retries: 0) → retryLimit 0 (pg-boss never re-runs it)', () => {
+    assert.equal(mapPikkuJobToPgBoss({ attempts: 1 }).retryLimit, 0)
+  })
+
+  test("backoff 'exponential' → retryBackoff true", () => {
+    assert.equal(
+      mapPikkuJobToPgBoss({ attempts: 6, backoff: 'exponential' })
+        .retryBackoff,
+      true
+    )
+  })
+
+  test('fixed backoff → retryBackoff false + retryDelay in seconds', () => {
+    const opts = mapPikkuJobToPgBoss({
+      attempts: 4,
+      backoff: { type: 'fixed', delay: 5000 },
+    })
+    assert.equal(opts.retryBackoff, false)
+    // pg-boss takes seconds; our delay is milliseconds.
+    assert.equal(opts.retryDelay, 5)
+  })
+
+  test('exponential object backoff → retryBackoff true + retryDelay in seconds', () => {
+    const opts = mapPikkuJobToPgBoss({
+      attempts: 4,
+      backoff: { type: 'exponential', delay: 2000 },
+    })
+    assert.equal(opts.retryBackoff, true)
+    assert.equal(opts.retryDelay, 2)
+  })
+
+  test('no options → no retry fields set', () => {
+    const opts = mapPikkuJobToPgBoss(undefined)
+    assert.equal(opts.retryLimit, undefined)
+    assert.equal(opts.retryBackoff, undefined)
+  })
+})

package/src/pg-boss-queue-worker.test.ts

@@ -4,12 +4,12 @@ import assert from 'node:assert/strict'
 import { PgBossQueueWorkers } from './pg-boss-queue-worker.js'
 
 describe('PgBossQueueWorkers', () => {
-  test('requires setJobRunner before registerQueues', async () => {
+  test('requires a logger (explicit or from singleton services)', async () => {
     const workers = new PgBossQueueWorkers({} as any)
 
     await assert.rejects(() => workers.registerQueues(), {
       message:
-        'PgBossQueueWorkers requires setJobRunner() before registerQueues()',
+        'Logger is required for registerQueues — pass it explicitly or ensure singleton services are initialized first',
     })
   })
 })

package/src/pg-boss-scheduler-service.ts

@@ -17,6 +17,9 @@ interface ScheduledJobData {
   session?: CoreUserSession
 }
 
+/** Prefix for pg-boss queues/schedules backing recurring scheduled tasks. */
+const RECURRING_TASK_PREFIX = 'pikku-recurring-scheduled-task_'
+
 /**
  * pg-boss scheduler service implementation
  * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL.
@@ -131,8 +134,10 @@ export class PgBossSchedulerService extends SchedulerService {
     const logger = pikkuState(null, 'package', 'singletonServices')!.logger
     const scheduledTasks = getScheduledTasks()
 
+    const expectedCronNames = new Set<string>()
     for (const [name, task] of scheduledTasks) {
-      const cronName = `pikku-recurring-scheduled-task_${name.replace(/[^a-zA-Z0-9_\-.]/g, '_')}`
+      const cronName = `${RECURRING_TASK_PREFIX}${name.replace(/[^a-zA-Z0-9_\-.]/g, '_')}`
+      expectedCronNames.add(cronName)
       await this.pgBoss.createQueue(cronName)
       await this.pgBoss.schedule(cronName, task.schedule, {
         rpcName: name,
@@ -148,6 +153,29 @@ export class PgBossSchedulerService extends SchedulerService {
         }
       })
     }
+
+    // Prune orphaned schedules. A task removed from code leaves its pg-boss
+    // schedule behind; with no worker registered it keeps producing jobs that
+    // pile up as 'created' forever (this is how a removed task flooded a queue
+    // with thousands of stuck jobs). Drop any recurring schedule + queue that's
+    // no longer registered so task removals self-heal on the next boot.
+    try {
+      const existing = await this.pgBoss.getSchedules()
+      for (const schedule of existing) {
+        if (
+          schedule.name.startsWith(RECURRING_TASK_PREFIX) &&
+          !expectedCronNames.has(schedule.name)
+        ) {
+          await this.pgBoss.unschedule(schedule.name)
+          await this.pgBoss.deleteQueue(schedule.name)
+          logger.warn(`Pruned orphaned scheduled task queue: ${schedule.name}`)
+        }
+      }
+    } catch (err) {
+      logger.warn(
+        `Failed to prune orphaned scheduled tasks: ${err instanceof Error ? err.message : String(err)}`
+      )
+    }
   }
 
   /**