@zudojs/http 0.1.0 → 1.1.0

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

@@ -0,0 +1,183 @@
+/**
+ * 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";
+import { decodeQueryComponent } from "../../httpQuery/http.query.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;
+}
+/**
+ * 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 function parseNodeQuery(request) {
+    const url = request.url;
+    if (!url) {
+        return Object.freeze({});
+    }
+    const questionIndex = url.indexOf("?");
+    if (questionIndex === -1) {
+        return Object.freeze({});
+    }
+    const hashIndex = url.indexOf("#", questionIndex + 1);
+    const queryString = url.slice(questionIndex + 1, hashIndex === -1 ? undefined : hashIndex);
+    if (!queryString) {
+        return Object.freeze({});
+    }
+    const params = {};
+    for (const pair of queryString.split("&")) {
+        if (pair === "") {
+            continue;
+        }
+        const separator = pair.indexOf("=");
+        const rawKey = separator === -1 ? pair : pair.slice(0, separator);
+        const rawValue = separator === -1 ? "" : pair.slice(separator + 1);
+        const key = decodeQueryComponent(rawKey);
+        if (key) {
+            params[key] = decodeQueryComponent(rawValue);
+        }
+    }
+    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;
             }

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

@@ -0,0 +1,84 @@
+/**
+ * Node.js HTTP adapter types and validation.
+ *
+ * @module httpAdapter/node/types
+ */
+import type { Server } from "node:http";
+import type { HttpAdapterOptions } from "../http.adapter.js";
+import type { TrustProxy } from "../../httpTrustProxy/httpTrustProxy.core.js";
+export interface NodeAdapterOptions extends HttpAdapterOptions {
+    readonly host?: string;
+    readonly port?: number;
+    readonly server?: Server;
+    readonly maxBodySize?: number;
+    readonly trustProxy?: boolean | number | string | readonly string[];
+    readonly requestTimeout?: number;
+    readonly headersTimeout?: number;
+    readonly keepAliveTimeout?: number;
+    readonly connectionTimeout?: number;
+    /**
+     * Maximum number of concurrent connections the server will accept.
+     */
+    readonly maxConnections?: number;
+    /**
+     * How often, in milliseconds, Node sweeps connections for expired
+     * header/request timeouts. Node's default is 30000, which means a
+     * configured `headersTimeout` can overshoot by up to 30 seconds; the
+     * adapter tightens it to the headers timeout unless overridden.
+     */
+    readonly connectionsCheckingInterval?: number;
+    /**
+     * Grace period, in milliseconds, granted to in-flight requests during
+     * `stop()` before their sockets are destroyed. Defaults to 10000.
+     */
+    readonly shutdownGraceMs?: number;
+    /**
+     * Lifecycle listeners invoked by the adapter.
+     */
+    readonly events?: NodeAdapterEvents;
+}
+/**
+ * Options for creating a Node.js request context.
+ */
+export interface NodeRequestOptions {
+    /**
+     * Maximum body size in bytes.
+     */
+    readonly maxBodySize?: number;
+    /**
+     * Trust proxy configuration for X-Forwarded-* headers.
+     * - false: Never trust (default, most secure)
+     * - true: Trust all (only for direct connections)
+     * - number: Trust N proxies from the right
+     * - string[]: Trust specific IP addresses
+     */
+    readonly trustProxy?: TrustProxy;
+}
+export interface NodeServerAddress {
+    readonly host: string;
+    readonly port: number;
+    readonly family: string;
+}
+export interface NodeAdapterEvents {
+    readonly onError?: (error: Error) => void;
+    readonly onListening?: (address: NodeServerAddress) => void;
+    readonly onClose?: () => void;
+}
+export declare const DEFAULT_HOST = "127.0.0.1";
+export declare const DEFAULT_PORT = 3000;
+/**
+ * Default slowloris-resistant timeouts.
+ *
+ * Node's own defaults (300s request, 60s headers) are long enough that a
+ * handful of connections dribbling a request line can hold server resources
+ * for minutes, so the adapter tightens them unless the operator opts out by
+ * configuring an explicit value.
+ */
+export declare const NODE_DEFAULT_HEADERS_TIMEOUT = 10000;
+export declare const NODE_DEFAULT_REQUEST_TIMEOUT = 30000;
+export declare const NODE_DEFAULT_KEEP_ALIVE_TIMEOUT = 5000;
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+export declare function validatePort(port: number): number;
+export declare function validateMaxBodySize(size: number): number;
+export declare function validateTimeout(value: number, name: string): number;
+//# sourceMappingURL=httpNode.type.d.ts.map

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

