@ngockhoale/ukit 3.0.11 → 3.1.0

package/src/core/observability/emit/crash.js

@@ -0,0 +1,434 @@
+/**
+ * crash.js (TASK-004, SPEC §5 DF2-FR04, §7, §10) — bounded crash capture.
+ *
+ *   registerCrashCapture({ root, writerId, bootId, now? })
+ *     → { ok: true,  dispose, _onError }
+ *     → { ok: false, reason, dispose, _onError }
+ *   readCrashReports(root)
+ *     → { ok: true, crashes, coverage:{files,parsed,corrupt,expired} }
+ *     → { ok: false, reason }
+ *
+ * Behaviour contract (DF2-FR04):
+ *   - Installs process handlers for uncaughtException, unhandledRejection,
+ *     SIGINT, SIGTERM. Every capture is BEST-EFFORT: synchronous fs only
+ *     (signal handlers cannot await), never throws, never blocks.
+ *   - Writes `crashes/crash-<boot>-<seq>.json` via temp-write + rename
+ *     (all-or-nothing publish), capped at MAX_CRASH_FILES = 10, FIFO —
+ *     the oldest file is evicted, newest data wins (flight-recorder rule).
+ *     The seq counter is shared per (dir, bootId) so a second registration
+ *     in the same process appends instead of overwriting prior files.
+ *   - Original signal/error semantics are preserved (AC2). When several
+ *     captures are live the LAST-registered one decides fate; every
+ *     sibling still records first (Node emits to a listener snapshot —
+ *     removal mid-emit never skips a sibling's write). The deciding
+ *     handler strips all of this module's listeners for the event, so
+ *     the two-registration case can never mutual-defer into a live
+ *     process swallowing a fatal error/signal:
+ *       signals        — when a foreign listener survives we return and
+ *                        it decides; otherwise every listener is removed
+ *                        and we re-kill self with the same signal so the
+ *                        OS default (die by signal, exit 128+n) applies.
+ *       uncaughtException — when no foreign listener survives we print
+ *                        the original stack to stderr and exit(1) —
+ *                        UNCONDITIONALLY, a stderr/write failure must
+ *                        not leave the loop alive. (Re-throwing inside
+ *                        the handler exits 7, not 1 — it cannot restore
+ *                        the default, so we reproduce it explicitly.)
+ *       unhandledRejection — same rule; the reason is wrapped when it
+ *                        is not Error-like so a printed stack exists.
+ *   - Crash records pass through sanitizeObserved (the canonical write
+ *     gate): payload carries codes[], digest, kind/signal/error_kind/
+ *     exit_code ONLY — no stack strings, no paths, no argv, no messages.
+ *     `digest` is a sha256 of normalised stack frames (fn name + file
+ *     basename, line:col stripped) so identical crashes correlate
+ *     without leaking the filesystem layout.
+ *
+ * readCrashReports is synchronous by design (same fs-only constraint);
+ * callers may still `await` it harmlessly. `coverage.expired` counts
+ * crash files older than CRASH_EXPIRY_MS (30 days) — they are excluded
+ * from `crashes` and are candidates for projection-side cleanup.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { sanitizeObserved } from '../privacy/sanitizeObserved.js';
+import { SCHEMA_VERSION } from '../schema/constants.js';
+import { ioReason, sanitizeNameComponent } from '../segments/internal.js';
+
+export const CRASH_DIR_NAME = 'crashes';
+export const MAX_CRASH_FILES = 10;
+export const CRASH_EXPIRY_MS = 30 * 24 * 60 * 60 * 1000;
+
+const CRASH_FILE_RE = /^crash-.+\.json$/;
+const SIGNALS = ['SIGINT', 'SIGTERM'];
+/** Conventional shell exit codes (128 + signal number) for the kill fallback. */
+const SIGNAL_EXIT_CODES = Object.freeze({ SIGINT: 130, SIGTERM: 143 });
+const ERROR_CODE_RE = /^[A-Z][A-Z0-9_]*$/;
+const SAFE_IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * Process-wide coordination between concurrent registrations.
+ *
+ * liveOrder — event name → registered handler list in listener order. A
+ *   second registerCrashCapture must NOT defuse the process: every
+ *   capture still records (Node emits to a listener snapshot — removing
+ *   listeners mid-emit never skips them), then the LAST-registered live
+ *   handler alone decides fate. Without this, two captures each see
+ *   "another listener exists", both defer, and a fatal signal/error
+ *   leaves the process alive.
+ * fileSeq — file-key prefix (dir + sanitized boot id) → last assigned
+ *   seq. Two registrations sharing root+bootId would otherwise each
+ *   count their own seq from 1 and overwrite each other's
+ *   `crash-<boot>-<seq>.json` records.
+ */
+const liveOrder = new Map();
+const fileSeq = new Map();
+
+function orderAdd(event, handler) {
+  const order = liveOrder.get(event);
+  if (order) order.push(handler);
+  else liveOrder.set(event, [handler]);
+}
+
+function orderRemove(event, handler) {
+  const order = liveOrder.get(event);
+  if (!order) return;
+  const i = order.indexOf(handler);
+  if (i >= 0) order.splice(i, 1);
+  if (order.length === 0) liveOrder.delete(event);
+}
+
+/** True when this handler is the last live capture for `event`. */
+function decidesFate(event, handler) {
+  const order = liveOrder.get(event);
+  return Boolean(order) && order.length > 0 && order[order.length - 1] === handler;
+}
+
+/** Monotonic per-(dir,bootId) sequence — shared across registrations. */
+function nextFileSeq(dir, bootKey) {
+  const key = `${dir}::${bootKey}`;
+  const seq = (fileSeq.get(key) || 0) + 1;
+  fileSeq.set(key, seq);
+  return seq;
+}
+
+/** Numeric seq parsed from a crash filename (0 when absent/malformed). */
+function fileSeqOf(name) {
+  const m = /-(\d+)\.json$/.exec(name);
+  return m ? Number(m[1]) : 0;
+}
+
+function sha256(text) {
+  return 'sha256:' + crypto.createHash('sha256').update(text).digest('hex');
+}
+
+function isErrorLike(value) {
+  return value instanceof Error || (value !== null && typeof value === 'object' && typeof value.name === 'string' && typeof value.stack === 'string');
+}
+
+/**
+ * Reduce a stack to frame signatures: function name + file basename,
+ * absolute path segments and line:col stripped. Never persisted raw —
+ * only hashed into `digest`.
+ */
+function normalizeStackFrames(stack) {
+  if (typeof stack !== 'string') return null;
+  const frames = [];
+  for (const rawLine of stack.split('\n')) {
+    const line = rawLine.trim();
+    if (!line.startsWith('at ')) continue;
+    let s = line.slice(3).trim();
+    s = s.replace(/^file:\/\//, '');
+    // Unwrap `fn (location)` → `fn location`.
+    s = s.replace(/\(([^()]*)\)/g, ' $1 ');
+    // Collapse any absolute path (posix or windows) to its basename.
+    s = s.replace(/(?:[A-Za-z]:)?[\\/][^\s()]*?[\\/]([^\\/()\s]+)/g, '$1');
+    s = s.replace(/:[0-9]+(?::[0-9]+)?/g, '');
+    s = s.replace(/\s+/g, ' ').trim();
+    if (s.length > 0) frames.push(s);
+    if (frames.length >= 16) break;
+  }
+  return frames.length > 0 ? frames : null;
+}
+
+function errorKindOf(err, trigger) {
+  if (trigger === 'SIGINT' || trigger === 'SIGTERM') return null;
+  if (isErrorLike(err)) {
+    const name = typeof err.name === 'string' && SAFE_IDENTIFIER_RE.test(err.name) ? err.name : 'Error';
+    return name;
+  }
+  return 'non_error';
+}
+
+function codesFor(err, trigger) {
+  const codes = [String(trigger).toUpperCase()];
+  if (isErrorLike(err) && typeof err.code === 'string' && ERROR_CODE_RE.test(err.code) && !codes.includes(err.code)) {
+    codes.push(err.code);
+  }
+  return codes.slice(0, 4);
+}
+
+function digestOf(err, trigger, errorKind) {
+  const frames = isErrorLike(err) ? normalizeStackFrames(err.stack) : null;
+  const basis = frames ? `${trigger}\n${frames.join('\n')}` : `${trigger}|${errorKind || ''}`;
+  return sha256(basis);
+}
+
+function toError(value) {
+  if (isErrorLike(value)) return value;
+  return new Error('Unhandled rejection with non-Error reason');
+}
+
+/**
+ * Synchronous read of the crash directory for projection/health surfaces.
+ * @returns {{ok:true,crashes:object[],coverage:{files:number,parsed:number,corrupt:number,expired:number}}
+ *          |{ok:false,reason:string}}
+ */
+export function readCrashReports(root) {
+  const empty = { files: 0, parsed: 0, corrupt: 0, expired: 0 };
+  if (typeof root !== 'string' || root.length === 0) {
+    return { ok: false, reason: 'invalid_root' };
+  }
+  const dir = path.join(root, CRASH_DIR_NAME);
+  let names;
+  try {
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) {
+      return { ok: false, reason: 'unsupported_file_type' };
+    }
+    names = fs.readdirSync(dir).filter((n) => CRASH_FILE_RE.test(n));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { ok: true, crashes: [], coverage: empty };
+    }
+    return { ok: false, reason: ioReason(err) };
+  }
+
+  const nowMs = Date.now();
+  const crashes = [];
+  const coverage = { ...empty };
+  for (const name of names) {
+    coverage.files += 1;
+    const file = path.join(dir, name);
+    try {
+      const st = fs.statSync(file);
+      if (nowMs - st.mtimeMs > CRASH_EXPIRY_MS) {
+        coverage.expired += 1;
+        continue;
+      }
+      const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+        coverage.corrupt += 1;
+        continue;
+      }
+      coverage.parsed += 1;
+      crashes.push({ file: name, mtime_ms: st.mtimeMs, record });
+    } catch {
+      coverage.corrupt += 1;
+    }
+  }
+  // Newest first — mtime desc; numeric seq desc on ties so seq 10 sorts
+  // after seq 9 (a lexical filename tiebreak inverts them); lexical asc
+  // for deterministic order across boots when both fields tie.
+  crashes.sort((a, b) => (b.mtime_ms - a.mtime_ms) || (fileSeqOf(b.file) - fileSeqOf(a.file)) || (a.file < b.file ? -1 : 1));
+  return { ok: true, crashes: crashes.map((c) => c.record), coverage };
+}
+
+/**
+ * Install bounded crash capture. Never throws.
+ * `now` is an injectable wall clock returning epoch milliseconds.
+ */
+export function registerCrashCapture({ root, writerId, bootId, now } = {}) {
+  const validRoot = typeof root === 'string' && root.length > 0;
+  const dir = validRoot ? path.join(root, CRASH_DIR_NAME) : null;
+  const clock = typeof now === 'function' ? now : Date.now;
+  const state = {
+    disposed: false,
+    bootKey: sanitizeNameComponent(bootId),
+    // Rejection reasons re-emitted for capture are deduped once. WeakSet —
+    // a long-lived capture must not retain every captured error object.
+    seen: new WeakSet(),
+  };
+
+  function wallTimeUtc() {
+    try {
+      const t = new Date(clock());
+      return Number.isNaN(t.getTime()) ? new Date().toISOString() : t.toISOString();
+    } catch {
+      return new Date().toISOString();
+    }
+  }
+
+  function pruneCrashes() {
+    // Oldest-by-sequence evicted first; mtimes are a fallback only (two
+    // writes can share an mtime tick and lexical seq order is wrong for
+    // seq ≥ 10). Best-effort: individual unlink failures are ignored.
+    const names = fs.readdirSync(dir)
+      .filter((n) => CRASH_FILE_RE.test(n))
+      .map((n) => {
+        const m = /-(\d+)\.json$/.exec(n);
+        return { name: n, seq: m ? Number(m[1]) : Number.MAX_SAFE_INTEGER };
+      })
+      .sort((a, b) => a.seq - b.seq || (a.name < b.name ? -1 : 1));
+    for (let i = 0; i < names.length - MAX_CRASH_FILES; i += 1) {
+      try { fs.unlinkSync(path.join(dir, names[i].name)); } catch {}
+    }
+  }
+
+  function writeRecord(record, name) {
+    const target = path.join(dir, name);
+    const tmpPath = `${target}.tmp-${process.pid}`;
+    try {
+      fs.writeFileSync(tmpPath, `${JSON.stringify(record)}\n`, 'utf8');
+      fs.renameSync(tmpPath, target);
+    } catch (err) {
+      try { fs.unlinkSync(tmpPath); } catch {}
+      throw err;
+    }
+  }
+
+  // The exported injection seam (tests call it directly; handlers bind it).
+  function _onError(err, trigger = 'uncaught_exception') {
+    try {
+      if (state.disposed || dir === null) return;
+      if (err !== null && (typeof err === 'object' || typeof err === 'function')) {
+        if (state.seen.has(err)) return;
+        state.seen.add(err);
+      }
+
+      const isSignal = trigger === 'SIGINT' || trigger === 'SIGTERM';
+      const errorKind = errorKindOf(err, trigger);
+      const payload = {
+        kind: isSignal ? 'signal' : 'error',
+        codes: codesFor(err, trigger),
+        digest: digestOf(err, trigger, errorKind),
+      };
+      if (isSignal) {
+        payload.signal = trigger;
+        payload.exit_code = SIGNAL_EXIT_CODES[trigger] || 1;
+      } else {
+        payload.error_kind = errorKind;
+      }
+
+      const sanitized = sanitizeObserved({
+        record_type: 'fact',
+        semantic_name: 'telemetry.crashed',
+        schema_version: SCHEMA_VERSION,
+        boot_id: String(bootId ?? 'unknown'),
+        writer_id: String(writerId ?? 'unknown'),
+        wall_time_utc: wallTimeUtc(),
+        importance: 'high',
+        privacy_class: 'private',
+        payload,
+      });
+      if (!sanitized.ok) return;
+
+      fs.mkdirSync(dir, { recursive: true });
+      writeRecord(
+        sanitized.record,
+        `crash-${state.bootKey}-${nextFileSeq(dir, state.bootKey)}.json`,
+      );
+      pruneCrashes();
+    } catch {
+      // Best-effort by contract: a capture failure can never take the
+      // process down, so every path out of here is silent.
+    }
+  }
+
+  // --- handler wiring -------------------------------------------------------
+
+  /**
+   * Reproduce Node's default fatal semantics once we are the sole
+   * listener: raw stack (or reason text) to stderr, exit code 1. The
+   * exit is UNCONDITIONAL — a stderr/write failure must still end the
+   * process, never silently swallow a fatal error (setting only
+   * process.exitCode leaves an alive loop running: STILL ALIVE repro).
+   */
+  function fatalExit(err) {
+    try {
+      process.removeAllListeners('uncaughtException');
+      process.removeAllListeners('unhandledRejection');
+      const errLike = toError(err);
+      process.stderr.write(`${errLike.stack || errLike}\n`);
+    } catch {
+      // Reporting is best-effort; the exit below must run regardless.
+    }
+    process.exit(1);
+  }
+
+  function onUncaughtException(err) {
+    _onError(err, 'uncaught_exception');
+    if (!decidesFate('uncaughtException', onUncaughtException)) return;
+    // A surviving foreign delegate owns the process fate — do not exit.
+    if (process.listenerCount('uncaughtException') > liveOrder.get('uncaughtException').length) return;
+    fatalExit(err);
+  }
+
+  function onUnhandledRejection(reason) {
+    _onError(reason, 'unhandled_rejection');
+    if (!decidesFate('unhandledRejection', onUnhandledRejection)) return;
+    if (process.listenerCount('unhandledRejection') > liveOrder.get('unhandledRejection').length) return;
+    fatalExit(reason);
+  }
+
+  const signalHandlers = new Map();
+  function onSignal(signal) {
+    const handler = signalHandlers.get(signal);
+    _onError(null, signal);
+    if (!decidesFate(signal, handler)) return;
+    const order = liveOrder.get(signal);
+    // Foreign delegate owns the fate when one survives our listeners.
+    if (process.listenerCount(signal) > order.length) return;
+    // Restore OS semantics: strip every listener on the signal (sibling
+    // captures already recorded — Node emitted to a snapshot, so removal
+    // mid-emit never skips them), then re-raise the same signal on self.
+    // POSIX kills synchronously; the explicit exit covers platforms where
+    // the kill is emulated (Windows) so 128+n is still honoured.
+    process.removeAllListeners(signal);
+    try {
+      process.kill(process.pid, signal);
+    } catch {}
+    process.exit(SIGNAL_EXIT_CODES[signal] || 1);
+  }
+
+  process.on('uncaughtException', onUncaughtException);
+  orderAdd('uncaughtException', onUncaughtException);
+  process.on('unhandledRejection', onUnhandledRejection);
+  orderAdd('unhandledRejection', onUnhandledRejection);
+  for (const signal of SIGNALS) {
+    const handler = () => onSignal(signal);
+    signalHandlers.set(signal, handler);
+    process.on(signal, handler);
+    orderAdd(signal, handler);
+  }
+
+  function dispose() {
+    if (state.disposed) return;
+    state.disposed = true;
+    process.removeListener('uncaughtException', onUncaughtException);
+    orderRemove('uncaughtException', onUncaughtException);
+    process.removeListener('unhandledRejection', onUnhandledRejection);
+    orderRemove('unhandledRejection', onUnhandledRejection);
+    for (const [signal, handler] of signalHandlers) {
+      process.removeListener(signal, handler);
+      orderRemove(signal, handler);
+    }
+    signalHandlers.clear();
+  }
+
+  // --- initial dir probe ----------------------------------------------------
+  // Handlers are installed even when the probe fails: the dir may become
+  // writable later, and every write retries mkdir — capture stays silent
+  // and best-effort either way.
+  if (!validRoot) {
+    return { ok: false, reason: 'invalid_root', dispose, _onError };
+  }
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    return { ok: false, reason: ioReason(err), dispose, _onError };
+  }
+  return { ok: true, dispose, _onError };
+}