@zudojs/http 1.3.0 → 1.4.0

package/dist/httpFetchMount/httpFetchMount.core.js

@@ -0,0 +1,84 @@
+/**
+ * Serving web-standard fetch handlers from an `@zudojs/http` router.
+ */
+import { webResponseToContext } from "../httpResponse/httpResponse.fromWeb.js";
+import { normalizeRoutePattern } from "../httpRouter/core/util/httpRoute.util.js";
+import { contextUrl, toWebRequest } from "./httpFetchMount.request.js";
+/** The wildcard every mount registers; its name is reserved for mounts. */
+const MOUNT_WILDCARD = "*fetchMountPath";
+function segments(path) {
+    return path.split("/").filter((segment) => segment !== "");
+}
+/**
+ * Removes the first `count` path segments, keeping a trailing slash.
+ *
+ * Counted in segments rather than characters so it holds for a mount under
+ * a group prefix, a parameterised mount path and a case-insensitive match.
+ */
+function splitPrefix(pathname, count) {
+    const parts = segments(pathname);
+    const prefix = `/${parts.slice(0, count).join("/")}`;
+    const rest = parts.slice(count);
+    if (rest.length === 0)
+        return [prefix, "/"];
+    return [prefix, `/${rest.join("/")}${pathname.endsWith("/") ? "/" : ""}`];
+}
+/**
+ * Serves a web-standard `(request: Request) => Promise<Response>` handler —
+ * an `@zudojs/rpc` server, `@zudojs/api` operations, any fetch-style app —
+ * under `basePath` of an `@zudojs/http` router or router group.
+ *
+ * The handler receives a `Request` with the original method, headers
+ * (connection-scoped ones removed), body and query, and a `signal` that
+ * aborts when the client disconnects. Its `Response` is streamed back with
+ * status, status text and headers intact, every `Set-Cookie` kept separate.
+ * A handler that throws, or returns something that is not a `Response`,
+ * fails the request like any other route (500 unless the error carries a
+ * status).
+ *
+ * ```ts
+ * mountFetchHandler(router, "/rpc", createRPCFetchHandler(rpcServer));
+ * ```
+ *
+ * @returns A function that removes the mount.
+ */
+export function mountFetchHandler(target, basePath, handler, options = {}) {
+    if (typeof handler !== "function") {
+        throw new TypeError("mountFetchHandler requires a handler function.");
+    }
+    const base = normalizeRoutePattern(basePath);
+    const pattern = base === "/" ? `/${MOUNT_WILDCARD}` : `${base}/${MOUNT_WILDCARD}`;
+    const strip = options.stripPrefix ?? true;
+    const routeHandler = async (context) => {
+        const url = contextUrl(context.request, options.origin);
+        const headers = {};
+        if (strip) {
+            const mounted = segments(context.route.path).length - 1;
+            const [prefix, rest] = splitPrefix(url.pathname, mounted);
+            url.pathname = rest;
+            if (mounted > 0)
+                headers["x-forwarded-prefix"] = prefix;
+        }
+        const request = toWebRequest(context.request, {
+            url,
+            signal: context.signal,
+            headers,
+        });
+        const response = await handler(request);
+        if (!(response instanceof Response)) {
+            throw new TypeError(`The fetch handler mounted at ${base} returned ${typeof response}, not a Response.`);
+        }
+        return webResponseToContext(response);
+    };
+    const routeOptions = {
+        openapi: options.openapi ?? false,
+        ...(options.name === undefined ? {} : { name: options.name }),
+        ...(options.middleware ? { middleware: options.middleware } : {}),
+    };
+    const removers = (options.methods ?? ["*"]).map((method) => target.on(method, pattern, routeHandler, routeOptions));
+    return () => {
+        for (const remove of removers)
+            remove();
+    };
+}
+//# sourceMappingURL=httpFetchMount.core.js.map

