kinetex 1.3.0 → 1.5.0

package/dist/cjs/interceptors.js

@@ -28,6 +28,9 @@
  *  - No dependencies, no runtime globals beyond Promise/Map/Set
  */
 import { getAuthFingerprint } from "./cache.js";
+import { perfNow, sleep, redactHeaders as redactHeaderValues } from "./utils.js";
+import { KinetexError } from "./types.js";
+import { parseHTTPDate } from "./headers.js";
 // ============================================================================
 // §3  INTERCEPTOR MANAGER
 // ============================================================================
@@ -357,7 +360,9 @@ export function createRetryInterceptor(config = {}) {
         const exp = cfg.baseDelayMs * Math.pow(2, attempt - 1);
         const capped = Math.min(exp, cfg.maxDelayMs);
         const jitterMs = capped * cfg.jitter * Math.random();
-        return Math.floor(capped + jitterMs);
+        // `maxDelayMs` is documented as a hard maximum, so it has to be applied
+        // after jitter too — capping first let jitter push the delay past it.
+        return Math.min(Math.floor(capped + jitterMs), cfg.maxDelayMs);
     }
     function shouldRetryCtx(ctx) {
         if (ctx.attempt > cfg.maxRetries)
@@ -378,8 +383,12 @@ export function createRetryInterceptor(config = {}) {
             return null;
         if (/^\d+$/.test(ra.trim()))
             return parseInt(ra, 10) * 1000;
-        const ms = Date.parse(ra);
-        if (!isNaN(ms))
+        // Only the three HTTP-date formats count. Raw `Date.parse` is lenient to a
+        // fault here: it happily accepts "1.5", "-5" and "+5" as ancient dates, so a
+        // malformed `Retry-After` resolved to ~0ms and silently cancelled the
+        // back-off instead of falling through to the exponential delay.
+        const ms = parseHTTPDate(ra);
+        if (ms !== null)
             return Math.max(0, ms - Date.now());
         return null;
     }
@@ -599,13 +608,9 @@ let _reqIdSeq = 0;
 export function createLoggingInterceptor(config = {}) {
     const cfg = { ...LOG_DEFAULTS, ...config };
     const redactSet = new Set(cfg.redactHeaders.map((h) => h.toLowerCase()));
-    function redactHeaders(headers) {
-        const out = {};
-        for (const [k, v] of Object.entries(headers)) {
-            out[k] = redactSet.has(k.toLowerCase()) ? "**REDACTED**" : v;
-        }
-        return out;
-    }
+    // The mask is "**REDACTED**" rather than the logger's "***" — that string is
+    // observable in this interceptor's own log output, so it is preserved here.
+    const redactHeaders = (headers) => redactHeaderValues(headers, redactSet, "**REDACTED**");
     function makeEntry(type, ctx) {
         const requestId = ctx.store.get(REQUEST_ID_KEY) ?? "unknown";
         return {
@@ -618,6 +623,7 @@ export function createLoggingInterceptor(config = {}) {
             durationMs: type !== "request" ? now() - ctx.startedAt : null,
             attempt: ctx.attempt,
             error: ctx.error instanceof Error ? ctx.error.message : null,
+            headers: redactHeaders(ctx.request.headers ?? {}),
         };
     }
     const requestInterceptor = (ctx) => {
@@ -637,7 +643,6 @@ export function createLoggingInterceptor(config = {}) {
             return;
         cfg.logger(makeEntry("error", ctx));
     };
-    void redactHeaders; // used externally; suppress unused warning
     return { requestInterceptor, responseInterceptor, errorInterceptor };
 }
 const CACHE_DEFAULTS = {
@@ -863,6 +868,19 @@ const RATE_LIMIT_DEFAULTS = {
  */
 export function createRateLimitInterceptor(config = {}) {
     const cfg = { ...RATE_LIMIT_DEFAULTS, ...config };
+    // A non-positive `limit` (or a non-positive `windowMs`) has no valid token-bucket
+    // state: the refill interval `windowMs / limit` becomes `Infinity` or `NaN`,
+    // which `setInterval` turns into a ~1ms busy-poll, and every request either
+    // throws or queues forever. Reject it up front rather than degrading silently.
+    if (!Number.isFinite(cfg.limit) || cfg.limit < 1) {
+        throw new RangeError(`rateLimit.limit must be a finite number >= 1, got ${cfg.limit}`);
+    }
+    if (!Number.isFinite(cfg.windowMs) || cfg.windowMs < 1) {
+        throw new RangeError(`rateLimit.windowMs must be a finite number >= 1, got ${cfg.windowMs}`);
+    }
+    if (!Number.isFinite(cfg.maxQueue) || cfg.maxQueue < 0) {
+        throw new RangeError(`rateLimit.maxQueue must be a finite number >= 0, got ${cfg.maxQueue}`);
+    }
     let tokens = cfg.limit;
     let lastRefill = now();
     const pending = [];
@@ -919,6 +937,191 @@ export class RateLimitError extends Error {
         this.name = "RateLimitError";
     }
 }
+/** Defaults for {@link ConcurrencyLimitConfig}. */
+export const CONCURRENCY_DEFAULTS = {
+    maxConcurrent: 10,
+    queue: true,
+    maxQueue: 100,
+};
+/**
+ * Raised when the concurrency limit is reached and the request cannot be
+ * queued (or queueing is disabled).
+ *
+ * Distinct from {@link RateLimitError}: a rate limit bounds requests per unit
+ * of _time_, this bounds requests in flight.
+ */
+export class ConcurrencyLimitError extends Error {
+    /** Machine-readable error code identifying this as a concurrency error */
+    code = "ECONCURRENCY";
+    constructor(message) {
+        super(message);
+        this.name = "ConcurrencyLimitError";
+    }
+}
+/**
+ * Detach a waiter's abort listener.
+ *
+ * Nulling `onAbort` alone is not enough: a caller-supplied signal usually
+ * outlives a single request, so the `{ once: true }` listener would stay
+ * attached forever and accumulate one closure per queued request.
+ */
+function detachAbortListener(waiter) {
+    if (waiter.onAbort && waiter.signal) {
+        waiter.signal.removeEventListener("abort", waiter.onAbort);
+    }
+    waiter.onAbort = null;
+    waiter.signal = null;
+}
+/**
+ * A counting semaphore bounding how many requests may be in flight at once.
+ *
+ * The rate limiter is a token bucket: it releases a token at _dispatch_, so
+ * `limit: 100` per minute still permits 100 simultaneous sockets. This bounds
+ * concurrency instead — a permit is held for the whole request (including its
+ * retries) and returned only when it settles.
+ *
+ * Permits are handed directly to the next waiter on release, so releasing
+ * never transiently overshoots {@link ConcurrencyLimitConfig.maxConcurrent}.
+ *
+ * @example
+ * ```ts
+ * const limiter = new ConcurrencyLimiter({ maxConcurrent: 4 });
+ * await limiter.acquire();
+ * try {
+ *   await doWork();
+ * } finally {
+ *   limiter.release();
+ * }
+ * ```
+ */
+export class ConcurrencyLimiter {
+    cfg;
+    active = 0;
+    peak = 0;
+    waiters = [];
+    /**
+     * @param config - Partial configuration; omitted fields use {@link CONCURRENCY_DEFAULTS}.
+     * @throws {RangeError} If `maxConcurrent` is not a finite number >= 1, or
+     *   `maxQueue` is neither a non-negative integer nor `Infinity`.
+     */
+    constructor(config = {}) {
+        this.cfg = { ...CONCURRENCY_DEFAULTS, ...config };
+        if (!Number.isFinite(this.cfg.maxConcurrent) || this.cfg.maxConcurrent < 1) {
+            throw new RangeError(`concurrencyLimit.maxConcurrent must be a finite number >= 1, received ${String(this.cfg.maxConcurrent)}`);
+        }
+        // The cap is tested as `waiters.length >= maxQueue`, so `NaN` makes every
+        // comparison false and the queue stops bounding anything: each request then
+        // parks a waiter holding its promise, signal and closures, with nothing
+        // ever rejected. A negative value is the opposite failure — the first
+        // overflow is refused, so a configured depth of -1 silently means 0.
+        if (this.cfg.maxQueue !== Number.POSITIVE_INFINITY &&
+            (!Number.isInteger(this.cfg.maxQueue) || this.cfg.maxQueue < 0)) {
+            throw new RangeError(`concurrencyLimit.maxQueue must be a non-negative integer or Infinity, received ${String(this.cfg.maxQueue)}`);
+        }
+    }
+    /** Number of permits currently held. */
+    get inFlight() {
+        return this.active;
+    }
+    /** Number of requests currently waiting for a permit. */
+    get waiting() {
+        return this.waiters.length;
+    }
+    /** Highest concurrent in-flight count observed. */
+    get highWaterMark() {
+        return this.peak;
+    }
+    /**
+     * Take a permit, waiting in the queue if the limit is saturated.
+     *
+     * @param signal - Optional abort signal; aborting while queued removes the
+     *   waiter and rejects without ever consuming a permit.
+     * @throws {ConcurrencyLimitError} If queueing is disabled or the queue is full.
+     * @throws {KinetexError} With code `EABORT` if `signal` aborts while queued —
+     *   the same contract every other abort path in the library offers, so
+     *   `err.code === "EABORT"` and `err.isAbort` work here too.
+     */
+    acquire(signal) {
+        // Checked before anything else, so the answer does not depend on whether a
+        // permit happened to be free. This used to sit only inside the enqueue
+        // path, which gave the same call three different answers: on an idle pool
+        // the fast path granted the permit and dropped the abort entirely; with
+        // queueing disabled or the queue full, the abort was reported as a queue
+        // overflow, so a caller branching on `err.code === "EABORT"` treated a
+        // cancelled request as a capacity failure.
+        if (signal?.aborted) {
+            // Refused before a permit is taken, so none can leak.
+            return Promise.reject(new KinetexError("Concurrency acquire aborted", "EABORT"));
+        }
+        if (this.active < this.cfg.maxConcurrent) {
+            this.active++;
+            if (this.active > this.peak)
+                this.peak = this.active;
+            return Promise.resolve();
+        }
+        if (!this.cfg.queue) {
+            return Promise.reject(new ConcurrencyLimitError(`Concurrency limit reached (${this.cfg.maxConcurrent} in flight) and queueing is disabled`));
+        }
+        if (this.waiters.length >= this.cfg.maxQueue) {
+            return Promise.reject(new ConcurrencyLimitError(`Concurrency queue is full (${this.cfg.maxQueue} waiting)`));
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, onAbort: null, signal: null };
+            if (signal) {
+                if (signal.aborted) {
+                    // Redundant with the check at the top of `acquire`, and kept as
+                    // defence in depth: nothing awaits between the two, but an `abort`
+                    // event never fires on an already-aborted signal, so if this branch
+                    // were ever the only check the abort would be lost silently.
+                    reject(new KinetexError("Concurrency acquire aborted", "EABORT"));
+                    return;
+                }
+                waiter.onAbort = () => {
+                    const idx = this.waiters.indexOf(waiter);
+                    if (idx !== -1)
+                        this.waiters.splice(idx, 1);
+                    reject(new KinetexError("Concurrency acquire aborted", "EABORT"));
+                };
+                waiter.signal = signal;
+                signal.addEventListener("abort", waiter.onAbort, { once: true });
+            }
+            this.waiters.push(waiter);
+        });
+    }
+    /**
+     * Return a permit taken by {@link acquire}.
+     *
+     * The permit is handed to the longest-waiting caller, so `inFlight` never
+     * exceeds `maxConcurrent`. Releasing with nothing held is a no-op.
+     */
+    release() {
+        if (this.active === 0)
+            return;
+        const next = this.waiters.shift();
+        if (!next) {
+            this.active--;
+            return;
+        }
+        // Transfer the permit: `active` is intentionally left unchanged.
+        detachAbortListener(next);
+        next.resolve();
+    }
+    /**
+     * Drop every queued waiter, rejecting them with `reason`.
+     *
+     * Used by {@link Kinetex.destroy} so a shutdown cannot leave callers parked
+     * on a queue that will never drain.
+     *
+     * @param reason - Error to reject waiters with.
+     */
+    drain(reason = new ConcurrencyLimitError("Client destroyed")) {
+        const pending = this.waiters.splice(0, this.waiters.length);
+        for (const w of pending) {
+            detachAbortListener(w);
+            w.reject(reason);
+        }
+    }
+}
 /**
  * Create a HAR (HTTP Archive) recording interceptor.
  * Captures request/response pairs for export as a HAR log.
@@ -950,7 +1153,11 @@ export function createHARInterceptor() {
             ctx.response.headers["Content-Type"] ??
             "application/octet-stream";
         const body = ctx.response.body;
-        const bSize = body instanceof Uint8Array ? body.byteLength : typeof body === "string" ? body.length : 0;
+        // Byte length, not `.length`: a non-ASCII response body was under-reported in
+        // both `content.size` and `bodySize` by one byte per accented character and by
+        // three bytes per astral character. `computeBodySize` returns -1 for a body it
+        // cannot size, which HAR reports as 0 here (unchanged for those types).
+        const bSize = Math.max(0, computeBodySize(body));
         entries.push({
             startedDateTime: new Date(Date.now() - total).toISOString(),
             time: total,
@@ -1066,22 +1273,18 @@ export function createMetricsInterceptor() {
 // ============================================================================
 // §14  UTILITIES
 // ============================================================================
-function now() {
-    // Use performance.now() when available (browser, Deno, Node 16+, Bun)
-    // Fall back to Date.now() for edge runtimes that may not expose it
-    return typeof performance !== "undefined" && typeof performance.now === "function"
-        ? performance.now()
-        : Date.now();
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
+/** High-resolution monotonic clock — the one `utils.ts` exports, under a local name. */
+const now = perfNow;
 /** @internal Compute byte size of a request/response body. Exported for testing. */
 export function computeBodySize(body) {
     if (!body)
         return 0;
-    if (typeof body === "string")
-        return body.length;
+    if (typeof body === "string") {
+        // UTF-8 byte length, not `.length` (UTF-16 code units). HAR `bodySize` and the
+        // metrics byte counters are byte counts, and a non-ASCII body was under-reported
+        // by 2 bytes per astral character and 1 per Latin-1 accented character.
+        return new TextEncoder().encode(body).length;
+    }
     if (body instanceof Uint8Array)
         return body.byteLength;
     if (body instanceof ArrayBuffer)

package/dist/cjs/lifecycle.js

@@ -23,6 +23,7 @@
  *  - Hook timing + tracing
  *  - Typed event emitter
  */
+import { perfNow, redactHeaders, abortError } from "./utils.js";
 /**
  * Lightweight typed event emitter for lifecycle events.
  *
@@ -30,7 +31,6 @@
  * Use when you just need pub/sub notification.
  */
 export class HookEmitter {
-    // deno-lint-ignore ban-types
     listeners = new Map();
     /** Register a persistent event listener. */
     on(event, listener) {
@@ -59,9 +59,19 @@ export class HookEmitter {
         const list = this.listeners.get(event);
         if (!list || list.length === 0)
             return;
-        const toRemove = new Set();
-        for (let i = 0; i < list.length; i++) {
-            const listener = list[i];
+        // Iterate a snapshot, and remove `once` listeners by identity rather than
+        // by index into the live array. Two things went wrong without that. A
+        // listener that registered another listener mid-emit had the new one
+        // called by the *same* emit, because the loop walks the live array and
+        // re-checks its length. And a listener that called `off()` mid-emit had
+        // its removal undone: the trailing write-back rebuilt the list from the
+        // snapshot taken before the emit, re-adding whatever it had just removed.
+        const snapshot = [...list];
+        // The same element type as `list`, inferred rather than restated: the
+        // bare `Function` type this used to name provides no type safety at all,
+        // since it is every function and every class.
+        const invokedOnce = new Set();
+        for (const listener of snapshot) {
             try {
                 await listener.fn(data);
             }
@@ -69,11 +79,11 @@ export class HookEmitter {
                 /* isolate listener errors */
             }
             if (listener.once)
-                toRemove.add(i);
+                invokedOnce.add(listener);
         }
-        if (toRemove.size > 0) {
-            const remaining = list.filter((_, i) => !toRemove.has(i));
-            this.listeners.set(event, remaining);
+        if (invokedOnce.size > 0) {
+            const current = this.listeners.get(event) ?? [];
+            this.listeners.set(event, current.filter((l) => !invokedOnce.has(l)));
         }
     }
     /** Remove all listeners for an event (or all events if omitted). */
@@ -324,17 +334,25 @@ export class HookRegistry {
      * If any hook returns a HookResponse, it is treated as recovery and returned.
      */
     async runOnError(err, ctx) {
+        let recovered = null;
         for (const hook of sortHooks(this.onError)) {
             if (!this._shouldRun(hook, ctx))
                 continue;
             const result = await this._safeRun(hook, () => hook.fn(err, ctx));
             this._maybeEject(hook, this.onError);
+            // First recovery wins; later hooks are not consulted.
             if (result && typeof result === "object" && "status" in result) {
-                return result;
+                recovered = result;
+                break;
             }
         }
+        // The emitter is the notification channel, not the recovery channel, so it
+        // fires on every error. This line used to sit after the loop behind a plain
+        // `return`, so a recovered error — the one an operator most wants to hear
+        // about, since the caller never sees it — was the only kind an
+        // `emitter.on("error", ...)` subscriber was never told about.
         await this.emitter.emit("error", err);
-        return null;
+        return recovered;
     }
     /** Execute all on-retry hooks. */
     async runOnRetry(evt, ctx) {
@@ -370,12 +388,7 @@ export class HookRegistry {
         for (const hook of sortHooks(this.onUploadProgress)) {
             if (!this._shouldRun(hook, ctx))
                 continue;
-            try {
-                hook.fn(evt, ctx);
-            }
-            catch {
-                /* isolate */
-            }
+            this._safeRunSync(hook, () => hook.fn(evt, ctx));
             this._maybeEject(hook, this.onUploadProgress);
         }
         this.emitter.emit("upload:progress", evt);
@@ -385,12 +398,7 @@ export class HookRegistry {
         for (const hook of sortHooks(this.onDownloadProgress)) {
             if (!this._shouldRun(hook, ctx))
                 continue;
-            try {
-                hook.fn(evt, ctx);
-            }
-            catch {
-                /* isolate */
-            }
+            this._safeRunSync(hook, () => hook.fn(evt, ctx));
             this._maybeEject(hook, this.onDownloadProgress);
         }
         this.emitter.emit("download:progress", evt);
@@ -398,25 +406,26 @@ export class HookRegistry {
     /** Execute all on-cancel hooks. */
     runOnCancel(evt, ctx) {
         for (const hook of sortHooks(this.onCancel)) {
-            try {
-                hook.fn(evt, ctx);
-            }
-            catch {
-                /* isolate */
-            }
+            if (!this._shouldRun(hook, ctx))
+                continue;
+            this._safeRunSync(hook, () => hook.fn(evt, ctx));
             this._maybeEject(hook, this.onCancel);
         }
         this.emitter.emit("cancel", evt);
     }
-    /** Execute all on-connection hooks. */
-    runOnConnection(evt) {
+    /**
+     * Execute all on-connection hooks.
+     *
+     * `ctx` is required rather than optional: a hook registered with a
+     * `condition` can only be evaluated against a context, and making the
+     * parameter optional left the condition silently unevaluated for every caller
+     * that omitted it — which is a wrong answer rather than a compile error.
+     */
+    runOnConnection(evt, ctx) {
         for (const hook of sortHooks(this.onConnection)) {
-            try {
-                hook.fn(evt);
-            }
-            catch {
-                /* isolate */
-            }
+            if (!this._shouldRun(hook, ctx))
+                continue;
+            this._safeRunSync(hook, () => hook.fn(evt));
             this._maybeEject(hook, this.onConnection);
         }
         this.emitter.emit("connection", evt);
@@ -433,8 +442,19 @@ export class HookRegistry {
             fn = () => {
                 if (!this._shouldRun(hook, ctx))
                     return next();
-                const result = hook.fn(ctx, next);
+                // `safe` is honoured here too. It used to be ignored, and ignored in
+                // the *other* direction: a `safe: true` around hook that threw took the
+                // whole request down. On failure the dispatch is still run, because an
+                // around hook that throws before calling `next` has no response to
+                // return and the pipeline cannot continue without one.
+                let failed = false;
+                const result = this._safeRunSync(hook, () => {
+                    failed = true;
+                    return hook.fn(ctx, next);
+                });
                 this._maybeEject(hook, this.aroundHooks);
+                if (failed)
+                    return next();
                 return result;
             };
         }
@@ -468,6 +488,26 @@ export class HookRegistry {
             return undefined;
         }
     }
+    /**
+     * Synchronous counterpart of {@link _safeRun}, used by the phases whose hook
+     * signature is synchronous (progress, cancel, connection) and by around hooks.
+     *
+     * These phases used a bare `try {} catch {}`, which ignored `safe` in both
+     * directions: `safe: false` — the documented default, "critical hooks that
+     * must propagate errors" — was swallowed, and `safe: true` was the only thing
+     * that produced the log line the other phases write.
+     */
+    _safeRunSync(hook, fn) {
+        try {
+            return fn();
+        }
+        catch (err) {
+            if (!hook.safe)
+                throw err;
+            console.error(`[lifecycle] Hook "${hook.id}" threw:`, err);
+            return undefined;
+        }
+    }
     _maybeEject(hook, list) {
         if (!hook.once)
             return;
@@ -597,8 +637,14 @@ export function withBaseURL(base) {
     return (req) => {
         if (/^https?:\/\//i.test(req.url))
             return;
-        const slash = base.endsWith("/") || req.url.startsWith("/") ? "" : "/";
-        return { ...req, url: `${base}${slash}${req.url}` };
+        // Join with exactly one slash. The old test asked "does either side already
+        // carry a slash, in which case add none" — which is wrong precisely when
+        // *both* do: `baseURL: "https://api.test/"` (the most common spelling) with
+        // the path `"/users"` produced "https://api.test//users". Trimming both sides
+        // and adding one slash is the only rule that is right in all four cases.
+        const baseTrimmed = base.replace(/\/+$/, "");
+        const pathTrimmed = req.url.replace(/^\/+/, "");
+        return { ...req, url: `${baseTrimmed}/${pathTrimmed}` };
     };
 }
 /**
@@ -761,13 +807,12 @@ export function composeAround(...hooks) {
  */
 export function createLoggingHooks(options = {}) {
     const log = options.logger ?? ((msg, data) => console.log(msg, JSON.stringify(data)));
-    const redact = new Set((options.redactHeaders ?? ["authorization", "cookie"]).map((h) => h.toLowerCase()));
-    function safeHeaders(h) {
-        const out = {};
-        for (const [k, v] of Object.entries(h))
-            out[k] = redact.has(k.toLowerCase()) ? "***" : v;
-        return out;
-    }
+    // The default list was `authorization` and `cookie` only, while
+    // `afterResponse` logs *response* headers — so `Set-Cookie` was written in
+    // cleartext by default, on a hook whose entire purpose is to log. The
+    // interceptors' own logging defaults already redact all four.
+    const redact = new Set((options.redactHeaders ?? ["authorization", "cookie", "set-cookie", "proxy-authorization"]).map((h) => h.toLowerCase()));
+    const safeHeaders = (h) => redactHeaders(h, redact, "***");
     return {
         beforeRequest: (req) => {
             log("→ request", {
@@ -844,7 +889,7 @@ export function createAbortHook() {
         beforeRequest: (req, ctx) => {
             if (req.signal?.aborted) {
                 ctx.meta.aborted = true;
-                throw createAbortError("Request aborted before sending");
+                throw abortError("Request aborted before sending");
             }
         },
         onCancel: (evt) => {
@@ -855,18 +900,6 @@ export function createAbortHook() {
 // ============================================================================
 // §9  UTILITIES
 // ============================================================================
-// Cross-runtime: safe AbortError creation (DOMException may not exist in all runtimes)
-function createAbortError(message) {
-    if (typeof DOMException !== "undefined") {
-        return new DOMException(message, "AbortError");
-    }
-    const err = new Error(message);
-    err.name = "AbortError";
-    return err;
-}
-function perfNow() {
-    return typeof performance !== "undefined" ? performance.now() : Date.now();
-}
 /**
  * Create a new HookContext for the given request.
  *