@jongleberry/api-server 1.2.2 → 2.1.0

package/README.md

@@ -42,17 +42,19 @@ app.route("/").get((ctx) => ctx.json({ ok: true }));
 
 - **Trie router** — `find-my-way` under the hood; zero regex overhead on the hot path
 - **Buffered responses** — `ctx.json()`, `ctx.response.text()`, `.html()`, `.xml()`, `.buffer()`
-- **Streaming** — `ctx.pipeline(readable, ...transforms)` with back-pressure and error propagation
+- **Streaming** — `ctx.pipeline(readable, ...transforms)` and `streamJsonObject()` with back-pressure and error propagation
 - **Automatic ETag** — SHA-256 ETag on every buffered 2xx; `If-None-Match` → 304
 - **Compression** — `br` / `gzip` / `deflate` negotiation; 1 KB threshold; `SYNC_FLUSH` for streams
 - **Server-Timing** — response latency as a `Server-Timing` header (buffered) or trailer (streaming)
 - **Abort signals** — `ctx.signal` / `ctx.abortController` wired to client disconnect
 - **Request body limits** — `ctx.request.buffer()` and `.json()` use a safe 1 MB default, with per-call overrides
-- **Opt-in hardening** — fallback CSP, close-on-oversize, and strict HTTP method policies without default behavior changes
+- **Mutation media-type safety** — body-bearing POST/PUT/PATCH/DELETE requests default to JSON, with route-level exceptions
 - **AsyncLocalStorage** — per-request store via `app.setAsyncLocalStorage(als)`
 - **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/application.d.mts

