@blamejs/core 0.8.43 → 0.8.50

package/lib/log-stream.js

@@ -1,56 +1,52 @@
 "use strict";
 /**
- * Log streaming dispatcher — operational logs to one or many sinks with
- * redaction and bidirectional command channel.
- *
- * Same dispatcher pattern: backends configured per-name with a protocol
- * + protocol-specific options. Built-in protocols:
- *
- *   local    — append-only file with rotation
- *   webhook  — generic HTTP POST; covers Splunk HEC, Datadog, Sumo
- *              Logic, Loki, custom collectors that ingest JSON
- *   otlp     — OpenTelemetry Protocol over HTTP/JSON; ResourceLogs
- *              envelope with severity mapping per OTel Logs Data
- *              Model. Operators with an OTel collector running
- *              (k8s, cloud) get standard log forwarding without a
- *              vendor-specific adapter.
- *   otlp-grpc — same OTel Logs Data Model but over gRPC (HTTP/2 +
- *              hand-encoded protobuf). Higher-throughput than the
- *              JSON variant; preferred for production deployments
- *              pushing >100K logs/s straight to a remote OTel
- *              collector. No protobuf parser ships in the bundle —
- *              the encoder is the framework's own (lib/protobuf-encoder.js).
- *   cloudwatch — AWS CloudWatch Logs (PutLogEvents) over HTTPS with
- *              SigV4. Pass { autoCreate: true } to have the framework
- *              issue CreateLogGroup + CreateLogStream on first emit
- *              (idempotent — ResourceAlreadyExistsException treated as
- *              success). Honors IAM role + STS session tokens. Respects
- *              the 10K-event / 1 MiB / 256 KiB-per-event AWS caps.
- *   syslog   — RFC 5424 with octet-counting framing over UDP / TCP /
- *              TLS. UDP is best-effort; TCP/TLS buffer during socket
- *              reconnect and replay on connect. Default ports 514
- *              (UDP/TCP) and 6514 (TLS).
- *
- * Every emit goes through lib/redact.js BEFORE any sink sees it. PHI/PCI
- * never reaches operational logs even on a misconfigured field name —
- * pattern detectors catch credit-card-shaped values, JWTs, PEM blocks,
- * AWS access keys, vault-sealed strings, SSN-shaped values, etc.
- *
- * Bidirectional command channel:
- *   logStream.onIncoming(handler) registers a handler for inbound events.
- *   Operators wire their HTTP route (or other transport — webhook receiver,
- *   SSE, message-queue subscriber) to call logStream.deliverIncoming(payload)
- *   which invokes registered handlers. The framework doesn't prescribe the
- *   transport — it provides the dispatch.
- *
- * Public API:
- *   logStream.init({ sinks: { name: { protocol, ... } }, classification? })
- *   logStream.emit(level, message, meta?)         (sync — non-blocking)
- *   logStream.info(msg, meta?) / .warn / .error / .debug
- *   logStream.onIncoming(handler)                 (handler returns Promise)
- *   logStream.deliverIncoming(payload, opts?)
- *   logStream.shutdown()
- *   logStream.listSinks()                         → [{ name, protocol, stats }]
+ * @module b.logStream
+ * @nav    Observability
+ * @title  Log Stream
+ *
+ * @intro
+ *   Pluggable structured-log dispatcher — fire-and-forget JSON records
+ *   from request hot paths to one or many sinks (local file with
+ *   rotation, generic webhook, OTLP HTTP/JSON, OTLP gRPC, AWS
+ *   CloudWatch Logs, RFC 5424 syslog over UDP/TCP/TLS). Each sink
+ *   keeps its own connection / fd / batch buffer, so a slow remote
+ *   collector backpressures only its own queue — never the request
+ *   thread that called `emit()`.
+ *
+ *   Every record passes through `b.redact` BEFORE any sink sees it.
+ *   PHI / PCI / JWTs / PEM blocks / AWS access keys / vault-sealed
+ *   strings / credit-card-shaped digits / SSN-shaped values are
+ *   stripped on the framework side, not delegated to the operator's
+ *   sink config — a misnamed field cannot leak sensitive data into
+ *   operational logs.
+ *
+ *   Sink failures are drop-silent on the hot path: a captured Promise
+ *   reroutes the error into `audit.system.log.sink_failure` so a
+ *   downed collector never crashes the request that emitted the log
+ *   line. Pending emits are tracked and drained on `shutdown()` so
+ *   records queued just before close still reach disk / the wire.
+ *
+ *   Bidirectional command channel: `onIncoming(handler)` registers a
+ *   handler for inbound events; the operator wires their preferred
+ *   transport (HTTP route, webhook receiver, SSE subscription,
+ *   message-queue consumer) to call `deliverIncoming(payload)`, which
+ *   redacts, audits, and dispatches to every registered handler. The
+ *   framework provides the dispatch; the operator provides the wire.
+ *
+ *   Built-in protocols:
+ *     local      — append-only file with size + age rotation
+ *     webhook    — generic HTTP POST (Splunk HEC, Datadog, Loki,
+ *                  Sumo Logic, custom JSON collectors)
+ *     otlp       — OpenTelemetry Protocol over HTTP/JSON
+ *     otlp-grpc  — same Logs Data Model over gRPC (higher throughput;
+ *                  hand-encoded protobuf, no parser dependency)
+ *     cloudwatch — PutLogEvents over HTTPS with SigV4; honours the
+ *                  10K-event / 1 MiB / 256 KiB-per-event AWS caps
+ *     syslog     — RFC 5424 octet-counting framing over UDP / TCP /
+ *                  TLS (default ports 514 / 6514)
+ *
+ * @card
+ *   Pluggable structured-log dispatcher — fire-and-forget JSON records from request hot paths to one or many sinks (local file with rotation, generic webhook, OTLP HTTP/JSON, OTLP gRPC, AWS CloudWatch Logs, RFC 5424 syslog over UDP/TCP/TLS).
  */
 var localProto      = require("./log-stream-local");
 var webhookProto    = require("./log-stream-webhook");
