@zudojs/http 0.1.0 → 1.1.0

package/dist/httpResponse/httpResponse.fromWeb.js

@@ -0,0 +1,114 @@
+/**
+ * Conversion from a WHATWG `Response` into an {@link HttpResponseContext}.
+ *
+ * @module httpResponse/fromWeb
+ *
+ * Returning a plain web `Response` from a middleware is part of the public
+ * contract (`HttpMiddlewareResult` includes `Response`), but nothing in the
+ * package ever converted one. Both middleware normalizers fabricated
+ * `{ response } as unknown as ResponseContext` — an object with no `status`,
+ * no `headers` and no `body`, which the adapter then read as `undefined`.
+ *
+ * A `Response` is not a response context and cannot be cast into one: its
+ * headers live in a `Headers` instance (no own enumerable properties, so
+ * spreading yields `{}`) and its body is a `ReadableStream`. The conversion
+ * has to be written out, and it is written here once so that the pipeline and
+ * the built-in middleware share it.
+ */
+import { HttpResponseContext } from "./httpResponse.context.js";
+/**
+ * Narrows an unknown value to a WHATWG `Response`.
+ *
+ * @param value - Candidate value.
+ * @returns `true` when `value` is a `Response` instance.
+ */
+export function isWebResponse(value) {
+    return typeof Response !== "undefined" && value instanceof Response;
+}
+/**
+ * Copies a `Response`'s headers into a plain header record.
+ *
+ * `set-cookie` is read through `getSetCookie()` so that multiple cookies stay
+ * separate values; iterating `Headers` alone joins them into one
+ * comma-separated string, which is invalid for that header.
+ */
+function collectHeaders(headers) {
+    const collected = {};
+    for (const [name, value] of headers.entries()) {
+        if (name.toLowerCase() === "set-cookie") {
+            continue;
+        }
+        collected[name.toLowerCase()] = value;
+    }
+    const setCookies = typeof headers.getSetCookie === "function" ? headers.getSetCookie() : [];
+    if (setCookies.length > 0) {
+        collected["set-cookie"] = setCookies;
+    }
+    return collected;
+}
+function assertBodyReadable(response) {
+    if (response.bodyUsed) {
+        /*
+         * Silently producing a body-less context here would drop the payload the
+         * middleware meant to send, which is exactly the failure this module
+         * exists to remove. Fail loudly instead.
+         */
+        throw new TypeError("Cannot convert a Response whose body has already been consumed. " +
+            "Return a fresh Response per request, or clone it before reading.");
+    }
+}
+/**
+ * Converts a web `Response` into a response context, streaming its body.
+ *
+ * The body is carried across as the `Response`'s own `ReadableStream`; the
+ * response writer already has a streaming branch with backpressure handling,
+ * so nothing is buffered and an unbounded stream stays unbounded. This keeps
+ * the conversion synchronous, which is what lets the middleware normalizer
+ * stay synchronous too.
+ *
+ * The stream can only be consumed once, so this suits a `Response` built for
+ * a single request. For a `Response` value reused across requests use
+ * {@link bufferWebResponse}.
+ *
+ * @param response - The web response to convert.
+ * @returns An equivalent response context.
+ * @throws {TypeError} If the response body has already been consumed.
+ */
+export function webResponseToContext(response) {
+    assertBodyReadable(response);
+    return new HttpResponseContext({
+        status: response.status,
+        statusText: response.statusText === "" ? undefined : response.statusText,
+        headers: collectHeaders(response.headers),
+        body: response.body ?? undefined,
+    });
+}
+/**
+ * Converts a web `Response` into a response context, reading its body into
+ * memory.
+ *
+ * Use this for a `Response` that has to survive more than one request: the
+ * resulting context holds bytes rather than a one-shot stream, so it can be
+ * cloned per request.
+ *
+ * @param response - The web response to convert.
+ * @returns An equivalent response context holding a buffered body.
+ * @throws {TypeError} If the response body has already been consumed.
+ */
+export async function bufferWebResponse(response) {
+    assertBodyReadable(response);
+    const headers = collectHeaders(response.headers);
+    const status = response.status;
+    const statusText = response.statusText === "" ? undefined : response.statusText;
+    if (response.body === null) {
+        return new HttpResponseContext({ status, statusText, headers });
+    }
+    const buffer = await response.arrayBuffer();
+    return new HttpResponseContext({
+        status,
+        statusText,
+        headers,
+        body: new Uint8Array(buffer),
+    });
+}
+//# sourceMappingURL=httpResponse.fromWeb.js.map

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

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ *
+ * The destination goes through {@link assertSafeRedirect}: a `javascript:` or
+ * `data:` URL, a scheme-relative `//evil.com`, or a value carrying a control
+ * character throws instead of being emitted as `Location`.
+ *
+ * @throws {TypeError} If the destination is not a safe redirect target.
+ */
+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.
+ *
+ * This is the serializer the adapters use for `response.cookie()` and it
+ * previously concatenated every field verbatim, so a value such as
+ * `x; Domain=evil.com` became a second attribute and a `__Host-` cookie
+ * missing `Secure` was emitted (and silently dropped by the browser). It now
+ * applies the same rules as `serializeCookie()` in the cookies module:
+ *
+ * - the name must be an RFC 6265 token;
+ * - `__Host-` / `__Secure-` prefix constraints are enforced;
+ * - `Domain` and `Path` may not contain `;` or a control character;
+ * - a value that is not made only of `cookie-octet` characters is
+ *   percent-encoded, so it can neither inject an attribute nor split the
+ *   header (a value that is already valid is emitted unchanged);
+ * - `maxAge` must be finite and `expires` must be a valid `Date`.
+ *
+ * @throws {TypeError} If the name, a prefix rule or an attribute is invalid.
+ */
+export declare function serializeResponseCookie(cookie: ResponseCookie): string;
+//# sourceMappingURL=httpResponse.helper.d.ts.map

