@zudojs/http 1.0.0 → 1.2.0

package/dist/httpResponse/httpResponse.context.js

@@ -5,6 +5,7 @@
  */
 import { DEFAULT_RESPONSE_STATUS } from "./core/httpResponse.type.js";
 import { getStatusText } from "./core/httpResponse.statusText.js";
+import { assertSafeRedirect } from "../httpRedirect/http.redirect.js";
 export class HttpResponseContext {
     _status;
     _statusText;
@@ -86,10 +87,21 @@ export class HttpResponseContext {
         this._cookies = this._cookies.filter((c) => c.name !== name);
         return this;
     }
+    /**
+     * Redirects to `url`.
+     *
+     * The destination goes through `assertSafeRedirect`: a `javascript:` or
+     * `data:` URL, a scheme-relative `//evil.com`, or a value carrying a
+     * control character throws instead of being emitted as `Location`. An
+     * absolute `http(s)` URL and a same-origin path reference are accepted.
+     *
+     * @throws {TypeError} If the destination is not a safe redirect target.
+     */
     redirect(url, status = 302) {
+        const location = assertSafeRedirect(url);
         this._status = status;
         this._statusText = getStatusText(status);
-        this._headers["location"] = url;
+        this._headers["location"] = location;
         return this;
     }
     markSent() {

package/dist/httpResponse/httpResponse.helper.d.ts

@@ -30,6 +30,12 @@ export declare function htmlResponse(html: string, status?: number, headers?: Re
 };
 /**
  * Creates a redirect response.
+ *
+ * The destination goes through {@link assertSafeRedirect}: a `javascript:` or
+ * `data:` URL, a scheme-relative `//evil.com`, or a value carrying a control
+ * character throws instead of being emitted as `Location`.
+ *
+ * @throws {TypeError} If the destination is not a safe redirect target.
  */
 export declare function redirectResponse(url: string, status?: number, headers?: ResponseHeaders): {
     readonly status: number;
@@ -46,6 +52,22 @@ export declare function emptyResponse(status?: number, headers?: ResponseHeaders
 };
 /**
  * Serializes a response cookie into a Set-Cookie header string.
+ *
+ * This is the serializer the adapters use for `response.cookie()` and it
+ * previously concatenated every field verbatim, so a value such as
+ * `x; Domain=evil.com` became a second attribute and a `__Host-` cookie
+ * missing `Secure` was emitted (and silently dropped by the browser). It now
+ * applies the same rules as `serializeCookie()` in the cookies module:
+ *
+ * - the name must be an RFC 6265 token;
+ * - `__Host-` / `__Secure-` prefix constraints are enforced;
+ * - `Domain` and `Path` may not contain `;` or a control character;
+ * - a value that is not made only of `cookie-octet` characters is
+ *   percent-encoded, so it can neither inject an attribute nor split the
+ *   header (a value that is already valid is emitted unchanged);
+ * - `maxAge` must be finite and `expires` must be a valid `Date`.
+ *
+ * @throws {TypeError} If the name, a prefix rule or an attribute is invalid.
  */
 export declare function serializeResponseCookie(cookie: ResponseCookie): string;
 //# sourceMappingURL=httpResponse.helper.d.ts.map

package/dist/httpResponse/httpResponse.helper.js

@@ -3,6 +3,8 @@
  *
  * @module httpResponse/helpers
  */
+import { withSecureCookieDefaults } from "../httpCookies/httpCookies.defaults.js";
+import { assertSafeRedirect } from "../httpRedirect/http.redirect.js";
 /**
  * Creates a JSON response.
  */
@@ -44,12 +46,18 @@ export function htmlResponse(html, status = 200, headers = {}) {
 }
 /**
  * Creates a redirect response.
+ *
+ * The destination goes through {@link assertSafeRedirect}: a `javascript:` or
+ * `data:` URL, a scheme-relative `//evil.com`, or a value carrying a control
+ * character throws instead of being emitted as `Location`.
+ *
+ * @throws {TypeError} If the destination is not a safe redirect target.
  */
 export function redirectResponse(url, status = 302, headers = {}) {
     return {
         status,
         headers: {
-            location: url,
+            location: assertSafeRedirect(url),
             ...headers,
         },
         body: undefined,
@@ -65,40 +73,102 @@ export function emptyResponse(status = 204, headers = {}) {
         body: undefined,
     };
 }
+/**
+ * RFC 6265 `cookie-name`, which is an RFC 9110 `token`.
+ */
+const COOKIE_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * RFC 6265 `cookie-octet`: printable US-ASCII minus CTLs, SP, DQUOTE, comma,
+ * semicolon and backslash.
+ */
+const COOKIE_OCTETS = /^[\u0021\u0023-\u002b\u002d-\u003a\u003c-\u005b\u005d-\u007e]*$/;
+/**
+ * Characters that must never appear in a cookie attribute value: `;` starts
+ * the next attribute, and any control character can split the header.
+ */
+const COOKIE_ATTRIBUTE_FORBIDDEN = /[;\u0000-\u001f\u007f]/;
 /**
  * Serializes a response cookie into a Set-Cookie header string.
+ *
+ * This is the serializer the adapters use for `response.cookie()` and it
+ * previously concatenated every field verbatim, so a value such as
+ * `x; Domain=evil.com` became a second attribute and a `__Host-` cookie
+ * missing `Secure` was emitted (and silently dropped by the browser). It now
+ * applies the same rules as `serializeCookie()` in the cookies module:
+ *
+ * - the name must be an RFC 6265 token;
+ * - `__Host-` / `__Secure-` prefix constraints are enforced;
+ * - `Domain` and `Path` may not contain `;` or a control character;
+ * - a value that is not made only of `cookie-octet` characters is
+ *   percent-encoded, so it can neither inject an attribute nor split the
+ *   header (a value that is already valid is emitted unchanged);
+ * - `maxAge` must be finite and `expires` must be a valid `Date`.
+ *
+ * @throws {TypeError} If the name, a prefix rule or an attribute is invalid.
  */
 export function serializeResponseCookie(cookie) {
-    let str = `${cookie.name}=${cookie.value}`;
-    if (cookie.options) {
-        const opts = cookie.options;
-        if (opts.domain) {
-            str += `; Domain=${opts.domain}`;
-        }
-        if (opts.path) {
-            str += `; Path=${opts.path}`;
-        }
-        if (opts.expires instanceof Date) {
-            str += `; Expires=${opts.expires.toUTCString()}`;
+    const name = cookie.name;
+    if (!name || !COOKIE_NAME_TOKEN.test(name)) {
+        throw new TypeError(`Invalid cookie name: ${JSON.stringify(name)}`);
+    }
+    const opts = withSecureCookieDefaults(cookie.options, "Lax");
+    if (name.startsWith("__Host-")) {
+        if (!opts.secure) {
+            throw new TypeError("A __Host- cookie requires the Secure attribute.");
         }
-        if (typeof opts.maxAge === "number") {
-            str += `; Max-Age=${opts.maxAge}`;
+        if (opts.domain) {
+            throw new TypeError("A __Host- cookie must not set a Domain attribute.");
         }
-        if (opts.httpOnly) {
-            str += "; HttpOnly";
+        if ((opts.path ?? "/") !== "/") {
+            throw new TypeError("A __Host- cookie requires Path=/.");
         }
-        if (opts.secure) {
-            str += "; Secure";
+    }
+    else if (name.startsWith("__Secure-") && !opts.secure) {
+        throw new TypeError("A __Secure- cookie requires the Secure attribute.");
+    }
+    const rawValue = String(cookie.value);
+    const value = COOKIE_OCTETS.test(rawValue)
+        ? rawValue
+        : encodeURIComponent(rawValue);
+    let str = `${name}=${value}`;
+    if (opts.domain) {
+        if (COOKIE_ATTRIBUTE_FORBIDDEN.test(opts.domain)) {
+            throw new TypeError("Invalid cookie domain.");
         }
-        if (opts.sameSite) {
-            str += `; SameSite=${opts.sameSite}`;
+        str += `; Domain=${opts.domain}`;
+    }
+    if (opts.path) {
+        if (COOKIE_ATTRIBUTE_FORBIDDEN.test(opts.path)) {
+            throw new TypeError("Invalid cookie path.");
         }
-        if (opts.priority) {
-            str += `; Priority=${opts.priority}`;
+        str += `; Path=${opts.path}`;
+    }
+    if (opts.expires instanceof Date) {
+        if (Number.isNaN(opts.expires.getTime())) {
+            throw new TypeError("Cookie expires must be a valid Date.");
         }
-        if (opts.partitioned) {
-            str += "; Partitioned";
+        str += `; Expires=${opts.expires.toUTCString()}`;
+    }
+    if (typeof opts.maxAge === "number") {
+        if (!Number.isFinite(opts.maxAge)) {
+            throw new TypeError("Cookie maxAge must be a finite number.");
         }
+        str += `; Max-Age=${Math.floor(opts.maxAge)}`;
+    }
+    if (opts.httpOnly) {
+        str += "; HttpOnly";
+    }
+    if (opts.secure) {
+        str += "; Secure";
+    }
+    if (opts.sameSite) {
+        str += `; SameSite=${opts.sameSite}`;
+    }
+    if (opts.priority) {
+        str += `; Priority=${opts.priority}`;
+    }
+    if (opts.partitioned) {
+        str += "; Partitioned";
     }
     return str;
 }

package/dist/httpRouter/core/registry/core/httpRegistry.helper.js

@@ -42,7 +42,7 @@ export function normalizePath(path, options) {
         normalized = normalized.toLowerCase();
     }
     if (!options.strict) {
-        normalized = normalized.replace(/\/+$/, "") || "/";
+        normalized = normalized.replace(/(?<!\/)\/+$/, "") || "/";
     }
     return normalized;
 }

package/dist/httpRouter/core/util/httpRoute.util.d.ts

@@ -8,7 +8,21 @@ import type { HttpRequestContext as RequestContext } from "../../../httpRequest/
 export declare function getRequestMethod(request: RequestContext): string;
 export declare function getRequestUrl(request: RequestContext): string;
 export declare function getRequestSignal(request: RequestContext): AbortSignal | undefined;
+/**
+ * Parses a request-target with the canonical parser shared by the request
+ * context and path-scoped middleware.
+ */
 export declare function parseUrl(value: string): URL;
+/**
+ * Builds the router's query record.
+ *
+ * Uses the same parser as the Node adapter's `request.query`
+ * (`parseQueryString`): a repeated name is an array, the record has a `null`
+ * prototype, and `__proto__` / `constructor` / `prototype` are dropped. The
+ * two used to disagree (`ctx.query.role` an array, `request.getQuery("role")`
+ * the last value), which let middleware and handlers read different values
+ * for the same parameter.
+ */
 export declare function parseQuery(params: URLSearchParams): Readonly<Record<string, string | string[]>>;
 export declare function normalizePath(path: string): string;
 export declare function splitPath(path: string): string[];

package/dist/httpRouter/core/util/httpRoute.util.js

@@ -4,6 +4,8 @@
  * Request accessors, URL/query parsing, and path normalization shared by the
  * router core.
  */
+import { parseRequestTarget } from "../../../httpRequest/target/httpRequest.target.js";
+import { parseQueryString } from "../../../httpQuery/http.query.js";
 import { InvalidRoutePatternError } from "../error/httpRouter.error.js";
 export function getRequestMethod(request) {
     const value = request.method;
@@ -19,23 +21,25 @@ export function getRequestUrl(request) {
 export function getRequestSignal(request) {
     return request.signal;
 }
+/**
+ * Parses a request-target with the canonical parser shared by the request
+ * context and path-scoped middleware.
+ */
 export function parseUrl(value) {
-    try {
-        return new URL(value, "http://zudojs.local");
-    }
-    catch {
-        return new URL("/", "http://zudojs.local");
-    }
+    return parseRequestTarget(value);
 }
+/**
+ * Builds the router's query record.
+ *
+ * Uses the same parser as the Node adapter's `request.query`
+ * (`parseQueryString`): a repeated name is an array, the record has a `null`
+ * prototype, and `__proto__` / `constructor` / `prototype` are dropped. The
+ * two used to disagree (`ctx.query.role` an array, `request.getQuery("role")`
+ * the last value), which let middleware and handlers read different values
+ * for the same parameter.
+ */
 export function parseQuery(params) {
-    const result = {};
-    for (const key of new Set(Array.from(params.keys()))) {
-        const values = params.getAll(key);
-        result[key] = values.length > 1 ? values : (values[0] ?? "");
-    }
-    return Object.freeze({
-        ...result,
-    });
+    return Object.freeze(parseQueryString(params.toString()));
 }
 /* -------------------------------------------------------------------------- */
 /* Path Helpers                                                               */

package/dist/httpRouter/dispatch/httpRoute.dispatcher.js

@@ -229,8 +229,19 @@ function toDispatchHandler(handler, context) {
             signal: getRequestSignal(request),
         }));
         if (result instanceof HttpResponseContext && result !== response) {
-            response.status_code(result.status);
+            /*
+             * Everything the handler put on its response must survive the merge.
+             * Copying only status, headers and body dropped every cookie the
+             * handler set, its custom status text and its metadata.
+             */
+            response.setStatus(result.status, result.statusText);
             response.headers_obj(result.headers);
+            for (const cookie of result.cookies) {
+                response.setCookie(cookie);
+            }
+            for (const [key, value] of Object.entries(result.metadata)) {
+                response.setMetadata(key, value);
+            }
             response.setBody(result.body);
         }
     };

package/dist/httpSecurity/httpSecurity.config.d.ts

@@ -26,6 +26,12 @@ export interface HTTPSecurityConfig {
     readonly maxQueryLength?: number;
     /** Allowed Host header values. Empty = allow all. */
     readonly allowedHosts?: readonly string[];
+    /**
+     * Whether a request without a Host header is rejected (default: true).
+     * The Node adapter relaxes this for HTTP/1.0 requests, where Host is
+     * optional and some load-balancer health checks omit it.
+     */
+    readonly requireHost?: boolean;
     /**
      * Whether `X-Forwarded-*` headers may be trusted (default: `false`).
      *

package/dist/httpSecurity/httpSecurity.config.js

@@ -20,6 +20,7 @@ export const DEFAULT_SECURITY_CONFIG = Object.freeze({
     maxUrlLength: 2048,
     maxQueryLength: 4096,
     allowedHosts: [],
+    requireHost: true,
     trustProxy: false,
     maxRequestIdLength: 128,
     requestIdPattern: /^[a-zA-Z0-9_-]+$/,

package/dist/httpSecurity/httpSecurity.guard.d.ts

@@ -5,6 +5,7 @@
  * first security boundary. Rejects malformed, oversized, or
  * suspicious requests before they reach the router.
  */
+import { HttpRequestGuardError } from "@zudojs/errors";
 import type { HTTPSecurityConfig } from "./httpSecurity.config.js";
 /** A request-like object for validation (keeps the guard decoupled from HTTP types). */
 export interface GuardableRequest {
@@ -39,16 +40,13 @@ export declare function guardRequest(request: GuardableRequest, config?: Partial
  */
 export declare function createRequestGuard(config?: Partial<HTTPSecurityConfig>): (request: GuardableRequest) => GuardResult;
 /**
- * Error thrown by {@link assertRequestAllowed}.
- *
- * Carries the status the response should use and the individual validation
- * failures, so a caller can log the detail without returning it to the client.
+ * Error thrown by {@link assertRequestAllowed}: the shared
+ * `HttpRequestGuardError` from `@zudojs/errors` (a `BaseError`, code
+ * `HTTP_REQUEST_REJECTED`, not exposed). It carries the status the response
+ * should use and the individual validation failures, so a caller can log
+ * the detail without returning it to the client.
  */
-export declare class HttpRequestGuardError extends Error {
-    readonly statusCode: number;
-    readonly errors: readonly string[];
-    constructor(result: GuardResult);
-}
+export { HttpRequestGuardError };
 /**
  * Runs the guard and throws {@link HttpRequestGuardError} when the request is
  * rejected.

package/dist/httpSecurity/httpSecurity.guard.js

@@ -5,6 +5,7 @@
  * first security boundary. Rejects malformed, oversized, or
  * suspicious requests before they reach the router.
  */
+import { HttpRequestGuardError } from "@zudojs/errors";
 import { validateHeaders, validateHost, validateUrl, validateQuery, validateContentLength, validateRequestId, validateTransferEncoding, } from "./httpSecurity.validator.js";
 /**
  * Run all security validations against an incoming request.
@@ -52,21 +53,13 @@ export function createRequestGuard(config) {
     return (request) => guardRequest(request, config);
 }
 /**
- * Error thrown by {@link assertRequestAllowed}.
- *
- * Carries the status the response should use and the individual validation
- * failures, so a caller can log the detail without returning it to the client.
+ * Error thrown by {@link assertRequestAllowed}: the shared
+ * `HttpRequestGuardError` from `@zudojs/errors` (a `BaseError`, code
+ * `HTTP_REQUEST_REJECTED`, not exposed). It carries the status the response
+ * should use and the individual validation failures, so a caller can log
+ * the detail without returning it to the client.
  */
-export class HttpRequestGuardError extends Error {
-    statusCode;
-    errors;
-    constructor(result) {
-        super(`Request rejected by security guard: ${result.errors.join("; ")}`);
-        this.name = "HttpRequestGuardError";
-        this.statusCode = result.statusCode;
-        this.errors = result.errors;
-    }
-}
+export { HttpRequestGuardError };
 /**
  * Runs the guard and throws {@link HttpRequestGuardError} when the request is
  * rejected.

package/dist/httpSecurity/httpSecurity.nodeGuard.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Request guard wiring for the Node adapter.
+ *
+ * `guardRequest` (Host, request-ID, header-count, header-size, URL/query
+ * length and `Transfer-Encoding`/`Content-Length` checks) had no call site,
+ * so every one of those checks was inert unless an application wired it by
+ * hand. The Node adapter now runs it on every request before the request
+ * context is built or the body is read, and answers `400` when it refuses.
+ *
+ * @module httpSecurity/nodeGuard
+ */
+import type { IncomingMessage } from "node:http";
+import type { HTTPSecurityConfig } from "./httpSecurity.config.js";
+import { type GuardResult } from "./httpSecurity.guard.js";
+/**
+ * The adapter's `security` option.
+ *
+ * - `true` / omitted (default): run the guard with its defaults.
+ * - an object: run the guard with that configuration.
+ * - `false`: do not run the guard.
+ */
+export type NodeAdapterSecurityOption = boolean | Partial<HTTPSecurityConfig>;
+/**
+ * Adapter options contributed by the request guard.
+ */
+export interface NodeAdapterSecurityOptions {
+    /**
+     * Request guard applied before dispatch (on by default). See
+     * {@link NodeAdapterSecurityOption}.
+     *
+     * The guard's `maxBodySize` defaults to "no limit" here so the adapter's own
+     * `maxBodySize` keeps answering oversized bodies with `413`; set it
+     * explicitly to have the guard refuse a too-large `Content-Length` with
+     * `400` before any body is read. `requireHost` defaults to `true` except for
+     * HTTP/1.0 requests, where Host is optional.
+     */
+    readonly security?: NodeAdapterSecurityOption;
+}
+/**
+ * A per-request guard for Node requests.
+ */
+export type NodeRequestGuard = (request: IncomingMessage) => GuardResult;
+/**
+ * Builds the guard the adapter runs on each request, or `undefined` when the
+ * guard is disabled with `security: false`.
+ */
+export declare function createNodeRequestGuard(option: NodeAdapterSecurityOption | undefined): NodeRequestGuard | undefined;
+//# sourceMappingURL=httpSecurity.nodeGuard.d.ts.map

package/dist/httpSecurity/httpSecurity.nodeGuard.js

@@ -0,0 +1,32 @@
+/**
+ * Request guard wiring for the Node adapter.
+ *
+ * `guardRequest` (Host, request-ID, header-count, header-size, URL/query
+ * length and `Transfer-Encoding`/`Content-Length` checks) had no call site,
+ * so every one of those checks was inert unless an application wired it by
+ * hand. The Node adapter now runs it on every request before the request
+ * context is built or the body is read, and answers `400` when it refuses.
+ *
+ * @module httpSecurity/nodeGuard
+ */
+import { guardRequest, } from "./httpSecurity.guard.js";
+/**
+ * Builds the guard the adapter runs on each request, or `undefined` when the
+ * guard is disabled with `security: false`.
+ */
+export function createNodeRequestGuard(option) {
+    if (option === false) {
+        return undefined;
+    }
+    const configured = typeof option === "object" ? option : {};
+    return (request) => guardRequest({
+        method: request.method ?? "GET",
+        url: request.url ?? "/",
+        headers: request.headers,
+    }, {
+        maxBodySize: Number.MAX_SAFE_INTEGER,
+        requireHost: request.httpVersion !== "1.0",
+        ...configured,
+    });
+}
+//# sourceMappingURL=httpSecurity.nodeGuard.js.map

package/dist/httpSecurity/httpSecurity.validator.js

@@ -36,10 +36,12 @@ export function validateHeaders(headers, config) {
  * Validate the Host header against allowed hosts.
  */
 export function validateHost(host, config) {
+    const cfg = resolveConfig(config);
     if (!host) {
-        return { valid: false, errors: ["Missing Host header"] };
+        return cfg.requireHost
+            ? { valid: false, errors: ["Missing Host header"] }
+            : { valid: true, errors: [] };
     }
-    const cfg = resolveConfig(config);
     if (cfg.allowedHosts.length === 0) {
         return { valid: true, errors: [] };
     }

package/dist/httpSecurity/index.d.ts

@@ -11,4 +11,6 @@ export type { SecurityValidationResult } from "./httpSecurity.validator.js";
 export { validateHeaders, validateHost, validateUrl, validateQuery, validateContentLength, validateRequestId, validateTransferEncoding, } from "./httpSecurity.validator.js";
 export type { GuardableRequest, GuardResult } from "./httpSecurity.guard.js";
 export { guardRequest, createRequestGuard, assertRequestAllowed, HttpRequestGuardError, } from "./httpSecurity.guard.js";
+export type { NodeAdapterSecurityOption, NodeAdapterSecurityOptions, NodeRequestGuard, } from "./httpSecurity.nodeGuard.js";
+export { createNodeRequestGuard } from "./httpSecurity.nodeGuard.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpSecurity/index.js

@@ -8,4 +8,5 @@
 export { DEFAULT_SECURITY_CONFIG } from "./httpSecurity.config.js";
 export { validateHeaders, validateHost, validateUrl, validateQuery, validateContentLength, validateRequestId, validateTransferEncoding, } from "./httpSecurity.validator.js";
 export { guardRequest, createRequestGuard, assertRequestAllowed, HttpRequestGuardError, } from "./httpSecurity.guard.js";
+export { createNodeRequestGuard } from "./httpSecurity.nodeGuard.js";
 //# sourceMappingURL=index.js.map

package/dist/httpServer/core/httpServer.core.d.ts

@@ -45,6 +45,12 @@ export declare class HttpServer {
     close(): Promise<this>;
     setHandler(handler: HttpHandler): this;
     setErrorHandler(handler: HttpErrorHandler): this;
+    /**
+     * Installs `handler` on the adapter, wrapped so every dispatch is counted
+     * (`requests`, `onRequest`) and its completion reported (`onResponse`).
+     * Nothing called `recordRequest`/`recordResponse` before, so the counter
+     * and both events stayed at zero.
+     */
     private adapterHandler;
     private adapterErrorHandler;
     recordRequest(): void;
@@ -61,6 +67,11 @@ export declare class HttpServer {
     snapshot(): HttpServerSnapshot;
     toJSON(): HttpServerSnapshot;
     private performStart;
+    /**
+     * The adapter is told the shutdown timeout as its grace period, so
+     * in-flight requests get the documented `gracefulShutdownTimeout` rather
+     * than the Node adapter's hidden 10 s default.
+     */
     private performStop;
     private refreshAddress;
 }

package/dist/httpServer/core/httpServer.core.js

@@ -6,6 +6,7 @@
 import { isHttpAdapter, startAdapter, stopAdapter, } from "../../httpAdapter/http.adapter.js";
 import { HttpServerLifecycleError, InvalidHttpServerStateError, HttpServerStartError, HttpServerStopError, } from "@zudojs/errors";
 import { withTimeout, validateShutdownTimeout, } from "../factory/httpServer.factory.js";
+const SHUTDOWN_CLOSE_MARGIN_MS = 1_000;
 export class HttpServer {
     name;
     adapter;
@@ -170,7 +171,22 @@ export class HttpServer {
         this.adapterErrorHandler(handler);
         return this;
     }
-    adapterHandler(handler) {
+    /**
+     * Installs `handler` on the adapter, wrapped so every dispatch is counted
+     * (`requests`, `onRequest`) and its completion reported (`onResponse`).
+     * Nothing called `recordRequest`/`recordResponse` before, so the counter
+     * and both events stayed at zero.
+     */
+    adapterHandler(application) {
+        const handler = async (request) => {
+            this.recordRequest();
+            try {
+                return await application(request);
+            }
+            finally {
+                this.recordResponse();
+            }
+        };
         const adapter = this.adapter;
         if (typeof adapter.setHandler === "function") {
             adapter.setHandler(handler);
@@ -262,13 +278,23 @@ export class HttpServer {
     async performStart() {
         await startAdapter(this.adapter);
     }
+    /**
+     * The adapter is told the shutdown timeout as its grace period, so
+     * in-flight requests get the documented `gracefulShutdownTimeout` rather
+     * than the Node adapter's hidden 10 s default.
+     */
+    /*
+     * The adapter gets the full timeout as its grace period and then destroys
+     * the remaining sockets; the margin only lets that close complete before
+     * the stop is reported as timed out.
+     */
     async performStop(force, timeout) {
         if (force) {
-            await stopAdapter(this.adapter);
+            await stopAdapter(this.adapter, { graceMs: 0 });
             return;
         }
         try {
-            await withTimeout(stopAdapter(this.adapter), timeout, "HTTP server shutdown timed out.");
+            await withTimeout(stopAdapter(this.adapter, { graceMs: timeout }), timeout + SHUTDOWN_CLOSE_MARGIN_MS, "HTTP server shutdown timed out.");
         }
         catch (error) {
             /*
@@ -277,7 +303,7 @@ export class HttpServer {
              * rebind the port. Escalate to a forced stop before rethrowing.
              */
             try {
-                await stopAdapter(this.adapter);
+                await stopAdapter(this.adapter, { graceMs: 0 });
             }
             catch {
                 /* The original timeout is the more useful error. */

package/dist/httpTrustProxy/httpTrustProxy.compilation.d.ts

@@ -23,10 +23,13 @@ export type TrustProxyPredicate = (value: string, index: number) => boolean;
  * - `"loopback"`, `"linklocal"`, `"uniquelocal"` / `"private"` — named ranges.
  * - an IP address, a CIDR range, a comma-separated list of either, or an array
  *   of the same.
+ * - a hop count `n`: trust the `n` hops nearest the server (the socket peer
+ *   is hop `0`), as Express/`proxy-addr` do. `0` trusts nothing.
  * - a custom predicate `(address, hopIndexFromPeer) => boolean`.
  *
- * Throws `TypeError` on a string that is none of the above rather than
- * returning a predicate that can never match.
+ * Throws `TypeError` on a string that is none of the above, or on a hop
+ * count that is not a non-negative integer, rather than returning a
+ * predicate that can never match.
  */
 export declare function compileTrustProxy(trustProxy: TrustProxy): TrustProxyPredicate;
 //# sourceMappingURL=httpTrustProxy.compilation.d.ts.map