@zudojs/http 0.1.0 → 1.0.0

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

@@ -6,14 +6,15 @@
  *
  * @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 { isIncomingMessage, isServerResponse, isNodeRequestResponsePair, configureServer, listen, closeServer, readNodeRequestBody, NodeRequestBodyTooLargeError, isResponseContextLike, } from "./httpNode.server.js";
 /* -------------------------------------------------------------------------- */
 /* Node HTTP Adapter                                                          */
 /* -------------------------------------------------------------------------- */
@@ -26,6 +27,9 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
     keepAliveTimeout;
     connectionTimeout;
     trustProxy;
+    maxConnections;
+    connectionsCheckingInterval;
+    shutdownGraceMs;
     events;
     server;
     ownsServer = false;
@@ -48,12 +52,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;
     }
@@ -114,6 +126,7 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
         const response = input.response;
         const context = this.createRequest(request);
         try {
+            await this.attachNodeBody(request, context);
             const result = await this.executeNodeHandler(context);
             const responseContext = this.normalizeResult(result);
             await this.writeNodeResponse(response, responseContext);
@@ -122,6 +135,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 +179,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);
@@ -164,31 +206,56 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
     }
     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 +263,25 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
             headersTimeout: this.headersTimeout,
             keepAliveTimeout: this.keepAliveTimeout,
             connectionTimeout: this.connectionTimeout,
+            maxConnections: this.maxConnections,
+        });
+        this.server.on("clientError", (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();
         });
         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 +289,18 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
             await super.stop();
             return;
         }
-        await closeServer(this.server);
+        await closeServer(this.server, { graceMs: this.shutdownGraceMs });
         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,23 @@
+/**
+ * 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;
+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

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

@@ -0,0 +1,166 @@
+/**
+ * Node.js HTTP request parsing helpers.
+ *
+ * @module httpAdapter/node/request
+ */
+import { HttpRequestContext, createRequestContext, } from "../../httpRequest/httpRequest.context.js";
+import { getClientIp, isTrustedProxy, } from "../../httpTrustProxy/httpTrustProxy.core.js";
+import { removePort, extractPort } from "./httpNode.server.js";
+/* -------------------------------------------------------------------------- */
+/* Proxy Trust                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Decides whether the *immediate peer* of this connection is a configured
+ * trusted proxy.
+ *
+ * Every `X-Forwarded-*` header is written by whoever opened the socket. Unless
+ * that peer is a proxy the operator has declared trustworthy, the headers are
+ * attacker-controlled and must be ignored entirely — checking only "is a
+ * trustProxy value configured?" lets any direct client spoof its own address,
+ * protocol and host.
+ */
+function isPeerTrusted(request, trustProxy) {
+    if (trustProxy === undefined || trustProxy === false) {
+        return false;
+    }
+    const peer = request.socket?.remoteAddress;
+    if (!peer) {
+        return false;
+    }
+    return isTrustedProxy(peer, trustProxy);
+}
+/* -------------------------------------------------------------------------- */
+/* Node Request Helpers                                                       */
+/* -------------------------------------------------------------------------- */
+export function getNodeRequestHeaders(request) {
+    const headers = {};
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (Array.isArray(value)) {
+            headers[name] = value.join(", ");
+        }
+        else if (value !== undefined) {
+            headers[name] = value;
+        }
+    }
+    return Object.freeze(headers);
+}
+export function getNodeRequestProtocol(request, options = {}) {
+    const trustProxy = options.trustProxy ?? false;
+    if (isPeerTrusted(request, trustProxy)) {
+        const forwardedProto = request.headers["x-forwarded-proto"];
+        if (typeof forwardedProto === "string") {
+            const proto = forwardedProto.split(",")[0]?.trim().toLowerCase();
+            if (proto === "http" || proto === "https") {
+                return proto;
+            }
+        }
+    }
+    return request.socket?.encrypted
+        ? "https"
+        : "http";
+}
+export function getNodeRequestHostname(request, options = {}) {
+    const trustProxy = options.trustProxy ?? false;
+    if (isPeerTrusted(request, trustProxy)) {
+        const forwardedHost = request.headers["x-forwarded-host"];
+        if (typeof forwardedHost === "string") {
+            const host = forwardedHost.split(",")[0]?.trim();
+            if (host) {
+                return removePort(host);
+            }
+        }
+    }
+    const hostHeader = request.headers.host;
+    if (typeof hostHeader === "string") {
+        return removePort(hostHeader);
+    }
+    return request.socket?.localAddress ?? "127.0.0.1";
+}
+export function getNodeRequestPort(request, options = {}) {
+    const trustProxy = options.trustProxy ?? false;
+    if (isPeerTrusted(request, trustProxy)) {
+        const forwardedHost = request.headers["x-forwarded-host"];
+        if (typeof forwardedHost === "string") {
+            const host = forwardedHost.split(",")[0]?.trim();
+            if (host) {
+                const port = extractPort(host);
+                if (port !== undefined) {
+                    return port;
+                }
+            }
+        }
+    }
+    const hostHeader = request.headers.host;
+    if (typeof hostHeader === "string") {
+        const port = extractPort(hostHeader);
+        if (port !== undefined) {
+            return port;
+        }
+    }
+    return request.socket?.localPort ?? 80;
+}
+/**
+ * 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 function getNodeRemoteAddress(request, options = {}) {
+    const trustProxy = options.trustProxy ?? false;
+    const peer = request.socket?.remoteAddress ?? undefined;
+    if (!isPeerTrusted(request, trustProxy)) {
+        return peer;
+    }
+    const proxyRequest = {
+        headers: request.headers,
+        socket: { remoteAddress: peer },
+    };
+    return getClientIp(proxyRequest, trustProxy) ?? peer;
+}
+export function parseNodeQuery(request) {
+    const url = request.url;
+    if (!url) {
+        return Object.freeze({});
+    }
+    const questionIndex = url.indexOf("?");
+    if (questionIndex === -1) {
+        return Object.freeze({});
+    }
+    const queryString = url.slice(questionIndex + 1);
+    if (!queryString) {
+        return Object.freeze({});
+    }
+    const params = {};
+    for (const pair of queryString.split("&")) {
+        const [key, value] = pair.split("=");
+        if (key) {
+            params[decodeURIComponent(key)] =
+                value !== undefined ? decodeURIComponent(value) : "";
+        }
+    }
+    return Object.freeze(params);
+}
+/* -------------------------------------------------------------------------- */
+/* Request Context                                                            */
+/* -------------------------------------------------------------------------- */
+export function createNodeRequestContext(request, options = {}) {
+    const headers = getNodeRequestHeaders(request);
+    const protocol = getNodeRequestProtocol(request, options);
+    const hostname = getNodeRequestHostname(request, options);
+    const port = getNodeRequestPort(request, options);
+    const remoteAddress = getNodeRemoteAddress(request, options);
+    const query = parseNodeQuery(request);
+    const url = request.url ?? "/";
+    return createRequestContext({
+        method: request.method?.toUpperCase() ?? "GET",
+        url,
+        protocol,
+        hostname,
+        port,
+        headers,
+        query,
+        remoteAddress,
+    });
+}
+//# sourceMappingURL=httpNode.request.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * Node.js HTTP response writer.
+ *
+ * @module httpAdapter/node/response
+ */
+import type { ServerResponse } from "node:http";
+import type { HttpResponseWriter } from "../../httpResponse/httpResponse.writer.js";
+export declare class NodeResponseWriter implements HttpResponseWriter {
+    private readonly response;
+    constructor(response: ServerResponse);
+    get headersSent(): boolean;
+    get writableEnded(): boolean;
+    get writable(): boolean;
+    writeHead(status: number, statusText?: string, headers?: Readonly<Record<string, string>>): void;
+    setHeader(name: string, value: string): void;
+    appendHeader(name: string, value: string): void;
+    removeHeader(name: string): void;
+    write(chunk: string | Uint8Array): boolean;
+    end(chunk?: string | Uint8Array): void;
+    /**
+     * Resolves once the socket has drained, or immediately if it already has.
+     */
+    waitForDrain(): Promise<void>;
+    flushHeaders(): void;
+    flush(): void;
+}
+//# sourceMappingURL=httpNode.response.d.ts.map

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

