@zudojs/http 1.2.0 → 1.4.0

package/dist/httpRouter/core/types/httpRouter.type.d.ts

@@ -3,11 +3,25 @@
  *
  * Core types for routing, route definitions, and router context.
  */
+import type { RouteOpenAPIMetadata } from "@zudojs/openapi";
 import type { HttpRequestContext as RequestContext } from "../../../httpRequest/httpRequest.context.js";
 import type { HttpResponseContext as ResponseContext } from "../../../httpResponse/httpResponse.context.js";
 import type { HttpMiddleware, HttpMiddlewareContext } from "../../../httpMiddleware/httpMiddleware.type.js";
 export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "CONNECT" | "TRACE";
-export type RouterHandler = (context: HttpRouterContext) => ResponseContext | Response | void | Promise<ResponseContext | Response | void>;
+/**
+ * A plain, JSON-serialisable value a route handler may return: an object,
+ * array, string, number, boolean or `null`.
+ */
+export type RouterJsonValue = object | string | number | boolean | null;
+/**
+ * What a route handler may return, as server handlers do:
+ * - an `HttpResponseContext` or a web `Response`: sent as built;
+ * - a plain value: sent as `200` with a JSON body
+ *   (`return { id }` is `ctx.middleware.response.json({ id })`);
+ * - `undefined` / `null`: `204 No Content`.
+ */
+export type RouterHandlerResult = ResponseContext | Response | RouterJsonValue | void;
+export type RouterHandler = (context: HttpRouterContext) => RouterHandlerResult | Promise<RouterHandlerResult>;
 export type RouterHandlerLike = RouterHandler | HttpMiddleware;
 export interface HttpRouterContext {
     readonly request: RequestContext;
@@ -18,6 +32,14 @@ export interface HttpRouterContext {
     readonly middleware: HttpMiddlewareContext;
     readonly signal: AbortSignal;
 }
+/**
+ * OpenAPI documentation a route carries: summary, tags, operationId,
+ * `params` / `query` / `headers` / `body` schemas, responses, security,
+ * `deprecated`, `hidden`. It is `@zudojs/openapi`'s `RouteOpenAPIMetadata`,
+ * so the schemas it names document the route in `generateOpenAPIDocument`.
+ * `false` hides the route from the generated document.
+ */
+export type HttpRouteOpenAPI = RouteOpenAPIMetadata | false;
 export interface RouteDefinition {
     readonly method: HttpMethod | readonly HttpMethod[] | "*";
     readonly path: string;
@@ -26,12 +48,20 @@ export interface RouteDefinition {
     readonly name?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly strictTrailingSlash?: boolean;
+    /** OpenAPI documentation; stored as `metadata.openapi`. */
+    readonly openapi?: HttpRouteOpenAPI;
 }
 export interface RouteOptions {
     readonly name?: string;
     readonly middleware?: readonly HttpMiddleware[];
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly strictTrailingSlash?: boolean;
+    /**
+     * OpenAPI documentation; stored as `metadata.openapi`, where
+     * `generateOpenAPIDocument` reads it. Takes precedence over a
+     * `metadata.openapi` passed alongside it.
+     */
+    readonly openapi?: HttpRouteOpenAPI;
 }
 export interface MatchedRoute {
     readonly id: string;
@@ -104,6 +134,12 @@ export interface CompiledRoute {
     readonly segments: readonly CompiledSegment[];
     readonly score: number;
     readonly strictTrailingSlash: boolean;
+    /**
+     * Whether the registered pattern ended with a slash.
+     *
+     * Only consulted when {@link CompiledRoute.strictTrailingSlash} is set.
+     */
+    readonly expectsTrailingSlash?: boolean;
 }
 export { HttpRouterError, RouteConflictError, } from "../error/httpRouter.error.js";
 //# sourceMappingURL=httpRouter.type.d.ts.map

package/dist/httpRouter/core/util/httpRoute.util.d.ts

@@ -8,6 +8,14 @@ import type { HttpRequestContext as RequestContext } from "../../../httpRequest/
 export declare function getRequestMethod(request: RequestContext): string;
 export declare function getRequestUrl(request: RequestContext): string;
 export declare function getRequestSignal(request: RequestContext): AbortSignal | undefined;
+/**
+ * Copies the matched route's parameters onto the request before any route
+ * middleware runs, so `request.getParam("id")` / `request.params` see them
+ * in middleware as well as in the handler. They were only on the router
+ * context, so a guard reading the request (a permissions
+ * `extractResource`, an ownership check) always saw `undefined` and denied.
+ */
+export declare function applyRouteParams(request: RequestContext, params: Readonly<Record<string, string>>): void;
 /**
  * Parses a request-target with the canonical parser shared by the request
  * context and path-scoped middleware.
@@ -24,8 +32,55 @@ export declare function parseUrl(value: string): URL;
  * for the same parameter.
  */
 export declare function parseQuery(params: URLSearchParams): Readonly<Record<string, string | string[]>>;
+/**
+ * Normalizes a **request** path.
+ *
+ * Strips the query string, forces a leading slash, collapses repeated
+ * slashes, and trims a trailing slash.
+ *
+ * This must not be used on a route *pattern*: a pattern may legitimately
+ * contain `?` (the optional-parameter marker), which this function treats as
+ * the start of a query string. Use {@link normalizeRoutePattern} for
+ * patterns.
+ */
 export declare function normalizePath(path: string): string;
+/**
+ * Normalizes a request path while preserving a single trailing slash.
+ *
+ * The trailing slash is the only information a strict-trailing-slash route
+ * needs and {@link normalizePath} destroys it, so matching runs on this
+ * spelling instead.
+ *
+ * @param path - The raw request path, possibly with a query or fragment.
+ * @returns The normalized path, keeping one trailing slash if present.
+ */
+export declare function normalizeMatchPath(path: string): string;
+/**
+ * Normalizes a route **pattern**.
+ *
+ * Identical to {@link normalizePath} except that `?` is left alone, so the
+ * documented optional-parameter syntax (`/users/:id?`, `/files/{name?}`)
+ * survives registration.
+ *
+ * @param pattern - The raw route pattern.
+ * @returns The normalized pattern.
+ */
+export declare function normalizeRoutePattern(pattern: string): string;
+/**
+ * Reports whether a path carries a meaningful trailing slash.
+ *
+ * @param path - The path to inspect.
+ * @returns `true` when the path ends with `/` and is not the root path.
+ */
+export declare function hasTrailingSlash(path: string): boolean;
 export declare function splitPath(path: string): string[];
+/**
+ * Splits a route pattern into its segments, keeping `?` markers intact.
+ *
+ * @param pattern - The raw route pattern.
+ * @returns The pattern's non-empty segments.
+ */
+export declare function splitRoutePattern(pattern: string): string[];
 export declare function validateParameterName(name: string, path: string): void;
 export declare function decodeRouteValue(value: string): string;
 /**

package/dist/httpRouter/core/util/httpRoute.util.js

@@ -5,7 +5,7 @@
  * router core.
  */
 import { parseRequestTarget } from "../../../httpRequest/target/httpRequest.target.js";
-import { parseQueryString } from "../../../httpQuery/http.query.js";
+import { parseQueryString } from "../../../httpQuery/index.js";
 import { InvalidRoutePatternError } from "../error/httpRouter.error.js";
 export function getRequestMethod(request) {
     const value = request.method;
@@ -21,6 +21,22 @@ export function getRequestUrl(request) {
 export function getRequestSignal(request) {
     return request.signal;
 }
+/**
+ * Copies the matched route's parameters onto the request before any route
+ * middleware runs, so `request.getParam("id")` / `request.params` see them
+ * in middleware as well as in the handler. They were only on the router
+ * context, so a guard reading the request (a permissions
+ * `extractResource`, an ownership check) always saw `undefined` and denied.
+ */
+export function applyRouteParams(request, params) {
+    const target = request;
+    if (typeof target.setParam !== "function") {
+        return;
+    }
+    for (const [name, value] of Object.entries(params)) {
+        target.setParam(name, value);
+    }
+}
 /**
  * Parses a request-target with the canonical parser shared by the request
  * context and path-scoped middleware.
@@ -44,14 +60,82 @@ export function parseQuery(params) {
 /* -------------------------------------------------------------------------- */
 /* Path Helpers                                                               */
 /* -------------------------------------------------------------------------- */
+/**
+ * Normalizes a **request** path.
+ *
+ * Strips the query string, forces a leading slash, collapses repeated
+ * slashes, and trims a trailing slash.
+ *
+ * This must not be used on a route *pattern*: a pattern may legitimately
+ * contain `?` (the optional-parameter marker), which this function treats as
+ * the start of a query string. Use {@link normalizeRoutePattern} for
+ * patterns.
+ */
 export function normalizePath(path) {
     if (!path || path === "") {
         return "/";
     }
     const withoutQuery = path.split("?", 1)[0] ?? path;
-    let normalized = withoutQuery.startsWith("/")
-        ? withoutQuery
-        : `/${withoutQuery}`;
+    return collapsePath(withoutQuery);
+}
+/**
+ * Normalizes a request path while preserving a single trailing slash.
+ *
+ * The trailing slash is the only information a strict-trailing-slash route
+ * needs and {@link normalizePath} destroys it, so matching runs on this
+ * spelling instead.
+ *
+ * @param path - The raw request path, possibly with a query or fragment.
+ * @returns The normalized path, keeping one trailing slash if present.
+ */
+export function normalizeMatchPath(path) {
+    if (!path || path.trim() === "") {
+        return "/";
+    }
+    let target = path.trim();
+    if (target.startsWith("http://") || target.startsWith("https://")) {
+        try {
+            target = new URL(target).pathname;
+        }
+        catch {
+            /* Keep the original value if it is not a valid absolute URL. */
+        }
+    }
+    const withoutQuery = target.split("?", 1)[0] ?? target;
+    const withoutHash = withoutQuery.split("#", 1)[0] ?? withoutQuery;
+    const collapsed = collapsePath(withoutHash);
+    return hasTrailingSlash(withoutHash) && collapsed !== "/"
+        ? `${collapsed}/`
+        : collapsed;
+}
+/**
+ * Normalizes a route **pattern**.
+ *
+ * Identical to {@link normalizePath} except that `?` is left alone, so the
+ * documented optional-parameter syntax (`/users/:id?`, `/files/{name?}`)
+ * survives registration.
+ *
+ * @param pattern - The raw route pattern.
+ * @returns The normalized pattern.
+ */
+export function normalizeRoutePattern(pattern) {
+    if (!pattern || pattern === "") {
+        return "/";
+    }
+    return collapsePath(pattern);
+}
+/**
+ * Reports whether a path carries a meaningful trailing slash.
+ *
+ * @param path - The path to inspect.
+ * @returns `true` when the path ends with `/` and is not the root path.
+ */
+export function hasTrailingSlash(path) {
+    const trimmed = path.replace(/\/{2,}/g, "/");
+    return trimmed.length > 1 && trimmed.endsWith("/");
+}
+function collapsePath(value) {
+    let normalized = value.startsWith("/") ? value : `/${value}`;
     normalized = normalized.replace(/\/{2,}/g, "/");
     if (normalized.length > 1 && normalized.endsWith("/")) {
         normalized = normalized.slice(0, -1);
@@ -65,6 +149,19 @@ export function splitPath(path) {
     }
     return normalized.split("/").filter(Boolean);
 }
+/**
+ * Splits a route pattern into its segments, keeping `?` markers intact.
+ *
+ * @param pattern - The raw route pattern.
+ * @returns The pattern's non-empty segments.
+ */
+export function splitRoutePattern(pattern) {
+    const normalized = normalizeRoutePattern(pattern);
+    if (normalized === "/") {
+        return [];
+    }
+    return normalized.split("/").filter(Boolean);
+}
 export function validateParameterName(name, path) {
     if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(name)) {
         throw new InvalidRoutePatternError(path, `Invalid parameter name "${name}".`);

package/dist/httpRouter/dispatch/httpRoute.dispatcher.d.ts

@@ -24,6 +24,17 @@ export interface RouteDispatchContext {
 export interface RouteDispatchOptions {
     readonly onError?: RouteDispatchErrorHandler;
     readonly onComplete?: RouteDispatchCompleteHandler;
+    /**
+     * Keeps the response the middleware chain produced.
+     *
+     * By default a response returned by a route handler is merged into the
+     * response passed to `dispatch()`, overwriting its status, headers, cookies
+     * and body. With this set, the handler's response is left alone and the
+     * dispatch response is returned exactly as the middleware chain built it.
+     *
+     * The option was previously declared and never read, so it silently did
+     * nothing.
+     */
     readonly preserveResponse?: boolean;
 }
 export type RouteDispatchErrorHandler = (error: unknown, context: RouteDispatchContext) => void | Promise<void>;

package/dist/httpRouter/dispatch/httpRoute.dispatcher.js

@@ -5,10 +5,13 @@
  * handler pipeline. Route registration and route matching remain separate
  * concerns.
  */
+import { isGuardResponse } from "@zudojs/middleware";
+import { applyGuardResponse } from "../../httpMiddleware/pipeline/httpPipeline.guardResponse.js";
 import { HttpResponseContext } from "../../httpResponse/httpResponse.context.js";
 import { createRouterContext } from "../httpRouter.context.js";
+import { normalizeResponse } from "../core/factory/httpRoute.factory.base.js";
 import { RouterMiddlewareState } from "../httpRouter.state.js";
-import { getRequestSignal } from "../core/util/httpRoute.util.js";
+import { applyRouteParams, getRequestSignal, } from "../core/util/httpRoute.util.js";
 /* -------------------------------------------------------------------------- */
 /* Route Dispatcher                                                           */
 /* -------------------------------------------------------------------------- */
@@ -104,7 +107,7 @@ export class RouteDispatcher {
     async execute(context) {
         const state = new RouterMiddlewareState();
         const middleware = context.route.middleware.map((layer) => toRouteMiddleware(layer, context.route, state));
-        const handler = toDispatchHandler(context.route.handler, context);
+        const handler = toDispatchHandler(context.route.handler, context, this.options.preserveResponse === true);
         let index = -1;
         const dispatchNext = async (current) => {
             if (current <= index) {
@@ -177,6 +180,8 @@ export async function dispatchRoute(dispatcher, request, response) {
 /* Context Creation                                                           */
 /* -------------------------------------------------------------------------- */
 function createDispatchContext(request, response, match) {
+    /* Route middleware reads params from the request, so set them first. */
+    applyRouteParams(request, match.params);
     return Object.freeze({
         request,
         response,
@@ -220,15 +225,25 @@ function normalizeHandler(handler) {
  * A response context returned by the handler is merged into the dispatch
  * response so the dispatcher's response object stays authoritative.
  */
-function toDispatchHandler(handler, context) {
+function toDispatchHandler(handler, context, preserveResponse = false) {
     return async (request, response) => {
-        const result = await handler(createRouterContext({
+        const returned = await handler(createRouterContext({
             request,
             route: context.route,
             params: context.params,
             signal: getRequestSignal(request),
         }));
-        if (result instanceof HttpResponseContext && result !== response) {
+        /* A web Response or a plain value becomes a response context, exactly
+         * as the router treats it (a plain value is a 200 JSON body). */
+        const result = preserveResponse ||
+            returned === undefined ||
+            returned === null ||
+            returned instanceof HttpResponseContext
+            ? returned
+            : await normalizeResponse(returned);
+        if (!preserveResponse &&
+            result instanceof HttpResponseContext &&
+            result !== response) {
             /*
              * Everything the handler put on its response must survive the merge.
              * Copying only status, headers and body dropped every cookie the
@@ -252,7 +267,7 @@ function toDispatchHandler(handler, context) {
  */
 function toRouteMiddleware(middleware, route, state) {
     return async (request, response, next) => {
-        await middleware({
+        const result = await middleware({
             request,
             response,
             state,
@@ -262,6 +277,10 @@ function toRouteMiddleware(middleware, route, state) {
             await next();
             return response;
         });
+        /* A guard's refusal is written onto the dispatch response, not dropped. */
+        if (isGuardResponse(result)) {
+            applyGuardResponse(response, result);
+        }
     };
 }
 function normalizeMiddleware(middleware) {

package/dist/httpRouter/matching/httpRoute.matcher.core.js

@@ -5,14 +5,28 @@
  * case sensitivity, optional parameters, per-parameter regular expression
  * constraints, and trailing wildcards.
  */
-import { decodeRouteSegment, normalizePath, splitPath, } from "../core/util/httpRoute.util.js";
+import { decodeRouteSegment, hasTrailingSlash, normalizePath, splitPath, } from "../core/util/httpRoute.util.js";
 export function matchCompiledRoute(route, path, caseSensitive) {
+    /*
+     * `strictTrailingSlash` used to be compiled and stored but never read, so a
+     * strict router still answered `/users/` with the `/users` route. The
+     * request path reaches this function with its trailing slash intact
+     * (`normalizeMatchPath`), so the two spellings can finally be told apart.
+     */
+    if (route.strictTrailingSlash &&
+        hasTrailingSlash(path) !== (route.expectsTrailingSlash ?? false)) {
+        return undefined;
+    }
     const routePath = normalizePath(path);
     const inputSegments = splitPath(routePath);
     const output = {};
     const routeSegments = route.segments;
     let inputIndex = 0;
-    for (const segment of routeSegments) {
+    for (let segmentIndex = 0; segmentIndex < routeSegments.length; segmentIndex += 1) {
+        const segment = routeSegments[segmentIndex];
+        if (segment === undefined) {
+            continue;
+        }
         if (segment.type === "wildcard") {
             /*
              * Decode each segment separately and re-join. Decoding the joined tail
@@ -33,10 +47,18 @@ export function matchCompiledRoute(route, path, caseSensitive) {
             break;
         }
         const input = inputSegments[inputIndex];
-        if (input === undefined &&
-            segment.type === "parameter" &&
-            segment.optional) {
-            continue;
+        if (segment.type === "parameter" && segment.optional) {
+            /*
+             * An optional parameter only claims a segment when the segments that
+             * follow it still have enough input left. Without that check
+             * `/account/:id?/profile` swallowed `profile` as the id and then found
+             * nothing to match its literal tail.
+             */
+            const remainingInput = inputSegments.length - inputIndex;
+            if (input === undefined ||
+                remainingInput <= requiredSegments(routeSegments, segmentIndex + 1)) {
+                continue;
+            }
         }
         if (input === undefined) {
             return undefined;
@@ -69,4 +91,27 @@ export function matchCompiledRoute(route, path, caseSensitive) {
     }
     return Object.freeze(output);
 }
+/**
+ * Counts the segments from `start` onwards that must consume input.
+ *
+ * Optional parameters and wildcards can match nothing, so they do not count.
+ *
+ * @param segments - The route's compiled segments.
+ * @param start - The index to count from.
+ * @returns The number of segments that require an input segment.
+ */
+function requiredSegments(segments, start) {
+    let required = 0;
+    for (let index = start; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if (segment === undefined || segment.type === "wildcard") {
+            continue;
+        }
+        if (segment.type === "parameter" && segment.optional) {
+            continue;
+        }
+        required += 1;
+    }
+    return required;
+}
 //# sourceMappingURL=httpRoute.matcher.core.js.map

package/dist/httpRouter/matching/httpRoute.matcher.d.ts

@@ -51,7 +51,6 @@ export declare class RouteMatcher {
     stats(): RouteMatcherStats;
     resetStats(): void;
     private collect;
-    private matchFirstAllowed;
 }
 export declare function createRouteMatcher(router: HttpRouter, options?: RouteMatcherOptions): RouteMatcher;
 export declare function matchRoute(matcher: RouteMatcher, method: string, path: string): RouteMatcherResult | undefined;

package/dist/httpRouter/matching/httpRoute.matcher.js

@@ -5,7 +5,8 @@
  * pathname. Route registration lives in the router core; per-route segment
  * matching lives in `httpRoute.matcher.core.ts`.
  */
-import { normalizeMethod } from "../core/factory/httpRoute.factory.base.js";
+import { createOptionsResponse, normalizeMethod, } from "../core/factory/httpRoute.factory.base.js";
+import { normalizeMatchPath } from "../core/util/httpRoute.util.js";
 import { formatAllowHeader } from "../../httpMethods/http.methods.js";
 import { matchCompiledRoute } from "./httpRoute.matcher.core.js";
 /* -------------------------------------------------------------------------- */
@@ -31,14 +32,20 @@ export class RouteMatcher {
     match(request) {
         this.requests += 1;
         const method = normalizeMethod(request.method);
-        const path = normalizeRequestPath(request.path);
-        const direct = this.matchMethod(method, path);
+        /*
+         * The raw target is threaded through so a strict-trailing-slash route can
+         * still tell `/users` from `/users/`; only the reported path is
+         * normalized.
+         */
+        const target = request.path;
+        const path = normalizeRequestPath(target);
+        const direct = this.matchMethod(method, target);
         if (direct) {
             this.matches += 1;
             return direct;
         }
         if (method === "HEAD" && this.matcherOptions.allowHeadFallback) {
-            const fallback = this.matchMethod("GET", path);
+            const fallback = this.matchMethod("GET", target);
             if (fallback) {
                 this.matches += 1;
                 return {
@@ -48,13 +55,25 @@ export class RouteMatcher {
             }
         }
         if (method === "OPTIONS" && this.matcherOptions.allowOptionsFallback) {
-            const first = this.matchFirstAllowed(this.allowedMethods(path).methods, path);
-            if (first) {
+            const allowed = this.allowedMethods(target);
+            if (allowed.allowed) {
                 this.matches += 1;
-                return {
-                    ...first,
+                /*
+                 * The fallback must never carry an executable route. It used to
+                 * answer with the first route registered on the path under ANY
+                 * method, so `OPTIONS /accounts/42` ran the `DELETE` handler — past
+                 * any CSRF guard that treats `OPTIONS` as safe. The synthetic route
+                 * below owns no middleware and answers `204` with `Allow`, matching
+                 * what `HttpRouter.match()` already does.
+                 */
+                return Object.freeze({
+                    route: createOptionsRoute(path, allowed),
+                    params: Object.freeze({}),
+                    method,
+                    path,
+                    score: 0,
                     matchedBy: "options-fallback",
-                };
+                });
             }
         }
         this.misses += 1;
@@ -63,11 +82,12 @@ export class RouteMatcher {
     matchMethod(method, path) {
         const normalizedMethod = normalizeMethod(method);
         const normalizedPath = normalizeRequestPath(path);
+        const matchPath = normalizeMatchPath(path);
         for (const route of this.router.compiled()) {
             if (!methodApplies(route.definition.method, normalizedMethod)) {
                 continue;
             }
-            const params = matchCompiledRoute(route, normalizedPath, this.matcherOptions.caseSensitive);
+            const params = matchCompiledRoute(route, matchPath, this.matcherOptions.caseSensitive);
             if (!params) {
                 continue;
             }
@@ -80,23 +100,22 @@ export class RouteMatcher {
     /* ------------------------------------------------------------------------ */
     matchAll(request) {
         const method = normalizeMethod(request.method);
-        const path = normalizeRequestPath(request.path);
-        return this.collect(method, path);
+        return this.collect(method, request.path);
     }
     /* ------------------------------------------------------------------------ */
     /* Path Matching                                                            */
     /* ------------------------------------------------------------------------ */
     matchPath(path) {
-        return this.collect("*", normalizeRequestPath(path));
+        return this.collect("*", path);
     }
     /* ------------------------------------------------------------------------ */
     /* Allowed Methods                                                          */
     /* ------------------------------------------------------------------------ */
     allowedMethods(path) {
-        const normalizedPath = normalizeRequestPath(path);
+        const matchPath = normalizeMatchPath(path);
         const methods = new Set();
         for (const route of this.router.compiled()) {
-            const params = matchCompiledRoute(route, normalizedPath, this.matcherOptions.caseSensitive);
+            const params = matchCompiledRoute(route, matchPath, this.matcherOptions.caseSensitive);
             if (params) {
                 methods.add(route.definition.method);
             }
@@ -140,29 +159,22 @@ export class RouteMatcher {
     /* ------------------------------------------------------------------------ */
     collect(method, path) {
         const results = [];
+        const normalizedPath = normalizeRequestPath(path);
+        const matchPath = normalizeMatchPath(path);
         const seen = new Set();
         for (const route of this.router.compiled()) {
             if (!methodApplies(route.definition.method, method)) {
                 continue;
             }
-            const params = matchCompiledRoute(route, path, this.matcherOptions.caseSensitive);
+            const params = matchCompiledRoute(route, matchPath, this.matcherOptions.caseSensitive);
             if (!params || seen.has(route.definition.id)) {
                 continue;
             }
             seen.add(route.definition.id);
-            results.push(createResult(route, params, method, path));
+            results.push(createResult(route, params, method, normalizedPath));
         }
         return Object.freeze(results);
     }
-    matchFirstAllowed(methods, path) {
-        for (const method of methods) {
-            const result = this.matchMethod(method, path);
-            if (result) {
-                return result;
-            }
-        }
-        return undefined;
-    }
 }
 /* -------------------------------------------------------------------------- */
 /* Factory                                                                    */
@@ -200,6 +212,32 @@ function createResult(route, params, method, path) {
         matchedBy: route.definition.method === "*" ? "wildcard" : "exact",
     });
 }
+/**
+ * Builds the synthetic route an `OPTIONS` fallback resolves to.
+ *
+ * It carries no middleware and a handler that only answers `204` with the
+ * path's `Allow` header, so an `OPTIONS` request can never reach a handler
+ * registered for another method.
+ *
+ * @param path - The normalized request path.
+ * @param allowed - The methods registered on that path.
+ * @returns The synthetic route definition.
+ */
+function createOptionsRoute(path, allowed) {
+    const methods = allowed.methods.includes("OPTIONS")
+        ? allowed.methods
+        : [...allowed.methods, "OPTIONS"];
+    return Object.freeze({
+        id: "route:options-fallback",
+        method: "OPTIONS",
+        path,
+        name: undefined,
+        params: Object.freeze({}),
+        metadata: Object.freeze({}),
+        handler: () => createOptionsResponse(methods),
+        middleware: Object.freeze([]),
+    });
+}
 /* -------------------------------------------------------------------------- */
 /* Method Utilities                                                           */
 /* -------------------------------------------------------------------------- */

package/dist/httpRouter/pattern/httpRoute.pattern.parse.d.ts

@@ -20,6 +20,7 @@ export interface CompiledRoutePath {
     readonly segments: readonly CompiledSegment[];
     readonly score: number;
     readonly strictTrailingSlash: boolean;
+    readonly expectsTrailingSlash: boolean;
 }
 /**
  * Compiles a route path into its segments.
@@ -35,4 +36,19 @@ export declare function compileRoute(path: string, strictTrailingSlash: boolean)
  * Scores compiled segments by specificity.
  */
 export declare function scoreSegments(segments: readonly CompiledSegment[]): number;
+/**
+ * Compares two compiled patterns by specificity, most specific first.
+ *
+ * Segments are compared left to right by kind (literal, then parameter, then
+ * wildcard), which is how a router is expected to rank patterns. Summing the
+ * kinds into one scalar — as this used to — let a longer but entirely
+ * parameterised pattern such as `/:p/:q/:r/:s` outrank a literal-anchored
+ * `/admin/*rest`, so a request to `/admin/a/b/c` bypassed the admin route and
+ * every guard registered on it.
+ *
+ * @param left - The first pattern's segments.
+ * @param right - The second pattern's segments.
+ * @returns A negative number when `left` is more specific.
+ */
+export declare function compareSegmentSpecificity(left: readonly CompiledSegment[], right: readonly CompiledSegment[]): number;
 //# sourceMappingURL=httpRoute.pattern.parse.d.ts.map