@zudojs/http 1.0.0 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 HTTP primitives, request handling, routing, middleware, and server infrastructure for Zudojs applications.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-http](https://zudojs.oyinlola.site/docs/packages-http) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-http.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -11,19 +17,71 @@ npm install @zudojs/http
 ## Quick Start
 
 ```typescript
-import { createHTTPServer } from "@zudojs/http";
+import {
+  createHttpServer,
+  createNodeHttpAdapter,
+  createResponseContext,
+} from "@zudojs/http";
 
-const server = createHTTPServer({
-  handler: {
-    async fetch(request) {
-      return new Response("Hello from Zudojs");
-    },
+const server = createHttpServer({
+  adapter: createNodeHttpAdapter({ host: "127.0.0.1", port: 3000 }),
+  handler: async (request) => {
+    return createResponseContext().text(`Hello from Zudojs (${request.path})`);
   },
 });
 
 await server.start();
 ```
 
+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
+sent as `application/json`, whatever its keys. To choose the status, headers
+or raw body, return `createResponseContext({ status, headers, body })`.
+Throwing an `HttpError` created by `notFound()`, `unauthorized()` and friends
+answers with that error's status. When errors are wrapped, the **outermost**
+error that carries a status wins; only the middleware pipeline's own
+wrappers are looked through, so `new HttpError(502, "Bad Gateway", { cause })`
+answers 502 and never exposes the cause.
+
+## Secure defaults
+
+- **Request guard.** The Node adapter runs `guardRequest` on every request
+  before the body is read and answers `400` when it refuses: Host,
+  `X-Request-Id` format, header count and size, URL and query length, and
+  `Transfer-Encoding`/`Content-Length` smuggling. Tune it with
+  `createNodeHttpAdapter({ security: { allowedHosts: ["api.example.com"] } })`
+  or turn it off with `security: false`. HTTP/1.0 requests may omit Host, and
+  oversized bodies still get `413` from `maxBodySize`.
+- **Canonical request targets.** Request targets with `.`/`..` segments
+  (including `%2e%2e`), backslashes or a non-origin form are refused with
+  `400`. `request.path`, the router and `createPathMiddleware` all read the
+  path with one parser, and `//host/admin` is a path, never an authority.
+- **Path-scoped middleware** matches the way the router does: case-insensitive
+  and ignoring repeated or trailing slashes (`{ caseSensitive: true }` to opt
+  out).
+- **Query strings** are parsed once: a repeated name is an array in both
+  `request.query`/`getQuery()` and the router's `ctx.query`.
+- **Cookies** default to `Path=/; HttpOnly; Secure; SameSite=Lax`; override
+  any attribute explicitly. Signed cookies are bound to their name: read them
+  with `parseSignedCookie(value, secret, name)`.
+- **`trustProxy`** accepts a hop count (`trustProxy: 1` trusts one proxy).
+- **CORS** origin matching is `@zudojs/security`'s `isOriginAllowed`, and a
+  wildcard origin with `credentials: true` throws when the middleware is
+  created. **Rate limiting**: `createRateLimitMiddleware({ max, windowMs })`
+  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.
+- Signed-cookie signatures are compared with `@zudojs/crypto`'s constant-time
+  `timingSafeEqualString`.
+- Contexts built by the stock adapters log through a `@zudojs/logger` console
+  logger named `http`, which redacts secret metadata fields (`authorization`,
+  `password`, `apiKey`, …).
+- `HttpRequestGuardError`, `HttpMiddlewareError` and
+  `HttpMiddlewarePipelineError` are the `@zudojs/errors` classes, re-exported.
+- `HttpServer.stop()` gives in-flight requests the full
+  `gracefulShutdownTimeout`.
+
 ## Features
 
 - Runtime-independent HTTP server abstraction

package/dist/httpAdapter/http.adapter.d.ts

@@ -64,7 +64,12 @@ export interface HttpAdapter {
      */
     setErrorHandler?(handler: HttpErrorHandler): void;
     start?(): void | Promise<void>;
-    stop?(): void | Promise<void>;
+    /**
+     * Stops the adapter. `options.graceMs` bounds how long in-flight requests
+     * may run before their connections are closed; `HttpServer.stop()` passes
+     * its `gracefulShutdownTimeout` here.
+     */
+    stop?(options?: HttpAdapterStopOptions): void | Promise<void>;
 }
 import { HttpAdapterError } from "@zudojs/errors";
 export { HttpAdapterError };
@@ -96,7 +101,7 @@ export declare abstract class BaseHttpAdapter implements HttpAdapter {
     protected handleError(error: unknown, request: HttpRequestContext, input: unknown, response: HttpResponseContext): Promise<void>;
     protected write(input: unknown, context: HttpResponseContext): Promise<void>;
     start(): Promise<void>;
-    stop(): Promise<void>;
+    stop(_options?: HttpAdapterStopOptions): Promise<void>;
     get isStarted(): boolean;
 }
 export interface GenericAdapterOptions extends HttpAdapterOptions {
@@ -128,9 +133,35 @@ export declare class HttpAdapterRegistry {
     clear(): void;
 }
 export declare function startAdapter(adapter: HttpAdapter): Promise<void>;
-export declare function stopAdapter(adapter: HttpAdapter): Promise<void>;
+/**
+ * Options passed to {@link HttpAdapter.stop}.
+ */
+export interface HttpAdapterStopOptions {
+    /** Milliseconds in-flight requests may run before connections are closed. */
+    readonly graceMs?: number;
+}
+export declare function stopAdapter(adapter: HttpAdapter, options?: HttpAdapterStopOptions): Promise<void>;
 export declare function isHttpAdapter(value: unknown): value is HttpAdapter;
+/**
+ * Turns a handler's return value into a response.
+ *
+ * Only an `HttpResponseContext` is treated as a response; `undefined`/`null`
+ * is an empty 200. **Every other value, including any plain object, is
+ * data** and is sent as `application/json`. To answer with a status, headers
+ * or a raw body, return `createResponseContext({ status, headers, body })`.
+ *
+ * A plain object used to count as a response init whenever it had any of
+ * eight common keys, so `{ status: "ok" }` became a 500 and a row with a
+ * `body` or `metadata` column was silently emptied or truncated.
+ */
 export declare function normalizeHandlerResult(result: HttpHandlerResult): HttpResponseContext;
+/**
+ * Whether a value has the shape of a response init.
+ *
+ * @deprecated No longer used to interpret handler results: a plain object
+ * returned from a handler is always sent as JSON (see
+ * {@link normalizeHandlerResult}). Kept for API compatibility.
+ */
 export declare function isResponseContextInit(value: unknown): value is ResponseContextInit;
 export declare function mergeResponseContext(target: HttpResponseContext, source: HttpResponseContext): HttpResponseContext;
 //# sourceMappingURL=http.adapter.d.ts.map

package/dist/httpAdapter/http.adapter.js

@@ -11,6 +11,7 @@
 import { HttpRequestContext, createRequestContext, } from "../httpRequest/httpRequest.context.js";
 import { HttpResponseContext, createResponseContext, } from "../httpResponse/httpResponse.context.js";
 import { writeResponse } from "../httpResponse/httpResponse.writer.js";
+import { resolveErrorResponse } from "./httpAdapter.errorResponse.js";
 /* -------------------------------------------------------------------------- */
 /* Adapter Error                                                              */
 /* -------------------------------------------------------------------------- */
@@ -85,10 +86,11 @@ export class BaseHttpAdapter {
             mergeResponseContext(response, context);
         }
         else {
-            response.internalServerError();
-            response.json({
-                error: "Internal Server Error",
-            });
+            const resolved = resolveErrorResponse(error);
+            for (const [name, value] of Object.entries(resolved.headers)) {
+                response.setHeader(name, value);
+            }
+            response.setStatus(resolved.status).json(resolved.body);
         }
         await this.write(input, response);
     }
@@ -108,7 +110,7 @@ export class BaseHttpAdapter {
         }
         this.started = true;
     }
