@zudojs/http 1.2.0 → 1.4.0

package/dist/httpOpenApi/httpOpenApi.document.js

@@ -0,0 +1,61 @@
+/**
+ * OpenAPI document generation from a router's registered routes.
+ */
+import { createOpenAPIDocumentFromRoutes, createOpenAPIManagerFromRoutes, routeDescriptorToRouteInfo, } from "@zudojs/openapi";
+import { collectOpenAPIRoutes } from "./routeTable/routeTable.collect.js";
+/**
+ * Generates an OpenAPI document from the routes a router has registered.
+ *
+ * Nothing is added by hand: every route's method and path come from the
+ * router, and its summary, tags, schemas and responses from the `openapi`
+ * option it was registered with. Call it again after adding routes and the
+ * new routes are in the result.
+ *
+ * ```ts
+ * const router = createRouter();
+ * router.get("/users/:id", getUser, {
+ *   openapi: { summary: "Get a user", tags: ["users"],
+ *              responses: { "200": { schema: userSchema } } },
+ * });
+ * const document = generateOpenAPIDocument(router, {
+ *   info: { title: "Users API", version: "1.0.0" },
+ *   exclude: ["/health"],
+ * });
+ * ```
+ *
+ * @throws {OpenAPIRouteError} When a documented route cannot be expressed.
+ * @throws {OpenAPIValidationError} When `validate` is set and the document
+ *   is invalid.
+ */
+export function generateOpenAPIDocument(router, options) {
+    return createOpenAPIDocumentFromRoutes(collectOpenAPIRoutes(router, options), options);
+}
+function fingerprint(router) {
+    return router
+        .compiled()
+        .map((route) => route.definition.id)
+        .sort()
+        .join(",");
+}
+/**
+ * Creates an `OpenAPIManager` kept in step with `router`: each access checks
+ * the route table and re-reads it only when a route was added or removed,
+ * so serving the document stays cheap while never going stale.
+ */
+export function createRouterOpenAPI(router, options) {
+    const manager = createOpenAPIManagerFromRoutes([], options);
+    let seen;
+    const refresh = () => {
+        const current = fingerprint(router);
+        if (current !== seen) {
+            manager.setRoutes(collectOpenAPIRoutes(router, options).map(routeDescriptorToRouteInfo));
+            seen = current;
+        }
+        return manager;
+    };
+    return Object.freeze({
+        manager: refresh,
+        document: () => refresh().getDocument(options.validate ?? false),
+    });
+}
+//# sourceMappingURL=httpOpenApi.document.js.map

package/dist/httpOpenApi/httpOpenApi.mount.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Serving a router's own OpenAPI document and documentation page.
+ */
+import type { OpenAPIDocument } from "@zudojs/openapi";
+import type { HttpRouter } from "../httpRouter/core/register/httpRouter.register.js";
+import type { HttpOpenAPIMountOptions } from "./httpOpenApi.type.js";
+/** What `mountOpenAPI` registered. */
+export interface HttpOpenAPIMount {
+    /** The current document, built from the router's routes. */
+    document(): OpenAPIDocument;
+    /** Removes every route `mountOpenAPI` registered. */
+    unmount(): void;
+}
+/**
+ * Serves the router's OpenAPI document at `path` (default `/openapi.json`),
+ * optionally as YAML at `yamlPath`, and a Swagger UI page (or ReDoc, with
+ * `ui: { renderer: "redoc" }`) at `docsPath` (default `/docs`).
+ *
+ * The document is generated from the routes registered on `router`, so a
+ * route added after mounting appears on the next request. The routes this
+ * registers are hidden from the document themselves.
+ *
+ * ```ts
+ * mountOpenAPI(router, {
+ *   info: { title: "Orders API", version: "1.0.0" },
+ *   exclude: ["/health", "/internal/*"],
+ * });
+ * ```
+ */
+export declare function mountOpenAPI(router: HttpRouter, options: HttpOpenAPIMountOptions): HttpOpenAPIMount;
+//# sourceMappingURL=httpOpenApi.mount.d.ts.map

package/dist/httpOpenApi/httpOpenApi.mount.js

