@zudojs/http 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/httpAdapter/fetch/httpFetch.helper.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Fetch adapter type guards.
+ *
+ * @module httpAdapter/fetch/helpers
+ */
+import type { FetchRequestInput } from "./httpFetch.type.js";
+/**
+ * Type guard for Request objects.
+ */
+export declare function isRequest(value: unknown): value is Request;
+/**
+ * Type guard for Response objects.
+ */
+export declare function isResponse(value: unknown): value is Response;
+/**
+ * Type guard for FetchRequestInput objects.
+ */
+export declare function isFetchRequestInput(value: unknown): value is FetchRequestInput;
+//# sourceMappingURL=httpFetch.helper.d.ts.map

package/dist/httpAdapter/fetch/httpFetch.helper.js

@@ -0,0 +1,35 @@
+/**
+ * Fetch adapter type guards.
+ *
+ * @module httpAdapter/fetch/helpers
+ */
+/**
+ * Type guard for Request objects.
+ */
+export function isRequest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "method" in value &&
+        "url" in value &&
+        "headers" in value);
+}
+/**
+ * Type guard for Response objects.
+ */
+export function isResponse(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "status" in value &&
+        "headers" in value &&
+        "body" in value);
+}
+/**
+ * Type guard for FetchRequestInput objects.
+ */
+export function isFetchRequestInput(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "url" in value &&
+        typeof value.url === "string");
+}
+//# sourceMappingURL=httpFetch.helper.js.map

package/dist/httpAdapter/fetch/httpFetch.requestContext.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fetch request context creation.
+ *
+ * @module httpAdapter/fetch/requestContext
+ */
+import type { FetchRequestInput } from "./httpFetch.type.js";
+/**
+ * Creates a request context from a FetchRequestInput.
+ */
+export declare function createFetchRequestContext(input: FetchRequestInput): Promise<{
+    readonly method: string;
+    readonly url: URL;
+    readonly headers: Record<string, string>;
+    readonly body: unknown;
+}>;
+/**
+ * Creates a FetchRequest from a FetchRequestInput.
+ */
+export declare function createFetchRequest(input: FetchRequestInput, init?: Omit<RequestInit, "method" | "headers" | "body">): Request;
+//# sourceMappingURL=httpFetch.requestContext.d.ts.map

package/dist/httpAdapter/fetch/httpFetch.requestContext.js

@@ -0,0 +1,72 @@
+/**
+ * Fetch request context creation.
+ *
+ * @module httpAdapter/fetch/requestContext
+ */
+/**
+ * Creates a request context from a FetchRequestInput.
+ */
+export async function createFetchRequestContext(input) {
+    const method = (input.method ?? "GET").toUpperCase();
+    const url = new URL(input.url);
+    const headers = {};
+    if (input.headers) {
+        for (const [key, value] of Object.entries(input.headers)) {
+            if (value !== undefined) {
+                headers[key.toLowerCase()] = value;
+            }
+        }
+    }
+    let body = undefined;
+    if (input.body !== undefined && method !== "GET" && method !== "HEAD") {
+        if (typeof input.body === "string" || Buffer.isBuffer(input.body)) {
+            body = input.body;
+        }
+        else if (typeof input.body === "object") {
+            body = JSON.stringify(input.body);
+            if (!headers["content-type"]) {
+                headers["content-type"] = "application/json";
+            }
+        }
+    }
+    return { method, url, headers, body };
+}
+function stripUndefined(value) {
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry !== undefined) {
+            result[key] = entry;
+        }
+    }
+    return result;
+}
+/**
+ * Creates a FetchRequest from a FetchRequestInput.
+ */
+export function createFetchRequest(input, init = {}) {
+    const method = (input.method ?? "GET").toUpperCase();
+    const headers = new Headers();
+    if (input.headers) {
+        for (const [key, value] of Object.entries(input.headers)) {
+            if (value !== undefined) {
+                headers.set(key, value);
+            }
+        }
+    }
+    const requestInit = {
+        /*
+         * Caller-supplied init first so `method`/`headers`/`body` below always
+         * win, but so security-relevant options — `redirect`, `credentials`,
+         * `integrity`, `mode`, `cache`, `keepalive` — actually reach the Request.
+         */
+        ...stripUndefined(init),
+        method,
+        headers,
+    };
+    if (input.body !== undefined && method !== "GET" && method !== "HEAD") {
+        requestInit.body =
+            typeof input.body === "string" ? input.body : JSON.stringify(input.body);
+    }
+    return new Request(input.url, requestInit);
+}
+//# sourceMappingURL=httpFetch.requestContext.js.map