-    async stop() {
+    async stop(_options) {
         if (!this.started) {
             return;
         }
@@ -220,9 +222,9 @@ export async function startAdapter(adapter) {
         await adapter.start();
     }
 }
-export async function stopAdapter(adapter) {
+export async function stopAdapter(adapter, options) {
     if (adapter.stop) {
-        await adapter.stop();
+        await adapter.stop(options);
     }
 }
 /* -------------------------------------------------------------------------- */
@@ -242,6 +244,18 @@ export function isHttpAdapter(value) {
 /* -------------------------------------------------------------------------- */
 /* Result Normalization                                                       */
 /* -------------------------------------------------------------------------- */
+/**
+ * Turns a handler's return value into a response.
+ *
+ * Only an `HttpResponseContext` is treated as a response; `undefined`/`null`
+ * is an empty 200. **Every other value, including any plain object, is
+ * data** and is sent as `application/json`. To answer with a status, headers
+ * or a raw body, return `createResponseContext({ status, headers, body })`.
+ *
+ * A plain object used to count as a response init whenever it had any of
+ * eight common keys, so `{ status: "ok" }` became a 500 and a row with a
+ * `body` or `metadata` column was silently emptied or truncated.
+ */
 export function normalizeHandlerResult(result) {
     if (result instanceof HttpResponseContext) {
         return result;
@@ -249,11 +263,15 @@ export function normalizeHandlerResult(result) {
     if (result === undefined || result === null) {
         return createResponseContext();
     }
-    if (isResponseContextInit(result)) {
-        return createResponseContext(result);
-    }
     return createResponseContext().json(result);
 }
+/**
+ * Whether a value has the shape of a response init.
+ *
+ * @deprecated No longer used to interpret handler results: a plain object
+ * returned from a handler is always sent as JSON (see
+ * {@link normalizeHandlerResult}). Kept for API compatibility.
+ */
 export function isResponseContextInit(value) {
     if (value === null || typeof value !== "object") {
         return false;

package/dist/httpAdapter/http.adapters.js

@@ -1,6 +1,7 @@
 import { createHTTPContext } from "../httpContext/http.context.js";
 import { createHTTPRequest } from "../httpRequest/http.request.js";
 import { createHTTPResponse } from "../httpResponse/http.response.js";
+import { createDefaultContextLogger } from "./httpAdapter.logger.js";
 /* -------------------------------------------------------------------------- */
 /* Node Adapter                                                               */
 /* -------------------------------------------------------------------------- */
@@ -18,7 +19,7 @@ export class NodeHTTPAdapter {
             response,
             state: options.state ?? {},
             signal: options.signal,
-            logger: createFallbackLogger(),
+            logger: createDefaultContextLogger(),
         });
     }
 }
@@ -45,7 +46,7 @@ export class NodeContextAdapter {
             response,
             state: options.state ?? {},
             signal: options.signal,
-            logger: createFallbackLogger(),
+            logger: createDefaultContextLogger(),
         });
     }
 }
@@ -87,7 +88,7 @@ export function adaptNodeContext(request, response, options = {}) {
         response: adaptNodeResponse(response),
         state: options.state ?? {},
         signal: options.signal,
-        logger: createFallbackLogger(),
+        logger: createDefaultContextLogger(),
     });
 }
 /* -------------------------------------------------------------------------- */
