kinetex 1.3.0 → 1.5.0

package/README.md

@@ -23,13 +23,14 @@ const users = await api.get<User[]>("/users");
 const post = await api.POST("/posts").withJSON({ title: "Hello" }).bearer("token").json<Post>();
 ```
 
-Works in **Node.js 18+**, **Deno**, **Bun**, **browsers**, **Cloudflare Workers**, **Vercel Edge**, and all **WinterCG-compliant** runtimes.
+Works in **Node.js 22+** (LTS lines: 22, 24, 26), **Deno**, **Bun**, **browsers**, **Cloudflare Workers**, **Vercel Edge**, and all **WinterCG-compliant** runtimes.
 
 ---
 
 ## Table of Contents
 
 - [Installation](#installation)
+- [Migrating from 1.4.x](#migrating-from-14x)
 - [Quick Start](#quick-start)
 - [Client Configuration](#client-configuration)
 - [Basic HTTP Methods](#basic-http-methods)
@@ -39,6 +40,7 @@ Works in **Node.js 18+**, **Deno**, **Bun**, **browsers**, **Cloudflare Workers*
 - [Authentication](#authentication)
 - [Retry](#retry)
 - [Rate Limiting](#rate-limiting)
+- [Concurrency Limiting](#concurrency-limiting)
 - [Timeout](#timeout)
 - [Interceptors](#interceptors)
 - [Lifecycle Hooks](#lifecycle-hooks)
@@ -60,6 +62,7 @@ Works in **Node.js 18+**, **Deno**, **Bun**, **browsers**, **Cloudflare Workers*
 - [HAR Recording](#har-recording)
 - [OpenTelemetry Tracing](#opentelemetry-tracing)
 - [Pipeline Trace](#pipeline-trace)
+- [Private networks, DNS and TLS](#private-networks-dns-and-tls)
 - [Transport Layer](#transport-layer)
 - [Runtime Detection](#runtime-detection)
 - [Child Clients](#child-clients)
@@ -101,6 +104,37 @@ import { kinetex } from "jsr:@kinetexjs/kinetex";
 
 ---
 
+## Migrating from 1.4.x
+
+1.5.0 contains three breaking changes. Each has a one-line opt-out, so none of them requires you to change anything unless the new default breaks you.
+
+**`maxResponseSize` now defaults to 100 MB** instead of unlimited. The body is read in full before you see any of it, so an unbounded default let a single response exhaust the heap. If you legitimately receive responses over 100 MB:
+
+```ts
+kinetex({ maxResponseSize: 0 }); // 0 has always meant "no limit"
+```
+
+**`totalTimeoutMs` now defaults to the effective `timeout`.** `timeout` bounds one attempt, and the backoff between attempts was not bounded by anything — `timeout: 1_000` with `maxRetries: 5` could hold the caller for roughly 37 seconds. The whole-request ceiling now defaults to `timeout`, so if you were relying on retries outliving `timeout`, raise it or remove it:
+
+```ts
+kinetex({ timeout: 1_000, totalTimeoutMs: 0 }); // unbounded retries, as in 1.4.x
+```
+
+**`URLBuilderOptions` is removed.** It was exported from `kinetex/url` but no constructor, factory or method accepted it, so it could never have been passed anywhere. If you imported the name as a type, drop it — `from()` takes a base URL directly, and `sortParams` is a real method.
+
+Behaviour changes that are not breaking, but will change what you observe:
+
+- A request carrying an `Idempotency-Key` is now retried whatever its method. An unkeyed POST is still attempted exactly once.
+- `Cache-Control: private` responses are no longer cached. This cache is a `Map` in your process, shared across every request it makes, so storing a per-user response served it to whoever asked next. `honorCacheControl: false` opts out.
+- `SameSite=Lax` and `SameSite=Strict` cookies are now sent. The client stated no SameSite context, which by design sends only `Unset` and `None`, so most real sessions were going out without their cookie.
+- A 307/308 redirect carrying a stream or `Blob` body is now refused with a clear `EVALIDATION` rather than failing later as an opaque `ENETWORK`. Those methods preserve the body, and a one-shot body is spent after the first attempt. 301/302/303 are unaffected — they downgrade to GET.
+- A `WebSocket.send()` on a socket that is not OPEN, with `bufferMessages: false`, now reports through `onError` instead of dropping the message silently.
+- A caller-supplied `fetch` is exempt from the pre-flight DNS screen and owns its own resolution. The lexical screen still applies to the initial URL and every redirect hop.
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for the full list, including the defects this release fixes.
+
+---
+
 ## Quick Start
 
 ```ts
