@blamejs/core 0.6.12 → 0.6.20

package/lib/network.js

@@ -0,0 +1,233 @@
+"use strict";
+
+var ntpCheck = require("./ntp-check");
+var nts      = require("./network-nts");
+var dns      = require("./network-dns");
+var proxy    = require("./network-proxy");
+var trust    = require("./network-tls");
+var heartbeat = require("./network-heartbeat");
+
+var validateOpts = require("./validate-opts");
+var lazyRequire = require("./lazy-require");
+var { defineClass } = require("./framework-error");
+
+var NetworkError = defineClass("NetworkError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("./observability"); });
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var SOCKET_DEFAULTS = {
+  noDelay:           true,
+  keepAlive:         true,
+  keepAliveInitialDelayMs: 0,
+};
+
+function _setSocketNoDelay(value) {
+  if (typeof value !== "boolean") {
+    throw new NetworkError("socket/bad-no-delay", "socket.setDefaultNoDelay: expected boolean, got " + typeof value);
+  }
+  SOCKET_DEFAULTS.noDelay = value;
+}
+
+function _setSocketKeepAlive(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["enable", "initialDelayMs"], "socket.setDefaultKeepAlive");
+  if (opts.enable !== undefined) {
+    if (typeof opts.enable !== "boolean") {
+      throw new NetworkError("socket/bad-keepalive", "socket.setDefaultKeepAlive: enable must be boolean");
+    }
+    SOCKET_DEFAULTS.keepAlive = opts.enable;
+  }
+  if (opts.initialDelayMs !== undefined) {
+    if (typeof opts.initialDelayMs !== "number" || !isFinite(opts.initialDelayMs) || opts.initialDelayMs < 0) {
+      throw new NetworkError("socket/bad-keepalive-delay", "socket.setDefaultKeepAlive: initialDelayMs must be non-negative finite number");
+    }
+    SOCKET_DEFAULTS.keepAliveInitialDelayMs = opts.initialDelayMs;
+  }
+}
+
+// SO_LINGER is intentionally NOT exposed: Node's net.Socket has no
+// public setLinger() method (the option is tracked at
+// nodejs/node#27293 / rejected for the public surface). Reaching into
+// socket._handle to call setLinger is an unstable internal API. The
+// closest operator-exposed semantic is socket.destroy() (RST = "abort
+// on close") vs socket.end() (graceful FIN). Operators needing true
+// SO_LINGER should use a native binding outside the framework. This
+// stub stays in the export with throw-on-call so a future Node release
+// that exposes setLinger can be wired without an API addition.
+function _setSocketLinger(_opts) {
+  throw new NetworkError("socket/linger-not-supported",
+    "socket.setDefaultLinger: SO_LINGER is not exposed by Node's public net.Socket API " +
+    "(see nodejs/node#27293). Use socket.destroy() (abort) vs socket.end() (graceful) " +
+    "to control close semantics, or a native binding if true SO_LINGER is required.");
+}
+
+function _socketDefaults() {
+  return {
+    noDelay:                 SOCKET_DEFAULTS.noDelay,
+    keepAlive:               SOCKET_DEFAULTS.keepAlive,
+    keepAliveInitialDelayMs: SOCKET_DEFAULTS.keepAliveInitialDelayMs,
+  };
+}
+
+function applyToSocket(socket) {
+  if (!socket) return socket;
+  try {
+    if (typeof socket.setNoDelay === "function") socket.setNoDelay(SOCKET_DEFAULTS.noDelay);
+    if (typeof socket.setKeepAlive === "function") {
+      socket.setKeepAlive(SOCKET_DEFAULTS.keepAlive, SOCKET_DEFAULTS.keepAliveInitialDelayMs || 0);
+    }
+  } catch (_e) {}
+  return socket;
+}
+
+var ntpFacade = {
+  querySingle:    ntpCheck.querySingle,
+  checkDrift:     ntpCheck.checkDrift,
+  bootCheck:      ntpCheck.bootCheck,
+  setThresholds:  ntpCheck.setThresholds,
+  getThresholds:  ntpCheck.getThresholds,
+  setServers:     function (list) {
+    if (!Array.isArray(list) || list.length === 0) {
+      throw new NetworkError("ntp/bad-servers", "ntp.setServers: expected non-empty array");
+    }
+    ntpFacade._defaultServers = list.slice();
+    _emitObs("network.ntp.servers.set", { count: list.length });
+  },
+  getServers:     function () {
+    return (ntpFacade._defaultServers || ntpCheck.DEFAULT_SERVERS).slice();
+  },
+  _defaultServers: null,
+  nts:            nts,
+};
+
+function bootFromEnv(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["env", "audit"], "network.bootFromEnv");
+  var env = opts.env || process.env;
+  var applied = { ntp: {}, dns: {}, proxy: false, tls: {}, heartbeat: 0, socket: {} };
+
+  if (env.BLAMEJS_NTP_SERVERS) {
+    var list = String(env.BLAMEJS_NTP_SERVERS).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+    if (list.length > 0) { ntpFacade.setServers(list); applied.ntp.servers = list.length; }
+  }
+  var ntpTimeout = env.BLAMEJS_NTP_TIMEOUT_MS;
+  if (ntpTimeout) {
+    var t = parseInt(ntpTimeout, 10);
+    if (isFinite(t) && t > 0) { ntpFacade._defaultTimeoutMs = t; applied.ntp.timeoutMs = t; }
+  }
+  var ntpWarn = env.BLAMEJS_NTP_DRIFT_WARN_MS;
+  var ntpFatal = env.BLAMEJS_NTP_DRIFT_FATAL_MS;
+  if (ntpWarn || ntpFatal) {
+    var thr = {};
+    if (ntpWarn)  { thr.warnMs  = parseInt(ntpWarn, 10);  applied.ntp.warnMs  = thr.warnMs; }
+    if (ntpFatal) { thr.fatalMs = parseInt(ntpFatal, 10); applied.ntp.fatalMs = thr.fatalMs; }
+    ntpCheck.setThresholds(thr);
+  }
+
+  var dnsServers = env.BLAMEJS_DNS_SERVERS;
+  if (dnsServers) {
+    var dl = String(dnsServers).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+    if (dl.length > 0) { dns.setServers(dl); applied.dns.servers = dl.length; }
+  }
+  if (env.BLAMEJS_DNS_RESULT_ORDER)  { dns.setResultOrder(env.BLAMEJS_DNS_RESULT_ORDER); applied.dns.resultOrder = env.BLAMEJS_DNS_RESULT_ORDER; }
+  if (env.BLAMEJS_DNS_FAMILY)        { dns.setFamily(parseInt(env.BLAMEJS_DNS_FAMILY, 10)); applied.dns.family = parseInt(env.BLAMEJS_DNS_FAMILY, 10); }
+  if (env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS) { dns.setLookupTimeoutMs(parseInt(env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS, 10)); applied.dns.lookupTimeoutMs = parseInt(env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS, 10); }
+  if (env.BLAMEJS_DNS_CACHE_TTL_MS)      { dns.setCacheTtlMs(parseInt(env.BLAMEJS_DNS_CACHE_TTL_MS, 10)); applied.dns.cacheTtlMs = parseInt(env.BLAMEJS_DNS_CACHE_TTL_MS, 10); }
+  if (env.BLAMEJS_DOH_URL)               { dns.useDnsOverHttps({ url: env.BLAMEJS_DOH_URL }); applied.dns.doh = env.BLAMEJS_DOH_URL; }
+  else if (env.BLAMEJS_DOH_PROVIDER)     { dns.useDnsOverHttps({ provider: env.BLAMEJS_DOH_PROVIDER }); applied.dns.dohProvider = env.BLAMEJS_DOH_PROVIDER; }
+  if (env.BLAMEJS_DOT_HOST)              { dns.useDnsOverTls({ host: env.BLAMEJS_DOT_HOST, port: env.BLAMEJS_DOT_PORT ? parseInt(env.BLAMEJS_DOT_PORT, 10) : 853 }); applied.dns.dot = env.BLAMEJS_DOT_HOST; }
+
+  if (env.HTTP_PROXY || env.http_proxy || env.HTTPS_PROXY || env.https_proxy ||
+      env.NO_PROXY  || env.no_proxy  || env.ALL_PROXY    || env.all_proxy) {
+    applied.proxy = proxy.fromEnv(env);
+  }
+
+  if (env.BLAMEJS_EXTRA_CA_CERTS) {
+    trust.addCa(env.BLAMEJS_EXTRA_CA_CERTS, { label: "BLAMEJS_EXTRA_CA_CERTS" });
+    applied.tls.fileLoaded = env.BLAMEJS_EXTRA_CA_CERTS;
+  }
+  if (env.BLAMEJS_EXTRA_CA_CERTS_DIR) {
+    trust.addCaBundle(env.BLAMEJS_EXTRA_CA_CERTS_DIR, { label: "BLAMEJS_EXTRA_CA_CERTS_DIR" });
+    applied.tls.dirLoaded = env.BLAMEJS_EXTRA_CA_CERTS_DIR;
+  }
+  if (env.BLAMEJS_USE_SYSTEM_TRUST === "1" || env.BLAMEJS_USE_SYSTEM_TRUST === "true") {
+    trust.useSystemTrust(true);
+    applied.tls.systemTrust = true;
+  }
+
+  if (env.BLAMEJS_SOCKET_NO_DELAY)             _setSocketNoDelay(env.BLAMEJS_SOCKET_NO_DELAY === "1" || env.BLAMEJS_SOCKET_NO_DELAY === "true");
+  if (env.BLAMEJS_SOCKET_KEEPALIVE)            _setSocketKeepAlive({ enable: env.BLAMEJS_SOCKET_KEEPALIVE === "1" || env.BLAMEJS_SOCKET_KEEPALIVE === "true" });
+  if (env.BLAMEJS_SOCKET_KEEPALIVE_DELAY_MS)   _setSocketKeepAlive({ initialDelayMs: parseInt(env.BLAMEJS_SOCKET_KEEPALIVE_DELAY_MS, 10) });
+  applied.socket = _socketDefaults();
+
+  var auditOn = opts.audit !== false;
+  if (auditOn) {
+    var sink;
+    try { sink = audit(); } catch (_e) { sink = null; }
+    if (sink && typeof sink.safeEmit === "function") {
+      try {
+        sink.safeEmit({
+          action:   "network.boot.from_env",
+          outcome:  "success",
+          metadata: applied,
+        });
+      } catch (_e) {}
+    }
+  }
+  _emitObs("network.boot.from_env", { source: "env" });
+  return applied;
+}
+
+function snapshot() {
+  return {
+    ntp: {
+      servers:     ntpFacade.getServers(),
+      thresholds:  ntpCheck.getThresholds(),
+    },
+    dns: dns._stateForTest(),
+    proxy: proxy.snapshot(),
+    tls:  {
+      systemTrust: trust.isSystemTrustEnabled(),
+      caCount:     trust.getTrustStore().length,
+    },
+    heartbeat: heartbeat.statuses(),
+    socket: _socketDefaults(),
+  };
+}
+
+function _emitObs(name, fields) {
+  try { observability().emit(name, fields || {}); } catch (_e) {}
+}
+
+function _resetForTest() {
+  ntpFacade._defaultServers = null;
+  ntpFacade._defaultTimeoutMs = null;
+  if (typeof ntpCheck._resetThresholdsForTest === "function") ntpCheck._resetThresholdsForTest();
+  dns._resetForTest();
+  proxy._resetForTest();
+  trust._resetForTest();
+  heartbeat._resetForTest();
+  SOCKET_DEFAULTS.noDelay = true;
+  SOCKET_DEFAULTS.keepAlive = true;
+  SOCKET_DEFAULTS.keepAliveInitialDelayMs = 0;
+}
+
+module.exports = {
+  ntp:        ntpFacade,
+  dns:        dns,
+  proxy:      proxy,
+  tls:        trust,
+  heartbeat:  heartbeat,
+  socket: {
+    setDefaultNoDelay:   _setSocketNoDelay,
+    setDefaultKeepAlive: _setSocketKeepAlive,
+    setDefaultLinger:    _setSocketLinger,
+    defaults:            _socketDefaults,
+    applyToSocket:       applyToSocket,
+  },
+  bootFromEnv:    bootFromEnv,
+  snapshot:       snapshot,
+  NetworkError:   NetworkError,
+  _resetForTest:  _resetForTest,
+};