@@ -103,35 +104,4 @@ export function isHTTPAdapter(value) {
         typeof candidate.createResponse === "function" &&
         typeof candidate.createContext === "function");
 }
-/* -------------------------------------------------------------------------- */
-/* Fallback Logger                                                             */
-/* -------------------------------------------------------------------------- */
-function createFallbackLogger() {
-    return {
-        info(message, metadata) {
-            if (metadata !== undefined) {
-                console.info(message, metadata);
-            }
-            else {
-                console.info(message);
-            }
-        },
-        warn(message, metadata) {
-            if (metadata !== undefined) {
-                console.warn(message, metadata);
-            }
-            else {
-                console.warn(message);
-            }
-        },
-        error(message, metadata) {
-            if (metadata !== undefined) {
-                console.error(message, metadata);
-            }
-            else {
-                console.error(message);
-            }
-        },
-    };
-}
 //# sourceMappingURL=http.adapters.js.map

package/dist/httpAdapter/httpAdapter.errorResponse.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Default error-to-response mapping shared by the adapters.
+ *
+ * An error thrown from a handler used to be answered with a generic 500 no
+ * matter what it was, so `throw notFound()` — the documented way to fail a
+ * request — reached the client as `500 Internal Server Error` with the
+ * error's status, message and headers (`WWW-Authenticate`, `Allow`,
+ * `Retry-After`) all discarded. Middleware wrappers made it worse: the
+ * pipeline wraps every failure in `HttpMiddlewareError` /
+ * `HttpMiddlewarePipelineError`, both of which report status 500, so the
+ * original error's status was hidden even from a custom error handler that
+ * only looked one level deep.
+ *
+ * This module is deliberately internal: it is not part of the public API.
+ *
+ * @module httpAdapter/errorResponse
+ */
+export interface ResolvedErrorResponse {
+    readonly status: number;
+    readonly body: Readonly<Record<string, unknown>>;
+    readonly headers: Readonly<Record<string, string>>;
+}
+/**
+ * Builds the default response for an unhandled error.
+ *
+ * - The outermost error with a 4xx/5xx `statusCode` (looking through the
+ *   pipeline's own wrappers only) is answered with that status.
+ * - Its `message` and `code` are included only when the error opts in with
+ *   `expose: true` (the `@zudojs/errors` default for 4xx); otherwise the
+ *   body carries the status text alone, so a 5xx never leaks internals.
+ * - Its `headers` are applied when they are valid header values.
+ * - Anything else is a generic `500 Internal Server Error`.
+ */
+export declare function resolveErrorResponse(error: unknown): ResolvedErrorResponse;
+//# sourceMappingURL=httpAdapter.errorResponse.d.ts.map