package/dist/httpAdapter/fetch/httpFetch.responseWriter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Fetch response writer.
+ *
+ * @module httpAdapter/fetch/responseWriter
+ */
+import type { FetchResponseWriter } from "./httpFetch.type.js";
+export declare class FetchHttpResponseWriter implements FetchResponseWriter {
+    private _status;
+    private _headers;
+    private _body;
+    private _ended;
+    status(code: number): FetchResponseWriter;
+    header(name: string, value: string): FetchResponseWriter;
+    send(body?: unknown): Promise<void>;
+    json(data: unknown): Promise<void>;
+    end(): Promise<void>;
+    get status_code(): number;
+    get headers(): Record<string, string>;
+    get body(): unknown;
+    get ended(): boolean;
+    toResponse(): Response;
+}
+/**
+ * Converts a Response to a context object.
+ */
+export declare function responseToContext(response: Response): {
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    readonly body: unknown;
+};
+//# sourceMappingURL=httpFetch.responseWriter.d.ts.map

package/dist/httpAdapter/fetch/httpFetch.responseWriter.js

@@ -0,0 +1,69 @@
+/**
+ * Fetch response writer.
+ *
+ * @module httpAdapter/fetch/responseWriter
+ */
+export class FetchHttpResponseWriter {
+    _status = 200;
+    _headers = {};
+    _body = undefined;
+    _ended = false;
+    status(code) {
+        this._status = code;
+        return this;
+    }
+    header(name, value) {
+        this._headers[name.toLowerCase()] = value;
+        return this;
+    }
+    async send(body) {
+        this._body = body ?? this._body;
+        this._ended = true;
+    }
+    async json(data) {
+        this._body = JSON.stringify(data);
+        this._headers["content-type"] = "application/json";
+        this._ended = true;
+    }
+    async end() {
+        this._ended = true;
+    }
+    get status_code() {
+        return this._status;
+    }
+    get headers() {
+        return { ...this._headers };
+    }
+    get body() {
+        return this._body;
+    }
+    get ended() {
+        return this._ended;
+    }
+    toResponse() {
+        const body = this._body !== undefined
+            ? typeof this._body === "string"
+                ? this._body
+                : JSON.stringify(this._body)
+            : undefined;
+        return new Response(body, {
+            status: this._status,
+            headers: this._headers,
+        });
+    }
+}
+/**
+ * Converts a Response to a context object.
+ */
+export function responseToContext(response) {
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    return {
+        status: response.status,
+        headers,
+        body: response.body,
+    };
+}
+//# sourceMappingURL=httpFetch.responseWriter.js.map

package/dist/httpAdapter/fetch/httpFetch.type.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Fetch adapter types.
+ *
+ * @module httpAdapter/fetch/types
+ */
+export interface FetchAdapterOptions {
+    readonly port?: number;
+    readonly host?: string;
+    readonly maxBodySize?: number;
+    readonly trustProxy?: boolean;
+}
+export interface FetchRequestInput {
+    readonly url: string;
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: unknown;
+}
+export interface FetchResponseWriter {
+    readonly status: (code: number) => FetchResponseWriter;
+    readonly header: (name: string, value: string) => FetchResponseWriter;
+    readonly send: (body?: unknown) => Promise<void>;
+    readonly json: (data: unknown) => Promise<void>;
+    readonly end: () => Promise<void>;
+}
+export interface FetchAdapterResult {
+    readonly response: Response;
+    readonly context: unknown;
+}
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+//# sourceMappingURL=httpFetch.type.d.ts.map

package/dist/httpAdapter/fetch/httpFetch.type.js

