@zudojs/http 0.1.0 → 1.1.0

package/dist/httpMiddleware/builtin/conditional/httpMiddleware.conditional.js

@@ -0,0 +1,70 @@
+/**
+ * Conditional, path, method, and response middleware factories.
+ *
+ * @module httpMiddleware/builtin/conditional
+ */
+import { getRequestMethod, getRequestUrl, extractPathname, } from "../helpers/index.js";
+import { isWebResponse, bufferWebResponse, } from "../../../httpResponse/httpResponse.fromWeb.js";
+export function createAsyncMiddleware(factory) {
+    return async (context, next) => {
+        const middleware = await factory(context);
+        return middleware(context, next);
+    };
+}
+export function createConditionalMiddleware(predicate, middleware) {
+    return async (context, next) => {
+        if (await predicate(context)) {
+            return middleware(context, next);
+        }
+        return next();
+    };
+}
+export function createPathMiddleware(path, middleware) {
+    const targetPath = extractPathname(path);
+    return createConditionalMiddleware((context) => {
+        const url = getRequestUrl(context.request);
+        const pathname = extractPathname(url);
+        return pathname === targetPath;
+    }, middleware);
+}
+export function createMethodMiddleware(method, middleware) {
+    const targetMethod = method.toUpperCase();
+    return createConditionalMiddleware((context) => {
+        const requestMethod = getRequestMethod(context.request);
+        return requestMethod === targetMethod;
+    }, middleware);
+}
+/**
+ * Builds a resolver that yields a fresh response context per request.
+ *
+ * A `Response` handed to one of these factories is a *single value reused for
+ * every request*, and its body is a one-shot `ReadableStream`. Streaming it
+ * straight through would serve the body once and hand the second request a
+ * disturbed stream, so the body is read into memory once, on first use, and
+ * each request receives a clone of the resulting context. Cloning also keeps
+ * one request's mutations away from the next.
+ */
+function createResponseResolver(response) {
+    if (!isWebResponse(response)) {
+        return async () => response.clone();
+    }
+    let buffered;
+    return async () => {
+        buffered ??= bufferWebResponse(response);
+        return (await buffered).clone();
+    };
+}
+export function createResponseMiddleware(response) {
+    const resolve = createResponseResolver(response);
+    return async () => resolve();
+}
+export function createShortCircuitMiddleware(predicate, response) {
+    const resolve = createResponseResolver(response);
+    return async (context, next) => {
+        if (await predicate(context)) {
+            return resolve();
+        }
+        return next();
+    };
+}
+//# sourceMappingURL=httpMiddleware.conditional.js.map

package/dist/httpMiddleware/builtin/conditional/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Conditional middleware barrel.
+ *
+ * @module httpMiddleware/builtin/conditional
+ */
+export { createAsyncMiddleware, createConditionalMiddleware, createPathMiddleware, createMethodMiddleware, createResponseMiddleware, createShortCircuitMiddleware, } from "./httpMiddleware.conditional.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/builtin/conditional/index.js

@@ -0,0 +1,7 @@
+/**
+ * Conditional middleware barrel.
+ *
+ * @module httpMiddleware/builtin/conditional
+ */
+export { createAsyncMiddleware, createConditionalMiddleware, createPathMiddleware, createMethodMiddleware, createResponseMiddleware, createShortCircuitMiddleware, } from "./httpMiddleware.conditional.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,28 @@
+/**
+ * CORS middleware factory.
+ *
+ * @module httpMiddleware/builtin/cors
+ */
+import type { HttpMiddleware, HttpMiddlewareContext } from "../../httpMiddleware.type.js";
+export interface CorsMiddlewareOptions {
+    /**
+     * The allowed origin(s).
+     *
+     * - a string: an exact origin, or `"*"` for any origin (rejected when
+     *   `credentials` is true).
+     * - an array: the set of exact origins that are allowed.
+     * - a function: called with the request origin; return `true` to allow it.
+     */
+    readonly allowOrigin?: string | readonly string[] | ((origin: string, context: HttpMiddlewareContext) => boolean);
+    readonly allowMethods?: string;
+    readonly allowHeaders?: string;
+    readonly exposeHeaders?: string;
+    readonly credentials?: boolean;
+    readonly maxAge?: number;
+    /**
+     * Status used to answer a preflight request. Defaults to 204.
+     */
+    readonly optionsSuccessStatus?: number;
+}
+export declare function createCorsMiddleware(options?: CorsMiddlewareOptions): HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.cors.d.ts.map