package/dist/httpAdapter/httpAdapter.errorResponse.js

@@ -0,0 +1,137 @@
+/**
+ * Default error-to-response mapping shared by the adapters.
+ *
+ * An error thrown from a handler used to be answered with a generic 500 no
+ * matter what it was, so `throw notFound()` — the documented way to fail a
+ * request — reached the client as `500 Internal Server Error` with the
+ * error's status, message and headers (`WWW-Authenticate`, `Allow`,
+ * `Retry-After`) all discarded. Middleware wrappers made it worse: the
+ * pipeline wraps every failure in `HttpMiddlewareError` /
+ * `HttpMiddlewarePipelineError`, both of which report status 500, so the
+ * original error's status was hidden even from a custom error handler that
+ * only looked one level deep.
+ *
+ * This module is deliberately internal: it is not part of the public API.
+ *
+ * @module httpAdapter/errorResponse
+ */
+import { getStatusText } from "../httpResponse/core/httpResponse.statusText.js";
+import { isValidHeaderFieldValue } from "../httpHeaders/security/index.js";
+import { HttpMiddlewareError, HttpMiddlewarePipelineError, } from "../httpMiddleware/httpMiddleware.error.js";
+/* -------------------------------------------------------------------------- */
+/* Constants                                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * How many levels of `cause` / `errors` nesting are inspected. Deep enough
+ * for the pipeline's two wrappers plus a few application layers; bounded so a
+ * cyclic `cause` chain cannot loop.
+ */
+const MAX_UNWRAP_DEPTH = 8;
+/* -------------------------------------------------------------------------- */
+/* Resolution                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * Whether `error` is one of the pipeline's own wrappers. These are added by
+ * the framework on the way out and always report 500, so they are looked
+ * through; nothing else is.
+ */
+function isFrameworkWrapper(error) {
+    return (error instanceof HttpMiddlewareError ||
+        error instanceof HttpMiddlewarePipelineError);
+}
+/**
+ * Locates the error whose status answers the request.
+ *
+ * The **outermost** error that carries a status wins. Only the framework's
+ * own wrappers (`HttpMiddlewareError`, `HttpMiddlewarePipelineError`) are
+ * unwrapped. An application that throws
+ * `new HttpError(502, "Bad Gateway", { cause: upstream401 })` is mapping an
+ * upstream failure on purpose; taking the innermost status sent the client
+ * the upstream's 401, its message and its `WWW-Authenticate` header.
+ * An error that is neither a wrapper nor carries a status ends the search
+ * (generic 500), so a `cause` the application attached is never exposed.
+ */
+function findStatusError(error, depth, seen) {
+    if (error === null || typeof error !== "object" || depth > MAX_UNWRAP_DEPTH) {
+        return undefined;
+    }
+    if (seen.has(error)) {
+        return undefined;
+    }
+    seen.add(error);
+    const candidate = error;
+    if (!isFrameworkWrapper(error)) {
+        return isHttpStatus(candidate.statusCode)
+            ? candidate
+            : undefined;
+    }
+    const nested = [];
+    if (Array.isArray(candidate.errors)) {
+        nested.push(...candidate.errors);
+    }
+    if (candidate.cause !== undefined) {
+        nested.push(candidate.cause);
+    }
+    for (const inner of nested) {
+        const found = findStatusError(inner, depth + 1, seen);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+function isHttpStatus(value) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= 400 &&
+        value <= 599);
+}
+/**
+ * Builds the default response for an unhandled error.
+ *
+ * - The outermost error with a 4xx/5xx `statusCode` (looking through the
+ *   pipeline's own wrappers only) is answered with that status.
+ * - Its `message` and `code` are included only when the error opts in with
+ *   `expose: true` (the `@zudojs/errors` default for 4xx); otherwise the
+ *   body carries the status text alone, so a 5xx never leaks internals.
+ * - Its `headers` are applied when they are valid header values.
+ * - Anything else is a generic `500 Internal Server Error`.
+ */
+export function resolveErrorResponse(error) {
+    const statusError = findStatusError(error, 0, new Set());
+    if (!statusError) {
+        return {
+            status: 500,
+            body: { error: "Internal Server Error" },
+            headers: {},
+        };
+    }
+    const status = statusError.statusCode;
+    const expose = statusError.expose === true;
+    const message = expose && typeof statusError.message === "string" && statusError.message
+        ? statusError.message
+        : getStatusText(status);
+    const body = { error: message };
+    if (expose && typeof statusError.code === "string" && statusError.code) {
+        body.code = statusError.code;
+    }
+    return {
+        status,
+        body,
+        headers: collectHeaders(statusError.headers),
+    };
+}
+function collectHeaders(value) {
+    if (value === null || typeof value !== "object") {
+        return {};
+    }
+    const headers = {};
+    for (const [name, entry] of Object.entries(value)) {
+        if (typeof entry !== "string" || !isValidHeaderFieldValue(entry)) {
+            continue;
+        }
+        headers[name] = entry;
+    }
+    return headers;
+}
+//# sourceMappingURL=httpAdapter.errorResponse.js.map