package/dist/httpFetchMount/httpFetchMount.request.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Conversion of a request context into a WHATWG `Request`.
+ */
+import type { HttpRequestContext } from "../httpRequest/httpRequest.context.js";
+import type { ToWebRequestOptions } from "./httpFetchMount.type.js";
+/**
+ * The context's URL as an absolute URL. The request target is never read
+ * as an authority; the origin is `origin` when given, else the context's.
+ */
+export declare function contextUrl(context: HttpRequestContext, origin?: string): URL;
+/**
+ * Builds a web `Request` from a request context.
+ *
+ * Headers are copied except connection-scoped ones; the body is the one the
+ * adapter read (bytes, text, a stream, or a parsed value re-encoded as JSON,
+ * labelled `application/json` unless it already had a JSON content type)
+ * and is never attached to `GET` / `HEAD`; the signal aborts the request
+ * when the client disconnects.
+ */
+export declare function toWebRequest(context: HttpRequestContext, options?: ToWebRequestOptions): Request;
+//# sourceMappingURL=httpFetchMount.request.d.ts.map

package/dist/httpFetchMount/httpFetchMount.request.js

@@ -0,0 +1,100 @@
+/**
+ * Conversion of a request context into a WHATWG `Request`.
+ */
+import { parseRequestTarget } from "../httpRequest/target/httpRequest.target.js";
+/**
+ * Connection-scoped headers. They describe the hop between the client and
+ * this server, not the request, and `content-length` is recomputed from the
+ * body actually passed on.
+ */
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-connection",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+    "content-length",
+]);
+const DEFAULT_ORIGIN = "http://localhost";
+const JSON_TYPE = /^application\/(?:[\w.+-]+\+)?json(?:\s*;|$)/i;
+/**
+ * The origin of the web request: `pinned` when the caller configured one,
+ * otherwise the context's own (from the `Host` header, or a trusted
+ * proxy's `X-Forwarded-Host`), otherwise `http://localhost`.
+ */
+function resolveOrigin(context, pinned) {
+    for (const candidate of [pinned, context.origin, DEFAULT_ORIGIN]) {
+        if (candidate === undefined)
+            continue;
+        try {
+            return new URL(candidate).origin;
+        }
+        catch {
+            continue;
+        }
+    }
+    return DEFAULT_ORIGIN;
+}
+/**
+ * The context's URL as an absolute URL. The request target is never read
+ * as an authority; the origin is `origin` when given, else the context's.
+ */
+export function contextUrl(context, origin) {
+    const target = parseRequestTarget(context.url);
+    const url = new URL(resolveOrigin(context, origin));
+    url.pathname = target.pathname;
+    url.search = target.search;
+    return url;
+}
+function toBody(body, headers) {
+    if (body === undefined || body === null)
+        return undefined;
+    if (typeof body === "string")
+        return body;
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return body;
+    if (body instanceof ReadableStream ||
+        body instanceof Blob ||
+        body instanceof FormData ||
+        body instanceof URLSearchParams) {
+        return body;
+    }
+    if (!JSON_TYPE.test(headers.get("content-type") ?? "")) {
+        headers.set("content-type", "application/json");
+    }
+    return JSON.stringify(body);
+}
+/**
+ * Builds a web `Request` from a request context.
+ *
+ * Headers are copied except connection-scoped ones; the body is the one the
+ * adapter read (bytes, text, a stream, or a parsed value re-encoded as JSON,
+ * labelled `application/json` unless it already had a JSON content type)
+ * and is never attached to `GET` / `HEAD`; the signal aborts the request
+ * when the client disconnects.
+ */
+export function toWebRequest(context, options = {}) {
+    const method = context.method.toUpperCase();
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(context.headers)) {
+        if (!HOP_BY_HOP.has(name.toLowerCase()))
+            headers.append(name, value);
+    }
+    for (const [name, value] of Object.entries(options.headers ?? {})) {
+        headers.set(name, value);
+    }
+    const body = method === "GET" || method === "HEAD" ? undefined : toBody(context.body, headers);
+    const init = {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body }),
+        ...(body instanceof ReadableStream ? { duplex: "half" } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
+    return new Request(options.url ?? contextUrl(context, options.origin), init);
+}
+//# sourceMappingURL=httpFetchMount.request.js.map