package/dist/httpMiddleware/builtin/cors/httpMiddleware.cors.js

@@ -0,0 +1,120 @@
+/**
+ * CORS middleware factory.
+ *
+ * @module httpMiddleware/builtin/cors
+ */
+import { applyHeadersToResponse } from "../helpers/index.js";
+function getRequestHeader(context, name) {
+    const headers = context.request.headers;
+    const value = headers?.[name];
+    return Array.isArray(value) ? value[0] : value;
+}
+function getRequestMethod(context) {
+    return (context.request.method ?? "GET").toUpperCase();
+}
+/**
+ * Decides whether an origin is allowed.
+ *
+ * The previous implementation ignored the request origin entirely and wrote
+ * `Access-Control-Allow-Origin: *` on every response, so the documented
+ * "reflect the origin" pattern allowed every origin on the internet.
+ */
+function resolveAllowedOrigin(origin, context, options) {
+    const configured = options.allowOrigin ?? "*";
+    if (typeof configured === "function") {
+        return configured(origin, context) ? origin : undefined;
+    }
+    const list = typeof configured === "string" ? [configured] : configured;
+    if (list.includes("*")) {
+        if (options.credentials) {
+            /*
+             * A wildcard origin with credentials is forbidden by the spec, and
+             * reflecting the request origin instead would authorise every origin
+             * to read authenticated responses.
+             */
+            throw new TypeError("CORS: a wildcard allowOrigin cannot be combined with credentials.");
+        }
+        return "*";
+    }
+    return list.includes(origin) ? origin : undefined;
+}
+function appendVary(headers, value) {
+    const existing = headers.get("vary");
+    if (!existing) {
+        headers.set("vary", value);
+        return;
+    }
+    const present = existing
+        .split(",")
+        .map((entry) => entry.trim().toLowerCase());
+    if (!present.includes(value.toLowerCase())) {
+        headers.set("vary", `${existing}, ${value}`);
+    }
+}
+export function createCorsMiddleware(options = {}) {
+    return async (context, next) => {
+        const origin = getRequestHeader(context, "origin");
+        /*
+         * A request without an Origin is not a CORS request. Emitting
+         * Access-Control-* on it pollutes shared caches for no benefit.
+         */
+        if (!origin) {
+            return next();
+        }
+        const allowed = resolveAllowedOrigin(origin, context, options);
+        const isPreflight = getRequestMethod(context) === "OPTIONS" &&
+            getRequestHeader(context, "access-control-request-method") !== undefined;
+        const applyHeaders = (headers) => {
+            /*
+             * `Vary: Origin` is mandatory whenever the response depends on the
+             * request Origin. Without it a shared cache stores one origin's
+             * Access-Control-Allow-Origin and serves it to everybody.
+             */
+            appendVary(headers, "Origin");
+            if (isPreflight) {
+                appendVary(headers, "Access-Control-Request-Method");
+                appendVary(headers, "Access-Control-Request-Headers");
+            }
+            if (allowed === undefined) {
+                return;
+            }
+            headers.set("access-control-allow-origin", allowed);
+            if (options.credentials) {
+                headers.set("access-control-allow-credentials", "true");
+            }
+            if (options.exposeHeaders) {
+                headers.set("access-control-expose-headers", options.exposeHeaders);
+            }
+            if (!isPreflight) {
+                return;
+            }
+            if (options.allowMethods) {
+                headers.set("access-control-allow-methods", options.allowMethods);
+            }
+            const requestedHeaders = options.allowHeaders ??
+                getRequestHeader(context, "access-control-request-headers");
+            if (requestedHeaders) {
+                headers.set("access-control-allow-headers", requestedHeaders);
+            }
+            if (options.maxAge !== undefined) {
+                headers.set("access-control-max-age", String(options.maxAge));
+            }
+        };
+        if (isPreflight) {
+            /*
+             * Preflights are answered here. Previously OPTIONS fell through to the
+             * router, which returned a 404/405, so every legitimate cross-origin
+             * call with a preflight failed.
+             */
+            const headers = new Headers();
+            applyHeaders(headers);
+            headers.set("content-length", "0");
+            return applyHeadersToResponse(undefined, headers, options.optionsSuccessStatus ?? 204);
+        }
+        const response = await next();
+        const headers = new Headers(response.headers);
+        applyHeaders(headers);
+        return applyHeadersToResponse(response, headers);
+    };
+}
+//# sourceMappingURL=httpMiddleware.cors.js.map

