@plurnk/plurnk-schemes-http 2.0.5 → 2.0.6

package/dist/Http.js

@@ -1,142 +1,13 @@
-// HTTP(S) handler. Operation-to-method semantics live in {§op-surface};
+// HTTP(S) handler. Operation-to-method semantics live in {§http-manifest};
 // acquisition, materialization, publication, and query flow live in
-// {§http-lifecycle}. The implementation depends only on SchemeCtx capabilities.
+// {§http-lifecycle} and {§http-status}. The implementation depends only on SchemeCtx capabilities.
 import { Validator } from "@plurnk/plurnk-contracts";
-import { createParser } from "eventsource-parser";
-import { MetadataOptions, MimetypeClassifier, NetworkAddress, ProjectionInputLimitError, Results } from "@plurnk/plurnk-schemes";
+import { MetadataOptions, NetworkAddress } from "@plurnk/plurnk-schemes";
 import { readFile } from "node:fs/promises";
-import ErrorDetail from "./ErrorDetail.js";
-import WebFetcher, { CACHE_VARIANT_HEADER, MATERIALIZER_ID_HEADER, PROJECTION_ID_HEADER, cacheVariantEvidence, classifyCacheVariant } from "./WebFetcher.js";
-import { responseMimetype } from "./ContentType.js";
-import { requireNonNegativeIntegerEnv as requireNumEnv } from "./Config.js";
-import { BODY, FETCHED_AT, HEADER, REQUEST_METHOD } from "./http-names.js";
 import HttpGet from "./HttpGet.js";
 import HttpRequester from "./HttpRequester.js";