package/dist/httpAdapter/httpAdapter.logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Default logger for contexts built by the stock adapters.
+ *
+ * @module httpAdapter/httpAdapter.logger
+ */
+import { type Logger } from "@zudojs/logger";
+/**
+ * Creates the logger a stock adapter gives each `HTTPContext` when the
+ * caller supplies none: a `@zudojs/logger` console logger named `http`.
+ *
+ * It goes through the logger's secret-field redaction, so metadata such as
+ * `authorization`, `password` or `apiKey` passed to `ctx.log()` is printed
+ * as `[REDACTED]`. The earlier fallback called `console.*` with the raw
+ * metadata object. One logger per context (construction costs a few
+ * microseconds), so `setLevel()` / `disable()` / `close()` on one context's
+ * logger cannot silence another's.
+ */
+export declare function createDefaultContextLogger(): Logger;
+//# sourceMappingURL=httpAdapter.logger.d.ts.map

package/dist/httpAdapter/httpAdapter.logger.js

@@ -0,0 +1,21 @@
+/**
+ * Default logger for contexts built by the stock adapters.
+ *
+ * @module httpAdapter/httpAdapter.logger
+ */
+import { createDefaultLogger } from "@zudojs/logger";
+/**
+ * Creates the logger a stock adapter gives each `HTTPContext` when the
+ * caller supplies none: a `@zudojs/logger` console logger named `http`.
+ *
+ * It goes through the logger's secret-field redaction, so metadata such as
+ * `authorization`, `password` or `apiKey` passed to `ctx.log()` is printed
+ * as `[REDACTED]`. The earlier fallback called `console.*` with the raw
+ * metadata object. One logger per context (construction costs a few
+ * microseconds), so `setLevel()` / `disable()` / `close()` on one context's
+ * logger cannot silence another's.
+ */
+export function createDefaultContextLogger() {
+    return createDefaultLogger("http");
+}
+//# sourceMappingURL=httpAdapter.logger.js.map

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