package/dist/httpMiddleware/builtin/cors/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CORS middleware barrel.
+ *
+ * @module httpMiddleware/builtin/cors
+ */
+export { createCorsMiddleware, type CorsMiddlewareOptions, } from "./httpMiddleware.cors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/builtin/cors/index.js

@@ -0,0 +1,7 @@
+/**
+ * CORS middleware barrel.
+ *
+ * @module httpMiddleware/builtin/cors
+ */
+export { createCorsMiddleware, } from "./httpMiddleware.cors.js";
+//# sourceMappingURL=index.js.map

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.accessor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Request/response accessor helpers for builtin middleware.
+ *
+ * @module httpMiddleware/builtin/helpers/accessors
+ */
+import type { HttpRequestContext as RequestContext } from "../../../httpRequest/httpRequest.context.js";
+import type { HttpResponseContext as ResponseContext } from "../../../httpResponse/httpResponse.context.js";
+export declare function getRequestMethod(request: RequestContext): string;
+export declare function getRequestUrl(request: RequestContext): string;
+export declare function getRequestHeaders(request: RequestContext): Record<string, string>;
+export declare function getResponseStatus(response: ResponseContext): number;
+export declare function getContextSignal(request: RequestContext): AbortSignal | undefined;
+export declare function extractPathname(value: string): string;
+export declare function performanceNow(): number;
+export declare function createNeverAbortedSignal(): AbortSignal;
+//# sourceMappingURL=httpMiddleware.accessor.d.ts.map

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.contextHelper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Context creation helpers for builtin middleware.
+ *
+ * @module httpMiddleware/builtin/helpers/context
+ */
+import type { HttpMiddlewareContext, HttpMiddlewareState } from "../../httpMiddleware.type.js";
+import type { HttpRequestContext as RequestContext } from "../../../httpRequest/httpRequest.context.js";
+import type { HttpResponseContext as ResponseContext } from "../../../httpResponse/httpResponse.context.js";
+import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+export declare function createMiddlewareContext(request: RequestContext, response: ResponseContext, options?: {
+    readonly state?: HttpMiddlewareState;
+    readonly signal?: AbortSignal;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}): HttpMiddlewareContext;
+export declare function isHttpMiddleware(value: unknown): value is HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.contextHelper.d.ts.map

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.contextHelper.js

@@ -0,0 +1,23 @@
+/**
+ * Context creation helpers for builtin middleware.
+ *
+ * @module httpMiddleware/builtin/helpers/context
+ */
+import { getContextSignal, createNeverAbortedSignal, } from "./httpMiddleware.accessor.js";
+export function createMiddlewareContext(request, response, options = {}) {
+    const state = options.state ?? new Map();
+    const signal = options.signal ?? getContextSignal(request);
+    return {
+        request,
+        response,
+        state,
+        signal: signal ?? createNeverAbortedSignal(),
+        metadata: Object.freeze({
+            ...(options.metadata ?? {}),
+        }),
+    };
+}
+export function isHttpMiddleware(value) {
+    return typeof value === "function";
+}
+//# sourceMappingURL=httpMiddleware.contextHelper.js.map

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.response.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Response helpers for the built-in middleware.
+ *
+ * @module httpMiddleware/builtin/helpers/response
+ *
+ * Every built-in middleware used to return `{ ...response, headers } as unknown
+ * as ResponseContext`. `HttpResponseContext` keeps its state in private
+ * `_`-prefixed instance fields and exposes it through prototype getters, so
+ * spreading an instance yields a plain object carrying `_status`, `_body` and
+ * friends, with every getter lost. The adapter then read `.status` and `.body`
+ * as `undefined` — the response's status and body were dropped for every
+ * request that passed through a built-in middleware. The double cast is what
+ * let it compile.
+ *
+ * These helpers keep the class instance intact instead.
+ */
+import { HttpResponseContext } from "../../../httpResponse/httpResponse.context.js";
+/**
+ * Returns a copy of `response` carrying the supplied headers.
+ *
+ * The original is left untouched, so a middleware cannot mutate a response an
+ * outer middleware still holds.
+ *
+ * @param response - The response returned by the next middleware.
+ * @param headers - Header names mapped to values, applied over the existing set.
+ * @returns A new context with the headers applied.
+ * @throws {TypeError} If a header value contains a control character.
+ */
+export declare function withResponseHeaders(response: HttpResponseContext, headers: Readonly<Record<string, string>>): HttpResponseContext;
+/**
+ * Builds a fresh response context, for middleware that answers without calling
+ * `next()` — a CORS preflight, for instance.
+ *
+ * @param status - HTTP status code.
+ * @param headers - Header names mapped to values.
+ * @returns A new context.
+ * @throws {TypeError} If a header value contains a control character.
+ */
+export declare function createMiddlewareResponse(status: number, headers: Readonly<Record<string, string>>): HttpResponseContext;
+/**
+ * Copies a `Headers` accumulator onto a response context.
+ *
+ * Middleware that needs `Headers` semantics while building its result — CORS
+ * appends to `Vary` rather than overwriting it — can accumulate there and hand
+ * the result here. `set-cookie` is transferred through `getSetCookie()` so
+ * multiple cookies stay separate values; iterating `Headers` alone would join
+ * them into one comma-separated string, which is invalid for that header.
+ *
+ * @param response - Context to copy onto, or `undefined` to build a fresh one.
+ * @param headers - Accumulated headers.
+ * @param status - Status for the fresh context; ignored when `response` is given.
+ * @returns A new context carrying the accumulated headers.
+ */
+export declare function applyHeadersToResponse(response: HttpResponseContext | undefined, headers: Headers, status?: number): HttpResponseContext;
+//# sourceMappingURL=httpMiddleware.response.d.ts.map

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.response.js