@@ -17,7 +17,6 @@ export declare class Application extends EventEmitter {
     private bodyLimit;
     private readonly securityHeaders;
     private trustProxy;
-    private strictJsonContentType;
     private readonly oversizedBodyStrategy;
     private readonly fallbackContentSecurityPolicy;
     private readonly strictHttpMethods;

package/dist/application.mjs

@@ -1,11 +1,12 @@
 import { EventEmitter } from "node:events";
 import { Context, createContextClass } from "./context.mjs";
-import { createRouteBuilder, isSupportedHttpMethod } from "./router.mjs";
+import { createRouteBuilder, getAcceptedMediaTypes, isSupportedHttpMethod, } from "./router.mjs";
 import Router from "find-my-way";
 import { ServerTiming } from "./server-timing.mjs";
 import { Logger } from "./logger.mjs";
 import { getRawPath } from "./request-path.mjs";
 import { createRequestAbortController } from "./request-abort.mjs";
+import { assertAcceptedMutationMediaType, drainUnreadHttp2Mutation, } from "./mutation-media-type.mjs";
 import { applySecurityHeaders, ensureFallbackHeaders, getFallbackBody, getFallbackStatus, resolveSecurityHeaders, safeString, sendFallback, } from "./fallback-response.mjs";
 export class Application extends EventEmitter {
     router = Router();
@@ -18,7 +19,6 @@ export class Application extends EventEmitter {
     bodyLimit;
     securityHeaders;
     trustProxy;
-    strictJsonContentType;
     oversizedBodyStrategy;
     fallbackContentSecurityPolicy;
     strictHttpMethods;
@@ -28,7 +28,6 @@ export class Application extends EventEmitter {
         this.bodyLimit = options?.bodyLimit ?? "1mb";
         this.securityHeaders = resolveSecurityHeaders(options?.securityHeaders);
         this.trustProxy = options?.trustProxy ?? false;
-        this.strictJsonContentType = options?.strictJsonContentType ?? false;
         this.oversizedBodyStrategy = options?.oversizedBodyStrategy ?? "drain";
         this.fallbackContentSecurityPolicy = options?.fallbackContentSecurityPolicy ?? false;
         this.strictHttpMethods = options?.strictHttpMethods ?? false;
@@ -56,18 +55,13 @@ export class Application extends EventEmitter {
     }
     handleRequest(req, res) {
         const run = () => this.runRequest(req, res).catch((err) => {
-            // Safety net: if runRequest rejects before its own try-catch (e.g. during
-            // context/timing setup), ensure the client always gets a response instead
-            // of a socket hang-up from an unhandled promise rejection.
             const error = err instanceof Error ? err : new Error(safeString(err));
             try {
                 if (this.listenerCount("error") > 0) {
                     this.emit("error", error);
                 }
             }
-            catch {
-                // Swallow listener throws so the 500 response still goes out.
-            }
+            catch { }
             if (!res.headersSent) {
                 ensureFallbackHeaders(res, this.securityHeaders, this.fallbackContentSecurityPolicy);
                 res.writeHead(500);
@@ -86,7 +80,7 @@ export class Application extends EventEmitter {
         const timing = new ServerTiming();
         const ContextClass = this.contextClass;
         const { onWriteHead, onFinish } = this.logger.onRequestStart(req);
-        const ctx = new ContextClass(req, res, {}, timing, this.asyncLocalStorage, abortController, this.bodyLimit, this.trustProxy, onWriteHead, this.strictJsonContentType, this.oversizedBodyStrategy);
+        const ctx = new ContextClass(req, res, {}, timing, this.asyncLocalStorage, abortController, this.bodyLimit, this.trustProxy, onWriteHead, this.oversizedBodyStrategy);
         applySecurityHeaders(res, this.securityHeaders);
         try {
             const method = req.method ?? "GET";
@@ -97,21 +91,29 @@ export class Application extends EventEmitter {
             const rawPath = getRawPath(url);
             const routePath = rawPath.replace(/^\/+/, "/") || "/";
             const found = this.router.find(method, routePath);
-            if (found) {
-                ctx.params = found.params;
-                await found.handler(req, res, found.params, ctx, found.searchParams);
-            }
-            if (!ctx.response.sent) {
-                if (this.notFoundHandlerFn) {
-                    await this.notFoundHandlerFn(ctx);
+            const mediaTypeCheck = assertAcceptedMutationMediaType(req, found ? getAcceptedMediaTypes(found.handler) : undefined);
+            if (mediaTypeCheck)
+                await mediaTypeCheck;
+            try {
+                if (found) {
+                    ctx.params = found.params;
+                    await found.handler(req, res, found.params, ctx, found.searchParams);
                 }
-                else {
-                    ensureFallbackHeaders(res, this.securityHeaders, this.fallbackContentSecurityPolicy);
-                    res.writeHead(404);
-                    res.end("Not Found");
+                if (!ctx.response.sent) {
+                    if (this.notFoundHandlerFn) {
+                        await this.notFoundHandlerFn(ctx);
+                    }
+                    else {
+                        ensureFallbackHeaders(res, this.securityHeaders, this.fallbackContentSecurityPolicy);
+                        res.writeHead(404);
+                        res.end("Not Found");
+                    }
                 }
+                onFinish(res.statusCode);
+            }
+            finally {
+                drainUnreadHttp2Mutation(req);
             }
-            onFinish(res.statusCode);
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(safeString(err));
@@ -127,9 +129,6 @@ export class Application extends EventEmitter {
                         this.emit("error", handlerErr);
                     }
                 }
-                // Safety net: ensure the client always receives a response, even if the
-                // registered error handler threw or returned without sending one. Without
-                // this, requests hang until the socket times out (issue #1948).
                 if (!res.headersSent) {
                     sendFallback(res, this.securityHeaders, this.fallbackContentSecurityPolicy);
                 }

package/dist/context.d.mts

@@ -19,7 +19,7 @@ export declare class Context {
     private queryCache;
     private asyncLocalStorage;
     private trustProxy;
-    constructor(req: IncomingMessage, res: ServerResponse, params: Record<string, string | undefined>, timing: ServerTiming, als: AsyncLocalStorage<unknown> | null, abortController: AbortController, bodyLimit: string | number | false, trustProxy: boolean, onWriteHead?: () => void, strictJsonContentType?: boolean, oversizedBodyStrategy?: OversizedBodyStrategy);
+    constructor(req: IncomingMessage, res: ServerResponse, params: Record<string, string | undefined>, timing: ServerTiming, als: AsyncLocalStorage<unknown> | null, abortController: AbortController, bodyLimit: string | number | false, trustProxy: boolean, onWriteHead?: () => void, oversizedBodyStrategy?: OversizedBodyStrategy);
     get query(): Record<string, string | string[]>;
     get store(): unknown;
     get ip(): string | undefined;

package/dist/context.mjs

@@ -26,11 +26,11 @@ export class Context {
     queryCache = null;
     asyncLocalStorage;
     trustProxy;
-    constructor(req, res, params, timing, als, abortController, bodyLimit, trustProxy, onWriteHead, strictJsonContentType, oversizedBodyStrategy) {
+    constructor(req, res, params, timing, als, abortController, bodyLimit, trustProxy, onWriteHead, oversizedBodyStrategy) {
         this.req = req;
         this.res = res;
         this.params = params;
-        this.request = new Request(req, res, bodyLimit, strictJsonContentType ?? false, oversizedBodyStrategy ?? "drain");
+        this.request = new Request(req, res, bodyLimit, oversizedBodyStrategy ?? "drain");
         this.response = new Response(req, res, timing, onWriteHead);
         this.cookies = new Cookies(req, res);
         this.abortController = abortController;

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/index.d.mts

@@ -10,5 +10,8 @@ export type { LoggerOptions } from "./logger.mts";
 export * from "./etag.mts";
 export * from "./cache-control.mts";
 export * from "./compression.mts";
+export { streamJsonObject } from "./stream-json-object.mts";
+export type { StreamJsonObjectInput } from "./stream-json-object.mts";
 export type { Handler, RouteBuilder } from "./router.mts";
+export type { MutationRouteOptions } from "./mutation-media-type.mts";
 export type { CookieOptions, ApplicationOptions, OversizedBodyStrategy, SecurityHeaderName, SecurityHeadersOptions, } from "./types.mts";

package/dist/index.mjs

@@ -8,3 +8,4 @@ export * from "./logger.mjs";
 export * from "./etag.mjs";
 export * from "./cache-control.mjs";
 export * from "./compression.mjs";
+export { streamJsonObject } from "./stream-json-object.mjs";

package/dist/mutation-media-type.d.mts

@@ -0,0 +1,8 @@
+import type { IncomingMessage } from "node:http";
+export declare const DEFAULT_MUTATION_MEDIA_TYPES: readonly ["application/json", "application/*+json"];
+export interface MutationRouteOptions {
+    /** Replaces the default JSON media types for this mutation route. */
+    acceptedMediaTypes: readonly string[];
+}
+export declare function assertAcceptedMutationMediaType(req: IncomingMessage, acceptedMediaTypes?: readonly string[]): Promise<void> | undefined;
+export declare function drainUnreadHttp2Mutation(req: IncomingMessage): void;

package/dist/mutation-media-type.mjs

@@ -0,0 +1,92 @@
+export const DEFAULT_MUTATION_MEDIA_TYPES = ["application/json", "application/*+json"];
+export function assertAcceptedMutationMediaType(req, acceptedMediaTypes = DEFAULT_MUTATION_MEDIA_TYPES) {
+    const contentType = req.headers["content-type"];
+    const accepted = typeof contentType === "string" &&
+        acceptedMediaTypes.some((type) => matchesMediaType(contentType, type));
+    if (!isMutationMethod(req.method))
+        return;
+    if (req.headers["transfer-encoding"] !== undefined || Number(req.headers["content-length"]) > 0) {
+        if (!accepted)
+            rejectUnsupportedMediaType(req);
+        return;
+    }
+    if (req.httpVersionMajor === 2 && !accepted) {
+        return waitForRejectedHttp2Body(req).then((hasBody) => {
+            if (hasBody)
+                rejectUnsupportedMediaType(req);
+        });
+    }
+    return undefined;
+}
+export function drainUnreadHttp2Mutation(req) {
+    if (req.httpVersionMajor === 2 && isMutationMethod(req.method) && !req.readableEnded)
+        drainRequest(req);
+}
+function isMutationMethod(method) {
+    return method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
+}
+function matchesMediaType(contentType, acceptedMediaType) {
+    const actual = parseMediaType(contentType);
+    const expected = parseMediaType(acceptedMediaType);
+    return (actual !== null &&
+        expected !== null &&
+        matchesToken(actual[0], expected[0]) &&
+        matchesToken(actual[1], expected[1]));
+}
+function parseMediaType(value) {
+    const [type, subtype, ...extra] = value.split(";", 1)[0]?.trim().toLowerCase().split("/") ?? [];
+    return type && subtype && extra.length === 0 ? [type, subtype] : null;
+}
+function matchesToken(actual, expected) {
+    if (!expected.includes("*"))
+        return actual === expected;
+    const parts = expected.split("*");
+    if (!actual.startsWith(parts[0] ?? ""))
+        return false;
+    let offset = (parts[0] ?? "").length;
+    for (const part of parts.slice(1, -1)) {
+        const index = actual.indexOf(part, offset);
+        if (index === -1)
+            return false;
+        offset = index + part.length;
+    }
+    const suffix = parts.at(-1) ?? "";
+    return expected.endsWith("*") || actual.slice(offset).endsWith(suffix);
+}
+function rejectUnsupportedMediaType(req) {
+    drainRequest(req);
+    throw Object.assign(new Error("Unsupported Media Type"), { status: 415 });
+}
+function waitForRejectedHttp2Body(req) {
+    if (req.readableEnded)
+        return Promise.resolve(false);
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            req.removeListener("data", onData);
+            req.removeListener("end", onEnd);
+            req.removeListener("error", onError);
+        };
+        const onData = () => {
+            drainRequest(req);
+            cleanup();
+            resolve(true);
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(false);
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        req.once("data", onData);
+        req.once("end", onEnd);
+        req.once("error", onError);
+        req.resume();
+    });
+}
+function drainRequest(req) {
+    req.on("error", noop);
+    req.resume();
+}
+function noop() { }

package/dist/request.d.mts

@@ -5,9 +5,8 @@ export declare class Request {
     private res;
     private bodyPromise;
     private defaultLimit;
-    private strictJsonContentType;
     private readonly oversizedBodyStrategy;
-    constructor(req: IncomingMessage, res: ServerResponse, defaultLimit?: string | number | false, strictJsonContentType?: boolean, oversizedBodyStrategy?: OversizedBodyStrategy);
+    constructor(req: IncomingMessage, res: ServerResponse, defaultLimit?: string | number | false, oversizedBodyStrategy?: OversizedBodyStrategy);
     is(type: string | string[]): string | false | null;
     buffer(limit?: string | number | false): Promise<Buffer>;
     json<T = unknown>(limit?: string | number | false): Promise<T>;

package/dist/request.mjs

@@ -8,13 +8,11 @@ export class Request {
     res;
     bodyPromise = null;
     defaultLimit;
-    strictJsonContentType;
     oversizedBodyStrategy;
-    constructor(req, res, defaultLimit = "1mb", strictJsonContentType = false, oversizedBodyStrategy = "drain") {
+    constructor(req, res, defaultLimit = "1mb", oversizedBodyStrategy = "drain") {
         this.req = req;
         this.res = res;
         this.defaultLimit = defaultLimit;
-        this.strictJsonContentType = strictJsonContentType;
         this.oversizedBodyStrategy = oversizedBodyStrategy;
     }
     is(type) {
@@ -31,23 +29,6 @@ export class Request {
         return this.bodyPromise;
     }
     async json(limit) {
-        if (this.strictJsonContentType) {
-            // type-is semantics:
-            //   null  → no body (no Content-Length / Transfer-Encoding header);
-            //           skip the content-type check — buffer() will return an empty
-            //           buffer that JSON.parse rejects with 400 as usual.
-            //   false → a body is indicated but Content-Type is not a JSON type.
-            //           We 415 only when the body actually has content (CL > 0 or
-            //           Transfer-Encoding is set without CL). A Content-Length: 0
-            //           body has nothing to read, so let it fall through to 400.
-            //   truthy → recognised JSON type; proceed normally.
-            const mediaType = this.is(["json", "application/*+json"]);
-            const cl = this.req.headers["content-length"];
-            const emptyBody = cl !== undefined && Number(cl) === 0;
-            if (mediaType === false && !emptyBody) {
-                throw Object.assign(new Error("Unsupported Media Type"), { status: 415 });
-            }
-        }
         const buf = await this.buffer(limit);
         try {
             return JSON.parse(buf.toString("utf8"));
@@ -67,6 +48,8 @@ function parseLimit(limit) {
     return parsed;
 }
 function readBody(req, res, limit, oversizedBodyStrategy) {
+    if (req.readableEnded)
+        return Promise.resolve(Buffer.alloc(0));
     return new Promise((resolve, reject) => {
         const maxBytes = parseLimit(limit);
         if (oversizedBodyStrategy === "close") {

package/dist/router.d.mts

@@ -1,14 +1,16 @@
 import Router from "find-my-way";
 import type { Context } from "./context.mts";
+import type { MutationRouteOptions } from "./mutation-media-type.mts";
 type RouterInstance = Router.Instance<Router.HTTPVersion.V1>;
 export type Handler = (ctx: Context) => Promise<void> | void;
 export interface RouteBuilder {
     get(handler: Handler): RouteBuilder;
-    post(handler: Handler): RouteBuilder;
-    put(handler: Handler): RouteBuilder;
-    delete(handler: Handler): RouteBuilder;
-    patch(handler: Handler): RouteBuilder;
+    post(handler: Handler, options?: MutationRouteOptions): RouteBuilder;
+    put(handler: Handler, options?: MutationRouteOptions): RouteBuilder;
+    delete(handler: Handler, options?: MutationRouteOptions): RouteBuilder;
+    patch(handler: Handler, options?: MutationRouteOptions): RouteBuilder;
 }
 export declare function isSupportedHttpMethod(method: string): boolean;
 export declare function createRouteBuilder(router: RouterInstance, path: string): RouteBuilder;
+export declare function getAcceptedMediaTypes(handler: Router.Handler<Router.HTTPVersion.V1>): readonly string[] | undefined;
 export {};

package/dist/router.mjs

@@ -10,28 +10,34 @@ export function createRouteBuilder(router, path) {
             router.on("HEAD", path, wrapHandler(handler));
             return builder;
         },
-        post(handler) {
-            router.on("POST", path, wrapHandler(handler));
+        post(handler, options) {
+            router.on("POST", path, wrapHandler(handler, options));
             return builder;
         },
-        put(handler) {
-            router.on("PUT", path, wrapHandler(handler));
+        put(handler, options) {
+            router.on("PUT", path, wrapHandler(handler, options));
             return builder;
         },
-        delete(handler) {
-            router.on("DELETE", path, wrapHandler(handler));
+        delete(handler, options) {
+            router.on("DELETE", path, wrapHandler(handler, options));
             return builder;
         },
-        patch(handler) {
-            router.on("PATCH", path, wrapHandler(handler));
+        patch(handler, options) {
+            router.on("PATCH", path, wrapHandler(handler, options));
             return builder;
         },
     };
     return builder;
 }
-function wrapHandler(handler) {
-    return (_req, _res, _params, store) => {
+export function getAcceptedMediaTypes(handler) {
+    return handler.acceptedMediaTypes;
+}
+function wrapHandler(handler, options) {
+    const wrapped = (_req, _res, _params, store) => {
         const ctx = store;
         return handler(ctx);
     };
+    if (options)
+        wrapped.acceptedMediaTypes = options.acceptedMediaTypes;
+    return wrapped;
 }

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/dist/stream-json-object.d.mts

@@ -0,0 +1,7 @@
+import { Readable } from "node:stream";
+export type StreamJsonObjectInput<T extends object> = {
+    [Key in keyof T]: T[Key] | PromiseLike<T[Key]>;
+};
+export declare function streamJsonObject<T extends object>(input: StreamJsonObjectInput<T>): Readable;
+/** @internal Test-only visibility for bounded waiter regression coverage. */
+export declare function getStreamJsonObjectWaiterCountForTesting(stream: Readable): number;

package/dist/stream-json-object.mjs

@@ -0,0 +1,186 @@
+import { Readable } from "node:stream";
+import { isPromise } from "node:util/types";
+import { JsonStreamStringify } from "json-stream-stringify";
+const cancelled = Symbol("cancelled");
+const states = new WeakMap();
+export function streamJsonObject(input) {
+    const state = createState();
+    const stream = Readable.from(iterateObject(snapshotEntries(input, state), state));
+    const destroy = stream.destroy.bind(stream);
+    stream.destroy = ((error) => {
+        stop(state);
+        return destroy(error);
+    });
+    stream.once("close", () => stop(state));
+    states.set(stream, state);
+    return stream;
+}
+/** @internal Test-only visibility for bounded waiter regression coverage. */
+export function getStreamJsonObjectWaiterCountForTesting(stream) {
+    return states.get(stream)?.listeners.size ?? 0;
+}
+async function* iterateObject(entries, state) {
+    if (state.failed)
+        throw state.failure;
+    yield "{";
+    let hasEntries = false;
+    while (!state.closed) {
+        const entry = await waitFor(nextEntry(entries), state);
+        if (entry === cancelled)
+            return;
+        if (!entry)
+            break;
+        if ("error" in entry)
+            throw entry.error;
+        hasEntries = yield* iterateEntry(entry, hasEntries, state);
+    }
+    yield "}";
+}
+async function* iterateEntry(entry, hasEntries, state) {
+    const source = entry.value instanceof Readable ? entry.value : null;
+    const producer = new JsonStreamStringify(entry.value);
+    state.producer = producer;
+    try {
+        const iterator = producer[Symbol.asyncIterator]();
+        const first = await waitFor(iterator.next(), state);
+        if (first === cancelled || first.done)
+            return hasEntries;
+        yield `${hasEntries ? "," : ""}${JSON.stringify(entry.key)}:${String(first.value)}`;
+        for (;;) {
+            const next = await waitFor(iterator.next(), state);
+            if (next === cancelled || next.done)
+                return true;
+            yield String(next.value);
+        }
+    }
+    finally {
+        if (state.producer === producer)
+            state.producer = null;
+        source?.destroy();
+        producer.destroy();
+    }
+}
+function createState() {
+    const state = {
+        closed: false,
+        failure: undefined,
+        failed: false,
+        fail: null,
+        listeners: new Set(),
+        producer: null,
+        sources: new Set(),
+    };
+    state.fail = (error) => {
+        if (!state.failed) {
+            state.failed = true;
+            state.failure = error;
+            for (const listener of state.listeners)
+                listener.fail(error);
+            state.listeners.clear();
+            state.producer?.destroy();
+            for (const source of state.sources)
+                source.destroy();
+        }
+    };
+    return state;
+}
+function stop(state) {
+    if (state.closed)
+        return;
+    state.closed = true;
+    for (const listener of state.listeners)
+        listener.stop();
+    state.listeners.clear();
+    state.producer?.destroy();
+    for (const source of state.sources)
+        source.destroy();
+}
+function snapshotEntries(input, state) {
+    const pending = { count: 0, entries: [], waiters: [] };
+    for (const [key, value] of Object.entries(input)) {
+        const promise = assimilate(value);
+        if (promise)
+            addPendingEntry(pending, key, promise, state);
+        else {
+            if (value instanceof Readable)
+                state.sources.add(value);
+            pending.entries.push({ key, value });
+        }
+    }
+    return pending;
+}
+function addPendingEntry(pending, key, value, state) {
+    pending.count += 1;
+    const resolve = (resolved) => settle(pending, { key, value: resolved });
+    const reject = (error) => {
+        state.fail(error);
+        settle(pending, { error });
+    };
+    Reflect.apply(Promise.prototype.then, value, [resolve, reject]);
+}
+function settle(pending, entry) {
+    pending.count -= 1;
+    const waiter = pending.waiters.shift();
+    if (waiter)
+        waiter(entry);
+    else
+        pending.entries.push(entry);
+}
+function nextEntry(pending) {
+    const entry = pending.entries.shift();
+    if (entry)
+        return Promise.resolve(entry);
+    return pending.count === 0
+        ? Promise.resolve(undefined)
+        : new Promise((resolve) => pending.waiters.push(resolve));
+}
+function waitFor(value, state) {
+    if (state.closed)
+        return Promise.resolve(cancelled);
+    if (state.failed)
+        return Promise.reject(state.failure);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (settle) => {
+            if (settled)
+                return;
+            settled = true;
+            state.listeners.delete(listener);
+            settle();
+        };
+        const listener = {
+            fail: (error) => finish(() => reject(error)),
+            stop: () => finish(() => resolve(cancelled)),
+        };
+        state.listeners.add(listener);
+        Reflect.apply(Promise.prototype.then, value, [
+            (result) => finish(() => resolve(result)),
+            (error) => finish(() => reject(error)),
+        ]);
+    });
+}
+function assimilate(value) {
+    if (!value || (typeof value !== "object" && typeof value !== "function"))
+        return;
+    if (isPromise(value))
+        return value;
+    let then;
+    try {
+        then = value.then;
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    if (typeof then !== "function")
+        return;
+    return new Promise((resolve, reject) => {
+        queueMicrotask(() => {
+            try {
+                Reflect.apply(then, value, [resolve, reject]);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}

package/dist/types.d.mts

@@ -22,13 +22,4 @@ export interface ApplicationOptions {
     trustProxy?: boolean;
     /** Reject methods outside node:http.METHODS with 400. Defaults to false. */
     strictHttpMethods?: boolean;
-    /**
-     * When true, ctx.request.json() rejects requests whose Content-Type is not
-     * application/json (or a compatible JSON subtype such as application/merge-patch+json)
-     * with a 415 Unsupported Media Type error. Requests with no body are unaffected.
-     *
-     * Defaults to false (lenient: any Content-Type is accepted, preserving
-     * backward-compatible behavior).
-     */
-    strictJsonContentType?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jongleberry/api-server",
-  "version": "1.2.2",
+  "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": {
@@ -30,6 +38,7 @@
     "find-my-way": "^9.6.0",
     "http-assert": "^1.5.0",
     "http-errors": "^2.0.1",
+    "json-stream-stringify": "^3.1.7",
     "negotiator": "^1.0.0",
     "type-is": "^2.1.0"
   },
@@ -44,7 +53,7 @@
     "@types/type-is": "^1.6.7",
     "@vitest/coverage-v8": "^4.1.6",
     "husky": "^9.1.7",
-    "oxfmt": "^0.59.0",
+    "oxfmt": "^0.63.0",
     "oxlint": "^1.65.0",
     "supertest": "^7.2.2",
     "typescript": "^7.0.2",