@zudojs/http 1.1.0 → 1.3.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
@@ -28,9 +34,53 @@ await server.start();
 ```
 
 A handler receives an `HttpRequestContext` and may return an
-`HttpResponseContext`, a plain `{ status, headers, body }` object, or any JSON
-value (which is sent as `application/json`). Throwing an `HttpError` created by
-`notFound()`, `unauthorized()` and friends answers with that error's status.
+`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
 

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

@@ -110,7 +110,7 @@ export class BaseHttpAdapter {
         }
         this.started = true;
     }
-    async stop() {
+    async stop(_options) {
         if (!this.started) {
             return;
         }
@@ -222,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);
     }
 }
 /* -------------------------------------------------------------------------- */
@@ -244,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;
@@ -251,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.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { HTTPContext, HTTPHandler, HTTPMiddleware, HTTPRequest, HTTPResponse, HTTPRouteMatch, HTTPState } from "../httpTypes/http.types.js";
+import type { TrustProxy } from "../httpTrustProxy/httpTrustProxy.type.js";
 export interface HTTPAdapter<State extends HTTPState = HTTPState> {
     readonly name: string;
     createRequest(request: IncomingMessage): HTTPRequest;
@@ -9,9 +10,21 @@ export interface HTTPAdapter<State extends HTTPState = HTTPState> {
         readonly signal?: AbortSignal;
     }): HTTPContext<State>;
 }
