partial-content 1.0.0

package/dist/web.js

@@ -0,0 +1,1094 @@
+/**
+ * Web / Fetch API adapter for partial-content.
+ *
+ * Composes a partial-content {@link ObjectStore} with the kernel's conditional
+ * request evaluation to produce a standards-compliant file-serving handler.
+ *
+ * Framework-agnostic: works with Next.js App Router, Hono, SvelteKit, Remix,
+ * Cloudflare Workers, Bun.serve, Deno.serve, or any runtime that uses the
+ * standard Request/Response API.
+ *
+ * Handles: 200 (full), 206 (partial), 304 (not modified), 412 (precondition
+ * failed), 416 (range not satisfiable), and HEAD (headers only).
+ *
+ * @example
+ * ```typescript
+ * import { serveObject } from "partial-content/web";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const store = s3Store({ client, bucket: "documents" });
+ *
+ * export const GET = serveObject(store, {
+ *   key: (req) => req.url.split("/").pop()!,
+ *   disposition: "inline",
+ * });
+ * export const HEAD = GET;
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { evaluateConditionalRequest, buildRangeResponseHeaders, buildContentDisposition, generateETag, clientWantsDigest, sanitizeHeaderValue, isRangeFresh, parseRanges, ObjectChangedError, build416Headers, buildMultipartHeaders, buildMultipartPartHeader, multipartEpilogue, generateMultipartBoundary, MAX_RANGES_DEFAULT, OPEN_ENDED, parseRetryAfterSeconds, } from "./index.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * One reusable UTF-8 encoder for the module (multipart part headers, plain-text
+ * error bodies), mirroring the kernel's hoisted encoder. `TextEncoder` is
+ * stateless, so a single instance is safe to share and avoids a per-response
+ * allocation.
+ */
+const UTF8_ENCODER = new TextEncoder();
+/** Reason phrases for HTTP statuses used by this adapter. */
+const STATUS_TEXT = {
+    200: "OK",
+    206: "Partial Content",
+    304: "Not Modified",
+    412: "Precondition Failed",
+    416: "Range Not Satisfiable",
+    499: "Client Closed Request",
+    502: "Bad Gateway",
+};
+export function serveObject(store, opts = {}) {
+    const raw = serveObjectRaw(store, opts);
+    return async function handleServe(req, ctx) {
+        const parts = await raw(req, ctx);
+        // BodyInit accepts both body forms; byte bodies take the runtime's
+        // static-body fast path (no stream machinery).
+        return new Response(parts.body, {
+            status: parts.status,
+            statusText: parts.statusText,
+            headers: parts.headers,
+        });
+    };
+}
+/**
+ * The engine behind serveObject, exposed for server adapters: identical
+ * protocol behavior, but the result is RawResponseParts instead of a
+ * Response. Use this when your server writes status/headers/body natively
+ * (the bundled node adapter does) -- constructing a Response + Headers pair
+ * per request just to immediately deconstruct them is measurable overhead
+ * on hot paths.
+ */
+export function serveObjectRaw(store, opts = {}) {
+    const { disposition: dispositionOpt = "attachment", cacheControl: rawCacheControl = "private, no-cache", immutable: immutableOpt = false, securityHeaders, crossOriginResourcePolicy, timingAllowOrigin, timing: timingEnabled = false, onTiming, fallbackFilename = "download", onError, onServe: rawOnServe, onTransfer: rawOnTransfer, maxRanges = MAX_RANGES_DEFAULT, enforceCharset = true, } = opts;
+    // A consumer's audit hook must never break the never-throw contract: the
+    // bodyless emissions (302/304/412/416/HEAD) fire outside any guard, so a
+    // throwing hook would escape the handler. Route hook failures to onError;
+    // the response itself is unaffected.
+    const onServe = rawOnServe
+        ? (event) => {
+            try {
+                rawOnServe(event);
+            }
+            catch (err) {
+                onError?.(err, { key: event.key, operation: "audit" });
+            }
+        }
+        : undefined;
+    // Same guard for the transfer hook, which fires from inside the body's
+    // stream machinery (during the runtime's consumption, after the handler has
+    // returned). A throw there would error the response stream mid-flight;
+    // route it to onError instead so the transfer completes cleanly.
+    const onTransfer = rawOnTransfer
+        ? (event) => {
+            try {
+                rawOnTransfer(event);
+            }
+            catch (err) {
+                onError?.(err, { key: event.key, operation: "audit" });
+            }
+        }
+        : undefined;
+    // Resolve Cache-Control once (append immutable if configured)
+    const cacheControl = immutableOpt && !rawCacheControl.includes("immutable")
+        ? `${rawCacheControl}, immutable`
+        : rawCacheControl;
+    return async function handleServeRaw(req, ctx) {
+        // Method validation: only GET and HEAD are valid for file serving.
+        // Other methods get 405 with Allow header per RFC 9110 Section 15.5.6.
+        const method = req.method;
+        if (method !== "GET" && method !== "HEAD") {
+            return {
+                status: 405,
+                statusText: "Method Not Allowed",
+                headers: {
+                    Allow: "GET, HEAD",
+                    "Content-Length": "0",
+                    "Cache-Control": "no-store",
+                    "Content-Security-Policy": "default-src 'none'",
+                    "X-Content-Type-Options": "nosniff",
+                },
+                body: null,
+            };
+        }
+        const { key } = ctx;
+        const isHead = method === "HEAD";
+        const mime = ctx.mime ?? "application/octet-stream";
+        // Resolve Content-Disposition
+        const dispositionType = typeof dispositionOpt === "function"
+            ? dispositionOpt(mime)
+            : dispositionOpt;
+        const disposition = ctx.filename
+            ? buildContentDisposition(ctx.filename, { type: dispositionType, fallback: fallbackFilename })
+            : dispositionType;
+        // Extra security headers for body responses
+        const extraHeaders = securityHeaders ? securityHeaders(mime) : {};
+        // Response-building context shared by all response paths
+        const rctx = {
+            mime, disposition, extraHeaders,
+            cacheControl: ctx.cacheControl ?? cacheControl,
+            crossOriginResourcePolicy, timingAllowOrigin, enforceCharset,
+            digestWanted: clientWantsDigest(req.headers),
+        };
+        // ── Signed-URL fallback for backends that cannot stream ranges ───────
+        if (store.supportsRange === false) {
+            if (store.createSignedUrl) {
+                const result = await store.createSignedUrl(key, {
+                    expiresInSeconds: 60,
+                    downloadFilename: ctx.filename,
+                });
+                if ("url" in result) {
+                    // A signed-URL redirect grants file access: audit it like a serve.
+                    onServe?.({ key, method: isHead ? "HEAD" : "GET", status: 302, mime, bytesServed: 0 });
+                    return {
+                        status: 302,
+                        statusText: "Found",
+                        headers: {
+                            // The signed URL is backend-derived: sanitize it like every
+                            // other metadata-sourced header so a malformed provider
+                            // response cannot inject a header or crash the writer.
+                            Location: sanitizeHeaderValue(result.url),
+                            "Cache-Control": "no-store, no-cache",
+                            "Accept-Ranges": "none",
+                            "Content-Length": "0",
+                        },
+                        body: null,
+                    };
+                }
+            }
+            return plainTextError(502, "Bad Gateway", "Storage backend does not support streaming");
+        }
+        // ── Detect request characteristics ──────────────────────────────────
+        const headers = req.headers;
+        const hasConditional = Boolean(headers.get("if-none-match") || headers.get("if-modified-since")
+            || headers.get("if-match") || headers.get("if-unmodified-since"));
+        const rangeHeader = headers.get("range");
+        const hasIfRange = Boolean(headers.get("if-range"));
+        // Multi-range (comma-separated) is served as multipart/byteranges. It
+        // always needs the HEAD-resolved total to clamp bounds and cannot use the
+        // single-range fast path.
+        const isMultiRange = !isHead && Boolean(rangeHeader && rangeHeader.includes(","));
+        // Range requests need HEAD to resolve: parseRangeHeader requires
+        // totalSize to clamp bounds and detect unsatisfiable ranges.
+        const needsHead = hasConditional || hasIfRange || isHead || Boolean(rangeHeader);
+        // ── Path B: plain range on an authoritative-range store ──────────────
+        // A range GET with no conditionals and no If-Range needs nothing from a
+        // HEAD: stores whose 206 bounds/total come from the backend's actual
+        // Content-Range can serve the seek in ONE round-trip (validators,
+        // bounds, and digest all come from the GET itself -- inherently
+        // TOCTOU-atomic). This halves latency on the hottest media path
+        // (video seeking, PDF.js chunked loading). Suffix ranges (`bytes=-N`)
+        // and anything the strict parser rejects fall through to Path A, whose
+        // HEAD-resolved evaluation handles them.
+        if (rangeHeader && !hasConditional && !hasIfRange && !isHead && store.authoritativeRange) {
+            const fastRange = parseFastRange(rangeHeader);
+            if (fastRange) {
+                let parts = null;
+                // Capture (don't report yet) the speculative failure. A 502 falls
+                // through to Path A, which re-runs and reports authoritatively --
+                // reporting here too would double-count. But a terminal 404/503 is
+                // served straight from Path B and never re-runs, so on the hottest
+                // path (every authoritative-range seek) those failures would be
+                // invisible to onError -- exactly the telemetry a monitoring
+                // consumer wires up. Capture here, report once below if terminal.
+                let speculativeErr;
+                try {
+                    parts = await streamFromStore({
+                        store, key, range: fastRange, ctx: rctx, signal: req.signal,
+                        onError: onError ? (err) => { speculativeErr = err; } : undefined,
+                        timingCtx: timingEnabled ? { storeMs: 0, evaluateMs: 0, onTiming } : undefined,
+                        auditCtx: onServe ? { onServe, mime } : undefined,
+                        // A speculative success IS the served response, so it must meter.
+                        // A failure returns 502 (no store body) and falls to Path A, which
+                        // meters the real transfer -- no double-fire.
+                        onTransfer,
+                    });
+                }
+                catch {
+                    // ObjectChangedError without a pin, or any other escape: fall
+                    // through to Path A, which reports and responds correctly.
+                }
+                // A 502 here usually means the backend rejected the range natively
+                // (e.g. start beyond EOF -> S3 InvalidRange). Path A's
+                // HEAD-resolved evaluation turns that into the correct 416 with
+                // real bounds (or surfaces the genuine store failure with full
+                // error reporting). The retry only ever costs an extra attempt on
+                // error paths.
+                if (parts && parts.status !== 502) {
+                    // Terminal outcome served from Path B (200/206 success, or a 404/503
+                    // that Path A would never revisit): surface a captured 404/503 error
+                    // exactly once so throttle/not-found storms stay visible to onError.
+                    if ((parts.status === 404 || parts.status === 503) && speculativeErr !== undefined) {
+                        onError?.(speculativeErr, { key, operation: "get" });
+                    }
+                    return parts;
+                }
+            }
+        }
+        // ── Path A: HEAD required ───────────────────────────────────────────
+        // The GET is pinned to the HEAD's raw ETag (GetObjectOptions.ifMatch),
+        // making the HEAD->GET pair atomic on backends with conditional reads.
+        // If the object changes in that window the store throws
+        // ObjectChangedError; re-validate ONCE against the new state so the
+        // client gets a coherent answer (e.g. a stale If-Range now correctly
+        // yields a full 200 of the new bytes) instead of an error.
+        for (let attempt = 0; needsHead; attempt++) {
+            let meta;
+            const t0 = timingEnabled ? performance.now() : 0;
+            try {
+                meta = await store.headObject(key, { signal: req.signal });
+            }
+            catch (err) {
+                if (isAbortError(err))
+                    return clientClosed();
+                onError?.(err, { key, operation: "head" });
+                return storeErrorResponse(err);
+            }
+            const storeMs = timingEnabled ? performance.now() - t0 : 0;
+            const etag = deriveETag(meta);
+            // RFC 7232/7233 full evaluation chain. Conditionals apply to HEAD
+            // exactly as to GET (RFC 9110 Section 13.1) -- a conditional HEAD must
+            // still yield 304/412. Range, however, is only defined for GET
+            // (RFC 9110 Section 14.2), so it is masked out for HEAD requests.
+            const evalHeaders = isHead ? withoutRangeHeaders(headers) : headers;
+            const t1 = timingEnabled ? performance.now() : 0;
+            let evaluation;
+            try {
+                evaluation = evaluateConditionalRequest(evalHeaders, {
+                    totalSize: meta.contentLength,
+                    contentType: mime,
+                    etag,
+                    lastModified: meta.lastModified,
+                    cacheControl: rctx.cacheControl,
+                    digest: meta.digest,
+                });
+            }
+            catch (err) {
+                // The kernel rejects corrupt store metadata (NaN/negative sizes)
+                // with a RangeError. That is an adapter bug, but a handler must
+                // always produce a Response -- an escaping throw becomes an
+                // unhandled rejection (and a process crash under Express 4).
+                onError?.(err, { key, operation: "head" });
+                return storeErrorResponse(err);
+            }
+            const evaluateMs = timingEnabled ? performance.now() - t1 : 0;
+            // Early exits: 412, 304, 416
+            if (evaluation.status === 304) {
+                onServe?.({ key, method: isHead ? "HEAD" : "GET", status: 304, mime, bytesServed: 0, etag });
+                return {
+                    status: 304,
+                    statusText: STATUS_TEXT[304],
+                    headers: evaluation.headers,
+                    body: null,
+                };
+            }
+            if (evaluation.status === 412) {
+                // Denials are audit events too: a 412 is an optimistic-concurrency
+                // conflict (failed If-Match), exactly what SOC 2 change-control
+                // trails want captured alongside grants.
+                onServe?.({ key, method: isHead ? "HEAD" : "GET", status: 412, mime, bytesServed: 0, etag });
+                return {
+                    status: 412,
+                    statusText: STATUS_TEXT[412],
+                    headers: {
+                        ...evaluation.headers,
+                        ...DENY_HEADERS,
+                    },
+                    body: null,
+                };
+            }
+            if (evaluation.status === 416) {
+                onServe?.({ key, method: "GET", status: 416, mime, bytesServed: 0, etag });
+                return {
+                    status: evaluation.status,
+                    statusText: "Range Not Satisfiable",
+                    headers: {
+                        ...evaluation.headers,
+                        ...DENY_HEADERS,
+                    },
+                    body: null,
+                };
+            }
+            // HEAD method: preconditions passed -- return headers only, no body
+            // (PDF.js size probing, cache priming).
+            if (isHead) {
+                onServe?.({ key, method: "HEAD", status: 200, mime, bytesServed: 0, etag });
+                return buildHeadResponse(meta, etag, rctx);
+            }
+            // Stream bytes from store, pinned to the representation just validated.
+            // Only STRONG validators pin: RFC 9110 Section 13.1.1 mandates strong
+            // comparison for If-Match, so a weak `W/` ETag would fail the
+            // precondition on every attempt (guaranteed 412 -> retry -> 502).
+            // Weak validators cannot assert byte equality anyway; the response-side
+            // guard still protects those reads.
+            const pinEtag = meta.etag && !meta.etag.startsWith("W/") ? meta.etag : undefined;
+            // ── Multi-range: serve multipart/byteranges ──────────────────────────
+            // evaluateConditionalRequest already settled 412/304 above (conditionals
+            // are range-independent) and, because parseRangeHeader rejects comma
+            // ranges, left this as a would-be 200. Honor the ranges here. A stale
+            // If-Range (validator moved) means ignore the Range -> fall through to
+            // the full 200 below; parseRanges returning null (amplification, or the
+            // ranges cover the whole file) does the same.
+            if (isMultiRange && isRangeFresh(headers, etag, meta.lastModified)) {
+                const set = parseRanges(rangeHeader, meta.contentLength, maxRanges);
+                if (set === "unsatisfiable") {
+                    onServe?.({ key, method: "GET", status: 416, mime, bytesServed: 0, etag });
+                    return {
+                        status: 416,
+                        statusText: "Range Not Satisfiable",
+                        headers: {
+                            ...build416Headers(meta.contentLength).headers,
+                            ...DENY_HEADERS,
+                        },
+                        body: null,
+                    };
+                }
+                if (set !== null) {
+                    try {
+                        if (set.ranges.length === 1) {
+                            // Overlapping ranges coalesced to one: a normal single 206.
+                            return await streamFromStore({
+                                store, key, range: set.ranges[0],
+                                ifMatch: pinEtag, pin: meta.pin,
+                                headEtag: etag, headLastModified: meta.lastModified,
+                                reprDigest: meta.digest, ctx: rctx, signal: req.signal, onError,
+                                timingCtx: timingEnabled ? { storeMs, evaluateMs, onTiming } : undefined,
+                                auditCtx: onServe ? { onServe, mime } : undefined,
+                                onTransfer,
+                            });
+                        }
+                        return await serveMultipart({
+                            store, key, ranges: set.ranges, totalSize: meta.contentLength,
+                            mime, etag, lastModified: meta.lastModified, digest: meta.digest,
+                            ifMatch: pinEtag, pin: meta.pin, ctx: rctx, signal: req.signal,
+                            onError, auditCtx: onServe ? { onServe, mime } : undefined, onTransfer,
+                        });
+                    }
+                    catch (err) {
+                        // A pinned first-part read lost its race: re-validate once, exactly
+                        // like single-range serving.
+                        if (isObjectChangedError(err) && attempt === 0)
+                            continue;
+                        onError?.(err, { key, operation: "get" });
+                        return storeErrorResponse(err);
+                    }
+                }
+                // set === null: serve the full 200 (fall through).
+            }
+            try {
+                return await streamFromStore({
+                    store, key, range: evaluation.range ?? undefined,
+                    ifMatch: pinEtag, pin: meta.pin,
+                    headEtag: etag, headLastModified: meta.lastModified,
+                    reprDigest: meta.digest, ctx: rctx, signal: req.signal, onError,
+                    timingCtx: timingEnabled ? { storeMs, evaluateMs, onTiming } : undefined,
+                    auditCtx: onServe ? { onServe, mime } : undefined,
+                    onTransfer,
+                });
+            }
+            catch (err) {
+                // Re-validate ONCE, and only for a pinned-read race. Any other error
+                // that escapes streamFromStore -- e.g. a corrupt-metadata RangeError
+                // rethrown from buildHeaders -- is deterministic, so a retry just wastes
+                // a HEAD+GET and drops the first failure from onError. Report it now.
+                // Mirrors the multipart catch above.
+                if (isObjectChangedError(err) && attempt === 0)
+                    continue;
+                onError?.(err, { key, operation: "get" });
+                return storeErrorResponse(err);
+            }
+        }
+        // ── Path C: No Range, no conditional headers ─────────────────────────
+        // Same never-throw contract as Path A: corrupt GET metadata (header
+        // builder RangeError), a throwing onServe hook, or a store throwing
+        // ObjectChangedError without a pin must become a 502, not a rejected
+        // handler (which crashes Express 4 processes).
+        try {
+            return await streamFromStore({
+                store, key, ctx: rctx, signal: req.signal, onError,
+                timingCtx: timingEnabled ? { storeMs: 0, evaluateMs: 0, onTiming } : undefined,
+                auditCtx: onServe ? { onServe, mime } : undefined,
+                onTransfer,
+            });
+        }
+        catch (err) {
+            onError?.(err, { key, operation: "get" });
+            return storeErrorResponse(err);
+        }
+    };
+}
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+/**
+ * Wrap a headers view so Range and If-Range read as absent.
+ *
+ * Used for HEAD requests: RFC 9110 Section 14.2 defines range handling only
+ * for GET, so the evaluation chain must not see the Range header (a 206 or
+ * 416 for HEAD would be wrong), while conditionals still apply.
+ */
+function withoutRangeHeaders(headers) {
+    return {
+        get(name) {
+            const lower = name.toLowerCase();
+            if (lower === "range" || lower === "if-range")
+                return null;
+            return headers.get(lower);
+        },
+    };
+}
+/**
+ * Parse a Range header for the single-round-trip fast path (no totalSize
+ * available yet). Accepts only `bytes=a-b` and `bytes=a-` (open end becomes
+ * MAX_SAFE_INTEGER; RFC 9110 Section 14.1.2 lets the server clamp a
+ * last-byte-pos past EOF, and authoritative-range backends do). Everything
+ * else -- suffix ranges, multi-range, malformed specs -- returns null so the
+ * validating HEAD path evaluates it with the real object size.
+ */
+function parseFastRange(header) {
+    const m = /^bytes=(\d+)-(\d*)$/.exec(header.trim());
+    if (!m)
+        return null;
+    const start = Number(m[1]);
+    if (!Number.isSafeInteger(start))
+        return null;
+    const end = m[2] ? Number(m[2]) : OPEN_ENDED;
+    if (!Number.isSafeInteger(end) || end < start)
+        return null;
+    return { start, end };
+}
+/** Derive an ETag from storage metadata using the kernel's formatter. */
+function deriveETag(meta) {
+    return generateETag({
+        hash: meta.etag,
+        size: meta.contentLength,
+        mtime: meta.lastModified,
+    });
+}
+/**
+ * Locked-down headers for bodyless denial responses (304 excepted, which
+ * carries only validators). A `default-src 'none'` CSP plus `nosniff` so a
+ * 412/416 body can never be sniffed or execute anything, and `no-store` so a
+ * transient denial is never cached (a 416 in particular advertises
+ * `Accept-Ranges: bytes` per RFC 7233 and must not linger in a shared cache).
+ * Spread onto the protocol headers the kernel produced for the status.
+ */
+const DENY_HEADERS = {
+    "Content-Security-Policy": "default-src 'none'",
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "no-store",
+};
+/**
+ * Append `; charset=utf-8` to a textual Content-Type when charset enforcement
+ * is on and none is present. Shared by the single-range/200 path and each
+ * multipart part so their Content-Type (and thus the precomputed
+ * Content-Length) is derived identically.
+ */
+function withCharset(mime, ctx) {
+    return ctx.enforceCharset && isTextualMime(mime) && !mime.includes("charset")
+        ? `${mime}; charset=utf-8`
+        : mime;
+}
+/**
+ * Layer the adapter's success-response header tail (Content-Disposition,
+ * nosniff, caller `extraHeaders`, CORP, TAO) onto a protocol header base.
+ * Shared by the single-range/200 and multipart paths so a future security
+ * header can never be added to one and silently forgotten on the other.
+ */
+function applyAdapterHeaders(base, ctx) {
+    const headers = {
+        ...base,
+        "Content-Disposition": ctx.disposition,
+        "X-Content-Type-Options": "nosniff",
+        ...ctx.extraHeaders,
+    };
+    if (ctx.crossOriginResourcePolicy)
+        headers["Cross-Origin-Resource-Policy"] = ctx.crossOriginResourcePolicy;
+    if (ctx.timingAllowOrigin)
+        headers["Timing-Allow-Origin"] = ctx.timingAllowOrigin;
+    return headers;
+}
+/**
+ * Build response headers by composing the kernel's protocol headers with
+ * adapter-specific extras.
+ */
+function buildHeaders(ctx, meta) {
+    const { headers: protocol } = buildRangeResponseHeaders({
+        totalSize: meta.totalSize,
+        range: meta.range ?? null,
+        contentType: withCharset(ctx.mime, ctx),
+        etag: meta.etag,
+        lastModified: meta.lastModified,
+        // RFC 9530 Section 4: respect Want-Repr-Digest negotiation. Weight 0 or
+        // an algorithm list without sha-256 means "do not send"; honoring that
+        // here keeps adapter responses consistent with the kernel orchestrator.
+        digest: ctx.digestWanted ? meta.digest : undefined,
+        cacheControl: ctx.cacheControl,
+    });
+    const headers = applyAdapterHeaders(protocol, ctx);
+    if (meta.serverTiming)
+        headers["Server-Timing"] = meta.serverTiming;
+    return headers;
+}
+/** Build a HEAD-only response (no body). */
+function buildHeadResponse(meta, etag, ctx) {
+    return {
+        status: 200,
+        statusText: "OK",
+        headers: buildHeaders(ctx, {
+            totalSize: meta.contentLength,
+            etag,
+            lastModified: meta.lastModified,
+            digest: meta.digest,
+        }),
+        body: null,
+    };
+}
+/**
+ * Stream bytes from the store, building a proper 200/206 response.
+ *
+ * Maps store failures to responses internally, with one exception:
+ * ObjectChangedError (a pinned read losing its race) is rethrown so the
+ * caller can re-validate against the object's new state.
+ */
+async function streamFromStore(opts) {
+    const { store, key, range, ifMatch, pin, headEtag, headLastModified, reprDigest, ctx, signal, onError, timingCtx, auditCtx, onTransfer, } = opts;
+    const t0 = timingCtx ? performance.now() : 0;
+    let result;
+    try {
+        result = await store.getObject(key, { range, signal, ifMatch, pin });
+    }
+    catch (err) {
+        if (isObjectChangedError(err))
+            throw err;
+        if (isAbortError(err))
+            return clientClosed();
+        onError?.(err, { key, operation: "get" });
+        return storeErrorResponse(err);
+    }
+    const getMs = timingCtx ? performance.now() - t0 : 0;
+    let serverTiming;
+    if (timingCtx) {
+        const totalMs = (timingCtx.storeMs + timingCtx.evaluateMs + getMs);
+        serverTiming = `store;dur=${(timingCtx.storeMs + getMs).toFixed(1)},eval;dur=${timingCtx.evaluateMs.toFixed(1)}`;
+        timingCtx.onTiming?.({
+            storeMs: timingCtx.storeMs + getMs,
+            evaluateMs: timingCtx.evaluateMs,
+            totalMs,
+        });
+    }
+    // Derive the response ETag from the GET result itself: strong from the
+    // backend hash when present, weak from size + mtime otherwise. This keeps
+    // validators consistent between Path A (HEAD-derived) and Path C (GET-only),
+    // so plain 200s from hash-less stores (fs) still carry a revalidator.
+    const finalEtag = generateETag({
+        hash: result.etag,
+        size: result.totalSize,
+        mtime: result.lastModified,
+    }) ?? headEtag;
+    const finalLastModified = result.lastModified ?? headLastModified;
+    const finalDigest = result.digest ?? reprDigest;
+    // TOCTOU guard: the range the backend ACTUALLY served is the source of
+    // truth for 206 vs 200 AND for the emitted byte bounds. If a range was
+    // requested but the GET result carries none, the store served full
+    // content: emit 200, never a lying 206. Incoherent bounds (a custom-store
+    // bug) cannot be trusted -- emitting them would corrupt client caches,
+    // so fail loudly instead.
+    const actualRange = range ? result.range ?? null : null;
+    if (actualRange && !isServableRange(actualRange, result.totalSize)) {
+        const err = new Error(`Store returned invalid served range for ${key}: ` +
+            `${actualRange.start}-${actualRange.end}/${result.totalSize}`);
+        onError?.(err, { key, operation: "get" });
+        // The body was never handed to a response: cancel a stream form or the
+        // backing resource (fs file handle, pooled HTTP socket) stays open
+        // until GC. Byte bodies hold nothing.
+        cancelBody(result.body);
+        return storeErrorResponse(err);
+    }
+    // Byte-count coherence: the emitted Content-Length is derived from the range
+    // span (206) or totalSize (200), but the body streams result.contentLength
+    // bytes. A store that reports a contentLength disagreeing with those would
+    // commit a Content-Length that over- or under-runs the body -- a truncated
+    // response the client cannot distinguish from a complete one. The multipart
+    // path enforces this per part (servedSpanMatches); the hotter single-range
+    // and 200 paths must guarantee it too. (A 200 with undefined totalSize is an
+    // adapter bug the header builder already rejects, so only the defined case
+    // is checked here.)
+    const incoherentByteCount = actualRange
+        ? result.contentLength !== actualRange.end - actualRange.start + 1
+        : result.totalSize !== undefined && result.contentLength !== result.totalSize;
+    if (incoherentByteCount) {
+        const err = new Error(`Store returned incoherent byte count for ${key}: contentLength=${result.contentLength} ` +
+            (actualRange ? `range=${actualRange.start}-${actualRange.end}` : `totalSize=${result.totalSize}`));
+        onError?.(err, { key, operation: "get" });
+        cancelBody(result.body);
+        return storeErrorResponse(err);
+    }
+    const isPartial = actualRange !== null;
+    const status = isPartial ? 206 : 200;
+    const responseRange = actualRange ?? undefined;
+    const totalSize = result.totalSize;
+    // Between here and the returned parts the body has an owner only on the
+    // happy path: a throw from the audit hook or header builder would
+    // otherwise leak a stream form.
+    try {
+        const headers = buildHeaders(ctx, {
+            totalSize,
+            range: responseRange,
+            etag: finalEtag,
+            lastModified: finalLastModified,
+            digest: finalDigest,
+            serverTiming,
+        });
+        // Audit AFTER the headers commit, never before. onServe is the "grant"
+        // event, so it must not fire for a response that never materializes: if
+        // buildHeaders throws on corrupt metadata this streamFromStore call is
+        // discarded (Path A re-runs, or a 502 is returned), and an onServe fired
+        // up front would double-count the retry or log a phantom grant on a 502.
+        if (auditCtx) {
+            // streamFromStore only runs for GET: HEAD returns early via
+            // buildHeadResponse, and Path C is unreachable when isHead forces needsHead.
+            auditCtx.onServe({
+                key, method: "GET", status: status, mime: auditCtx.mime,
+                bytesServed: result.contentLength, etag: finalEtag,
+                ...(responseRange ? { rangeStart: responseRange.start, rangeEnd: responseRange.end } : {}),
+            });
+        }
+        // Metering is opt-in: only wrap the body when a transfer hook is present,
+        // so the common path keeps the runtime's static-body fast path. The wrap
+        // happens AFTER buildHeaders and the audit hook, so the catch below still
+        // cancels the untouched original on any earlier throw (once wrapped, the
+        // source reader is locked and owned by the returned stream).
+        const body = onTransfer
+            ? meterBody(result.body, (bytesTransferred, completed) => onTransfer({
+                key,
+                method: "GET",
+                status: status,
+                bytesExpected: result.contentLength,
+                bytesTransferred,
+                completed,
+                ...(responseRange ? { rangeStart: responseRange.start, rangeEnd: responseRange.end } : {}),
+            }))
+            : result.body;
+        return {
+            status,
+            statusText: STATUS_TEXT[status],
+            headers,
+            body,
+        };
+    }
+    catch (err) {
+        cancelBody(result.body);
+        throw err;
+    }
+}
+/**
+ * Serve multiple byte ranges as a `multipart/byteranges` (206) response.
+ *
+ * The Content-Length is computed exactly by the kernel from the framing and
+ * the range spans, so the response is never chunked. The first part is fetched
+ * EAGERLY so a pinned-read `ObjectChangedError` surfaces before headers commit
+ * (giving the caller the same one-shot re-validation single-range serving
+ * gets); the remaining parts stream lazily, one `getObject` per range, each
+ * pinned to the same representation via `ifMatch`.
+ *
+ * Relies on each store serving exactly the requested (already size-clamped)
+ * span per range -- which every bundled adapter does -- so the precomputed
+ * Content-Length matches the streamed body byte-for-byte.
+ */
+async function serveMultipart(opts) {
+    const { store, key, ranges, totalSize, mime, etag, lastModified, digest, ifMatch, pin, ctx, signal, onError, auditCtx, onTransfer, } = opts;
+    const boundary = generateMultipartBoundary();
+    // Each part carries the representation's own Content-Type; apply the same
+    // charset enforcement single-range responses use so the value (and thus the
+    // precomputed Content-Length) is identical to what the framing emits.
+    const partContentType = withCharset(mime, ctx);
+    // Fetch the first part up front: a pinned read losing its race throws
+    // ObjectChangedError HERE, before any headers are committed, so the caller
+    // can re-validate once. Abort and store errors map to responses.
+    let firstStream;
+    try {
+        firstStream = await store.getObject(key, { range: ranges[0], signal, ifMatch, pin });
+    }
+    catch (err) {
+        if (isObjectChangedError(err))
+            throw err;
+        if (isAbortError(err))
+            return clientClosed();
+        onError?.(err, { key, operation: "get" });
+        return storeErrorResponse(err);
+    }
+    // Validate the first part's served span BEFORE headers commit. On a
+    // non-pinning store (one that cannot honor ifMatch/pin), a concurrent
+    // overwrite between parts would otherwise splice bytes across
+    // representations or under-run the precomputed Content-Length. A first-part
+    // mismatch re-validates once via the orchestrator's retry loop.
+    if (!servedSpanMatches(firstStream, ranges[0])) {
+        cancelBody(firstStream.body);
+        throw new ObjectChangedError(key);
+    }
+    const multipart = buildMultipartHeaders({
+        boundary, ranges, totalSize, contentType: partContentType,
+        etag, lastModified, digest, cacheControl: ctx.cacheControl,
+    });
+    // Ownership of the eagerly-fetched first part transfers to the generator the
+    // moment it takes the part's reader (or yields its bytes). Until then, a
+    // consumer cancel would strand firstStream: gen.return() only runs the
+    // reader's finally if control already entered the try. Track the handoff so
+    // the outer cancel can release it in the pre-handoff window (suspendedStart,
+    // or suspended at the part-header yield).
+    let firstPartOwned = false;
+    const enc = UTF8_ENCODER;
+    async function* multipartChunks() {
+        for (let i = 0; i < ranges.length; i++) {
+            const range = ranges[i];
+            yield enc.encode(buildMultipartPartHeader(boundary, range, totalSize, partContentType));
+            const stream = i === 0
+                ? firstStream
+                : await store.getObject(key, { range, signal, ifMatch, pin });
+            // Lazy parts settle AFTER headers commit, so a mismatch can only be
+            // surfaced as a stream error (a reset). That still beats splicing bytes
+            // from a changed representation or under-running the committed length.
+            // The span check alone would miss a SAME-SIZE overwrite (right byte count,
+            // different bytes); comparing each part's validator against the first
+            // catches that too, since any overwrite changes the fs weak ETag (mtime)
+            // and the S3 strong ETag (content hash). Stores that return no GET
+            // validator fall back to the span check.
+            if (i > 0 && (!servedSpanMatches(stream, range) || !sameRepresentation(firstStream, stream))) {
+                cancelBody(stream.body);
+                throw new ObjectChangedError(key);
+            }
+            const body = stream.body;
+            // Handoff point: cleanup is now guaranteed by the reader's finally below
+            // (stream body) or is unneeded (byte body holds no resource). No await or
+            // yield sits between here and getReader(), so a cancel cannot interleave.
+            if (i === 0)
+                firstPartOwned = true;
+            if (body instanceof Uint8Array) {
+                yield body;
+            }
+            else {
+                const reader = body.getReader();
+                try {
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        yield value;
+                    }
+                }
+                finally {
+                    // Release the backend resource on normal completion AND on an early
+                    // generator return (client cancelled mid-part).
+                    reader.cancel().catch(() => { });
+                }
+            }
+            yield enc.encode("\r\n");
+        }
+        yield enc.encode(multipartEpilogue(boundary));
+    }
+    const gen = multipartChunks();
+    const rawBody = new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await gen.next();
+                if (done)
+                    controller.close();
+                // Part headers (encoder output) and part bodies are ArrayBuffer-backed;
+                // narrow so the multipart body stays Response-assignable under DOM (F5).
+                else
+                    controller.enqueue(value);
+            }
+            catch (err) {
+                controller.error(err);
+            }
+        },
+        async cancel(reason) {
+            await gen.return?.(reason);
+            // Cancelled before the generator took ownership of the eagerly-fetched
+            // first part (suspendedStart, or suspended at the part-header yield):
+            // gen.return ran no finally, so release it here. A byte-body first part
+            // is a no-op in cancelBody; a stream part's file handle/socket is freed.
+            if (!firstPartOwned)
+                cancelBody(firstStream.body);
+        },
+    });
+    const headers = applyAdapterHeaders(multipart.headers, ctx);
+    // Audit reports the multipart body's granted length (framing + all parts).
+    auditCtx?.onServe({
+        key, method: "GET", status: 206, mime: auditCtx.mime,
+        bytesServed: multipart.contentLength, etag,
+    });
+    const body = onTransfer
+        ? meterBody(rawBody, (bytesTransferred, completed) => onTransfer({
+            key, method: "GET", status: 206,
+            bytesExpected: multipart.contentLength, bytesTransferred, completed,
+        }))
+        : rawBody;
+    return { status: 206, statusText: STATUS_TEXT[206], headers, body };
+}
+/**
+ * Wrap a response body in a counting stream that reports the true bytes
+ * transferred exactly once when the body reaches its terminal state.
+ *
+ * `report(bytesTransferred, completed)` fires on:
+ *   - full drain (`completed: true`) -- the consumer read every byte,
+ *   - cancel / client disconnect (`completed: false`) -- fewer bytes reached
+ *     the client than the Content-Length promised,
+ *   - source error (`completed: false`) -- a mid-transfer backend failure.
+ *
+ * A byte body is wrapped into a one-shot stream so metering is uniform across
+ * stream and byte stores (the caller only pays this when a transfer hook is
+ * registered; unmetered byte bodies keep the static-body fast path). The
+ * `settled` latch guarantees the report fires once even if the consumer
+ * cancels after the stream already closed.
+ */
+function meterBody(source, report) {
+    let transferred = 0;
+    let settled = false;
+    const settle = (completed) => {
+        if (settled)
+            return;
+        settled = true;
+        report(transferred, completed);
+    };
+    // Normalize a byte body to a one-shot stream and meter it through the SAME
+    // reader path, so `completed:true` fires only when the consumer has pulled
+    // the terminal (done) result -- i.e. after it read the last chunk -- never
+    // merely because the chunk was buffered ahead of a read. A dedicated
+    // byte-path that settled inside its enqueue would over-report a disconnect
+    // that lands after the chunk was queued but before it was consumed.
+    const stream = source instanceof Uint8Array
+        ? new ReadableStream({
+            start(controller) {
+                if (source.byteLength > 0)
+                    controller.enqueue(source);
+                controller.close();
+            },
+        })
+        : source;
+    const reader = stream.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            let res;
+            try {
+                res = await reader.read();
+            }
+            catch (err) {
+                settle(false);
+                controller.error(err);
+                return;
+            }
+            if (res.done) {
+                settle(true);
+                controller.close();
+            }
+            else {
+                transferred += res.value.byteLength;
+                // Backend byte chunks are ArrayBuffer-backed; narrow so the metered
+                // body stays `new Response(...)`-assignable under DOM lib (F5).
+                controller.enqueue(res.value);
+            }
+        },
+        async cancel(reason) {
+            settle(false);
+            await reader.cancel(reason);
+        },
+    });
+}
+/**
+ * True when a store served EXACTLY the requested span: same inclusive bounds
+ * and matching byte count. A mismatch means the object changed under a
+ * non-pinning store (or the store's accounting is broken), so the committed
+ * multipart framing and Content-Length no longer describe the bytes.
+ */
+function servedSpanMatches(stream, range) {
+    const served = stream.range;
+    return !!served
+        && served.start === range.start
+        && served.end === range.end
+        && stream.contentLength === range.end - range.start + 1;
+}
+/**
+ * True when two parts of a multipart response came from the same
+ * representation, judged by the strongest validator both expose. Any overwrite
+ * changes the fs weak ETag (mtime) and the S3 strong ETag (content hash), so an
+ * ETag disagreement means the object changed mid-stream. When a store returns
+ * no GET ETag (or no Last-Modified) on one side, there is nothing to compare
+ * and the caller's span check is the only guard -- so this returns `true` and
+ * does not manufacture a mismatch from missing metadata.
+ */
+function sameRepresentation(a, b) {
+    if (a.etag && b.etag)
+        return a.etag === b.etag;
+    if (a.lastModified && b.lastModified)
+        return a.lastModified === b.lastModified;
+    return true;
+}
+/** Release a body that will never reach a response (stream forms only). */
+function cancelBody(body) {
+    if (!(body instanceof ReadableStream))
+        return;
+    try {
+        // A locked stream (a reader was taken) throws SYNCHRONOUSLY here rather
+        // than rejecting, so .catch alone would let it escape; an already-errored
+        // stream rejects. Swallow both -- teardown is best-effort by definition.
+        body.cancel().catch(() => { });
+    }
+    catch { /* locked: the reader owns teardown */ }
+}
+/** Bodyless 499 parts, built per return (headers object is caller-owned). */
+function clientClosed() {
+    return {
+        status: 499,
+        statusText: "Client Closed Request",
+        headers: { "Content-Length": "0" },
+        body: null,
+    };
+}
+// ─── Error Helpers ──────────────────────────────────────────────────────────
+/**
+ * Validate a store-reported served range against the representation size:
+ * inclusive integer bounds, ordered, and inside the object. Anything else
+ * means the store's byte accounting is broken.
+ *
+ * When `totalSize` is `undefined` the backend served an unknown-total partial
+ * (`bytes a-b/*`): there is no EOF to bound-check against, so the ordered
+ * bounds the authoritative backend reported are trusted as-is.
+ */
+function isServableRange(r, totalSize) {
+    if (!Number.isSafeInteger(r.start) || !Number.isSafeInteger(r.end))
+        return false;
+    if (r.start < 0 || r.start > r.end)
+        return false;
+    if (totalSize === undefined)
+        return true;
+    return Number.isSafeInteger(totalSize) && r.end < totalSize;
+}
+/**
+ * Check if an error is an AbortError (client disconnected).
+ * Works across runtimes: DOMException in browsers/Workers, AbortError in Node.
+ */
+function isAbortError(err) {
+    if (err instanceof DOMException && err.name === "AbortError")
+        return true;
+    if (err instanceof Error && err.name === "AbortError")
+        return true;
+    return false;
+}
+/**
+ * Check if an error is a pinned-read ObjectChangedError.
+ *
+ * Matched by name rather than instanceof so third-party stores can throw
+ * their own equivalently-named error without importing the kernel class.
+ */
+function isObjectChangedError(err) {
+    return err instanceof Error && err.name === "ObjectChangedError";
+}
+/**
+ * Build a plain-text error response with a computed Content-Length.
+ *
+ * The body is encoded once and Content-Length comes from the encoded byte
+ * count, so the header stays truthful even if a message ever gains
+ * non-ASCII characters (String.length counts UTF-16 units, not bytes).
+ */
+function plainTextError(status, statusText, body, extraHeaders) {
+    const bytes = UTF8_ENCODER.encode(body);
+    return {
+        status,
+        statusText,
+        headers: {
+            "Content-Type": "text/plain; charset=utf-8",
+            "Content-Length": String(bytes.byteLength),
+            "Accept-Ranges": "none",
+            // 404 is heuristically cacheable (RFC 9111 Section 4.2.2): without
+            // this, a CDN can cache a transient miss and keep serving it after
+            // the object appears. Errors must never outlive their cause.
+            "Cache-Control": "no-store",
+            "X-Content-Type-Options": "nosniff",
+            "Content-Security-Policy": "default-src 'none'",
+            ...extraHeaders,
+        },
+        body: bytes,
+    };
+}
+/**
+ * Build an error response for store failures.
+ *
+ * Discriminates three cases: "object not found" (404), "backend transiently
+ * unavailable" (503, retryable), and everything else (502, the upstream
+ * returned something invalid). A 404 hint comes from a `status` of 404 or an
+ * error named `ObjectNotFoundError`/`NotFound`; a 503 hint from a `status` of
+ * 503 or an error named `StoreUnavailableError`, which additionally carries an
+ * optional `retryAfterSeconds` echoed as `Retry-After`.
+ */
+function storeErrorResponse(err) {
+    if (isNotFoundStoreError(err)) {
+        return plainTextError(404, "Not Found", "Not Found");
+    }
+    if (isUnavailableStoreError(err)) {
+        const secs = retryAfterSeconds(err);
+        return plainTextError(503, "Service Unavailable", "Storage backend unavailable", secs !== undefined ? { "Retry-After": String(secs) } : undefined);
+    }
+    return plainTextError(502, "Bad Gateway", "Storage backend error");
+}
+/**
+ * Check if a store error represents a missing object (404).
+ */
+function isNotFoundStoreError(err) {
+    if (typeof err === "object" && err !== null && "status" in err) {
+        return err.status === 404;
+    }
+    if (err instanceof Error) {
+        return err.name === "ObjectNotFoundError" || err.name === "NotFound";
+    }
+    return false;
+}
+/**
+ * Check if a store error signals a transient, retryable backend condition
+ * (throttling/overload/timeout). Matched by `status` 503 or by name so a
+ * third-party store can throw an equivalently-named error without importing
+ * the kernel class.
+ */
+function isUnavailableStoreError(err) {
+    if (typeof err === "object" && err !== null && "status" in err) {
+        if (err.status === 503)
+            return true;
+    }
+    return err instanceof Error && err.name === "StoreUnavailableError";
+}
+/**
+ * Extract a non-negative integer `Retry-After` (delay-seconds, RFC 9110
+ * Section 10.2.3) from a store error's `retryAfterSeconds`, or `undefined`
+ * when absent or malformed. Delegates to the shared parser: fractional hints
+ * are floored, 0 is kept, and a huge finite hint that would serialize as
+ * `1e+21` (a duck-typed third-party error that skipped the StoreUnavailableError
+ * constructor's normalization) is rejected rather than emitted as a malformed
+ * header.
+ */
+function retryAfterSeconds(err) {
+    if (typeof err !== "object" || err === null || !("retryAfterSeconds" in err))
+        return undefined;
+    return parseRetryAfterSeconds(err.retryAfterSeconds);
+}
+/**
+ * Check if a MIME type is textual and should have charset=utf-8 enforced.
+ */
+function isTextualMime(mime) {
+    if (mime.startsWith("text/"))
+        return true;
+    if (mime === "application/json" || mime === "application/xml")
+        return true;
+    if (mime.endsWith("+json") || mime.endsWith("+xml"))
+        return true;
+    if (mime === "application/javascript" || mime === "application/ecmascript")
+        return true;
+    return false;
+}
+//# sourceMappingURL=web.js.map