@@ -100,6 +96,39 @@ var _inflight = new Set();
 var minLevel = "info";
 var incomingHandlers = [];
 
+/**
+ * @primitive b.logStream.init
+ * @signature b.logStream.init(opts)
+ * @since     0.0.13
+ * @related   b.logStream.bootFromEnv, b.logStream.shutdown, b.logStream.listSinks
+ *
+ * Configure the dispatcher. Call once at boot; subsequent calls are
+ * no-ops while the dispatcher is initialized (call `shutdown()` first
+ * to reconfigure). Every named sink resolves a built-in protocol
+ * (`local` / `webhook` / `otlp` / `otlp-grpc` / `cloudwatch` /
+ * `syslog`) and constructs a per-sink instance from its own typed
+ * config block.
+ *
+ * Records below `minLevel` (or a sink's per-sink `minLevel` override)
+ * are dropped before redaction — debug / info chatter on a
+ * production deployment costs nothing past the dispatcher.
+ *
+ * @opts
+ *   sinks:    { [name]: { protocol, minLevel?, ...protocolOpts } },
+ *   minLevel: "debug" | "info" | "warn" | "error",   // default "info"
+ *
+ * @example
+ *   b.logStream.init({
+ *     minLevel: "info",
+ *     sinks: {
+ *       file:   { protocol: "local",   path: "/var/log/app.log" },
+ *       remote: { protocol: "otlp",
+ *                 url:         "https://collector.internal:4318/v1/logs",
+ *                 serviceName: "checkout",
+ *                 minLevel:    "warn" },
+ *     },
+ *   });
+ */
 function init(opts) {
   if (initialized) return;
   if (!opts || !opts.sinks) throw new Error("logStream.init({ sinks }) is required");
@@ -125,6 +154,31 @@ function _shouldEmit(level, sinkLevelFilter) {
   return LEVEL_PRIORITY[level] >= threshold;
 }
 
+/**
+ * @primitive b.logStream.emit
+ * @signature b.logStream.emit(level, message, meta?)
+ * @since     0.0.13
+ * @related   b.logStream.info, b.logStream.warn, b.logStream.error, b.logStream.debug, b.redact.redact
+ *
+ * Synchronous, fire-and-forget emit to every registered sink whose
+ * level filter accepts `level`. The record is `{ ts, level, message,
+ * meta }`; `meta` is run through `b.redact.redact` BEFORE distribution
+ * so PHI / credentials / vault-sealed values never reach a sink even
+ * on a misnamed field. Sink errors are captured, audited
+ * (`system.log.sink_failure`), and discarded — a downed collector
+ * cannot crash the caller. Throws only on an unknown level (config
+ * typo at the call site).
+ *
+ * @example
+ *   // Structured event with sensitive metadata — `apiKey` and
+ *   // `cardNumber` are redacted by pattern before any sink sees them.
+ *   b.logStream.emit("warn", "checkout retry", {
+ *     orderId:    "ord_01HXYZ",
+ *     attempt:    3,
+ *     apiKey:     "<sk-live-placeholder>",
+ *     cardNumber: "<pan-placeholder>",
+ *   });
+ */
 function emit(level, message, meta) {
   if (!initialized) return;
   if (LEVELS.indexOf(level) === -1) {
@@ -164,13 +218,93 @@ function emit(level, message, meta) {
   });
 }
 
+/**
+ * @primitive b.logStream.debug
+ * @signature b.logStream.debug(message, meta?)
+ * @since     0.0.13
+ * @related   b.logStream.emit, b.logStream.info, b.logStream.warn, b.logStream.error
+ *
+ * Convenience wrapper for `emit("debug", ...)`. Records drop below
+ * `minLevel` (default `"info"`) without serialization cost, so leaving
+ * `debug()` calls in production code is cheap.
+ *
+ * @example
+ *   b.logStream.debug("cache lookup", { key: "user:42", hit: false });
+ */
 function debug(message, meta) { emit("debug", message, meta); }
+
+/**
+ * @primitive b.logStream.info
+ * @signature b.logStream.info(message, meta?)
+ * @since     0.0.13
+ * @related   b.logStream.emit, b.logStream.debug, b.logStream.warn, b.logStream.error
+ *
+ * Convenience wrapper for `emit("info", ...)`. Use for routine
+ * lifecycle events worth keeping in the operational log under default
+ * filtering.
+ *
+ * @example
+ *   b.logStream.info("worker ready", { pid: process.pid, queue: "checkout" });
+ */
 function info(message, meta)  { emit("info",  message, meta); }
+
+/**
+ * @primitive b.logStream.warn
+ * @signature b.logStream.warn(message, meta?)
+ * @since     0.0.13
+ * @related   b.logStream.emit, b.logStream.debug, b.logStream.info, b.logStream.error
+ *
+ * Convenience wrapper for `emit("warn", ...)`. Use for recoverable
+ * anomalies the operator should notice but that don't fail the
+ * request — retry exhaustion below the cap, degraded-mode entry,
+ * cache misses on a hot key.
+ *
+ * @example
+ *   b.logStream.warn("retry succeeded after backoff", {
+ *     route: "POST /checkout", attempts: 4, totalMs: 1820,
+ *   });
+ */
 function warn(message, meta)  { emit("warn",  message, meta); }
+
+/**
+ * @primitive b.logStream.error
+ * @signature b.logStream.error(message, meta?)
+ * @since     0.0.13
+ * @related   b.logStream.emit, b.logStream.debug, b.logStream.info, b.logStream.warn
+ *
+ * Convenience wrapper for `emit("error", ...)`. Use for the failed-
+ * request / unhandled-exception class. `b.audit` remains the
+ * authoritative tamper-evident record for privileged actions; the
+ * log stream is operational telemetry.
+ *
+ * @example
+ *   b.logStream.error("dispatcher failure", {
+ *     route: "POST /checkout", err: "ECONNRESET", upstream: "payments",
+ *   });
+ */
 function error(message, meta) { emit("error", message, meta); }
 
 // ---- Bidirectional incoming command channel ----
 
+/**
+ * @primitive b.logStream.onIncoming
+ * @signature b.logStream.onIncoming(handler)
+ * @since     0.0.13
+ * @related   b.logStream.deliverIncoming
+ *
+ * Register a handler for inbound command-channel events. Returns an
+ * unsubscribe function. Handlers may be `async` and may return a
+ * value; `deliverIncoming` collects every handler's result and reports
+ * per-handler success / failure. Throws on a non-function argument.
+ *
+ * @example
+ *   var off = b.logStream.onIncoming(async function (payload) {
+ *     if (payload.command === "raise-log-level") return { applied: true };
+ *     return { applied: false };
+ *   });
+ *   // Later, when teardown is needed:
+ *   off();
+ */
 function onIncoming(handler) {
   if (typeof handler !== "function") {
     throw _err("INVALID_HANDLER", "onIncoming requires a function handler", true);
@@ -182,6 +316,31 @@ function onIncoming(handler) {
   };
 }
 
+/**
+ * @primitive b.logStream.deliverIncoming
+ * @signature b.logStream.deliverIncoming(payload, opts?)
+ * @since     0.0.13
+ * @related   b.logStream.onIncoming, b.audit.safeEmit
+ *
+ * Dispatch an inbound command-channel payload to every registered
+ * handler. The payload is redacted before audit and before handlers
+ * run, so even a noisy webhook receiver cannot smuggle secrets into
+ * the audit chain. Audit-logs the receipt under
+ * `system.log.incoming` BEFORE invoking handlers — handler exceptions
+ * never erase the receipt. Returns a per-handler `[{ ok, value? |
+ * error? }]` array; one handler throwing does not abort the rest.
+ *
+ * @opts
+ *   actor:  { userId?, sessionId?, ip?, userAgent? },   // audit context
+ *   source: string,                                     // transport name
+ *
+ * @example
+ *   var results = await b.logStream.deliverIncoming(
+ *     { command: "rotate-sink", sink: "file" },
+ *     { actor: { userId: "ops-42" }, source: "webhook" }
+ *   );
+ *   // → [{ ok: true, value: { applied: false } }]
+ */
 async function deliverIncoming(payload, opts) {
   opts = opts || {};
   var redacted = redactor.redact(payload);
@@ -204,6 +363,24 @@ async function deliverIncoming(payload, opts) {
   return results;
 }
 
+/**
+ * @primitive b.logStream.shutdown
+ * @signature b.logStream.shutdown()
+ * @since     0.0.13
+ * @related   b.logStream.init, b.appShutdown.create
+ *
+ * Drain pending fire-and-forget emits, close every sink (file fds,
+ * webhook keep-alive sockets, syslog connections, OTLP gRPC streams),
+ * and clear registered incoming handlers. Idempotent — safe to call
+ * twice. Records queued just before shutdown reach disk / the wire
+ * because in-flight Promises are tracked and awaited before close.
+ *
+ * @example
+ *   process.on("SIGTERM", async function () {
+ *     await b.logStream.shutdown();
+ *     process.exit(0);
+ *   });
+ */
 async function shutdown() {
   if (!initialized) return;
   // Drain any in-flight emits before closing sink fds so records
@@ -222,6 +399,23 @@ async function shutdown() {
   initialized = false;
 }
 
+/**
+ * @primitive b.logStream.listSinks
+ * @signature b.logStream.listSinks()
+ * @since     0.0.13
+ * @related   b.logStream.init
+ *
+ * Return one descriptor per configured sink: `{ name, protocol, stats
+ * }`. Sinks that expose a `stats()` method (file rotation counters,
+ * webhook batch metrics, OTLP queue depth) report through it; those
+ * that don't return `null`. Returns `[]` before `init()` runs, so
+ * health endpoints can call it unconditionally.
+ *
+ * @example
+ *   var snapshot = b.logStream.listSinks();
+ *   // → [{ name: "file", protocol: "local",
+ *   //      stats: { rotations: 2, bytesWritten: 4194304 } }]
+ */
 function listSinks() {
   if (!initialized) return [];
   return Object.keys(sinks).map(function (name) {
@@ -255,6 +449,42 @@ function listSinks() {
 //     BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_STREAM
 //   local-only:
 //     BLAMEJS_LOG_STREAM_PATH
+/**
+ * @primitive b.logStream.bootFromEnv
+ * @signature b.logStream.bootFromEnv(opts?)
+ * @since     0.6.25
+ * @related   b.logStream.init, b.network.bootFromEnv
+ *
+ * Operator-friendly env-driven init. Reads `BLAMEJS_LOG_STREAM_*` (and
+ * standard `AWS_*`) variables and constructs a single-sink
+ * configuration. Returns `false` and skips silently when
+ * `BLAMEJS_LOG_STREAM_PROTOCOL` is unset, so deployments that wire
+ * sinks through `init()` keep their existing config. Throws on an
+ * unknown protocol value.
+ *
+ * Recognised variables: `BLAMEJS_LOG_STREAM_PROTOCOL` (`local` |
+ * `webhook` | `otlp` | `cloudwatch`), `BLAMEJS_LOG_STREAM_MIN_LEVEL`,
+ * `BLAMEJS_LOG_STREAM_URL`, `BLAMEJS_LOG_STREAM_TOKEN`,
+ * `BLAMEJS_LOG_STREAM_SERVICE_NAME`, `BLAMEJS_LOG_STREAM_PATH`,
+ * `BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_GROUP`, plus `AWS_REGION` /
+ * `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`.
+ *
+ * @opts
+ *   env: object,   // override process.env (testing / fixtures)
+ *
+ * @example
+ *   // Operator sets BLAMEJS_LOG_STREAM_PROTOCOL=otlp and the URL in
+ *   // the deployment manifest; the framework wires the sink at boot.
+ *   var wired = b.logStream.bootFromEnv({
+ *     env: {
+ *       BLAMEJS_LOG_STREAM_PROTOCOL:     "otlp",
+ *       BLAMEJS_LOG_STREAM_URL:          "https://collector.internal:4318/v1/logs",
+ *       BLAMEJS_LOG_STREAM_SERVICE_NAME: "checkout",
+ *       BLAMEJS_LOG_STREAM_MIN_LEVEL:    "info",
+ *     },
+ *   });
+ *   // → true   (false when BLAMEJS_LOG_STREAM_PROTOCOL is unset)
+ */
 function bootFromEnv(opts) {
   opts = opts || {};
   var env = opts.env || process.env;