@zudojs/http 0.1.0 → 1.1.0

package/dist/httpAdapter/httpAdapter.errorResponse.js

@@ -0,0 +1,120 @@
+/**
+ * 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";
+/* -------------------------------------------------------------------------- */
+/* 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                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * Locates the innermost error that carries an HTTP status.
+ *
+ * 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.
+ */
+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;
+    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;
+        }
+    }
+    if (isHttpStatus(candidate.statusCode)) {
+        return candidate;
+    }
+    return undefined;
+}
+function isHttpStatus(value) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= 400 &&
+        value <= 599);
+}
+/**
+ * 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.
+ * - 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/httpFetch.adapter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fetch adapter for HTTP.
+ *
+ * @module httpAdapter/httpFetch
+ */
+export type { FetchAdapterOptions, FetchRequestInput, FetchResponseWriter, FetchAdapterResult, } from "./fetch/httpFetch.type.js";
+export { FetchHttpResponseWriter } from "./fetch/httpFetch.responseWriter.js";
+export { createFetchRequestContext, createFetchRequest, } from "./fetch/httpFetch.requestContext.js";
+export { readFetchBody, readFetchBodyAsString, readFetchBodyAsJson, FetchRequestBodyTooLargeError, } from "./fetch/httpFetch.body.js";
+export { isRequest, isResponse, isFetchRequestInput, } from "./fetch/httpFetch.helper.js";
+//# sourceMappingURL=httpFetch.adapter.d.ts.map

package/dist/httpAdapter/httpFetch.adapter.js

@@ -0,0 +1,10 @@
+/**
+ * Fetch adapter for HTTP.
+ *
+ * @module httpAdapter/httpFetch
+ */
+export { FetchHttpResponseWriter } from "./fetch/httpFetch.responseWriter.js";
+export { createFetchRequestContext, createFetchRequest, } from "./fetch/httpFetch.requestContext.js";
+export { readFetchBody, readFetchBodyAsString, readFetchBodyAsJson, FetchRequestBodyTooLargeError, } from "./fetch/httpFetch.body.js";
+export { isRequest, isResponse, isFetchRequestInput, } from "./fetch/httpFetch.helper.js";
+//# sourceMappingURL=httpFetch.adapter.js.map

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

@@ -21,9 +21,19 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     private readonly keepAliveTimeout;
     private readonly connectionTimeout;
     private readonly trustProxy;
+    private readonly maxConnections;
+    private readonly connectionsCheckingInterval;
+    private readonly shutdownGraceMs;
     private readonly events;
     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;
@@ -31,10 +41,29 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     createResponse(input?: unknown): HttpResponseContext;
     createWriter(response: unknown): HttpResponseWriter;
     handle(input: unknown): Promise<void>;
+    /**
+     * Reads the request body (subject to `maxBodySize`) and attaches it to the
+     * context.
+     *
+     * Without this the adapter hands handlers a context with no body at all, and
+     * the configured `maxBodySize` limit is never applied to anything.
+     */
+    private attachNodeBody;
     private executeNodeHandler;
     private normalizeResult;
     private handleNodeError;
+    private writeBadRequest;
     private writeNodeResponse;
+    /**
+     * Runs `handle` for a Node request/response pair without ever letting the
+     * resulting promise reject.
+     *
+     * `createServer`'s callback is synchronous, so a rejection from `handle`
+     * would otherwise escape as an unhandled rejection and terminate the
+     * process under Node's default `--unhandled-rejections=throw`.
+     */
+    private dispatchNodeRequest;
+    private emitAdapterError;
     start(): Promise<void>;
     stop(): Promise<void>;
 }

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

@@ -6,14 +6,16 @@
  *
  * @module httpAdapter/node/adapter
  */
-import { Server, ServerResponse, createServer } from "node:http";
+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 { DEFAULT_HOST, DEFAULT_PORT, DEFAULT_MAX_BODY_SIZE, validatePort, validateMaxBodySize, } from "./httpNode.type.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 { getNodeRequestHeaders, getNodeRequestProtocol, getNodeRequestHostname, getNodeRequestPort, getNodeRemoteAddress, parseNodeQuery, createNodeRequestContext, } from "./httpNode.request.js";
-import { isIncomingMessage, isServerResponse, isNodeRequestResponsePair, configureServer, listen, closeServer, isResponseContextLike, } from "./httpNode.server.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";
 /* -------------------------------------------------------------------------- */
 /* Node HTTP Adapter                                                          */
 /* -------------------------------------------------------------------------- */
@@ -26,9 +28,19 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
     keepAliveTimeout;
     connectionTimeout;
     trustProxy;
+    maxConnections;
+    connectionsCheckingInterval;
+    shutdownGraceMs;
     events;
     server;
     ownsServer = false;
