@sdxc/http 2026.10.24 → 2026.10.26

package/README.md

@@ -3,8 +3,8 @@
 Response builders, content negotiation, and HTTP caching for the Fetch API.
 
 Each concern is its own entry point — status codes, content types, response builders,
-`Accept` negotiation, `Cache-Control` and validators, and `HEAD` middleware — so a handler
-imports only the surface it uses.
+`Accept` negotiation, `Cache-Control` and validators, deprecation notices, `Retry-After`,
+and `HEAD` middleware — so a handler imports only the surface it uses.
 
 ## Installation
 
@@ -16,6 +16,8 @@ It installs alongside [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/resul
 `Result` that `etag` and `precondition` answer),
 [`@sdxc/duration`](https://www.npmjs.com/package/@sdxc/duration) (cache ages),
 [`@sdxc/crypto`](https://www.npmjs.com/package/@sdxc/crypto),
+[`@sdxc/structured-fields`](https://www.npmjs.com/package/@sdxc/structured-fields),
+[`@sdxc/link-header`](https://www.npmjs.com/package/@sdxc/link-header) (deprecation notices),
 [`@sdxc/location`](https://www.npmjs.com/package/@sdxc/location) and
 [`remix`](https://www.npmjs.com/package/remix) (typed headers and the router).
 
@@ -172,7 +174,8 @@ Writes `application/pdf`.
 
 #### `file(body: Blob | ArrayBuffer | ReadableStream, filename: string, init?: ResponseInit): Response`
 
-A download of opaque bytes: `application/octet-stream` plus `attachment(filename)`.
+A download with `Content-Disposition: attachment(filename)`, typed by the `Content-Type` in
+`init` or `application/octet-stream` when it names none.
 
 #### `attachment(filename: string): string`
 
@@ -242,6 +245,38 @@ Calls the handler for the most preferred type, then `default`, then answers
 `406 Not Acceptable`. `respond.Handlers` holds an optional `() => Response` per shorthand
 plus `default`.
 
+### `@sdxc/http/deprecation`
+
+#### `setDeprecation(headers: Headers, notice: DeprecationNotice): Result<void, DeprecationNoticeError>`
+
+Writes the RFC 9745 `Deprecation` and RFC 8594 `Sunset` fields and their `deprecation` and
+`sunset` links, keeping the response's other links. Fails for a sunset earlier than the
+deprecation.
+
+```typescript
+setDeprecation(response.headers, {
+	deprecation: new Date("2026-12-01T00:00:00Z"),
+	sunset: new Date("2027-06-01T00:00:00Z"),
+	deprecationLink: "https://example.com/changelog",
+});
+```
+
+#### `getDeprecation(headers: Headers): DeprecationNotice | null`
+
+Reads the notice back on the client, leaving out any field that does not parse.
+
+### `@sdxc/http/retry-after`
+
+#### `parseRetryAfter(value: string | null, now?: Date): number | null`
+
+Reads a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#section-10.2.3) as
+milliseconds to wait, from delay-seconds or an HTTP-date measured from `now` (a past date
+is `0`). Anything else is `null`.
+
+```typescript
+let wait = parseRetryAfter(response.headers.get("Retry-After")) ?? backoff(attempt);
+```
+
 ### `@sdxc/http/cache`
 
 Built on the typed `CacheControl` header from `remix/headers`. Every age is a duration
@@ -260,6 +295,13 @@ policy({ visibility: "public", maxAge: "1 hour", sMaxAge: "1 day" }).toString();
 // "public, max-age=3600, s-maxage=86400"
 ```
 
+#### `targetedPolicy(options?: PolicyOptions): string` and `parseTargetedPolicy(value: string | null): CacheControl | null`
+
+Write and read [RFC 9213](https://www.rfc-editor.org/rfc/rfc9213) targeted fields such as
+`CDN-Cache-Control`, as Structured Field Dictionaries, to give an edge its own lifetime
+(`targetedPolicy({ maxAge: "1 day" })` is `"max-age=86400"`). The parser answers `null` for
+a field a cache ignores: absent, empty or invalid.
+
 #### `Policies`
 
 The recurring policies, each returning a `CacheControl`:

package/dist/cache/index.d.ts

@@ -2,6 +2,7 @@
  * Public surface of the cache subpath: policies that decide who may store a
  * response and for how long, validators that identify its content, and the
  * conditional-request handling that turns a current client copy into a `304`.
+ * Targeted fields give an edge cache its own lifetime apart from the browser's.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -17,4 +18,5 @@ export { ifModifiedSince, isModifiedSince } from "./if-modified-since.js";
 export { Policies } from "./policies.js";
 export { policy } from "./policy.js";
 export { precondition, PreconditionFailedError } from "./precondition.js";
+export { parseTargetedPolicy, targetedPolicy } from "./targeted.js";
 export { vary } from "./vary.js";

package/dist/cache/index.js

@@ -2,6 +2,7 @@
  * Public surface of the cache subpath: policies that decide who may store a
  * response and for how long, validators that identify its content, and the
  * conditional-request handling that turns a current client copy into a `304`.
+ * Targeted fields give an edge cache its own lifetime apart from the browser's.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -13,4 +14,5 @@ export { ifModifiedSince, isModifiedSince } from "./if-modified-since.js";
 export { Policies } from "./policies.js";
 export { policy } from "./policy.js";
 export { precondition, PreconditionFailedError } from "./precondition.js";
+export { parseTargetedPolicy, targetedPolicy } from "./targeted.js";
 export { vary } from "./vary.js";

package/dist/cache/targeted.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Writes and reads RFC 9213 targeted cache fields such as `CDN-Cache-Control`, which give one
+ * class of cache (a CDN, or one vendor's edge) its own lifetime apart from `Cache-Control`.
+ * They are Structured Field Dictionaries, so both directions go through that grammar.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { CacheControl } from "remix/headers";
+import type { PolicyOptions } from "./policy.js";
+/**
+ * Builds a targeted cache field value from the same description `policy()` takes, so an
+ * edge-only lifetime reads like any other. An empty description yields `""`, which caches
+ * ignore, leaving `Cache-Control` in charge.
+ *
+ * @param options - Visibility, ages, and directives to emit; all optional.
+ * @returns The Structured Field Dictionary text for `CDN-Cache-Control` and its kin.
+ * @example
+ * headers.set("CDN-Cache-Control", targetedPolicy({ maxAge: "1 day" })); // "max-age=86400"
+ */
+export declare function targetedPolicy(options?: PolicyOptions): string;
+/**
+ * Reads a targeted cache field. `null` means a cache ignores the field (absent, empty, or not a
+ * valid Dictionary) and falls back to the next one; any other result governs, even with no
+ * known directive. Parameters, unknown directives and ill-typed values are skipped.
+ *
+ * @param value - The field value, as `Headers#get` returns it.
+ * @returns The directives the field sets, or `null` when the field is ignored.
+ * @example
+ * parseTargetedPolicy(response.headers.get("CDN-Cache-Control"))?.maxAge; // 86400
+ */
+export declare function parseTargetedPolicy(value: string | null | undefined): CacheControl | null;

package/dist/cache/targeted.js

@@ -0,0 +1,112 @@
+/**
+ * Writes and reads RFC 9213 targeted cache fields such as `CDN-Cache-Control`, which give one
+ * class of cache (a CDN, or one vendor's edge) its own lifetime apart from `Cache-Control`.
+ * They are Structured Field Dictionaries, so both directions go through that grammar.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure } from "@sdxc/result";
+import { parse, stringify } from "@sdxc/structured-fields";
+import { CacheControl } from "remix/headers";
+import { policy } from "./policy.js";
+/** Directives whose value is an Integer number of seconds, in the order they are written. */
+const AGE_DIRECTIVES = [
+    ["max-age", "maxAge"],
+    ["s-maxage", "sMaxage"],
+    ["stale-while-revalidate", "staleWhileRevalidate"],
+    ["stale-if-error", "staleIfError"],
+];
+/** Directives written as a bare key, in the order they are written. */
+const FLAG_DIRECTIVES = [
+    ["public", "public"],
+    ["private", "private"],
+    ["no-cache", "noCache"],
+    ["no-store", "noStore"],
+    ["no-transform", "noTransform"],
+    ["must-revalidate", "mustRevalidate"],
+    ["proxy-revalidate", "proxyRevalidate"],
+    ["must-understand", "mustUnderstand"],
+    ["immutable", "immutable"],
+];
+/**
+ * Directives that may instead carry a String listing field names. A cache reading one takes
+ * the unqualified directive, which withholds the whole response rather than some fields.
+ */
+const QUALIFIABLE_DIRECTIVES = new Set(["private", "no-cache"]);
+/** The largest Integer a Structured Field can carry. */
+const MAX_INTEGER = 999_999_999_999_999;
+/**
+ * Builds a targeted cache field value from the same description `policy()` takes, so an
+ * edge-only lifetime reads like any other. An empty description yields `""`, which caches
+ * ignore, leaving `Cache-Control` in charge.
+ *
+ * @param options - Visibility, ages, and directives to emit; all optional.
+ * @returns The Structured Field Dictionary text for `CDN-Cache-Control` and its kin.
+ * @example
+ * headers.set("CDN-Cache-Control", targetedPolicy({ maxAge: "1 day" })); // "max-age=86400"
+ */
+export function targetedPolicy(options = {}) {
+    let control = policy(options);
+    let dictionary = {};
+    for (let [name, key] of FLAG_DIRECTIVES)
+        if (control[key])
+            dictionary[name] = true;
+    for (let [name, key] of AGE_DIRECTIVES) {
+        let seconds = control[key];
+        if (seconds !== undefined)
+            dictionary[name] = Math.min(Math.max(seconds, 0), MAX_INTEGER);
+    }
+    let text = stringify(dictionary, "dictionary");
+    return isFailure(text) ? "" : text.data;
+}
+/**
+ * Reads a targeted cache field. `null` means a cache ignores the field (absent, empty, or not a
+ * valid Dictionary) and falls back to the next one; any other result governs, even with no
+ * known directive. Parameters, unknown directives and ill-typed values are skipped.
+ *
+ * @param value - The field value, as `Headers#get` returns it.
+ * @returns The directives the field sets, or `null` when the field is ignored.
+ * @example
+ * parseTargetedPolicy(response.headers.get("CDN-Cache-Control"))?.maxAge; // 86400
+ */
+export function parseTargetedPolicy(value) {
+    if (value === null || value === undefined)
+        return null;
+    let parsed = parse(value, "dictionary");
+    if (isFailure(parsed))
+        return null;
+    let members = Object.entries(parsed.data);
+    if (members.length === 0)
+        return null;
+    let init = {};
+    for (let [name, member] of members) {
+        if ("items" in member)
+            continue;
+        readDirective(init, name, member.value);
+    }
+    return new CacheControl(init);
+}
+/**
+ * Copies one directive into the init when its value has the type the directive allows: a
+ * non-negative Integer for an age, Boolean true for a flag, or a String for `private` and
+ * `no-cache`. Anything else is skipped, since coercing it would diverge from other caches.
+ *
+ * @param init - The directives read so far.
+ * @param name - The directive's key in the Dictionary.
+ * @param value - The member's bare value.
+ */
+function readDirective(init, name, value) {
+    let age = AGE_DIRECTIVES.find(([directive]) => directive === name);
+    if (age) {
+        if (typeof value === "number" && Number.isInteger(value) && value >= 0)
+            init[age[1]] = value;
+        return;
+    }
+    let flag = FLAG_DIRECTIVES.find(([directive]) => directive === name);
+    if (!flag)
+        return;
+    if (value === true || (QUALIFIABLE_DIRECTIVES.has(name) && typeof value === "string")) {
+        init[flag[1]] = true;
+    }
+}

package/dist/deprecation.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Deprecation signalling on the Fetch API: the RFC 9745 `Deprecation` field, the RFC 8594
+ * `Sunset` field and their `deprecation` and `sunset` link relations, written by a server
+ * announcing a resource's retirement and read back by a client watching for one.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+/**
+ * What a response announces about its resource's retirement. Every member is optional:
+ * a resource may publish its deprecation policy link long before it names a date.
+ */
+export interface DeprecationNotice {
+    /** When the resource was deprecated, or will be when the date is in the future. */
+    deprecation?: Date;
+    /** When the resource is expected to stop answering; never earlier than `deprecation`. */
+    sunset?: Date;
+    /** Documentation of the deprecation and how to migrate, linked with `rel="deprecation"`. */
+    deprecationLink?: string;
+    /** Documentation of the retirement policy, linked with `rel="sunset"`. */
+    sunsetLink?: string;
+}
+/**
+ * A notice the fields cannot carry: an invalid `Date`, or a sunset earlier than the
+ * deprecation, which RFC 9745 forbids a server to send.
+ */
+export declare class DeprecationNoticeError extends Error {
+    name: "DeprecationNoticeError";
+}
+/**
+ * Writes a notice onto response headers, replacing any `Deprecation`, `Sunset` and
+ * `deprecation`/`sunset` links already there and keeping every other link. Dates are
+ * truncated to whole seconds, the precision both fields carry.
+ *
+ * @param headers - The response headers to write.
+ * @param notice - What to announce.
+ * @returns Success once written, or why the notice is invalid, leaving `headers` untouched.
+ * @example setDeprecation(response.headers, { deprecation: new Date("2026-12-01T00:00:00Z"), sunset: new Date("2027-06-01T00:00:00Z"), deprecationLink: "https://example.com/changelog" });
+ * @example setDeprecation(response.headers, { deprecationLink: "https://example.com/deprecation-policy" });
+ */
+export declare function setDeprecation(headers: Headers, notice: DeprecationNotice): Result<void, DeprecationNoticeError>;
+/**
+ * Reads the notice a response carries. Both fields are hints a client must work without,
+ * so an unreadable one is left out of the notice: a `Sunset` reads in any spelling
+ * `Date.parse` accepts, including the `UTC` zone RFC 9745's own example uses.
+ *
+ * @param headers - The response headers to read.
+ * @returns The notice, or `null` when the response announces nothing.
+ * @example
+ * let notice = getDeprecation(response.headers);
+ * if (notice?.deprecation) log.warn("Deprecated endpoint", { deprecation: notice.deprecation });
+ */
+export declare function getDeprecation(headers: Headers): DeprecationNotice | null;

package/dist/deprecation.js

@@ -0,0 +1,98 @@
+import { parse as parseLinks, serializeLink, stringify as stringifyLinks } from "@sdxc/link-header";
+import { failure, isFailure, success } from "@sdxc/result";
+import { getField, setField } from "@sdxc/structured-fields";
+/**
+ * A notice the fields cannot carry: an invalid `Date`, or a sunset earlier than the
+ * deprecation, which RFC 9745 forbids a server to send.
+ */
+export class DeprecationNoticeError extends Error {
+    name = "DeprecationNoticeError";
+}
+/** The relation types this module owns inside a `Link` field. */
+const RELATIONS = ["deprecation", "sunset"];
+/**
+ * Writes a notice onto response headers, replacing any `Deprecation`, `Sunset` and
+ * `deprecation`/`sunset` links already there and keeping every other link. Dates are
+ * truncated to whole seconds, the precision both fields carry.
+ *
+ * @param headers - The response headers to write.
+ * @param notice - What to announce.
+ * @returns Success once written, or why the notice is invalid, leaving `headers` untouched.
+ * @example setDeprecation(response.headers, { deprecation: new Date("2026-12-01T00:00:00Z"), sunset: new Date("2027-06-01T00:00:00Z"), deprecationLink: "https://example.com/changelog" });
+ * @example setDeprecation(response.headers, { deprecationLink: "https://example.com/deprecation-policy" });
+ */
+export function setDeprecation(headers, notice) {
+    let deprecation = notice.deprecation === undefined ? undefined : wholeSeconds(notice.deprecation);
+    let sunset = notice.sunset === undefined ? undefined : wholeSeconds(notice.sunset);
+    if (deprecation !== undefined && Number.isNaN(deprecation.getTime())) {
+        return failure(new DeprecationNoticeError("The deprecation date is invalid"));
+    }
+    if (sunset !== undefined && Number.isNaN(sunset.getTime())) {
+        return failure(new DeprecationNoticeError("The sunset date is invalid"));
+    }
+    if (deprecation !== undefined && sunset !== undefined && sunset < deprecation) {
+        return failure(new DeprecationNoticeError("The sunset date is earlier than the deprecation"));
+    }
+    headers.delete("Deprecation");
+    if (deprecation !== undefined) {
+        let written = setField(headers, "Deprecation", deprecation, "item");
+        if (isFailure(written))
+            return failure(new DeprecationNoticeError(written.error.message));
+    }
+    if (sunset === undefined)
+        headers.delete("Sunset");
+    else
+        headers.set("Sunset", sunset.toUTCString());
+    let links = [];
+    for (let link of parseLinks(headers.get("Link"))) {
+        if (!link.rels.some((rel) => RELATIONS.includes(rel))) {
+            links.push(link.raw);
+        }
+    }
+    if (notice.deprecationLink !== undefined) {
+        links.push(serializeLink(notice.deprecationLink, "deprecation"));
+    }
+    if (notice.sunsetLink !== undefined)
+        links.push(serializeLink(notice.sunsetLink, "sunset"));
+    let link = stringifyLinks(links);
+    if (link === null)
+        headers.delete("Link");
+    else
+        headers.set("Link", link);
+    return success(undefined);
+}
+/**
+ * Reads the notice a response carries. Both fields are hints a client must work without,
+ * so an unreadable one is left out of the notice: a `Sunset` reads in any spelling
+ * `Date.parse` accepts, including the `UTC` zone RFC 9745's own example uses.
+ *
+ * @param headers - The response headers to read.
+ * @returns The notice, or `null` when the response announces nothing.
+ * @example
+ * let notice = getDeprecation(response.headers);
+ * if (notice?.deprecation) log.warn("Deprecated endpoint", { deprecation: notice.deprecation });
+ */
+export function getDeprecation(headers) {
+    let notice = {};
+    let deprecation = getField(headers, "Deprecation", "item");
+    if (!isFailure(deprecation) && deprecation.data?.value instanceof Date) {
+        notice.deprecation = deprecation.data.value;
+    }
+    let sunset = headers.get("Sunset");
+    let sunsetTime = sunset === null ? Number.NaN : Date.parse(sunset);
+    if (!Number.isNaN(sunsetTime))
+        notice.sunset = new Date(sunsetTime);
+    for (let link of parseLinks(headers.get("Link"))) {
+        if (notice.deprecationLink === undefined && link.rels.includes("deprecation")) {
+            notice.deprecationLink = link.target;
+        }
+        if (notice.sunsetLink === undefined && link.rels.includes("sunset")) {
+            notice.sunsetLink = link.target;
+        }
+    }
+    return Object.keys(notice).length === 0 ? null : notice;
+}
+/** Drops the milliseconds an HTTP-date and an sf-date cannot represent. */
+function wholeSeconds(date) {
+    return new Date(Math.floor(date.getTime() / 1000) * 1000);
+}

package/dist/negotiate.js

@@ -5,7 +5,7 @@
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
-const shortToMime = new Map([
+const SHORT_TO_MIME = new Map([
     ["json", ["application/json"]],
     ["html", ["text/html"]],
     ["xml", ["application/xml", "text/xml"]],
@@ -16,7 +16,7 @@ const shortToMime = new Map([
     ["csv", ["text/csv"]],
     ["pdf", ["application/pdf"]],
 ]);
-const mimeToShort = new Map([
+const MIME_TO_SHORT = new Map([
     ["application/json", "json"],
     ["text/html", "html"],
     ["application/xml", "xml"],
@@ -86,7 +86,7 @@ export class AcceptList {
      * @returns The shorthand type or null if not recognized
      */
     toShortType(mimeType) {
-        return mimeToShort.get(mimeType) ?? null;
+        return MIME_TO_SHORT.get(mimeType) ?? null;
     }
     parseAcceptHeader(header) {
         return header
@@ -105,7 +105,7 @@ export class AcceptList {
             .map(({ type }) => type);
     }
     resolveType(type) {
-        return shortToMime.get(type) ?? [type];
+        return SHORT_TO_MIME.get(type) ?? [type];
     }
 }
 /**

package/dist/response.d.ts

@@ -123,7 +123,8 @@ export declare function pdf(body: Blob | ArrayBuffer | ReadableStream, init?: Re
 export declare function attachment(filename: string): string;
 /**
  * Creates a Response for a file download, with the name written by `attachment` so a quote
- * or a non-ASCII character in it reaches the client intact.
+ * or a non-ASCII character in it reaches the client intact. A `Content-Type` in `init` names
+ * the file's type; without one the download is `application/octet-stream`.
  * @param body - The file content as Blob, ArrayBuffer, or ReadableStream
  * @param filename - The filename to suggest for the download
  * @param init - Optional response options (status, headers, etc.)
@@ -131,7 +132,7 @@ export declare function attachment(filename: string): string;
  * @example
  * return file(zipBuffer, "archive.zip");
  * @example
- * return file(imageBlob, "photo.png", { headers: { "Cache-Control": "no-store" } });
+ * return file(zipBuffer, "archive.zip", { headers: { "Content-Type": ContentType.ZIP } });
  */
 export declare function file(body: Blob | ArrayBuffer | ReadableStream, filename: string, init?: ResponseInit): Response;
 /**

package/dist/response.js

@@ -187,7 +187,8 @@ export function attachment(filename) {
 }
 /**
  * Creates a Response for a file download, with the name written by `attachment` so a quote
- * or a non-ASCII character in it reaches the client intact.
+ * or a non-ASCII character in it reaches the client intact. A `Content-Type` in `init` names
+ * the file's type; without one the download is `application/octet-stream`.
  * @param body - The file content as Blob, ArrayBuffer, or ReadableStream
  * @param filename - The filename to suggest for the download
  * @param init - Optional response options (status, headers, etc.)
@@ -195,11 +196,12 @@ export function attachment(filename) {
  * @example
  * return file(zipBuffer, "archive.zip");
  * @example
- * return file(imageBlob, "photo.png", { headers: { "Cache-Control": "no-store" } });
+ * return file(zipBuffer, "archive.zip", { headers: { "Content-Type": ContentType.ZIP } });
  */
 export function file(body, filename, init) {
     let headers = new Headers(init?.headers);
-    headers.set("Content-Type", ContentType.OctetStream);
+    if (!headers.has("Content-Type"))
+        headers.set("Content-Type", ContentType.OctetStream);
     headers.set("Content-Disposition", attachment(filename));
     return new Response(body, { ...init, headers });
 }

package/dist/retry-after.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The RFC 9110 `Retry-After` field read as a wait in milliseconds, from either of its
+ * forms: delay-seconds or an HTTP-date, the date in any of the three spellings a
+ * recipient must accept, so every client backs off by the same reading of the header.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Reads how long a `Retry-After` asks the client to wait. Delay-seconds count from the
+ * answer; a date counts from `now`, and one already past reads as `0`. A value in neither
+ * form, a negative or fractional number included, reads as `null`, so the caller falls
+ * back to its own backoff.
+ *
+ * @param value - The header's value, or `null` when the response carried none.
+ * @param now - The time the answer arrived, which a date is measured from.
+ * @default now new Date()
+ * @returns Milliseconds to wait, or `null` when the header names no usable delay.
+ * @example
+ * parseRetryAfter(response.headers.get("Retry-After")); // 120000 for "120"
+ * @example
+ * parseRetryAfter("Wed, 21 Oct 2015 07:28:30 GMT", new Date("2015-10-21T07:28:00Z")); // 30000
+ */
+export declare function parseRetryAfter(value: string | null, now?: Date): number | null;

package/dist/retry-after.js

@@ -0,0 +1,99 @@
+/**
+ * The RFC 9110 `Retry-After` field read as a wait in milliseconds, from either of its
+ * forms: delay-seconds or an HTTP-date, the date in any of the three spellings a
+ * recipient must accept, so every client backs off by the same reading of the header.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** RFC 9110 `delay-seconds`: one or more digits, nothing else. */
+const DELAY_SECONDS = /^\d+$/;
+/** The preferred spelling: `Sun, 06 Nov 1994 08:49:37 GMT`. */
+const IMF_FIXDATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) ([A-Z][a-z]{2}) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+/** The obsolete RFC 850 spelling, with a two-digit year: `Sunday, 06-Nov-94 08:49:37 GMT`. */
+const RFC_850_DATE = /^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-([A-Z][a-z]{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+/** The obsolete asctime spelling, always UTC: `Sun Nov  6 08:49:37 1994`. */
+const ASCTIME_DATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) ([A-Z][a-z]{2}) ([ \d]\d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
+/** Month names in the order `Date.UTC` numbers them from zero. */
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/**
+ * Reads how long a `Retry-After` asks the client to wait. Delay-seconds count from the
+ * answer; a date counts from `now`, and one already past reads as `0`. A value in neither
+ * form, a negative or fractional number included, reads as `null`, so the caller falls
+ * back to its own backoff.
+ *
+ * @param value - The header's value, or `null` when the response carried none.
+ * @param now - The time the answer arrived, which a date is measured from.
+ * @default now new Date()
+ * @returns Milliseconds to wait, or `null` when the header names no usable delay.
+ * @example
+ * parseRetryAfter(response.headers.get("Retry-After")); // 120000 for "120"
+ * @example
+ * parseRetryAfter("Wed, 21 Oct 2015 07:28:30 GMT", new Date("2015-10-21T07:28:00Z")); // 30000
+ */
+export function parseRetryAfter(value, now = new Date()) {
+    if (value === null)
+        return null;
+    let text = value.trim();
+    if (DELAY_SECONDS.test(text))
+        return Number(text) * 1000;
+    let date = parseHttpDate(text, now);
+    if (date === null)
+        return null;
+    return Math.max(0, date - now.getTime());
+}
+/**
+ * Parses an RFC 9110 HTTP-date in any of its three spellings as epoch milliseconds. A
+ * two-digit RFC 850 year more than 50 years past `now` belongs to the previous century.
+ *
+ * @param text - The trimmed header value.
+ * @param now - The clock a two-digit year is placed against.
+ * @returns The instant, or `null` for any other text or an impossible date.
+ */
+function parseHttpDate(text, now) {
+    let imf = IMF_FIXDATE.exec(text);
+    if (imf) {
+        let [, day = "", month = "", year = "", hour = "", minute = "", second = ""] = imf;
+        return toTime({ year: Number(year), month, day, hour, minute, second });
+    }
+    let rfc850 = RFC_850_DATE.exec(text);
+    if (rfc850) {
+        let [, day = "", month = "", year = "", hour = "", minute = "", second = ""] = rfc850;
+        let current = now.getUTCFullYear();
+        let full = current - (current % 100) + Number(year);
+        if (full > current + 50)
+            full -= 100;
+        return toTime({ year: full, month, day, hour, minute, second });
+    }
+    let asctime = ASCTIME_DATE.exec(text);
+    if (asctime) {
+        let [, month = "", day = "", hour = "", minute = "", second = "", year = ""] = asctime;
+        return toTime({ year: Number(year), month, day: day.trim(), hour, minute, second });
+    }
+    return null;
+}
+/**
+ * Turns date parts into epoch milliseconds in UTC, refusing a date `Date.UTC` would roll
+ * over (31 February, hour 24), so a malformed header never becomes a wrong wait.
+ *
+ * @param parts - The parts one spelling captured.
+ * @returns The instant, or `null` when the parts name no real date.
+ */
+function toTime(parts) {
+    let month = MONTHS.indexOf(parts.month);
+    if (month === -1)
+        return null;
+    let day = Number(parts.day);
+    let hour = Number(parts.hour);
+    let minute = Number(parts.minute);
+    let second = Number(parts.second);
+    let time = Date.UTC(parts.year, month, day, hour, minute, second);
+    let date = new Date(time);
+    let exact = date.getUTCFullYear() === parts.year &&
+        date.getUTCMonth() === month &&
+        date.getUTCDate() === day &&
+        date.getUTCHours() === hour &&
+        date.getUTCMinutes() === minute &&
+        date.getUTCSeconds() === second;
+    return exact ? time : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/http",
-	"version": "2026.10.24",
+	"version": "2026.10.26",
 	"description": "Response builders, content negotiation, and HTTP caching for the Fetch API",
 	"license": "MIT",
 	"type": "module",
@@ -11,19 +11,23 @@
 		"./response/json": "./dist/response/json.js",
 		"./response/html": "./dist/response/html.js",
 		"./negotiate": "./dist/negotiate.js",
+		"./deprecation": "./dist/deprecation.js",
+		"./retry-after": "./dist/retry-after.js",
 		"./cache": "./dist/cache/index.js",
 		"./middleware/head-requests": "./dist/middleware/head-requests.js"
 	},
 	"dependencies": {
 		"@sdxc/crypto": "2026.10.23",
 		"@sdxc/duration": "2026.10.13",
+		"@sdxc/link-header": "2026.10.25",
 		"@sdxc/location": "2026.10.13",
-		"@sdxc/result": "2026.10.13"
+		"@sdxc/result": "2026.10.13",
+		"@sdxc/structured-fields": "2026.10.25"
 	},
 	"peerDependencies": {
 		"remix": "3.1.0"
 	},
-	"gitHead": "f9db0f8f1f51a256e74b94b0f4b1db4be9880370",
+	"gitHead": "ff18988bd00de6200766dbc77367257277979566",
 	"publishConfig": {
 		"access": "public"
 	},