@@ -0,0 +1,7 @@
+/**
+ * Fetch adapter types.
+ *
+ * @module httpAdapter/fetch/types
+ */
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB
+//# sourceMappingURL=httpFetch.type.js.map

package/dist/httpAdapter/fetch/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fetch adapter utilities.
+ *
+ * @module httpAdapter/fetch
+ */
+export * from "./httpFetch.type.js";
+export * from "./httpFetch.requestContext.js";
+export * from "./httpFetch.responseWriter.js";
+export * from "./httpFetch.body.js";
+export * from "./httpFetch.helper.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpAdapter/fetch/index.js

@@ -0,0 +1,11 @@
+/**
+ * Fetch adapter utilities.
+ *
+ * @module httpAdapter/fetch
+ */
+export * from "./httpFetch.type.js";
+export * from "./httpFetch.requestContext.js";
+export * from "./httpFetch.responseWriter.js";
+export * from "./httpFetch.body.js";
+export * from "./httpFetch.helper.js";
+//# sourceMappingURL=index.js.map

package/dist/httpAdapter/http.adapter.d.ts

@@ -51,6 +51,18 @@ export interface HttpAdapter {
     normalizeRequest?(input: unknown): RequestContextInit | Promise<RequestContextInit>;
     normalizeResponse?(input: unknown): ResponseContextInit | Promise<ResponseContextInit>;
     writeResponse?(response: unknown, context: HttpResponseContext): void | Promise<void>;
+    /**
+     * Installs the application request handler.
+     *
+     * Optional, but an adapter that stores its handler anywhere other than a
+     * public `handler` property MUST implement this — otherwise `HttpServer`
+     * has no way to hand the handler over and will refuse to start.
+     */
+    setHandler?(handler: HttpHandler): void;
+    /**
+     * Installs the error handler. Same contract as {@link setHandler}.
+     */
+    setErrorHandler?(handler: HttpErrorHandler): void;
     start?(): void | Promise<void>;
     stop?(): void | Promise<void>;
 }