@@ -0,0 +1,58 @@
+/**
+ * Serving a router's own OpenAPI document and documentation page.
+ */
+import { createResponseContext } from "../httpResponse/httpResponse.context.js";
+import { createRouterOpenAPI } from "./httpOpenApi.document.js";
+/**
+ * Serves the router's OpenAPI document at `path` (default `/openapi.json`),
+ * optionally as YAML at `yamlPath`, and a Swagger UI page (or ReDoc, with
+ * `ui: { renderer: "redoc" }`) at `docsPath` (default `/docs`).
+ *
+ * The document is generated from the routes registered on `router`, so a
+ * route added after mounting appears on the next request. The routes this
+ * registers are hidden from the document themselves.
+ *
+ * ```ts
+ * mountOpenAPI(router, {
+ *   info: { title: "Orders API", version: "1.0.0" },
+ *   exclude: ["/health", "/internal/*"],
+ * });
+ * ```
+ */
+export function mountOpenAPI(router, options) {
+    const source = createRouterOpenAPI(router, options);
+    const jsonPath = options.path ?? "/openapi.json";
+    const cacheControl = options.cacheControl ?? "no-cache";
+    const routeOptions = {
+        openapi: false,
+        ...(options.middleware ? { middleware: options.middleware } : {}),
+    };
+    const serve = (format) => () => {
+        const response = source.manager().toResponse({
+            format,
+            validate: options.validate ?? false,
+            cacheControl,
+        });
+        return createResponseContext({ ...response, headers: { ...response.headers } });
+    };
+    const removers = [router.get(jsonPath, serve("json"), routeOptions)];
+    if (typeof options.yamlPath === "string") {
+        removers.push(router.get(options.yamlPath, serve("yaml"), routeOptions));
+    }
+    const docsPath = options.docsPath ?? "/docs";
+    if (docsPath !== false) {
+        const ui = { ...options.ui, specUrl: options.ui?.specUrl ?? jsonPath };
+        removers.push(router.get(docsPath, () => {
+            const response = source.manager().toUIResponse(ui);
+            return createResponseContext({ ...response, headers: { ...response.headers } });
+        }, routeOptions));
+    }
+    return Object.freeze({
+        document: source.document,
+        unmount: () => {
+            for (const remove of removers)
+                remove();
+        },
+    });
+}
+//# sourceMappingURL=httpOpenApi.mount.js.map

package/dist/httpOpenApi/httpOpenApi.type.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Types for generating and serving OpenAPI documents from a router.
+ */
+import type { OpenAPIDocumentFromRoutesOptions, OpenAPIUIOptions } from "@zudojs/openapi";
+import type { CompiledRoute, MatchedRoute } from "../httpRouter/core/types/httpRouter.type.js";
+import type { HttpMiddleware } from "../httpMiddleware/httpMiddleware.type.js";
+import type { HttpOpenAPIWildcardMode } from "./routeTable/routeTable.template.js";
+/** Anything exposing the router's compiled route table (`HttpRouter`). */
+export interface HttpOpenAPIRouteSource {
+    compiled(): readonly CompiledRoute[];
+}
+/** A path matcher: exact path, `prefix/*` prefix, a RegExp, or a predicate. */
+export type HttpOpenAPIRouteFilter = readonly (string | RegExp)[] | ((route: MatchedRoute) => boolean);
+/** Which registered routes reach the document. */
+export interface HttpOpenAPIRouteSelection {
+    /**
+     * Routes to leave out, matched against the registered pattern
+     * (`/health`, `/internal/*`, `/^\/admin/`) or by predicate. Routes whose
+     * `openapi` is `false` or `{ hidden: true }` are always left out.
+     */
+    readonly exclude?: HttpOpenAPIRouteFilter;
+    /**
+     * `"include"` (default) documents every route, with whatever the route
+     * itself declares; `"exclude"` documents only routes that declare
+     * `openapi` metadata.
+     */
+    readonly undocumented?: "include" | "exclude";
+    /** How `*rest` segments are documented. Default: `"parameter"`. */
+    readonly wildcards?: HttpOpenAPIWildcardMode;
+    /** Receives routes skipped because another route owns the same operation. */
+    readonly onRouteWarning?: (message: string) => void;
+}
+/** Options for `generateOpenAPIDocument`. */
+export interface HttpOpenAPIOptions extends OpenAPIDocumentFromRoutesOptions, HttpOpenAPIRouteSelection {
+}
+/** Options for `mountOpenAPI`. */
+export interface HttpOpenAPIMountOptions extends HttpOpenAPIOptions {
+    /** Where the JSON document is served. Default: `/openapi.json`. */
+    readonly path?: string;
+    /** Where a YAML copy is served, or `false` (default) for none. */
+    readonly yamlPath?: string | false;
+    /** Where the documentation page is served, or `false`. Default: `/docs`. */
+    readonly docsPath?: string | false;
+    /**
+     * Documentation page options (`renderer: "redoc"`, `logo`, …). `specUrl`
+     * defaults to `path`; set it when the router is served under a prefix.
+     */
+    readonly ui?: Partial<OpenAPIUIOptions>;
+    /** `cache-control` for the document responses. Default: `no-cache`. */
+    readonly cacheControl?: string;
+    /** Middleware run before the documentation routes (e.g. auth). */
+    readonly middleware?: readonly HttpMiddleware[];
+}
+//# sourceMappingURL=httpOpenApi.type.d.ts.map