package/dist/httpFetchMount/httpFetchMount.type.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Types for serving web-standard fetch handlers from a router.
+ */
+import type { HttpMethod, HttpRouteOpenAPI, RouteOptions, RouterHandler } from "../httpRouter/core/types/httpRouter.type.js";
+import type { HttpMiddleware } from "../httpMiddleware/httpMiddleware.type.js";
+/** A web-standard handler: `Request` in, `Response` out. */
+export type HttpFetchHandler = (request: Request) => Response | Promise<Response>;
+/** Anything routes can be registered on: an `HttpRouter` or a router group. */
+export interface HttpFetchMountTarget {
+    on(method: HttpMethod | "*", path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+}
+/** Options for `mountFetchHandler`. */
+export interface MountFetchHandlerOptions {
+    /** Methods routed to the handler. Default: every method. */
+    readonly methods?: readonly HttpMethod[];
+    /**
+     * Remove the mount path from the URL the handler sees, so a handler
+     * mounted at `/rpc` receives `/users.get` for `/rpc/users.get`. The
+     * removed prefix is passed as `x-forwarded-prefix`. Default: `true`.
+     */
+    readonly stripPrefix?: boolean;
+    /**
+     * Origin of the handler's `request.url`, e.g. `https://api.example.com`.
+     * When set it is used for every request. When not, the origin comes from
+     * the request — its `Host` header, or `X-Forwarded-Host` from a trusted
+     * proxy — which the client chooses; set this whenever the handler builds
+     * absolute URLs (redirects, callback or reset links) or checks
+     * `Origin` against its own. Falls back to `http://localhost`.
+     */
+    readonly origin?: string;
+    /** Middleware run before the handler. */
+    readonly middleware?: readonly HttpMiddleware[];
+    /** Route name. */
+    readonly name?: string;
+    /**
+     * OpenAPI documentation for the mount. Default: `false` — a mounted
+     * handler documents its own operations (see `@zudojs/openapi`'s
+     * `createOpenAPIDocumentFromRoutes`).
+     */
+    readonly openapi?: HttpRouteOpenAPI;
+}
+/** Options for `toWebRequest`. */
+export interface ToWebRequestOptions {
+    /** Overrides the request URL (absolute). */
+    readonly url?: string | URL;
+    /** Aborts the web request; normally the router context's signal. */
+    readonly signal?: AbortSignal;
+    /**
+     * Origin of the web request. Overrides the context's protocol and host
+     * (which come from the client's `Host` header) when set.
+     */
+    readonly origin?: string;
+    /** Extra headers set on the web request, replacing same-named ones. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=httpFetchMount.type.d.ts.map

package/dist/httpFetchMount/httpFetchMount.type.js

@@ -0,0 +1,5 @@
+/**
+ * Types for serving web-standard fetch handlers from a router.
+ */
+export {};
+//# sourceMappingURL=httpFetchMount.type.js.map

package/dist/httpFetchMount/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @zudojs/http/httpFetchMount
+ *
+ * Serves web-standard fetch handlers (`Request` → `Response`) from an
+ * `@zudojs/http` router: `mountFetchHandler` registers one under a path,
+ * `toWebRequest` converts a request context into a `Request` on its own.
+ */
+export { mountFetchHandler } from "./httpFetchMount.core.js";
+export { toWebRequest, contextUrl } from "./httpFetchMount.request.js";
+export type { HttpFetchHandler, HttpFetchMountTarget, MountFetchHandlerOptions, ToWebRequestOptions, } from "./httpFetchMount.type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpFetchMount/index.js

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/http/httpFetchMount
+ *
+ * Serves web-standard fetch handlers (`Request` → `Response`) from an
+ * `@zudojs/http` router: `mountFetchHandler` registers one under a path,
+ * `toWebRequest` converts a request context into a `Request` on its own.
+ */
+export { mountFetchHandler } from "./httpFetchMount.core.js";
+export { toWebRequest, contextUrl } from "./httpFetchMount.request.js";
+//# sourceMappingURL=index.js.map

package/dist/httpMiddleware/builtin/rateLimit/httpMiddleware.rateLimit.d.ts

@@ -39,9 +39,12 @@ export type RateLimitMiddlewareOptions = RateLimiterOptions | {
     readonly limiter: HttpRateLimiter;
 };
 /**
- * Creates middleware that answers `429 Too Many Requests` (with
- * `Retry-After`, from the `@zudojs/security` handler) once a client exceeds
- * its allowance, and otherwise passes the request on.
+ * Creates middleware that answers `429 Too Many Requests` once a client
+ * exceeds its allowance, and otherwise passes the request on. The 429 has a
+ * JSON body (`{"error":{"code":"RATE_LIMIT_EXCEEDED",...}}`) sent as
+ * `application/json`, and always a `Retry-After` header (the
+ * `@zudojs/security` handler's, or one computed from the limiter's reset
+ * time when a custom handler leaves it out).
  */
 export declare function createRateLimitMiddleware(options: RateLimitMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.rateLimit.d.ts.map

package/dist/httpMiddleware/builtin/rateLimit/httpMiddleware.rateLimit.js

@@ -18,7 +18,7 @@
  *
  * @module httpMiddleware/builtin/rateLimit
  */
-import { createRateLimiter, parseClientIp, } from "@zudojs/security";
+import { createRateLimiter, parseClientIp, retryAfterSeconds, } from "@zudojs/security";
 import { createResponseContext } from "../../../httpResponse/httpResponse.context.js";
 /**
  * The `ip` given to the limiter for a request whose `remoteAddress` is
@@ -27,9 +27,12 @@ import { createResponseContext } from "../../../httpResponse/httpResponse.contex
  */
 export const UNKNOWN_CLIENT_RATE_LIMIT_IP = "0.0.0.0";
 /**
- * Creates middleware that answers `429 Too Many Requests` (with
- * `Retry-After`, from the `@zudojs/security` handler) once a client exceeds
- * its allowance, and otherwise passes the request on.
+ * Creates middleware that answers `429 Too Many Requests` once a client
+ * exceeds its allowance, and otherwise passes the request on. The 429 has a
+ * JSON body (`{"error":{"code":"RATE_LIMIT_EXCEEDED",...}}`) sent as
+ * `application/json`, and always a `Retry-After` header (the
+ * `@zudojs/security` handler's, or one computed from the limiter's reset
+ * time when a custom handler leaves it out).
  */
 export function createRateLimitMiddleware(options) {
     const limiter = "limiter" in options ? options.limiter : createRateLimiter(options);
@@ -42,16 +45,41 @@ export function createRateLimitMiddleware(options) {
             headers: request.headers,
         };
         const rejection = { statusCode: 429, headers: {} };
-        if (limiter.middleware(limitRequest, rejection).allowed) {
+        const decision = limiter.middleware(limitRequest, rejection);
+        if (decision.allowed) {
             return next();
         }
         const response = createResponseContext().setStatus(rejection.statusCode);
         for (const [name, value] of Object.entries(rejection.headers)) {
             response.setHeader(name.toLowerCase(), value);
         }
-        return response.setBody(rejection.body ?? "Too Many Requests");
+        if (response.headers["retry-after"] === undefined) {
+            response.setHeader("retry-after", String(retryAfterSeconds(decision)));
+        }
+        const body = rejection.body ?? DEFAULT_REJECTION_BODY;
+        /*
+         * The limiter's body is JSON, but it went out as a bare string, which the
+         * writer labels `text/plain`. A handler's own content type is kept.
+         */
+        if (response.headers["content-type"] === undefined) {
+            response.setHeader("content-type", isJson(body) ? "application/json; charset=utf-8" : "text/plain; charset=utf-8");
+        }
+        return response.setBody(body);
     };
 }
+/** Body sent when a custom limiter handler supplies none. */
+const DEFAULT_REJECTION_BODY = JSON.stringify({
+    error: { code: "RATE_LIMIT_EXCEEDED", message: "Too Many Requests" },
+});
+function isJson(body) {
+    try {
+        JSON.parse(body);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function clientIpOf(remoteAddress) {
     return typeof remoteAddress === "string" &&
         parseClientIp(remoteAddress) !== undefined

package/dist/httpMiddleware/httpMiddleware.type.d.ts

@@ -3,9 +3,17 @@
  *
  * @module httpMiddleware/types
  */
+import type { GuardResponse } from "@zudojs/middleware";
 import type { HttpRequestContext as RequestContext } from "../httpRequest/httpRequest.context.js";
 import type { HttpResponseContext as ResponseContext } from "../httpResponse/httpResponse.context.js";
-export type HttpMiddlewareResult = void | Response | RequestContext | ResponseContext | Promise<void | Response | RequestContext | ResponseContext>;
+/**
+ * What a middleware may return.
+ *
+ * A `GuardResponse` (from `createGuardResponse` in `@zudojs/middleware`) is
+ * sent with its own status, headers and body; it is how a guard in a
+ * lower-tier package, which cannot import this one, answers 401/403/404.
+ */
+export type HttpMiddlewareResult = void | Response | RequestContext | ResponseContext | GuardResponse | Promise<void | Response | RequestContext | ResponseContext | GuardResponse>;
 export type HttpNext = () => Promise<ResponseContext>;
 export type HttpMiddleware = (context: HttpMiddlewareContext, next: HttpNext) => HttpMiddlewareResult;
 export interface HttpMiddlewareContext {

package/dist/httpMiddleware/pipeline/httpPipeline.execution.js

@@ -3,7 +3,7 @@
  *
  * @module httpMiddleware/pipeline/execution
  */
-import { HttpMiddlewareError, HttpMiddlewarePipelineError, } from "../httpMiddleware.error.js";
+import { HttpMiddlewareError } from "../httpMiddleware.error.js";
 import { normalizeResult } from "./httpPipeline.helper.js";
 import { list } from "./httpPipeline.registration.js";
 export async function executePipeline(entries, request, response, options = {}, pipelineOptions) {
@@ -42,56 +42,33 @@ export async function executePipeline(entries, request, response, options = {},
             }
             return dispatch(index + 1);
         };
-        try {
-            const result = await entry.middleware(context, next);
-            return normalizeResult(result, response);
-        }
-        catch (error) {
-            /*
-             * Rethrow rather than returning the untouched response. Swallowing here
-             * let an inner failure resume the *outer* frames, so middleware that
-             * runs after `await next()` — access logging, CORS and security header
-             * emission, audit commits — executed against a response that was about
-             * to be discarded, and recorded the request as a success.
-             */
-            throw error instanceof HttpMiddlewareError
-                ? error
-                : new HttpMiddlewareError(`Middleware "${entry.name}" threw an error.`, {
-                    middlewareId: entry.id,
-                    middlewareName: entry.name,
-                    cause: error,
-                });
-        }
+        /*
+         * A failure propagates as the error that was thrown, never a wrapper and
+         * never swallowed. An outer middleware's `await next()` rejects with it,
+         * so code after `await next()` does not run unless that middleware
+         * catches it (`try/catch`, `try/finally`), and `instanceof NotFoundError`
+         * works there and in the server's `errorHandler`. It used to be wrapped
+         * in `HttpMiddlewareError` here and `HttpMiddlewarePipelineError` below,
+         * which hid the original in `cause` / `errors[0].cause`.
+         */
+        const result = await entry.middleware(context, next);
+        return normalizeResult(result, response);
     };
     try {
         return await dispatch(0);
     }
     catch (error) {
-        const middlewareError = error instanceof HttpMiddlewareError
-            ? error
-            : new HttpMiddlewareError("HTTP middleware pipeline failed.", {
-                cause: error,
-            });
-        if (pipelineOptions.onError) {
-            try {
-                /*
-                 * A successful `onError` is a genuine recovery and must be returned.
-                 * Previously every caught error was recorded before `onError` ran and
-                 * the recorded list was rethrown afterwards, so the handler's result
-                 * was always discarded and the option could never take effect.
-                 */
-                const errorResult = await pipelineOptions.onError(middlewareError.cause ?? error, context);
-                return normalizeResult(errorResult, response);
-            }
-            catch (handlerError) {
-                /* The handler's own failure is reported, not swallowed. */
-                throw new HttpMiddlewarePipelineError([
-                    middlewareError,
-                    new HttpMiddlewareError("HTTP middleware error handler threw an error.", { cause: handlerError }),
-                ]);
-            }
+        if (!pipelineOptions.onError) {
+            throw error;
         }
-        throw new HttpMiddlewarePipelineError([middlewareError]);
+        /*
+         * A successful `onError` is a genuine recovery and is returned. If the
+         * handler throws, what it threw propagates: rethrowing the error it was
+         * given passes that original on, and throwing a translated error (a
+         * `NotFoundError` for a missing row) replaces it.
+         */
+        const errorResult = await pipelineOptions.onError(error, context);
+        return normalizeResult(errorResult, response);
     }
 }
 //# sourceMappingURL=httpPipeline.execution.js.map

package/dist/httpMiddleware/pipeline/httpPipeline.guardResponse.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Turns a `@zudojs/middleware` guard response into a real response.
+ *
+ * A middleware that refuses a request — the permissions `authorize()` guard,
+ * the tenancy resolver — returns `createGuardResponse({ status, body })`.
+ * Route middleware used to ignore any returned object that was not an
+ * `HttpResponseContext`, so a plain `{ status: 403, body, headers }` reached
+ * the client as `200`: the handler did not run, but clients, caches and
+ * monitoring saw a success. Only the branded object is honoured; an unbranded
+ * object keeps its previous meaning, so data that happens to carry a
+ * `status` key is never read as a response.
+ *
+ * @module httpMiddleware/pipeline/guardResponse
+ */
+import type { GuardResponse } from "@zudojs/middleware";
+import { HttpResponseContext } from "../../httpResponse/httpResponse.context.js";
+/**
+ * Writes a guard response's status, headers and body onto `target`.
+ *
+ * Headers already on `target` (set by an outer middleware before it called
+ * `next()`, such as CORS) are kept unless the guard response overrides them.
+ *
+ * @param target - The response that stays authoritative.
+ * @param guard - The guard response to apply.
+ * @returns `target`.
+ * @throws {TypeError} If a header value contains a control character.
+ */
+export declare function applyGuardResponse(target: HttpResponseContext, guard: GuardResponse): HttpResponseContext;
+/**
+ * Builds a fresh response context from a guard response.
+ *
+ * @param guard - The guard response to convert.
+ * @returns A new response context.
+ */
+export declare function guardResponseToContext(guard: GuardResponse): HttpResponseContext;
+//# sourceMappingURL=httpPipeline.guardResponse.d.ts.map

package/dist/httpMiddleware/pipeline/httpPipeline.guardResponse.js

@@ -0,0 +1,57 @@
+/**
+ * Turns a `@zudojs/middleware` guard response into a real response.
+ *
+ * A middleware that refuses a request — the permissions `authorize()` guard,
+ * the tenancy resolver — returns `createGuardResponse({ status, body })`.
+ * Route middleware used to ignore any returned object that was not an
+ * `HttpResponseContext`, so a plain `{ status: 403, body, headers }` reached
+ * the client as `200`: the handler did not run, but clients, caches and
+ * monitoring saw a success. Only the branded object is honoured; an unbranded
+ * object keeps its previous meaning, so data that happens to carry a
+ * `status` key is never read as a response.
+ *
+ * @module httpMiddleware/pipeline/guardResponse
+ */
+import { HttpResponseContext } from "../../httpResponse/httpResponse.context.js";
+import { isValidHeaderFieldValue } from "../../httpHeaders/security/index.js";
+/**
+ * Writes a guard response's status, headers and body onto `target`.
+ *
+ * Headers already on `target` (set by an outer middleware before it called
+ * `next()`, such as CORS) are kept unless the guard response overrides them.
+ *
+ * @param target - The response that stays authoritative.
+ * @param guard - The guard response to apply.
+ * @returns `target`.
+ * @throws {TypeError} If a header value contains a control character.
+ */
+export function applyGuardResponse(target, guard) {
+    target.setStatus(guard.status);
+    const body = guard.body;
+    if (body === undefined) {
+        target.setBody(undefined);
+    }
+    else if (typeof body === "string" || body instanceof Uint8Array) {
+        target.setBody(body);
+    }
+    else {
+        target.json(body);
+    }
+    for (const [name, value] of Object.entries(guard.headers)) {
+        if (!isValidHeaderFieldValue(value)) {
+            throw new TypeError(`Invalid value for response header "${name}": it contains a control character or surrounding whitespace.`);
+        }
+        target.setHeader(name, value);
+    }
+    return target;
+}
+/**
+ * Builds a fresh response context from a guard response.
+ *
+ * @param guard - The guard response to convert.
+ * @returns A new response context.
+ */
+export function guardResponseToContext(guard) {
+    return applyGuardResponse(new HttpResponseContext(), guard);
+}
+//# sourceMappingURL=httpPipeline.guardResponse.js.map

package/dist/httpMiddleware/pipeline/httpPipeline.helper.d.ts

@@ -3,6 +3,7 @@
  *
  * @module httpMiddleware/pipeline/helpers
  */
+import { type GuardResponse } from "@zudojs/middleware";
 import type { HttpMiddlewareContext, RegisteredMiddleware } from "../httpMiddleware.type.js";
 import { HttpRequestContext as RequestContext } from "../../httpRequest/httpRequest.context.js";
 import { HttpResponseContext as ResponseContext } from "../../httpResponse/httpResponse.context.js";
@@ -20,7 +21,7 @@ export declare function nextResult(context: HttpMiddlewareContext, dispatch: (in
  * @returns The response context to continue the pipeline with.
  * @throws {HttpMiddlewareError} If no response context can be determined.
  */
-export declare function normalizeResult(result: void | Response | RequestContext | ResponseContext | undefined, fallback?: ResponseContext): ResponseContext;
+export declare function normalizeResult(result: void | Response | RequestContext | ResponseContext | GuardResponse | undefined, fallback?: ResponseContext): ResponseContext;
 /**
  * Narrows a value to a response context.
  *

package/dist/httpMiddleware/pipeline/httpPipeline.helper.js

@@ -3,10 +3,12 @@
  *
  * @module httpMiddleware/pipeline/helpers
  */
+import { isGuardResponse } from "@zudojs/middleware";
 import { HttpRequestContext as RequestContext } from "../../httpRequest/httpRequest.context.js";
 import { HttpResponseContext as ResponseContext } from "../../httpResponse/httpResponse.context.js";
 import { isWebResponse, webResponseToContext, } from "../../httpResponse/httpResponse.fromWeb.js";
 import { HttpMiddlewareError } from "../httpMiddleware.error.js";
+import { guardResponseToContext } from "./httpPipeline.guardResponse.js";
 export async function nextResult(context, dispatch, index) {
     return dispatch(index + 1);
 }
@@ -24,6 +26,14 @@ export async function nextResult(context, dispatch, index) {
  * @throws {HttpMiddlewareError} If no response context can be determined.
  */
 export function normalizeResult(result, fallback) {
+    /*
+     * A guard response is checked before the structural `isResponseContext`
+     * test, which would otherwise pass the frozen plain object through as if it
+     * were a response context.
+     */
+    if (isGuardResponse(result)) {
+        return guardResponseToContext(result);
+    }
     /*
      * The `Response` check must come first. `isResponseContext` tests for a
      * `headers` property, and `headers` is a getter on `Response.prototype`, so

package/dist/httpMiddleware/pipeline/index.d.ts

@@ -5,6 +5,7 @@
  */
 export * from "./httpMiddleware.pipeline.js";
 export * from "./httpPipeline.execution.js";
+export * from "./httpPipeline.guardResponse.js";
 export * from "./httpPipeline.helper.js";
 export * from "./httpPipeline.registration.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/pipeline/index.js

@@ -5,6 +5,7 @@
  */
 export * from "./httpMiddleware.pipeline.js";
 export * from "./httpPipeline.execution.js";
+export * from "./httpPipeline.guardResponse.js";
 export * from "./httpPipeline.helper.js";
 export * from "./httpPipeline.registration.js";
 //# sourceMappingURL=index.js.map