+/**
+ * Options every Node request built by this module accepts.
+ *
+ * `trustProxy` defaults to `false`, so `X-Forwarded-For` and
+ * `X-Forwarded-Proto` are ignored and the socket peer decides `request.ip`,
+ * `request.protocol` and `request.secure`.
+ */
+export interface NodeRequestTrustOptions {
+    readonly trustProxy?: TrustProxy;
+}
 export declare class NodeHTTPAdapter<State extends HTTPState = HTTPState> implements HTTPAdapter<State> {
     readonly name = "node";
-    createRequest(request: IncomingMessage): HTTPRequest;
+    private readonly trustProxy;
+    constructor(options?: NodeRequestTrustOptions);
+    createRequest(request: IncomingMessage, options?: NodeRequestTrustOptions): HTTPRequest;
     createResponse(response: ServerResponse): HTTPResponse;
     createContext(request: HTTPRequest, response: HTTPResponse, options?: {
         readonly state?: State;
@@ -20,12 +33,19 @@ export declare class NodeHTTPAdapter<State extends HTTPState = HTTPState> implem
 }
 export interface HTTPAdapterOptions<State extends HTTPState = HTTPState> {
     readonly adapter?: HTTPAdapter<State>;
+    /**
+     * Which socket peers may speak for a client through `X-Forwarded-*`.
+     * Defaults to `false` — forwarded headers are ignored.
+     */
+    readonly trustProxy?: TrustProxy;
 }
-export declare function createHTTPAdapter<State extends HTTPState = HTTPState>(): NodeHTTPAdapter<State>;
+export declare function createHTTPAdapter<State extends HTTPState = HTTPState>(options?: NodeRequestTrustOptions): NodeHTTPAdapter<State>;
 export interface RequestAdapter {
     toHTTPRequest(request: IncomingMessage): HTTPRequest;
 }
 export declare class NodeRequestAdapter implements RequestAdapter {
+    private readonly trustProxy;
+    constructor(options?: NodeRequestTrustOptions);
     toHTTPRequest(request: IncomingMessage): HTTPRequest;
 }
 export interface ResponseAdapter {
@@ -61,11 +81,12 @@ export declare class DefaultHTTPMiddlewareAdapter<State extends HTTPState = HTTP
 export interface HTTPRouteAdapter<State extends HTTPState = HTTPState> {
     match(method: string, path: string): HTTPRouteMatch<State> | undefined;
 }
-export declare function adaptNodeRequest(request: IncomingMessage): HTTPRequest;
+export declare function adaptNodeRequest(request: IncomingMessage, options?: NodeRequestTrustOptions): HTTPRequest;
 export declare function adaptNodeResponse(response: ServerResponse): HTTPResponse;
 export declare function adaptNodeContext<State extends HTTPState = HTTPState>(request: IncomingMessage, response: ServerResponse, options?: {
     readonly state?: State;
     readonly signal?: AbortSignal;
+    readonly trustProxy?: TrustProxy;
 }): HTTPContext<State>;
 export declare function isHTTPAdapter(value: unknown): value is HTTPAdapter;
 //# sourceMappingURL=http.adapters.d.ts.map

package/dist/httpAdapter/http.adapters.js

@@ -1,13 +1,17 @@
 import { createHTTPContext } from "../httpContext/http.context.js";
 import { createHTTPRequest } from "../httpRequest/http.request.js";
 import { createHTTPResponse } from "../httpResponse/http.response.js";
-/* -------------------------------------------------------------------------- */
-/* Node Adapter                                                               */
-/* -------------------------------------------------------------------------- */
+import { createDefaultContextLogger } from "./httpAdapter.logger.js";
 export class NodeHTTPAdapter {
     name = "node";
-    createRequest(request) {
-        return createHTTPRequest(request);
+    trustProxy;
+    constructor(options = {}) {
+        this.trustProxy = options.trustProxy ?? false;
+    }
+    createRequest(request, options = {}) {
+        return createHTTPRequest(request, {
+            trustProxy: options.trustProxy ?? this.trustProxy,
+        });
     }
     createResponse(response) {
         return createHTTPResponse(response);
@@ -18,19 +22,23 @@ export class NodeHTTPAdapter {
             response,
             state: options.state ?? {},
             signal: options.signal,
-            logger: createFallbackLogger(),
+            logger: createDefaultContextLogger(),
         });
     }
 }
 /* -------------------------------------------------------------------------- */
 /* Adapter Factory                                                             */
 /* -------------------------------------------------------------------------- */
-export function createHTTPAdapter() {
-    return new NodeHTTPAdapter();
+export function createHTTPAdapter(options = {}) {
+    return new NodeHTTPAdapter(options);
 }
 export class NodeRequestAdapter {
+    trustProxy;
+    constructor(options = {}) {
+        this.trustProxy = options.trustProxy ?? false;
+    }
     toHTTPRequest(request) {
-        return createHTTPRequest(request);
+        return createHTTPRequest(request, { trustProxy: this.trustProxy });
     }
 }
 export class NodeResponseAdapter {
@@ -45,7 +53,7 @@ export class NodeContextAdapter {
             response,
             state: options.state ?? {},
             signal: options.signal,
-            logger: createFallbackLogger(),
+            logger: createDefaultContextLogger(),
         });
     }
 }
@@ -75,19 +83,21 @@ export class DefaultHTTPMiddlewareAdapter {
 /* -------------------------------------------------------------------------- */
 /* Request Conversion Helpers                                                  */
 /* -------------------------------------------------------------------------- */
-export function adaptNodeRequest(request) {
-    return createHTTPRequest(request);
+export function adaptNodeRequest(request, options = {}) {
+    return createHTTPRequest(request, {
+        trustProxy: options.trustProxy ?? false,
+    });
 }
 export function adaptNodeResponse(response) {
     return createHTTPResponse(response);
 }
 export function adaptNodeContext(request, response, options = {}) {
     return createHTTPContext({
-        request: adaptNodeRequest(request),
+        request: adaptNodeRequest(request, { trustProxy: options.trustProxy }),
         response: adaptNodeResponse(response),
         state: options.state ?? {},
         signal: options.signal,
-        logger: createFallbackLogger(),
+        logger: createDefaultContextLogger(),
     });
 }
 /* -------------------------------------------------------------------------- */
@@ -103,35 +113,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

@@ -23,8 +23,8 @@ export interface ResolvedErrorResponse {
 /**
  * Builds the default response for an unhandled error.
  *
- * - An error (or any error in its `cause` / `errors` chain) with a 4xx/5xx
- *   `statusCode` is answered with that status.
+ * - 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.

package/dist/httpAdapter/httpAdapter.errorResponse.js

@@ -17,6 +17,7 @@
  */
 import { getStatusText } from "../httpResponse/core/httpResponse.statusText.js";
 import { isValidHeaderFieldValue } from "../httpHeaders/security/index.js";
+import { HttpMiddlewareError, HttpMiddlewarePipelineError, } from "../httpMiddleware/httpMiddleware.error.js";
 /* -------------------------------------------------------------------------- */
 /* Constants                                                                  */
 /* -------------------------------------------------------------------------- */
@@ -30,11 +31,25 @@ const MAX_UNWRAP_DEPTH = 8;
 /* Resolution                                                                 */
 /* -------------------------------------------------------------------------- */
 /**
- * Locates the innermost error that carries an HTTP status.
+ * 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 innermost one wins because outer errors are wrappers added on the way
- * out (middleware, pipeline, adapter); the error the application actually
- * threw sits at the bottom of the chain.
+ * 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) {
@@ -45,6 +60,11 @@ function findStatusError(error, depth, seen) {
     }
     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);
@@ -58,9 +78,6 @@ function findStatusError(error, depth, seen) {
             return found;
         }
     }
-    if (isHttpStatus(candidate.statusCode)) {
-        return candidate;
-    }
     return undefined;
 }
 function isHttpStatus(value) {
@@ -72,8 +89,8 @@ function isHttpStatus(value) {
 /**
  * Builds the default response for an unhandled error.
  *
- * - An error (or any error in its `cause` / `errors` chain) with a 4xx/5xx
- *   `statusCode` is answered with that status.
+ * - 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.

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,6 +26,7 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     private readonly connectionsCheckingInterval;
     private readonly shutdownGraceMs;
     private readonly events;
+    private readonly requestGuard;
     private server;
     private ownsServer;
     /**
@@ -50,6 +52,10 @@ 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;
@@ -65,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

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

@@ -9,13 +9,15 @@
 import { IncomingMessage, Server, ServerResponse, createServer, } from "node:http";
 import { HttpRequestContext } from "../../httpRequest/httpRequest.context.js";
 import { HttpResponseContext, createResponseContext, } from "../../httpResponse/httpResponse.context.js";
-import { BaseHttpAdapter } from "../http.adapter.js";
+import { BaseHttpAdapter, normalizeHandlerResult } from "../http.adapter.js";
 import { writeResponse } from "../../httpResponse/httpResponse.writer.js";
 import { DEFAULT_HOST, DEFAULT_PORT, DEFAULT_MAX_BODY_SIZE, NODE_DEFAULT_HEADERS_TIMEOUT, NODE_DEFAULT_REQUEST_TIMEOUT, NODE_DEFAULT_KEEP_ALIVE_TIMEOUT, validatePort, validateMaxBodySize, } from "./httpNode.type.js";
 import { NodeResponseWriter } from "./httpNode.response.js";
+import { compileTrustProxy } from "../../httpTrustProxy/httpTrustProxy.compilation.js";
+import { createNodeRequestGuard } from "../../httpSecurity/httpSecurity.nodeGuard.js";
 import { createNodeRequestContext } from "./httpNode.request.js";
 import { resolveErrorResponse } from "../httpAdapter.errorResponse.js";
-import { isIncomingMessage, isServerResponse, isNodeRequestResponsePair, configureServer, listen, closeServer, readNodeRequestBody, NodeRequestBodyTooLargeError, isResponseContextLike, } from "./httpNode.server.js";
+import { isIncomingMessage, isServerResponse, isNodeRequestResponsePair, configureServer, listen, closeServer, readNodeRequestBody, NodeRequestBodyTooLargeError, } from "./httpNode.server.js";
 /* -------------------------------------------------------------------------- */
 /* Node HTTP Adapter                                                          */
 /* -------------------------------------------------------------------------- */
@@ -32,6 +34,7 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
     connectionsCheckingInterval;
     shutdownGraceMs;
     events;
+    requestGuard;
     server;
     ownsServer = false;
     /**
@@ -73,7 +76,11 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
                 Math.min(30_000, this.headersTimeout);
         this.shutdownGraceMs = options.shutdownGraceMs;
         this.trustProxy = options.trustProxy;
+        if (options.trustProxy !== undefined) {
+            compileTrustProxy(options.trustProxy);
+        }
         this.events = options.events ?? {};
+        this.requestGuard = createNodeRequestGuard(options.security);
         this.server = options.server;
         this.ownsServer = !options.server;
     }
@@ -132,6 +139,10 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
         }
         const request = input.request;
         const response = input.response;
+        if (this.requestGuard && !this.requestGuard(request).allowed) {
+            await this.writeBadRequest(response);
+            return;
+        }
         let context;
         try {
             context = this.createRequest(request);
@@ -183,17 +194,12 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
         }
         return this.handler(request);
     }
+    /**
+     * Plain objects are data and are sent as JSON; see
+     * `normalizeHandlerResult`.
+     */
     normalizeResult(result) {
-        if (result instanceof HttpResponseContext) {
-            return result;
-        }
-        if (result === undefined || result === null) {
-            return createResponseContext();
-        }
-        if (isResponseContextLike(result)) {
-            return createResponseContext(result);
-        }
-        return createResponseContext().json(result);
+        return normalizeHandlerResult(result);
     }
     async handleNodeError(error, request, response) {
         if (response.headersSent) {
@@ -326,12 +332,20 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
         }
         await super.start();
     }
-    async stop() {
+    /**
+     * Closes the server. The grace period is `options.graceMs` (the server's
+     * `gracefulShutdownTimeout`), capped by an explicit `shutdownGraceMs`;
+     * with neither it is 10 s.
+     */
+    async stop(options = {}) {
         if (!this.server || !this.server.listening) {
             await super.stop();
             return;
         }
-        await closeServer(this.server, { graceMs: this.shutdownGraceMs });
+        const graceMs = options.graceMs === undefined
+            ? this.shutdownGraceMs
+            : Math.min(options.graceMs, this.shutdownGraceMs ?? Infinity);
+        await closeServer(this.server, { graceMs });
         if (this.clientErrorListener) {
             this.server.off("clientError", this.clientErrorListener);
             this.clientErrorListener = undefined;

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

@@ -21,13 +21,14 @@ export declare function getNodeRemoteAddress(request: IncomingMessage, options?:
 /**
  * Parses the request-target's query string into a flat record.
  *
- * Every value is attacker-controlled. `decodeURIComponent` throws on a
- * malformed sequence such as `%E0`, and this ran before the adapter's
- * try/catch, so one such request tore the connection down instead of being
- * answered. Decoding is delegated to the query module's non-throwing
- * decoder, which also gives `+` its form-encoding meaning. A pair is split on
- * its **first** `=` so `a=b=c` keeps the value `b=c`.
+ * Every value is attacker-controlled, so decoding never throws (a malformed
+ * `%E0` is kept raw) and `+` has its form-encoding meaning. This uses the same
+ * parser as the router's `ctx.query` (`parseQueryString`), so both agree: a
+ * repeated name is an array (`?role=user&role=admin` gives
+ * `["user", "admin"]`), the record has a `null` prototype, and
+ * `__proto__` / `constructor` / `prototype` are dropped. Previously the last
+ * value silently won here while the router returned the array.
  */
-export declare function parseNodeQuery(request: IncomingMessage): Readonly<Record<string, string>>;
+export declare function parseNodeQuery(request: IncomingMessage): Readonly<Record<string, string | readonly string[]>>;
 export declare function createNodeRequestContext(request: IncomingMessage, options?: NodeRequestOptions): HttpRequestContext;
 //# sourceMappingURL=httpNode.request.d.ts.map