package/dist/httpOpenApi/httpOpenApi.type.js

@@ -0,0 +1,5 @@
+/**
+ * Types for generating and serving OpenAPI documents from a router.
+ */
+export {};
+//# sourceMappingURL=httpOpenApi.type.js.map

package/dist/httpOpenApi/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @zudojs/http/httpOpenApi
+ *
+ * OpenAPI generated from the application: documents built from the routes a
+ * router has actually registered (`generateOpenAPIDocument`), kept in step
+ * with it (`createRouterOpenAPI`), and served with a documentation page
+ * (`mountOpenAPI`). Route-level documentation is the `openapi` route option.
+ */
+export { generateOpenAPIDocument, createRouterOpenAPI, type HttpRouterOpenAPI, } from "./httpOpenApi.document.js";
+export { mountOpenAPI, type HttpOpenAPIMount } from "./httpOpenApi.mount.js";
+export type { HttpOpenAPIOptions, HttpOpenAPIMountOptions, HttpOpenAPIRouteSelection, HttpOpenAPIRouteFilter, HttpOpenAPIRouteSource, } from "./httpOpenApi.type.js";
+export * from "./routeTable/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpOpenApi/index.js

@@ -0,0 +1,12 @@
+/**
+ * @zudojs/http/httpOpenApi
+ *
+ * OpenAPI generated from the application: documents built from the routes a
+ * router has actually registered (`generateOpenAPIDocument`), kept in step
+ * with it (`createRouterOpenAPI`), and served with a documentation page
+ * (`mountOpenAPI`). Route-level documentation is the `openapi` route option.
+ */
+export { generateOpenAPIDocument, createRouterOpenAPI, } from "./httpOpenApi.document.js";
+export { mountOpenAPI } from "./httpOpenApi.mount.js";
+export * from "./routeTable/index.js";
+//# sourceMappingURL=index.js.map

package/dist/httpOpenApi/routeTable/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @zudojs/http/httpOpenApi/routeTable
+ *
+ * Reads a router's compiled route table as OpenAPI route descriptors:
+ * pattern → path template translation, route selection, and merging of
+ * group-level documentation into route-level documentation.
+ */
+export { collectOpenAPIRoutes } from "./routeTable.collect.js";
+export { routePathVariants, wildcardParameterName, type HttpOpenAPIPathVariant, type HttpOpenAPIWildcardMode, } from "./routeTable.template.js";
+export { mergeRouteOpenAPI } from "./routeTable.merge.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpOpenApi/routeTable/index.js

@@ -0,0 +1,11 @@
+/**
+ * @zudojs/http/httpOpenApi/routeTable
+ *
+ * Reads a router's compiled route table as OpenAPI route descriptors:
+ * pattern → path template translation, route selection, and merging of
+ * group-level documentation into route-level documentation.
+ */
+export { collectOpenAPIRoutes } from "./routeTable.collect.js";
+export { routePathVariants, wildcardParameterName, } from "./routeTable.template.js";
+export { mergeRouteOpenAPI } from "./routeTable.merge.js";
+//# sourceMappingURL=index.js.map

