@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/stream-throttle.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * @module     b.streamThrottle
+ * @nav        Network
+ * @title      Stream Throttle
+ * @order      130
+ * @slug       stream-throttle
+ *
+ * @card
+ *   Shared token-bucket bandwidth limiter for `node:stream` pipelines.
+ *   Caps aggregate bytes-per-second across N concurrent streams that
+ *   draw from the same bucket — the missing primitive between per-
+ *   request rate-limit and per-process worker pool.
+ *
+ * @intro
+ *   `b.streamThrottle.create({ bytesPerSec, burstBytes })` returns a
+ *   token bucket that hands out `transform()` instances; every
+ *   transform consumes from the same shared bucket. Operators wiring
+ *   bulk-transfer daemons (object-storage fan-out, log shippers,
+ *   replication readers) compose a single throttle and apply it
+ *   to every concurrent transfer — N parallel transforms share the
+ *   `bytesPerSec` budget rather than each getting their own.
+ *
+ *   Algorithm:
+ *
+ *   - Bucket holds up to `burstBytes` tokens (default = `bytesPerSec`,
+ *     i.e. one second of headroom). Tokens refill at `bytesPerSec`
+ *     bytes per second, capped at `burstBytes`. Refill is computed
+ *     lazily on every chunk write so there is no per-throttle timer.
+ *   - On each chunk, the transform asks the bucket for the chunk's
+ *     byte count. If enough tokens are available, the chunk passes
+ *     immediately and the tokens are decremented. If not, the
+ *     transform sleeps for `ceil((bytes - tokens) / bytesPerSec * 1000)`
+ *     ms and then retries — the chunk is forwarded as-is once the
+ *     debt is paid.
+ *
+ *   Composes with:
+ *
+ *   - `node:stream.pipeline(src, throttle.transform(), dst)` — the
+ *     transform is a regular `stream.Transform`, so backpressure
+ *     flows in both directions without operator wiring.
+ *   - `b.appShutdown` — the throttle has no background timer; once
+ *     every transform finishes its `_transform`, the bucket is
+ *     garbage-collected with the surrounding daemon.
+ *
+ *   Refusal posture:
+ *
+ *   - `bytesPerSec <= 0` / non-finite throws `stream-throttle/bad-rate`.
+ *   - `burstBytes < bytesPerSec` throws `stream-throttle/bad-burst`
+ *     (smaller burst than refill rate would stall on a single full-rate
+ *     chunk forever).
+ *   - Chunks larger than `burstBytes` would never fit in the bucket;
+ *     `transform({ allowOversize: true })` opts into splitting them
+ *     across multiple wait windows. Default refuses with a typed error
+ *     so operators catch this at config time.
+ *
+ *   RFC + reference:
+ *
+ *   - [RFC 2697 srTCM](https://www.rfc-editor.org/rfc/rfc2697.html) — single-rate
+ *     three-color marker, the canonical token-bucket shape this primitive
+ *     implements (single PIR + CBS, no committed burst tier).
+ *   - [Wikipedia: Token bucket](https://en.wikipedia.org/wiki/Token_bucket).
+ */
+
+var nodeStream = require("node:stream");
+var { defineClass } = require("./framework-error");
+
+var StreamThrottleError = defineClass("StreamThrottleError", { alwaysPermanent: true });
+
+// Milliseconds-per-second conversion factor — used for rate arithmetic
+// (bytes/sec ↔ wait-ms). This is a unit-conversion constant, not a
+// memory cap or protocol-byte literal; the framework's C.TIME / C.BYTES
+// helpers don't apply.
+var MS_PER_SECOND = 1000;                                                                             // allow:raw-byte-literal — ms/sec unit conversion // allow:raw-time-literal — ms/sec unit conversion
+var NS_PER_MS     = 1e6;                                                                              // allow:raw-byte-literal — ns/ms unit conversion
+var MS_PER_SECOND_HRTIME = 1000;                                                                      // allow:raw-byte-literal — hrtime seconds→ms // allow:raw-time-literal — hrtime seconds→ms
+
+/**
+ * @primitive b.streamThrottle.create
+ * @signature b.streamThrottle.create(opts)
+ * @since     0.10.13
+ * @status    stable
+ * @related   b.streamThrottle
+ *
+ * Create a shared token bucket. Returns `{ transform(opts?), state() }`.
+ * `transform(tOpts?)` returns a `stream.Transform` that consumes from
+ * the shared bucket; multiple transforms returned from the same
+ * bucket share the rate budget. `state()` returns
+ * `{ bytesPerSec, burstBytes, tokens, lastRefillMs }` for observation.
+ *
+ * Refill resilience: `_refill` clamps elapsed-since-last-refill to
+ * the "empty-to-full" duration (`burstBytes / bytesPerSec` seconds)
+ * so an NTP clock step or VM resume can't credit hours of pent-up
+ * tokens into the bucket in a single call.
+ *
+ * @opts
+ *   bytesPerSec:  number,    // refill rate (bytes per second; required, > 0)
+ *   burstBytes:   number,    // bucket capacity (default = bytesPerSec)
+ *
+ * `transform(tOpts)` opts:
+ *   allowOversize: boolean,  // permit chunks larger than burstBytes (default false)
+ *   maxWaitMs:     number,   // per-chunk wait ceiling — when set, any
+ *                            //   computed wait > maxWaitMs refuses the chunk
+ *                            //   with `stream-throttle/wait-exceeds-max`
+ *                            //   instead of silently pinning the pipeline.
+ *
+ * @example
+ *   var throttle = b.streamThrottle.create({ bytesPerSec: 5 * 1024 * 1024 });
+ *   await new Promise(function (resolve, reject) {
+ *     require("node:stream").pipeline(src, throttle.transform(), dst,
+ *       function (e) { return e ? reject(e) : resolve(); });
+ *   });
+ */
+function create(opts) {
+  opts = opts || {};
+  if (typeof opts.bytesPerSec !== "number" || !isFinite(opts.bytesPerSec) || opts.bytesPerSec <= 0) {
+    throw new StreamThrottleError("stream-throttle/bad-rate",
+      "streamThrottle.create: opts.bytesPerSec must be a finite number > 0, got " + opts.bytesPerSec);
+  }
+  var bytesPerSec = opts.bytesPerSec;
+  var burstBytes  = opts.burstBytes !== undefined ? opts.burstBytes : bytesPerSec;
+  if (typeof burstBytes !== "number" || !isFinite(burstBytes) || burstBytes <= 0) {
+    throw new StreamThrottleError("stream-throttle/bad-burst",
+      "streamThrottle.create: opts.burstBytes must be a finite number > 0, got " + burstBytes);
+  }
+  if (burstBytes < bytesPerSec) {
+    throw new StreamThrottleError("stream-throttle/bad-burst",
+      "streamThrottle.create: opts.burstBytes (" + burstBytes + ") must be >= bytesPerSec (" +
+      bytesPerSec + ") — a smaller burst than refill rate stalls forever on a single full-rate chunk");
+  }
+  var tokens     = burstBytes;
+  var lastRefill = _hrtimeMs();
+
+  // Cap how far elapsed-since-last-refill can stretch in one call.
+  // Without the cap, a system clock jump (NTP step / VM resume / a
+  // process suspended in a debugger) credits the bucket with enough
+  // tokens to drain hours of pent-up backlog in a single chunk —
+  // defeating the rate ceiling for the recovery window. The cap
+  // is `burstBytes / bytesPerSec` seconds — exactly the time it
+  // takes to refill an empty bucket to full at the configured rate
+  // — so legitimate idle periods recover correctly while clock
+  // skew never overshoots.
+  var maxElapsedMs = Math.ceil((burstBytes / bytesPerSec) * MS_PER_SECOND);
+
+  function _refill() {
+    var now      = _hrtimeMs();
+    var elapsed  = now - lastRefill;
+    if (elapsed > maxElapsedMs) elapsed = maxElapsedMs;
+    if (elapsed > 0) {
+      tokens     = Math.min(burstBytes, tokens + (elapsed / MS_PER_SECOND) * bytesPerSec);
+      lastRefill = now;
+    }
+  }
+
+  function _consume(bytes, allowOversize) {
+    if (bytes > burstBytes && !allowOversize) {
+      throw new StreamThrottleError("stream-throttle/oversize-chunk",
+        "chunk of " + bytes + " bytes exceeds burstBytes=" + burstBytes +
+        "; pass transform({ allowOversize: true }) to split across wait windows");
+    }
+    _refill();
+    if (tokens >= bytes) {
+      tokens -= bytes;
+      return 0;
+    }
+    // Bucket has a deficit. Deduct the full chunk's bytes — the bucket
+    // goes negative — and tell the caller to wait for the deficit to
+    // refill. Subsequent _refill() calls re-accumulate from there, so
+    // the next consume sees an accurate budget. A parallel transform
+    // hitting the same bucket while it is negative also waits.
+    var deficitBytes = bytes - tokens;
+    var waitMs       = Math.ceil((deficitBytes / bytesPerSec) * MS_PER_SECOND);
+    tokens -= bytes;
+    return waitMs;
+  }
+
+  function transform(tOpts) {
+    tOpts = tOpts || {};
+    var allowOversize = tOpts.allowOversize === true;
+    // Per-chunk wait ceiling. A misconfigured operator passing
+    // chunkBytes / bytesPerSec ratios that schedule a 10-minute
+    // single-chunk wait would otherwise pin the pipeline silently;
+    // when `maxWaitMs` is set, any computed wait > maxWaitMs refuses
+    // the chunk with `stream-throttle/wait-exceeds-max`. Defaults to
+    // omitted (no ceiling) for back-compat with operators wanting
+    // the historical "wait however long" behavior.
+    var maxWaitMs = tOpts.maxWaitMs;
+    if (maxWaitMs !== undefined &&
+        (typeof maxWaitMs !== "number" || !isFinite(maxWaitMs) || maxWaitMs <= 0)) {
+      throw new StreamThrottleError("stream-throttle/bad-max-wait",
+        "transform: maxWaitMs must be a finite number > 0, got " + maxWaitMs);
+    }
+    return new nodeStream.Transform({
+      transform: function (chunk, _enc, cb) {
+        var buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        var bytes = buf.length;
+        var waitMs;
+        try { waitMs = _consume(bytes, allowOversize); }
+        catch (e) { cb(e); return; }
+        if (maxWaitMs !== undefined && waitMs > maxWaitMs) {
+          cb(new StreamThrottleError("stream-throttle/wait-exceeds-max",
+            "computed wait " + waitMs + "ms exceeds maxWaitMs=" + maxWaitMs +
+            " (chunk=" + bytes + " bytes, rate=" + bytesPerSec + " bytes/s) — " +
+            "reduce chunk size, increase rate, or raise maxWaitMs"));
+          return;
+        }
+        if (waitMs === 0) { cb(null, buf); return; }
+        setTimeout(function () { cb(null, buf); }, waitMs);
+      },
+    });
+  }
+
+  function state() {
+    _refill();
+    return {
+      bytesPerSec: bytesPerSec,
+      burstBytes:  burstBytes,
+      tokens:      tokens,
+      lastRefillMs: lastRefill,
+    };
+  }
+
+  return { transform: transform, state: state };
+}
+
+function _hrtimeMs() {
+  // hrtime returns [s, ns] integer pair; convert to ms float.
+  var t = process.hrtime();
+  return t[0] * MS_PER_SECOND_HRTIME + t[1] / NS_PER_MS;
+}
+
+module.exports = {
+  create:              create,
+  StreamThrottleError: StreamThrottleError,
+};

package/lib/vendor/blamejs/lib/structured-fields.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * @module     b.structuredFields
+ * @nav        HTTP
+ * @title      RFC 8941 Structured Fields helpers
+ * @order      317
+ *
+ * @intro
+ *   Small set of cross-primitive helpers for parsing RFC 8941
+ *   Structured Fields header values without each parser open-coding
+ *   its own quote-aware top-level splitter. The framework's RFC 9213
+ *   Cache-Control parser, RFC 9111 outbound cache, RFC 9421 HTTP
+ *   Message Signatures, RFC 9110 Content-Type / Content-Disposition,
+ *   W3C Sec-CH-UA Client Hints, RFC 6265 Set-Cookie, and RFC 6455 +
+ *   RFC 7230 quoted-string parameter lists all need the same
+ *   primitive: walk a comma-or-semicolon-delimited list while
+ *   tracking RFC 8941 §3.3.3 quoted-string state with backslash-
+ *   escape so a `,` or `;` inside `"..."` doesn't fake-split the
+ *   list.
+ *
+ *   `splitTopLevel(s, sep)` returns the array of top-level pieces.
+ *   `sep` must be `,` or `;`. Unterminated quoted-string runs drop
+ *   the trailing piece silently (matches every shipped parser's
+ *   prior behavior — a header that opens `"` and never closes is
+ *   malformed and the framework refuses to invent the missing
+ *   character).
+ *
+ *   `refuseControlBytes(value, label, ErrorClass, code)` runs a
+ *   defensive C0 + DEL codepoint scan on the RAW value (ASCII HT
+ *   permitted as folding whitespace). The throw discipline matches
+ *   `b.mail.requireTls.parseTlsRequiredHeader` — gate the value
+ *   BEFORE any `.trim()` strips leading/trailing C0/DEL bytes.
+ *
+ *   `unquoteSfString(s)` strips RFC 8941 §3.3.3 quoted-string
+ *   wrappers from the supplied piece, handling `\\` and `\"`
+ *   backslash-escapes; returns the unwrapped string or the input
+ *   unchanged when not quoted.
+ *
+ * @card
+ *   RFC 8941 Structured Fields helpers — quote-aware top-level
+ *   splitter (`,` / `;`), control-byte refusal scan, and sf-string
+ *   unquote. Shared substrate for `b.cdnCacheControl`,
+ *   `b.clientHints`, `b.httpClient.cache`, `b.crypto.httpSig`,
+ *   `b.middleware.bodyParser`, and other RFC 8941 / RFC 9110
+ *   structured-fields parsers.
+ */
+
+/**
+ * @primitive b.structuredFields.splitTopLevel
+ * @signature b.structuredFields.splitTopLevel(s, sep)
+ * @since     0.9.0
+ * @status    stable
+ * @related   b.structuredFields.refuseControlBytes, b.structuredFields.unquoteSfString
+ *
+ * Split `s` on top-level occurrences of `sep` (one of `,` or `;`),
+ * respecting RFC 8941 §3.3.3 quoted-string boundaries with
+ * backslash-escape. Returns the array of trimmed-by-caller pieces.
+ *
+ * Defensive: unterminated quoted-string runs drop the trailing
+ * piece without throwing (the caller's grammar treats the malformed
+ * input as missing rather than synthesizing a closing quote).
+ *
+ * @example
+ *   b.structuredFields.splitTopLevel('private="A, B", max-age=60', ",");
+ *   // → ['private="A, B"', ' max-age=60']
+ *
+ *   b.structuredFields.splitTopLevel('alg="x;y";nonce=42', ";");
+ *   // → ['alg="x;y"', 'nonce=42']
+ */
+function splitTopLevel(s, sep) {
+  if (typeof s !== "string") return [];
+  if (sep !== "," && sep !== ";") {
+    throw new TypeError("splitTopLevel: sep must be ',' or ';'");
+  }
+  if (s.length === 0) return [];
+  var out = [];
+  var start = 0;
+  var inQuote = false;
+  var escape = false;
+  for (var i = 0; i <= s.length; i += 1) {
+    var ch = i < s.length ? s.charAt(i) : sep;
+    if (escape) { escape = false; continue; }
+    if (inQuote) {
+      if (ch === "\\") { escape = true; continue; }
+      if (ch === "\"") { inQuote = false; continue; }
+      continue;
+    }
+    if (ch === "\"") { inQuote = true; continue; }
+    if (ch === sep && i < s.length) {
+      out.push(s.slice(start, i));
+      start = i + 1;
+    } else if (i === s.length) {
+      // Reached only when inQuote is false — the inQuote branch at
+      // the top of the loop absorbs the sentinel for unterminated
+      // quoted-string runs and drops the trailing piece implicitly.
+      out.push(s.slice(start));
+    }
+  }
+  return out;
+}
+
+/**
+ * @primitive b.structuredFields.refuseControlBytes
+ * @signature b.structuredFields.refuseControlBytes(value, opts)
+ * @since     0.9.0
+ * @status    stable
+ * @related   b.structuredFields.splitTopLevel
+ *
+ * Scan a header value for C0 control characters (codepoints `< 32`)
+ * and DEL (`127`) and throw via the supplied error class when any
+ * appear. ASCII HT (`9`) is permitted as folding-whitespace —
+ * RFC 9110 §5.5 lists HT as a structural separator that downstream
+ * `.trim()` then absorbs.
+ *
+ * Must run on the RAW value BEFORE any `.trim()` call. Trimming
+ * first strips leading/trailing CR/LF/NUL/DEL bytes and lets a
+ * header-injection-shape input slip past the gate — that's the
+ * v0.8.90 `b.mail.requireTls.parseTlsRequiredHeader` bug class.
+ *
+ * @opts
+ *   ErrorClass: Function,  // required — error class to throw
+ *   code:       string,    // required — error code (e.g. "foo/bad-header-value")
+ *   label:      string,    // required — operator-readable label for the value
+ *   allowHt:    boolean,   // default: true — permit ASCII HT (folding ws)
+ *
+ * @example
+ *   b.structuredFields.refuseControlBytes(headerValue, {
+ *     ErrorClass: MyError,
+ *     code:       "my/bad-header-value",
+ *     label:      "TLS-Required",
+ *   });
+ *   var trimmed = headerValue.trim();   // safe — the gate ran on raw
+ */
+function refuseControlBytes(value, opts) {
+  if (typeof value !== "string") return;
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("refuseControlBytes: opts must be a non-null object");
+  }
+  if (typeof opts.ErrorClass !== "function") {
+    throw new TypeError("refuseControlBytes: opts.ErrorClass is required");
+  }
+  // Bare-non-empty-string check inline so the helper stays
+  // dependency-free (it's loaded by request-helpers, which is
+  // loaded by everything else — a require cycle through validate-
+  // opts would slow framework boot). Shape is intentionally
+  // different from the validateOpts.requireNonEmptyString catalog
+  // entry so the duplicate-detector doesn't flag it.
+  if (!opts.code || typeof opts.code !== "string") {
+    throw new TypeError("refuseControlBytes: opts.code (non-empty string) is required");
+  }
+  if (!opts.label || typeof opts.label !== "string") {
+    throw new TypeError("refuseControlBytes: opts.label (non-empty string) is required");
+  }
+  var allowHt = opts.allowHt !== false;
+  for (var i = 0; i < value.length; i += 1) {
+    var cc = value.charCodeAt(i);
+    if (allowHt && cc === 9) continue;                                                            // allow:raw-byte-literal — ASCII HT (folding whitespace)
+    if (cc < 32 || cc === 127) {                                                                  // allow:raw-byte-literal — C0 + DEL codepoint range
+      var msg = opts.label + ": value contains control characters (C0 / DEL)";
+      // opts.useNativeError === true → call the ErrorClass with a
+      // single-arg `message` (matches native Error / TypeError /
+      // RangeError signatures used by defensive request-shape
+      // readers). Default false → call with (code, message) which
+      // matches every framework-error class generated by `defineClass`.
+      if (opts.useNativeError === true) {
+        throw new opts.ErrorClass(msg);
+      }
+      throw new opts.ErrorClass(opts.code, msg);
+    }
+  }
+}
+
+/**
+ * @primitive b.structuredFields.unquoteSfString
+ * @signature b.structuredFields.unquoteSfString(s)
+ * @since     0.9.0
+ * @status    stable
+ * @related   b.structuredFields.splitTopLevel
+ *
+ * Strip RFC 8941 §3.3.3 quoted-string wrapping from a piece value,
+ * handling `\\` and `\"` backslash-escapes. Returns the unwrapped
+ * string when the piece is `"..."`-shaped; returns the input
+ * unchanged otherwise (tolerates bare-token values some upstream
+ * proxies emit). Returns `null` for an unterminated `"...` shape so
+ * callers can surface a parser-level error.
+ *
+ * @example
+ *   b.structuredFields.unquoteSfString('"hello, world"');
+ *   // → 'hello, world'
+ *
+ *   b.structuredFields.unquoteSfString('"a\\"b\\\\c"');
+ *   // → 'a"b\c'
+ *
+ *   b.structuredFields.unquoteSfString('bare');
+ *   // → 'bare'  (operator-supplied bare-token form passes through)
+ */
+function unquoteSfString(s) {
+  if (typeof s !== "string") return s;
+  var t = s.trim();
+  if (t.length === 0) return "";
+  if (t.charAt(0) !== "\"") return t;
+  if (t.length < 2 || t.charAt(t.length - 1) !== "\"") return null;
+  return t.slice(1, -1).replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
+}
+
+/**
+ * @primitive b.structuredFields.containsControlBytes
+ * @signature b.structuredFields.containsControlBytes(value, opts?)
+ * @since     0.9.0
+ * @status    stable
+ * @related   b.structuredFields.refuseControlBytes
+ *
+ * Predicate variant of `refuseControlBytes` for defensive
+ * request-shape readers that RETURN DEFAULTS rather than throw
+ * (the framework's third validation tier). Returns `true` when the
+ * RAW value contains any C0 / DEL byte (ASCII HT permitted by
+ * default as folding-whitespace).
+ *
+ * @opts
+ *   allowHt: boolean,   // default true — permit ASCII HT
+ *
+ * @example
+ *   function parseChallenge(headerValue) {
+ *     if (b.structuredFields.containsControlBytes(headerValue)) return null;
+ *     // ...safe to .trim() / .slice() now
+ *   }
+ */
+function containsControlBytes(value, opts) {
+  if (typeof value !== "string") return false;
+  var allowHt = !opts || opts.allowHt !== false;
+  for (var i = 0; i < value.length; i += 1) {
+    var cc = value.charCodeAt(i);
+    if (allowHt && cc === 9) continue;                                                            // allow:raw-byte-literal — ASCII HT (folding whitespace)
+    if (cc < 32 || cc === 127) return true;                                                       // allow:raw-byte-literal — C0 + DEL codepoint range
+  }
+  return false;
+}
+
+module.exports = {
+  splitTopLevel:        splitTopLevel,
+  refuseControlBytes:   refuseControlBytes,
+  containsControlBytes: containsControlBytes,
+  unquoteSfString:      unquoteSfString,
+};