@blamejs/core 0.8.43 → 0.8.49

package/lib/queue.js

@@ -1,34 +1,45 @@
 "use strict";
 /**
- * Queue dispatcher — pluggable job queue with retry, lease semantics, and
- * graceful shutdown.
- *
- * Same dispatcher pattern as object-store: backends are configured per-name,
- * each with a protocol + protocol-specific options. The built-in 'local'
- * protocol is SQLite-backed (baked into the framework's main DB).
- * External protocols (redis, sqs, amqp, nats) are listed as deferred and
- * surface a clear error when selected.
- *
- * Public API:
- *   queue.init({ backends: { name: { protocol: 'local' } }, defaultBackend? })
- *   queue.enqueue(queueName, payload, opts?)
- *                                       → { jobId, queueName, ... }
- *   queue.consume(queueName, handler, opts?)
- *                                       → consumer handle (with cancel())
- *   queue.size(queueName, opts?)        → number (pending + inflight)
- *   queue.purge(queueName, opts?)       → number deleted
- *   queue.shutdown(opts?)               → drain handlers gracefully
- *   queue.listBackends()                → [{ name, protocol }]
- *
- * Job lifecycle:
- *   enqueued (status='pending')
- *     ↓ availableAt reached + consumer leases
- *   inflight (status='inflight', lease expires after leaseDurationMs)
- *     ↓ handler returns                 ↓ handler throws
- *   done (status='done')              if attempts < maxAttempts:
- *                                       pending (with backoff)
- *                                     else:
- *                                       failed (status='failed')
+ * @module b.queue
+ * @nav    Data
+ * @title  Queue
+ *
+ * @intro
+ *   Durable, pluggable job queue with priority-aware leasing, retry +
+ *   deterministic backoff, graceful shutdown, parent/child flows, and
+ *   a dead-letter surface for jobs that exhaust their retries.
+ *
+ *   Same dispatcher shape as `b.objectStore`: every operator-named
+ *   backend declares a `protocol` plus protocol-specific options. The
+ *   built-in `local` protocol is SQLite-backed (rows live in the
+ *   framework's main DB so persistence survives crashes / restarts
+ *   without external infrastructure). `redis` and `sqs` ship; `amqp`
+ *   and `nats` are listed as deferred and surface a clear error if
+ *   selected.
+ *
+ *   Job lifecycle:
+ *     enqueued (status='pending', availableAt set by delaySeconds)
+ *       ↓ availableAt reached + consumer leases
+ *     inflight (status='inflight', lease expires after leaseDurationMs)
+ *       ↓ handler returns                 ↓ handler throws
+ *     done   (status='done')           attempts < maxAttempts:
+ *                                        pending (with deterministic backoff)
+ *                                      else:
+ *                                        failed → DLQ row written
+ *
+ *   A 30-second sweep timer re-pends inflight rows whose lease expired
+ *   without completion (crashed handlers, OOM kills) so no job is
+ *   abandoned. Within a single millisecond, higher `priority` jobs
+ *   lease before lower-priority ones (deterministic — see
+ *   `b.queue.enqueue` opts).
+ *
+ *   Dead-letter handling: jobs that exhaust `maxAttempts` write a
+ *   `system.queue.dlq.write` audit event and stay queryable via
+ *   `b.queue.dlqList`. Operator decides whether to retry
+ *   (`b.queue.dlqRetry`) — never automatic.
+ *
+ * @card
+ *   Durable, pluggable job queue with priority-aware leasing, retry + deterministic backoff, graceful shutdown, parent/child flows, and a dead-letter surface for jobs that exhaust their retries.
  */
 var C = require("./constants");
 var clusterStorage = require("./cluster-storage");
@@ -68,6 +79,43 @@ var defaultBackend = null;
 var consumers = [];   // [{ queueName, backendName, cancel(), running, inFlight: Set }]
 var sweepTimer = null;
 