package/dist/httpOpenApi/routeTable/routeTable.collect.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Collection of a router's registered routes as OpenAPI route descriptors.
+ */
+import { type OpenAPIRouteDescriptor } from "@zudojs/openapi";
+import type { HttpOpenAPIRouteSelection, HttpOpenAPIRouteSource } from "../httpOpenApi.type.js";
+/**
+ * Lists the operations a router actually serves, as descriptors for
+ * `createOpenAPIDocumentFromRoutes`.
+ *
+ * Routes appear in registration order. Left out: `all()` / `"*"` routes
+ * (they answer every method, so no single operation describes them),
+ * methods OpenAPI cannot carry (`CONNECT`), hidden and excluded routes. The
+ * router's automatic `HEAD` and `OPTIONS` answers are never registered
+ * routes, so they never appear; an explicitly registered `HEAD` does.
+ * When two patterns document the same operation (`/a/:id` and `/a/{id}`),
+ * the one registered first is kept and the other reported.
+ */
+export declare function collectOpenAPIRoutes(source: HttpOpenAPIRouteSource, selection?: HttpOpenAPIRouteSelection): readonly OpenAPIRouteDescriptor[];
+//# sourceMappingURL=routeTable.collect.d.ts.map

package/dist/httpOpenApi/routeTable/routeTable.collect.js

@@ -0,0 +1,89 @@
+/**
+ * Collection of a router's registered routes as OpenAPI route descriptors.
+ */
+import { isOpenAPIMethod, toOpenAPIPath, } from "@zudojs/openapi";
+import { routePathVariants } from "./routeTable.template.js";
+function sequenceOf(route) {
+    const sequence = Number(route.definition.id.split(":").pop());
+    return Number.isFinite(sequence) ? sequence : Number.MAX_SAFE_INTEGER;
+}
+function matchesFilter(route, filter) {
+    if (filter === undefined)
+        return false;
+    if (typeof filter === "function")
+        return filter(route);
+    return filter.some((entry) => {
+        if (entry instanceof RegExp)
+            return entry.test(route.path);
+        if (entry.endsWith("/*")) {
+            const prefix = entry.slice(0, -2);
+            return route.path === prefix || route.path.startsWith(`${prefix}/`);
+        }
+        return route.path === entry;
+    });
+}
+/** The route's `openapi` metadata; `false` when it is hidden. */
+function documentationOf(route) {
+    const value = route.metadata["openapi"];
+    if (value === false)
+        return false;
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const metadata = value;
+    return metadata.hidden === true ? false : metadata;
+}
+/**
+ * Lists the operations a router actually serves, as descriptors for
+ * `createOpenAPIDocumentFromRoutes`.
+ *
+ * Routes appear in registration order. Left out: `all()` / `"*"` routes
+ * (they answer every method, so no single operation describes them),
+ * methods OpenAPI cannot carry (`CONNECT`), hidden and excluded routes. The
+ * router's automatic `HEAD` and `OPTIONS` answers are never registered
+ * routes, so they never appear; an explicitly registered `HEAD` does.
+ * When two patterns document the same operation (`/a/:id` and `/a/{id}`),
+ * the one registered first is kept and the other reported.
+ */
+export function collectOpenAPIRoutes(source, selection = {}) {
+    const routes = [...source.compiled()].sort((a, b) => sequenceOf(a) - sequenceOf(b));
+    const descriptors = [];
+    const seen = new Map();
+    for (const route of routes) {
+        const definition = route.definition;
+        if (definition.method === "*" || !isOpenAPIMethod(definition.method))
+            continue;
+        const documentation = documentationOf(definition);
+        if (documentation === false)
+            continue;
+        if (documentation === undefined && selection.undocumented === "exclude")
+            continue;
+        if (matchesFilter(definition, selection.exclude))
+            continue;
+        const variants = routePathVariants(route, selection.wildcards);
+        variants.forEach((variant, index) => {
+            const key = `${definition.method} ${toOpenAPIPath(variant.path)}`;
+            const owner = seen.get(key);
+            if (owner !== undefined) {
+                selection.onRouteWarning?.(`${definition.method} ${definition.path} documents the same operation as ` +
+                    `${owner} (${key}); only the first registered is documented.`);
+                return;
+            }
+            seen.set(key, `${definition.method} ${definition.path}`);
+            const operationId = documentation?.operationId;
+            descriptors.push({
+                ...documentation,
+                method: definition.method,
+                path: variant.path,
+                ...(operationId !== undefined && index > 0
+                    ? { operationId: `${operationId}_${index}` }
+                    : {}),
+                inferredParameters: [
+                    ...variant.inferredParameters,
+                    ...(documentation?.inferredParameters ?? []),
+                ],
+            });
+        });
+    }
+    return descriptors;
+}
+//# sourceMappingURL=routeTable.collect.js.map

