@blamejs/core 0.8.43 → 0.8.50

package/lib/app-shutdown.js

@@ -1,83 +1,44 @@
 "use strict";
 /**
- * app-shutdown — graceful-shutdown orchestrator.
+ * @module b.appShutdown
+ * @nav    Production
+ * @title  App Shutdown
  *
- * SIGTERM is the contract between Kubernetes / systemd / docker stop
- * and the framework. Production rolling restarts depend on the
- * server draining cleanly: stop accepting new traffic, finish in-
- * flight requests, drain jobs, close DB, release the cluster lease.
- * Without orchestration each subsystem's shutdown races every other
- * subsystem's; the result is dropped requests, half-completed jobs,
- * stuck cluster leases that block the next pod from acquiring.
+ * @intro
+ *   Graceful shutdown orchestrator — drain in-flight requests, flush
+ *   audit, close DB, release the cluster lease, then exit. Configurable
+ *   timeouts and signal handlers wire SIGTERM / SIGINT (and any
+ *   operator-supplied signals) into a single phase-ordered shutdown.
  *
- * This module ships a phase-ordered orchestrator. Each phase is
- * named, time-bounded, and best-effort — a phase failure logs an
- * issue but doesn't block subsequent phases (we still want to close
- * the DB and release the lease even if jobs draining timed out).
+ *   SIGTERM is the contract between Kubernetes / systemd / `docker
+ *   stop` and the framework. Production rolling restarts depend on the
+ *   server draining cleanly. Without orchestration each subsystem's
+ *   shutdown races every other subsystem's — the result is dropped
+ *   requests, half-completed jobs, and stuck cluster leases that block
+ *   the next pod from acquiring. The orchestrator runs phases in array
+ *   order with per-phase budgets so a slow phase cannot starve later
+ *   ones; a phase failure is logged but does not skip the remaining
+ *   phases (the DB still closes even if jobs drain timed out).
  *
- * Standard phase order:
+ *   `b.appShutdown.standardPhases(components)` builds the canonical
+ *   ordering — mark-draining → scheduler → jobs → websockets →
+ *   http-server → cluster → db → external-db — given a components map.
+ *   Operators with custom topology call it directly and prepend or
+ *   append their own phases. `b.appShutdown.pidLock(path)` is a single-
+ *   instance file lock for daemons that must run exactly once on a
+ *   host; it composes with the orchestrator via `addPhase` so the lock
+ *   is released as part of graceful shutdown.
  *
- *   1.  beforeStop          operator hook (run before anything else)
- *   2.  mark-draining       health.markShuttingDown() so /readyz → 503
- *                           and the LB starts draining the pod
- *   3.  stop-accepting      flip the orchestrator's `draining` flag —
- *                           middleware (orchestrator.middleware())
- *                           refuses new requests with 503
- *   4.  drain-in-flight     wait for the in-flight counter to reach 0
- *                           (tracked via the same middleware) up to
- *                           phaseTimeoutMs
- *   5.  afterDrain          operator hook (run after in-flight drained)
- *   6.  scheduler           scheduler.stop() if registered
- *   7.  jobs                jobs.shutdown() / queue.shutdown() — let
- *                           current handlers finish, refuse new lease
- *   8.  websockets          router.closeWebSockets() if HTTP server
- *   9.  http-server         server.close() — waits for keepalive
- *                           connections to drain
- *   10. cluster             cluster.shutdown() — release lease cleanly
- *                           so the next pod can acquire it without
- *                           waiting out the lease TTL
- *   11. db                  db.close() — flushes encrypted-at-rest
- *                           snapshot, closes SQLite handle
- *   12. external-db         externalDb.shutdown() — drain pool
+ *   Idempotency: `shutdown()` is idempotent. Calling it twice returns
+ *   the same Promise. Signal handlers route through the same call so
+ *   SIGTERM, SIGINT, an `uncaughtException` reaching the operator hook,
+ *   and a manual `orchestrator.shutdown()` all converge on one
+ *   orchestration. When `b.tracing` has an active registry every phase
+ *   runs inside a span named `shutdown.<phase>` so per-phase durations
+ *   surface in the operator's tracing exporter.
  *
- * Custom phases can be added via opts.phases; each entry is
- * { name, run: async fn, timeoutMs? }. The orchestrator runs them
- * in array order. The standard phase set above is added by
- * createApp via the components map; standalone callers build their
- * own.
- *
- *   var orchestrator = b.appShutdown.create({
- *     graceMs:    30000,
- *     phases:     [
- *       { name: "beforeStop",   run: async function () { ... } },
- *       { name: "drain-in-flight", run: orchestrator.waitInFlight, timeoutMs: 10000 },
- *       { name: "db",           run: function () { db.close(); } },
- *     ],
- *     installSignalHandlers: true,    // SIGTERM + SIGINT auto-call shutdown
- *   });
- *
- *   var result = await orchestrator.shutdown();
- *   // → { ok, phases: [{ name, ms, ok, error? }, ...], totalMs, draining }
- *
- *   // Mounted as middleware to refuse new requests during drain +
- *   // track in-flight count.
- *   router.use(orchestrator.middleware());
- *
- *   orchestrator.draining();   // true once shutdown() has been called
- *   orchestrator.inFlight();   // current in-flight count
- *
- * Idempotency: shutdown() is idempotent. Calling it twice returns
- * the same Promise. Signal handlers fire it via `installSignalHandlers`
- * so SIGTERM + SIGINT both route through the same orchestration.
- *
- * Per-phase timeouts: each phase has a budget. If a phase doesn't
- * complete within timeoutMs it's marked failed and the orchestrator
- * moves to the next phase. Default = remaining grace divided by
- * remaining phases (so a slow phase doesn't starve later ones).
- *
- * Tracing integration: when b.tracing has an active registry, each
- * phase runs inside a span named "shutdown.<phase>" so operators see
- * which phase took how long in their tracing exporter.
+ * @card
+ *   Graceful shutdown orchestrator — drain in-flight requests, flush audit, close DB, release the cluster lease, then exit.
  */
 
 var safeAsync = require("./safe-async");