-import LiveAcquisitions from "./LiveAcquisitions.js";
-import HostPolicy from "./HostPolicy.js";
-// The channel the response body streams into, and the header metadata channel.
-// Package-owned metadata appended after untrusted origin headers. Readers take
-// the last value so an origin using the same field name cannot override it.
-// {§http-outbound-proposes} — the only methods this scheme proposes, and so the only ones a
-// settlement may perform.
-const OUTBOUND_METHODS = new Set(["POST", "PUT", "DELETE"]);
-const DELTA_SECONDS_LIMIT = 2147483648n;
-const HEURISTIC_CACHE_STATUSES = new Set([200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501]);
-const BODY_PROCESSING_FIELDS = new Set([
-    "content-encoding",
-    "content-length",
-    "content-range",
-    "content-type",
-]);
-const splitHttpList = (value) => {
-    const members = [];
-    let start = 0;
-    let quoted = false;
-    let escaped = false;
-    for (let index = 0; index < value.length; index += 1) {
-        const character = value[index];
-        if (quoted) {
-            if (escaped)
-                escaped = false;
-            else if (character === "\\")
-                escaped = true;
-            else if (character === '"')
-                quoted = false;
-        }
-        else if (character === '"') {
-            quoted = true;
-        }
-        else if (character === ",") {
-            members.push(value.slice(start, index).trim());
-            start = index + 1;
-        }
-    }
-    members.push(value.slice(start).trim());
-    return members.filter((member) => member.length > 0);
-};
-const cacheDirective = (member) => {
-    const equals = member.indexOf("=");
-    const name = member.slice(0, equals < 0 ? undefined : equals).trim().toLowerCase();
-    if (!/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name))
-        return null;
-    if (equals < 0)
-        return { name };
-    return { name, argument: member.slice(equals + 1).trim() };
-};
-const deltaMilliseconds = (argument) => {
-    if (argument === undefined)
-        return null;
-    const match = /^(?:([0-9]+)|"([0-9]+)")$/.exec(argument);
-    const digits = match?.[1] ?? match?.[2];
-    if (digits === undefined)
-        return null;
-    const seconds = BigInt(digits);
-    return Number(seconds > DELTA_SECONDS_LIMIT ? DELTA_SECONDS_LIMIT : seconds) * 1000;
-};
-const lastHeaderValue = (header, name) => {
-    const lines = header.split(/\r?\n/);
-    for (let index = lines.length - 1; index >= 0; index -= 1) {
-        const line = lines[index];
-        const colon = line.indexOf(":");
-        if (colon < 0 || line.slice(0, colon).trim().toLowerCase() !== name)
-            continue;
-        return line.slice(colon + 1).trim();
-    }
-    return undefined;
-};
-const entityTag = (value) => {
-    const match = /^(W\/)?"([\x21\x23-\x7e\x80-\xff]*)"$/.exec(value);
-    return match === null
-        ? null
-        : { weak: match[1] !== undefined, opaque: match[2] };
-};
-const MONTHS = [
-    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
-    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
-];
-const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
-const IMF_FIXDATE = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat), ([0-9]{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) ([0-9]{4}) ([0-9]{2}):([0-9]{2}):([0-9]{2}) GMT$/;
-const RFC850_DATE = /^(Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday), ([0-9]{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-([0-9]{2}) ([0-9]{2}):([0-9]{2}):([0-9]{2}) GMT$/;
-const ASCTIME_DATE = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (?: ([0-9])|([0-9]{2})) ([0-9]{2}):([0-9]{2}):([0-9]{2}) ([0-9]{4})$/;
-const utcHttpDate = (weekday, day, month, year, hour, minute, second) => {
-    const monthIndex = MONTHS.indexOf(month);
-    const weekdayIndex = WEEKDAYS.indexOf(weekday.slice(0, 3));
-    const numericDay = Number(day);
-    const numericHour = Number(hour);
-    const numericMinute = Number(minute);
-    const numericSecond = Number(second);
-    if (monthIndex < 0 || weekdayIndex < 0)
-        return null;
-    const date = new Date(0);
-    date.setUTCFullYear(year, monthIndex, numericDay);
-    date.setUTCHours(numericHour, numericMinute, numericSecond, 0);
-    return date.getUTCFullYear() === year
-        && date.getUTCMonth() === monthIndex
-        && date.getUTCDate() === numericDay
-        && date.getUTCHours() === numericHour
-        && date.getUTCMinutes() === numericMinute
-        && date.getUTCSeconds() === numericSecond
-        && date.getUTCDay() === weekdayIndex
-        ? date.getTime()
-        : null;
-};
-const httpDate = (value, now = Date.now()) => {
-    const preferred = IMF_FIXDATE.exec(value);
-    if (preferred !== null) {
-        return utcHttpDate(preferred[1], preferred[2], preferred[3], Number(preferred[4]), preferred[5], preferred[6], preferred[7]);
-    }
-    const rfc850 = RFC850_DATE.exec(value);
-    if (rfc850 !== null) {
-        let year = 2000 + Number(rfc850[4]);
-        if (year > new Date(now).getUTCFullYear() + 50)
-            year -= 100;
-        return utcHttpDate(rfc850[1], rfc850[2], rfc850[3], year, rfc850[5], rfc850[6], rfc850[7]);
-    }
-    const asctime = ASCTIME_DATE.exec(value);
-    return asctime === null
-        ? null
-        : utcHttpDate(asctime[1], asctime[3] ?? asctime[4], asctime[2], Number(asctime[8]), asctime[5], asctime[6], asctime[7]);
-};
+import { BODY, HTTP_CHANNELS, LiveAcquisitions, OUTBOUND_METHODS, httpAddress, httpBad, httpPassthrough, } from "./HttpShared.js";
+import WebFetcher from "./WebFetcher.js";
 // The package-shipped model teaching is loaded verbatim and fails hard if absent.
 // The relative path is identical from src/ during development and dist/ after build.
 const documentation = await readFile(new URL("../docs/https.md", import.meta.url), "utf-8");
@@ -151,9 +22,9 @@ export default class Http {
         // body is retyped per-call to the real response Content-Type;
         // octet-stream is the honest "unknown until fetched". header is always the status
         // line + headers (text/plain).
-        // {§readable-channel} — body is the response as served (a page's server source); readable
+        // {§channel-selection} — body is the response as served (a page's server source); readable
         // is curated Markdown or binary facts; header is transport evidence.
-        channels: { [BODY]: "application/octet-stream", [HEADER]: "text/plain", readable: "text/markdown" },
+        channels: { ...HTTP_CHANNELS },
         defaultChannel: BODY,
         category: "data",
         writableBy: ["model", "client"],
@@ -165,9 +36,9 @@ export default class Http {
         traits: ["web"],
     };
     #webFetcher;
-    // {§web-materialization-contract}: published for the entry sink; reached through the registry.
+    // {§scheme-operation-dispatch}: published for the entry sink; reached through the registry.
     webMaterializer;
-    // {§http-llms-txt} — one opportunistic origin-companion attempt per TTL
+    // {§http-lifecycle} — one opportunistic origin-companion attempt per TTL
     // window; success and failure share the timer so a 404 does not re-probe
     // on every READ.
     #get;
@@ -176,8 +47,8 @@ export default class Http {
     constructor() {
         this.#webFetcher = new WebFetcher();
         this.webMaterializer = this.#webFetcher;
-        this.#get = new HttpGet({ live: this.#live, webFetcher: this.#webFetcher, address: Http.#address, requestHeaders: Http.#requestHeaders, passthrough: Http.#passthrough, requestMethod: Http.#requestMethod, reusableGetRepresentation: Http.#reusableGetRepresentation, materializerIdentity: Http.#materializerIdentity, validators: Http.#validators, materializationFailure: Http.#materializationFailure, sourceMimetype: Http.#sourceMimetype, fresh: Http.#fresh, cancelled: Http.#cancelled, bad: Http.#bad, revalidationCorresponds: Http.#revalidationCorresponds, refreshAfter304: Http.#refreshAfter304, seedEntry: Http.#seedEntry, settleEventStream: Http.#settleEventStream });
-        this.#requester = new HttpRequester({ live: this.#live, manifest: Http.manifest, address: Http.#address, requestHeaders: Http.#requestHeaders, bad: Http.#bad, seedEntry: Http.#seedEntry, passthrough: Http.#passthrough, responseHeader: Http.#responseHeader, writeProjectionIdentity: Http.#writeProjectionIdentity, cancelled: Http.#cancelled, materializationFailure: Http.#materializationFailure });
+        this.#get = new HttpGet({ live: this.#live, webFetcher: this.#webFetcher });
+        this.#requester = new HttpRequester({ live: this.#live, manifest: Http.manifest });
     }
     async ready() {
         WebFetcher.validateConfiguration();
@@ -187,7 +58,7 @@ export default class Http {
     // returned 102 for a retained SSE response.
     async prepareRepresentation(request, ctx) {
         if (request.target.kind !== "url") {
-            return Http.#bad(400, "http", "bad-target", "READ requires an http(s):// URL target.", {
+            return httpBad(400, "http", "bad-target", "READ requires an http(s):// URL target.", {
                 stage: "target-validation",
                 recovery: "Provide an http(s):// URL target.",
                 retryable: false,
@@ -199,7 +70,7 @@ export default class Http {
     // remote resource - reject rather than silently ignore the model's intent.
     async editBatch(statements, _ctx) {
         if (statements.length !== 1) {
-            return Http.#bad(409, "http", "non-atomic-edit-batch", `${statements.length} EDIT statements cannot be committed atomically to one remote resource.`, {
+            return httpBad(409, "http", "non-atomic-edit-batch", `${statements.length} EDIT statements cannot be committed atomically to one remote resource.`, {
                 statements: statements.length,
                 stage: "mutation",
                 recovery: "Submit one whole-resource EDIT.",
@@ -208,14 +79,14 @@ export default class Http {
         }
         const statement = statements[0];
         if (statement.target === null || statement.target.kind !== "url") {
-            return Http.#bad(400, "http", "bad-target", "EDIT requires an http(s):// URL target.", {
+            return httpBad(400, "http", "bad-target", "EDIT requires an http(s):// URL target.", {
                 stage: "target-validation",
                 recovery: "Provide an http(s):// URL target.",
                 retryable: false,
             });
         }
         if (statement.lineMarker !== null) {
-            return Http.#bad(400, "http", "line-edit-unsupported", "HTTP EDIT replaces the whole remote resource and does not accept a line range.", {
+            return httpBad(400, "http", "line-edit-unsupported", "HTTP EDIT replaces the whole remote resource and does not accept a line range.", {
                 stage: "mutation",
                 recovery: "Remove the line range and submit the complete replacement body.",
                 retryable: false,
@@ -226,12 +97,12 @@ export default class Http {
     async edit(statement, ctx) {
         return this.editBatch([statement], ctx);
     }
-    // {§http-kill} — KILL follows the entry rule: a live acquisition of the address is
+    // {§revalidation} — KILL follows the entry rule: a live acquisition of the address is
     // cancelled, otherwise the stored response is forgotten. The remote DELETE is its own
     // spelling, `KILL (https://…) [{"remote": true}]`; any other metadata keys are its headers.
     async kill(statement, ctx) {
         if (statement.target === null || statement.target.kind !== "url") {
-            return Http.#bad(400, "http", "bad-target", "KILL requires an http(s):// URL target.", {
+            return httpBad(400, "http", "bad-target", "KILL requires an http(s):// URL target.", {
                 stage: "target-validation",
                 recovery: "Provide an http(s):// URL target.",
                 retryable: false,
@@ -244,16 +115,16 @@ export default class Http {
         // The `remote` spelling is stripped in applyResolution, where the request is actually made.
         if (read.options.remote === true)
             return Http.#propose("DELETE", statement.target);
-        const address = Http.#address(statement.target);
+        const address = httpAddress(statement.target);
         if (!(address instanceof NetworkAddress))
             return address;
         if (this.#live.cancel(LiveAcquisitions.key(ctx.workspaceId, address.url))) {
             // The owner settles itself as cancelled through its aborted signal.
             return { shape: "passthrough", status: 200 };
         }
-        return Http.#passthrough(await ctx.entries.delete(address.pathname));
+        return httpPassthrough(await ctx.entries.delete(address.pathname));
     }
-    // {§http-outbound-proposes} — a request that changes a remote resource declares the host
+    // {§http-manifest} — a request that changes a remote resource declares the host
     // effect and proposes; `PLURNK_SERVICE_EFFECT_HOST` decides whether that settles by consent
     // or runs unattended. The headers stay OUT of attrs: they ride the statement metadata across
     // the pause, so an `Authorization` value never enters durable proposal evidence.
@@ -291,10 +162,10 @@ export default class Http {
         }
         return this.#requester.request(url, metadata, ctx, method, body);
     }
-    // {§turn-disposition} — SEND is messaging; lifecycle operations never reach a scheme.
+    // {§op-shapes} — SEND is messaging; lifecycle operations never reach a scheme.
     async send(statement, _ctx) {
         if (statement.target === null || statement.target.kind !== "url") {
-            return Http.#bad(400, "http", "bad-target", "SEND requires an http(s):// URL target.", {
+            return httpBad(400, "http", "bad-target", "SEND requires an http(s):// URL target.", {
                 stage: "target-validation",
                 recovery: "Provide an http(s):// URL target.",
                 retryable: false,
@@ -302,473 +173,5 @@ export default class Http {
         }
         return Http.#propose("POST", statement.target, statement.body?.raw ?? "");
     }
-    // {§http-manifest}/{§http-lifecycle} Seed the declared channel shape before
-    // open(); notifyChunk later welds acquired content to its actual mimetype.
-    static #seedEntry() {
-        const channels = Object.fromEntries(Object.entries(Http.manifest.channels).map(([name, mimetype]) => [name, {
-                content: "",
-                mimetype,
-                state: "active",
-            }]));
-        return { channels };
-    }
-    // {§revalidation} The body and header must have settled successfully. An
-    // auxiliary channel may have terminally failed without invalidating body.
-    static #representationComplete(entry) {
-        const bodyState = entry.channels[BODY]?.state;
-        const headerState = entry.channels[HEADER]?.state;
-        const successful = (state) => state === "static" || state === "closed";
-        const terminal = (state) => successful(state) || state === "errored";
-        return successful(bodyState)
-            && successful(headerState)
-            && Object.values(entry.channels).every(({ state }) => terminal(state));
-    }
-    // {§revalidation} Direct READ and exact FIND share the complete reusable
-    // representation predicate; freshness only decides how READ uses a match.
-    static async #reusableGetRepresentation(entry, requestHeaders, projection) {
-        const body = entry.channels[BODY];
-        const header = entry.channels[HEADER];
-        if (body === undefined || header === undefined)
-            return false;
-        return Http.#representationComplete(entry)
-            && Http.#requestMethod(header.content) === "GET"
-            && requestHeaders.length === 0
-            && Http.#packageHeaderValue(header.content, CACHE_VARIANT_HEADER) === "default"
-            && Http.#storedCachePolicy(header.content).cacheable
-            && await Http.#projectionCurrent(header.content, projection);
-    }
-    // {§revalidation} Origin headers come first; authoritative package method
-    // and acquisition metadata are appended last.
-    static #responseHeader(method, status, statusText, responseHeaders, requestHeaders) {
-        const lines = [`HTTP ${status} ${statusText}`];
-        for (const [k, v] of responseHeaders)
-            lines.push(`${k}: ${v}`);
-        lines.push(`${REQUEST_METHOD}: ${method}`);
-        lines.push(`${FETCHED_AT}: ${new Date().toISOString()}`);
-        lines.push(cacheVariantEvidence(classifyCacheVariant(requestHeaders, responseHeaders)));
-        return lines.join("\n");
-    }
-    static async #writeProjectionIdentity(subscription, identity) {
-        await subscription.notifyChunk(HEADER, `\n${WebFetcher.projectionEvidence(identity)}`, "text/plain");
-    }
-    // Drain an acquired SSE body and settle its retained subscription. The READ
-    // has already returned 102, so terminal failure is durable stream state.
-    static async #settleEventStream(subscription, response, options) {
-        try {
-            const events = await Http.#streamEvents(subscription, response);
-            if (options.signal.aborted) {
-                const result = Http.#cancelled(options.url, options.method);
-                await subscription.close(result, result.problem?.detail);
-                return;
-            }
-            await subscription.close({ status: 200 }, `SSE stream; ${events} events`);
-        }
-        catch (error) {
-            if (options.signal.aborted) {
-                const result = Http.#cancelled(options.url, options.method);
-                await subscription.close(result, result.problem?.detail);
-                return;
-            }
-            console.error("HTTP SSE stream failed", { method: options.method, url: options.url, error });
-            const cause = ErrorDetail.preview(error);
-            const reason = `HTTP ${options.method} ${options.url} failed: ${cause}`;
-            const result = Http.#bad(502, "http", "fetch-failed", reason, {
-                target: options.url,
-                method: options.method,
-                stage: "transfer",
-                retryable: false,
-            });
-            await subscription.close(result, reason);
-        }
-    }
-    // event/id/retry/comments remain transport metadata: this projection
-    // publishes event data, not the wire, and does not reconnect.
-    static async #streamEvents(subscription, response) {
-        if (response.body === null)
-            return 0;
-        const decoder = new TextDecoder();
-        const pending = [];
-        let fatal = null;
-        let events = 0;
-        const parser = createParser({
-            maxBufferSize: requireNumEnv("PLURNK_SCHEMES_HTTP_SSE_MAX_BUFFER_CHARS"),
-            onEvent: ({ data }) => pending.push(data),
-            // Unknown fields and invalid retry hints are irrelevant to this
-            // non-reconnecting data projection. Buffer exhaustion is fatal.
-            onError: (error) => {
-                if (error.type === "max-buffer-size-exceeded")
-                    fatal = error;
-            },
-        });
-        const publish = async () => {
-            for (const data of pending.splice(0)) {
-                events += 1;
-                await subscription.notifyChunk(BODY, `${data}\n`, "text/plain");
-            }
-        };
-        for await (const chunk of response.body) {
-            parser.feed(decoder.decode(chunk, { stream: true }));
-            if (fatal !== null)
-                throw fatal;
-            await publish();
-        }
-        const tail = decoder.decode();
-        if (tail.length > 0)
-            parser.feed(tail);
-        parser.reset({ consume: true });
-        if (fatal !== null)
-            throw fatal;
-        await publish();
-        return events;
-    }
-    static #address(target) {
-        let address;
-        try {
-            address = NetworkAddress.from(target);
-        }
-        catch {
-            return Http.#bad(400, "http", "bad-target", "HTTP operations require an http(s):// URL with an authority.", {
-                stage: "target-validation",
-                recovery: "Provide an http(s):// URL with a host.",
-                retryable: false,
-            });
-        }
-        if (address.scheme !== "http" && address.scheme !== "https") {
-            return Http.#bad(400, "http", "bad-target", "HTTP operations require an http(s):// URL target.", {
-                stage: "target-validation",
-                recovery: "Provide an http(s):// URL target.",
-                retryable: false,
-            });
-        }
-        if (address.hasCredentials) {
-            return Http.#bad(400, "http", "userinfo-not-allowed", "HTTP URL userinfo is not allowed.", {
-                target: address.url,
-                stage: "target-validation",
-                recovery: "Remove credentials from the URL and use request metadata where authorization is required.",
-                retryable: false,
-            });
-        }
-        // {§http-host-policy} — an operator-confined deployment refuses other hosts before any I/O.
-        if (!HostPolicy.permits(address.url)) {
-            return Http.#bad(403, "http", "host-not-permitted", `${new URL(address.url).hostname} is outside the operator's web host policy.`, {
-                target: address.url,
-                stage: "target-validation",
-                retryable: false,
-            });
-        }
-        return address;
-    }
-    // {§scheme-metadata-modifier} The request's [metadata] object is its header map:
-    // every key is a header name and every value a header string. `remote` on KILL
-    // is the one non-header key, consumed before the headers are read.
-    static #requestHeaders(metadata) {
-        const read = MetadataOptions.parse(metadata, "scheme:http");
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a metadata refusal has no shape; the method's result type names the success's passthrough shape
-        if ("failure" in read)
-            return read.failure;
-        const headers = [];
-        for (const [name, value] of Object.entries(read.options)) {
-            if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(name)) {
-                return Http.#bad(400, "http", "metadata-header-name", `HTTP metadata key '${name}' is not a valid header name.`, { retryable: false });
-            }
-            if (typeof value !== "string") {
-                return Http.#bad(400, "http", "metadata-header-shape", `HTTP header '${name}' requires a string value.`, { retryable: false });
-            }
-            headers.push([name, value.trim()]);
-        }
-        return headers;
-    }
-    // {§revalidation} Validation-free reuse requires both the operator's local
-    // ceiling and the origin's response policy to remain live.
-    static #fresh(header, now = Date.now()) {
-        const fetchedAt = Http.#fetchedAt(header);
-        const ttl = requireNumEnv("PLURNK_SCHEMES_HTTP_TTL_MS");
-        if (fetchedAt === undefined || ttl <= 0)
-            return false;
-        const residentTime = Math.max(0, now - fetchedAt);
-        if (residentTime >= ttl)
-            return false;
-        const policy = Http.#storedCachePolicy(header);
-        if (!policy.cacheable || policy.noCache)
-            return false;
-        return policy.freshnessLifetimeMs === undefined
-            || Http.#currentAge(header, fetchedAt, now) < policy.freshnessLifetimeMs;
-    }
-    // Package metadata is appended after origin headers, so the last value wins.
-    static #fetchedAt(priorHeader) {
-        const value = lastHeaderValue(priorHeader, FETCHED_AT);
-        if (value === undefined)
-            return undefined;
-        const ms = Date.parse(value);
-        return Number.isNaN(ms) ? undefined : ms;
-    }
-    static #headerField(line) {
-        const colon = line.indexOf(":");
-        if (colon < 0)
-            return null;
-        const name = line.slice(0, colon).trim().toLowerCase();
-        if (name.length === 0)
-            return null;
-        return { name, value: line.slice(colon + 1).trim(), line };
-    }
-    static #packageStart(lines) {
-        let stampIndex = -1;
-        for (const [index, line] of lines.entries()) {
-            if (Http.#headerField(line)?.name === FETCHED_AT)
-                stampIndex = index;
-        }
-        if (stampIndex < 0)
-            return lines.length;
-        return Http.#headerField(lines[stampIndex - 1] ?? "")?.name === REQUEST_METHOD
-            ? stampIndex - 1
-            : stampIndex;
-    }
-    static #originFields(header) {
-        const lines = header.split(/\r?\n/);
-        return lines.slice(1, Http.#packageStart(lines))
-            .map((line) => Http.#headerField(line))
-            .filter((field) => field !== null);
-    }
-    static #originValues(fields, name) {
-        return fields.filter((field) => field.name === name).map(({ value }) => value);
-    }
-    static #storedCachePolicy(header) {
-        const fields = Http.#originFields(header);
-        const directives = Http.#originValues(fields, "cache-control")
-            .flatMap((value) => splitHttpList(value))
-            .map((member) => cacheDirective(member))
-            .filter((directive) => directive !== null);
-        const sharedMaxAges = directives.filter(({ name }) => name === "s-maxage");
-        const maxAges = sharedMaxAges.length > 0 ? sharedMaxAges
-            : directives.filter(({ name }) => name === "max-age");
-        let freshnessLifetimeMs;
-        if (maxAges.length > 0) {
-            freshnessLifetimeMs = maxAges.length === 1
-                ? deltaMilliseconds(maxAges[0].argument) ?? 0
-                : 0;
-        }
-        else {
-            const expiresValues = Http.#originValues(fields, "expires");
-            if (expiresValues.length > 0) {
-                const expires = expiresValues.length === 1
-                    ? httpDate(expiresValues[0])
-                    : null;
-                const fetchedAt = Http.#fetchedAt(header);
-                if (expires === null || fetchedAt === undefined) {
-                    freshnessLifetimeMs = 0;
-                }
-                else {
-                    const dateValues = Http.#originValues(fields, "date");
-                    const parsedDate = dateValues.length === 1
-                        ? httpDate(dateValues[0])
-                        : null;
-                    const generatedAt = parsedDate ?? fetchedAt;
-                    freshnessLifetimeMs = Math.max(0, expires - generatedAt);
-                }
-            }
-        }
-        const status = Number(/^HTTP ([0-9]{3})(?:\s|$)/.exec(header)?.[1]);
-        const explicitPermission = freshnessLifetimeMs !== undefined
-            || directives.some(({ name, argument }) => name === "public" && argument === undefined);
-        return {
-            cacheable: status >= 200 && status <= 599 && status !== 206
-                && !directives.some(({ name }) => name === "no-store" || name === "private")
-                && (HEURISTIC_CACHE_STATUSES.has(status) || explicitPermission),
-            noCache: directives.some(({ name }) => name === "no-cache"),
-            ...(freshnessLifetimeMs === undefined ? {} : { freshnessLifetimeMs }),
-        };
-    }
-    static #currentAge(header, fetchedAt, now) {
-        const fields = Http.#originFields(header);
-        const dateValues = Http.#originValues(fields, "date");
-        const date = dateValues.length === 1 ? httpDate(dateValues[0]) : null;
-        const apparentAge = date === null ? 0 : Math.max(0, fetchedAt - date);
-        const ageMember = Http.#originValues(fields, "age").flatMap(splitHttpList)[0];
-        const ageValue = deltaMilliseconds(ageMember) ?? 0;
-        return Math.max(apparentAge, ageValue) + Math.max(0, now - fetchedAt);
-    }
-    static #requestMethod(priorHeader) {
-        return lastHeaderValue(priorHeader, REQUEST_METHOD)?.toUpperCase();
-    }
-    // Package evidence is authoritative only after the package acquisition
-    // stamp. An origin field with the same name remains inert.
-    static #packageHeaderValue(priorHeader, field) {
-        const lines = priorHeader.split(/\r?\n/);
-        let stampIndex = -1;
-        for (const [index, line] of lines.entries()) {
-            const colon = line.indexOf(":");
-            if (colon < 0)
-                continue;
-            const name = line.slice(0, colon).trim().toLowerCase();
-            if (name === FETCHED_AT)
-                stampIndex = index;
-        }
-        if (stampIndex < 0)
-            return undefined;
-        let value;
-        for (const line of lines.slice(stampIndex + 1)) {
-            const colon = line.indexOf(":");
-            if (colon < 0 || line.slice(0, colon).trim().toLowerCase() !== field)
-                continue;
-            value = line.slice(colon + 1).trim();
-        }
-        return value === "" ? undefined : value;
-    }
-    static #projectionIdentity(priorHeader) {
-        return Http.#packageHeaderValue(priorHeader, PROJECTION_ID_HEADER);
-    }
-    static #materializerIdentity(priorHeader) {
-        return Http.#packageHeaderValue(priorHeader, MATERIALIZER_ID_HEADER);
-    }
-    static #sourceMimetype(header) {
-        return responseMimetype(lastHeaderValue(header, "content-type") ?? null);
-    }
-    static async #projectionCurrent(header, projection) {
-        const sourceMimetype = Http.#sourceMimetype(header);
-        const isHtml = MimetypeClassifier.isHtml(sourceMimetype);
-        const materializerIdentity = Http.#materializerIdentity(header);
-        if (materializerIdentity !== undefined) {
-            // {§http-materializer-extensions} — a stored body produced by the current
-            // configured materializer (or the built-in producers) is current.
-            return WebFetcher.materializerCurrent(materializerIdentity);
-        }
-        if (isHtml && materializerIdentity === undefined)
-            return false;
-        const storedIdentity = Http.#projectionIdentity(header);
-        if (storedIdentity === undefined)
-            return !isHtml;
-        return await projection.identity(sourceMimetype) === storedIdentity;
-    }
-    // RFC 9111 §3.2 permits a processed cache to retain the metadata that its
-    // stored body depends upon. Other 304 fields update by name; package-owned
-    // evidence is then rebuilt after the origin block. {§revalidation}
-    static #refreshAfter304(header, responseHeaders, requestHeaders) {
-        const lines = header.split(/\r?\n/);
-        const origin = Http.#originFields(header);
-        const updates = responseHeaders.filter(([name]) => !BODY_PROCESSING_FIELDS.has(name.toLowerCase()));
-        const updatedNames = new Set(updates.map(([name]) => name.toLowerCase()));
-        const retained = origin.filter(({ name }) => !updatedNames.has(name));
-        const merged = [
-            ...retained.map(({ name, value }) => [name, value]),
-            ...updates,
-        ];
-        // Materializer/provider evidence headers are extension-owned (unknown names);
-        // a 304 does not re-materialize the stored body, so its evidence is
-        // retained verbatim beside the rebuilt framework fields. Framework-owned
-        // x-plurnk-* fields (cache-variant, materializer/projection ids, method,
-        // fetched-at stamp) are rebuilt or omitted, never duplicated stale.
-        const rebuilt = [MATERIALIZER_ID_HEADER, PROJECTION_ID_HEADER].flatMap((field) => {
-            const value = Http.#packageHeaderValue(header, field);
-            return value === undefined ? [] : [`${field}: ${value}`];
-        });
-        const frameworkOwned = new Set([
-            CACHE_VARIANT_HEADER.toLowerCase(),
-            MATERIALIZER_ID_HEADER.toLowerCase(),
-            PROJECTION_ID_HEADER.toLowerCase(),
-            REQUEST_METHOD.toLowerCase(),
-            FETCHED_AT.toLowerCase(),
-        ]);
-        const packageEvidence = [
-            ...rebuilt,
-            ...lines.slice(1).filter((line) => {
-                const colon = line.indexOf(":");
-                if (colon <= 0)
-                    return false;
-                const name = line.slice(0, colon).toLowerCase();
-                return name.startsWith("x-plurnk-")
-                    && !frameworkOwned.has(name)
-                    && !updatedNames.has(name);
-            }),
-        ];
-        return [
-            lines[0] ?? "HTTP 200 OK",
-            ...retained.map(({ line }) => line),
-            ...updates.map(([name, value]) => `${name}: ${value}`),
-            `${REQUEST_METHOD}: GET`,
-            `${FETCHED_AT}: ${new Date().toISOString()}`,
-            cacheVariantEvidence(classifyCacheVariant(requestHeaders, merged)),
-            ...packageEvidence,
-        ].join("\n");
-    }
-    static #revalidationCorresponds(priorHeader, responseHeaders) {
-        const fields = Http.#originFields(priorHeader);
-        const responseTagValue = responseHeaders.get("etag");
-        if (responseTagValue !== null) {
-            const storedTagValues = Http.#originValues(fields, "etag");
-            const responseTag = entityTag(responseTagValue);
-            const storedTag = storedTagValues.length === 1
-                ? entityTag(storedTagValues[0])
-                : null;
-            if (responseTag === null || storedTag === null)
-                return false;
-            // {§revalidation}: RFC 9111 §4.3.4 identifies stored responses;
-            // it is not the origin's If-None-Match precondition comparison.
-            return responseTag.opaque === storedTag.opaque
-                && (responseTag.weak || !storedTag.weak);
-        }
-        const responseModifiedValue = responseHeaders.get("last-modified");
-        const storedModifiedValues = Http.#originValues(fields, "last-modified");
-        const responseModified = responseModifiedValue === null
-            ? null
-            : httpDate(responseModifiedValue);
-        const storedModified = storedModifiedValues.length === 1
-            ? httpDate(storedModifiedValues[0])
-            : null;
-        return responseModified !== null
-            && storedModified !== null
-            && responseModified === storedModified;
-    }
-    // Conditional-request headers from the prior fetch's stored response headers
-    // (the HEADER channel's response evidence): ETag → If-None-Match,
-    // Last-Modified → If-Modified-Since. Empty when neither is present — the
-    // origin then just 200s with a full body, which is correct.
-    static #validators(priorHeader) {
-        const fields = Http.#originFields(priorHeader);
-        const out = [];
-        const etags = Http.#originValues(fields, "etag");
-        if (etags.length === 1 && entityTag(etags[0]) !== null) {
-            out.push(["If-None-Match", etags[0]]);
-        }
-        const lastModified = Http.#originValues(fields, "last-modified");
-        if (lastModified.length === 1 && httpDate(lastModified[0]) !== null) {
-            out.push(["If-Modified-Since", lastModified[0]]);
-        }
-        return out;
-    }
-    static #passthrough(result) {
-        return Results.assertChannelProducerResult({ ...result, shape: "passthrough" });
-    }
-    static #cancelled(url, method) {
-        return Http.#bad(499, "http", "cancelled", `HTTP ${method} ${url} was cancelled.`, {
-            target: url,
-            method,
-            stage: "acquisition",
-            retryable: false,
-        });
-    }
-    static #materializationFailure(url, method, error) {
-        if (error.stage === "projection" && error.cause instanceof ProjectionInputLimitError) {
-            return Http.#bad(413, "http", "projection-input-limit", `HTTP ${method} ${url} exceeded the ${error.cause.maximumBytes}-byte binary input limit.`, {
-                target: url,
-                method,
-                mimetype: error.cause.mimetype,
-                maximumBytes: error.cause.maximumBytes,
-                observedBytes: error.cause.observedBytes,
-                stage: "projection",
-                retryable: false,
-            });
-        }
-        console.error("HTTP materialization failed", { method, url, error });
-        return Http.#bad(500, "http", "projection-failed", `HTTP ${method} ${url} response materialization failed.`, {
-            target: url,
-            method,
-            mimetype: error.mimetype,
-            stage: "projection",
-            retryable: false,
-        });
-    }
-    static #bad(status, scheme, kind, message, extensions = {}) {
-        return Results.failure(`scheme:${scheme}`, kind, status, message, { shape: "passthrough" }, extensions);
-    }
 }
 //# sourceMappingURL=Http.js.map