package/dist/httpOpenApi/routeTable/routeTable.merge.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Merging of group-level and route-level OpenAPI documentation.
+ */
+import type { HttpRouteOpenAPI } from "../../httpRouter/core/types/httpRouter.type.js";
+/**
+ * Combines a router group's `openapi` defaults with a route's own.
+ *
+ * The route wins field by field, except that `tags` are unioned and
+ * `parameters` concatenated (a route parameter with the same name and
+ * location still replaces the group's when the document is built). `false`
+ * on the route hides it; `false` on the group hides every route that does
+ * not document itself.
+ */
+export declare function mergeRouteOpenAPI(defaults: HttpRouteOpenAPI | undefined, route: HttpRouteOpenAPI | undefined): HttpRouteOpenAPI | undefined;
+//# sourceMappingURL=routeTable.merge.d.ts.map

package/dist/httpOpenApi/routeTable/routeTable.merge.js

@@ -0,0 +1,37 @@
+/**
+ * Merging of group-level and route-level OpenAPI documentation.
+ */
+function union(left, right) {
+    if (left === undefined)
+        return right;
+    if (right === undefined)
+        return left;
+    return [...new Set([...left, ...right])];
+}
+/**
+ * Combines a router group's `openapi` defaults with a route's own.
+ *
+ * The route wins field by field, except that `tags` are unioned and
+ * `parameters` concatenated (a route parameter with the same name and
+ * location still replaces the group's when the document is built). `false`
+ * on the route hides it; `false` on the group hides every route that does
+ * not document itself.
+ */
+export function mergeRouteOpenAPI(defaults, route) {
+    if (route === undefined)
+        return defaults;
+    if (route === false || defaults === undefined || defaults === false) {
+        return route;
+    }
+    const tags = union(defaults.tags, route.tags);
+    const parameters = defaults.parameters === undefined && route.parameters === undefined
+        ? undefined
+        : [...(defaults.parameters ?? []), ...(route.parameters ?? [])];
+    return {
+        ...defaults,
+        ...route,
+        ...(tags === undefined ? {} : { tags }),
+        ...(parameters === undefined ? {} : { parameters }),
+    };
+}
+//# sourceMappingURL=routeTable.merge.js.map

package/dist/httpOpenApi/routeTable/routeTable.template.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Translation of compiled router patterns into OpenAPI path templates.
+ *
+ * Built from the compiled segments rather than the pattern string, so every
+ * syntax the router accepts — `:id`, `{id}`, `:id(\\d+)`, `:id?`, `*rest` —
+ * is read the way the router itself reads it.
+ */
+import type { RouteParameterMetadata } from "@zudojs/openapi";
+import type { CompiledRoute } from "../../httpRouter/core/types/httpRouter.type.js";
+/** How wildcard (`*rest`) segments are documented. */
+export type HttpOpenAPIWildcardMode = "parameter" | "exclude";
+/** One documented path for a route. */
+export interface HttpOpenAPIPathVariant {
+    /** The OpenAPI path template, e.g. `/users/{id}`. */
+    readonly path: string;
+    /** Constraints the pattern itself declares (regex, wildcard tail). */
+    readonly inferredParameters: readonly RouteParameterMetadata[];
+}
+/** The template slot name for a wildcard; a bare `*` becomes `wildcard`. */
+export declare function wildcardParameterName(name: string): string;
+/**
+ * Lists the OpenAPI paths a compiled route answers.
+ *
+ * OpenAPI has no optional path parameters, so each optional segment doubles
+ * the variants (with and without it). A wildcard becomes one templated slot
+ * described as matching the rest of the path, or — with `wildcards:
+ * "exclude"` — removes the route from the document (an empty list).
+ */
+export declare function routePathVariants(route: CompiledRoute, wildcards?: HttpOpenAPIWildcardMode): readonly HttpOpenAPIPathVariant[];
+//# sourceMappingURL=routeTable.template.d.ts.map

package/dist/httpOpenApi/routeTable/routeTable.template.js

