@zudojs/http 0.0.6 → 1.0.0

package/dist/httpResponse/httpResponse.helper.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Response helper functions.
+ *
+ * @module httpResponse/helpers
+ */
+import type { ResponseHeaders, ResponseCookie } from "./core/httpResponse.type.js";
+/**
+ * Creates a JSON response.
+ */
+export declare function jsonResponse(data: unknown, status?: number, headers?: ResponseHeaders): {
+    readonly status: number;
+    readonly headers: ResponseHeaders;
+    readonly body: string;
+};
+/**
+ * Creates a text response.
+ */
+export declare function textResponse(text: string, status?: number, headers?: ResponseHeaders): {
+    readonly status: number;
+    readonly headers: ResponseHeaders;
+    readonly body: string;
+};
+/**
+ * Creates an HTML response.
+ */
+export declare function htmlResponse(html: string, status?: number, headers?: ResponseHeaders): {
+    readonly status: number;
+    readonly headers: ResponseHeaders;
+    readonly body: string;
+};
+/**
+ * Creates a redirect response.
+ */
+export declare function redirectResponse(url: string, status?: number, headers?: ResponseHeaders): {
+    readonly status: number;
+    readonly headers: ResponseHeaders;
+    readonly body: undefined;
+};
+/**
+ * Creates an empty response.
+ */
+export declare function emptyResponse(status?: number, headers?: ResponseHeaders): {
+    readonly status: number;
+    readonly headers: ResponseHeaders;
+    readonly body: undefined;
+};
+/**
+ * Serializes a response cookie into a Set-Cookie header string.
+ */
+export declare function serializeResponseCookie(cookie: ResponseCookie): string;
+//# sourceMappingURL=httpResponse.helper.d.ts.map

package/dist/httpResponse/httpResponse.helper.js

@@ -0,0 +1,105 @@
+/**
+ * Response helper functions.
+ *
+ * @module httpResponse/helpers
+ */
+/**
+ * Creates a JSON response.
+ */
+export function jsonResponse(data, status = 200, headers = {}) {
+    return {
+        status,
+        headers: {
+            "content-type": "application/json",
+            ...headers,
+        },
+        body: JSON.stringify(data),
+    };
+}
+/**
+ * Creates a text response.
+ */
+export function textResponse(text, status = 200, headers = {}) {
+    return {
+        status,
+        headers: {
+            "content-type": "text/plain",
+            ...headers,
+        },
+        body: text,
+    };
+}
+/**
+ * Creates an HTML response.
+ */
+export function htmlResponse(html, status = 200, headers = {}) {
+    return {
+        status,
+        headers: {
+            "content-type": "text/html",
+            ...headers,
+        },
+        body: html,
+    };
+}
+/**
+ * Creates a redirect response.
+ */
+export function redirectResponse(url, status = 302, headers = {}) {
+    return {
+        status,
+        headers: {
+            location: url,
+            ...headers,
+        },
+        body: undefined,
+    };
+}
+/**
+ * Creates an empty response.
+ */
+export function emptyResponse(status = 204, headers = {}) {
+    return {
+        status,
+        headers,
+        body: undefined,
+    };
+}
+/**
+ * Serializes a response cookie into a Set-Cookie header string.
+ */
+export function serializeResponseCookie(cookie) {
+    let str = `${cookie.name}=${cookie.value}`;
+    if (cookie.options) {
+        const opts = cookie.options;
+        if (opts.domain) {
+            str += `; Domain=${opts.domain}`;
+        }
+        if (opts.path) {
+            str += `; Path=${opts.path}`;
+        }
+        if (opts.expires instanceof Date) {
+            str += `; Expires=${opts.expires.toUTCString()}`;
+        }
+        if (typeof opts.maxAge === "number") {
+            str += `; Max-Age=${opts.maxAge}`;
+        }
+        if (opts.httpOnly) {
+            str += "; HttpOnly";
+        }
+        if (opts.secure) {
+            str += "; Secure";
+        }
+        if (opts.sameSite) {
+            str += `; SameSite=${opts.sameSite}`;
+        }
+        if (opts.priority) {
+            str += `; Priority=${opts.priority}`;
+        }
+        if (opts.partitioned) {
+            str += "; Partitioned";
+        }
+    }
+    return str;
+}
+//# sourceMappingURL=httpResponse.helper.js.map

package/dist/httpResponse/httpResponse.writer.d.ts

