@sdxc/http 2026.10.25 → 2026.11.3

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, deprecation notices, 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
 
@@ -174,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`
 
@@ -264,6 +265,18 @@ setDeprecation(response.headers, {
 
 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

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.25",
+	"version": "2026.11.3",
 	"description": "Response builders, content negotiation, and HTTP caching for the Fetch API",
 	"license": "MIT",
 	"type": "module",
@@ -12,11 +12,12 @@
 		"./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/crypto": "2026.11.3",
 		"@sdxc/duration": "2026.10.13",
 		"@sdxc/link-header": "2026.10.25",
 		"@sdxc/location": "2026.10.13",
@@ -26,7 +27,7 @@
 	"peerDependencies": {
 		"remix": "3.1.0"
 	},
-	"gitHead": "1440b969c0a3e3808dfcee3f17d2ef43915f32a8",
+	"gitHead": "d1dd4030f8df68b8a170940a3f790ea8654d3676",
 	"publishConfig": {
 		"access": "public"
 	},