@@ -0,0 +1,92 @@
+/**
+ * Response helpers for the built-in middleware.
+ *
+ * @module httpMiddleware/builtin/helpers/response
+ *
+ * Every built-in middleware used to return `{ ...response, headers } as unknown
+ * as ResponseContext`. `HttpResponseContext` keeps its state in private
+ * `_`-prefixed instance fields and exposes it through prototype getters, so
+ * spreading an instance yields a plain object carrying `_status`, `_body` and
+ * friends, with every getter lost. The adapter then read `.status` and `.body`
+ * as `undefined` — the response's status and body were dropped for every
+ * request that passed through a built-in middleware. The double cast is what
+ * let it compile.
+ *
+ * These helpers keep the class instance intact instead.
+ */
+import { HttpResponseContext } from "../../../httpResponse/httpResponse.context.js";
+import { isValidHeaderFieldValue } from "../../../httpHeaders/security/index.js";
+/**
+ * Returns a copy of `response` carrying the supplied headers.
+ *
+ * The original is left untouched, so a middleware cannot mutate a response an
+ * outer middleware still holds.
+ *
+ * @param response - The response returned by the next middleware.
+ * @param headers - Header names mapped to values, applied over the existing set.
+ * @returns A new context with the headers applied.
+ * @throws {TypeError} If a header value contains a control character.
+ */
+export function withResponseHeaders(response, headers) {
+    const next = response.clone();
+    for (const [name, value] of Object.entries(headers)) {
+        // A CR/LF or control character reaching a response header is a
+        // response-splitting primitive; refuse rather than emit it.
+        if (!isValidHeaderFieldValue(value)) {
+            throw new TypeError(`Invalid value for response header "${name}": it contains a control character or surrounding whitespace.`);
+        }
+        next.setHeader(name, value);
+    }
+    return next;
+}
+/**
+ * Builds a fresh response context, for middleware that answers without calling
+ * `next()` — a CORS preflight, for instance.
+ *
+ * @param status - HTTP status code.
+ * @param headers - Header names mapped to values.
+ * @returns A new context.
+ * @throws {TypeError} If a header value contains a control character.
+ */
+export function createMiddlewareResponse(status, headers) {
+    const response = new HttpResponseContext({ status });
+    for (const [name, value] of Object.entries(headers)) {
+        if (!isValidHeaderFieldValue(value)) {
+            throw new TypeError(`Invalid value for response header "${name}": it contains a control character or surrounding whitespace.`);
+        }
+        response.setHeader(name, value);
+    }
+    return response;
+}
+/**
+ * Copies a `Headers` accumulator onto a response context.
+ *
+ * Middleware that needs `Headers` semantics while building its result — CORS
+ * appends to `Vary` rather than overwriting it — can accumulate there and hand
+ * the result here. `set-cookie` is transferred through `getSetCookie()` so
+ * multiple cookies stay separate values; iterating `Headers` alone would join
+ * them into one comma-separated string, which is invalid for that header.
+ *
+ * @param response - Context to copy onto, or `undefined` to build a fresh one.
+ * @param headers - Accumulated headers.
+ * @param status - Status for the fresh context; ignored when `response` is given.
+ * @returns A new context carrying the accumulated headers.
+ */
+export function applyHeadersToResponse(response, headers, status = 204) {
+    const next = response ? response.clone() : new HttpResponseContext({ status });
+    const setCookies = typeof headers.getSetCookie === "function" ? headers.getSetCookie() : [];
+    for (const [name, value] of headers.entries()) {
+        if (name.toLowerCase() === "set-cookie") {
+            continue;
+        }
+        if (!isValidHeaderFieldValue(value)) {
+            throw new TypeError(`Invalid value for response header "${name}": it contains a control character or surrounding whitespace.`);
+        }
+        next.setHeader(name, value);
+    }
+    if (setCookies.length > 0) {
+        next.header("set-cookie", setCookies);
+    }
+    return next;
+}
+//# sourceMappingURL=httpMiddleware.response.js.map

