@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/test/helpers/mocks.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * HTTP request/response mocks for middleware-style tests.
+ *
+ * As of v0.2.38 these are thin re-exports of `b.testing.{mockReq,
+ * mockRes, bodyReq, bodyRes, streamingRes}` — the canonical
+ * implementations now live in lib/testing.js so operators get the same
+ * mocks the framework's own smoke suite uses. The underscore-prefixed
+ * names below are preserved so existing tests don't churn.
+ */
+
+var b = require("../../index.js");
+
+module.exports = {
+  _mockReq:       b.testing.mockReq,
+  _mockRes:       b.testing.mockRes,
+  _bodyReq:       b.testing.bodyReq,
+  _bodyRes:       b.testing.bodyRes,
+  _streamingRes:  b.testing.streamingRes,
+};

package/lib/vendor/blamejs/test/helpers/otel.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Fake @opentelemetry/api for tests that verify the framework routes
+ * through the real-OTel path instead of the pass-through.
+ *
+ * As of v0.2.38 this is a thin re-export of `b.testing.makeFakeOtelApi`
+ * — the canonical implementation lives in lib/testing.js so operators
+ * get the same fake the framework's own tracing/observability tests use.
+ */
+
+var b = require("../../index.js");
+
+module.exports = { makeFakeOtelApi: b.testing.makeFakeOtelApi };

package/lib/vendor/blamejs/test/helpers/services.js

