@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/accept-negotiation.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * `Accept` header negotiation, per RFC 9110 §12.5.1 — the one rule that
+ * decides whether a request gets HTML or Markdown.
+ *
+ * ## Why this is a parser and not a substring test
+ *
+ * The tempting implementation is `accept.includes('text/markdown')`. It is
+ * wrong in both directions, and the wrong answers are the ones that matter:
+ *
+ * - `Accept: text/markdown;q=0` CONTAINS the string and means *anything but
+ *   markdown*. A substring test serves markdown to a client that explicitly
+ *   refused it.
+ * - Every browser sends the full wildcard range with a low q alongside its
+ *   real preferences — Chrome's document `Accept` ends in `image/webp` and
+ *   then that range at `q=0.8`. A test for the full wildcard — the obvious
+ *   "they will take anything" shortcut — matches it, and a browser gets a wall
+ *   of raw Markdown.
+ *
+ * So the header is parsed into ranked entries and matched by the algorithm the
+ * RFC actually specifies: sort by q descending, break ties by specificity (an
+ * exact type beats a subtype wildcard beats the full wildcard), and treat
+ * `q=0` as a refusal rather than a low score.
+ *
+ * ## The absent-header rule is load-bearing
+ *
+ * No `Accept` at all means NO CONSTRAINT, not "nothing works", and the full
+ * wildcard means the same. Both serve the caller's default — which for a web
+ * page is HTML. Getting this backwards is how a site starts answering `curl`
+ * and every link-preview crawler with Markdown.
+ *
+ * ## 406 is rare on purpose
+ *
+ * {@link negotiateMediaType} returns `null` only when EVERY representation the
+ * caller can produce is either unmatched or explicitly refused with `q=0`.
+ * That is the only case where RFC 9110 §15.5.7 asks for a 406, and answering
+ * one more eagerly than that breaks ordinary clients for no gain.
+ */
+/** One parsed entry of an `Accept` header, in the order it was written. */
+export interface AcceptEntry {
+    /** Lowercased type, `*` for a wildcard. */
+    type: string;
+    /** Lowercased subtype, `*` for a wildcard. */
+    subtype: string;
+    /** Quality factor, 0–1. Absent `q` is 1. */
+    q: number;
+}
+/**
+ * Parse an `Accept` header into entries.
+ *
+ * Entries whose media range is unparseable are dropped rather than defaulted:
+ * a range we cannot read cannot be honored, and widening it to the full
+ * wildcard would silently grant more than the client asked for.
+ */
+export declare function parseAcceptHeader(header: string | null | undefined): AcceptEntry[];
+/**
+ * Pick which representation to serve.
+ *
+ * @param header - the raw `Accept` request header, or null/absent
+ * @param available - the media types this resource can produce, DEFAULT FIRST.
+ *   The order is the server's own preference and breaks ties — for a web page
+ *   that means HTML first, so a browser sending the full wildcard gets HTML.
+ * @returns the chosen media type, or `null` when the request must be answered
+ *   `406 Not Acceptable`.
+ */
+export declare function negotiateMediaType(header: string | null | undefined, available: readonly string[]): string | null;
+/** `text/markdown`, the media type RFC 7763 registers. */
+export declare const MARKDOWN_MEDIA_TYPE = "text/markdown";
+/** What a markdown response actually sends, charset included. */
+export declare const MARKDOWN_CONTENT_TYPE = "text/markdown; charset=utf-8";
+/** `text/html`, the default representation of every page on a site. */
+export declare const HTML_MEDIA_TYPE = "text/html";
+/**
+ * What a tenant page can produce, DEFAULT FIRST.
+ *
+ * HTML leads because a page whose visitor is a browser must stay a page: every
+ * client that sends no `Accept`, or only the full wildcard, lands on the
+ * first entry.
+ */
+export declare const PAGE_MEDIA_TYPES: readonly string[];
+/**
+ * Whether a request asked for the markdown representation of a page.
+ *
+ * The single door every surface uses, so the middleware's routing decision and
+ * the handler's `Content-Type` can never disagree about one header.
+ */
+export declare function wantsMarkdown(header: string | null | undefined): boolean;
+/**
+ * Whether a request refuses EVERY representation a page can produce, i.e. the
+ * one case that earns a 406.
+ */
+export declare function isPageUnacceptable(header: string | null | undefined): boolean;
+/**
+ * The plain-text body RFC 9110 §15.5.7 recommends a 406 carry: the list of
+ * representations the client could have asked for.
+ *
+ * A body rather than an empty response because the client is an agent, and an
+ * agent that is told what IS available can retry correctly on its next call
+ * instead of giving up on the URL.
+ */
+export declare function notAcceptableBody(requested: string | null | undefined, available?: readonly string[]): string;
+/**
+ * Add `Accept` to a `Vary` header without disturbing what is already there.
+ *
+ * Written as a merge rather than an assignment because the tenant already
+ * varies on Next's router headers (`rsc`, `next-router-state-tree`, …). An
+ * overwrite would drop those and serve an RSC payload to a document request;
+ * a blind append would list `Accept` twice on a response that already had it.
+ *
+ * `Vary: *` is left ALONE. It already means "do not cache this by any key",
+ * which is stricter than anything adding `Accept` could express, and rewriting
+ * it to a list would WEAKEN the response's caching contract.
+ */
+export declare function varyWithAccept(existing: string | null | undefined): string;