package/dist/httpMiddleware/builtin/helpers/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal helper functions barrel.
+ *
+ * @module httpMiddleware/builtin/helpers
+ */
+export * from "./httpMiddleware.contextHelper.js";
+export * from "./httpMiddleware.accessor.js";
+export * from "./httpMiddleware.response.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/builtin/helpers/index.js

@@ -0,0 +1,9 @@
+/**
+ * Internal helper functions barrel.
+ *
+ * @module httpMiddleware/builtin/helpers
+ */
+export * from "./httpMiddleware.contextHelper.js";
+export * from "./httpMiddleware.accessor.js";
+export * from "./httpMiddleware.response.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Image compression middleware using Sharp.
+ *
+ * @module httpMiddleware/builtin/image
+ *
+ * Requires: npm install sharp
+ */
+import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+export interface ImageCompressionOptions {
+    readonly quality?: number;
+    readonly format?: "jpeg" | "png" | "webp" | "avif";
+    readonly width?: number;
+    readonly height?: number;
+    readonly fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+}
+export interface ImageCompressionMiddlewareOptions {
+    readonly enabled?: boolean;
+    readonly defaultQuality?: number;
+    readonly defaultFormat?: "jpeg" | "png" | "webp" | "avif";
+    readonly maxWidth?: number;
+    readonly maxHeight?: number;
+    readonly contentTypeMap?: Record<string, ImageCompressionOptions>;
+}
+export declare function compressImage(buffer: Buffer, options?: ImageCompressionOptions): Promise<Buffer>;
+export declare function createImageCompressionMiddleware(options?: ImageCompressionMiddlewareOptions): HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.image.d.ts.map

package/dist/httpMiddleware/builtin/image/httpMiddleware.image.js