@@ -0,0 +1,93 @@
+/**
+ * Node.js HTTP response writer.
+ *
+ * @module httpAdapter/node/response
+ */
+/* -------------------------------------------------------------------------- */
+/* Node Response Writer                                                       */
+/* -------------------------------------------------------------------------- */
+export class NodeResponseWriter {
+    response;
+    constructor(response) {
+        this.response = response;
+    }
+    get headersSent() {
+        return this.response.headersSent;
+    }
+    get writableEnded() {
+        return this.response.writableEnded;
+    }
+    get writable() {
+        return this.response.writable;
+    }
+    writeHead(status, statusText, headers) {
+        if (headers) {
+            for (const [name, value] of Object.entries(headers)) {
+                this.setHeader(name, value);
+            }
+        }
+        if (statusText !== undefined && statusText !== "") {
+            this.response.writeHead(status, statusText);
+            return;
+        }
+        this.response.writeHead(status);
+    }
+    setHeader(name, value) {
+        this.response.setHeader(name, value);
+    }
+    appendHeader(name, value) {
+        const existing = this.response.getHeader(name);
+        if (existing === undefined) {
+            this.response.setHeader(name, value);
+            return;
+        }
+        if (Array.isArray(existing)) {
+            this.response.setHeader(name, [...existing.map(String), value]);
+            return;
+        }
+        this.response.setHeader(name, [String(existing), value]);
+    }
+    removeHeader(name) {
+        this.response.removeHeader(name);
+    }
+    write(chunk) {
+        return this.response.write(chunk);
+    }
+    end(chunk) {
+        if (chunk === undefined) {
+            this.response.end();
+            return;
+        }
+        this.response.end(chunk);
+    }
+    /**
+     * Resolves once the socket has drained, or immediately if it already has.
+     */
+    waitForDrain() {
+        if (this.response.writableEnded || this.response.destroyed) {
+            return Promise.resolve();
+        }
+        if (this.response.writableNeedDrain !== true) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const done = () => {
+                this.response.off("drain", done);
+                this.response.off("close", done);
+                this.response.off("error", done);
+                resolve();
+            };
+            this.response.once("drain", done);
+            this.response.once("close", done);
+            this.response.once("error", done);
+        });
+    }
+    flushHeaders() {
+        this.response.flushHeaders();
+    }
+    flush() {
+        const response = this.response;
+        response.flush?.();
+    }
+}
+//# sourceMappingURL=httpNode.response.js.map

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

