@zudojs/http 1.3.0 → 1.4.0

package/README.md

@@ -33,6 +33,10 @@ const server = createHttpServer({
 await server.start();
 ```
 
+`createHttpServer` takes `HttpServerOptions`, so `request` in the handler
+above is typed `HttpRequestContext` without an annotation (the options used
+to be typed `unknown`, which failed `strict` builds with TS7006).
+
 A handler receives an `HttpRequestContext` and may return an
 `HttpResponseContext` or any JSON value. **Every value that is not an
 `HttpResponseContext` is data**: a plain object such as `{ status: "ok" }` is
@@ -72,6 +76,15 @@ answers 502 and never exposes the cause.
   wraps `@zudojs/security`'s `createRateLimiter`. Requests with no usable
   client address share one bucket (`UNKNOWN_CLIENT_RATE_LIMIT_IP`,
   `0.0.0.0`): they are limited together, never unlimited and never a 500.
+  The 429 carries a JSON body sent as `application/json` and always a
+  `Retry-After` header, even when a custom limiter handler omits it.
+- **Request ids.** `request.id` reuses the client's `x-request-id` when it is
+  1-128 characters of `[A-Za-z0-9._:-]`; any other value is ignored and a
+  UUID is generated, so an id copied into logs can never carry spaces,
+  quotes or control characters. `createNodeHttpAdapter({ trustRequestId:
+  false })` always generates one. The request guard's own `X-Request-Id`
+  check (letters, digits, `_`, `-`) still answers 400 to a malformed header
+  first unless it is tuned or turned off.
 - Signed-cookie signatures are compared with `@zudojs/crypto`'s constant-time
   `timingSafeEqualString`.
 - Contexts built by the stock adapters log through a `@zudojs/logger` console
@@ -82,12 +95,220 @@ answers 502 and never exposes the cause.
 - `HttpServer.stop()` gives in-flight requests the full
   `gracefulShutdownTimeout`.
 
+## Routes
+
+A route handler returns what a server handler returns:
+
+```typescript
+router.get("/health", () => ({ status: "ok" }));          // 200, JSON body
+router.get("/users/:id", async (ctx) => loadUser(ctx.params.id));
+router.post("/users", () =>
+  createResponseContext({ status: 201, body: { created: true } }),
+);
+router.delete("/users/:id", () => undefined);              // 204
+```
+
+A plain value (object, array, string, number, boolean) is sent as `200`
+with a JSON body; `undefined` or `null` is `204 No Content`; an
+`HttpResponseContext` or a web `Response` is sent as built. (A plain
+object used to be a type error and was sent as an empty `204`.) The
+router and `RouteDispatcher` behave the same.
+
+Route parameters are set on the request before route middleware runs, so
+`ctx.request.getParam("id")` works in a guard or an `extractResource`
+loader as well as in the handler (`ctx.params`).
+
+## Middleware errors
+
+An error thrown by a middleware or handler propagates **as the error that
+was thrown**. An outer middleware's `await next()` rejects with it, the
+pipeline's `onError` receives it, and so does the server's `errorHandler`,
+so `error instanceof NotFoundError` works in each. It used to arrive wrapped
+in `HttpMiddlewareError` (inside a middleware) or
+`HttpMiddlewarePipelineError` (in `errorHandler`), with the original only in
+`cause` / `errors[0].cause`.
+
+Code after `await next()` does not run when the chain below it throws,
+unless the middleware catches the error:
+
+```typescript
+pipeline.use(async (ctx, next) => {
+  const started = Date.now();
+  try {
+    return await next();
+  } finally {
+    log.info("request", { path: ctx.request.path, ms: Date.now() - started });
+  }
+});
+```
+
+If `onError` returns a response, that is the recovery; if it throws, what
+it threw propagates (rethrow the error to pass it on, or throw a different
+one to translate it).
+
+`new HttpError(415, "No XML")` without a `code` gets its code from the
+status (`"UNSUPPORTED_MEDIA_TYPE"`, `"NOT_FOUND"`, ...), matching the
+`notFound()`-style factories, instead of `ERR_OPERATION_FAILED`.
+
+## HTTP client: retries and backoff
+
+```typescript
+const client = new HttpClient({
+  timeout: 5_000,
+  retry: { retries: 3, retryDelay: 200, maxRetryDelay: 5_000 },
+});
+```
+
+- **What is retried:** responses with a status in `retryStatusCodes`
+  (default 429, 502, 503, 504); transport failures such as a refused
+  connection (`retryOnNetworkError`, default `true`); and requests that hit
+  `timeout` (`retryOnTimeout`, default: the `retryOnNetworkError` value).
+  Timeouts used to be excluded, so a `GET` with retries still failed on
+  the first timeout. Aborting through your own `signal` is never retried.
+- **Which methods:** only `retryMethods` (default `GET`, `HEAD`,
+  `OPTIONS`). A `POST` that timed out may already have been processed, so
+  it is not replayed unless you list it.
+- **Backoff:** the delay is `retryDelay` (default 1000 ms) times
+  `2^attempt` with `backoff: "exponential"` (the default), or `retryDelay`
+  every time with `"fixed"`, capped at `maxRetryDelay` (default 30 s).
+- **Jitter:** each wait is drawn uniformly between 0 and that delay (full
+  jitter), so clients that failed together do not retry in lockstep.
+  `jitter: false` waits exactly the delay. Jitter used to add up to a fixed
+  second regardless of `retryDelay`.
+- `retries` counts retries after the first attempt (default 0).
+
+## OpenAPI from your routes
+
+Routes carry their own documentation through the `openapi` option, and the
+document is generated from the routes the router actually registered — no
+second list to keep in sync. Schemas may be `@zudojs/schema` schemas or raw
+OpenAPI schemas.
+
+```typescript
+import { objectSchema, stringSchema, numberSchema, optionalSchema } from "@zudojs/schema";
+import { createRouter, generateOpenAPIDocument, mountOpenAPI } from "@zudojs/http";
+
+const user = objectSchema({ id: stringSchema().uuid(), name: stringSchema() });
+
+const router = createRouter();
+router.get("/users/:id", getUser, {
+  openapi: {
+    summary: "Get a user",
+    tags: ["users"],
+    params: objectSchema({ id: stringSchema().uuid() }),
+    responses: { "200": { schema: user }, "404": { description: "No such user" } },
+  },
+});
+router.get("/users", listUsers, {
+  openapi: { query: objectSchema({ limit: optionalSchema(numberSchema().int()) }) },
+});
+router.post("/users", createUser, {
+  openapi: { body: objectSchema({ name: stringSchema() }), responses: { "201": { schema: user } } },
+});
+router.get("/health", health, { openapi: false }); // never documented
+
+// One-off document:
+const document = generateOpenAPIDocument(router, {
+  info: { title: "Users API", version: "1.0.0" },
+  exclude: ["/internal/*"],
+  validate: true,
+});
+
+// Or serve it: GET /openapi.json and a Swagger UI page at GET /docs.
+mountOpenAPI(router, {
+  info: { title: "Users API", version: "1.0.0" },
+  yamlPath: "/openapi.yaml",        // optional
+  ui: { renderer: "redoc" },        // optional; any renderOpenAPIUI option
+});
+```
+
+- `:id` and `{id}` become `{id}`; every template slot is documented even when
+  nothing declares it. A regex-constrained `:id(\d+)` becomes a parameter
+  with that `pattern`, an optional `:id?` is documented as both paths, and a
+  wildcard `*rest` becomes a `{rest}` slot (`wildcards: "exclude"` drops such
+  routes instead).
+- Left out: `all()` routes, `CONNECT`, routes with `openapi: false` or
+  `{ hidden: true }`, and anything matched by `exclude` (exact path,
+  `"/prefix/*"`, a `RegExp`, or a predicate). The router's automatic `HEAD`
+  and `OPTIONS` answers are not registered routes and never appear.
+  `undocumented: "exclude"` documents only routes that declare `openapi`.
+- Router groups pass `openapi` defaults to their routes: tags are unioned,
+  everything else is overridden by the route.
+- The document follows the router: a route added later is in the next
+  `generateOpenAPIDocument` call and the next request to a mounted
+  `/openapi.json`. `createRouterOpenAPI(router, options)` gives the
+  underlying `OpenAPIManager`, re-read only when the route table changed.
+- Paths are configurable (`path`, `docsPath: false` to disable the page,
+  `ui.specUrl` when served under a prefix), and `middleware` protects the
+  documentation routes.
+
+## Mounting web-standard handlers
+
+`mountFetchHandler` serves any `(request: Request) => Response | Promise<Response>`
+handler — an `@zudojs/rpc` server, `@zudojs/api` operations, another
+fetch-style app — under a path of a router or router group.
+
+```typescript
+import { mountFetchHandler } from "@zudojs/http";
+import { createRPCFetchHandler } from "@zudojs/rpc";
+
+const unmount = mountFetchHandler(router, "/rpc", createRPCFetchHandler(rpcServer));
+// { methods: ["POST"], stripPrefix: false, middleware: [auth] } are optional
+```
+
+The handler sees the original method, query, headers (connection-scoped ones
+removed) and body; the mount path is stripped from its URL by default and
+passed as `x-forwarded-prefix`. Its `Response` is streamed back with status,
+status text and headers intact, each `Set-Cookie` kept separate. The
+request's `signal` aborts when the client disconnects. A handler that throws
+or returns something other than a `Response` fails the request like any
+route (a generic 500 unless the error carries a status). `toWebRequest(context)`
+does the request conversion on its own.
+
+The origin of the handler's `request.url` comes from the client's `Host`
+header (or `X-Forwarded-Host` from a trusted proxy) unless you pin it with
+`{ origin: "https://api.example.com" }`. Pin it whenever the handler builds
+absolute URLs or compares `Origin` against its own.
+
+Every Node request context now carries that signal too: `request.signal` and
+the router's `ctx.signal` abort when the client goes away, and a streamed
+response body stops being read.
+
+## Guards that refuse a request
+
+A middleware answers a request itself — 401, 403, 404 — by returning a
+`GuardResponse` from `@zudojs/middleware`. The router, `HttpMiddlewarePipeline`
+and `RouteDispatcher` send it with its own status, headers and body; headers an
+outer middleware already set (CORS, for instance) are kept.
+
+```typescript
+import { createGuardResponse } from "@zudojs/middleware";
+import { authorize } from "@zudojs/permissions";
+
+router.delete("/posts/:id", deletePost, {
+  middleware: [
+    authorize(engine, "post:delete", { extractActor }), // 401 / 403
+    async (ctx, next) =>
+      ctx.request.getHeader("x-confirm")
+        ? next()
+        : createGuardResponse({ status: 400, body: { error: "Confirm first" } }),
+  ],
+});
+```
+
+A route middleware's return value used to be ignored unless it was an
+`HttpResponseContext` or a web `Response`, so `authorize()` and the tenancy
+middleware refused requests with `200`. Only the branded object is honoured: an ordinary
+object with a `status` key keeps its old meaning.
+
 ## Features
 
 - Runtime-independent HTTP server abstraction
 - Request/response wrappers with full Web API compatibility
 - Middleware pipeline with error handling
 - Router with parameter extraction
+- OpenAPI documents generated from the registered routes
+- Mounting of web-standard fetch handlers
 - CORS, security headers, and content negotiation
 - HTTP client with interceptors
 

package/dist/httpAdapter/node/httpNode.adapter.d.ts

@@ -22,6 +22,7 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     private readonly keepAliveTimeout;
     private readonly connectionTimeout;
     private readonly trustProxy;
+    private readonly trustRequestId;
     private readonly maxConnections;
     private readonly connectionsCheckingInterval;
     private readonly shutdownGraceMs;
@@ -39,7 +40,7 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     constructor(options?: NodeAdapterOptions);
     get httpServer(): Server | undefined;
     get address(): NodeServerAddress | undefined;
-    createRequest(input: unknown): HttpRequestContext;
+    createRequest(input: unknown, signal?: AbortSignal): HttpRequestContext;
     createResponse(input?: unknown): HttpResponseContext;
     createWriter(response: unknown): HttpResponseWriter;
     handle(input: unknown): Promise<void>;

package/dist/httpAdapter/node/httpNode.adapter.js

@@ -30,6 +30,7 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
     keepAliveTimeout;
     connectionTimeout;
     trustProxy;
+    trustRequestId;
     maxConnections;
     connectionsCheckingInterval;
     shutdownGraceMs;
@@ -76,6 +77,7 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
                 Math.min(30_000, this.headersTimeout);
         this.shutdownGraceMs = options.shutdownGraceMs;
         this.trustProxy = options.trustProxy;
+        this.trustRequestId = options.trustRequestId ?? true;
         if (options.trustProxy !== undefined) {
             compileTrustProxy(options.trustProxy);
         }
@@ -109,13 +111,15 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
     /* ------------------------------------------------------------------------ */
     /* Request / Response                                                       */
     /* ------------------------------------------------------------------------ */
-    createRequest(input) {
+    createRequest(input, signal) {
         if (!isIncomingMessage(input)) {
             throw new TypeError("NodeHttpAdapter.createRequest expected an IncomingMessage.");
         }
         return createNodeRequestContext(input, {
             maxBodySize: this.maxBodySize,
             trustProxy: this.trustProxy,
+            trustRequestId: this.trustRequestId,
+            signal,
         });
     }
     createResponse(input) {
@@ -144,8 +148,19 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
             return;
         }
         let context;
+        const disconnect = new AbortController();
+        /*
+         * `close` before the response finished means the client went away.
+         * Handlers see it as `request.signal` / the router's `ctx.signal`, and a
+         * streamed response body stops being pulled.
+         */
+        response.once("close", () => {
+            if (!response.writableFinished) {
+                disconnect.abort();
+            }
+        });
         try {
-            context = this.createRequest(request);
+            context = this.createRequest(request, disconnect.signal);
         }
         catch (error) {
             /*

package/dist/httpAdapter/node/httpNode.request.js

@@ -8,6 +8,7 @@ import { getClientIp, isTrustedProxy, } from "../../httpTrustProxy/httpTrustProx
 import { removePort, extractPort } from "./httpNode.server.js";
 import { parseQueryString } from "../../httpQuery/index.js";
 import { findRequestTargetViolation } from "../../httpRequest/target/httpRequest.target.js";
+import { resolveIncomingRequestId } from "../../httpRequest/requestId/httpRequest.requestId.js";
 /* -------------------------------------------------------------------------- */
 /* Proxy Trust                                                                */
 /* -------------------------------------------------------------------------- */
@@ -159,7 +160,11 @@ export function createNodeRequestContext(request, options = {}) {
     const port = getNodeRequestPort(request, options);
     const remoteAddress = getNodeRemoteAddress(request, options);
     const query = parseNodeQuery(request);
+    const id = options.trustRequestId === false
+        ? undefined
+        : resolveIncomingRequestId(request.headers["x-request-id"]);
     return createRequestContext({
+        ...(id === undefined ? {} : { id }),
         method: request.method?.toUpperCase() ?? "GET",
         url,
         protocol,
@@ -168,6 +173,7 @@ export function createNodeRequestContext(request, options = {}) {
         headers,
         query,
         remoteAddress,
+        signal: options.signal,
     });
 }
 //# sourceMappingURL=httpNode.request.js.map

package/dist/httpAdapter/node/httpNode.type.d.ts

@@ -13,6 +13,11 @@ export interface NodeAdapterOptions extends HttpAdapterOptions, NodeAdapterSecur
     readonly server?: Server;
     readonly maxBodySize?: number;
     readonly trustProxy?: boolean | number | string | readonly string[];
+    /**
+     * Whether `request.id` reuses a well-formed incoming `x-request-id`
+     * header (default: `true`); see {@link NodeRequestOptions.trustRequestId}.
+     */
+    readonly trustRequestId?: boolean;
     readonly requestTimeout?: number;
     readonly headersTimeout?: number;
     readonly keepAliveTimeout?: number;
@@ -54,6 +59,15 @@ export interface NodeRequestOptions {
      * - string[]: Trust specific IP addresses
      */
     readonly trustProxy?: TrustProxy;
+    /** Signal carried by the context; aborted when the client disconnects. */
+    readonly signal?: AbortSignal;
+    /**
+     * Whether `request.id` reuses the client's `x-request-id` header
+     * (default: `true`). The header is used only when it is at most 128
+     * characters of `[A-Za-z0-9._:-]`; any other value is ignored and an id
+     * is generated. `false` always generates one.
+     */
+    readonly trustRequestId?: boolean;
 }
 export interface NodeServerAddress {
     readonly host: string;

package/dist/httpClient/httpClient.retry.d.ts

@@ -4,17 +4,8 @@
  * Handles retry configuration, status-based retry decisions,
  * exponential backoff, and delay utilities.
  */
-import type { HttpClientMethod } from "./httpClient.type.js";
-/** Retry options for the HTTP client. */
-export interface HttpRetryOptions {
-    readonly retries?: number;
-    readonly retryDelay?: number;
-    readonly maxRetryDelay?: number;
-    readonly retryStatusCodes?: readonly number[];
-    readonly retryMethods?: readonly HttpClientMethod[];
-    readonly retryOnNetworkError?: boolean;
-    readonly backoff?: "fixed" | "exponential";
-}
+import type { HttpRetryOptions } from "./httpClient.type.js";
+export type { HttpRetryOptions } from "./httpClient.type.js";
 /**
  * Normalize retry options with defaults.
  */
@@ -25,10 +16,24 @@ export declare function normalizeRetryOptions(options?: HttpRetryOptions): HttpR
 export declare function shouldRetryStatus(status: number, method: string, retry?: HttpRetryOptions): boolean;
 /**
  * Check if an error should trigger a retry.
+ *
+ * Transport failures are retried when `retryOnNetworkError` is on, and
+ * timeouts when `retryOnTimeout` is on (it defaults to
+ * `retryOnNetworkError`). Both apply only to `retryMethods`, which default
+ * to the idempotent `GET`, `HEAD` and `OPTIONS`. A caller's own abort is
+ * never retried.
  */
 export declare function shouldRetryError(error: unknown, method: string, retry?: HttpRetryOptions): boolean;
 /**
- * Calculate retry delay with exponential backoff.
+ * Calculate the wait before retry number `attempt + 1`.
+ *
+ * The delay is `retryDelay` (fixed backoff) or `retryDelay * 2^attempt`
+ * (exponential), capped at `maxRetryDelay`. With `jitter` (the default) the
+ * wait is drawn uniformly from 0 up to that delay ("full jitter"), so a
+ * burst of clients that failed together does not retry in lockstep;
+ * `jitter: false` waits exactly the delay. Jitter used to add up to a
+ * fixed 1000 ms whatever `retryDelay` was, so `retryDelay: 50` could wait
+ * a second.
  */
 export declare function calculateRetryDelay(attempt: number, retry: HttpRetryOptions): number;
 /**

package/dist/httpClient/httpClient.retry.js

@@ -4,6 +4,7 @@
  * Handles retry configuration, status-based retry decisions,
  * exponential backoff, and delay utilities.
  */
+import { HttpClientTimeoutError } from "./httpClient.error.js";
 /**
  * Normalize retry options with defaults.
  */
@@ -17,7 +18,9 @@ export function normalizeRetryOptions(options) {
         retryStatusCodes: options.retryStatusCodes ?? [429, 502, 503, 504],
         retryMethods: options.retryMethods ?? ["GET", "HEAD", "OPTIONS"],
         retryOnNetworkError: options.retryOnNetworkError ?? true,
+        retryOnTimeout: options.retryOnTimeout ?? options.retryOnNetworkError ?? true,
         backoff: options.backoff ?? "exponential",
+        jitter: options.jitter ?? true,
     };
 }
 /**
@@ -32,20 +35,35 @@ export function shouldRetryStatus(status, method, retry) {
 }
 /**
  * Check if an error should trigger a retry.
+ *
+ * Transport failures are retried when `retryOnNetworkError` is on, and
+ * timeouts when `retryOnTimeout` is on (it defaults to
+ * `retryOnNetworkError`). Both apply only to `retryMethods`, which default
+ * to the idempotent `GET`, `HEAD` and `OPTIONS`. A caller's own abort is
+ * never retried.
  */
 export function shouldRetryError(error, method, retry) {
     if (!retry?.retries)
         return false;
-    if (!retry.retryOnNetworkError)
-        return false;
     /*
-     * A connection that drops after the server processed the request is
-     * indistinguishable from one that never arrived, so replaying a
-     * non-idempotent method duplicates its side effects. `retryMethods` exists
-     * for exactly this and was honoured only on the status path.
+     * A connection that drops (or a request that times out) after the server
+     * processed it is indistinguishable from one that never arrived, so
+     * replaying a non-idempotent method duplicates its side effects.
+     * `retryMethods` exists for exactly this and was honoured only on the
+     * status path.
      */
     if (!retry.retryMethods?.includes(method))
         return false;
+    /*
+     * Timeouts were never retried: `isRetryableNetworkError` does not match
+     * `HttpClientTimeoutError`, so `retryOnNetworkError` had no effect on the
+     * most common transient failure.
+     */
+    if (error instanceof HttpClientTimeoutError) {
+        return retry.retryOnTimeout ?? retry.retryOnNetworkError ?? true;
+    }
+    if (!retry.retryOnNetworkError)
+        return false;
     return isRetryableNetworkError(error);
 }
 /**
@@ -71,15 +89,22 @@ function isRetryableNetworkError(error) {
     return !/body|disturbed|already (been )?(used|read)/i.test(error.message);
 }
 /**
- * Calculate retry delay with exponential backoff.
+ * Calculate the wait before retry number `attempt + 1`.
+ *
+ * The delay is `retryDelay` (fixed backoff) or `retryDelay * 2^attempt`
+ * (exponential), capped at `maxRetryDelay`. With `jitter` (the default) the
+ * wait is drawn uniformly from 0 up to that delay ("full jitter"), so a
+ * burst of clients that failed together does not retry in lockstep;
+ * `jitter: false` waits exactly the delay. Jitter used to add up to a
+ * fixed 1000 ms whatever `retryDelay` was, so `retryDelay: 50` could wait
+ * a second.
  */
 export function calculateRetryDelay(attempt, retry) {
     const base = retry.retryDelay ?? 1000;
     const max = retry.maxRetryDelay ?? 30_000;
     const ms = retry.backoff === "fixed" ? base : base * Math.pow(2, attempt);
-    /* Clamp *after* jitter, and on the fixed branch too, or `maxRetryDelay`
-     * is not actually a maximum. */
-    return Math.min(ms + Math.random() * 1000, max);
+    const capped = Math.max(0, Math.min(ms, max));
+    return retry.jitter === false ? capped : Math.random() * capped;
 }
 /**
  * Delay for a given number of milliseconds.

package/dist/httpClient/httpClient.type.d.ts

@@ -8,14 +8,28 @@ export type HttpClientBody = BodyInit | Record<string, unknown> | readonly unkno
 export type HttpClientQueryValue = string | number | boolean | bigint | null | undefined | readonly (string | number | boolean | bigint)[];
 export type HttpClientQuery = Readonly<Record<string, HttpClientQueryValue>> | URLSearchParams;
 export type HttpResponseType = "auto" | "json" | "text" | "arrayBuffer" | "blob" | "response";
+/**
+ * Retry policy for the HTTP client. See the README's "Retries and backoff".
+ */
 export interface HttpRetryOptions {
+    /** Retries after the first attempt (default 0: no retries). */
     readonly retries?: number;
+    /** Base delay in ms (default 1000). */
     readonly retryDelay?: number;
+    /** Upper bound on any single wait, in ms (default 30000). */
     readonly maxRetryDelay?: number;
+    /** Statuses that are retried (default 429, 502, 503, 504). */
     readonly retryStatusCodes?: readonly number[];
+    /** Methods that may be retried at all (default GET, HEAD, OPTIONS). */
     readonly retryMethods?: readonly HttpClientMethod[];
+    /** Retry transport failures such as a refused connection (default true). */
     readonly retryOnNetworkError?: boolean;
+    /** Retry a request that hit `timeout` (default: `retryOnNetworkError`). */
+    readonly retryOnTimeout?: boolean;
+    /** `"exponential"` doubles the delay per attempt (default); `"fixed"` does not. */
     readonly backoff?: "fixed" | "exponential";
+    /** Wait a random 0..delay instead of exactly the delay (default true). */
+    readonly jitter?: boolean;
 }
 export interface HttpClientResponse<T = unknown> {
     readonly data: T;

package/dist/httpErrors/httpError.base.js

@@ -7,7 +7,7 @@
  * @module httpErrors/base
  */
 import { HttpError as BaseHttpError } from "@zudojs/errors";
-import { normalizeHeaders, getStatusText } from "./httpError.util.js";
+import { defaultErrorCode, normalizeHeaders, getStatusText, } from "./httpError.util.js";
 /**
  * HTTP error with response-specific properties.
  *
@@ -31,7 +31,7 @@ export class HttpError extends BaseHttpError {
         const statusText = getStatusText(status);
         super(message ?? statusText, {
             statusCode: status,
-            code: options.code,
+            code: options.code ?? defaultErrorCode(status),
             expose: options.expose ?? status < 500,
             metadata: options.metadata,
             cause: options.cause,

package/dist/httpErrors/httpError.util.d.ts

@@ -19,4 +19,12 @@ export declare function normalizeHeaders(headers: Record<string, string> | undef
  * `statusText` and `message` as "Unknown Status".
  */
 export declare function getStatusText(status: number): string;
+/**
+ * The default error code for a status: its symbolic name, as the factories
+ * use (`415` gives `"UNSUPPORTED_MEDIA_TYPE"`, `404` `"NOT_FOUND"`).
+ * `undefined` for a status with no name, which keeps the shared default.
+ * `new HttpError(415, msg)` without a code used to report
+ * `ERR_OPERATION_FAILED`.
+ */
+export declare function defaultErrorCode(status: number): string | undefined;
 //# sourceMappingURL=httpError.util.d.ts.map

package/dist/httpErrors/httpError.util.js

@@ -8,6 +8,7 @@
  * @module httpErrors/util
  */
 import { getStatusText as lookupStatusText } from "../httpStatus/httpStatus.lookup.js";
+import { statusName } from "../httpStatus/httpStatus.name.js";
 /**
  * Normalizes header keys to lowercase.
  */
@@ -33,4 +34,15 @@ export function normalizeHeaders(headers) {
 export function getStatusText(status) {
     return lookupStatusText(status);
 }
+/**
+ * The default error code for a status: its symbolic name, as the factories
+ * use (`415` gives `"UNSUPPORTED_MEDIA_TYPE"`, `404` `"NOT_FOUND"`).
+ * `undefined` for a status with no name, which keeps the shared default.
+ * `new HttpError(415, msg)` without a code used to report
+ * `ERR_OPERATION_FAILED`.
+ */
+export function defaultErrorCode(status) {
+    const name = statusName(status);
+    return name === "UNKNOWN" ? undefined : name;
+}
 //# sourceMappingURL=httpError.util.js.map

package/dist/httpFetchMount/httpFetchMount.core.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Serving web-standard fetch handlers from an `@zudojs/http` router.
+ */
+import type { HttpFetchHandler, HttpFetchMountTarget, MountFetchHandlerOptions } from "./httpFetchMount.type.js";
+/**
+ * Serves a web-standard `(request: Request) => Promise<Response>` handler —
+ * an `@zudojs/rpc` server, `@zudojs/api` operations, any fetch-style app —
+ * under `basePath` of an `@zudojs/http` router or router group.
+ *
+ * The handler receives a `Request` with the original method, headers
+ * (connection-scoped ones removed), body and query, and a `signal` that
+ * aborts when the client disconnects. Its `Response` is streamed back with
+ * status, status text and headers intact, every `Set-Cookie` kept separate.
+ * A handler that throws, or returns something that is not a `Response`,
+ * fails the request like any other route (500 unless the error carries a
+ * status).
+ *
+ * ```ts
+ * mountFetchHandler(router, "/rpc", createRPCFetchHandler(rpcServer));
+ * ```
+ *
+ * @returns A function that removes the mount.
+ */
+export declare function mountFetchHandler(target: HttpFetchMountTarget, basePath: string, handler: HttpFetchHandler, options?: MountFetchHandlerOptions): () => void;
+//# sourceMappingURL=httpFetchMount.core.d.ts.map