@@ -0,0 +1,44 @@
+/**
+ * Node.js HTTP adapter types and validation.
+ *
+ * @module httpAdapter/node/types
+ */
+/* -------------------------------------------------------------------------- */
+/* Constants                                                                  */
+/* -------------------------------------------------------------------------- */
+export const DEFAULT_HOST = "127.0.0.1";
+export const DEFAULT_PORT = 3000;
+/**
+ * Default slowloris-resistant timeouts.
+ *
+ * Node's own defaults (300s request, 60s headers) are long enough that a
+ * handful of connections dribbling a request line can hold server resources
+ * for minutes, so the adapter tightens them unless the operator opts out by
+ * configuring an explicit value.
+ */
+export const NODE_DEFAULT_HEADERS_TIMEOUT = 10_000;
+export const NODE_DEFAULT_REQUEST_TIMEOUT = 30_000;
+export const NODE_DEFAULT_KEEP_ALIVE_TIMEOUT = 5_000;
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
+/* -------------------------------------------------------------------------- */
+/* Validation                                                                 */
+/* -------------------------------------------------------------------------- */
+export function validatePort(port) {
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new RangeError("HTTP server port must be an integer between 0 and 65535.");
+    }
+    return port;
+}
+export function validateMaxBodySize(size) {
+    if (!Number.isSafeInteger(size) || size < 0) {
+        throw new RangeError("Maximum request body size must be a non-negative safe integer.");
+    }
+    return size;
+}
+export function validateTimeout(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative finite number.`);
+    }
+    return value;
+}
+//# sourceMappingURL=httpNode.type.js.map

package/dist/httpAgent/http.agent.d.ts

@@ -0,0 +1,63 @@
+import { Agent as HTTPAgent } from "node:http";
+import { Agent as HTTPSAgent } from "node:https";
+export type HTTPAgentProtocol = "http" | "https";
+export interface HTTPAgentOptionsBase {
+    readonly keepAlive?: boolean;
+    readonly keepAliveMsecs?: number;
+    readonly maxSockets?: number;
+    readonly maxFreeSockets?: number;
+    readonly maxTotalSockets?: number;
+    readonly scheduling?: "fifo" | "lifo";
+    readonly timeout?: number;
+}
+export interface HTTPAgentConfig extends HTTPAgentOptionsBase {
+    readonly protocol?: HTTPAgentProtocol;
+}
+export interface HTTPSAgentConfig extends HTTPAgentOptionsBase {
+    readonly protocol?: "https";
+    readonly rejectUnauthorized?: boolean;
+    readonly ca?: string | Buffer | readonly (string | Buffer)[];
+    readonly cert?: string | Buffer;
+    readonly key?: string | Buffer;
+    readonly servername?: string;
+}
+export type HTTPAgentInstance = HTTPAgent | HTTPSAgent;
+export declare const DEFAULT_AGENT_KEEP_ALIVE = true;
+export declare const DEFAULT_AGENT_KEEP_ALIVE_MSECS = 1000;
+export declare const DEFAULT_AGENT_MAX_SOCKETS = 50;
+export declare const DEFAULT_AGENT_MAX_FREE_SOCKETS = 10;
+export declare const DEFAULT_AGENT_MAX_TOTAL_SOCKETS = 100;
+export declare const DEFAULT_AGENT_SCHEDULING: "fifo" | "lifo";
+export declare function createHTTPAgent(options?: HTTPAgentConfig): HTTPAgent;
+export declare function createHTTPSAgent(options?: HTTPSAgentConfig): HTTPSAgent;
+export declare function createAgent(options?: HTTPAgentConfig | HTTPSAgentConfig): HTTPAgentInstance;
+export interface AgentStats {
+    readonly sockets: number;
+    readonly freeSockets: number;
+    readonly requests: number;
+    readonly totalSockets: number;
+}
+export declare function getAgentStats(agent: HTTPAgentInstance): AgentStats;
+export declare function destroyAgent(agent: HTTPAgentInstance): void;
+export declare function closeAgent(agent: HTTPAgentInstance): void;
+export declare function configureAgentTimeout(agent: HTTPAgentInstance, timeout: number): void;
+export interface AgentRegistryKey {
+    readonly protocol: HTTPAgentProtocol;
+    readonly name?: string;
+}
+export declare function getOrCreateAgent(key: string | AgentRegistryKey, options?: HTTPAgentConfig | HTTPSAgentConfig): HTTPAgentInstance;
+export declare function getAgent(key: string | AgentRegistryKey): HTTPAgentInstance | undefined;
+export declare function hasAgent(key: string | AgentRegistryKey): boolean;
+export declare function removeAgent(key: string | AgentRegistryKey, destroy?: boolean): boolean;
+export declare function clearAgents(destroy?: boolean): void;
+export declare function getRegisteredAgentKeys(): string[];
+export declare function getDefaultHTTPAgent(): HTTPAgent;
+export declare function getDefaultHTTPSAgent(): HTTPSAgent;
+export declare function setDefaultHTTPAgent(agent: HTTPAgent): void;
+export declare function setDefaultHTTPSAgent(agent: HTTPSAgent): void;
+export declare function resetDefaultAgents(): void;
+export declare function getAgentForProtocol(protocol: string | undefined): HTTPAgentInstance;
+export declare function isHTTPAgent(agent: HTTPAgentInstance): agent is HTTPAgent;
+export declare function isHTTPSAgent(agent: HTTPAgentInstance): agent is HTTPSAgent;
+export declare function validateAgentOptions(options: HTTPAgentOptionsBase): void;
+//# sourceMappingURL=http.agent.d.ts.map