@@ -0,0 +1,380 @@
+"use strict";
+/**
+ * Service config + readiness helpers for integration tests that
+ * connect to the docker-compose.test.yml stack.
+ *
+ * Both plain and TLS endpoints are exposed for every backend that
+ * supports TLS in the test stack. The framework targets PQC-first
+ * crypto on its own internal surfaces; these external service URLs
+ * are what tests use to exercise the framework's connect-over-TLS code
+ * paths against a real handshake (where applicable, with X25519MLKEM768
+ * hybrid groups requested in the cipher list).
+ *
+ * Public API:
+ *   var svcs = require("./services");
+ *
+ *   svcs.URLS.redis           — plain redis://...:6379
+ *   svcs.URLS.redisTls        — TLS rediss://...:6380
+ *   svcs.URLS.postgres        — postgres://... (sslmode picked client-side)
+ *   svcs.URLS.postgresTls     — same host:port + ?sslmode=require
+ *   svcs.URLS.mysql, .mysqlTls, .mongodb, .mongodbTls, .minio, .minioTls,
+ *   svcs.URLS.rabbitmq, .rabbitmqTls, .nats, .natsTls, .syslog, .syslogTls,
+ *   svcs.URLS.mailpit, .mailpitTls, .ntp, .haproxy, .caddy, .caddyTls,
+ *   svcs.URLS.mitmproxy, .mitmproxyWeb, .squid
+ *
+ *   await svcs.requireService("redis")
+ *     // { ok: true, url, host, port, scheme }
+ *     // { ok: false, reason }
+ *
+ *   await svcs.requireAll()
+ *     // throws when any service is unreachable
+ *
+ *   svcs.CA_CERT_PATH          // host-side path that mirrors the
+ *                              // certs volume's ca.crt; null until
+ *                              // svcs.exportCaCert() is called
+ *   await svcs.exportCaCert()  // copies /certs/ca.crt out of the
+ *                              // pki-init volume so node:tls clients
+ *                              // can pin against it
+ *
+ * Test-side usage pattern:
+ *   var svc = await svcs.requireService("redisTls");
+ *   if (!svc.ok) {
+ *     console.log("[skip] redis-tls: " + svc.reason);
+ *     return;
+ *   }
+ *   // svc.url is safe to pass to b.redisClient.create({ url: svc.url, ca: svcs.CA_CERT_PATH })
+ */
+var fs   = require("node:fs");
+var net  = require("node:net");
+var os   = require("node:os");
+var path = require("node:path");
+var tls  = require("node:tls");
+var dgram = require("node:dgram");
+
+// Every endpoint exposes IPv4 and IPv6 forms — the docker-compose.test.yml
+// dual-binds every host port onto both 127.0.0.1 and [::1]. Tests that
+// want to exercise both address families iterate { foo, fooV6 } pairs.
+var DEFAULTS = {
+  // ---- backends, plain (IPv4) ----
+  redis:        "redis://127.0.0.1:6379",
+  postgres:     "postgres://blamejs:blamejs_test@127.0.0.1:5432/blamejs_test",
+  mysql:        "mysql://blamejs:blamejs_test@127.0.0.1:3306/blamejs_test",
+  mongodb:      "mongodb://blamejs:blamejs_test@127.0.0.1:27017/?authSource=admin",
+  minio:        "http://blamejs:blamejs_test_password@127.0.0.1:9000",
+  rabbitmq:     "amqp://blamejs:blamejs_test@127.0.0.1:5672",
+  nats:         "nats://127.0.0.1:4222",
+  syslog:       "tcp://127.0.0.1:5514",
+  ntp:          "ntp://127.0.0.1:12300",
+  mailpit:      "smtp://127.0.0.1:1025",
+
+  // ---- backends, plain (IPv6) ----
+  redisV6:      "redis://[::1]:6379",
+  postgresV6:   "postgres://blamejs:blamejs_test@[::1]:5432/blamejs_test",
+  mysqlV6:      "mysql://blamejs:blamejs_test@[::1]:3306/blamejs_test",
+  mongodbV6:    "mongodb://blamejs:blamejs_test@[::1]:27017/?authSource=admin",
+  minioV6:      "http://blamejs:blamejs_test_password@[::1]:9000",
+  rabbitmqV6:   "amqp://blamejs:blamejs_test@[::1]:5672",
+  natsV6:       "nats://[::1]:4222",
+  syslogV6:     "tcp://[::1]:5514",
+  ntpV6:        "ntp://[::1]:12300",
+  mailpitV6:    "smtp://[::1]:1025",
+
+  // ---- backends, TLS (IPv4) ----
+  redisTls:     "rediss://127.0.0.1:6380",
+  postgresTls:  "postgres://blamejs:blamejs_test@127.0.0.1:5432/blamejs_test?sslmode=require",
+  mysqlTls:     "mysql://blamejs:blamejs_test@127.0.0.1:3306/blamejs_test?ssl=true",
+  mongodbTls:   "mongodb://blamejs:blamejs_test@127.0.0.1:27017/?authSource=admin&tls=true",
+  minioTls:     "https://blamejs:blamejs_test_password@127.0.0.1:9443",
+  rabbitmqTls:  "amqps://blamejs:blamejs_test@127.0.0.1:5671",
+  natsTls:      "tls://127.0.0.1:4222",
+  syslogTls:    "tcp+tls://127.0.0.1:6514",
+  // mailpit uses STARTTLS on the plain :1025 port — there is no native
+  // SMTPS listener. Use URLS.mailpit and let the framework's smtpTransport
+  // negotiate the TLS upgrade via EHLO/STARTTLS.
+
+  // ---- backends, TLS (IPv6) ----
+  redisTlsV6:    "rediss://[::1]:6380",
+  postgresTlsV6: "postgres://blamejs:blamejs_test@[::1]:5432/blamejs_test?sslmode=require",
+  mysqlTlsV6:    "mysql://blamejs:blamejs_test@[::1]:3306/blamejs_test?ssl=true",
+  mongodbTlsV6:  "mongodb://blamejs:blamejs_test@[::1]:27017/?authSource=admin&tls=true",
+  minioTlsV6:    "https://blamejs:blamejs_test_password@[::1]:9443",
+  rabbitmqTlsV6: "amqps://blamejs:blamejs_test@[::1]:5671",
+  natsTlsV6:     "tls://[::1]:4222",
+  syslogTlsV6:   "tcp+tls://[::1]:6514",
+
+  // ---- DNS resolver (plain + DoT + DoH) ----
+  dns:          "dns://127.0.0.1:1053",
+  dnsV6:        "dns://[::1]:1053",
+  dnsTls:       "dns+tls://127.0.0.1:1853",
+  dnsTlsV6:     "dns+tls://[::1]:1853",
+  dnsHttps:     "https://127.0.0.1:8053/dns-query",
+  dnsHttpsV6:   "https://[::1]:8053/dns-query",
+  dnsHealth:    "http://127.0.0.1:8054/health",
+  dnsHealthV6:  "http://[::1]:8054/health",
+
+  // ---- proxies + DPI (IPv4) ----
+  haproxy:      "https://127.0.0.1:8443",
+  haproxyStats: "http://127.0.0.1:8404/stats",
+  haproxyRedis: "tcp://127.0.0.1:6390",
+  caddy:        "http://127.0.0.1:8080",
+  caddyTls:     "https://127.0.0.1:8444",
+  mitmproxy:    "http://127.0.0.1:8090",
+  mitmproxyWeb: "http://127.0.0.1:8091",
+  squid:        "http://127.0.0.1:3128",
+
+  // ---- federated authentication (Keycloak — OIDC OP + SAML IdP) ----
+  keycloak:     "http://127.0.0.1:18080",
+  keycloakV6:   "http://[::1]:18080",
+
+  // ---- proxies + DPI (IPv6) ----
+  haproxyV6:      "https://[::1]:8443",
+  haproxyStatsV6: "http://[::1]:8404/stats",
+  haproxyRedisV6: "tcp://[::1]:6390",
+  caddyV6:        "http://[::1]:8080",
+  caddyTlsV6:     "https://[::1]:8444",
+  mitmproxyV6:    "http://[::1]:8090",
+  mitmproxyWebV6: "http://[::1]:8091",
+  squidV6:        "http://[::1]:3128",
+};
+
+function _envOverride(name) {
+  var key = "BLAMEJS_" + name.replace(/[A-Z]/g, function (c) { return "_" + c; }).toUpperCase() + "_URL";
+  var v = process.env[key];
+  return (typeof v === "string" && v.length > 0) ? v : null;
+}
+
+var URLS = {};
+Object.keys(DEFAULTS).forEach(function (name) {
+  URLS[name] = _envOverride(name) || DEFAULTS[name];
+});
+
+var CA_CERT_PATH = null;
+
+// Copy /certs/ca.crt out of the pki-init named volume into a temp file
+// the host can read (named volumes aren't directly host-accessible).
+// Idempotent — caches the path on the module exports.
+async function exportCaCert() {
+  if (CA_CERT_PATH && fs.existsSync(CA_CERT_PATH)) return CA_CERT_PATH;
+  var dest = path.join(os.tmpdir(), "blamejs-test-ca.crt");
+  // Use docker cp via child_process — but the framework forbids depending
+  // on shell-out from test helpers. Instead, copy via a one-shot exec
+  // through a known-running container. The pki-init container has
+  // already exited; pick any running container that has /certs mounted.
+  // Simpler: run `docker cp` via spawn since this helper is dev-only
+  // and dev tooling is allowed shell access.
+  var spawn = require("node:child_process").spawn;
+  return await new Promise(function (resolve, reject) {
+    var p = spawn("docker", ["cp", "blamejs-test-redis:/certs/ca.crt", dest], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    var err = "";
+    p.stderr.on("data", function (b) { err += b.toString(); });
+    p.on("close", function (code) {
+      if (code !== 0) {
+        return reject(new Error("docker cp ca.crt failed (exit " + code + "): " + err.trim()));
+      }
+      CA_CERT_PATH = dest;
+      module.exports.CA_CERT_PATH = dest;
+      resolve(dest);
+    });
+    p.on("error", function (e) { reject(e); });
+  });
+}
+
+// Parse a URL down to { scheme, host, port } for TCP probing without
+// hauling in node:url quirks for non-standard schemes. Handles bracketed
+// IPv6 hosts: scheme://[::1]:port/...
+function _hostPort(name, urlStr) {
+  // Bracketed IPv6 form first (must come before the bare-host fallback).
+  var m6 = /^([a-z][a-z0-9+.-]*):\/\/(?:[^@/]*@)?\[([0-9a-f:]+)\](?::(\d+))?/i.exec(urlStr);
+  if (m6) {
+    var scheme6 = m6[1].toLowerCase();
+    var port6 = m6[3] ? Number(m6[3]) : _defaultPort(scheme6);
+    if (!Number.isFinite(port6) || port6 <= 0) {
+      return { ok: false, reason: "services: no port for " + name + " in " + urlStr };
+    }
+    return { ok: true, scheme: scheme6, host: m6[2], port: port6, family: 6 };
+  }
+  var m = /^([a-z][a-z0-9+.-]*):\/\/(?:[^@/]*@)?([^/:?#[]+)(?::(\d+))?/i.exec(urlStr);
+  if (!m) {
+    return { ok: false, reason: "services: cannot parse URL for " + name + ": " + urlStr };
+  }
+  var scheme = m[1].toLowerCase();
+  var host = m[2];
+  var port = m[3] ? Number(m[3]) : _defaultPort(scheme);
+  if (!Number.isFinite(port) || port <= 0) {
+    return { ok: false, reason: "services: no port for " + name + " in " + urlStr };
+  }
+  return { ok: true, scheme: scheme, host: host, port: port, family: 4 };
+}
+
+function _defaultPort(scheme) {
+  switch (scheme) {
+    case "redis":     return 6379;
+    case "rediss":    return 6380;
+    case "postgres":  return 5432;
+    case "postgresql":return 5432;
+    case "mysql":     return 3306;
+    case "mongodb":   return 27017;
+    case "amqp":      return 5672;
+    case "amqps":     return 5671;
+    case "nats":      return 4222;
+    case "tls":       return 4222;
+    case "ntp":       return 123;
+    case "smtp":      return 25;
+    case "smtps":     return 465;
+    case "http":      return 80;
+    case "https":     return 443;
+    default:          return null;
+  }
+}
+
+function _probeTcp(host, port, timeoutMs) {
+  return new Promise(function (resolve) {
+    var family = host.indexOf(":") !== -1 ? 6 : 4;
+    var sock = net.connect({ host: host, port: port, family: family });
+    var done = false;
+    var timer = setTimeout(function () {
+      if (done) return;
+      done = true;
+      try { sock.destroy(); } catch (_e) {}
+      resolve({ ok: false, reason: "tcp connect timeout after " + timeoutMs + "ms" });
+    }, timeoutMs);
+    sock.once("connect", function () {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { sock.end(); } catch (_e) {}
+      resolve({ ok: true });
+    });
+    sock.once("error", function (err) {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      var msg = (err && err.code) || (err && err.message) || String(err);
+      resolve({ ok: false, reason: "tcp connect failed: " + msg });
+    });
+  });
+}
+
+function _probeTls(host, port, timeoutMs) {
+  return new Promise(function (resolve) {
+    var done = false;
+    var family = host.indexOf(":") !== -1 ? 6 : 4;
+    var sock = tls.connect({
+      host: host,
+      port: port,
+      family: family,
+      rejectUnauthorized: false,
+      // SNI is not legal for IP literals — drop servername for both
+      // IPv4 and IPv6 hosts.
+      servername: undefined,
+    });
+    var timer = setTimeout(function () {
+      if (done) return;
+      done = true;
+      try { sock.destroy(); } catch (_e) {}
+      resolve({ ok: false, reason: "tls handshake timeout after " + timeoutMs + "ms" });
+    }, timeoutMs);
+    sock.once("secureConnect", function () {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      var info = { protocol: sock.getProtocol(), cipher: (sock.getCipher() || {}).name };
+      try { sock.end(); } catch (_e) {}
+      resolve({ ok: true, info: info });
+    });
+    sock.once("error", function (err) {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      var msg = (err && err.code) || (err && err.message) || String(err);
+      resolve({ ok: false, reason: "tls handshake failed: " + msg });
+    });
+  });
+}
+
+function _probeUdp(host, port, timeoutMs) {
+  return new Promise(function (resolve) {
+    var sock = dgram.createSocket(host.indexOf(":") !== -1 ? "udp6" : "udp4");
+    var done = false;
+    var timer = setTimeout(function () {
+      if (done) return;
+      done = true;
+      try { sock.close(); } catch (_e) {}
+      // For UDP we can't tell "down" vs "no reply" from a single send.
+      // The probe succeeds when no error fires synchronously.
+      resolve({ ok: true, soft: true });
+    }, timeoutMs);
+    sock.once("error", function (err) {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { sock.close(); } catch (_e) {}
+      var msg = (err && err.code) || (err && err.message) || String(err);
+      resolve({ ok: false, reason: "udp probe error: " + msg });
+    });
+    sock.send(Buffer.alloc(1), 0, 1, port, host, function (err) {
+      if (err && !done) {
+        done = true;
+        clearTimeout(timer);
+        try { sock.close(); } catch (_e) {}
+        var msg = (err && err.code) || (err && err.message) || String(err);
+        resolve({ ok: false, reason: "udp send error: " + msg });
+      }
+    });
+  });
+}
+
+async function requireService(name, opts) {
+  opts = opts || {};
+  var timeoutMs = Number(opts.timeoutMs) || 2000;
+  var url = URLS[name];
+  if (!url) {
+    return { ok: false, reason: "services: unknown service '" + name +
+      "' (valid: " + Object.keys(URLS).join(", ") + ")" };
+  }
+  var hp = _hostPort(name, url);
+  if (!hp.ok) return hp;
+
+  var probe;
+  if (hp.scheme === "ntp") {
+    probe = await _probeUdp(hp.host, hp.port, timeoutMs);
+  } else if (hp.scheme === "rediss" || hp.scheme === "amqps" || hp.scheme === "smtps" ||
+             hp.scheme === "https"  || (hp.scheme === "tls" && hp.port === 4222)) {
+    probe = await _probeTls(hp.host, hp.port, timeoutMs);
+  } else {
+    probe = await _probeTcp(hp.host, hp.port, timeoutMs);
+  }
+  if (!probe.ok) {
+    return { ok: false, reason: name + " unreachable at " + hp.host + ":" + hp.port +
+      " (" + probe.reason + ")", url: url, host: hp.host, port: hp.port, scheme: hp.scheme };
+  }
+  return { ok: true, url: url, host: hp.host, port: hp.port, scheme: hp.scheme,
+           tlsInfo: probe.info || null };
+}
+
+async function requireAll(opts) {
+  var names = Object.keys(URLS);
+  var results = await Promise.all(names.map(function (n) {
+    return requireService(n, opts).then(function (r) { return { name: n, result: r }; });
+  }));
+  var failed = results.filter(function (r) { return !r.result.ok; });
+  if (failed.length === 0) return results.map(function (r) { return r.result; });
+  var msg = "services: " + failed.length + " of " + names.length + " unreachable: " +
+    failed.map(function (f) { return f.name + " (" + f.result.reason + ")"; }).join("; ") +
+    " — bring the stack up with `docker compose -f docker-compose.test.yml up -d --wait`";
+  var err = new Error(msg);
+  err.code = "BLAMEJS_SERVICES_UNREACHABLE";
+  err.failed = failed.map(function (f) { return f.name; });
+  throw err;
+}
+
+module.exports = {
+  URLS:           URLS,
+  DEFAULTS:       DEFAULTS,
+  CA_CERT_PATH:   CA_CERT_PATH,
+  exportCaCert:   exportCaCert,
+  requireService: requireService,
+  requireAll:     requireAll,
+};

package/lib/vendor/blamejs/test/helpers/wait.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * test/helpers/wait — poll-until-condition primitive for tests that
+ * observe asynchronous state (queue drain, audit flush, fs.watch
+ * delivery, mock-collector receive).
+ *
+ * Replace fixed-budget sleeps:
+ *
+ *     await new Promise(function (r) { setTimeout(r, 1500); });
+ *     assert(collector.requestCount >= 1);
+ *
+ * with poll-until-event:
+ *
+ *     await waitUntil(function () { return collector.requestCount >= 1; });
+ *     assert(collector.requestCount >= 1);
+ *
+ * Why this shape:
+ *
+ * - **Fast platforms exit in milliseconds.** A Linux runner that
+ *   delivers the event on the first event-loop turn doesn't pay the
+ *   full timeout budget — `waitUntil` returns as soon as the
+ *   predicate is truthy.
+ * - **Contended platforms get a generous budget.** macOS GitHub-
+ *   Actions runners under SMOKE_PARALLEL=64 routinely take 1-2s
+ *   to deliver an fs.watch event or flush a deferred-audit queue;
+ *   the default `timeoutMs: 5000` covers the worst case without
+ *   slowing down the non-contended path.
+ * - **One source of truth.** Pre-helper, every flaky-on-contention
+ *   test rolled its own `setTimeout(r, N)` with a hand-tuned N.
+ *   When CI surfaced the flake, the fix was to bump N — at best a
+ *   moving target, at worst it papered over the race. Centralizing
+ *   the polling loop here means future fixes update one timeout
+ *   ceiling instead of N inline budgets.
+ *
+ * The pattern that fixed v0.8.60's macOS watcher flake (priming
+ * wait + poll-until-event with 5s cap) is the canonical use case;
+ * every other "test passes alone, fails under SMOKE_PARALLEL=64"
+ * flake (log-stream-otlp / safe-async-loops / sandbox / rate-limit-
+ * cluster) is the same root cause: a fixed sleep too short for
+ * runner-contention reality.
+ */
+
+var DEFAULT_TIMEOUT_MS  = 5000;                                                                  // allow:raw-byte-literal — 5s contention-tolerant default
+var DEFAULT_INTERVAL_MS = 25;                                                                    // allow:raw-byte-literal — 40 polls/sec; doesn't burn CPU
+
+/**
+ * waitUntil(predicate, opts?) — poll a synchronous OR async predicate
+ * every `intervalMs` until it returns truthy OR `timeoutMs` elapses.
+ *
+ * @param predicate {Function} — sync (returns boolean) or async
+ *   (returns Promise<boolean>). Throws inside the predicate count as
+ *   "not ready yet" — the next tick re-checks. Catch + log inside
+ *   the predicate if you want different behavior.
+ * @param opts.timeoutMs  — total budget (default 5000ms)
+ * @param opts.intervalMs — poll cadence (default 25ms)
+ * @param opts.label      — string in the timeout error for grep'ability
+ * @returns {Promise<*>} the truthy value the predicate returned (so
+ *   tests can `var info = await waitUntil(() => collector.last)` and
+ *   chain assertions on the value).
+ * @throws Error("waitUntil timeout: <label>") on timeout.
+ */
+async function waitUntil(predicate, opts) {
+  opts = opts || {};
+  if (typeof predicate !== "function") {
+    throw new TypeError("waitUntil: predicate must be a function");
+  }
+  var timeoutMs = typeof opts.timeoutMs === "number" ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+  var intervalMs = typeof opts.intervalMs === "number" ? opts.intervalMs : DEFAULT_INTERVAL_MS;
+  var label = opts.label || "condition";
+  var deadline = Date.now() + timeoutMs;
+  var lastError = null;
+  while (Date.now() < deadline) {
+    var rv;
+    try { rv = await predicate(); lastError = null; }
+    catch (e) { lastError = e; rv = false; }
+    if (rv) return rv;
+    await new Promise(function (r) { setTimeout(r, intervalMs); });
+  }
+  // One last try right at the deadline — gives a final shot to a
+  // predicate whose latency-to-truthy is exactly timeoutMs.
+  try {
+    var finalRv = await predicate();
+    if (finalRv) return finalRv;
+  } catch (e) { lastError = e; }
+  var msg = "waitUntil timeout: " + label + " (after " + timeoutMs + "ms)";
+  if (lastError) msg += " — last predicate threw: " + ((lastError && lastError.message) || String(lastError));
+  throw new Error(msg);
+}
+
+/**
+ * waitUntilEqual(getter, expected, opts?) — convenience wrapper for
+ * the most common case ("wait until this value equals that value").
+ * Compares with === for primitives, JSON.stringify for objects.
+ */
+async function waitUntilEqual(getter, expected, opts) {
+  opts = opts || {};
+  return waitUntil(function () {
+    var v = getter();
+    if (v === expected) return v;
+    if (typeof v === "object" && typeof expected === "object" &&
+        JSON.stringify(v) === JSON.stringify(expected)) return v;
+    return false;
+  }, Object.assign({ label: opts.label || ("value === " + JSON.stringify(expected)) }, opts));
+}
+
+/**
+ * withTestTimeout(label, fn, opts?) — wrap an async test body with a
+ * wall-clock ceiling. Tests doing real-time work (setTimeout-based
+ * rate limiting, stream pipelines, child-process exits, fs.watch
+ * delivery on contended runners) get a hard per-test deadline so a
+ * future runner flake surfaces as `test timed out: <label>` in
+ * seconds instead of burning the full GitHub Actions job timeout.
+ *
+ * Default budget is 10s — generous enough to absorb SMOKE_PARALLEL=64
+ * contention on a macOS runner while keeping a hang's blast radius
+ * to a single test rather than a 6-hour stuck job. Tests that need a
+ * longer window pass `{ timeoutMs }` explicitly with a written reason
+ * in the surrounding comment.
+ *
+ * @param label    {string}   — surfaced in the timeout message
+ * @param fn       {Function} — async function (the test body)
+ * @param opts     {object?}  — `timeoutMs` (default 10000)
+ * @returns        {Promise}    resolves to fn's return value
+ *
+ * @example
+ *   await withTestTimeout("rate enforcement", async function () {
+ *     var t = b.streamThrottle.create({ bytesPerSec: 1024 });
+ *     await pipeBuf(t.transform(), 4096, 1024);
+ *   });
+ */
+var DEFAULT_TEST_TIMEOUT_MS = 10000;                                                             // allow:raw-byte-literal // allow:raw-time-literal — 10s per-test cap
+
+function withTestTimeout(label, fn, opts) {
+  opts = opts || {};
+  var timeoutMs = typeof opts.timeoutMs === "number" ? opts.timeoutMs : DEFAULT_TEST_TIMEOUT_MS;
+  if (typeof label !== "string" || label.length === 0) {
+    throw new Error("withTestTimeout: label (string) required");
+  }
+  if (typeof fn !== "function") {
+    throw new Error("withTestTimeout: fn (function) required");
+  }
+  return new Promise(function (resolve, reject) {
+    var settled = false;
+    var timer = setTimeout(function () {
+      if (settled) return;
+      settled = true;
+      reject(new Error("test timed out: " + label + " (after " + timeoutMs + "ms)"));
+    }, timeoutMs);
+    Promise.resolve().then(fn).then(function (v) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(v);
+    }, function (e) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(e);
+    });
+  });
+}
+
+/**
+ * passiveObserve(ms, label) — let `ms` real-time milliseconds pass.
+ *
+ * Distinct from `waitUntil`: the goal is NOT to wait for a condition
+ * to become true, but to let real time elapse so the test can verify
+ * the ABSENCE of an event over a window (e.g. "ping/pong machinery
+ * keeps the connection alive — no pong-timeout error fires across
+ * 800ms of ticks"). Such observations cannot be expressed as a
+ * predicate because the assertion is precisely that no observable
+ * state-change occurred during the budget.
+ *
+ * Use sparingly. If there IS an observable predicate for the thing
+ * you're waiting on (a counter incremented, a state transition, a
+ * file appearing), use `waitUntil` instead — passive-observation is
+ * the wrong tool for those cases and slows the test on fast platforms.
+ *
+ * The `label` is required so a grep through a flake log immediately
+ * identifies which observation budget was consumed.
+ *
+ * @param ms    {number} — real-time milliseconds to elapse
+ * @param label {string} — surfaces in audit logs / future diagnostics
+ * @returns     {Promise}  resolves after `ms`
+ *
+ * @example
+ *   client.ping(Buffer.from("ping-data"));
+ *   await helpers.passiveObserve(800, "ws ping/pong: no pong-timeout fired");
+ *   check("ping/pong keeps connection alive", c3Err === null);
+ */
+function passiveObserve(ms, label) {
+  if (typeof ms !== "number" || !isFinite(ms) || ms <= 0) {
+    throw new TypeError("passiveObserve: ms must be a positive finite number");
+  }
+  if (typeof label !== "string" || label.length === 0) {
+    throw new TypeError("passiveObserve: label (string) required — grep'able diagnostic");
+  }
+  return new Promise(function (r) { setTimeout(r, ms); });
+}
+
+module.exports = {
+  waitUntil:       waitUntil,
+  waitUntilEqual:  waitUntilEqual,
+  withTestTimeout: withTestTimeout,
+  passiveObserve:  passiveObserve,
+};