package/dist/httpResponse/httpResponse.helper.js

@@ -0,0 +1,174 @@
+/**
+ * Response helper functions.
+ *
+ * @module httpResponse/helpers
+ */
+import { assertSafeRedirect } from "../httpRedirect/http.redirect.js";
+/**
+ * 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.
+ *
+ * The destination goes through {@link assertSafeRedirect}: a `javascript:` or
+ * `data:` URL, a scheme-relative `//evil.com`, or a value carrying a control
+ * character throws instead of being emitted as `Location`.
+ *
+ * @throws {TypeError} If the destination is not a safe redirect target.
+ */
+export function redirectResponse(url, status = 302, headers = {}) {
+    return {
+        status,
+        headers: {
+            location: assertSafeRedirect(url),
+            ...headers,
+        },
+        body: undefined,
+    };
+}
+/**
+ * Creates an empty response.
+ */
+export function emptyResponse(status = 204, headers = {}) {
+    return {
+        status,
+        headers,
+        body: undefined,
+    };
+}
+/**
+ * RFC 6265 `cookie-name`, which is an RFC 9110 `token`.
+ */
+const COOKIE_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * RFC 6265 `cookie-octet`: printable US-ASCII minus CTLs, SP, DQUOTE, comma,
+ * semicolon and backslash.
+ */
+const COOKIE_OCTETS = /^[\u0021\u0023-\u002b\u002d-\u003a\u003c-\u005b\u005d-\u007e]*$/;
+/**
+ * Characters that must never appear in a cookie attribute value: `;` starts
+ * the next attribute, and any control character can split the header.
+ */
+const COOKIE_ATTRIBUTE_FORBIDDEN = /[;\u0000-\u001f\u007f]/;
+/**
+ * Serializes a response cookie into a Set-Cookie header string.
+ *
+ * This is the serializer the adapters use for `response.cookie()` and it
+ * previously concatenated every field verbatim, so a value such as
+ * `x; Domain=evil.com` became a second attribute and a `__Host-` cookie
+ * missing `Secure` was emitted (and silently dropped by the browser). It now
+ * applies the same rules as `serializeCookie()` in the cookies module:
+ *
+ * - the name must be an RFC 6265 token;
+ * - `__Host-` / `__Secure-` prefix constraints are enforced;
+ * - `Domain` and `Path` may not contain `;` or a control character;
+ * - a value that is not made only of `cookie-octet` characters is
+ *   percent-encoded, so it can neither inject an attribute nor split the
+ *   header (a value that is already valid is emitted unchanged);
+ * - `maxAge` must be finite and `expires` must be a valid `Date`.
+ *
+ * @throws {TypeError} If the name, a prefix rule or an attribute is invalid.
+ */
+export function serializeResponseCookie(cookie) {
+    const name = cookie.name;
+    if (!name || !COOKIE_NAME_TOKEN.test(name)) {
+        throw new TypeError(`Invalid cookie name: ${JSON.stringify(name)}`);
+    }
+    const opts = cookie.options ?? {};
+    if (name.startsWith("__Host-")) {
+        if (!opts.secure) {
+            throw new TypeError("A __Host- cookie requires the Secure attribute.");
+        }
+        if (opts.domain) {
+            throw new TypeError("A __Host- cookie must not set a Domain attribute.");
+        }
+        if ((opts.path ?? "/") !== "/") {
+            throw new TypeError("A __Host- cookie requires Path=/.");
+        }
+    }
+    else if (name.startsWith("__Secure-") && !opts.secure) {
+        throw new TypeError("A __Secure- cookie requires the Secure attribute.");
+    }
+    const rawValue = String(cookie.value);
+    const value = COOKIE_OCTETS.test(rawValue)
+        ? rawValue
+        : encodeURIComponent(rawValue);
+    let str = `${name}=${value}`;
+    if (opts.domain) {
+        if (COOKIE_ATTRIBUTE_FORBIDDEN.test(opts.domain)) {
+            throw new TypeError("Invalid cookie domain.");
+        }
+        str += `; Domain=${opts.domain}`;
+    }
+    if (opts.path) {
+        if (COOKIE_ATTRIBUTE_FORBIDDEN.test(opts.path)) {
+            throw new TypeError("Invalid cookie path.");
+        }
+        str += `; Path=${opts.path}`;
+    }
+    if (opts.expires instanceof Date) {
+        if (Number.isNaN(opts.expires.getTime())) {
+            throw new TypeError("Cookie expires must be a valid Date.");
+        }
+        str += `; Expires=${opts.expires.toUTCString()}`;
+    }
+    if (typeof opts.maxAge === "number") {
+        if (!Number.isFinite(opts.maxAge)) {
+            throw new TypeError("Cookie maxAge must be a finite number.");
+        }
+        str += `; Max-Age=${Math.floor(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