@@ -0,0 +1,67 @@
+/**
+ * Translation of compiled router patterns into OpenAPI path templates.
+ *
+ * Built from the compiled segments rather than the pattern string, so every
+ * syntax the router accepts — `:id`, `{id}`, `:id(\\d+)`, `:id?`, `*rest` —
+ * is read the way the router itself reads it.
+ */
+/** The template slot name for a wildcard; a bare `*` becomes `wildcard`. */
+export function wildcardParameterName(name) {
+    return name === "*" || name === "" ? "wildcard" : name;
+}
+/**
+ * Lists the OpenAPI paths a compiled route answers.
+ *
+ * OpenAPI has no optional path parameters, so each optional segment doubles
+ * the variants (with and without it). A wildcard becomes one templated slot
+ * described as matching the rest of the path, or — with `wildcards:
+ * "exclude"` — removes the route from the document (an empty list).
+ */
+export function routePathVariants(route, wildcards = "parameter") {
+    let drafts = [{ parts: [], parameters: [] }];
+    for (const segment of route.segments) {
+        if (segment.type === "literal") {
+            drafts = drafts.map((draft) => ({
+                ...draft,
+                parts: [...draft.parts, segment.value],
+            }));
+            continue;
+        }
+        if (segment.type === "wildcard") {
+            if (wildcards === "exclude")
+                return [];
+            const name = wildcardParameterName(segment.name);
+            const parameter = {
+                name,
+                in: "path",
+                description: 'The rest of the path; may contain "/".',
+                schema: { type: "string" },
+            };
+            drafts = drafts.map((draft) => ({
+                parts: [...draft.parts, `{${name}}`],
+                parameters: [...draft.parameters, parameter],
+            }));
+            continue;
+        }
+        const parameters = segment.pattern === undefined
+            ? []
+            : [
+                {
+                    name: segment.name,
+                    in: "path",
+                    schema: { type: "string", pattern: segment.pattern.source },
+                },
+            ];
+        const withSegment = drafts.map((draft) => ({
+            parts: [...draft.parts, `{${segment.name}}`],
+            parameters: [...draft.parameters, ...parameters],
+        }));
+        drafts = segment.optional ? [...drafts, ...withSegment] : withSegment;
+    }
+    const trailing = route.strictTrailingSlash && route.expectsTrailingSlash === true ? "/" : "";
+    return drafts.map((draft) => ({
+        path: draft.parts.length === 0 ? "/" : `/${draft.parts.join("/")}${trailing}`,
+        inferredParameters: draft.parameters,
+    }));
+}
+//# sourceMappingURL=routeTable.template.js.map

package/dist/httpProxy/http.proxy.d.ts

@@ -167,6 +167,15 @@ export declare function applyProxyHeaders(headers: readonly HTTPHeader[], additi
  * with `httpTrustProxy.getClientIp` rather than copying the raw header.
  */
 export declare function setForwardedHeaders(headers: readonly HTTPHeader[], target: ProxyTarget, client?: ProxyClientContext): HTTPHeader[];
+/**
+ * Builds an RFC 7239 `Forwarded` field value.
+ *
+ * Every parameter is escaped as a `quoted-string` when it is not a bare
+ * token, and the finished value is checked the same way `setForwardedHeaders`
+ * checks the values it writes.
+ *
+ * @throws {TypeError} If any parameter contains a control character.
+ */
 export declare function createForwardedHeader(address: ForwardedAddress): string;
 export declare function parseForwardedHeader(value: string | undefined | null): ForwardedAddress[];
 /**

package/dist/httpProxy/http.proxy.js

@@ -10,7 +10,7 @@
 import { appendHeader, deleteHeader, getHeader, setHeader, } from "../httpProtocol/http.protocol.js";
 import { isValidHTTPURL, isValidHeaderValue } from "../httpValidation/index.js";
 import { isLinkLocalAddress, isLoopbackAddress, isUniqueLocalAddress, parseIpAddress, } from "../httpTrustProxy/httpTrustProxy.ip.js";
-import { assertSafeHeaderValue } from "../httpHeaders/security/index.js";
+import { assertSafeHeaderValue, escapeHeaderQuotedString, } from "../httpHeaders/security/index.js";
 import { assertProxyPathContained } from "./httpProxy.pathGuard.js";
 /* -------------------------------------------------------------------------- */
 /* Target                                                                     */
@@ -72,6 +72,16 @@ function isBlockedLiteralAddress(hostname) {
             (address.bytes[1] ?? 0) <= 127) {
             return true;
         }
+        /* 192.0.0.0/24 IETF protocol assignments (192.0.0.8, 192.0.0.170, …). */
+        if (first === 192 &&
+            (address.bytes[1] ?? 0) === 0 &&
+            (address.bytes[2] ?? 0) === 0) {
+            return true;
+        }
+        /* 198.18.0.0/15 benchmarking. */
+        if (first === 198 && ((address.bytes[1] ?? 0) & 0xfe) === 18) {
+            return true;
+        }
         return false;
     }
     const first = address.bytes[0] ?? 0;