+    /**
+     * 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.
+     */
+    clientErrorListener;
     constructor(options = {}) {
         super({
             ...options,
@@ -48,12 +60,20 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
         this.host = options.host ?? DEFAULT_HOST;
         this.port = validatePort(options.port ?? DEFAULT_PORT);
         this.maxBodySize = validateMaxBodySize(options.maxBodySize ?? DEFAULT_MAX_BODY_SIZE);
-        this.requestTimeout = options.requestTimeout;
-        this.headersTimeout = options.headersTimeout;
-        this.keepAliveTimeout = options.keepAliveTimeout;
+        this.requestTimeout =
+            options.requestTimeout ?? NODE_DEFAULT_REQUEST_TIMEOUT;
+        this.headersTimeout =
+            options.headersTimeout ?? NODE_DEFAULT_HEADERS_TIMEOUT;
+        this.keepAliveTimeout =
+            options.keepAliveTimeout ?? NODE_DEFAULT_KEEP_ALIVE_TIMEOUT;
         this.connectionTimeout = options.connectionTimeout;
+        this.maxConnections = options.maxConnections;
+        this.connectionsCheckingInterval =
+            options.connectionsCheckingInterval ??
+                Math.min(30_000, this.headersTimeout);
+        this.shutdownGraceMs = options.shutdownGraceMs;
         this.trustProxy = options.trustProxy;
-        this.events = {};
+        this.events = options.events ?? {};
         this.server = options.server;
         this.ownsServer = !options.server;
     }
@@ -112,8 +132,23 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
         }
         const request = input.request;
         const response = input.response;
-        const context = this.createRequest(request);
+        let context;
         try {
+            context = this.createRequest(request);
+        }
+        catch (error) {
+            /*
+             * The request could not even be described (an unparseable request
+             * target, a header the context refuses). It is the client's fault, so
+             * answer 400 rather than letting the rejection destroy the socket
+             * without a response.
+             */
+            this.emitAdapterError(error);
+            await this.writeBadRequest(response);
+            return;
+        }
+        try {
+            await this.attachNodeBody(request, context);
             const result = await this.executeNodeHandler(context);
             const responseContext = this.normalizeResult(result);
             await this.writeNodeResponse(response, responseContext);
@@ -122,6 +157,26 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
             await this.handleNodeError(error, context, response);
         }
     }
+    /**
+     * Reads the request body (subject to `maxBodySize`) and attaches it to the
+     * context.
+     *
+     * Without this the adapter hands handlers a context with no body at all, and
+     * the configured `maxBodySize` limit is never applied to anything.
+     */
+    async attachNodeBody(request, context) {
+        const method = (request.method ?? "GET").toUpperCase();
+        if (method === "GET" || method === "HEAD") {
+            return;
+        }
+        const hasLength = request.headers["content-length"] !== undefined;
+        const hasEncoding = request.headers["transfer-encoding"] !== undefined;
+        if (!hasLength && !hasEncoding) {
+            return;
+        }
+        const body = await readNodeRequestBody(request, this.maxBodySize);
+        context.setBody(body);
+    }
     async executeNodeHandler(request) {
         if (!this.handler) {
             throw new Error("No HTTP handler has been configured.");
@@ -146,6 +201,15 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
             return;
         }
         const context = createResponseContext();
+        if (error instanceof NodeRequestBodyTooLargeError) {
+            /*
+             * The request body was never drained, so this connection cannot be
+             * safely reused for a following request.
+             */
+            context.setHeader("connection", "close");
+            await this.writeNodeResponse(response, context.setStatus(413).json({ error: "Payload Too Large" }));
+            return;
+        }
         if (this.errorHandler) {
             try {
                 const result = await this.errorHandler(error, request);
@@ -157,38 +221,79 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
                 // Fall through to the safe internal server error response.
             }
         }
-        context.internalServerError().json({
-            error: "Internal Server Error",
-        });
+        /*
+         * A thrown `HttpError` (or one buried under the middleware pipeline's
+         * wrappers) is answered with its own status, exposed message and headers;
+         * anything else stays a generic 500.
+         */
+        const resolved = resolveErrorResponse(error);
+        for (const [name, value] of Object.entries(resolved.headers)) {
+            context.setHeader(name, value);
+        }
+        context.setStatus(resolved.status).json(resolved.body);
         await this.writeNodeResponse(response, context);
     }
+    async writeBadRequest(response) {
+        if (response.headersSent) {
+            response.destroy();
+            return;
+        }
+        const context = createResponseContext();
+        context.setHeader("connection", "close");
+        await this.writeNodeResponse(response, context.setStatus(400).json({ error: "Bad Request" }));
+    }
     async writeNodeResponse(response, context) {
         const writer = this.createWriter(response);
-        await this.writeNodeResponse(response, context);
+        await writeResponse(context, writer);
         if (!response.writableEnded) {
             writer.end();
         }
     }
