@jongleberry/api-server 2.0.0 → 2.1.0

package/README.md

@@ -53,6 +53,8 @@ app.route("/").get((ctx) => ctx.json({ ok: true }));
 - **Cookies** — `ctx.cookies.get()` / `.set()` with full `Set-Cookie` options
 - **Cache-Control** — `ctx.cacheControl(visibility, maxAge)` helper
 - **Trusted client IP** — proxy headers are opt-in via `trustProxy`; standalone helpers support Node, Deno, and Bun
+- **HTTP retry primitives** — strict Retry-After parsing, code-based network classification, and pure backoff calculation
+- **SHA-256** — standalone Node digest bytes shared by ETag generation
 - **Dev logger** — concurrent-request bar, color-coded status codes, timing thresholds; silent in `NODE_ENV=production` and `NODE_ENV=test`
 - **Error safety net** — error handlers that throw or return without a response still guarantee the client receives a response
 
@@ -65,24 +67,26 @@ app.route("/").get((ctx) => ctx.json({ ok: true }));
 
 See [docs/](docs/README.md) for full API reference:
 
-| Topic                                              | Description                                         |
-| -------------------------------------------------- | --------------------------------------------------- |
-| [Getting started](docs/getting-started.md)         | Install, hello world, mounting on http.createServer |
-| [Routing](docs/routing.md)                         | Route registration, params, notFoundHandler         |
-| [Context](docs/context.md)                         | Full `ctx` API surface                              |
-| [Request](docs/request.md)                         | Body parsing, size limits, content-type detection   |
-| [Response](docs/response.md)                       | Buffered and streaming responses                    |
-| [ETag and caching](docs/etag-and-caching.md)       | Automatic ETags, 304s, Cache-Control                |
-| [Compression](docs/compression.md)                 | br/gzip/deflate negotiation                         |
-| [Server-Timing](docs/server-timing.md)             | Response latency headers and trailers               |
-| [Cookies](docs/cookies.md)                         | Reading and writing cookies                         |
-| [Error handling](docs/error-handling.md)           | errorHandler, notFoundHandler, http-errors          |
-| [Async local storage](docs/async-local-storage.md) | Per-request store                                   |
-| [Abort signals](docs/abort-signals.md)             | Client-disconnect propagation                       |
-| [Logger](docs/logger.md)                           | Dev logger configuration                            |
-| [Trusted client IP](docs/trusted-client-ip.md)     | Node, Deno, and Bun client IP helpers               |
-| [Extending context](docs/extending-context.md)     | Adding methods to ctx                               |
-| [Testing](docs/testing.md)                         | Testing patterns with vitest and supertest          |
+| Topic                                              | Description                                              |
+| -------------------------------------------------- | -------------------------------------------------------- |
+| [Getting started](docs/getting-started.md)         | Install, hello world, mounting on http.createServer      |
+| [Routing](docs/routing.md)                         | Route registration, params, notFoundHandler              |
+| [Context](docs/context.md)                         | Full `ctx` API surface                                   |
+| [Request](docs/request.md)                         | Body parsing, size limits, content-type detection        |
+| [Response](docs/response.md)                       | Buffered and streaming responses                         |
+| [ETag and caching](docs/etag-and-caching.md)       | Automatic ETags, 304s, Cache-Control                     |
+| [Compression](docs/compression.md)                 | br/gzip/deflate negotiation                              |
+| [Server-Timing](docs/server-timing.md)             | Response latency headers and trailers                    |
+| [Cookies](docs/cookies.md)                         | Reading and writing cookies                              |
+| [Error handling](docs/error-handling.md)           | errorHandler, notFoundHandler, http-errors               |
+| [Async local storage](docs/async-local-storage.md) | Per-request store                                        |
+| [Abort signals](docs/abort-signals.md)             | Client-disconnect propagation                            |
+| [Logger](docs/logger.md)                           | Dev logger configuration                                 |
+| [Trusted client IP](docs/trusted-client-ip.md)     | Node, Deno, and Bun client IP helpers                    |
+| [HTTP retry](docs/http-retry.md)                   | Strict header, Retry-After, network, and backoff helpers |
+| [SHA-256](docs/sha256.md)                          | Node digest helper and ETag reuse                        |
+| [Extending context](docs/extending-context.md)     | Adding methods to ctx                                    |
+| [Testing](docs/testing.md)                         | Testing patterns with vitest and supertest               |
 
 ## Design
 

package/dist/etag.mjs