+/**
+ * @primitive b.queue.init
+ * @signature b.queue.init(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.bootFromEnv, b.queue.shutdown, b.queue.listBackends
+ *
+ * One-time initialization. Wires every named backend through the
+ * protocol dispatcher, wraps mutating ops with the retry helper +
+ * circuit breaker, and starts the 30-second expired-lease sweep.
+ * Idempotent — calling `init` after the queue is already initialized
+ * is a no-op (boot order doesn't have to be exact).
+ *
+ * Throws when `opts.backends` is missing — operators catch the typo
+ * at boot rather than discovering it on first enqueue.
+ *
+ * @opts
+ *   backends: {
+ *     [name: string]: {
+ *       protocol:  "local" | "redis" | "sqs",
+ *       breaker?:  { ... },   // see b.retry.CircuitBreaker opts
+ *       retry?:    { ... },   // see b.retry.withRetry opts
+ *       // ...protocol-specific opts (e.g. redis url, sqs queueUrl)
+ *     },
+ *   },
+ *   defaultBackend?: string,  // name to use when enqueue/consume omit { backend }
+ *
+ * @example
+ *   b.queue.init({
+ *     backends: {
+ *       primary: { protocol: "local" },
+ *     },
+ *     defaultBackend: "primary",
+ *   });
+ *   b.queue.listBackends();
+ *   // → [{ name: "primary", protocol: "local", breakerState: "closed" }]
+ */
 function init(opts) {
   if (initialized) return;
   if (!opts || !opts.backends) {
@@ -151,6 +199,42 @@ function _backendFor(opts) {
 
 // ---- Public API ----
 
+/**
+ * @primitive b.queue.enqueue
+ * @signature b.queue.enqueue(queueName, payload, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.consume, b.queue.enqueueFlow, b.queue.size
+ *
+ * Persists a single job to the named queue and returns a promise that
+ * resolves with the assigned `jobId`. The job's `payload` is stored
+ * verbatim by the backend (the `local` protocol JSON-encodes; redis
+ * and sqs follow their wire formats). Resolves before any consumer
+ * actually leases the job — `enqueue` is durable handoff, not
+ * synchronous execution.
+ *
+ * Higher `priority` jobs lease ahead of lower ones within the same
+ * `availableAt` window. `delaySeconds` parks the job until the
+ * timestamp arrives. `maxAttempts` overrides the queue default; on
+ * the final attempt the job moves to the dead-letter view rather
+ * than retrying again.
+ *
+ * @opts
+ *   backend?:        string,   // backend name; defaults to defaultBackend
+ *   priority?:       number,   // higher leases first (default 0)
+ *   delaySeconds?:   number,   // park before becoming leaseable
+ *   maxAttempts?:    number,   // retries before DLQ (backend default applies)
+ *   classification?: string,   // operator metadata, surfaced in audit
+ *   traceId?:        string,   // cross-request correlation id
+ *
+ * @example
+ *   var result = await b.queue.enqueue("ingest", { url: "https://example.com" }, {
+ *     priority:     5,
+ *     maxAttempts:  3,
+ *   });
+ *   result.jobId;
+ *   // → "job-7c2f8e1a..."
+ */
 function enqueue(queueName, payload, opts) {
   _requireInit();
   if (!queueName) throw _err("MISSING_QUEUE", "enqueue requires queueName", true);
@@ -176,6 +260,50 @@ function enqueue(queueName, payload, opts) {
   );
 }
 
+/**
+ * @primitive b.queue.consume
+ * @signature b.queue.consume(queueName, handler, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.enqueue, b.queue.shutdown, b.queue.dlqRetry
+ *
+ * Starts a long-running consumer that leases jobs and runs them
+ * through `handler(job, ctx)`. Handler resolution marks the job
+ * `done`; rejection bumps the attempt counter and either re-pends
+ * with deterministic exponential backoff (1s base, 5min cap, no
+ * jitter) or routes to the DLQ when `attempts >= maxAttempts`.
+ *
+ * Returns a consumer state handle whose `.cancel()` aborts the poll
+ * loop immediately (without waiting for the next `pollIntervalMs`
+ * tick) and stops leasing new work. In-flight handlers complete on
+ * their own; `b.queue.shutdown` waits for them with a deadline.
+ *
+ * `ctx` carries `extendLease(additionalMs)` for long-running
+ * handlers about to overrun their lease, and `progress(0..100)` for
+ * audit-chain progress markers (rate-limited so a chatty handler
+ * can't flood the chain).
+ *
+ * @opts
+ *   backend?:         string,   // backend name; defaults to defaultBackend
+ *   concurrency?:     number,   // max in-flight handlers (default 1)
+ *   leaseDurationMs?: number,   // lease window before sweep re-pends (default 30s)
+ *   pollIntervalMs?:  number,   // idle backoff between empty leases (default 1s)
+ *   fastPollMs?:      number,   // delay between non-empty lease batches (default 50ms)
+ *   rateLimit?: {
+ *     max:        number,       // positive integer
+ *     perSeconds: number,       // positive finite seconds
+ *   },
+ *
+ * @example
+ *   var consumer = b.queue.consume("ingest", async function (job, ctx) {
+ *     ctx.progress(10);
+ *     // ...do work...
+ *     ctx.progress(100);
+ *   }, { concurrency: 4 });
+ *
+ *   // Later, on shutdown signal:
+ *   consumer.cancel();
+ */
 function consume(queueName, handler, opts) {
   _requireInit();
   if (!queueName) throw _err("MISSING_QUEUE", "consume requires queueName", true);
@@ -402,11 +530,48 @@ function _backoffDelay(attempt) {
   return retryHelper.backoffDelay(attempt, _QUEUE_BACKOFF_OPTS);
 }
 
+/**
+ * @primitive b.queue.size
+ * @signature b.queue.size(queueName, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.dlqSize, b.queue.purge
+ *
+ * Resolves with the number of pending + inflight jobs in the queue —
+ * the live backlog. Excludes `done` and `failed` rows. Operators wire
+ * this to dashboards and autoscalers.
+ *
+ * @opts
+ *   backend?: string,   // backend name; defaults to defaultBackend
+ *
+ * @example
+ *   var pending = await b.queue.size("ingest");
+ *   // → 42
+ */
 function size(queueName, opts) {
   _requireInit();
   return _backendFor(opts).size(queueName);
 }
 
+/**
+ * @primitive b.queue.purge
+ * @signature b.queue.purge(queueName, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.size, b.queue.dlqList
+ *
+ * Deletes every job in the named queue and resolves with the deleted
+ * count. Emits a `system.queue.purge` audit event for forensic
+ * traceability. Use during operator-driven cleanups; never in normal
+ * traffic — purged jobs are not recoverable.
+ *
+ * @opts
+ *   backend?: string,   // backend name; defaults to defaultBackend
+ *
+ * @example
+ *   var deleted = await b.queue.purge("ingest");
+ *   // → 42
+ */
 function purge(queueName, opts) {
   _requireInit();
   var b = _backendFor(opts);
@@ -424,6 +589,28 @@ function purge(queueName, opts) {
 // `dlqRetry` resets a single job back to 'pending' so it gets picked
 // up by consumers again (operator-driven — never automatic).
 
+/**
+ * @primitive b.queue.dlqList
+ * @signature b.queue.dlqList(queueName, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.dlqRetry, b.queue.dlqSize
+ *
+ * Resolves with an array of dead-letter rows — jobs that exhausted
+ * their retries and were parked for human review. Each row carries
+ * the original payload, attempt count, last failure reason, and
+ * trace correlation id. Rejects with `DLQ_UNSUPPORTED` when the
+ * configured backend does not implement a dead-letter view.
+ *
+ * @opts
+ *   backend?: string,   // backend name; defaults to defaultBackend
+ *   limit?:   number,   // backend-specific paging cap
+ *
+ * @example
+ *   var dead = await b.queue.dlqList("ingest", { limit: 50 });
+ *   dead.length;
+ *   // → 3
+ */
 function dlqList(queueName, opts) {
   _requireInit();
   var b = _backendFor(opts);
@@ -434,6 +621,26 @@ function dlqList(queueName, opts) {
   return b.dlqList(queueName, opts);
 }
 
+/**
+ * @primitive b.queue.dlqRetry
+ * @signature b.queue.dlqRetry(jobId, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.dlqList, b.queue.dlqSize
+ *
+ * Resets a single dead-letter row back to `pending` so consumers
+ * pick it up again. Operator-driven only — the framework never
+ * auto-retries failed-after-retries jobs because the failure mode
+ * usually requires human investigation. Resolves with `true` when
+ * the row was found and reset, `false` otherwise.
+ *
+ * @opts
+ *   backend?: string,   // backend name; defaults to defaultBackend
+ *
+ * @example
+ *   var ok = await b.queue.dlqRetry("job-7c2f8e1a");
+ *   // → true
+ */
 function dlqRetry(jobId, opts) {
   _requireInit();
   var b = _backendFor(opts);
@@ -451,6 +658,26 @@ function dlqRetry(jobId, opts) {
   });
 }
 
+/**
+ * @primitive b.queue.dlqSize
+ * @signature b.queue.dlqSize(queueName, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.dlqList, b.queue.dlqRetry
+ *
+ * Resolves with the number of dead-letter rows for the named queue —
+ * jobs that exhausted their retries and were parked for human review.
+ * Operators wire this to dashboards / alerting so a growing DLQ
+ * surfaces before it becomes a backlog. Rejects with `DLQ_UNSUPPORTED`
+ * when the configured backend does not implement a dead-letter view.
+ *
+ * @opts
+ *   backend?: string,   // backend name; defaults to defaultBackend
+ *
+ * @example
+ *   var stuck = await b.queue.dlqSize("ingest");
+ *   // → 3
+ */
 function dlqSize(queueName, opts) {
   _requireInit();
   var b = _backendFor(opts);
@@ -461,6 +688,28 @@ function dlqSize(queueName, opts) {
   return b.dlqSize(queueName);
 }
 
+/**
+ * @primitive b.queue.shutdown
+ * @signature b.queue.shutdown(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.consume, b.queue.init
+ *
+ * Cancels every active consumer and waits for in-flight handlers to
+ * drain, then stops the expired-lease sweep timer. Honors a deadline
+ * — handlers that exceed `timeoutMs` are abandoned (their leases
+ * expire and the sweep re-pends them on the next process). Idempotent
+ * — calling `shutdown` before `init` is a no-op so SIGTERM handlers
+ * can be wired unconditionally.
+ *
+ * @opts
+ *   timeoutMs?: number,   // drain deadline in ms (default 30000)
+ *
+ * @example
+ *   process.on("SIGTERM", async function () {
+ *     await b.queue.shutdown({ timeoutMs: 15000 });
+ *   });
+ */
 async function shutdown(opts) {
   if (!initialized) return;
   opts = opts || {};
@@ -477,6 +726,23 @@ async function shutdown(opts) {
   if (sweepTimer) { sweepTimer.stop(); sweepTimer = null; }
 }
 
+/**
+ * @primitive b.queue.listBackends
+ * @signature b.queue.listBackends()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.init, b.queue.bootFromEnv
+ *
+ * Returns an array of `{ name, protocol, breakerState }` rows — one
+ * per configured backend. `breakerState` is `"closed"` / `"open"` /
+ * `"half-open"` from the per-backend circuit breaker. Operators wire
+ * this to a `/health/queue` endpoint or readiness probe so a tripped
+ * breaker surfaces in the orchestrator before silent backlog growth.
+ *
+ * @example
+ *   var status = b.queue.listBackends();
+ *   // → [{ name: "primary", protocol: "local", breakerState: "closed" }]
+ */
 function listBackends() {
   _requireInit();
   return Object.keys(backends).map(function (name) {
@@ -502,20 +768,52 @@ function _resetForTest() {
   audit.reset();
 }
 
-// enqueueFlow — atomic registration of a parent-child job graph.
-//
-//   await b.queue.enqueueFlow({
-//     queueName: "ingest",
-//     children: [
-//       { name: "fetch",      payload: { url } },
-//       { name: "transform",  payload: { ... }, dependsOn: ["fetch"] },
-//       { name: "publish",    payload: { ... }, dependsOn: ["transform"] },
-//     ],
-//   });
-//
-// Cycle detection runs at registration (throws at call site). Each child enters
-// the queue with availableAt = MAX_SAFE_INTEGER until parent completion
-// bumps it. Returns { flowId, jobs: [{ name, jobId }, ...] }.
+/**
+ * @primitive b.queue.enqueueFlow
+ * @signature b.queue.enqueueFlow(spec)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.enqueue, b.queue.consume
+ *
+ * Atomically registers a parent-child job graph. Each child enqueues
+ * with a parking-lot `availableAt = MAX_SAFE_INTEGER` until every
+ * `dependsOn` row reaches `done`, at which point the dependent's
+ * availableAt drops to "now" and consumers pick it up. Cycle detection
+ * runs at registration time — bad graphs reject with `FLOW_CYCLE` /
+ * `FLOW_UNKNOWN_DEP` before any row lands.
+ *
+ * Resolves with `{ flowId, jobs: [{ name, jobId }, ...] }`. The
+ * returned `jobId` array is in declaration order, not topological
+ * order — callers that need a specific child's id look it up by
+ * `name`.
+ *
+ * @opts
+ *   queueName: string,
+ *   children: [
+ *     {
+ *       name:            string,           // unique within the flow
+ *       payload:         any,
+ *       dependsOn?:      string[],         // sibling names this child waits on
+ *       priority?:       number,
+ *       maxAttempts?:    number,
+ *       classification?: string,
+ *       traceId?:        string,
+ *     },
+ *     ...
+ *   ],
+ *
+ * @example
+ *   var flow = await b.queue.enqueueFlow({
+ *     queueName: "ingest",
+ *     children: [
+ *       { name: "fetch",     payload: { url: "https://example.com" } },
+ *       { name: "transform", payload: { stage: 1 }, dependsOn: ["fetch"] },
+ *       { name: "publish",   payload: { topic: "out" }, dependsOn: ["transform"] },
+ *     ],
+ *   });
+ *   flow.jobs.length;
+ *   // → 3
+ */
 function enqueueFlow(spec) {
   _requireInit();
   if (!spec || typeof spec !== "object") {
@@ -632,17 +930,40 @@ function enqueueFlow(spec) {
   );
 }
 
-// bootFromEnv — env-driven init mirroring b.network.bootFromEnv and
-// b.logStream.bootFromEnv. Reads the BLAMEJS_QUEUE_* env vars and
-// calls queue.init({ backends }) accordingly. Operators get a working
-// queue backend without writing build-app code.
-//
-//   BLAMEJS_QUEUE_PROTOCOL          local | redis              (default: local)
-//   BLAMEJS_QUEUE_REDIS_URL         redis://host:port/db       (required when protocol=redis)
-//   BLAMEJS_QUEUE_REDIS_PASSWORD    auth password
-//   BLAMEJS_QUEUE_REDIS_USERNAME    ACL username (optional)
-//   BLAMEJS_QUEUE_REDIS_TLS         "1"/"true" forces TLS (else inferred from rediss://)
-//   BLAMEJS_QUEUE_REDIS_KEY_PREFIX  key prefix (default "blamejs:queue")
+/**
+ * @primitive b.queue.bootFromEnv
+ * @signature b.queue.bootFromEnv(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.queue.init, b.queue.listBackends
+ *
+ * Env-driven `init` mirroring `b.network.bootFromEnv` and
+ * `b.logStream.bootFromEnv`. Reads `BLAMEJS_QUEUE_*` and calls
+ * `queue.init({ backends: { default: ... } })` so operators get a
+ * working queue without writing build-app code. Idempotent — a
+ * second call after `init` already ran is a no-op.
+ *
+ * Recognized env vars:
+ *   BLAMEJS_QUEUE_PROTOCOL          "local" | "redis"  (default "local")
+ *   BLAMEJS_QUEUE_REDIS_URL         redis://host:port/db (required when protocol=redis)
+ *   BLAMEJS_QUEUE_REDIS_PASSWORD    auth password
+ *   BLAMEJS_QUEUE_REDIS_USERNAME    ACL username
+ *   BLAMEJS_QUEUE_REDIS_TLS         "1" / "true" forces TLS (else inferred from rediss://)
+ *   BLAMEJS_QUEUE_REDIS_KEY_PREFIX  key prefix (default "blamejs:queue")
+ *
+ * Throws `INVALID_CONFIG` when `BLAMEJS_QUEUE_PROTOCOL` is unknown
+ * or when `redis` is selected without `BLAMEJS_QUEUE_REDIS_URL` —
+ * operators catch the typo at boot rather than first enqueue.
+ *
+ * @opts
+ *   env?: object,   // override process.env for testing / fixtures
+ *
+ * @example
+ *   process.env.BLAMEJS_QUEUE_PROTOCOL = "local";
+ *   b.queue.bootFromEnv();
+ *   b.queue.listBackends().length;
+ *   // → 1
+ */
 function bootFromEnv(opts) {
   opts = opts || {};
   var env = opts.env || process.env;