@@ -0,0 +1,90 @@
+/**
+ * Image compression middleware using Sharp.
+ *
+ * @module httpMiddleware/builtin/image
+ *
+ * Requires: npm install sharp
+ */
+import { applyHeadersToResponse } from "../helpers/index.js";
+const DEFAULT_QUALITY = 80;
+const DEFAULT_FORMAT = "jpeg";
+async function getSharp() {
+    try {
+        const mod = await import("sharp");
+        return mod.default ?? mod;
+    }
+    catch {
+        throw new Error("Sharp is not installed. Run: npm install sharp");
+    }
+}
+export async function compressImage(buffer, options = {}) {
+    const sharpInstance = await getSharp();
+    const quality = options.quality ?? DEFAULT_QUALITY;
+    const format = options.format ?? DEFAULT_FORMAT;
+    let pipeline = sharpInstance(buffer);
+    if (options.width || options.height) {
+        pipeline = pipeline.resize({
+            width: options.width,
+            height: options.height,
+            fit: options.fit ?? "inside",
+            withoutEnlargement: true,
+        });
+    }
+    switch (format) {
+        case "jpeg":
+            return pipeline.jpeg({ quality }).toBuffer();
+        case "png":
+            return pipeline.png({ quality }).toBuffer();
+        case "webp":
+            return pipeline.webp({ quality }).toBuffer();
+        case "avif":
+            return pipeline.avif({ quality }).toBuffer();
+        default:
+            return pipeline.toBuffer();
+    }
+}
+export function createImageCompressionMiddleware(options = {}) {
+    const enabled = options.enabled ?? true;
+    const defaultQuality = options.defaultQuality ?? DEFAULT_QUALITY;
+    const defaultFormat = options.defaultFormat ?? DEFAULT_FORMAT;
+    const contentTypeMap = options.contentTypeMap ?? {};
+    return async (context, next) => {
+        if (!enabled) {
+            return next();
+        }
+        const response = await next();
+        const contentType = context.response.headers["content-type"];
+        if (!contentType || !contentType.startsWith("image/")) {
+            return response;
+        }
+        const body = context.response.body;
+        if (!Buffer.isBuffer(body) && typeof body !== "string") {
+            return response;
+        }
+        const buffer = Buffer.isBuffer(body) ? body : Buffer.from(body);
+        const compressionOptions = contentTypeMap[contentType] ?? {
+            quality: defaultQuality,
+            format: defaultFormat,
+        };
+        try {
+            const compressed = await compressImage(buffer, compressionOptions);
+            const newContentType = compressionOptions.format === "jpeg"
+                ? "image/jpeg"
+                : compressionOptions.format === "png"
+                    ? "image/png"
+                    : compressionOptions.format === "webp"
+                        ? "image/webp"
+                        : compressionOptions.format === "avif"
+                            ? "image/avif"
+                            : contentType;
+            const headers = new Headers(response.headers);
+            headers.set("content-type", newContentType);
+            headers.set("cache-control", headers.get("cache-control") ?? "public, max-age=86400");
+            return applyHeadersToResponse(response, headers).setBody(compressed);
+        }
+        catch {
+            return response;
+        }
+    };
+}
+//# sourceMappingURL=httpMiddleware.image.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Logging middleware factory.
+ *
+ * @module httpMiddleware/builtin/logging
+ */
+import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+export interface RequestLogger {
+    info?: (message: string, metadata?: Readonly<Record<string, unknown>>) => void;
+    error?: (message: string, metadata?: Readonly<Record<string, unknown>>) => void;
+}
+export interface LoggingMiddlewareOptions {
+    readonly logger?: RequestLogger;
+    readonly includeHeaders?: boolean;
+}
+export declare function createLoggingMiddleware(options?: LoggingMiddlewareOptions): HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.logging.d.ts.map

package/dist/httpMiddleware/builtin/logging/httpMiddleware.logging.js

@@ -0,0 +1,42 @@
+/**
+ * Logging middleware factory.
+ *
+ * @module httpMiddleware/builtin/logging
+ */
+import { getRequestMethod, getRequestUrl, getRequestHeaders, getResponseStatus, } from "../helpers/index.js";
+export function createLoggingMiddleware(options = {}) {
+    return async (context, next) => {
+        const startedAt = Date.now();
+        const request = context.request;
+        const logger = options.logger;
+        logger?.info?.("HTTP request started.", {
+            method: getRequestMethod(request),
+            url: getRequestUrl(request),
+            ...(options.includeHeaders
+                ? {
+                    headers: getRequestHeaders(request),
+                }
+                : {}),
+        });
+        try {
+            const response = await next();
+            logger?.info?.("HTTP request completed.", {
+                method: getRequestMethod(request),
+                url: getRequestUrl(request),
+                status: getResponseStatus(response),
+                duration: Date.now() - startedAt,
+            });
+            return response;
+        }
+        catch (error) {
+            logger?.error?.("HTTP request failed.", {
+                method: getRequestMethod(request),
+                url: getRequestUrl(request),
+                duration: Date.now() - startedAt,
+                error,
+            });
+            throw error;
+        }
+    };
+}
+//# sourceMappingURL=httpMiddleware.logging.js.map

package/dist/httpMiddleware/builtin/logging/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Logging middleware barrel.
+ *
+ * @module httpMiddleware/builtin/logging
+ */
+export { createLoggingMiddleware, type LoggingMiddlewareOptions, type RequestLogger, } from "./httpMiddleware.logging.js";
+//# sourceMappingURL=index.d.ts.map