@@ -15,9 +15,26 @@ export declare function configureServer(server: Server, options: {
     readonly headersTimeout?: number;
     readonly keepAliveTimeout?: number;
     readonly connectionTimeout?: number;
+    readonly maxConnections?: number;
 }): void;
 export declare function listen(server: Server, port: number, host: string): Promise<void>;
-export declare function closeServer(server: Server): Promise<void>;
+/**
+ * Closes a listening server.
+ *
+ * `server.close()` on its own stops accepting new connections but waits
+ * indefinitely for every existing socket to end, including idle keep-alive
+ * sockets that no request is using. Idle sockets are therefore closed
+ * immediately, and after `graceMs` any connection still in flight is closed
+ * too so shutdown cannot be held open by a client.
+ *
+ * @param server - The server to close.
+ * @param options - `graceMs` is how long in-flight requests are given before
+ *   their sockets are destroyed. `0` closes everything immediately;
+ *   `Infinity` waits forever (the old behaviour).
+ */
+export declare function closeServer(server: Server, options?: {
+    readonly graceMs?: number;
+}): Promise<void>;
 export declare function getHeader(request: IncomingMessage, name: string): string | undefined;
 export declare function removePort(host: string): string;
 export declare function extractPort(host: string): number | undefined;

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

@@ -38,6 +38,13 @@ export function configureServer(server, options) {
     if (options.connectionTimeout !== undefined) {
         server.timeout = validateTimeout(options.connectionTimeout, "connectionTimeout");
     }
+    if (options.maxConnections !== undefined) {
+        if (!Number.isInteger(options.maxConnections) ||
+            options.maxConnections < 1) {
+            throw new RangeError("maxConnections must be a positive integer.");
+        }
+        server.maxConnections = options.maxConnections;
+    }
 }
 /* -------------------------------------------------------------------------- */
 /* Listen / Close                                                             */
@@ -61,18 +68,45 @@ export function listen(server, port, host) {
         server.listen(port, host);
     });
 }
-export function closeServer(server) {
+/**
+ * Closes a listening server.
+ *
+ * `server.close()` on its own stops accepting new connections but waits
+ * indefinitely for every existing socket to end, including idle keep-alive
+ * sockets that no request is using. Idle sockets are therefore closed
+ * immediately, and after `graceMs` any connection still in flight is closed
+ * too so shutdown cannot be held open by a client.
+ *
+ * @param server - The server to close.
+ * @param options - `graceMs` is how long in-flight requests are given before
+ *   their sockets are destroyed. `0` closes everything immediately;
+ *   `Infinity` waits forever (the old behaviour).
+ */
+export function closeServer(server, options = {}) {
     if (!server.listening) {
         return Promise.resolve();
     }
+    const graceMs = options.graceMs ?? 10_000;
     return new Promise((resolve, reject) => {
+        let timer;
         server.close((error) => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
             if (error) {
                 reject(error);
                 return;
             }
             resolve();
         });
+        /* Idle keep-alive sockets are never going to end on their own. */
+        server.closeIdleConnections();
+        if (Number.isFinite(graceMs)) {
+            timer = setTimeout(() => {
+                server.closeAllConnections();
+            }, Math.max(0, graceMs));
+            timer.unref?.();
+        }
     });
 }
 /* -------------------------------------------------------------------------- */
@@ -150,7 +184,12 @@ export function readNodeRequestBody(request, maxBodySize = DEFAULT_MAX_BODY_SIZE
     if (declaredLength) {
         const length = Number(declaredLength);
         if (Number.isFinite(length) && length > limit) {
-            request.destroy();
+            /*
+             * Pause rather than destroy: the caller still needs a live socket to
+             * answer with 413. Destroying here makes the client see a dropped
+             * connection instead of the status.
+             */
+            request.pause();
             return Promise.reject(new NodeRequestBodyTooLargeError(limit, length));
         }
     }
@@ -176,7 +215,7 @@ export function readNodeRequestBody(request, maxBodySize = DEFAULT_MAX_BODY_SIZE
             const data = new Uint8Array(chunk);
             total += data.byteLength;
             if (total > limit) {
-                request.destroy();
+                request.pause();
                 fail(new NodeRequestBodyTooLargeError(limit, total));
                 return;
             }