@@ -67,6 +79,14 @@ export declare abstract class BaseHttpAdapter implements HttpAdapter {
     normalizeResponse?(input: unknown): ResponseContextInit | Promise<ResponseContextInit>;
     writeResponse?(response: unknown, context: HttpResponseContext): void | Promise<void>;
     constructor(options?: HttpAdapterOptions);
+    /**
+     * Installs the application request handler.
+     */
+    setHandler(handler: HttpHandler): void;
+    /**
+     * Installs the error handler.
+     */
+    setErrorHandler(handler: HttpErrorHandler): void;
     abstract createRequest(input: unknown): HttpRequestContext;
     abstract createResponse(input?: unknown): HttpResponseContext;
     abstract createWriter(response: unknown): HttpResponseWriter;

package/dist/httpAdapter/http.adapter.js

@@ -37,6 +37,18 @@ export class BaseHttpAdapter {
         this.handler = options.handler;
         this.errorHandler = options.errorHandler;
     }
+    /**
+     * Installs the application request handler.
+     */
+    setHandler(handler) {
+        this.handler = handler;
+    }
+    /**
+     * Installs the error handler.
+     */
+    setErrorHandler(handler) {
+        this.errorHandler = handler;
+    }
     async handle(input) {
         const request = await this.createRequestContext(input);
         const response = this.createResponse();
@@ -262,6 +274,11 @@ export function isResponseContextInit(value) {
 export function mergeResponseContext(target, source) {
     target.setStatus(source.status, source.statusText);
     for (const [name, value] of Object.entries(source.headers)) {
+        /* `ResponseHeaders` allows an explicit `undefined` value, which means the
+         * header is absent. Merging one used to call `.join` on it and throw. */
+        if (value === undefined) {
+            continue;
+        }
         target.setHeader(name, typeof value === "string" ? value : value.join(", "));
     }
     for (const cookie of source.cookies) {

package/dist/httpAdapter/http.adapters.d.ts

@@ -0,0 +1,71 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HTTPContext, HTTPHandler, HTTPMiddleware, HTTPRequest, HTTPResponse, HTTPRouteMatch, HTTPState } from "../httpTypes/http.types.js";
+export interface HTTPAdapter<State extends HTTPState = HTTPState> {
+    readonly name: string;
+    createRequest(request: IncomingMessage): HTTPRequest;
+    createResponse(response: ServerResponse): HTTPResponse;
+    createContext(request: HTTPRequest, response: HTTPResponse, options?: {
+        readonly state?: State;
+        readonly signal?: AbortSignal;
+    }): HTTPContext<State>;
+}
+export declare class NodeHTTPAdapter<State extends HTTPState = HTTPState> implements HTTPAdapter<State> {
+    readonly name = "node";
+    createRequest(request: IncomingMessage): HTTPRequest;
+    createResponse(response: ServerResponse): HTTPResponse;
+    createContext(request: HTTPRequest, response: HTTPResponse, options?: {
+        readonly state?: State;
+        readonly signal?: AbortSignal;
+    }): HTTPContext<State>;
+}
+export interface HTTPAdapterOptions<State extends HTTPState = HTTPState> {
+    readonly adapter?: HTTPAdapter<State>;
+}
+export declare function createHTTPAdapter<State extends HTTPState = HTTPState>(): NodeHTTPAdapter<State>;
+export interface RequestAdapter {
+    toHTTPRequest(request: IncomingMessage): HTTPRequest;
+}
+export declare class NodeRequestAdapter implements RequestAdapter {
+    toHTTPRequest(request: IncomingMessage): HTTPRequest;
+}
+export interface ResponseAdapter {
+    toHTTPResponse(response: ServerResponse): HTTPResponse;
+}
+export declare class NodeResponseAdapter implements ResponseAdapter {
+    toHTTPResponse(response: ServerResponse): HTTPResponse;
+}
+export interface ContextAdapter<State extends HTTPState = HTTPState> {
+    create(request: HTTPRequest, response: HTTPResponse, options?: {
+        readonly state?: State;
+        readonly signal?: AbortSignal;
+    }): HTTPContext<State>;
+}
+export declare class NodeContextAdapter<State extends HTTPState = HTTPState> implements ContextAdapter<State> {
+    create(request: HTTPRequest, response: HTTPResponse, options?: {
+        readonly state?: State;
+        readonly signal?: AbortSignal;
+    }): HTTPContext<State>;
+}
+export interface HTTPHandlerAdapter<State extends HTTPState = HTTPState> {
+    handle(handler: HTTPHandler<State>, context: HTTPContext<State>): Promise<unknown>;
+}
+export declare class DefaultHTTPHandlerAdapter<State extends HTTPState = HTTPState> implements HTTPHandlerAdapter<State> {
+    handle(handler: HTTPHandler<State>, context: HTTPContext<State>): Promise<unknown>;
+}
+export interface HTTPMiddlewareAdapter<State extends HTTPState = HTTPState> {
+    execute(middleware: readonly HTTPMiddleware<State>[], context: HTTPContext<State>, handler: HTTPHandler<State>): Promise<void>;
+}
+export declare class DefaultHTTPMiddlewareAdapter<State extends HTTPState = HTTPState> implements HTTPMiddlewareAdapter<State> {
+    execute(middleware: readonly HTTPMiddleware<State>[], context: HTTPContext<State>, handler: HTTPHandler<State>): Promise<void>;
+}
+export interface HTTPRouteAdapter<State extends HTTPState = HTTPState> {
+    match(method: string, path: string): HTTPRouteMatch<State> | undefined;
+}
+export declare function adaptNodeRequest(request: IncomingMessage): HTTPRequest;
+export declare function adaptNodeResponse(response: ServerResponse): HTTPResponse;
+export declare function adaptNodeContext<State extends HTTPState = HTTPState>(request: IncomingMessage, response: ServerResponse, options?: {
+    readonly state?: State;
+    readonly signal?: AbortSignal;
+}): HTTPContext<State>;
+export declare function isHTTPAdapter(value: unknown): value is HTTPAdapter;
+//# sourceMappingURL=http.adapters.d.ts.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,6 +21,9 @@ 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;
@@ -31,10 +34,28 @@ 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 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>;
 }