@zudojs/http 0.0.6 → 1.0.0

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

package/dist/httpAgent/http.agent.js

@@ -0,0 +1,297 @@
+import { Agent as HTTPAgent, } from "node:http";
+import { Agent as HTTPSAgent, } from "node:https";
+import { createHash } from "node:crypto";
+/* -------------------------------------------------------------------------- */
+/* Defaults                                                                   */
+/* -------------------------------------------------------------------------- */
+export const DEFAULT_AGENT_KEEP_ALIVE = true;
+export const DEFAULT_AGENT_KEEP_ALIVE_MSECS = 1_000;
+export const DEFAULT_AGENT_MAX_SOCKETS = 50;
+export const DEFAULT_AGENT_MAX_FREE_SOCKETS = 10;
+export const DEFAULT_AGENT_MAX_TOTAL_SOCKETS = 100;
+export const DEFAULT_AGENT_SCHEDULING = "lifo";
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+export function createHTTPAgent(options = {}) {
+    validateAgentOptions(options);
+    const agentOptions = normalizeAgentOptions(options);
+    return new HTTPAgent(agentOptions);
+}
+export function createHTTPSAgent(options = {}) {
+    validateAgentOptions(options);
+    const agentOptions = normalizeHTTPSAgentOptions(options);
+    return new HTTPSAgent(agentOptions);
+}
+export function createAgent(options = {}) {
+    const protocol = options.protocol ?? "http";
+    if (protocol === "https") {
+        return createHTTPSAgent(options);
+    }
+    return createHTTPAgent(options);
+}
+/* -------------------------------------------------------------------------- */
+/* Normalization                                                              */
+/* -------------------------------------------------------------------------- */
+function normalizeAgentOptions(options) {
+    return {
+        keepAlive: options.keepAlive ?? DEFAULT_AGENT_KEEP_ALIVE,
+        keepAliveMsecs: options.keepAliveMsecs ?? DEFAULT_AGENT_KEEP_ALIVE_MSECS,
+        maxSockets: options.maxSockets ?? DEFAULT_AGENT_MAX_SOCKETS,
+        maxFreeSockets: options.maxFreeSockets ?? DEFAULT_AGENT_MAX_FREE_SOCKETS,
+        maxTotalSockets: options.maxTotalSockets ?? DEFAULT_AGENT_MAX_TOTAL_SOCKETS,
+        scheduling: options.scheduling ?? DEFAULT_AGENT_SCHEDULING,
+        timeout: options.timeout,
+    };
+}
+function normalizeHTTPSAgentOptions(options) {
+    return {
+        keepAlive: options.keepAlive ?? DEFAULT_AGENT_KEEP_ALIVE,
+        keepAliveMsecs: options.keepAliveMsecs ?? DEFAULT_AGENT_KEEP_ALIVE_MSECS,
+        maxSockets: options.maxSockets ?? DEFAULT_AGENT_MAX_SOCKETS,
+        maxFreeSockets: options.maxFreeSockets ?? DEFAULT_AGENT_MAX_FREE_SOCKETS,
+        maxTotalSockets: options.maxTotalSockets ?? DEFAULT_AGENT_MAX_TOTAL_SOCKETS,
+        scheduling: options.scheduling ?? DEFAULT_AGENT_SCHEDULING,
+        timeout: options.timeout,
+        rejectUnauthorized: options.rejectUnauthorized,
+        ca: options.ca,
+        cert: options.cert,
+        key: options.key,
+        servername: options.servername,
+    };
+}
+export function getAgentStats(agent) {
+    return {
+        sockets: countAgentEntries(agent.sockets),
+        freeSockets: countAgentEntries(agent.freeSockets),
+        requests: countAgentEntries(agent.requests),
+        totalSockets: countAgentEntries(agent.sockets) + countAgentEntries(agent.freeSockets),
+    };
+}
+function countAgentEntries(entries) {
+    let total = 0;
+    for (const value of Object.values(entries)) {
+        if (Array.isArray(value)) {
+            total += value.length;
+        }
+        else {
+            total += 1;
+        }
+    }
+    return total;
+}
+/* -------------------------------------------------------------------------- */
+/* Agent Lifecycle                                                            */
+/* -------------------------------------------------------------------------- */
+export function destroyAgent(agent) {
+    agent.destroy();
+}
+export function closeAgent(agent) {
+    agent.destroy();
+}
+/* -------------------------------------------------------------------------- */
+/* Socket Configuration                                                       */
+/* -------------------------------------------------------------------------- */
+export function configureAgentTimeout(agent, timeout) {
+    if (!Number.isFinite(timeout) || timeout < 0) {
+        throw new RangeError("Agent timeout must be a non-negative finite number.");
+    }
+    if ("options" in agent) {
+        agent.options.timeout = timeout;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Shared Agent Registry                                                      */
+/* -------------------------------------------------------------------------- */
+const agentRegistry = new Map();
+export function getOrCreateAgent(key, options = {}) {
+    const registryKey = normalizeRegistryKey(key);
+    /*
+     * The key includes the TLS-relevant options. Keying on protocol+host alone
+     * meant the first caller's `ca`/`cert`/`servername`/`rejectUnauthorized`
+     * silently applied to every later caller for that host: a staging call
+     * passing `rejectUnauthorized: false` would have disabled certificate
+     * verification for a caller that had pinned a CA, with no way to detect it.
+     */
+    const cacheKey = `${registryKey}|${tlsFingerprint(options)}`;
+    const existing = agentRegistry.get(cacheKey);
+    if (existing) {
+        return existing;
+    }
+    const agent = createAgent({
+        ...options,
+        protocol: registryKey.startsWith("https:")
+            ? "https"
+            : (options.protocol ?? "http"),
+    });
+    agentRegistry.set(cacheKey, agent);
+    return agent;
+}
+/**
+ * Builds a stable fingerprint of the TLS-relevant fields of an agent config.
+ */
+function tlsFingerprint(options) {
+    const tls = options;
+    const parts = [
+        describeCredential(tls.ca),
+        describeCredential(tls.cert),
+        describeCredential(tls.key),
+        tls.servername ?? "",
+        tls.rejectUnauthorized === undefined ? "" : String(tls.rejectUnauthorized),
+    ];
+    return parts.join("|");
+}
+function describeCredential(value) {
+    if (value === undefined || value === null) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return createHash("sha256").update(value).digest("hex");
+    }
+    if (value instanceof Uint8Array) {
+        return createHash("sha256").update(value).digest("hex");
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => describeCredential(entry)).join(",");
+    }
+    return "opaque";
+}
+export function getAgent(key) {
+    return agentRegistry.get(normalizeRegistryKey(key));
+}
+export function hasAgent(key) {
+    return agentRegistry.has(normalizeRegistryKey(key));
+}
+export function removeAgent(key, destroy = true) {
+    const registryKey = normalizeRegistryKey(key);
+    const agent = agentRegistry.get(registryKey);
+    if (!agent) {
+        return false;
+    }
+    agentRegistry.delete(registryKey);
+    if (destroy) {
+        agent.destroy();
+    }
+    return true;
+}
+export function clearAgents(destroy = true) {
+    if (destroy) {
+        for (const agent of agentRegistry.values()) {
+            agent.destroy();
+        }
+    }
+    agentRegistry.clear();
+}
+export function getRegisteredAgentKeys() {
+    return Array.from(agentRegistry.keys());
+}
+/* -------------------------------------------------------------------------- */
+/* Registry Helpers                                                           */
+/* -------------------------------------------------------------------------- */
+function normalizeRegistryKey(key) {
+    if (typeof key === "string") {
+        return normalizeURLKey(key);
+    }
+    const protocol = key.protocol === "https" ? "https:" : "http:";
+    return key.name ? `${protocol}//${key.name}` : protocol;
+}
+function normalizeURLKey(value) {
+    try {
+        const url = new URL(value.includes("://") ? value : `http://${value}`);
+        return `${url.protocol}//${url.host}`;
+    }
+    catch {
+        return value.trim();
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Global Defaults                                                            */
+/* -------------------------------------------------------------------------- */
+let defaultHTTPAgent;
+let defaultHTTPSAgent;
+export function getDefaultHTTPAgent() {
+    if (!defaultHTTPAgent) {
+        defaultHTTPAgent = createHTTPAgent();
+    }
+    return defaultHTTPAgent;
+}
+export function getDefaultHTTPSAgent() {
+    if (!defaultHTTPSAgent) {
+        defaultHTTPSAgent = createHTTPSAgent();
+    }
+    return defaultHTTPSAgent;
+}
+export function setDefaultHTTPAgent(agent) {
+    if (defaultHTTPAgent && defaultHTTPAgent !== agent) {
+        defaultHTTPAgent.destroy();
+    }
+    defaultHTTPAgent = agent;
+}
+export function setDefaultHTTPSAgent(agent) {
+    if (defaultHTTPSAgent && defaultHTTPSAgent !== agent) {
+        defaultHTTPSAgent.destroy();
+    }
+    defaultHTTPSAgent = agent;
+}
+export function resetDefaultAgents() {
+    defaultHTTPAgent?.destroy();
+    defaultHTTPSAgent?.destroy();
+    defaultHTTPAgent = undefined;
+    defaultHTTPSAgent = undefined;
+}
+/* -------------------------------------------------------------------------- */
+/* Agent Selection                                                            */
+/* -------------------------------------------------------------------------- */
+export function getAgentForProtocol(protocol) {
+    const normalized = protocol?.toLowerCase();
+    if (normalized === "https:" || normalized === "https") {
+        return getDefaultHTTPSAgent();
+    }
+    return getDefaultHTTPAgent();
+}
+export function isHTTPAgent(agent) {
+    return agent instanceof HTTPAgent;
+}
+export function isHTTPSAgent(agent) {
+    return agent instanceof HTTPSAgent;
+}
+/* -------------------------------------------------------------------------- */
+/* Validation                                                                 */
+/* -------------------------------------------------------------------------- */
+export function validateAgentOptions(options) {
+    validateNonNegativeInteger(options.keepAliveMsecs, "keepAliveMsecs");
+    validatePositiveInteger(options.maxSockets, "maxSockets");
+    validatePositiveInteger(options.maxFreeSockets, "maxFreeSockets");
+    validatePositiveInteger(options.maxTotalSockets, "maxTotalSockets");
+    if (options.maxFreeSockets !== undefined &&
+        options.maxSockets !== undefined &&
+        options.maxFreeSockets > options.maxSockets) {
+        throw new RangeError("maxFreeSockets cannot exceed maxSockets.");
+    }
+    if (options.maxTotalSockets !== undefined &&
+        options.maxSockets !== undefined &&
+        options.maxTotalSockets < options.maxSockets) {
+        throw new RangeError("maxTotalSockets cannot be less than maxSockets.");
+    }
+    if (options.timeout !== undefined &&
+        (!Number.isFinite(options.timeout) || options.timeout < 0)) {
+        throw new RangeError("timeout must be a non-negative finite number.");
+    }
+}
+function validateNonNegativeInteger(value, name) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative safe integer.`);
+    }
+}
+function validatePositiveInteger(value, name) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer.`);
+    }
+}
+//# sourceMappingURL=http.agent.js.map