@@ -150,9 +184,14 @@ const client = kinetex({
   throwOnError: true, // Throw on 4xx/5xx (default: true)
   followRedirects: true, // Follow redirects (default: true; false returns the 3xx as-is)
   maxRedirects: 20, // Max redirect hops (default: 20; 0 disables following)
+  //                    kinetex follows every hop itself, so each `Location` is screened
+  //                    (see "Redirects" under Transport Layer) — the transport is never
+  //                    asked to follow, whatever this is set to
   httpsOnly: false, // Reject non-HTTPS URLs
-  maxResponseSize: 10_000_000, // Response body size limit (0 = no limit)
+  maxResponseSize: 10_000_000, // Response body size limit (default: 100 MB; 0 = no limit)
   maxRequestSize: 10_000_000, // Request body size limit (0 = no limit)
+  ca: [readFileSync("./corp-root.pem", "utf8")], // Extra CAs to trust (Node transports)
+  allowPrivateNetwork: false, // Permit private/loopback destinations
   strictHeaders: false, // Throw on invalid headers vs warn+drop
   onPipelineTrace: (step) => console.log(step), // Pipeline observability callback
   onSWRError: (err, req) => log(err), // Background SWR revalidation error callback
@@ -171,10 +210,15 @@ const client = kinetex({
   // ── Rate Limit ──
   rateLimit: { limit: 100, windowMs: 60_000, queue: true, maxQueue: 100 },
 
+  // ── Concurrency Limit ──
+  // Bounds requests *in flight*, which rateLimit cannot: a token bucket
+  // releases at dispatch, so 100/min still permits 100 simultaneous sockets.
+  concurrencyLimit: { maxConcurrent: 10, queue: true, maxQueue: 100 },
+
   // ── Proxy ──
-  // NOTE: `proxy` fails fast — kinetex's built-in transports cannot route
-  // through it. Use the `fetch` option with a proxy-capable agent for
-  // HTTP(S) proxies, or createSocks5Tunnel() from "kinetex/socks5" for SOCKS5.
+  // HTTP(S) CONNECT proxies work on Node, on both built-in transports.
+  // SOCKS5 URLs still throw, pointing at kinetex/socks5.
+  // proxy: { url: "http://127.0.0.1:8080" },
   // proxy: { url: "socks5://127.0.0.1:1080" },  // → throws with guidance
 
   // ── Cache ──
@@ -373,7 +417,7 @@ interface SendOptions<T = unknown> {
   maxRedirects?: number; // Max redirect hops (default: 20; 0 disables following)
   httpVersion?: HTTPVersion; // Preferred HTTP version
   maxRequestSize?: number; // Request size limit (bytes)
-  maxResponseSize?: number; // Response size limit (bytes)
+  maxResponseSize?: number; // Response size limit (bytes, default 104857600; 0 = unlimited)
   parseResponse?: (raw: Uint8Array, headers: Record<string, string>, url: string) => T | Promise<T>;
   parseFailure?: (raw: Uint8Array, error: Error) => void;
   onSuccess?: (res: KinetexResponse<T>) => void;
@@ -461,12 +505,16 @@ client.GET("/public").noAuth().json();
 kinetex({
   retry: {
     maxRetries: 3, // Max attempts (default: 3)
+    totalTimeoutMs: 20_000, // Ceiling on the WHOLE request: attempts + backoff (default: = timeout)
     baseDelayMs: 300, // Exponential back-off base (default: 300)
     maxDelayMs: 30_000, // Max delay cap (default: 30_000)
     jitter: 0.3, // Random jitter factor 0-1 (default: 0.3)
     statuses: [408, 429, 500, 502, 503, 504], // Status codes that trigger retry
     onNetworkError: true, // Retry on network errors (default: true)
     onTimeout: false, // Retry on timeouts (default: false)
+    // Only these methods are retried. A request carrying an `Idempotency-Key`
+    // is retried whatever its method — the key is the caller's declaration
+    // that repeating it is safe. See "Idempotency Keys" below.
     methods: ["GET", "HEAD", "PUT", "DELETE", "OPTIONS", "TRACE"],
     shouldRetry: (ctx) => ctx.attempt < 3 && ctx.response?.status === 503, // Custom predicate
     onRetry: (ctx, delayMs) => console.log(`Retry ${ctx.attempt} in ${delayMs}ms`),
@@ -474,6 +522,38 @@ kinetex({
 });
 ```
 
+`timeout` applies to a single attempt; `totalTimeoutMs` bounds the whole logical
+request, backoff included, and defaults to `timeout`. Set it to `0` to remove
+the ceiling. When the next backoff would exceed the budget the retry is skipped
+rather than slept through, and the original response or error is what the caller
+receives — the budget never substitutes an `ETIMEOUT` for a real cause.
+
+### Idempotency Keys
+
+A `POST` is not retried by default, because replaying an unkeyed write can
+double-charge someone. A request that carries an `Idempotency-Key` **is** retried
+whatever its method: the header exists precisely to declare the request
+replayable, and the server collapses the duplicates.
+
+```ts
+import { generateIdempotencyKey, isValidIdempotencyKey } from "kinetex";
+
+// Keys are RFC 9562 v4 UUIDs from the runtime CSPRNG.
+const key = generateIdempotencyKey();
+isValidIdempotencyKey(key); // true
+
+// Any method, retried on transient failures, same key every attempt —
+// a fresh key per attempt would defeat the mechanism.
+await client.post("/charges", body, { headers: { "idempotency-key": key } });
+
+// Or fluently:
+await client.POST("/charges").withJSON(body).idempotencyKey().json();
+```
+
+An unkeyed `POST` is still attempted exactly once. Validation is 1–255 visible
+ASCII, so CR/LF/NUL cannot be smuggled into the headers, and a runtime without
+`crypto.getRandomValues` throws rather than falling back to a guessable value.
+
 ### RetryContext
 
 The `ctx` parameter in `shouldRetry` and `onRetry` is of type `RetryContext`:
@@ -516,6 +596,76 @@ kinetex({
 
 ---
 
+## Concurrency Limiting
+
+A counting semaphore bounding how many requests may be **in flight** at once.
+`rateLimit` cannot do this: a token bucket releases at _dispatch_, so
+`rateLimit: { limit: 100 }` per minute still permits 100 simultaneous sockets.
+
+```ts
+kinetex({
+  concurrencyLimit: {
+    maxConcurrent: 10, // Permits held at once (default: 10; must be a finite number >= 1)
+    queue: true, // Queue the excess vs reject (default: true)
+    maxQueue: 100, // Queue depth before rejecting (default: 100)
+  },
+});
+```
+
+A permit is held for the **whole logical request, retries included**, and
+returned in a `finally` — so a throw, an exhausted retry budget or a `destroy()`
+can never leak one and permanently shrink the pool. On release the permit is
+handed straight to the longest-waiting caller rather than freed and re-taken, so
+`inFlight` never transiently exceeds `maxConcurrent`.
+
+When the queue is full (or `queue: false`), the request is rejected with
+`ConcurrencyLimitError`, code `ECONCURRENCY`:
+
+```ts
+import { ConcurrencyLimitError } from "kinetex";
+
+try {
+  await client.get("/slow");
+} catch (err) {
+  if (err instanceof ConcurrencyLimitError) {
+    console.log(err.code); // "ECONCURRENCY"
+  }
+}
+```
+
+A request cancelled while queued is a **different** failure and is reported as
+such — `code: "EABORT"` with `isAbort`, the same contract every other abort path
+in the library offers. That holds whichever path the acquire took: an idle pool,
+a saturated pool with queueing on, queueing off, and a full queue all answer
+`EABORT` rather than reporting a cancellation as a capacity failure. An
+already-aborted signal is refused before a permit is taken, so none can leak.
+
+`maxQueue` must be a non-negative integer, or `Infinity` for an unbounded queue;
+anything else — including `NaN` — throws a `RangeError` at construction rather
+than leaving the cap unbound. `maxConcurrent` is validated the same way.
+
+### Standalone use
+
+The limiter is exported on its own, for gating work that is not a request:
+
+```ts
+import { ConcurrencyLimiter, CONCURRENCY_DEFAULTS } from "kinetex";
+
+const limiter = new ConcurrencyLimiter({ maxConcurrent: 4 });
+console.log(limiter.inFlight, limiter.waiting, limiter.highWaterMark);
+
+await limiter.acquire(signal);
+try {
+  await doWork();
+} finally {
+  limiter.release();
+}
+
+limiter.drain(); // reject everyone still queued (what Kinetex.destroy does)
+```
+
+---
+
 ## Timeout
 
 Default timeout is 30 seconds. Set to 0 for no timeout:
@@ -540,6 +690,15 @@ try {
 
 Internally uses `sendWithTimeout(transport, request, timeoutMs)` which races the transport promise against a timeout promise using `AbortController` and `mergeSignals`.
 
+**A merged signal keeps the reason.** `mergeSignals(a, b)` re-aborts with the
+`reason` of whichever source actually aborted, so
+`signal.reason` survives the combination instead of collapsing to a generic
+`AbortError: This operation was aborted` — including when a source was _already_
+aborted before the call, which is the case a shortcut in the "no live signals
+left" branch used to get wrong. Interceptors rely on this: retry and
+deduplication logic reads `existing.reason` off the combined signal to decide
+what actually went wrong.
+
 ---
 
 ## Interceptors
@@ -655,7 +814,14 @@ const suite = createInterceptorSuite({
 
 ## Lifecycle Hooks
 
-Hooks are higher-level callbacks for specific lifecycle stages, configured at client creation:
+Hooks are higher-level callbacks for specific lifecycle stages, configured at client creation.
+
+`onAfterRequest` fires in exactly the window its name describes: after the
+transport has answered and before the response is built, once per attempt. It
+is the only place you can observe that the round trip is over without also
+having to see the parsed response — and it deliberately does **not** fire on a
+request that never left, so a hook that counts what was sent does not count a
+connection that died first.
 
 ```ts
 kinetex({
@@ -668,7 +834,7 @@ kinetex({
     ],
     onAfterRequest: [
       (req, ctx) => {
-        /* request was sent */
+        /* the wire round trip is over; the response is not built yet */
       },
     ],
     onBeforeResponse: [
@@ -840,7 +1006,7 @@ interface HookOptions {
 
 ## Request Deduplication
 
-Coalesces identical concurrent GET/HEAD requests into a single network call. The dedup key includes a SHA-256 fingerprint of every credential-bearing header, so two users calling the same URL with different `Authorization` / `Cookie` / API-key headers are never coalesced into one response:
+Coalesces identical concurrent GET/HEAD requests into a single network call. The dedup key includes a SHA-256 fingerprint of **every request header**, so two callers are only ever coalesced when they would have received the same response — different `Authorization`, `Cookie`, API key _or_ a tenant/session header each get their own in-flight slot. Per-request tracing headers (`traceparent`, `tracestate`, `baggage`, `x-request-id`, `x-correlation-id`, `x-trace-id`) are excluded, since every request carries its own and including them would disable coalescing entirely:
 
 ```ts
 import { CREDENTIAL_HEADERS } from "kinetex/cache";
@@ -987,7 +1153,7 @@ const client = kinetex({
     // maxBodySizeBytes: 5 * 1024 * 1024, // skip caching larger bodies
     // defaultTtlMs: 60_000, // when the response has no Cache-Control (max 1 year)
     // maxAbsoluteAgeMs: 7 * 24 * 60 * 60 * 1000, // hard cap regardless of Cache-Control
-    // honorCacheControl: true, // respect no-store / no-cache
+    // honorCacheControl: true, // respect no-store / no-cache / private
     // cacheMethods: ["GET", "HEAD"],
     // cacheStatuses: [200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501],
     storage: new MemoryStorageAdapter(), // omit for plain in-memory
@@ -1009,6 +1175,11 @@ client.GET("/users").cache({ ttlMs: 5000 }).json();
 client.GET("/users").noCache().json(); // forceRefresh: true
 ```
 
+`forceRefresh` skips the cache **read** for that one request and nothing else:
+the fresh response is still written, so a later plain request is served from
+the cache again. It is a bypass, not a purge — use `cache.clear()` or
+`invalidateTags()` to drop entries.
+
 **Stale-while-revalidate needs no config flag.** There is no `swr` or `swrTtlMs` option: the SWR window is taken from the response's `Cache-Control: stale-while-revalidate=N`, and within that window kinetex serves the stale copy immediately and revalidates in the background. Two consequences worth knowing:
 
 - A per-request `cache.ttlMs` override pins the SWR window to 0 for that request. If you want SWR, let the server's `Cache-Control` decide the lifetime.
@@ -1113,7 +1284,15 @@ await cache.clear();
 
 ## Cookie Jar
 
-Full RFC 6265 cookie storage and management with SameSite, HttpOnly, Secure, domain/path matching:
+Full RFC 6265 cookie storage and management with SameSite, HttpOnly, Secure, domain/path matching.
+
+`CookieJar.fromJSON` / `loadCookieJar` are the one public path that ingests
+externally authored JSON, so they canonicalise `sameSite` on the way in:
+`"lax"`, `"LAX"` and `"Lax"` all mean `Lax`, and an unrecognised or missing
+value becomes `Unset`. Without that, a persisted jar could report `count === 1`
+and send nothing at all, because an unrecognised `SameSite` matches no branch
+of the retrieval filter. `Unset` still refuses an explicit cross-site request,
+so a value that cannot be interpreted is never treated as "send everywhere".
 
 ```ts
 // Auto-managed through the client
@@ -1579,7 +1758,7 @@ const ws = new WSClient({
   lowWaterMark: 16384,
   maxSendRate: 0, // 0 = unlimited
   keepRooms: true,
-  bufferMessages: true,
+  bufferMessages: true, // queue sends made while reconnecting; see below
   maxBufferSize: 1000,
   rooms: ["prices"],
   signal: controller.signal,
@@ -1642,6 +1821,11 @@ ws.leave("prices");
 ws.rooms; // readonly WSSubscribedRoom[]
 
 // Backpressure
+// With `bufferMessages: true` (default) a send made while the socket is not
+// OPEN is queued, up to `maxBufferSize`, oldest evicted first. With it false
+// there is nowhere to put that message: it is dropped, and the drop is reported
+// through `onError` — `send()` returns void, so silence would make a lost
+// message indistinguishable from a delivered one.
 ws.backpressure; // { bufferedBytes, highWaterMark, lowWaterMark, isBackpressured, ... }
 await ws.drain(30_000); // Wait until outbound buffer is flushed
 await ws.drainAndClose(30_000); // Drain, then close gracefully
@@ -2004,6 +2188,17 @@ const skewMs = await detectClockSkew("https://sts.amazonaws.com", credentials);
 isClockSkewError(err); // → boolean
 ```
 
+**`imdsCredentials` reports failure as a `NetworkError`, never a raw
+`SyntaxError`.** Every way the EC2 metadata service can disappoint you — an
+unreachable endpoint, a non-200, a body that is not JSON, or a 200 whose JSON
+is missing `AccessKeyId` / `SecretAccessKey` / `Token` — surfaces as the same
+error type, so a `chainCredentials` fallback can catch one thing. A body is
+accepted only if every required field is a non-empty string; `{}` and
+`{"AccessKeyId": null}` are refused, and the error names _all_ the fields that
+were absent rather than making you discover them one round trip at a time.
+Signing with `undefined` keys would otherwise produce a `SignatureDoesNotMatch`
+from AWS that points at the caller instead of at the metadata service.
+
 ### Client-Level SigV4
 
 ```ts
@@ -2155,6 +2350,14 @@ Create one per client (do not share it across users). `Kinetex`'s built-in `auth
 
 ## Structured Logging
 
+Body-field redaction applies to every JSON media type, not just
+`application/json`: `+json` structured suffixes (`application/vnd.api+json`,
+`application/hal+json`, `application/problem+json`, …), `text/json`, any
+casing, and any parameters. `allowedBodyTypes` decides whether a body is logged
+at all; a body that clears that gate has its `bodyFields` redacted whatever
+its exact media type, so widening `allowedBodyTypes` cannot quietly start
+leaking `password` fields.
+
 ```ts
 import {
   HTTPLogger,
@@ -2238,7 +2441,7 @@ const har = client.getHAR();
 // HARLog { version: "1.2", creator: { name: "kinetex", version: "1.0.0" }, entries: [...] }
 
 // Each HAREntry contains:
-// startedDateTime, time, request (method, url, httpVersion, headers, queryString, bodySize),
+// startedDateTime, time, request (method, url, httpVersion, headers, queryString, bodySize, postData?),
 // response (status, statusText, httpVersion, headers, content, redirectURL, bodySize),
 // timings (send, wait, receive), cache
 
@@ -2254,6 +2457,7 @@ HAR logs are routinely exported and shared, so entries are redacted before they
 - **URLs** — sensitive query parameters (`api_key`, `access_token`, `signature`, `password`, `code`, `sas`, …) and the fragment are masked, in both `request.url` and `request.queryString[]`. Non-sensitive parameters and the rest of the URL are preserved so the log stays useful.
 - **`Location`** — the redirect target is passed through the same URL redaction.
 - **Bodies** — response text is recorded only for `json`/`xml`/`text/plain`/`javascript` content types and truncated to 8 KiB; HTML and binary bodies are never recorded.
+- **Request bodies** — recorded as `request.postData` (`{ mimeType, text }`) under the same policy and the same limit, so a HAR viewer shows what was actually sent. A `ReadableStream` or `FormData` body is omitted rather than buffered, since reading it would consume it; `request.bodySize` is `-1` for those, as it always was. For a `json` body the same sensitive names used for headers and query parameters (`password`, `token`, `api_key`, `secret`, …) are replaced with `***REDACTED***` at any nesting depth, since a JSON body is where credentials most often travel and HAR files get shared. Non-JSON bodies keep their text, but the literal values of this request's own credentials — the credential header, the part after its scheme, and sensitive query parameters — are still replaced wherever they appear, which catches a server echoing a token back in an error message.
 
 ```ts
 // ?api_key=SUPERSECRET&page=2  →  https://api.example.com/v1/items?api_key=***REDACTED***&page=2
@@ -2337,8 +2541,114 @@ Pipeline stages in order:
 
 ---
 
+## Private networks, DNS and TLS
+
+```ts
+const client = kinetex({
+  baseURL: "https://internal.svc",
+
+  // Trust a private CA alongside the system store. Without this, a service mesh
+  // or enterprise proxy whose certificate a corporate CA issued fails TLS.
+  // Node's transports only — `fetch` exposes no CA option, so a custom `fetch`
+  // or `dispatcher` setup has to carry its own.
+  ca: [readFileSync("./corp-root.pem", "utf8")],
+
+  // Reach localhost, a service mesh or a local dev server. Off by default.
+  allowPrivateNetwork: true,
+});
+```
+
+### How the screen works
+
+A URL is a name, not an address, so screening the text you typed does not
+describe what the socket will do. Three layers close that gap:
+
+1. **Lexical.** `isSafeURL` rejects a literal loopback, private, link-local or
+   otherwise blocked address, on the initial URL and on every redirect hop.
+2. **Resolution, pinned (Node).** `NodeHTTP2Transport` and the HTTP/1.1 path
+   resolve once and hand the _checked_ address to the socket
+   (`createPinnedLookup`). A name answering with both a public and a private
+   address keeps only the public one; one answering with only private space
+   fails with `EBLOCKEDHOST` rather than connecting.
+3. **Resolution, pre-flight (`FetchTransport`).** `fetch` exposes no resolver
+   hook — undici owns the connection — so `FetchTransport` resolves before the
+   call and refuses a host whose answers are all blocked. This layer applies
+   only when kinetex is using the runtime's own `fetch`. Supply your own via
+   the `fetch` option and you own resolution end to end: kinetex screens every
+   URL lexically, but it cannot observe which address your dispatcher dials, so
+   checking the system resolver's answer would describe a lookup that never
+   happens. Treat `fetch` the way you would treat a custom `dispatcher` — a
+   decision you have taken responsibility for.
+
+The second layer closes rebinding completely, because the address that passed
+the check is the address that is dialled. The third cannot: it is a check
+followed by a separate resolution inside `fetch`, so a resolver that answers
+public on the first lookup and private on the second is not caught here. On
+Node you get the pinned path; on Deno, Bun and edge runtimes this is the
+residual exposure, and it is worth a runtime-level DNS policy where one is
+available.
+
+### What the opt-out really does
+
+`allowPrivateNetwork: true` is not a narrower exception — it turns the screen
+off for the initial URL _and_ for every redirect hop, and it is the reason a
+redirect to `http://127.0.0.1:9/` is followed rather than refused. Set it only
+where the URLs you request are not influenced by anyone else: local
+development, a service mesh you control, and the test suite.
+
 ## Transport Layer
 
+### Redirects
+
+**kinetex follows every redirect itself.** The outgoing request always carries
+`redirect: "manual"`, and a server-chosen `Location` is resolved, screened and
+re-dispatched one hop at a time. This is not a tuning knob — it is what makes
+the per-hop checks below possible at all, because `fetch` following on its own
+never reports a target back to the caller.
+
+Every hop is subject to:
+
+- **SSRF.** `isSafeURL` runs on each `Location` before it is dialled, so a
+  redirect cannot walk the client onto a loopback, private or link-local
+  address. A 302 to `http://127.0.0.1:9/` or to `http://169.254.169.254/`
+  raises `EVALIDATION` ("Unsafe redirect target blocked") rather than opening
+  the socket — the initial request URL gets the same screen.
+- **`httpsOnly`.** Checked on the target, not just the request you wrote, so an
+  `https:` request cannot be downgraded to cleartext by its response.
+- **`maxRedirects`.** Enforced per request, default 20. Exhausting it raises
+  `RedirectError` (`EREDIRECT`, "Too many redirects"). `followRedirects: false`
+  — or `maxRedirects: 0` — hands the 3xx back to you instead.
+- **Loop detection.** A target already visited in this chain is refused with
+  `RedirectError` (`EREDIRECT`, "Redirect loop detected").
+- **Method downgrade.** Per RFC 7231, 301/302/303 downgrade to `GET` and drop
+  the body; 307/308 preserve both. A 307/308 therefore needs the body a second
+  time, and a `ReadableStream`/`Blob` body is spent after the first attempt — so
+  that hop is refused with `EVALIDATION` rather than silently sent empty. Buffer
+  the body first, or disable redirects for that request.
+- **Credentials.** `Authorization`, `apikey` headers, `Cookie` and any
+  declared auth are dropped when a hop changes origin, and kept when it does
+  not. Intermediate `Set-Cookie` headers are captured by the jar, so cookies
+  set on a redirect leg are applied to the next one.
+- **Scheme.** Anything but `http:` / `https:` is rejected as
+  `EVALIDATION`, so `file:`, `data:` and friends cannot be reached.
+
+`res.redirected` tells you whether a hop was actually taken, and `res.url` is
+where the request finally landed. An _unfollowed_ 3xx — `followRedirects:
+false`, or `maxRedirects: 0` — reports `redirected: false` and the original
+`res.url`, because nothing was followed: that response is the one you have to
+read `Location` on and act on yourself.
+
+A redirect failure is a `RedirectError` with code `EREDIRECT` ("Too many
+redirects", "Redirect loop detected"), and it is **not** retried. A chain is a
+deterministic answer from the origin, so replaying it would only multiply the
+requests against a server already looping: `maxRedirects: 3` makes exactly
+four requests, not one per retry attempt. The SSRF and `httpsOnly` gates stay
+`EVALIDATION`, as does an unsafe redirect target.
+
+The built-in transports enforce the same two gates in their own loops
+(`https:` only, plus `isSafeURL`), so the protection does not depend on going
+through `Kinetex`.
+
 ### FetchTransport
 
 Universal fetch-based transport for all runtimes:
@@ -2388,6 +2698,57 @@ Features:
 - Iterative redirect following (not recursive)
 - Backpressure-aware body writes (awaits `drain` events)
 
+**The transport owns the request line.** `:method`, `:path`, `:scheme` and
+`:authority` are built from the URL you hand to `send()` and cannot be
+overridden from `request.headers`. A pseudo-header there is refused the same
+way any other invalid header is: `EVALIDATION` under `strict: true`, otherwise
+`onDroppedHeader(name, value)` or a `console.warn`. This is not a formality —
+`":"` is not a token character, so `FetchTransport` has always dropped such a
+header, and the two transports now answer a single request the same way.
+
+Header names are validated as tokens and values as field-values, so a
+`__proto__` header (legal — it is all token characters) is sent as a real
+header rather than disappearing into an inherited setter.
+
+### Request Bodies
+
+`FetchTransport` hands the body to `fetch`; `NodeHTTP2Transport` drives
+`node:http2` directly. The two therefore serialize differently, and on Node
+the default transport is the latter — so anything fetch would have encoded has
+to be encoded by kinetex first. `URLSearchParams`, `Blob` and `FormData` are
+all covered:
+
+```ts
+const form = new FormData();
+form.append("field", "value");
+form.append("file", new File([blob], "report.csv", { type: "text/csv" }));
+
+// → multipart/form-data; boundary=----kinetexFormBoundary<random>
+const res = await client.POST("/upload").withForm(form).send();
+```
+
+**The boundary and the header are generated together.** The boundary is
+invented _during_ encoding, so a body encoded after the header block was
+already written names a boundary no header mentions — and a multipart body
+whose boundary is not announced is unparseable. Both raw Node paths therefore
+pre-encode the body before building headers, and a `content-type` you set
+yourself always wins. `encodeMultipart(form, boundary?)` is exported for
+callers who want the bytes directly; pass a boundary to make the output
+deterministic.
+
+A field name containing CR, LF or a double quote is refused with
+`EVALIDATION` rather than serialized, since a name is interpolated into a
+`Content-Disposition` header and could otherwise forge extra part headers. A
+File's `filename` goes into the same quoted-string context but is
+percent-escaped rather than refused, so ordinary names keep working.
+
+`maxRequestSize` counts what actually goes on the wire. For a `FormData`
+that means the form is encoded once and its real byte length is compared —
+there is no per-part guess, and the encoding is not repeated on the dispatch
+path. A `ReadableStream` body is the one type that cannot be measured at all,
+so it is refused instead of bypassing the limit; pass `maxRequestSize: 0` to
+opt out, or buffer the body first.
+
 ### Transport Factory
 
 ```ts
@@ -2577,14 +2938,7 @@ import {
   buildDataURL,
   diffURLs,
 } from "kinetex/url";
-import type {
-  ParsedURL,
-  URLBuilderOptions,
-  URLPattern,
-  URLPatternMatch,
-  URLDiff,
-  DataURLParts,
-} from "kinetex/url";
+import type { ParsedURL, URLPattern, URLPatternMatch, URLDiff, DataURLParts } from "kinetex/url";
 
 // URL Builder (fluent, immutable — every method returns a new builder)
 const builder = URLBuilder.from("https://api.example.com")
@@ -2999,8 +3353,12 @@ isSafeURL("http://169.254.169.254/latest/meta-data/"); // false
 isSafeURL("http://[::ffff:127.0.0.1]/"); // false
 
 // Applied to the initial URL AND to every redirect hop, so a public host cannot
-// bounce a request into the private network. (DNS rebinding is out of scope —
-// the check is literal-address based, not a resolution.)
+// bounce a request into the private network.
+//
+// These helpers are literal-address checks. Resolution is handled separately by
+// the transports: the Node ones resolve once and pin the checked address to the
+// socket, and `FetchTransport` resolves before the call and refuses a host whose
+// answers are all blocked. See "Private networks and DNS" below.
 sanitizeURL("javascript:alert(1)"); // null — invalid or an SSRF risk
 sanitizeURL("https://user:pass@api.example.com/x"); // "https://api.example.com/x" (credentials stripped)
 
@@ -3023,9 +3381,19 @@ const b64 = uint8ArrayToBase64(uint8);
 
 // Object
 const clone = deepClone(original);
-const normalized = normalizeHeaders(rawHeaders); // Lowercase keys
+// normalizeHeaders keys are lowercased, and a header that appears more than
+// once keeps every value rather than only the last one.
+const normalized = normalizeHeaders(rawHeaders);
 ```
 
+**Repeated headers keep every value.** `Set-Cookie` is the one header a
+`Headers` object yields _separately_ per cookie rather than already joined, so
+a naive normalisation that assigns as it iterates silently drops every cookie
+but the last — and the request still looks fine. `normalizeHeaders`
+accumulates instead, so a response with three `Set-Cookie` lines round-trips
+back to three, each with its `Expires=Wed, 09 Jun 2021 10:18:14 GMT` intact.
+`toNodeHeaders` and the `HttpHeaders` type were already correct on this.
+
 ---
 
 ## Error Handling
@@ -3252,14 +3620,7 @@ import type { Socks5ProxyConfig, Socks5Tunnel, Socks5Target, TcpConnector } from
 import type { FetchTransportOptions } from "kinetex/core";
 import type { OTelTracer, OTelSpan } from "kinetex";
 import type { SafeJSONParseOptions, SafeJSONParseResult, ErrorContext } from "kinetex";
-import type {
-  ParsedURL,
-  URLBuilderOptions,
-  URLPattern,
-  URLPatternMatch,
-  URLDiff,
-  DataURLParts,
-} from "kinetex/url";
+import type { ParsedURL, URLPattern, URLPatternMatch, URLDiff, DataURLParts } from "kinetex/url";
 ```
 
 ---
@@ -3330,26 +3691,26 @@ import { kinetex } from "kinetex/browser";
 
 ## Runtime Compatibility
 
-| Feature                                   | Node 18+                 | Node 22+ | Deno          | Bun           | Browser       | CF Workers    | Vercel Edge   |
-| ----------------------------------------- | ------------------------ | -------- | ------------- | ------------- | ------------- | ------------- | ------------- |
-| HTTP/1.1 fetch                            | ✓                        | ✓        | ✓             | ✓             | ✓             | ✓             | ✓             |
-| HTTP/2 (fetch, via Alt-Svc/runtime hints) | ✓*                       | ✓        | ✓             | ✓             | ✓             | ✓             | ✓             |
-| HTTP/2 (NodeHTTP2Transport)               | ✗                        | ✓        | ✗             | ✗             | ✗             | ✗             | ✗             |
-| HTTP/3 (detection via Alt-Svc)            | ✓*                       | ✓*       | ✓*            | ✓*            | experimental  | ✓*            | ✓*            |
-| WebSocket (WSClient)                      | ✗¹ (no native WebSocket) | ✓        | ✓             | ✓             | ✓             | partial²      | ✗³            |
-| SOCKS5 proxy                              | ✓                        | ✓        | ✓             | ✓             | ✗             | ✗             | ✗             |
-| Blob                                      | ✓                        | ✓        | ✓             | ✓             | ✓             | guarded       | guarded       |
-| DOMException                              | ✓                        | ✓        | ✓             | ✓             | ✓             | guarded       | guarded       |
-| Buffer                                    | ✓                        | ✓        | ✓             | ✓             | ✗             | ✗             | ✗             |
-| crypto.subtle                             | ✓                        | ✓        | ✓             | ✓             | ✓             | ✓             | ✓             |
-| ReadableStream                            | ✓                        | ✓        | ✓             | ✓             | ✓             | ✓             | ✓             |
-| URL pattern matching                      | ✓                        | ✓        | ✓             | ✓             | ✓             | ✓             | ✓             |
-| Brotli decompression                      | ✓                        | ✓        | ✗ passthrough | ✗ passthrough | ✗ passthrough | ✗ passthrough | ✗ passthrough |
-| Gzip/deflate decompression                | ✓                        | ✓        | ✓             | ✓             | ✓             | ✓             | ✓             |
-
-\* HTTP/2+ detection is best-effort and internal. kinetex's own `detectHTTPVersion()` helper (not exported) reports HTTP/2 only when the runtime exposes protocol evidence — a response `httpVersion`/`protocol` property, or an `Alt-Svc` header — and otherwise reports `HTTP/1.1`. The version on every `KinetexResponse` comes from that heuristic, so it is not a guarantee. This is accurate for Node 18's undici fetch, which does not negotiate h2 by default; use `NodeHTTP2Transport` (Node 22+) when you need guaranteed HTTP/2.
-
-¹ WSClient requires a native `WebSocket` constructor. Node added one in v22 — on Node 18 use a polyfill (`globalThis.WebSocket = require('undici').WebSocket`).
+| Feature                                   | Node 22+ | Deno | Bun           | Browser       | CF Workers    | Vercel Edge   |
+| ----------------------------------------- | -------- | ---- | ------------- | ------------- | ------------- | ------------- |
+| HTTP/1.1 fetch                            | ✓        | ✓    | ✓             | ✓             | ✓             | ✓             |
+| HTTP/2 (fetch, via Alt-Svc/runtime hints) | ✓*       | ✓    | ✓             | ✓             | ✓             | ✓             |
+| HTTP/2 (NodeHTTP2Transport)               | ✓        | ✗    | ✗             | ✗             | ✗             | ✗             |
+| HTTP/3 (detection via Alt-Svc)            | ✓*       | ✓*   | ✓*            | experimental  | ✓*            | ✓*            |
+| WebSocket (WSClient)                      | ✓        | ✓    | ✓             | ✓             | partial²      | ✗³            |
+| SOCKS5 proxy                              | ✓        | ✓    | ✓             | ✓             | ✗             | ✗             | ✗             |
+| Blob                                      | ✓        | ✓    | ✓             | ✓             | ✓             | guarded       | guarded       |
+| DOMException                              | ✓        | ✓    | ✓             | ✓             | ✓             | guarded       | guarded       |
+| Buffer                                    | ✓        | ✓    | ✓             | ✓             | ✗             | ✗             | ✗             |
+| crypto.subtle                             | ✓        | ✓    | ✓             | ✓             | ✓             | ✓             | ✓             |
+| ReadableStream                            | ✓        | ✓    | ✓             | ✓             | ✓             | ✓             | ✓             |
+| URL pattern matching                      | ✓        | ✓    | ✓             | ✓             | ✓             | ✓             | ✓             |
+| Brotli decompression                      | ✓        | ✓    | ✗ passthrough | ✗ passthrough | ✗ passthrough | ✗ passthrough | ✗ passthrough |
+| Gzip/deflate decompression                | ✓        | ✓    | ✓             | ✓             | ✓             | ✓             | ✓             |
+
+\* HTTP/2+ detection is best-effort and internal. kinetex's own `detectHTTPVersion()` helper (not exported) reports HTTP/2 only when the runtime exposes protocol evidence — a response `httpVersion`/`protocol` property, or an `Alt-Svc` header — and otherwise reports `HTTP/1.1`. The version on every `KinetexResponse` comes from that heuristic, so it is not a guarantee. This is accurate for any runtime whose `fetch` does not negotiate h2 by default; use `NodeHTTP2Transport` (Node 22+) when you need guaranteed HTTP/2.
+
+¹ WSClient requires a native `WebSocket` constructor, which every supported Node.js version (22+) provides.
 
 ² Cloudflare Workers exposes a `WebSocket` constructor, but outbound client connections depend on runtime support.