package/lib/notify.js

@@ -49,6 +49,7 @@
 
 var lazyRequire = require("./lazy-require");
 var bootLog = require("./log");
+var numericChecks = require("./numeric-checks");
 var requestHelpers = require("./request-helpers");
 var safeAsync = require("./safe-async");
 var safeUrl = require("./safe-url");
@@ -76,9 +77,7 @@ var DEFAULTS = Object.freeze({
 
 // ---- Call-site validation (throw on bad input) ----
 
-function _isFiniteNonNegative(n) {
-  return typeof n === "number" && isFinite(n) && n >= 0;
-}
+var _isFiniteNonNegative = numericChecks.isFiniteNonNegative;
 
 function _validateTransport(name, t) {
   if (!t || typeof t !== "object") {

package/lib/ntp-check.js

@@ -36,6 +36,43 @@ var DEFAULT_SERVERS = ["pool.ntp.org", "time.cloudflare.com"];
 var DEFAULT_PORT    = 123;
 var DEFAULT_TIMEOUT_MS = 3000;
 
+var DEFAULT_DRIFT_WARN_MS  = C.TIME.minutes(5);
+var DEFAULT_DRIFT_FATAL_MS = C.TIME.hours(1);
+
+var thresholds = {
+  warnMs:  DEFAULT_DRIFT_WARN_MS,
+  fatalMs: DEFAULT_DRIFT_FATAL_MS,
+};
+
+function setThresholds(opts) {
+  opts = opts || {};
+  if (opts.warnMs !== undefined) {
+    if (typeof opts.warnMs !== "number" || !isFinite(opts.warnMs) || opts.warnMs < 0) {
+      throw new TypeError("ntpCheck.setThresholds: warnMs must be non-negative finite number, got " + JSON.stringify(opts.warnMs));
+    }
+    thresholds.warnMs = opts.warnMs;
+  }
+  if (opts.fatalMs !== undefined) {
+    if (typeof opts.fatalMs !== "number" || !isFinite(opts.fatalMs) || opts.fatalMs < 0) {
+      throw new TypeError("ntpCheck.setThresholds: fatalMs must be non-negative finite number, got " + JSON.stringify(opts.fatalMs));
+    }
+    thresholds.fatalMs = opts.fatalMs;
+  }
+  if (thresholds.warnMs > thresholds.fatalMs && thresholds.fatalMs > 0) {
+    throw new RangeError("ntpCheck.setThresholds: warnMs (" + thresholds.warnMs +
+      ") must be <= fatalMs (" + thresholds.fatalMs + ")");
+  }
+}
+
+function getThresholds() {
+  return { warnMs: thresholds.warnMs, fatalMs: thresholds.fatalMs };
+}
+
+function _resetThresholdsForTest() {
+  thresholds.warnMs  = DEFAULT_DRIFT_WARN_MS;
+  thresholds.fatalMs = DEFAULT_DRIFT_FATAL_MS;
+}
+
 /**
  * Query an NTP server once. Resolves with { driftMs, serverTimeMs } or
  * rejects with { code, message } where code is one of:
@@ -142,22 +179,26 @@ async function bootCheck(opts) {
   }
   var absMs = Math.abs(result.driftMs);
   var driftStr = (result.driftMs >= 0 ? "+" : "") + result.driftMs + "ms";
-  if (absMs >= C.TIME.hours(1)) {
+  var fatalMs = (opts && typeof opts.driftFatalMs === "number") ? opts.driftFatalMs : thresholds.fatalMs;
+  var warnMs  = (opts && typeof opts.driftWarnMs  === "number") ? opts.driftWarnMs  : thresholds.warnMs;
+  if (fatalMs > 0 && absMs >= fatalMs) {
     return {
       ok:       false,
       severity: "fatal",
       driftMs:  result.driftMs,
       server:   result.server,
-      message:  "clock drift " + driftStr + " from " + result.server + " (>= 1 hour) — refuse to boot",
+      message:  "clock drift " + driftStr + " from " + result.server +
+                " (>= " + fatalMs + "ms) — refuse to boot",
     };
   }
-  if (absMs >= C.TIME.minutes(5)) {
+  if (warnMs > 0 && absMs >= warnMs) {
     return {
       ok:       true,
       severity: "warning",
       driftMs:  result.driftMs,
       server:   result.server,
-      message:  "clock drift " + driftStr + " from " + result.server + " (>= 5 minutes) — investigate",
+      message:  "clock drift " + driftStr + " from " + result.server +
+                " (>= " + warnMs + "ms) — investigate",
     };
   }
   return {
@@ -173,6 +214,11 @@ module.exports = {
   querySingle:               querySingle,
   checkDrift:                checkDrift,
   bootCheck:                 bootCheck,
+  setThresholds:             setThresholds,
+  getThresholds:             getThresholds,
   DEFAULT_SERVERS:           DEFAULT_SERVERS,
+  DEFAULT_DRIFT_WARN_MS:     DEFAULT_DRIFT_WARN_MS,
+  DEFAULT_DRIFT_FATAL_MS:    DEFAULT_DRIFT_FATAL_MS,
   NTP_TO_UNIX_OFFSET_SECONDS: NTP_TO_UNIX_OFFSET_SECONDS,
+  _resetThresholdsForTest:   _resetThresholdsForTest,
 };

package/lib/numeric-checks.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * numeric-checks — predicate helpers for opts / arg validation.
+ *
+ * Existed previously as private `_isPositiveInt` / `_isFiniteNonNegative`
+ * / `_isNonNegFinite` copies inside api-key, cache, notify, retry, slug,
+ * testing, webhook, and (new in v0.6.12) inline checks in queue and
+ * restore. Same shape, different file — that's the repeat-means-primitive
+ * rule. Everything routes through here now so adding (e.g.) NaN-or-
+ * Infinity-string handling is a one-file change.
+ *
+ * Predicates only — callers throw with their own framework-error class.
+ *
+ *   isPositiveInt(n)        n is a finite integer >= 1
+ *   isFiniteNonNegative(n)  n is a finite number >= 0
+ *   isPositiveFinite(n)     n is a finite number > 0
+ *
+ * All return false for non-numbers, NaN, Infinity, -Infinity, null,
+ * undefined, strings, etc. — operators get one consistent gate against
+ * the silent-NaN-cap class of bug regardless of which primitive they're
+ * configuring.
+ */
+
+function isPositiveInt(n) {
+  return typeof n === "number" && isFinite(n) && n >= 1 && Math.floor(n) === n;
+}
+
+function isFiniteNonNegative(n) {
+  return typeof n === "number" && isFinite(n) && n >= 0;
+}
+
+function isPositiveFinite(n) {
+  return typeof n === "number" && isFinite(n) && n > 0;
+}
+
+module.exports = {
+  isPositiveInt:        isPositiveInt,
+  isFiniteNonNegative:  isFiniteNonNegative,
+  isPositiveFinite:     isPositiveFinite,
+};

package/lib/object-store/azure-blob.js

@@ -400,49 +400,23 @@ function create(config) {
   function presignedUploadUrl(opts)   { return _presign("PUT", "cw", opts); }
   function presignedDownloadUrl(opts) { return _presign("GET", "r",  opts); }
 
-  // Azure SAS doesn't support an equivalent of S3 / GCS POST policy
-  // with a content-length-range constraint. The SAS spec carries
-  // permissions / start / expiry / IP / protocol / resource-content-
-  // headers but no body-size cap — Azure validates the upload at the
-  // service level only via the operator's optional Block Blob size
-  // limit applied at storage-account or container scope, not via the
-  // SAS token itself.
+  // Azure SAS has no equivalent of S3 / GCS POST policy with a
+  // content-length-range constraint — the SAS spec carries permissions
+  // / start / expiry / IP / protocol / resource-content-headers but
+  // no body-size cap. Returning a PUT URL under the POST-policy name
+  // would be a silent shape mismatch (operators wiring an HTML form
+  // expecting multipart fields get a PUT URL with no fields), so the
+  // azure-blob backend refuses cleanly.
   //
-  // Rather than throw NOT_SUPPORTED, this returns the same SAS PUT
-  // shape as presignedUploadUrl with an `enforcement: 'client-only'`
-  // marker so operators making cross-vendor decisions know the
-  // body-size guard is advisory on Azure and must be enforced on the
-  // client side or via a server-side post-upload check.
-  //
-  // For strict server-side body-size enforcement on Azure, the
-  // canonical pattern is: SAS-authorize the upload, then have the
-  // operator's app issue a HEAD on the resulting blob and delete +
-  // 4xx the requester if Content-Length > opts.maxBytes.
-  function presignedUploadPolicy(opts) {
-    opts = opts || {};
-    if (typeof opts.maxBytes !== "number" || !Number.isFinite(opts.maxBytes) ||
-        opts.maxBytes <= 0) {
-      throw _err("INVALID_MAX_BYTES",
-        "presignedUploadPolicy: maxBytes (positive number of bytes) is required " +
-        "(advisory on Azure — see docstring for server-side enforcement)", true);
-    }
-    var underlying = _presign("PUT", "cw", opts);
-    return {
-      url:           underlying.url,
-      method:        "PUT",
-      // SAS uploads are PUT, not multipart POST — there are no form
-      // fields. Operators uploading attach the body directly to the
-      // returned URL with the headers in `headers`.
-      fields:        null,
-      headers:       underlying.headers,
-      expiresAt:     underlying.expiresAt,
-      maxBytes:      opts.maxBytes,
-      enforcement:   "client-only",
-      enforcementNote:
-        "Azure SAS does not natively cap upload size. Operators needing " +
-        "strict size enforcement must HEAD the blob post-upload and reject " +
-        "if Content-Length exceeds maxBytes.",
-    };
+  // For strict server-side body-size enforcement on Azure: use
+  // presignedUploadUrl + a server-side post-upload HEAD that deletes
+  // and 4xxs the requester if Content-Length > limit.
+  function presignedUploadPolicy(_opts) {
+    throw _err("PRESIGN_NOT_SUPPORTED",
+      "azure-blob backend does not support presigned upload policies — " +
+      "Azure SAS has no body-size cap. Use presignedUploadUrl + a server-side " +
+      "HEAD-and-delete check, or switch to an S3 / GCS-compatible backend.",
+      true);
   }
 
   return {