@@ -361,6 +371,15 @@ function appendForwardedValue(headers, name, value) {
 /* -------------------------------------------------------------------------- */
 /* Standard Forwarded Header                                                  */
 /* -------------------------------------------------------------------------- */
+/**
+ * Builds an RFC 7239 `Forwarded` field value.
+ *
+ * Every parameter is escaped as a `quoted-string` when it is not a bare
+ * token, and the finished value is checked the same way `setForwardedHeaders`
+ * checks the values it writes.
+ *
+ * @throws {TypeError} If any parameter contains a control character.
+ */
 export function createForwardedHeader(address) {
     const parts = [];
     if (address.for) {
@@ -375,7 +394,9 @@ export function createForwardedHeader(address) {
     if (address.protocol) {
         parts.push(`proto=${formatForwardedValue(address.protocol)}`);
     }
-    return parts.join("; ");
+    const value = parts.join("; ");
+    assertSafeHeaderValue(value);
+    return value;
 }
 export function parseForwardedHeader(value) {
     if (!value || value.trim().length === 0) {
@@ -534,11 +555,22 @@ function formatForwardedIdentifier(value) {
     }
     return formatForwardedValue(value);
 }
+/**
+ * Emits an RFC 7239 parameter value.
+ *
+ * Wrapping a value in quotes does not neutralise a CR or LF — the control
+ * character survives into the field value and an attacker-chosen header
+ * follows it on the wire. `escapeHeaderQuotedString` rejects those characters
+ * rather than escaping them, which is what every other quoted-parameter
+ * emitter in this package already uses.
+ *
+ * @throws {TypeError} If the value contains a forbidden control character.
+ */
 function formatForwardedValue(value) {
     if (/^[A-Za-z0-9._:-]+$/.test(value)) {
         return value;
     }
-    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    return `"${escapeHeaderQuotedString(value)}"`;
 }
 function unquoteForwardedValue(value) {
     if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {

package/dist/httpQuery/index.d.ts

@@ -1,7 +1,16 @@
 /**
  * @zudojs/http/httpQuery
  *
- * HTTP query string parsing and utilities.
+ * HTTP query string parsing, request accessors, and serialization.
+ *
+ * Every parser in this module enforces the same four limits
+ * ({@link QueryLimitOptions}) and drops `__proto__`, `constructor` and
+ * `prototype`, on both the string and the `URLSearchParams` entry points.
+ * Exceeding a limit throws {@link HTTPQueryLimitError}, which carries a 414
+ * status code.
  */
-export * from "./http.query.js";
+export * from "./queryTypes/index.js";
+export * from "./queryParse/index.js";
+export * from "./queryRequest/index.js";
+export * from "./querySerialize/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpQuery/index.js

@@ -1,7 +1,16 @@
 /**
  * @zudojs/http/httpQuery
  *
- * HTTP query string parsing and utilities.
+ * HTTP query string parsing, request accessors, and serialization.
+ *
+ * Every parser in this module enforces the same four limits
+ * ({@link QueryLimitOptions}) and drops `__proto__`, `constructor` and
+ * `prototype`, on both the string and the `URLSearchParams` entry points.
+ * Exceeding a limit throws {@link HTTPQueryLimitError}, which carries a 414
+ * status code.
  */
-export * from "./http.query.js";
+export * from "./queryTypes/index.js";
+export * from "./queryParse/index.js";
+export * from "./queryRequest/index.js";
+export * from "./querySerialize/index.js";
 //# sourceMappingURL=index.js.map