@@ -93,6 +54,41 @@ var log = boot("app-shutdown");
 
 var DEFAULT_GRACE_MS = C.TIME.seconds(30);
 
+/**
+ * @primitive b.appShutdown.create
+ * @signature b.appShutdown.create(opts)
+ * @since     0.6.0
+ * @related   b.appShutdown.standardPhases, b.appShutdown.pidLock
+ *
+ * Build a graceful-shutdown orchestrator. Returns an instance with
+ * `shutdown()` (idempotent — second call returns the same Promise),
+ * `middleware()` (refuses new requests with 503 + tracks in-flight
+ * count), `waitInFlight()`, `addPhase()`, `installSignals()`,
+ * `uninstallSignals()`, `draining()`, and `inFlight()`. Each phase has
+ * a per-phase budget; the default is remaining grace divided by
+ * remaining phases so a slow phase doesn't starve later ones. A phase
+ * failure is logged but does not skip the remaining phases.
+ *
+ * @opts
+ *   graceMs:               number,    // total budget across all phases (default 30000)
+ *   phases:                array,     // [{ name, run: async fn, timeoutMs? }]
+ *   installSignalHandlers: boolean,   // wire SIGTERM/SIGINT (default false)
+ *   signals:               array,     // signal names (default ["SIGTERM","SIGINT"])
+ *   onUncaught:            function,  // hook for uncaughtException / unhandledRejection
+ *   installUncaught:       boolean,   // wire uncaughtException handler unconditionally
+ *
+ * @example
+ *   var orchestrator = b.appShutdown.create({
+ *     graceMs: 30000,
+ *     phases: [
+ *       { name: "before-stop", run: async function () { return "ok"; } },
+ *       { name: "db",          run: function () { return; }, timeoutMs: 5000 },
+ *     ],
+ *   });
+ *   var result = await orchestrator.shutdown();
+ *   result.ok;                // → true
+ *   result.phases.length;     // → 2
+ */
 function create(opts) {
   opts = opts || {};
   nb.requirePositiveFiniteIntIfPresent(opts.graceMs,
@@ -331,10 +327,26 @@ function create(opts) {
   };
 }
 
-// Standard phase builder — given a components map, returns a phases
-// array suitable for create({ phases }). Used by createApp; operators
-// with custom topology call this directly to get the same ordering
-// then prepend / append their own phases.
+/**
+ * @primitive b.appShutdown.standardPhases
+ * @signature b.appShutdown.standardPhases(components)
+ * @since     0.6.0
+ * @related   b.appShutdown.create
+ *
+ * Build the canonical phases array for a components map. The order is
+ * mark-draining → scheduler → jobs (or queue) → websockets →
+ * http-server → cluster → db → external-db. Each entry carries a
+ * conservative `timeoutMs`. Operators wire the result into
+ * `b.appShutdown.create({ phases })`; with a non-standard topology they
+ * prepend or append their own entries to the returned array.
+ *
+ * @example
+ *   var phases = b.appShutdown.standardPhases({
+ *     db: { close: function () { return; } },
+ *   });
+ *   phases.length;          // → 1
+ *   phases[0].name;         // → "db"
+ */
 function standardPhases(components) {
   components = components || {};
   var phases = [];
@@ -440,6 +452,30 @@ function standardPhases(components) {
 var nodeFs   = require("fs");
 var nodePath = require("path");
 
+/**
+ * @primitive b.appShutdown.pidLock
+ * @signature b.appShutdown.pidLock(lockPath)
+ * @since     0.6.0
+ * @related   b.appShutdown.create
+ *
+ * Single-instance file lock for daemons that must run exactly once on
+ * a host. Returns `{ acquire, release, held, path }`. `acquire()`
+ * writes the current PID atomically (open with O_EXCL + write + fsync)
+ * and refuses to acquire if another live process already holds the
+ * lock; stale lock files (PID gone) are reaped automatically. On
+ * Windows the underlying advisory flock is unavailable, so the lock
+ * file's exclusive presence is the lock. Compose with the orchestrator
+ * by passing `release` as a phase via `addPhase`.
+ *
+ * @example
+ *   var lock = b.appShutdown.pidLock("/tmp/blamejs-doc-example.pid");
+ *   try {
+ *     lock.acquire();
+ *     lock.held();          // → true
+ *   } finally {
+ *     lock.release();
+ *   }
+ */
 function pidLock(lockPath) {
   if (typeof lockPath !== "string" || lockPath.length === 0) {
     throw new AppShutdownError("app-shutdown/bad-pidlock-path",