@@ -10,6 +10,7 @@ import { Server } from "node:http";
 import { HttpRequestContext } from "../../httpRequest/httpRequest.context.js";
 import { HttpResponseContext } from "../../httpResponse/httpResponse.context.js";
 import { BaseHttpAdapter } from "../http.adapter.js";
+import type { HttpAdapterStopOptions } from "../http.adapter.js";
 import type { HttpResponseWriter } from "../../httpResponse/httpResponse.writer.js";
 import type { NodeAdapterOptions, NodeServerAddress } from "./httpNode.type.js";
 export declare class NodeHttpAdapter extends BaseHttpAdapter {
@@ -25,8 +26,16 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     private readonly connectionsCheckingInterval;
     private readonly shutdownGraceMs;
     private readonly events;
+    private readonly requestGuard;
     private server;
     private ownsServer;
+    /**
+     * The `clientError` listener installed by `start()`, kept so `stop()` can
+     * remove it. On an externally supplied server the instance survives a
+     * stop/start cycle, and re-adding the listener on every start leaked one
+     * per restart.
+     */
+    private clientErrorListener;
     constructor(options?: NodeAdapterOptions);
     get httpServer(): Server | undefined;
     get address(): NodeServerAddress | undefined;
@@ -43,8 +52,13 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
      */
     private attachNodeBody;
     private executeNodeHandler;
+    /**
+     * Plain objects are data and are sent as JSON; see
+     * `normalizeHandlerResult`.
+     */
     private normalizeResult;
     private handleNodeError;
+    private writeBadRequest;
     private writeNodeResponse;
     /**
      * Runs `handle` for a Node request/response pair without ever letting the
@@ -57,7 +71,12 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     private dispatchNodeRequest;
     private emitAdapterError;
     start(): Promise<void>;
-    stop(): Promise<void>;
+    /**
+     * Closes the server. The grace period is `options.graceMs` (the server's
+     * `gracefulShutdownTimeout`), capped by an explicit `shutdownGraceMs`;
+     * with neither it is 10 s.
+     */
+    stop(options?: HttpAdapterStopOptions): Promise<void>;
 }
 export declare function createNodeHttpAdapter(options?: NodeAdapterOptions): NodeHttpAdapter;
 //# sourceMappingURL=httpNode.adapter.d.ts.map