@@ -1,6 +1,6 @@
-import crypto from "node:crypto";
+import { sha256 } from "./sha256.mjs";
 export function generateETag(body) {
-    const hash = crypto.createHash("sha256").update(body).digest("base64url");
+    const hash = sha256(body).toString("base64url");
     return `"${hash}"`;
 }
 export function isFresh(req, etag) {

package/dist/http-retry.d.mts

@@ -0,0 +1,19 @@
+export type HeaderValue = string | string[];
+export type HeaderGetter = {
+    get(name: string): string | null;
+};
+export type HeaderSource = HeaderGetter | Record<string, unknown> | null | undefined;
+export interface ExponentialBackoffOptions {
+    attempt: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    random: number;
+}
+/** Reads Fetch or Node-style headers without assuming a particular casing. */
+export declare function getHeaderValue(headers: HeaderSource, name: string): HeaderValue | undefined;
+/** Parses a single Retry-After field into milliseconds using the supplied or current clock. */
+export declare function parseRetryAfter(value: HeaderValue | null | undefined, now?: number): number | null;
+/** Classifies only known network error codes, following a finite error cause chain. */
+export declare function isRetryableNetworkError(error: unknown): boolean;
+/** Returns capped exponential delay with deterministic full jitter; it never sleeps. */
+export declare function computeExponentialBackoffMs(options: ExponentialBackoffOptions): number;

package/dist/http-retry.mjs

@@ -0,0 +1,117 @@
+const RETRYABLE_NETWORK_CODES = new Set([
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EPIPE",
+    "ETIMEDOUT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+const DECIMAL_SECONDS = /^(?:0|[1-9]\d*)$/;
+const HTTP_DATE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+function isHeaderGetter(headers) {
+    return typeof headers?.get === "function";
+}
+function normalizeHeaderValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    if (Array.isArray(value) && value.every((item) => typeof item === "string"))
+        return value;
+    return undefined;
+}
+/** Reads Fetch or Node-style headers without assuming a particular casing. */
+export function getHeaderValue(headers, name) {
+    if (!headers)
+        return undefined;
+    if (isHeaderGetter(headers))
+        return headers.get(name) ?? undefined;
+    const matchingEntries = Object.entries(headers).filter(([key]) => key.toLowerCase() === name.toLowerCase());
+    if (matchingEntries.length !== 1)
+        return undefined;
+    return normalizeHeaderValue(matchingEntries[0][1]);
+}
+/** Parses a single Retry-After field into milliseconds using the supplied or current clock. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (typeof value !== "string" || !Number.isFinite(now))
+        return null;
+    if (DECIMAL_SECONDS.test(value)) {
+        const seconds = Number(value);
+        return Number.isSafeInteger(seconds) && Number.isSafeInteger(seconds * 1_000)
+            ? seconds * 1_000
+            : null;
+    }
+    if (!HTTP_DATE.test(value))
+        return null;
+    const retryAt = Date.parse(value);
+    if (Number.isNaN(retryAt) || new Date(retryAt).toUTCString() !== value)
+        return null;
+    return Math.max(0, retryAt - now);
+}
+function isObject(value) {
+    return (typeof value === "object" && value !== null) || typeof value === "function";
+}
+function errorDetails(value) {
+    try {
+        const error = value;
+        return { code: error.code, cause: error.cause, name: error.name };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Classifies only known network error codes, following a finite error cause chain. */
+export function isRetryableNetworkError(error) {
+    const seen = new Set();
+    let retryable = false;
+    let current = error;
+    while (isObject(current) && !seen.has(current)) {
+        seen.add(current);
+        const details = errorDetails(current);
+        if (!details || details.name === "AbortError")
+            return false;
+        if (typeof details.code === "string" && RETRYABLE_NETWORK_CODES.has(details.code)) {
+            retryable = true;
+        }
+        current = details.cause;
+    }
+    return retryable;
+}
+function assertBackoffOptions(options) {
+    const { attempt, baseDelayMs, maxDelayMs, random } = options;
+    if (!Number.isSafeInteger(attempt) ||
+        attempt < 0 ||
+        !Number.isFinite(baseDelayMs) ||
+        baseDelayMs < 0 ||
+        !Number.isFinite(maxDelayMs) ||
+        maxDelayMs < 0 ||
+        !Number.isFinite(random) ||
+        random < 0 ||
+        random > 1) {
+        throw new RangeError("Invalid exponential backoff options");
+    }
+}
+/** Returns capped exponential delay with deterministic full jitter; it never sleeps. */
+export function computeExponentialBackoffMs(options) {
+    assertBackoffOptions(options);
+    const { attempt, baseDelayMs, maxDelayMs, random } = options;
+    if (baseDelayMs === 0 || maxDelayMs === 0 || random === 0)
+        return 0;
+    let capped = Math.min(baseDelayMs, maxDelayMs);
+    let remainingAttempts = attempt;
+    while (remainingAttempts > 0 && capped < maxDelayMs) {
+        if (capped >= maxDelayMs / 2) {
+            capped = maxDelayMs;
+            break;
+        }
+        capped *= 2;
+        remainingAttempts -= 1;
+    }
+    return Math.floor(capped * random);
+}

package/dist/sha256.d.mts

@@ -0,0 +1,2 @@
+/** Returns the SHA-256 digest bytes for a string or visible ArrayBufferView bytes. */
+export declare function sha256(input: string | NodeJS.ArrayBufferView): Buffer;

package/dist/sha256.mjs

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+/** Returns the SHA-256 digest bytes for a string or visible ArrayBufferView bytes. */
+export function sha256(input) {
+    return createHash("sha256").update(input).digest();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jongleberry/api-server",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A Node.js HTTP server library",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -18,6 +18,14 @@
     "./trusted-client-ip": {
       "types": "./dist/trusted-client-ip.d.mts",
       "import": "./dist/trusted-client-ip.mjs"
+    },
+    "./http-retry": {
+      "types": "./dist/http-retry.d.mts",
+      "import": "./dist/http-retry.mjs"
+    },
+    "./sha256": {
+      "types": "./dist/sha256.d.mts",
+      "import": "./dist/sha256.mjs"
     }
   },
   "engines": {