@@ -26,6 +26,14 @@ export interface HttpResponseWriter {
     end(chunk?: string | Uint8Array): void;
     flushHeaders?(): void;
     flush?(): void;
+    /**
+     * Resolves once the underlying sink has drained.
+     *
+     * Implemented by runtime writers that can report backpressure. Without it a
+     * streaming body is pulled as fast as the source produces, so a slow client
+     * buffers the whole stream in process memory.
+     */
+    waitForDrain?(): Promise<void>;
 }
 export interface ResponseWriter {
     write(context: HttpResponseContext, writer: HttpResponseWriter, options?: ResponseWriteOptions): void | Promise<void>;

package/dist/httpResponse/httpResponse.writer.js

@@ -9,6 +9,7 @@
  * specific runtime.
  */
 import { HttpResponseContext, serializeResponseCookie, } from "./httpResponse.context.js";
+import { isValidHeaderFieldName, isValidHeaderFieldValue, } from "../httpHeaders/security/index.js";
 /* -------------------------------------------------------------------------- */
 /* Errors                                                                     */
 /* -------------------------------------------------------------------------- */
@@ -24,15 +25,29 @@ export class DefaultResponseWriter {
         const body = context.body;
         const status = context.status;
         const statusText = context.statusText;
-        const headers = context.headers;
         const cookies = context.cookies;
+        /*
+         * `prepareAutomaticHeaders` mutates the context's header map (inferring
+         * Content-Type / Content-Length, stripping Content-Length from
+         * body-forbidden statuses). `context.headers` is a getter that returns a
+         * fresh copy on every access, so the header map must be read *after* this
+         * call — passing a snapshot taken beforehand silently discards every
+         * automatic header.
+         */
         prepareAutomaticHeaders(context);
-        writeHeaders(context, writer, headers);
+        writeHeaders(context, writer);
         writeCookies(writer, cookies);
+        /*
+         * `writeHead` is what commits the header block. Flushing beforehand
+         * commits it with the socket's default status (200) and makes the
+         * subsequent `writeHead` throw ERR_HTTP_HEADERS_SENT, so every response
+         * would reach the client as a 200. Flush only after the status line has
+         * been written.
+         */
+        writer.writeHead(status, statusText);
         if (options.flushHeaders !== false && writer.flushHeaders) {
             writer.flushHeaders();
         }
-        writer.writeHead(status, statusText);
         if (isBodyForbidden(status)) {
             writer.end();
             context.commit();
@@ -79,8 +94,27 @@ export function writeHeaders(context, writer, headers = context.headers) {
     for (const [name, value] of Object.entries(headers)) {
         if (value === undefined)
             continue;
-        const strValue = Array.isArray(value) ? value.join(", ") : value;
-        writer.setHeader(name, strValue);
+        if (!isValidHeaderFieldName(name)) {
+            throw new ResponseWriterError(`Refusing to write response header with invalid field name: ${JSON.stringify(name)}`);
+        }
+        const values = Array.isArray(value) ? value : [value];
+        for (const entry of values) {
+            if (!isValidHeaderFieldValue(entry)) {
+                throw new ResponseWriterError(`Refusing to write response header "${name}": value contains a control character or surrounding whitespace.`);
+            }
+        }
+        if (name.toLowerCase() === "set-cookie") {
+            /*
+             * Set-Cookie is the one header that must not be folded into a single
+             * comma-separated line: browsers read the joined form as one malformed
+             * cookie, so every cookie after the first is lost. Emit one line each.
+             */
+            for (const entry of values) {
+                writer.appendHeader(name, entry);
+            }
+            continue;
+        }
+        writer.setHeader(name, values.join(", "));
     }
 }
 export function writeCookies(writer, cookies) {
@@ -156,7 +190,10 @@ export async function writeReadableStream(stream, writer) {
                 break;
             }
             if (result.value) {
-                writer.write(result.value);
+                const accepted = writer.write(result.value);
+                if (!accepted && writer.waitForDrain) {
+                    await writer.waitForDrain();
+                }
             }
         }
     }

package/dist/httpResponse/index.d.ts

@@ -6,4 +6,5 @@
 export * from "./http.response.js";
 export * from "./httpResponse.context.js";
 export * from "./httpResponse.writer.js";
+export * from "./httpResponse.fromWeb.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpResponse/index.js

@@ -6,4 +6,5 @@
 export * from "./http.response.js";
 export * from "./httpResponse.context.js";
 export * from "./httpResponse.writer.js";
+export * from "./httpResponse.fromWeb.js";
 //# sourceMappingURL=index.js.map

package/dist/httpRouter/core/error/httpRouter.error.d.ts

@@ -0,0 +1,7 @@
+/**
+ * HTTP router error types.
+ *
+ * Re-exports from @zudojs/errors.
+ */
+export { HttpRouterError, RouteConflictError, InvalidRoutePatternError, createHttpRouterError, isHttpRouterError, } from "@zudojs/errors";
+//# sourceMappingURL=httpRouter.error.d.ts.map

package/dist/httpRouter/core/error/httpRouter.error.js

@@ -0,0 +1,7 @@
+/**
+ * HTTP router error types.
+ *
+ * Re-exports from @zudojs/errors.
+ */
+export { HttpRouterError, RouteConflictError, InvalidRoutePatternError, createHttpRouterError, isHttpRouterError, } from "@zudojs/errors";
+//# sourceMappingURL=httpRouter.error.js.map

package/dist/httpRouter/core/error/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @zudojs/http/httpRouter/core/error
+ *
+ * HTTP router error types.
+ */
+export * from "./httpRouter.error.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/core/error/index.js

@@ -0,0 +1,7 @@
+/**
+ * @zudojs/http/httpRouter/core/error
+ *
+ * HTTP router error types.
+ */
+export * from "./httpRouter.error.js";
+//# sourceMappingURL=index.js.map

package/dist/httpRouter/core/factory/httpRoute.factory.base.d.ts

@@ -0,0 +1,44 @@
+/**
+ * HTTP route factory base helpers.
+ *
+ * Internal normalization, validation, execution, and response utilities for
+ * route creation and dispatch.
+ */
+import type { HttpMethod, MatchedRoute, CompiledRoute, HttpRouterContext, HttpRouterRequestContext } from "../types/httpRouter.type.js";
+import { type HttpResponseContext as ResponseContext } from "../../../httpResponse/httpResponse.context.js";
+export declare function normalizeMethod(method: string): HttpMethod | "*";
+export declare function normalizeMethods(method: HttpMethod | readonly HttpMethod[] | "*"): readonly (HttpMethod | "*")[];
+export declare function isHttpMethod(value: string): value is HttpMethod;
+export declare function collectAllowedMethods(routes: readonly CompiledRoute[], path: string): HttpMethod[];
+/**
+ * Extracts the monotonic registration sequence from a generated route id.
+ *
+ * Route ids are shaped `route:<sequence>`; ids that do not follow that shape
+ * sort last, preserving a stable order.
+ */
+export declare function extractRouteSequence(id: string): number;
+/**
+ * Builds a placeholder route used when no route matched a request.
+ */
+export declare function createFallbackRoute(path: string, method: string): MatchedRoute;
+/**
+ * Coerces a handler result into a response context.
+ */
+export declare function normalizeResponse(value: ResponseContext | Response | void): Promise<ResponseContext>;
+/**
+ * Builds the automatic `OPTIONS` response for a matched path.
+ */
+export declare function createOptionsResponse(allowedMethods: readonly string[]): ResponseContext;
+/**
+ * Default handler used when no route matches a request.
+ */
+export declare function defaultNotFoundHandler(context: HttpRouterRequestContext): ResponseContext;
+/**
+ * Default handler used when a path matches but the method does not.
+ */
+export declare function defaultMethodNotAllowedHandler(context: HttpRouterRequestContext, allowedMethods: readonly HttpMethod[]): ResponseContext;
+/**
+ * Runs a matched route's middleware chain followed by its handler.
+ */
+export declare function executeRoute(route: MatchedRoute, context: HttpRouterContext): Promise<ResponseContext>;
+//# sourceMappingURL=httpRoute.factory.base.d.ts.map

package/dist/httpRouter/core/factory/httpRoute.factory.base.js

@@ -0,0 +1,186 @@
+/**
+ * HTTP route factory base helpers.
+ *
+ * Internal normalization, validation, execution, and response utilities for
+ * route creation and dispatch.
+ */
+import { HttpRouterError } from "../error/httpRouter.error.js";
+import { formatAllowHeader } from "../../../httpMethods/http.methods.js";
+import { matchCompiledRoute } from "../../matching/httpRoute.matcher.core.js";
+import { HttpResponseContext, } from "../../../httpResponse/httpResponse.context.js";
+/* -------------------------------------------------------------------------- */
+/* Method Helpers                                                             */
+/* -------------------------------------------------------------------------- */
+export function normalizeMethod(method) {
+    const normalized = method.toUpperCase();
+    if (normalized === "*") {
+        return "*";
+    }
+    if (!isHttpMethod(normalized)) {
+        throw new HttpRouterError(`Unsupported HTTP method "${method}".`);
+    }
+    return normalized;
+}
+export function normalizeMethods(method) {
+    const methods = typeof method === "string" ? [method] : method;
+    return methods.map(normalizeMethod);
+}
+export function isHttpMethod(value) {
+    return (value === "GET" ||
+        value === "HEAD" ||
+        value === "POST" ||
+        value === "PUT" ||
+        value === "PATCH" ||
+        value === "DELETE" ||
+        value === "OPTIONS" ||
+        value === "CONNECT" ||
+        value === "TRACE");
+}
+export function collectAllowedMethods(routes, path) {
+    const methods = new Set();
+    for (const route of routes) {
+        if (!matchCompiledRoute(route, path, false)) {
+            continue;
+        }
+        if (isHttpMethod(route.definition.method)) {
+            methods.add(route.definition.method);
+        }
+    }
+    if (methods.has("GET") && !methods.has("HEAD")) {
+        methods.add("HEAD");
+    }
+    return [...methods];
+}
+/* -------------------------------------------------------------------------- */
+/* Route Identity                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * Extracts the monotonic registration sequence from a generated route id.
+ *
+ * Route ids are shaped `route:<sequence>`; ids that do not follow that shape
+ * sort last, preserving a stable order.
+ */
+export function extractRouteSequence(id) {
+    const match = /^route:(\d+)$/.exec(id);
+    const sequence = match?.[1];
+    if (sequence === undefined) {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    return Number.parseInt(sequence, 10);
+}
+/**
+ * Builds a placeholder route used when no route matched a request.
+ */
+export function createFallbackRoute(path, method) {
+    const fallback = {
+        id: "route:unmatched",
+        method: isHttpMethod(method.toUpperCase()) ? normalizeMethod(method) : "*",
+        path,
+        name: undefined,
+        params: Object.freeze({}),
+        metadata: Object.freeze({}),
+        handler: () => undefined,
+        middleware: Object.freeze([]),
+    };
+    return Object.freeze(fallback);
+}
+/* -------------------------------------------------------------------------- */
+/* Response Helpers                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * Coerces a handler result into a response context.
+ */
+export async function normalizeResponse(value) {
+    if (value instanceof HttpResponseContext) {
+        return value;
+    }
+    if (typeof Response !== "undefined" && value instanceof Response) {
+        const body = value.body === null
+            ? undefined
+            : new Uint8Array(await value.arrayBuffer());
+        return new HttpResponseContext({
+            status: value.status,
+            statusText: value.statusText,
+            headers: Object.fromEntries(value.headers.entries()),
+            body,
+        });
+    }
+    return new HttpResponseContext({ status: 204 });
+}
+/**
+ * Builds the automatic `OPTIONS` response for a matched path.
+ */
+export function createOptionsResponse(allowedMethods) {
+    return new HttpResponseContext({
+        status: 204,
+        headers: {
+            allow: formatAllowHeader(allowedMethods),
+        },
+    });
+}
+/**
+ * Default handler used when no route matches a request.
+ */
+export function defaultNotFoundHandler(context) {
+    return new HttpResponseContext({
+        status: 404,
+        headers: { "content-type": "application/json; charset=utf-8" },
+        body: {
+            error: "Not Found",
+            method: context.method,
+            path: context.path,
+        },
+    });
+}
+/**
+ * Default handler used when a path matches but the method does not.
+ */
+export function defaultMethodNotAllowedHandler(context, allowedMethods) {
+    return new HttpResponseContext({
+        status: 405,
+        headers: {
+            allow: formatAllowHeader(allowedMethods),
+            "content-type": "application/json; charset=utf-8",
+        },
+        body: {
+            error: "Method Not Allowed",
+            method: context.method,
+            path: context.path,
+            allowed: [...allowedMethods],
+        },
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Route Execution                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Runs a matched route's middleware chain followed by its handler.
+ */
+export async function executeRoute(route, context) {
+    const layers = route.middleware;
+    let invoked = -1;
+    const run = async (index) => {
+        if (index <= invoked) {
+            throw new HttpRouterError("Route middleware called next() more than once.");
+        }
+        invoked = index;
+        const layer = layers[index];
+        if (layer === undefined) {
+            return normalizeResponse(await route.handler(context));
+        }
+        let downstream;
+        const result = await layer(context.middleware, async () => {
+            downstream = await run(index + 1);
+            return downstream;
+        });
+        if (result instanceof HttpResponseContext) {
+            return result;
+        }
+        if (typeof Response !== "undefined" && result instanceof Response) {
+            return normalizeResponse(result);
+        }
+        return downstream ?? context.middleware.response;
+    };
+    return run(0);
+}
+//# sourceMappingURL=httpRoute.factory.base.js.map

package/dist/httpRouter/core/factory/httpRoute.factory.d.ts

@@ -0,0 +1,36 @@
+/**
+ * HTTP router factory functions and type guards.
+ */
+import type { RouteDefinition, RouterOptions } from "../types/httpRouter.type.js";
+import { HttpRouter } from "../register/httpRouter.register.js";
+import { HttpRouterGroup } from "../group/httpRouterGroup.core.js";
+import { RouteConflictError, InvalidRoutePatternError } from "../error/httpRouter.error.js";
+/**
+ * Creates a new HTTP router instance.
+ */
+export declare function createRouter(options?: RouterOptions): HttpRouter;
+/**
+ * Creates a normalized route definition.
+ */
+export declare function createRoute(definition: RouteDefinition): RouteDefinition;
+/**
+ * Builds a route path from a pattern and parameters.
+ */
+export declare function buildRoutePath(pattern: string, params?: Readonly<Record<string, string | number>>): string;
+/**
+ * Type guard for HttpRouter instances.
+ */
+export declare function isHttpRouter(value: unknown): value is HttpRouter;
+/**
+ * Type guard for HttpRouterGroup instances.
+ */
+export declare function isHttpRouterGroup(value: unknown): value is HttpRouterGroup;
+/**
+ * Type guard for RouteConflictError instances.
+ */
+export declare function isRouteConflictError(value: unknown): value is RouteConflictError;
+/**
+ * Type guard for InvalidRoutePatternError instances.
+ */
+export declare function isInvalidRoutePatternError(value: unknown): value is InvalidRoutePatternError;
+//# sourceMappingURL=httpRoute.factory.d.ts.map

package/dist/httpRouter/core/factory/httpRoute.factory.js

@@ -0,0 +1,67 @@
+/**
+ * HTTP router factory functions and type guards.
+ */
+import { HttpRouter } from "../register/httpRouter.register.js";
+import { HttpRouterGroup } from "../group/httpRouterGroup.core.js";
+import { RouteConflictError, InvalidRoutePatternError, } from "../error/httpRouter.error.js";
+import { normalizePath } from "../util/httpRoute.util.js";
+/**
+ * Creates a new HTTP router instance.
+ */
+export function createRouter(options = {}) {
+    return new HttpRouter(options);
+}
+/**
+ * Creates a normalized route definition.
+ */
+export function createRoute(definition) {
+    return {
+        ...definition,
+        path: normalizePath(definition.path),
+        middleware: Object.freeze([...(definition.middleware ?? [])]),
+        metadata: Object.freeze({ ...(definition.metadata ?? {}) }),
+    };
+}
+/**
+ * Builds a route path from a pattern and parameters.
+ */
+export function buildRoutePath(pattern, params = {}) {
+    const normalized = normalizePath(pattern);
+    return normalized
+        .replace(/:([a-zA-Z_][a-zA-Z0-9_-]*)(\?)?/g, (_match, name, optional) => {
+        const value = params[name];
+        if (value === undefined || value === null) {
+            if (optional) {
+                return "";
+            }
+            throw new Error(`Missing route parameter "${name}".`);
+        }
+        return encodeURIComponent(String(value));
+    })
+        .replace(/\/+/g, "/");
+}
+/**
+ * Type guard for HttpRouter instances.
+ */
+export function isHttpRouter(value) {
+    return value instanceof HttpRouter;
+}
+/**
+ * Type guard for HttpRouterGroup instances.
+ */
+export function isHttpRouterGroup(value) {
+    return value instanceof HttpRouterGroup;
+}
+/**
+ * Type guard for RouteConflictError instances.
+ */
+export function isRouteConflictError(value) {
+    return value instanceof RouteConflictError;
+}
+/**
+ * Type guard for InvalidRoutePatternError instances.
+ */
+export function isInvalidRoutePatternError(value) {
+    return value instanceof InvalidRoutePatternError;
+}
+//# sourceMappingURL=httpRoute.factory.js.map

package/dist/httpRouter/core/factory/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @zudojs/http/httpRouter/core/factory
+ *
+ * HTTP route factory utilities.
+ */
+export * from "./httpRoute.factory.js";
+export * from "./httpRoute.factory.base.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/core/factory/index.js

@@ -0,0 +1,8 @@
+/**
+ * @zudojs/http/httpRouter/core/factory
+ *
+ * HTTP route factory utilities.
+ */
+export * from "./httpRoute.factory.js";
+export * from "./httpRoute.factory.base.js";
+//# sourceMappingURL=index.js.map