package/dist/httpBody/http.body.d.ts

@@ -3,12 +3,24 @@ export type HTTPBody = string | Buffer | Uint8Array | Record<string, unknown> |
 export interface HTTPBodyParseOptions {
     readonly limit?: number;
     readonly encoding?: BufferEncoding;
+    /**
+     * Enforce strict JSON body rules in {@link readJSON}: an empty body and a
+     * scalar top-level value (`5`, `null`, `"x"`) are rejected instead of being
+     * accepted as a body. Read only by {@link readJSON}; it has no meaning for
+     * the text, form or raw readers.
+     */
     readonly strict?: boolean;
 }
 export interface HTTPBodyReaderOptions extends HTTPBodyParseOptions {
     readonly request: IncomingMessage;
 }
-export declare const DEFAULT_BODY_LIMIT = 1048576;
+/**
+ * The package-wide default body limit.
+ *
+ * Aliases `HTTP_DEFAULTS.BODY_LIMIT` rather than repeating the literal, so
+ * the two cannot drift apart.
+ */
+export declare const DEFAULT_BODY_LIMIT: number;
 export declare const DEFAULT_BODY_ENCODING: BufferEncoding;
 export declare const BODY_CONTENT_TYPES: {
     readonly JSON: "application/json";
@@ -20,7 +32,14 @@ export declare const BODY_CONTENT_TYPES: {
 };
 export declare function readBody(options: HTTPBodyReaderOptions): Promise<Buffer>;
 export declare function readText(options: HTTPBodyReaderOptions): Promise<string>;
-export declare function readJSON<T = unknown>(options?: HTTPBodyReaderOptions): Promise<T>;
+/**
+ * Reads and parses a JSON request body.
+ *
+ * With `strict: true` an empty body is rejected and the top-level value must
+ * be an object or an array — a bare scalar such as `5`, `null` or `"x"` is
+ * not accepted as a request body.
+ */
+export declare function readJSON<T = unknown>(options: HTTPBodyReaderOptions): Promise<T>;
 export declare function readForm(options: HTTPBodyReaderOptions): Promise<Record<string, string | string[]>>;
 export declare function parseBody<T = unknown>(options: HTTPBodyReaderOptions): Promise<T | Buffer | string>;
 export declare function getContentType(request: IncomingMessage): string | undefined;
@@ -28,6 +47,16 @@ export declare function isJSONContentType(contentType: string | undefined): bool
 export declare function isFormContentType(contentType: string | undefined): boolean;
 export declare function isTextContentType(contentType: string | undefined): boolean;
 export declare function isMultipartContentType(contentType: string | undefined): boolean;
+/**
+ * Reads `Content-Length`.
+ *
+ * RFC 9112 §6.1 requires a recipient to reject a message that carries both
+ * `Content-Length` and `Transfer-Encoding`, and §6.3 to reject conflicting
+ * `Content-Length` values. Taking the first of a duplicated pair and ignoring
+ * the rest — as this did — is the attacker-favourable half of a CL.TE/CL.CL
+ * request-smuggling differential whenever the message reaches this helper
+ * from something other than Node's own HTTP/1 parser.
+ */
 export declare function getContentLength(request: IncomingMessage): number | undefined;
 export declare function bodyToBuffer(body: string | Buffer | Uint8Array, encoding?: BufferEncoding): Buffer;
 export declare function bodyToJSON(body: unknown): string;