package/src/lib/app-utils/accept-negotiation.js

@@ -0,0 +1,266 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * `Accept` header negotiation, per RFC 9110 §12.5.1 — the one rule that
+ * decides whether a request gets HTML or Markdown.
+ *
+ * ## Why this is a parser and not a substring test
+ *
+ * The tempting implementation is `accept.includes('text/markdown')`. It is
+ * wrong in both directions, and the wrong answers are the ones that matter:
+ *
+ * - `Accept: text/markdown;q=0` CONTAINS the string and means *anything but
+ *   markdown*. A substring test serves markdown to a client that explicitly
+ *   refused it.
+ * - Every browser sends the full wildcard range with a low q alongside its
+ *   real preferences — Chrome's document `Accept` ends in `image/webp` and
+ *   then that range at `q=0.8`. A test for the full wildcard — the obvious
+ *   "they will take anything" shortcut — matches it, and a browser gets a wall
+ *   of raw Markdown.
+ *
+ * So the header is parsed into ranked entries and matched by the algorithm the
+ * RFC actually specifies: sort by q descending, break ties by specificity (an
+ * exact type beats a subtype wildcard beats the full wildcard), and treat
+ * `q=0` as a refusal rather than a low score.
+ *
+ * ## The absent-header rule is load-bearing
+ *
+ * No `Accept` at all means NO CONSTRAINT, not "nothing works", and the full
+ * wildcard means the same. Both serve the caller's default — which for a web
+ * page is HTML. Getting this backwards is how a site starts answering `curl`
+ * and every link-preview crawler with Markdown.
+ *
+ * ## 406 is rare on purpose
+ *
+ * {@link negotiateMediaType} returns `null` only when EVERY representation the
+ * caller can produce is either unmatched or explicitly refused with `q=0`.
+ * That is the only case where RFC 9110 §15.5.7 asks for a 406, and answering
+ * one more eagerly than that breaks ordinary clients for no gain.
+ */ /** One parsed entry of an `Accept` header, in the order it was written. */ /** How well an accept entry matches a concrete media type. Higher is better. */ const SPECIFICITY_EXACT = 3;
+const SPECIFICITY_SUBTYPE_WILDCARD = 2;
+const SPECIFICITY_FULL_WILDCARD = 1;
+const SPECIFICITY_NONE = 0;
+/**
+ * Parse `q`, defaulting to 1 and clamping to [0, 1].
+ *
+ * A malformed `q` (`q=abc`, `q=`) is treated as ABSENT rather than as zero.
+ * Zero is a refusal, and inferring a refusal from a typo would let one bad
+ * character turn a normal request into a 406.
+ */ function parseQuality(raw) {
+    if (raw == null) return 1;
+    const value = Number.parseFloat(raw.trim());
+    if (!Number.isFinite(value)) return 1;
+    if (value < 0) return 0;
+    if (value > 1) return 1;
+    return value;
+}
+/**
+ * Parse an `Accept` header into entries.
+ *
+ * Entries whose media range is unparseable are dropped rather than defaulted:
+ * a range we cannot read cannot be honored, and widening it to the full
+ * wildcard would silently grant more than the client asked for.
+ */ export function parseAcceptHeader(header) {
+    if (typeof header !== 'string' || header.trim() === '') return [];
+    const entries = [];
+    for (const part of header.split(',')){
+        const [rangeRaw, ...paramParts] = part.split(';');
+        const range = rangeRaw.trim().toLowerCase();
+        if (!range) continue;
+        const slash = range.indexOf('/');
+        if (slash <= 0 || slash === range.length - 1) continue;
+        const type = range.slice(0, slash);
+        const subtype = range.slice(slash + 1);
+        // A wildcard TYPE with a concrete subtype is not a range any client
+        // means, and nothing can satisfy it. Dropped rather than matched.
+        if (type === '*' && subtype !== '*') continue;
+        let q;
+        for (const param of paramParts){
+            const equals = param.indexOf('=');
+            if (equals === -1) continue;
+            if (param.slice(0, equals).trim().toLowerCase() !== 'q') continue;
+            q = param.slice(equals + 1);
+            break;
+        }
+        entries.push({
+            type,
+            subtype,
+            q: parseQuality(q)
+        });
+    }
+    return entries;
+}
+/**
+ * How specifically `entry` names `mediaType`; {@link SPECIFICITY_NONE} when it
+ * does not name it at all.
+ *
+ * `mediaType` is matched on its TYPE ONLY — parameters such as
+ * `;charset=utf-8` are stripped first. A client that writes
+ * `Accept: text/markdown` is asking for the markdown representation whatever
+ * charset it comes in, and treating the parameters as part of the name would
+ * make every such request a 406.
+ */ function specificity(entry, mediaType) {
+    const bare = mediaType.split(';')[0].trim().toLowerCase();
+    const slash = bare.indexOf('/');
+    if (slash <= 0) return SPECIFICITY_NONE;
+    const type = bare.slice(0, slash);
+    const subtype = bare.slice(slash + 1);
+    if (entry.type === type && entry.subtype === subtype) return SPECIFICITY_EXACT;
+    if (entry.type === type && entry.subtype === '*') {
+        return SPECIFICITY_SUBTYPE_WILDCARD;
+    }
+    if (entry.type === '*' && entry.subtype === '*') return SPECIFICITY_FULL_WILDCARD;
+    return SPECIFICITY_NONE;
+}
+/**
+ * The best `Accept` entry for one media type — the MOST SPECIFIC match, not
+ * the highest-q one.
+ *
+ * RFC 9110 is explicit that precedence goes to the most specific range, and
+ * the difference is exactly what makes `q=0` work: given
+ * `text/markdown;q=0, text/*` the exact range refuses markdown even though a
+ * wildcard beside it would have scored 1. Picking by q would read that header
+ * as an acceptance.
+ */ function bestEntryFor(entries, mediaType) {
+    let best = null;
+    let bestScore = SPECIFICITY_NONE;
+    for (const entry of entries){
+        const score = specificity(entry, mediaType);
+        if (score === SPECIFICITY_NONE) continue;
+        if (score > bestScore) {
+            best = entry;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * Pick which representation to serve.
+ *
+ * @param header - the raw `Accept` request header, or null/absent
+ * @param available - the media types this resource can produce, DEFAULT FIRST.
+ *   The order is the server's own preference and breaks ties — for a web page
+ *   that means HTML first, so a browser sending the full wildcard gets HTML.
+ * @returns the chosen media type, or `null` when the request must be answered
+ *   `406 Not Acceptable`.
+ */ export function negotiateMediaType(header, available) {
+    if (available.length === 0) return null;
+    const entries = parseAcceptHeader(header);
+    // No usable Accept at all — no constraint. Serve the default.
+    if (entries.length === 0) return available[0];
+    /*
+    A header made of NOTHING BUT REFUSALS states no positive preference, so it
+    constrains rather than selects: `Accept: text/markdown;q=0` means *anything
+    except markdown*, not *markdown or nothing*. The two published vectors that
+    pin this are a pair, and only this branch satisfies both —
+
+      text/markdown;q=0  produces md + html  →  html   (a refusal, not a demand)
+      text/markdown;q=0  produces md only    →  406    (the one type, refused)
+
+    — where scoring every unlisted type as zero would 406 the first, and
+    ignoring q=0 would serve markdown to a client that just said not to.
+  */ if (entries.every((entry)=>entry.q <= 0)) {
+        for (const candidate of available){
+            const refusal = bestEntryFor(entries, candidate);
+            if (!refusal || refusal.q > 0) return candidate;
+        }
+        return null;
+    }
+    let chosen = null;
+    let chosenQ = 0;
+    let chosenSpecificity = SPECIFICITY_NONE;
+    for (const candidate of available){
+        const entry = bestEntryFor(entries, candidate);
+        if (!entry || entry.q <= 0) continue;
+        const candidateSpecificity = specificity(entry, candidate);
+        // Strictly greater on q, then on specificity: equal on both leaves the
+        // EARLIER candidate standing, which is how `available` order expresses the
+        // server's own preference.
+        if (entry.q > chosenQ || entry.q === chosenQ && candidateSpecificity > chosenSpecificity) {
+            chosen = candidate;
+            chosenQ = entry.q;
+            chosenSpecificity = candidateSpecificity;
+        }
+    }
+    return chosen;
+}
+/** `text/markdown`, the media type RFC 7763 registers. */ export const MARKDOWN_MEDIA_TYPE = 'text/markdown';
+/** What a markdown response actually sends, charset included. */ export const MARKDOWN_CONTENT_TYPE = 'text/markdown; charset=utf-8';
+/** `text/html`, the default representation of every page on a site. */ export const HTML_MEDIA_TYPE = 'text/html';
+/**
+ * What a tenant page can produce, DEFAULT FIRST.
+ *
+ * HTML leads because a page whose visitor is a browser must stay a page: every
+ * client that sends no `Accept`, or only the full wildcard, lands on the
+ * first entry.
+ */ export const PAGE_MEDIA_TYPES = [
+    HTML_MEDIA_TYPE,
+    MARKDOWN_MEDIA_TYPE
+];
+/**
+ * Whether a request asked for the markdown representation of a page.
+ *
+ * The single door every surface uses, so the middleware's routing decision and
+ * the handler's `Content-Type` can never disagree about one header.
+ */ export function wantsMarkdown(header) {
+    return negotiateMediaType(header, PAGE_MEDIA_TYPES) === MARKDOWN_MEDIA_TYPE;
+}
+/**
+ * Whether a request refuses EVERY representation a page can produce, i.e. the
+ * one case that earns a 406.
+ */ export function isPageUnacceptable(header) {
+    return negotiateMediaType(header, PAGE_MEDIA_TYPES) === null;
+}
+/**
+ * The plain-text body RFC 9110 §15.5.7 recommends a 406 carry: the list of
+ * representations the client could have asked for.
+ *
+ * A body rather than an empty response because the client is an agent, and an
+ * agent that is told what IS available can retry correctly on its next call
+ * instead of giving up on the URL.
+ */ export function notAcceptableBody(requested, available = PAGE_MEDIA_TYPES) {
+    const lines = [
+        'This resource is available in:'
+    ];
+    for (const type of available)lines.push(`- ${type}`);
+    const asked = typeof requested === 'string' ? requested.trim() : '';
+    if (asked) lines.push('', `You requested: ${asked}`);
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Add `Accept` to a `Vary` header without disturbing what is already there.
+ *
+ * Written as a merge rather than an assignment because the tenant already
+ * varies on Next's router headers (`rsc`, `next-router-state-tree`, …). An
+ * overwrite would drop those and serve an RSC payload to a document request;
+ * a blind append would list `Accept` twice on a response that already had it.
+ *
+ * `Vary: *` is left ALONE. It already means "do not cache this by any key",
+ * which is stricter than anything adding `Accept` could express, and rewriting
+ * it to a list would WEAKEN the response's caching contract.
+ */ export function varyWithAccept(existing) {
+    const current = typeof existing === 'string' ? existing.trim() : '';
+    if (!current) return 'Accept';
+    if (current === '*') return '*';
+    const names = current.split(',').map((name)=>name.trim()).filter(Boolean);
+    if (names.some((name)=>name.toLowerCase() === 'accept')) return names.join(', ');
+    return [
+        ...names,
+        'Accept'
+    ].join(', ');
+}
+
+//# sourceMappingURL=accept-negotiation.js.map

package/src/lib/app-utils/accept-negotiation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/accept-negotiation.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * `Accept` header negotiation, per RFC 9110 §12.5.1 — the one rule that\n * decides whether a request gets HTML or Markdown.\n *\n * ## Why this is a parser and not a substring test\n *\n * The tempting implementation is `accept.includes('text/markdown')`. It is\n * wrong in both directions, and the wrong answers are the ones that matter:\n *\n * - `Accept: text/markdown;q=0` CONTAINS the string and means *anything but\n *   markdown*. A substring test serves markdown to a client that explicitly\n *   refused it.\n * - Every browser sends the full wildcard range with a low q alongside its\n *   real preferences — Chrome's document `Accept` ends in `image/webp` and\n *   then that range at `q=0.8`. A test for the full wildcard — the obvious\n *   \"they will take anything\" shortcut — matches it, and a browser gets a wall\n *   of raw Markdown.\n *\n * So the header is parsed into ranked entries and matched by the algorithm the\n * RFC actually specifies: sort by q descending, break ties by specificity (an\n * exact type beats a subtype wildcard beats the full wildcard), and treat\n * `q=0` as a refusal rather than a low score.\n *\n * ## The absent-header rule is load-bearing\n *\n * No `Accept` at all means NO CONSTRAINT, not \"nothing works\", and the full\n * wildcard means the same. Both serve the caller's default — which for a web\n * page is HTML. Getting this backwards is how a site starts answering `curl`\n * and every link-preview crawler with Markdown.\n *\n * ## 406 is rare on purpose\n *\n * {@link negotiateMediaType} returns `null` only when EVERY representation the\n * caller can produce is either unmatched or explicitly refused with `q=0`.\n * That is the only case where RFC 9110 §15.5.7 asks for a 406, and answering\n * one more eagerly than that breaks ordinary clients for no gain.\n */\n\n/** One parsed entry of an `Accept` header, in the order it was written. */\nexport interface AcceptEntry {\n  /** Lowercased type, `*` for a wildcard. */\n  type: string\n  /** Lowercased subtype, `*` for a wildcard. */\n  subtype: string\n  /** Quality factor, 0–1. Absent `q` is 1. */\n  q: number\n}\n\n/** How well an accept entry matches a concrete media type. Higher is better. */\nconst SPECIFICITY_EXACT = 3\nconst SPECIFICITY_SUBTYPE_WILDCARD = 2\nconst SPECIFICITY_FULL_WILDCARD = 1\nconst SPECIFICITY_NONE = 0\n\n/**\n * Parse `q`, defaulting to 1 and clamping to [0, 1].\n *\n * A malformed `q` (`q=abc`, `q=`) is treated as ABSENT rather than as zero.\n * Zero is a refusal, and inferring a refusal from a typo would let one bad\n * character turn a normal request into a 406.\n */\nfunction parseQuality(raw: string | undefined): number {\n  if (raw == null) return 1\n  const value = Number.parseFloat(raw.trim())\n  if (!Number.isFinite(value)) return 1\n  if (value < 0) return 0\n  if (value > 1) return 1\n  return value\n}\n\n/**\n * Parse an `Accept` header into entries.\n *\n * Entries whose media range is unparseable are dropped rather than defaulted:\n * a range we cannot read cannot be honored, and widening it to the full\n * wildcard would silently grant more than the client asked for.\n */\nexport function parseAcceptHeader(header: string | null | undefined): AcceptEntry[] {\n  if (typeof header !== 'string' || header.trim() === '') return []\n  const entries: AcceptEntry[] = []\n  for (const part of header.split(',')) {\n    const [rangeRaw, ...paramParts] = part.split(';')\n    const range = rangeRaw.trim().toLowerCase()\n    if (!range) continue\n    const slash = range.indexOf('/')\n    if (slash <= 0 || slash === range.length - 1) continue\n    const type = range.slice(0, slash)\n    const subtype = range.slice(slash + 1)\n    // A wildcard TYPE with a concrete subtype is not a range any client\n    // means, and nothing can satisfy it. Dropped rather than matched.\n    if (type === '*' && subtype !== '*') continue\n    let q: string | undefined\n    for (const param of paramParts) {\n      const equals = param.indexOf('=')\n      if (equals === -1) continue\n      if (param.slice(0, equals).trim().toLowerCase() !== 'q') continue\n      q = param.slice(equals + 1)\n      // RFC 9110: parameters AFTER `q` are response parameters, not media-range\n      // parameters, so the first `q` wins and the rest are not `q` at all.\n      break\n    }\n    entries.push({ type, subtype, q: parseQuality(q) })\n  }\n  return entries\n}\n\n/**\n * How specifically `entry` names `mediaType`; {@link SPECIFICITY_NONE} when it\n * does not name it at all.\n *\n * `mediaType` is matched on its TYPE ONLY — parameters such as\n * `;charset=utf-8` are stripped first. A client that writes\n * `Accept: text/markdown` is asking for the markdown representation whatever\n * charset it comes in, and treating the parameters as part of the name would\n * make every such request a 406.\n */\nfunction specificity(entry: AcceptEntry, mediaType: string): number {\n  const bare = mediaType.split(';')[0].trim().toLowerCase()\n  const slash = bare.indexOf('/')\n  if (slash <= 0) return SPECIFICITY_NONE\n  const type = bare.slice(0, slash)\n  const subtype = bare.slice(slash + 1)\n  if (entry.type === type && entry.subtype === subtype) return SPECIFICITY_EXACT\n  if (entry.type === type && entry.subtype === '*') {\n    return SPECIFICITY_SUBTYPE_WILDCARD\n  }\n  if (entry.type === '*' && entry.subtype === '*') return SPECIFICITY_FULL_WILDCARD\n  return SPECIFICITY_NONE\n}\n\n/**\n * The best `Accept` entry for one media type — the MOST SPECIFIC match, not\n * the highest-q one.\n *\n * RFC 9110 is explicit that precedence goes to the most specific range, and\n * the difference is exactly what makes `q=0` work: given\n * `text/markdown;q=0, text/*` the exact range refuses markdown even though a\n * wildcard beside it would have scored 1. Picking by q would read that header\n * as an acceptance.\n */\nfunction bestEntryFor(\n  entries: readonly AcceptEntry[],\n  mediaType: string,\n): AcceptEntry | null {\n  let best: AcceptEntry | null = null\n  let bestScore = SPECIFICITY_NONE\n  for (const entry of entries) {\n    const score = specificity(entry, mediaType)\n    if (score === SPECIFICITY_NONE) continue\n    if (score > bestScore) {\n      best = entry\n      bestScore = score\n    }\n  }\n  return best\n}\n\n/**\n * Pick which representation to serve.\n *\n * @param header - the raw `Accept` request header, or null/absent\n * @param available - the media types this resource can produce, DEFAULT FIRST.\n *   The order is the server's own preference and breaks ties — for a web page\n *   that means HTML first, so a browser sending the full wildcard gets HTML.\n * @returns the chosen media type, or `null` when the request must be answered\n *   `406 Not Acceptable`.\n */\nexport function negotiateMediaType(\n  header: string | null | undefined,\n  available: readonly string[],\n): string | null {\n  if (available.length === 0) return null\n  const entries = parseAcceptHeader(header)\n  // No usable Accept at all — no constraint. Serve the default.\n  if (entries.length === 0) return available[0]\n\n  /*\n    A header made of NOTHING BUT REFUSALS states no positive preference, so it\n    constrains rather than selects: `Accept: text/markdown;q=0` means *anything\n    except markdown*, not *markdown or nothing*. The two published vectors that\n    pin this are a pair, and only this branch satisfies both —\n\n      text/markdown;q=0  produces md + html  →  html   (a refusal, not a demand)\n      text/markdown;q=0  produces md only    →  406    (the one type, refused)\n\n    — where scoring every unlisted type as zero would 406 the first, and\n    ignoring q=0 would serve markdown to a client that just said not to.\n  */\n  if (entries.every((entry) => entry.q <= 0)) {\n    for (const candidate of available) {\n      const refusal = bestEntryFor(entries, candidate)\n      if (!refusal || refusal.q > 0) return candidate\n    }\n    return null\n  }\n\n  let chosen: string | null = null\n  let chosenQ = 0\n  let chosenSpecificity = SPECIFICITY_NONE\n  for (const candidate of available) {\n    const entry = bestEntryFor(entries, candidate)\n    if (!entry || entry.q <= 0) continue\n    const candidateSpecificity = specificity(entry, candidate)\n    // Strictly greater on q, then on specificity: equal on both leaves the\n    // EARLIER candidate standing, which is how `available` order expresses the\n    // server's own preference.\n    if (\n      entry.q > chosenQ ||\n      (entry.q === chosenQ && candidateSpecificity > chosenSpecificity)\n    ) {\n      chosen = candidate\n      chosenQ = entry.q\n      chosenSpecificity = candidateSpecificity\n    }\n  }\n  return chosen\n}\n\n/** `text/markdown`, the media type RFC 7763 registers. */\nexport const MARKDOWN_MEDIA_TYPE = 'text/markdown'\n\n/** What a markdown response actually sends, charset included. */\nexport const MARKDOWN_CONTENT_TYPE = 'text/markdown; charset=utf-8'\n\n/** `text/html`, the default representation of every page on a site. */\nexport const HTML_MEDIA_TYPE = 'text/html'\n\n/**\n * What a tenant page can produce, DEFAULT FIRST.\n *\n * HTML leads because a page whose visitor is a browser must stay a page: every\n * client that sends no `Accept`, or only the full wildcard, lands on the\n * first entry.\n */\nexport const PAGE_MEDIA_TYPES: readonly string[] = [\n  HTML_MEDIA_TYPE,\n  MARKDOWN_MEDIA_TYPE,\n]\n\n/**\n * Whether a request asked for the markdown representation of a page.\n *\n * The single door every surface uses, so the middleware's routing decision and\n * the handler's `Content-Type` can never disagree about one header.\n */\nexport function wantsMarkdown(header: string | null | undefined): boolean {\n  return negotiateMediaType(header, PAGE_MEDIA_TYPES) === MARKDOWN_MEDIA_TYPE\n}\n\n/**\n * Whether a request refuses EVERY representation a page can produce, i.e. the\n * one case that earns a 406.\n */\nexport function isPageUnacceptable(header: string | null | undefined): boolean {\n  return negotiateMediaType(header, PAGE_MEDIA_TYPES) === null\n}\n\n/**\n * The plain-text body RFC 9110 §15.5.7 recommends a 406 carry: the list of\n * representations the client could have asked for.\n *\n * A body rather than an empty response because the client is an agent, and an\n * agent that is told what IS available can retry correctly on its next call\n * instead of giving up on the URL.\n */\nexport function notAcceptableBody(\n  requested: string | null | undefined,\n  available: readonly string[] = PAGE_MEDIA_TYPES,\n): string {\n  const lines = ['This resource is available in:']\n  for (const type of available) lines.push(`- ${type}`)\n  const asked = typeof requested === 'string' ? requested.trim() : ''\n  if (asked) lines.push('', `You requested: ${asked}`)\n  return `${lines.join('\\n')}\\n`\n}\n\n/**\n * Add `Accept` to a `Vary` header without disturbing what is already there.\n *\n * Written as a merge rather than an assignment because the tenant already\n * varies on Next's router headers (`rsc`, `next-router-state-tree`, …). An\n * overwrite would drop those and serve an RSC payload to a document request;\n * a blind append would list `Accept` twice on a response that already had it.\n *\n * `Vary: *` is left ALONE. It already means \"do not cache this by any key\",\n * which is stricter than anything adding `Accept` could express, and rewriting\n * it to a list would WEAKEN the response's caching contract.\n */\nexport function varyWithAccept(existing: string | null | undefined): string {\n  const current = typeof existing === 'string' ? existing.trim() : ''\n  if (!current) return 'Accept'\n  if (current === '*') return '*'\n  const names = current\n    .split(',')\n    .map((name) => name.trim())\n    .filter(Boolean)\n  if (names.some((name) => name.toLowerCase() === 'accept')) return names.join(', ')\n  return [...names, 'Accept'].join(', ')\n}\n"],"names":["SPECIFICITY_EXACT","SPECIFICITY_SUBTYPE_WILDCARD","SPECIFICITY_FULL_WILDCARD","SPECIFICITY_NONE","parseQuality","raw","value","Number","parseFloat","trim","isFinite","parseAcceptHeader","header","entries","part","split","rangeRaw","paramParts","range","toLowerCase","slash","indexOf","length","type","slice","subtype","q","param","equals","push","specificity","entry","mediaType","bare","bestEntryFor","best","bestScore","score","negotiateMediaType","available","every","candidate","refusal","chosen","chosenQ","chosenSpecificity","candidateSpecificity","MARKDOWN_MEDIA_TYPE","MARKDOWN_CONTENT_TYPE","HTML_MEDIA_TYPE","PAGE_MEDIA_TYPES","wantsMarkdown","isPageUnacceptable","notAcceptableBody","requested","lines","asked","join","varyWithAccept","existing","current","names","map","name","filter","Boolean","some"],"mappings":"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"}