+    /**
+     * Runs `handle` for a Node request/response pair without ever letting the
+     * resulting promise reject.
+     *
+     * `createServer`'s callback is synchronous, so a rejection from `handle`
+     * would otherwise escape as an unhandled rejection and terminate the
+     * process under Node's default `--unhandled-rejections=throw`.
+     */
+    dispatchNodeRequest(request, response) {
+        this.handle({ request, response }).catch((error) => {
+            this.emitAdapterError(error);
+            if (!response.writableEnded) {
+                response.destroy(error instanceof Error ? error : undefined);
+            }
+        });
+    }
+    emitAdapterError(error) {
+        const listener = this.events.onError;
+        if (typeof listener !== "function") {
+            return;
+        }
+        try {
+            listener(error instanceof Error ? error : new Error(String(error)));
+        }
+        catch {
+            /*
+             * A failing error listener must not itself escape and re-trigger the
+             * unhandled-rejection path this method exists to close.
+             */
+        }
+    }
     async start() {
         if (this.server?.listening) {
             return;
         }
         if (!this.server) {
-            this.server = createServer((request, response) => {
-                void this.handle({
-                    request,
-                    response,
-                });
+            this.server = createServer({ connectionsCheckingInterval: this.connectionsCheckingInterval }, (request, response) => {
+                this.dispatchNodeRequest(request, response);
             });
             this.ownsServer = true;
         }
         else {
             this.server.removeAllListeners("request");
             this.server.on("request", (request, response) => {
-                void this.handle({
-                    request,
-                    response,
-                });
+                this.dispatchNodeRequest(request, response);
             });
         }
         configureServer(this.server, {
@@ -196,8 +301,29 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
             headersTimeout: this.headersTimeout,
             keepAliveTimeout: this.keepAliveTimeout,
             connectionTimeout: this.connectionTimeout,
+            maxConnections: this.maxConnections,
         });
+        if (this.clientErrorListener) {
+            this.server.off("clientError", this.clientErrorListener);
+        }
+        this.clientErrorListener = (error, socket) => {
+            this.emitAdapterError(error);
+            if (socket.writable) {
+                socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+            }
+            socket.destroy();
+        };
+        this.server.on("clientError", this.clientErrorListener);
         await listen(this.server, this.port, this.host);
+        const address = this.address;
+        if (address && this.events.onListening) {
+            try {
+                this.events.onListening(address);
+            }
+            catch {
+                /* A listener failure must not abort a successful start. */
+            }
+        }
         await super.start();
     }
     async stop() {
@@ -205,10 +331,22 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
             await super.stop();
             return;
         }
-        await closeServer(this.server);
+        await closeServer(this.server, { graceMs: this.shutdownGraceMs });
+        if (this.clientErrorListener) {
+            this.server.off("clientError", this.clientErrorListener);
+            this.clientErrorListener = undefined;
+        }
         if (this.ownsServer) {
             this.server = undefined;
         }
+        if (this.events.onClose) {
+            try {
+                this.events.onClose();
+            }
+            catch {
+                /* A listener failure must not turn a clean stop into a failure. */
+            }
+        }
         await super.stop();
     }
 }

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

@@ -0,0 +1,33 @@
+/**
+ * Node.js HTTP request parsing helpers.
+ *
+ * @module httpAdapter/node/request
+ */
+import type { IncomingMessage } from "node:http";
+import { HttpRequestContext } from "../../httpRequest/httpRequest.context.js";
+import type { NodeRequestOptions } from "./httpNode.type.js";
+export declare function getNodeRequestHeaders(request: IncomingMessage): Readonly<Record<string, string>>;
+export declare function getNodeRequestProtocol(request: IncomingMessage, options?: NodeRequestOptions): string;
+export declare function getNodeRequestHostname(request: IncomingMessage, options?: NodeRequestOptions): string;
+export declare function getNodeRequestPort(request: IncomingMessage, options?: NodeRequestOptions): number;
+/**
+ * Resolves the client address for a Node request.
+ *
+ * The socket peer is authoritative. Forwarded headers are consulted only when
+ * that peer is itself a trusted proxy, and the chain walk is delegated to
+ * `getClientIp` so there is a single implementation of the hop logic.
+ */
+export declare function getNodeRemoteAddress(request: IncomingMessage, options?: NodeRequestOptions): string | undefined;
+/**
+ * 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`.
+ */
+export declare function parseNodeQuery(request: IncomingMessage): Readonly<Record<string, string>>;
+export declare function createNodeRequestContext(request: IncomingMessage, options?: NodeRequestOptions): HttpRequestContext;
+//# sourceMappingURL=httpNode.request.d.ts.map