@blamejs/core 0.10.7 → 0.10.8

package/lib/promise-pool.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * @module b.promisePool
+ * @nav    Async
+ * @title  Promise Pool
+ *
+ * @intro
+ *   Bounded-concurrency task runner for promise-returning work — the
+ *   common gap between `b.workerPool` (worker_threads for CPU-bound
+ *   work) and `b.queue` (durable cross-process messaging). Wraps the
+ *   typical "I have N parallel I/O fan-outs and want at most K in
+ *   flight at any moment" pattern with back-pressure on enqueue
+ *   (so the caller can't out-run the worker side) and a clean drain
+ *   path that composes with `b.appShutdown`.
+ *
+ *   Two enqueue paths:
+ *
+ *     - `pool.run(taskFn)` returns a Promise that resolves to the
+ *       task's return value (or rejects with the task's error). When
+ *       the pool is at capacity, `run` waits until a slot frees
+ *       BEFORE the task starts — back-pressure is part of the
+ *       contract, not an opt.
+ *
+ *     - `pool.fire(taskFn)` is the synchronous-enqueue variant for
+ *       fan-out from non-async contexts. Returns the same Promise
+ *       but the call itself can't await — useful inside event
+ *       handlers that fire-and-forget.
+ *
+ *   Drain semantics: `pool.drain()` resolves when every queued and
+ *   in-flight task settles. Callers wire this into shutdown via
+ *   `b.appShutdown.create({ priority: 50, run: () => pool.drain() })`
+ *   so the process doesn't tear down with work mid-flight.
+ *
+ *   The pool does NOT retry failed tasks; rejection of a task's
+ *   promise is the caller's signal. Operators that want retry compose
+ *   `b.retry.withRetry` inside the task body.
+ *
+ * @card
+ *   Bounded-concurrency promise pool — back-pressure on enqueue, drain-on-shutdown, no hidden retry. The thing every consumer reaches for p-limit for.
+ */
+
+var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
+var { defineClass } = require("./framework-error");
+
+var PromisePoolError = defineClass("PromisePoolError", { alwaysPermanent: true });
+
+var MAX_CONCURRENCY = 65536;                                                                    // allow:raw-byte-literal — uint16 ceiling on parallel I/O fan-out
+
+/**
+ * @primitive b.promisePool.create
+ * @signature b.promisePool.create(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.workerPool.create, b.appShutdown.create, b.retry.withRetry
+ *
+ * Build a bounded-concurrency pool. Returns
+ * `{ run, fire, drain, size, inFlight, queued, closed }`. The pool is
+ * closed via `drain({ close: true })`; subsequent enqueues throw.
+ *
+ * @opts
+ *   concurrency: number,        // required; integer in [1, 65536]
+ *   queueLimit:  number,        // default Infinity; once exceeded, enqueue throws
+ *
+ * @example
+ *   var pool = b.promisePool.create({ concurrency: 8 });
+ *   var results = await Promise.all(items.map(function (item) {
+ *     return pool.run(function () { return fetchOne(item); });
+ *   }));
+ *   await pool.drain({ close: true });
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "b.promisePool.create",
+    PromisePoolError, "promise-pool/bad-opts");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.concurrency,
+    "b.promisePool.create: concurrency", PromisePoolError, "promise-pool/bad-concurrency");
+  if (opts.concurrency === undefined || opts.concurrency > MAX_CONCURRENCY) {
+    throw new PromisePoolError("promise-pool/bad-concurrency",
+      "b.promisePool.create: concurrency must be an integer in [1, " +
+      MAX_CONCURRENCY + "] (got " + opts.concurrency + ")");
+  }
+  var queueLimit = opts.queueLimit === undefined ? Infinity : opts.queueLimit;
+  if (queueLimit !== Infinity) {
+    numericBounds.requirePositiveFiniteIntIfPresent(queueLimit + 1,
+      "b.promisePool.create: queueLimit (must be non-negative int)", PromisePoolError,
+      "promise-pool/bad-queue-limit");
+  }
+  var concurrency = opts.concurrency;
+  var inFlight = 0;
+  var queue = [];                // FIFO of pending { taskFn, resolve, reject }
+  var drainWaiters = [];
+  var closed = false;
+
+  function _pump() {
+    while (inFlight < concurrency && queue.length > 0) {
+      var slot = queue.shift();
+      inFlight += 1;
+      Promise.resolve().then(function () { return slot.taskFn(); })
+        .then(function (val) { slot.resolve(val); _settle(); })
+        .catch(function (err) { slot.reject(err); _settle(); });
+    }
+    if (inFlight === 0 && queue.length === 0 && drainWaiters.length > 0) {
+      var waiters = drainWaiters.slice();
+      drainWaiters.length = 0;
+      for (var i = 0; i < waiters.length; i += 1) waiters[i]();
+    }
+  }
+
+  function _settle() {
+    inFlight -= 1;
+    _pump();
+  }
+
+  function _enqueue(taskFn) {
+    if (typeof taskFn !== "function") {
+      throw new PromisePoolError("promise-pool/bad-task",
+        "b.promisePool: task must be a function returning a value or Promise");
+    }
+    if (closed) {
+      throw new PromisePoolError("promise-pool/closed",
+        "b.promisePool: pool is closed (drain({close:true}) was called)");
+    }
+    if (queue.length >= queueLimit) {
+      throw new PromisePoolError("promise-pool/queue-full",
+        "b.promisePool: queueLimit=" + queueLimit + " reached");
+    }
+    return new Promise(function (resolve, reject) {
+      queue.push({ taskFn: taskFn, resolve: resolve, reject: reject });
+      _pump();
+    });
+  }
+
+  function run(taskFn)  { return _enqueue(taskFn); }
+  function fire(taskFn) { return _enqueue(taskFn); }
+
+  function drain(drainOpts) {
+    drainOpts = drainOpts || {};
+    return new Promise(function (resolve) {
+      function _done() {
+        if (drainOpts.close === true) closed = true;
+        resolve();
+      }
+      if (inFlight === 0 && queue.length === 0) { _done(); return; }
+      drainWaiters.push(_done);
+    });
+  }
+
+  return {
+    run:      run,
+    fire:     fire,
+    drain:    drain,
+    size:     function () { return concurrency; },
+    inFlight: function () { return inFlight; },
+    queued:   function () { return queue.length; },
+    closed:   function () { return closed; },
+  };
+}
+
+module.exports = {
+  create:           create,
+  PromisePoolError: PromisePoolError,
+};

package/lib/sd-notify.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * @module b.sdNotify
+ * @nav    Process
+ * @title  systemd Notify
+ *
+ * @intro
+ *   `sd_notify` protocol surface for daemons running under
+ *   `Type=notify` systemd units. Composes the standard lifecycle
+ *   messages — `READY=1` on boot, `WATCHDOG=1` on heartbeat,
+ *   `STOPPING=1` on shutdown, `RELOADING=1` on hot-reload — against
+ *   the `$NOTIFY_SOCKET` env var systemd populates for the child
+ *   process.
+ *
+ *   Transport: Node has no unix-DGRAM socket support in its `dgram`
+ *   module, so the v1 path shells out to `systemd-notify(1)` via
+ *   `execFile` (NOT `exec` — no shell-string parsing on the
+ *   message bytes). Operators running under systemd already have
+ *   `systemd-tools` installed by definition, so the dependency is
+ *   no expansion of the trust surface.
+ *
+ *   Compose with `b.appShutdown` for the STOPPING signal: register a
+ *   priority-0 phase that calls `b.sdNotify.stopping()` so systemd
+ *   sees the shutdown intent before the framework tears anything
+ *   down. Compose with a periodic `WATCHDOG=1` against the unit's
+ *   `WatchdogSec=` interval so systemd auto-restarts the daemon if
+ *   the event loop wedges.
+ *
+ *   When `$NOTIFY_SOCKET` is unset (process running outside systemd
+ *   — bare invocation, foreground dev, container without
+ *   `--notify-ready`), every call is a no-op that surfaces a single
+ *   boot-time audit entry. Operators get observability of the
+ *   degraded state without per-call log noise.
+ *
+ * @card
+ *   sd_notify protocol for systemd Type=notify daemons — READY / WATCHDOG / STOPPING / RELOADING. Composes b.appShutdown for shutdown signaling.
+ */
+
+var { execFile } = require("node:child_process");
+var C = require("./constants");
+var safeEnv = require("./parsers/safe-env");
+var audit = require("./audit");
+var { defineClass } = require("./framework-error");
+
+var SdNotifyError = defineClass("SdNotifyError", { alwaysPermanent: true });
+
+// Whitelist of sd_notify state= values we ship as named helpers. The
+// underlying `send({ state })` accepts any string but the helpers are
+// the operator-facing surface — `READY=1` etc. — and the audit log
+// records the named state, not arbitrary payload bytes.
+var KNOWN_STATES = Object.freeze({
+  ready:     "READY=1",
+  stopping:  "STOPPING=1",
+  reloading: "RELOADING=1",
+  watchdog:  "WATCHDOG=1",
+});
+
+function _notifySocketPath() {
+  var p = safeEnv.readVar("NOTIFY_SOCKET");
+  if (typeof p !== "string" || p.length === 0) return null;
+  // Abstract namespace socket (Linux-only) prefixed with `@` —
+  // systemd-notify(1) accepts the same form, so we don't normalize.
+  return p;
+}
+
+function _runNotify(payload) {
+  return new Promise(function (resolve, reject) {
+    var args = [];
+    var lines = String(payload).split("\n");
+    for (var i = 0; i < lines.length; i += 1) {
+      if (lines[i].length > 0) args.push(lines[i]);
+    }
+    if (args.length === 0) { resolve(); return; }
+    // execFile (not exec) — no shell evaluation; the message bytes
+    // pass through argv exactly. systemd-notify accepts one or more
+    // KEY=VALUE arguments. The `--no-block` flag returns immediately
+    // without waiting for the notification to be processed.
+    execFile("systemd-notify", ["--no-block"].concat(args),
+      { timeout: C.TIME.seconds(5), windowsHide: true },
+      function (err) {
+        if (err) reject(err);
+        else resolve();
+      });
+  });
+}
+
+/**
+ * @primitive b.sdNotify.send
+ * @signature b.sdNotify.send(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.ready, b.sdNotify.stopping, b.appShutdown.create
+ *
+ * Generic sd_notify dispatch. Sends one or more `KEY=VALUE` payload
+ * lines to systemd via `systemd-notify(1)`. No-op when
+ * `$NOTIFY_SOCKET` is unset (foreground / container without
+ * `--notify-ready` / non-systemd init). Returns a Promise resolving
+ * on dispatch success.
+ *
+ * @opts
+ *   state:    string,                     // e.g. "READY=1" / "STOPPING=1"
+ *   status:   string,                     // free-form status text → `STATUS=`
+ *   mainpid:  number,                     // PID override → `MAINPID=`
+ *   audit:    boolean,                     // default true
+ *
+ * @example
+ *   await b.sdNotify.send({ state: "READY=1", status: "Listening on :8080" });
+ */
+function send(opts) {
+  opts = opts || {};
+  var lines = [];
+  if (typeof opts.state === "string" && opts.state.length > 0) lines.push(opts.state);
+  if (typeof opts.status === "string" && opts.status.length > 0) {
+    // STATUS= permits arbitrary UTF-8 except newline — refuse newline
+    // so a hostile status string can't smuggle a second key.
+    if (opts.status.indexOf("\n") !== -1 || opts.status.indexOf("\r") !== -1) {
+      throw new SdNotifyError("sd-notify/control-char-in-status",
+        "send: status field must not contain CR/LF (sd_notify framing)");
+    }
+    lines.push("STATUS=" + opts.status);
+  }
+  if (opts.mainpid !== undefined) {
+    if (typeof opts.mainpid !== "number" || !isFinite(opts.mainpid) ||
+        Math.floor(opts.mainpid) !== opts.mainpid || opts.mainpid < 1) {
+      throw new SdNotifyError("sd-notify/bad-mainpid",
+        "send: mainpid must be a positive integer");
+    }
+    lines.push("MAINPID=" + opts.mainpid);
+  }
+  if (lines.length === 0) return Promise.resolve();
+
+  var socketPath = _notifySocketPath();
+  if (socketPath === null) {
+    if (opts.audit !== false) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send.skipped",
+          outcome:  "denied",
+          metadata: { reason: "no-notify-socket", state: opts.state || null },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    return Promise.resolve();
+  }
+  var auditOn = opts.audit !== false;
+  return _runNotify(lines.join("\n")).then(function () {
+    if (auditOn) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send",
+          outcome:  "success",
+          metadata: { state: opts.state || null, status: opts.status || null },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+  }).catch(function (err) {
+    if (auditOn) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send",
+          outcome:  "failure",
+          metadata: { state: opts.state || null, error: (err && err.message) || String(err) },
+        });
+      } catch (_e2) { /* drop-silent */ }
+    }
+    throw new SdNotifyError("sd-notify/dispatch-failed",
+      "send: systemd-notify dispatch failed: " + ((err && err.message) || String(err)));
+  });
+}
+
+/**
+ * @primitive b.sdNotify.ready
+ * @signature b.sdNotify.ready(opts?)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.send, b.sdNotify.stopping
+ *
+ * Send `READY=1` to systemd, signaling boot complete. Use once the
+ * listener is bound and the daemon is accepting work.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   await b.sdNotify.ready({ status: "Listening on :8080" });
+ */
+function ready(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.ready }));
+}
+
+/**
+ * @primitive b.sdNotify.stopping
+ * @signature b.sdNotify.stopping(opts?)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.send, b.appShutdown.create
+ *
+ * Send `STOPPING=1`. Operators wire this into `b.appShutdown` as the
+ * earliest shutdown phase (priority 0) so systemd sees the shutdown
+ * intent before any teardown begins.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   b.appShutdown.create({ name: "sd-notify-stopping", priority: 0,
+ *     run: function () { return b.sdNotify.stopping(); } });
+ */
+function stopping(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.stopping }));
+}
+
+/**
+ * @primitive b.sdNotify.reloading
+ * @signature b.sdNotify.reloading(opts?)
+ * @since     0.10.8
+ * @status    stable
+ *
+ * Send `RELOADING=1` then (after the reload completes) `READY=1`.
+ * Use during hot-config-reload paths; systemd treats the unit as
+ * "reloading" until the next `READY=1`.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   await b.sdNotify.reloading();
+ *   await reloadConfig();
+ *   await b.sdNotify.ready();
+ */
+function reloading(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.reloading }));
+}
+
+/**
+ * @primitive b.sdNotify.watchdog
+ * @signature b.sdNotify.watchdog(opts?)
+ * @since     0.10.8
+ * @status    stable
+ *
+ * Send `WATCHDOG=1`. Operators with `WatchdogSec=` configured on
+ * their unit call this periodically (e.g. every `WatchdogSec/2`)
+ * so systemd auto-restarts the daemon when the event loop wedges.
+ *
+ * @opts
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   setInterval(function () { b.sdNotify.watchdog(); }, 15000);
+ */
+function watchdog(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.watchdog }));
+}
+
+module.exports = {
+  send:          send,
+  ready:         ready,
+  stopping:      stopping,
+  reloading:     reloading,
+  watchdog:      watchdog,
+  isAvailable:   function () { return _notifySocketPath() !== null; },
+  SdNotifyError: SdNotifyError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.10.7",
+  "version": "0.10.8",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:62b21ffc-fcde-4782-a950-d9b2db933f5c",
+  "serialNumber": "urn:uuid:2db3bd59-b835-4672-aac5-7c874f2f9276",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-17T20:52:27.570Z",
+    "timestamp": "2026-05-18T00:17:19.942Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.10.7",
+      "bom-ref": "@blamejs/core@0.10.8",
       "type": "library",
       "name": "blamejs",
-      "version": "0.10.7",
+      "version": "0.10.8",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.10.7",
+      "purl": "pkg:npm/%40blamejs/core@0.10.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.10.7",
+      "ref": "@blamejs/core@0.10.8",
       "dependsOn": []
     }
   ]