@zudojs/http 1.2.0 → 1.4.0

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

@@ -11,6 +11,24 @@ export interface RequestLogger {
 export interface LoggingMiddlewareOptions {
     readonly logger?: RequestLogger;
     readonly includeHeaders?: boolean;
+    /**
+     * Extra header names whose value must be replaced with `[REDACTED]`, on top
+     * of the credential-bearing names `@zudojs/logger` already recognises
+     * (`authorization`, `proxy-authorization`, `cookie`, `set-cookie`, …).
+     */
+    readonly redactHeaders?: readonly string[];
 }
+/**
+ * Creates the request/response logging middleware.
+ *
+ * With `includeHeaders` the header record is redacted before it reaches the
+ * logger, using the same matcher `@zudojs/logger` applies to log metadata.
+ * It used to be copied verbatim, so a bearer token and the whole session
+ * cookie landed in the log store on every request.
+ *
+ * @param options - Logger, header inclusion and extra redacted names.
+ * @returns A middleware that logs the start, completion and failure of a
+ *   request.
+ */
 export declare function createLoggingMiddleware(options?: LoggingMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.logging.d.ts.map

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

@@ -3,8 +3,24 @@
  *
  * @module httpMiddleware/builtin/logging
  */
+import { createSecretMatcher, redactLogValue } from "@zudojs/logger";
 import { getRequestMethod, getRequestUrl, getRequestHeaders, getResponseStatus, } from "../helpers/index.js";
+/**
+ * Creates the request/response logging middleware.
+ *
+ * With `includeHeaders` the header record is redacted before it reaches the
+ * logger, using the same matcher `@zudojs/logger` applies to log metadata.
+ * It used to be copied verbatim, so a bearer token and the whole session
+ * cookie landed in the log store on every request.
+ *
+ * @param options - Logger, header inclusion and extra redacted names.
+ * @returns A middleware that logs the start, completion and failure of a
+ *   request.
+ */
 export function createLoggingMiddleware(options = {}) {
+    const isSecret = createSecretMatcher({
+        keys: options.redactHeaders ? [...options.redactHeaders] : undefined,
+    });
     return async (context, next) => {
         const startedAt = Date.now();
         const request = context.request;
@@ -14,7 +30,7 @@ export function createLoggingMiddleware(options = {}) {
             url: getRequestUrl(request),
             ...(options.includeHeaders
                 ? {
-                    headers: getRequestHeaders(request),
+                    headers: redactLogValue(getRequestHeaders(request), isSecret),
                 }
                 : {}),
         });

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/builtin/security/httpMiddleware.security.d.ts

@@ -17,5 +17,16 @@ export interface SecurityMiddlewareOptions {
      */
     readonly useDefaults?: boolean;
 }
+/**
+ * Creates the response-hardening middleware.
+ *
+ * Called with no options it emits the package's default security header set
+ * ({@link createDefaultSecurityHeaderOptions}); the options below layer over
+ * that set, and `useDefaults: false` drops it entirely.
+ *
+ * @param options - Explicit header values, layered over the baseline.
+ * @returns A middleware that adds the headers to the downstream response.
+ * @throws {TypeError} If a configured value contains a control character.
+ */
 export declare function createSecurityMiddleware(options?: SecurityMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.security.d.ts.map

package/dist/httpMiddleware/builtin/security/httpMiddleware.security.js

@@ -4,19 +4,34 @@
  * @module httpMiddleware/builtin/security
  */
 import { isValidHeaderFieldValue } from "../../../httpHeaders/security/index.js";
+import { createSecurityHeaders } from "../../../httpSecurityHeaders/httpSecurityHeader.factory.js";
+import { createDefaultSecurityHeaderOptions } from "../../../httpSecurityHeaders/httpSecurityHeader.recommended.js";
 import { withResponseHeaders } from "../helpers/index.js";
 /**
- * Headers applied when the caller does not override them.
+ * The headers applied when the caller does not override them.
  *
- * `createSecurityMiddleware()` previously defaulted every option to
- * `undefined` and therefore set no headers at all — its presence in a
- * codebase read as evidence that the control existed while shipping nothing.
+ * This is the package's declared safe baseline — the very set
+ * `createDefaultSecurityHeaderOptions` was written for and, until now, was
+ * never called for. The middleware used to re-derive its own three-entry
+ * list, so `pipeline.use(createSecurityMiddleware())` emitted no
+ * `Content-Security-Policy`, no `Strict-Transport-Security`, no
+ * `Permissions-Policy` and none of the cross-origin isolation headers while
+ * reading as evidence that the control was in force.
+ */
+function defaultSecurityHeaders() {
+    return createSecurityHeaders(createDefaultSecurityHeaderOptions());
+}
+/**
+ * Creates the response-hardening middleware.
+ *
+ * Called with no options it emits the package's default security header set
+ * ({@link createDefaultSecurityHeaderOptions}); the options below layer over
+ * that set, and `useDefaults: false` drops it entirely.
+ *
+ * @param options - Explicit header values, layered over the baseline.
+ * @returns A middleware that adds the headers to the downstream response.
+ * @throws {TypeError} If a configured value contains a control character.
  */
-const DEFAULT_SECURITY_HEADERS = Object.freeze({
-    "x-content-type-options": "nosniff",
-    "x-frame-options": "DENY",
-    "referrer-policy": "strict-origin-when-cross-origin",
-});
 export function createSecurityMiddleware(options = {}) {
     const configured = {
         "strict-transport-security": options.strictTransportSecurity,
@@ -26,9 +41,7 @@ export function createSecurityMiddleware(options = {}) {
         "content-security-policy": options.contentSecurityPolicy,
         "referrer-policy": options.referrerPolicy,
     };
-    const resolved = {
-        ...(options.useDefaults === false ? {} : DEFAULT_SECURITY_HEADERS),
-    };
+    const resolved = options.useDefaults === false ? {} : defaultSecurityHeaders();
     for (const [name, value] of Object.entries(configured)) {
         if (value === undefined) {
             continue;

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

package/dist/httpNegotiation/httpNegotiation.core.d.ts

@@ -99,6 +99,19 @@ export declare function negotiateCharset(header: string | undefined | null, avai
  * @returns The selected alternative, or `undefined` if none is acceptable.
  */
 export declare function negotiate<T>(preferences: readonly NegotiationPreference[], available: readonly T[], matcher: (accepted: string, available: T) => boolean): T | undefined;
+/**
+ * Returns the weight a preference list assigns to one value.
+ *
+ * The **most specific** match wins, and only then the highest weight, per
+ * RFC 9110 section 12.4.2. Ranking by weight first let `*;q=1` override an
+ * explicit `gzip;q=0`, so a coding the client had refused came back with
+ * full quality.
+ *
+ * @param preferences - The parsed preferences.
+ * @param value - The alternative to weigh.
+ * @param matcher - Matches a preference value against an alternative.
+ * @returns The quality in `[0, 1]`, or `0` when nothing matches.
+ */
 export declare function getPreferenceQuality<T>(preferences: readonly NegotiationPreference[], value: T, matcher: (accepted: string, available: T) => boolean): number;
 export declare function normalizeMediaType(value: string): string;
 export declare function splitMediaType(value: string): [string, string] | undefined;

package/dist/httpNegotiation/httpNegotiation.core.js

@@ -214,7 +214,36 @@ export function negotiateEncoding(header, available) {
     if (preferences.length === 0) {
         return available[0];
     }
-    return negotiate(preferences, available, matchesEncoding);
+    const selected = negotiate(preferences, available, matchesEncoding);
+    if (selected !== undefined) {
+        return selected;
+    }
+    /*
+     * RFC 9110 section 12.5.3: a representation with no content coding is
+     * acceptable unless the field explicitly excludes it with `identity;q=0`
+     * or a `*;q=0` that no identity entry overrides. Returning `undefined`
+     * here made `Accept-Encoding: zstd` look like "nothing is acceptable", so
+     * a caller answered 406 for a request it could have served uncompressed.
+     */
+    const identity = available.find((value) => isIdentityEncoding(value));
+    if (identity === undefined || isIdentityRejected(preferences)) {
+        return undefined;
+    }
+    return identity;
+}
+/**
+ * Reports whether an `Accept-Encoding` field rejects the identity coding.
+ *
+ * @param preferences - The parsed preferences.
+ * @returns `true` when identity must not be served.
+ */
+function isIdentityRejected(preferences) {
+    const explicit = preferences.find((preference) => isIdentityEncoding(preference.value));
+    if (explicit) {
+        return !isAcceptableQuality(explicit.quality);
+    }
+    const wildcard = preferences.find((preference) => isWildcardEncoding(preference.value));
+    return wildcard !== undefined && !isAcceptableQuality(wildcard.quality);
 }
 export function getEncodingQuality(header, encoding) {
     const preferences = parseAcceptEncoding(header);
@@ -319,20 +348,43 @@ function isExcluded(candidate, selected, rejections, matcher) {
     return rejections.some((rejection) => rejection.specificity >= selected.specificity &&
         matcher(rejection.value, candidate));
 }
+/**
+ * Returns the weight a preference list assigns to one value.
+ *
+ * The **most specific** match wins, and only then the highest weight, per
+ * RFC 9110 section 12.4.2. Ranking by weight first let `*;q=1` override an
+ * explicit `gzip;q=0`, so a coding the client had refused came back with
+ * full quality.
+ *
+ * @param preferences - The parsed preferences.
+ * @param value - The alternative to weigh.
+ * @param matcher - Matches a preference value against an alternative.
+ * @returns The quality in `[0, 1]`, or `0` when nothing matches.
+ */
 export function getPreferenceQuality(preferences, value, matcher) {
     let best;
     for (const preference of preferences) {
-        if (matcher(preference.value, value)) {
-            if (!best ||
-                preference.quality > best.quality ||
-                (preference.quality === best.quality &&
-                    preference.specificity > best.specificity)) {
-                best = preference;
-            }
+        if (!matcher(preference.value, value)) {
+            continue;
+        }
+        if (!best || isMoreRelevant(preference, best)) {
+            best = preference;
         }
     }
     return best?.quality ?? 0;
 }
+/**
+ * Orders two matching preferences: specificity, then weight, then position.
+ */
+function isMoreRelevant(candidate, best) {
+    if (candidate.specificity !== best.specificity) {
+        return candidate.specificity > best.specificity;
+    }
+    if (candidate.quality !== best.quality) {
+        return candidate.quality > best.quality;
+    }
+    return false;
+}
 /* -------------------------------------------------------------------------- */
 /* Media Type Helpers                                                         */
 /* -------------------------------------------------------------------------- */

package/dist/httpOpenApi/httpOpenApi.document.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OpenAPI document generation from a router's registered routes.
+ */
+import { type OpenAPIDocument, type OpenAPIManager } from "@zudojs/openapi";
+import type { HttpOpenAPIOptions, HttpOpenAPIRouteSource } from "./httpOpenApi.type.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 declare function generateOpenAPIDocument(router: HttpOpenAPIRouteSource, options: HttpOpenAPIOptions): OpenAPIDocument;
+/** A manager that follows a router's route table. */
+export interface HttpRouterOpenAPI {
+    /** The manager, refreshed from the router. */
+    manager(): OpenAPIManager;
+    /** The current document, regenerated only when the route table changed. */
+    document(): OpenAPIDocument;
+}
+/**
+ * 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 declare function createRouterOpenAPI(router: HttpOpenAPIRouteSource, options: HttpOpenAPIOptions): HttpRouterOpenAPI;
+//# sourceMappingURL=httpOpenApi.document.d.ts.map