kinetex 1.2.0 → 1.4.0

package/dist/esm/response.js

@@ -57,9 +57,15 @@ export class HTTPResponseError extends Error {
     get isClientError() {
         return this.status >= 400 && this.status < 500;
     }
-    /** Returns true if the status code is a server error (5xx). */
+    /**
+     * Returns true if the status code is a server error (5xx).
+     *
+     * Bounded above, like `isClientError` is at both ends. Unbounded, any
+     * status at or past 600 — a non-standard code, or anything a caller invents
+     * — reported itself as a server error.
+     */
     get isServerError() {
-        return this.status >= 500;
+        return this.status >= 500 && this.status < 600;
     }
     /** Returns true if the status is 404 Not Found. */
     get isNotFound() {
@@ -240,6 +246,56 @@ export function isBinary(contentType) {
 // ============================================================================
 // §5  SIZE-LIMITED BODY READER
 // ============================================================================
+/**
+ * One `reader.read()` that also settles when the signal aborts.
+ *
+ * Checking `signal.aborted` at the top of the read loop is not enough, because
+ * the loop only gets another turn when the source produces a chunk or closes.
+ * A connection that stalls after its last byte leaves the read pending
+ * forever, so the abort was never observed and the promise never settled at
+ * all — `readText`/`readJSON`/`readBytes` simply hung, which is the one thing
+ * a signal exists to prevent. Racing the signal against the read is what makes
+ * an abort actually abort.
+ *
+ * An aborted read resolves as `{ done: true }` rather than rejecting, so each
+ * caller keeps its own established behaviour for an abort: the collecting
+ * readers re-check the signal and throw, while the streaming parsers stop
+ * iterating. `cancel()` is still issued so the source is released.
+ */
+function readWithAbort(reader, signal) {
+    if (!signal)
+        return reader.read();
+    if (signal.aborted)
+        return Promise.resolve({ done: true, value: undefined });
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            void reader.cancel("aborted").catch(() => { });
+            resolve({ done: true, value: undefined });
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        reader
+            .read()
+            .then(resolve, reject)
+            .finally(() => {
+            signal.removeEventListener("abort", onAbort);
+        });
+    });
+}
+/**
+ * Normalise the `onExceed` mode, failing closed.
+ *
+ * The three modes were tested as a chain of `if`s that each ended in a
+ * `break`/`return`. A value matching none of them therefore fell straight
+ * through to the ordinary "push the chunk" line below and the size limit did
+ * nothing at all: `onExceed: "ignore"` against a 10-byte cap returned all
+ * 1000 bytes, through both `readBodyWithLimit` and `readText`. That is a
+ * fail-open on the guard this option exists to provide, and the config is a
+ * plain interface, so a value read from JSON or asserted at a call site
+ * reaches it. An unrecognised mode is treated as `"throw"`.
+ */
+function normaliseOnExceed(mode) {
+    return mode === "truncate" || mode === "abort" ? mode : "throw";
+}
 /**
  * Read a ReadableStream with a hard size limit.
  *
@@ -252,7 +308,7 @@ export function isBinary(contentType) {
  * @throws {DOMException} If the signal fires.
  */
 export async function readBodyWithLimit(stream, url, limit, signal) {
-    const onExceed = limit.onExceed ?? "throw";
+    const onExceed = normaliseOnExceed(limit.onExceed);
     const reader = stream.getReader();
     const chunks = [];
     let bytesRead = 0;
@@ -262,9 +318,16 @@ export async function readBodyWithLimit(stream, url, limit, signal) {
                 await reader.cancel("aborted");
                 throw new DOMException("Response reading aborted", "AbortError");
             }
-            const { done, value } = await reader.read();
-            if (done)
+            const { done, value } = await readWithAbort(reader, signal);
+            if (done) {
+                // `done` is also how an aborted read settles (see readWithAbort), so
+                // the signal has to be re-checked here or a partial body would be
+                // returned as a complete one.
+                if (signal?.aborted) {
+                    throw new DOMException("Response reading aborted", "AbortError");
+                }
                 break;
+            }
             const newTotal = bytesRead + value.byteLength;
             if (newTotal > limit.maxBytes) {
                 limit.onExceedCallback?.(newTotal, limit.maxBytes);
@@ -314,7 +377,20 @@ const CHARSET_ALIASES = {
 function resolveCharset(charset) {
     if (!charset)
         return "utf-8";
-    return CHARSET_ALIASES[charset.toLowerCase()] ?? "utf-8";
+    const key = charset.toLowerCase().trim();
+    // Own-property check, not a bare index. `CHARSET_ALIASES` is a plain object
+    // literal, so an unrecognised charset naming an `Object.prototype` member
+    // resolved to that member instead of falling back: `charset=constructor`
+    // reached `TextDecoder` as `function Object() { [native code] }` and
+    // `charset=__proto__` as `[object Object]`, either of which throws
+    // ERR_ENCODING_NOT_SUPPORTED and fails the whole body with a decode error
+    // naming a charset nobody sent. The charset is attacker-controlled — it
+    // comes straight off a response header — so that is a denial of service on
+    // body parsing, and `__proto__` is the kind of value a scanner fuzzes.
+    if (Object.prototype.hasOwnProperty.call(CHARSET_ALIASES, key)) {
+        return CHARSET_ALIASES[key];
+    }
+    return "utf-8";
 }
 /**
  * Detect charset from BOM (byte order mark) in the body.
@@ -397,6 +473,14 @@ export function decompressStream(stream, encoding) {
     if (normalized === "br") {
         return brotliDecompressStream(stream);
     }
+    // ── zstd ─────────────────────────────────────────────────────────────────
+    // `DecompressionStream` has no "zstd" format in Node or the browsers as of
+    // this writing, but does in Bun and newer edge runtimes. Prefer it when
+    // present, otherwise fall back to node:zlib on Node 22+, and only then give
+    // up and pass the bytes through.
+    if (normalized === "zstd") {
+        return zstdDecompressStream(stream);
+    }
     // ── gzip / deflate ────────────────────────────────────────────────────────
     if (typeof DecompressionStream === "undefined")
         return stream;
@@ -420,34 +504,87 @@ export function decompressStream(stream, encoding) {
  * Uses node:zlib on Node.js. Returns the stream unchanged on other runtimes.
  */
 function brotliDecompressStream(stream) {
-    // Detect Node.js safely - process may not exist in edge runtimes
-    let isNode = false;
+    // Non-Node runtime: we cannot decompress brotli natively. Return raw bytes —
+    // this will likely cause a parse error downstream, which is the correct
+    // behaviour (the server shouldn't have sent br in the first place).
+    if (!isNodeRuntime())
+        return stream;
+    return nodeZlibDecompressStream(stream, (zlib) => zlib.createBrotliDecompress());
+}
+/**
+ * True when running on Node.js.
+ *
+ * Read defensively: `process` does not exist in edge runtimes and reading it
+ * through a hostile global can throw.
+ */
+function isNodeRuntime() {
     try {
-        isNode =
-            typeof globalThis.process?.versions
-                ?.node === "string";
+        return (typeof globalThis.process?.versions
+            ?.node === "string");
     }
     catch {
-        /* not Node */
-    }
-    if (!isNode) {
-        // Non-Node runtime: we cannot decompress brotli natively.
-        // Return raw bytes — this will likely cause a parse error downstream,
-        // which is the correct behaviour (server shouldn't have sent br).
-        return stream;
+        return false;
     }
-    // Node.js: pipe through zlib.createBrotliDecompress() via a TransformStream bridge
+}
+/**
+ * Pipe a web ReadableStream through a `node:zlib` decompressor.
+ *
+ * @param stream - Compressed input.
+ * @param create - Builds the zlib transform from the imported module.
+ * @returns The decompressed stream.
+ */
+function nodeZlibDecompressStream(stream, create) {
+    // The node stream and the read loop can both try to settle the controller,
+    // and `cancel()` settles it too. Whichever arrives second would throw
+    // ERR_INVALID_STATE on an already closed controller — an unhandled throw
+    // that takes the whole process down, not just the request. Two reachable
+    // ways to get there:
+    //   * an upstream error rejects `reader.read()`, we error the controller,
+    //     and the `br.destroy()` below makes node emit "end" afterwards;
+    //   * the consumer cancels (an aborted request), and cancelling the source
+    //     makes zlib drain and emit "end" against a closed controller.
+    // Neither is exotic — a server aborting a response mid-body, or a client
+    // cancelling one, is ordinary traffic on any content-encoding response.
+    let settled = false;
+    // Hoisted so `cancel()` can reach it: the bridge holds a reader lock for the
+    // whole stream, and `ReadableStream.cancel()` rejects with ERR_INVALID_STATE
+    // on a locked stream. `reader.cancel()` is the supported way to abort it.
+    let reader = null;
+    // `start()` awaits the dynamic import before locking the source, so a cancel
+    // can land in that window — an immediately-aborted request is the common
+    // case, not an edge one. Remember it and apply it once the reader exists.
+    let cancelRequested = false;
     return new ReadableStream({
         async start(controller) {
             // Dynamic import so non-Node runtimes never load node:zlib
             const zlib = await import("node:zlib");
-            const br = zlib.createBrotliDecompress();
-            const reader = stream.getReader();
+            const br = create(zlib);
+            reader = stream.getReader();
+            if (cancelRequested) {
+                // The source may already be gone; there is nothing left to release.
+                void reader.cancel().catch(() => undefined);
+                reader.releaseLock();
+                reader = null;
+                return;
+            }
+            const settleError = (e) => {
+                if (settled)
+                    return;
+                settled = true;
+                controller.error(e);
+            };
             br.on("data", (chunk) => {
+                if (settled)
+                    return;
                 controller.enqueue(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
             });
-            br.on("end", () => controller.close());
-            br.on("error", (e) => controller.error(e));
+            br.on("end", () => {
+                if (settled)
+                    return;
+                settled = true;
+                controller.close();
+            });
+            br.on("error", settleError);
             try {
                 while (true) {
                     const { done, value } = await reader.read();
@@ -460,17 +597,57 @@ function brotliDecompressStream(stream) {
             }
             catch (e) {
                 br.destroy(e instanceof Error ? e : new Error(String(e)));
-                controller.error(e);
+                settleError(e);
             }
             finally {
                 reader.releaseLock();
+                reader = null;
             }
         },
         cancel() {
-            stream.cancel();
+            // Mark settled first: cancelling the reader resolves the loop's pending
+            // read as `done`, which ends the zlib transform and emits "end" against
+            // an already-closed controller.
+            settled = true;
+            cancelRequested = true;
+            void reader?.cancel().catch(() => undefined);
         },
     });
 }
+/**
+ * Decompress a zstd-encoded ReadableStream.
+ *
+ * Tries, in order: the standard `DecompressionStream("zstd")` (Bun, newer edge
+ * runtimes), then `node:zlib`'s `createZstdDecompress` (Node 22+), then passes
+ * the bytes through unchanged. That last case is a genuine failure mode rather
+ * than a formality — kinetex does not advertise `zstd` in its default
+ * `accept-encoding`, so a server should never choose it, but a caller that sets
+ * the header explicitly (or proxies a response through) can still hit it.
+ */
+function zstdDecompressStream(stream) {
+    if (typeof DecompressionStream !== "undefined") {
+        try {
+            // "zstd" is a real CompressionFormat at runtime but is not yet in the
+            // TypeScript lib union, so it is asserted here rather than widened.
+            const Ctor = DecompressionStream;
+            return stream.pipeThrough(new Ctor("zstd"));
+        }
+        catch {
+            // Format not recognised by this runtime — try node:zlib below.
+        }
+    }
+    if (!isNodeRuntime())
+        return stream;
+    // node:zlib gained zstd in Node 22; older versions have no such export.
+    return nodeZlibDecompressStream(stream, (zlib) => {
+        const create = zlib
+            .createZstdDecompress;
+        if (typeof create !== "function") {
+            throw new Error("zstd decompression is not available in this Node.js version");
+        }
+        return create();
+    });
+}
 /**
  * Detect and apply decompression based on Content-Encoding header.
  *
@@ -620,7 +797,7 @@ export async function* readNDJSON(response, options = {}) {
         while (true) {
             if (options.signal?.aborted)
                 break;
-            const { done, value } = await reader.read();
+            const { done, value } = await readWithAbort(reader, options.signal);
             if (done) {
                 // Process remaining buffer
                 const trimmed = buffer.trim();
@@ -684,6 +861,12 @@ export async function* readJSONStream(response, options = {}) {
     let depth = 0;
     let buffer = "";
     let startIdx = -1;
+    // JSON string state for the scan below. Braces and brackets inside a string
+    // are DATA: the counter closed on a lone `}` in a value, cut the object in
+    // half, and reported both halves as parse errors — so the object was
+    // silently dropped. `{"note":"use } to close"}` yielded nothing at all.
+    let inString = false;
+    let escaped = false;
     const flushBuffer = () => {
         if (startIdx === -1)
             return null;
@@ -695,7 +878,7 @@ export async function* readJSONStream(response, options = {}) {
         while (true) {
             if (options.signal?.aborted)
                 break;
-            const { done, value } = await reader.read();
+            const { done, value } = await readWithAbort(reader, options.signal);
             if (done) {
                 // Try to parse remaining content as final object
                 const remaining = flushBuffer();
@@ -714,6 +897,19 @@ export async function* readJSONStream(response, options = {}) {
             buffer += decoder.decode(value, { stream: true });
             for (let i = 0; i < buffer.length; i++) {
                 const char = buffer[i];
+                if (inString) {
+                    if (escaped)
+                        escaped = false;
+                    else if (char === "\\")
+                        escaped = true;
+                    else if (char === '"')
+                        inString = false;
+                    continue;
+                }
+                if (char === '"') {
+                    inString = true;
+                    continue;
+                }
                 if (char === "{" || char === "[") {
                     if (depth === 0)
                         startIdx = i;
@@ -732,6 +928,12 @@ export async function* readJSONStream(response, options = {}) {
                             options.onParseError?.(err, objStr);
                         }
                         buffer = buffer.slice(i + 1);
+                        // The consumed object's index must not survive into the next
+                        // object: the buffer was resliced underneath it, and a stale
+                        // startIdx is an offset into a string it no longer indexes.
+                        startIdx = -1;
+                        inString = false;
+                        escaped = false;
                         i = -1;
                     }
                 }
@@ -843,7 +1045,9 @@ export class ResponseCache {
         const entry = this.cache.get(key);
         if (!entry)
             return null;
-        if (Date.now() > entry.expiresAt) {
+        // `>=`, not `>`: an entry is expired AT its expiry instant, so
+        // `ttlMs: 0` served a cached response instead of expiring immediately.
+        if (Date.now() >= entry.expiresAt) {
             this.cache.delete(key);
             return null;
         }
@@ -892,14 +1096,20 @@ export async function diffResponses(a, b) {
     const headersChanged = {};
     const headersAdded = {};
     const headersRemoved = {};
+    // Own-property tests, not `in`. `in` walks the prototype chain, and these
+    // are plain object literals, so a header whose lowercased name is an
+    // `Object.prototype` member read as PRESENT in the other response when it
+    // was absent: a `constructor` header only on `a` came back as
+    // `headersChanged: { constructor: ["yes", null] }` — a removed header
+    // reported as changed-to-nothing, in a field typed `[string, string]`.
     for (const [k, v] of Object.entries(ha)) {
-        if (!(k in hb))
+        if (!Object.prototype.hasOwnProperty.call(hb, k))
             headersRemoved[k] = v;
         else if (hb[k] !== v)
             headersChanged[k] = [v, hb[k]];
     }
     for (const [k, v] of Object.entries(hb)) {
-        if (!(k in ha))
+        if (!Object.prototype.hasOwnProperty.call(ha, k))
             headersAdded[k] = v;
     }
     // Body diff (only if both are text)
@@ -942,7 +1152,10 @@ export async function parseMultipartResponse(response) {
     // Split on boundary
     // offset tracking via start variable
     const findBoundary = (from) => {
-        for (let i = from; i < body.length - boundary.length; i++) {
+        // `<=`, not `<`: the loop needs `i + boundary.length <= body.length`, so
+        // a boundary sitting flush against the end of the body — no trailing
+        // newline at all — was the one position the search could not reach.
+        for (let i = from; i <= body.length - boundary.length; i++) {
             if (body.subarray(i, i + boundary.length).every((b, j) => b === boundary[j]))
                 return i;
         }
@@ -984,17 +1197,25 @@ export async function parseMultipartResponse(response) {
                 // The closing boundary break happens below after parsing
             }
         }
-        const partBytes = body.subarray(start, end - 2); // strip trailing CRLF
-        const crlfPos = findDoubleCRLF(partBytes);
-        if (crlfPos === -1) {
+        // Strip the delimiter that precedes this boundary. It was a blind `- 2`
+        // on the assumption of CRLF, so a bare-LF body lost its last two real
+        // bytes, and a part framed some other way lost them too. Measured on the
+        // same two parts: `end - 2` gave "hell" and "worl".
+        let partEnd = end;
+        if (partEnd >= 2 && body[partEnd - 2] === 0x0d && body[partEnd - 1] === 0x0a)
+            partEnd -= 2;
+        else if (partEnd >= 1 && body[partEnd - 1] === 0x0a)
+            partEnd -= 1;
+        const brk = findHeaderBreak(body, start, partEnd);
+        if (!brk) {
             start = end + boundary.length;
             continue;
         }
-        const headerBytes = partBytes.subarray(0, crlfPos);
-        const partBody = partBytes.subarray(crlfPos + 4);
+        const headerBytes = body.subarray(start, brk.headerEnd);
+        const partBody = body.subarray(brk.bodyStart, partEnd);
         const headerText = new TextDecoder().decode(headerBytes);
         const headers = {};
-        for (const line of headerText.split(/\r\n/)) {
+        for (const line of headerText.split(/\r\n|\n/)) {
             const colon = line.indexOf(":");
             if (colon !== -1) {
                 headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
@@ -1009,16 +1230,32 @@ export async function parseMultipartResponse(response) {
     }
     return parts;
 }
-function findDoubleCRLF(bytes) {
-    for (let i = 0; i < bytes.length - 3; i++) {
+/**
+ * Locate the blank line separating a part's headers from its body, accepting
+ * both CRLF and bare-LF framing.
+ *
+ * The old helper matched `\r\n\r\n` and nothing else, so a multipart body
+ * that used bare LF — non-conformant per RFC 2046, and produced in practice —
+ * parsed as ZERO parts rather than as a slightly-off one: every part failed
+ * the header/body split, each was skipped, and the caller got an empty array
+ * with no error. Both framings are now accepted, and the returned body offset
+ * is the real start of the content either way.
+ */
+function findHeaderBreak(bytes, from, to) {
+    for (let i = from; i < to; i++) {
+        // Bare LF: checked first because in `\r\n\r\n` the byte after the
+        // first LF is CR, so the two rules cannot both match at one position.
+        if (bytes[i] === 0x0a && bytes[i + 1] === 0x0a) {
+            return { headerEnd: i, bodyStart: i + 2 };
+        }
         if (bytes[i] === 0x0d &&
             bytes[i + 1] === 0x0a &&
             bytes[i + 2] === 0x0d &&
             bytes[i + 3] === 0x0a) {
-            return i;
+            return { headerEnd: i, bodyStart: i + 4 };
         }
     }
-    return -1;
+    return null;
 }
 /**
  * Read a multipart/form-data response as a FormData object.
@@ -1080,9 +1317,15 @@ export function extractServerTiming(headers) {
         const name = (segments[0] ?? "").trim();
         const params = parseParams(segments.slice(1).join(";"));
         const dur = params.get("dur");
+        // `Number.isFinite`, not `dur !== undefined`: `parseFloat` returns NaN
+        // for anything non-numeric, and `Server-Timing: x;dur=abc` is a
+        // malformed header a server can send. The NaN went straight into the
+        // metrics array, where it is not a number, fails every comparison, and
+        // vanishes from a chart with nothing to indicate why.
+        const parsed = dur !== undefined ? parseFloat(dur) : NaN;
         return {
             name,
-            duration: dur !== undefined ? parseFloat(dur) : null,
+            duration: Number.isFinite(parsed) ? parsed : null,
             description: params.get("desc") ?? null,
         };
     })
@@ -1114,19 +1357,29 @@ async function readBodyBytes(response, url, options) {
             if (options.signal?.aborted) {
                 throw new DOMException("Response reading aborted", "AbortError");
             }
-            const { done, value } = await reader.read();
-            if (done)
+            const { done, value } = await readWithAbort(reader, options.signal);
+            if (done) {
+                // See readWithAbort: an aborted read also resolves as done.
+                if (options.signal?.aborted) {
+                    throw new DOMException("Response reading aborted", "AbortError");
+                }
                 break;
+            }
             chunks.push(value);
         }
     }
     finally {
+        // Cancel before releasing when we are bailing out, so the unread remainder
+        // of the body is discarded rather than left buffered on a released lock.
+        if (options.signal?.aborted) {
+            await reader.cancel("aborted").catch(() => { });
+        }
         reader.releaseLock();
     }
     return concatUint8Arrays(chunks);
 }
 function applySizeLimit(stream, url, limit, signal) {
-    const onExceed = limit.onExceed ?? "throw";
+    const onExceed = normaliseOnExceed(limit.onExceed);
     let bytesRead = 0;
     return new ReadableStream({
         async start(controller) {
@@ -1138,8 +1391,15 @@ function applySizeLimit(stream, url, limit, signal) {
                         controller.error(new DOMException("Response reading aborted", "AbortError"));
                         return;
                     }
-                    const { done, value } = await reader.read();
+                    const { done, value } = await readWithAbort(reader, signal);
                     if (done) {
+                        // See readWithAbort: an aborted read also resolves as done, and
+                        // here the caller must see the error rather than a clean close.
+                        if (signal?.aborted) {
+                            await reader.cancel("aborted").catch(() => { });
+                            controller.error(new DOMException("Response reading aborted", "AbortError"));
+                            return;
+                        }
                         controller.close();
                         break;
                     }
@@ -1180,7 +1440,16 @@ function validateContentType(actual, expected, url) {
         throw new ContentTypeError(expected, "(none)", url);
     const normalizedActual = actual.split(";")[0]?.trim().toLowerCase() ?? "";
     const normalizedExpected = expected.split(";")[0]?.trim().toLowerCase() ?? "";
-    if (!normalizedActual.startsWith(normalizedExpected)) {
+    // Media-type equality, not a string prefix. `startsWith` accepted
+    // `text/plaintext` for `text/plain` and `application/json-seq` for
+    // `application/json` — an `expectedContentType` set to narrow the parse to
+    // one format accepted every format whose name merely begins with it. A bare
+    // top-level type still matches the whole tree, which is the one prefix case
+    // that means something: `image` for `image/png`.
+    const actualType = normalizedActual.split("/")[0] ?? "";
+    const matches = normalizedActual === normalizedExpected ||
+        (normalizedExpected.indexOf("/") === -1 && actualType === normalizedExpected);
+    if (!matches) {
         throw new ContentTypeError(expected, actual, url);
     }
 }