@nextrush/router 3.0.7 → 4.0.0-beta.1

package/src/__tests__/walk-pool-sizing.test.ts

@@ -0,0 +1,72 @@
+/**
+ * @nextrush/router - walk pool sizing tracks maxDepth (`reduce-router-match-allocations`)
+ *
+ * `Router.addRoute` rebuilds `state.walkPool` whenever a newly registered
+ * route's depth exceeds the current pool's size, so the pool is never too
+ * small for the deepest route actually registered — never guessed, never
+ * left stale after a deeper route is added later.
+ */
+
+import type { RouteHandler } from '@nextrush/types';
+import { describe, expect, it } from 'vitest';
+import { createRouter } from '../router';
+
+const noop: RouteHandler = async () => {};
+
+describe('walk pool sizing follows registered route depth', () => {
+  it('has no pool for a router with only static routes', () => {
+    const router = createRouter();
+    router.get('/a', noop);
+    router.get('/b', noop);
+    // No param/wildcard route registered — matches still work via the static
+    // fast path, and there is nothing for a pool to help with.
+    expect(router.match('GET', '/a')?.handler).toBe(noop);
+  });
+
+  it('matches correctly immediately after the first param route is registered', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const match = router.match('GET', '/users/42');
+    expect(match?.params).toEqual({ id: '42' });
+  });
+
+  it('matches correctly after a deeper route is registered later, growing the pool', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    // First match at the shallower depth, pool sized to depth 2.
+    expect(router.match('GET', '/users/1')?.params).toEqual({ id: '1' });
+
+    // Register a much deeper route — the pool must grow to cover it.
+    router.get('/orgs/:o/teams/:t/members/:m/roles/:r', noop);
+    const deep = router.match('GET', '/orgs/1/teams/2/members/3/roles/4');
+    expect(deep?.params).toEqual({ o: '1', t: '2', m: '3', r: '4' });
+
+    // The original shallow route still matches correctly after the pool grew.
+    expect(router.match('GET', '/users/2')?.params).toEqual({ id: '2' });
+  });
+
+  it('a router built with all routes registered up front matches every depth correctly', () => {
+    const router = createRouter();
+    router.get('/a/:x', noop);
+    router.get('/a/:x/b/:y', noop);
+    router.get('/a/:x/b/:y/c/:z', noop);
+
+    expect(router.match('GET', '/a/1')?.params).toEqual({ x: '1' });
+    expect(router.match('GET', '/a/1/b/2')?.params).toEqual({ x: '1', y: '2' });
+    expect(router.match('GET', '/a/1/b/2/c/3')?.params).toEqual({ x: '1', y: '2', z: '3' });
+  });
+
+  it('reset() clears pooled state so a shallower re-registration still matches correctly', () => {
+    const router = createRouter();
+    router.get('/orgs/:o/teams/:t/members/:m', noop);
+    expect(router.match('GET', '/orgs/1/teams/2/members/3')?.params).toEqual({
+      o: '1',
+      t: '2',
+      m: '3',
+    });
+
+    router.reset();
+    router.get('/x/:id', noop);
+    expect(router.match('GET', '/x/9')?.params).toEqual({ id: '9' });
+  });
+});

package/src/__tests__/walk-pool-undersized-guard.test.ts

@@ -0,0 +1,59 @@
+/**
+ * @nextrush/router - walk-pool fail-closed guard when undersized
+ * (`reduce-router-match-allocations`)
+ *
+ * `matchNodeIndexedPooled` defensively fails closed (treats the walk as a
+ * miss, never writes past the array) if a caller ever supplies a `WalkPool`
+ * smaller than the path actually being walked needs. `createWalkPool` sizes
+ * correctly today (`maxDepth + 1`), so this should be unreachable through the
+ * public API — this file proves the guard itself is correct if that
+ * invariant is ever violated by a future change, rather than leaving an
+ * untested "should be unreachable" comment as the only evidence.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { matchNodeIndexed } from '../matching';
+import { createWalkPool } from '../walk-pool';
+import { createNode, NodeType, type HandlerEntry } from '../segment-trie';
+import { compileExecutor } from '../segment-trie';
+
+const noop = async (): Promise<void> => {};
+
+describe('walk pool — fails closed when undersized (defense-in-depth)', () => {
+  it('a static-descent pool undersized by one frame misses cleanly instead of writing past the array', () => {
+    const root = createNode('');
+    const a = createNode('a');
+    root.children.set('a', a);
+    const executor = compileExecutor(noop, []);
+    const entry: HandlerEntry = { handler: noop, middleware: [], executor };
+    a.handlers.set('GET', entry);
+
+    // Correctly sized for depth 0 only (createWalkPool(0) -> 1 frame) — one
+    // fewer frame than the descent into 'a' (depth 1) actually needs.
+    const undersizedPool = createWalkPool(0);
+    const bindNames: string[] = [];
+    const bindValues: string[] = [];
+
+    const result = matchNodeIndexed(root, '/a', 1, bindNames, bindValues, 'GET', true, undefined, undersizedPool);
+    expect(result).toBeNull();
+  });
+
+  it('a param-descent pool undersized by one frame misses cleanly and leaves no dangling bind', () => {
+    const root = createNode('');
+    const idNode = createNode(':id', NodeType.PARAM);
+    idNode.paramName = 'id';
+    root.paramChild = idNode;
+    const executor = compileExecutor(noop, []);
+    idNode.handlers.set('GET', { handler: noop, middleware: [], executor });
+
+    const undersizedPool = createWalkPool(0);
+    const bindNames: string[] = [];
+    const bindValues: string[] = [];
+
+    const result = matchNodeIndexed(root, '/42', 1, bindNames, bindValues, 'GET', true, undefined, undersizedPool);
+    expect(result).toBeNull();
+    // The guard pops its own speculative bind before failing closed — no leak.
+    expect(bindNames).toEqual([]);
+    expect(bindValues).toEqual([]);
+  });
+});

package/src/canonicalize.ts

@@ -0,0 +1,137 @@
+/**
+ * @nextrush/router - Canonical Request Path
+ *
+ * The single normalization owner (RFC-029): every consumer that needs to know
+ * "what path does the router treat this request as" — the router's own match,
+ * a mounted-router prefix test, a CSRF exclude-path match, an adapter's
+ * published `ctx.path` — calls {@link canonicalizePath} instead of hand-rolling
+ * its own fold/collapse/strip, so there is exactly one definition of "the same
+ * path" across the framework (SEC-02, SEC-09, SEC-15).
+ *
+ * @see docs/RFC/request-data/029-canonical-request-path.md
+ * @packageDocumentation
+ */
+
+import { collapseAndStrip, isProvablyLowerAscii } from './matching';
+
+/** Result of {@link canonicalizePath}. */
+export interface CanonicalPathResult {
+  /**
+   * `true` when the path contains a `.`/`..` path segment. A dot segment is
+   * rejected outright (400), never resolved — resolving it locally would
+   * diverge from how a front-end proxy already resolved (or didn't resolve)
+   * the same segment before forwarding, reopening the desync this RFC closes.
+   */
+  readonly rejected: boolean;
+  /**
+   * The canonical path: query-stripped, dot-segment-free, case-folded (unless
+   * `caseSensitive`), slash-collapsed, trailing-slash-stripped per `strict`.
+   * Meaningless when {@link rejected} is `true`.
+   */
+  readonly path: string;
+}
+
+const DOT = 0x2e; // '.'
+const SLASH = 0x2f; // '/'
+
+/**
+ * True when `path` (already query-stripped) contains a `.` or `..` segment —
+ * a component that is exactly `.` or `..` between slash boundaries (or at the
+ * start/end of the string). A single linear scan, no backtracking regex
+ * (task 3.5): each character is visited at most once, so a pathological input
+ * cannot degrade to worse than O(n).
+ *
+ * A dot as filename content (`archive.tar.gz`, `..hidden.txt`) is NOT a dot
+ * segment — only a component whose entire text between slashes is `.` or `..`
+ * counts.
+ */
+export function hasDotSegment(path: string): boolean {
+  const len = path.length;
+  let segStart = 0;
+
+  for (let i = 0; i <= len; i++) {
+    const atBoundary = i === len || path.charCodeAt(i) === SLASH;
+    if (!atBoundary) continue;
+
+    const segLen = i - segStart;
+    if (segLen === 1 && path.charCodeAt(segStart) === DOT) return true;
+    if (segLen === 2 && path.charCodeAt(segStart) === DOT && path.charCodeAt(segStart + 1) === DOT) {
+      return true;
+    }
+    segStart = i + 1;
+  }
+
+  return false;
+}
+
+/**
+ * Single-entry memo for {@link canonicalizePath}.
+ *
+ * Exists because a request falling through N prefix mounts asks for the
+ * canonical form of the *same* path N times, once per mount — the O(mounts)
+ * term that made a 10-module app spend most of its dispatch time deciding which
+ * mount to enter. Each call also allocated its own result object, so the memo
+ * removes an allocation as well as three string scans.
+ *
+ * Safe to share the result across callers: {@link CanonicalPathResult} declares
+ * both fields `readonly`, and no caller mutates it (verified across all three
+ * call sites — the mount test, the router's own dispatch, and the adapter).
+ * Keyed on all three inputs, so two routers with different `caseSensitive` or
+ * `strict` options can never read each other's answer. A single entry means
+ * interleaved requests simply miss rather than getting a wrong answer.
+ *
+ * This is a pure-function memo, not shared state: it cannot make
+ * `canonicalizePath` return anything other than what recomputing would return.
+ */
+let memoTarget: string | undefined = undefined;
+let memoCaseSensitive = false;
+let memoStrict = false;
+let memoResult: CanonicalPathResult = { rejected: false, path: '/' };
+
+/**
+ * Canonicalize a raw request target into the one path value every consumer
+ * (router match, mount-prefix test, CSRF exclude match, published `ctx.path`)
+ * treats as "this request's path" (RFC-029).
+ *
+ * Order: strip the query string, reject a dot segment before any further
+ * normalization (a dot segment is a request-shape violation, not something to
+ * fold case on first), then fold case (unless `caseSensitive`) and collapse
+ * structure exactly as {@link import('./matching').normalizePathForMatch} does
+ * — this function IS that normalization, extended with dot-segment rejection
+ * and made a public, adapter-facing entry point.
+ *
+ * The most recent result is memoized; see the note above the memo fields for
+ * why that is sound. Treat the returned object as immutable.
+ *
+ * @param rawTarget - The raw request target, may include a query string.
+ * @param caseSensitive - Router case-sensitivity option.
+ * @param strict - Router strict-trailing-slash option.
+ */
+export function canonicalizePath(
+  rawTarget: string,
+  caseSensitive: boolean,
+  strict: boolean
+): CanonicalPathResult {
+  if (rawTarget === memoTarget && caseSensitive === memoCaseSensitive && strict === memoStrict) {
+    return memoResult;
+  }
+
+  const queryIdx = rawTarget.indexOf('?');
+  const path = queryIdx === -1 ? rawTarget : rawTarget.slice(0, queryIdx);
+
+  const result: CanonicalPathResult = hasDotSegment(path)
+    ? { rejected: true, path }
+    : {
+        rejected: false,
+        path: collapseAndStrip(
+          caseSensitive || isProvablyLowerAscii(path) ? path : path.toLowerCase(),
+          strict
+        ),
+      };
+
+  memoTarget = rawTarget;
+  memoCaseSensitive = caseSensitive;
+  memoStrict = strict;
+  memoResult = result;
+  return result;
+}

package/src/composition.ts

@@ -0,0 +1,79 @@
+/**
+ * @nextrush/router - Router Composition
+ *
+ * Sub-router mounting/copying logic extracted from the `Router` class (T014,
+ * design.md D3 — extracted after the matching-engine split left `router.ts`
+ * still over the 300-line ceiling).
+ *
+ * `copyRoutes`'s tree walk is structurally pure (segments/prefix/middleware are
+ * all explicit parameters), but its side effect — registering the copied route —
+ * needs `Router.addRoute`, a private method. Rather than reach into `Router`
+ * internals or promote `addRoute` to `public` (a public-API change out of scope
+ * for this refactor), the effect is injected explicitly as an `addRoute`
+ * callback parameter. `use`/`mount`/`mountRouter` stay on `Router` itself:
+ * they return `this` for fluent chaining and read `Router` instance state
+ * (`root`, `routerMiddleware`) that isn't naturally expressible as function
+ * parameters without more ceremony than the win justifies.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { HttpMethod, Middleware, RouteHandler } from '@nextrush/types';
+import type { TrieNode } from './segment-trie';
+
+/** Callback signature matching `Router['addRoute']` — injected, not imported. */
+export type AddRouteFn = (
+  method: HttpMethod,
+  path: string,
+  handlers: RouteHandler[],
+  middleware: Middleware[]
+) => void;
+
+/**
+ * Recursively copy routes from one router's trie into another via the
+ * supplied `addRoute` callback.
+ */
+export function copyRoutes(
+  node: TrieNode,
+  prefix: string,
+  segments: string[],
+  subRouterMiddleware: Middleware[],
+  addRoute: AddRouteFn
+): void {
+  // Copy handlers at this node
+  for (const [method, entry] of node.handlers) {
+    // A derived HEAD entry is not copied — the parent re-derives it from the
+    // GET registration below, which keeps the parent's own explicit-HEAD
+    // precedence and introspection rows correct.
+    if (entry.autoHead) continue;
+    const path = prefix + '/' + segments.join('/');
+    // Prepend sub-router middleware so it runs before the route's own middleware
+    const combined =
+      subRouterMiddleware.length > 0
+        ? [...subRouterMiddleware, ...entry.middleware]
+        : entry.middleware;
+    addRoute(method, path || '/', [entry.handler], combined);
+  }
+
+  // Copy static children
+  for (const [, child] of node.children) {
+    copyRoutes(child, prefix, [...segments, child.segment], subRouterMiddleware, addRoute);
+  }
+
+  // Copy param child
+  if (node.paramChild) {
+    copyRoutes(
+      node.paramChild,
+      prefix,
+      [...segments, node.paramChild.segment],
+      subRouterMiddleware,
+      addRoute
+    );
+  }
+
+  // Copy wildcard child
+  if (node.wildcardChild) {
+    copyRoutes(node.wildcardChild, prefix, [...segments, '*'], subRouterMiddleware, addRoute);
+  }
+}

package/src/constants.ts

@@ -0,0 +1,43 @@
+/**
+ * @nextrush/router - Shared internal constants
+ *
+ * A leaf module that imports nothing, so any router module can depend on it
+ * without risking an import cycle. This is the resolution of the former
+ * `EMPTY_PARAMS` duplication: the constant was previously copied across modules
+ * to dodge a `router.ts` <-> `match-route.ts` cycle, which a dependency-free
+ * leaf module makes impossible by construction.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+/**
+ * Prototype for every per-request key/value bag the router hands to
+ * application code (`ctx.params`).
+ *
+ * Built once at module load, so instances are created with
+ * `Object.create(NULL_PROTO)` rather than `Object.create(null)`. Both satisfy
+ * the security requirement — `Object.prototype` stays unreachable, so a param
+ * named `__proto__`/`constructor`/`prototype` binds as an own key and no
+ * inherited member is visible — but `Object.create(null)` additionally puts the
+ * object into V8 DICTIONARY mode, where property loads cannot be inline-cached.
+ * That cost is paid by every `ctx.params.id` read in every handler, forever.
+ * Deriving from a null-prototype object instead keeps FAST properties.
+ *
+ * @see docs/adr/ADR-0021-fast-property-request-containers.md
+ */
+export const NULL_PROTO: object = Object.create(null) as object;
+
+/**
+ * Frozen empty params object for matches with no path parameters (static-map
+ * hits and successful walks that bound no `:param`/`*`).
+ *
+ * Shared as a single instance to avoid allocating a fresh object per request on
+ * the hot path. Frozen so the shared instance can never be mutated by a
+ * handler. Built on {@link NULL_PROTO} because it is *read* on every
+ * static-route request — a dictionary-mode miss-read (`ctx.params.id` on a
+ * route with no params) measured 2.2x slower than a fast-property one.
+ */
+export const EMPTY_PARAMS: Record<string, string> = Object.freeze(
+  Object.create(NULL_PROTO) as Record<string, string>
+);

package/src/dispatch.ts

@@ -0,0 +1,145 @@
+/**
+ * @nextrush/router - Dispatch Middleware Generation
+ *
+ * The two app-facing `Middleware` factories extracted from the `Router` class
+ * (design.md D2 — finishing T014's split along the same seam: the composition,
+ * matching-engine, and sealing clusters were already extracted; this is the
+ * dispatch/allowed-methods generation cluster).
+ *
+ * Both closures are structurally pure — every value they read (the `match`
+ * function, the trie root, the case-sensitivity/strict flags) is passed in
+ * explicitly rather than captured off `this`, so they carry no hidden
+ * dependency on `Router` beyond their parameters (same principle as the
+ * matching-engine extraction, design.md D1). `Router.routes()` and
+ * `Router.allowedMethods()` stay as thin public methods that supply that
+ * state and return these closures.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { Context, HttpMethod, Middleware, RouteMatch } from '@nextrush/types';
+import { NOOP_NEXT, type TrieNode } from './segment-trie';
+import { findAllowedMethods } from './find-node';
+import { canonicalizePath } from './canonicalize';
+
+/**
+ * Shared resolved promise for the no-`next` miss path (NF-1). Reused rather than
+ * allocating a fresh `Promise.resolve()` per miss, mirroring the router's
+ * existing `NOOP_NEXT`/`RESOLVED_PROMISE` sentinels.
+ */
+const RESOLVED: Promise<void> = Promise.resolve();
+
+/**
+ * Build the router's primary dispatch middleware.
+ *
+ * On each request it canonicalizes the path (RFC-029): a dot segment
+ * (`.`/`..`) is rejected with 400 before any route match or path-based
+ * middleware runs — resolving it locally would diverge from how a front-end
+ * proxy already handled the same segment, so it is never resolved, only
+ * rejected. Otherwise it resolves the route via the injected `match`
+ * function, publishes the canonical path onto `ctx.path` (preserving the raw
+ * target as `ctx.originalPath`), sets `ctx.params`, and runs the
+ * pre-compiled executor (which already bakes in any router-level
+ * middleware). A miss sets `ctx.status = 404` and yields to the next
+ * middleware so `allowedMethods()`/a 404 handler can act.
+ *
+ * @param match - Route resolver, supplied by `Router.match` so this factory
+ *   never touches `Router` internals directly.
+ * @param caseSensitive - Router case-sensitivity option, forwarded to
+ *   canonicalization so the published `ctx.path` matches what `match` used.
+ * @param strict - Router strict-trailing-slash option, forwarded likewise.
+ */
+export function createRoutesMiddleware(
+  match: (method: HttpMethod, path: string) => RouteMatch | null,
+  caseSensitive: boolean,
+  strict: boolean
+): Middleware {
+  return (ctx: Context, next?: () => Promise<void>): Promise<void> => {
+    const originalPath = ctx.path;
+    const canonical = canonicalizePath(originalPath, caseSensitive, strict);
+
+    if (canonical.rejected) {
+      // A dot segment is a request-shape violation, not a 404 — it stops the
+      // chain outright rather than falling through to a 404/allowedMethods
+      // handler, which would still leak information about the un-normalized
+      // target via ctx.path.
+      ctx.status = 400;
+      (ctx as { originalPath: string }).originalPath = originalPath;
+      return RESOLVED;
+    }
+
+    (ctx as { path: string }).path = canonical.path;
+    (ctx as { originalPath: string }).originalPath = originalPath;
+
+    const routeMatch = match(ctx.method, canonical.path);
+
+    if (!routeMatch) {
+      // No route matched — set 404 so allowedMethods()/notFoundHandler() can act,
+      // then forward to the next middleware (the allowedMethods fall-through).
+      ctx.status = 404;
+      return next ? next() : RESOLVED;
+    }
+
+    ctx.params = routeMatch.params;
+
+    // NF-1: forward the executor's promise DIRECTLY instead of `await`-ing it in
+    // an extra `async` frame. The executor already returns a `Promise<void>`,
+    // converts synchronous throws to rejections, and terminates the chain at the
+    // handler, so ordering, rejection propagation, and the `setNext(NOOP_NEXT)`
+    // guard are unchanged — one state machine + one microtask hop removed. A
+    // synchronous throw from `match()` itself is still converted to a rejection
+    // by the composer's `try/catch` that wraps this middleware call.
+    return routeMatch.executor
+      ? routeMatch.executor(ctx)
+      : // Fallback (no pre-compiled executor — shouldn't happen): wrap so a void
+        // or thenable return still yields a Promise<void> and never a sync throw.
+        Promise.resolve(routeMatch.handler(ctx, NOOP_NEXT));
+  };
+}
+
+/**
+ * Build the allowed-methods middleware.
+ *
+ * Runs after the dispatch middleware: if the request was a 404, it does a
+ * single tree walk to collect every method registered for the path. An
+ * `OPTIONS` request gets a `200` with an `Allow` header; any other method
+ * gets a `405` with `Allow`. If no method is registered for the path it
+ * leaves the 404 untouched.
+ *
+ * @param root - Trie root to walk for allowed methods.
+ * @param caseSensitive - Router case-sensitivity option.
+ * @param strict - Router strict-trailing-slash option.
+ */
+export function createAllowedMethodsMiddleware(
+  root: TrieNode,
+  caseSensitive: boolean,
+  strict: boolean
+): Middleware {
+  return async (ctx: Context, next?: () => Promise<void>): Promise<void> => {
+    if (next) {
+      await next();
+    }
+
+    if (ctx.status !== 404) return;
+
+    // Single tree walk to find all allowed methods instead of N×match()
+    const allowed = findAllowedMethods(ctx.path, root, caseSensitive, strict);
+
+    if (allowed.length === 0) return;
+
+    const allowHeader = allowed.join(', ');
+
+    // If OPTIONS request, respond with allowed methods
+    if (ctx.method === 'OPTIONS') {
+      ctx.status = 200;
+      ctx.set('Allow', allowHeader);
+      ctx.body = '';
+      return;
+    }
+
+    // Otherwise, return 405 Method Not Allowed
+    ctx.status = 405;
+    ctx.set('Allow', allowHeader);
+  };
+}

package/src/find-node.ts

@@ -0,0 +1,125 @@
+/**
+ * @nextrush/router - Method-agnostic trie walk (allowed-methods / 405 path)
+ *
+ * `findNode` + `findAllowedMethods` were split out of `matching.ts` when the
+ * iterative rewrite of `findNode` (HP-17, OpenSpec change
+ * `router-context-final-cleanup`) pushed that file past the 300-line ceiling.
+ * They form one cohesive concern — resolving the *node* for a path regardless
+ * of HTTP method, to answer OPTIONS/405 — distinct from `matching.ts`'s
+ * method-aware handler match (`matchNodeIndexed`) and its normalization
+ * primitives, which are reused here via import (`segmentAt`,
+ * `normalizePathForMatch`).
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { HttpMethod } from '@nextrush/types';
+import { normalizePathForMatch, segmentAt } from './matching';
+import type { TrieNode } from './segment-trie';
+
+/**
+ * One node in {@link findNode}'s explicit-stack walk. `stage` is a small state
+ * machine (0 = extract segment + try static, 1 = try param, 2 = try
+ * wildcard/backtrack) so a single frame can be revisited on backtrack without
+ * recursion. `next` is the start position of the following segment, captured
+ * once in stage 0 and reused when descending into the param branch.
+ */
+interface FindFrame {
+  node: TrieNode;
+  pos: number;
+  stage: 0 | 1 | 2;
+  next: number;
+}
+
+/**
+ * Walk the trie to find the node matching a path (ignoring HTTP method), the
+ * method-agnostic walker used by {@link findAllowedMethods} for the 405/OPTIONS
+ * path (design.md D3 / HP-17).
+ *
+ * Walks with an EXPLICIT stack instead of recursion — mirroring
+ * `matchNodeIndexed` — so a pathological segment count cannot overflow the call
+ * stack (the same DoS class HP-11 closed for the match path). Behavior is
+ * byte-identical to the former recursive walker: precedence is static > param >
+ * wildcard at each node, a partially-matching branch backtracks cleanly, the
+ * wildcard child is a terminal (it captures the remainder), and the first
+ * accepted terminal wins. The scalar {@link segmentAt} scan is reused so the
+ * traversal shares one segment-extraction helper rather than duplicating it.
+ *
+ * `path` is the already-normalized lookup path; `startPos` skips the leading
+ * `/` (callers pass `1`, matching `matchNodeIndexed`).
+ */
+export function findNode(root: TrieNode, path: string, startPos: number): TrieNode | null {
+  const stack: FindFrame[] = [{ node: root, pos: startPos, stage: 0, next: 0 }];
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame === undefined) break;
+
+    // Stage 0 — first visit: terminal check, then try the static child.
+    if (frame.stage === 0) {
+      // Whole path consumed at this node → it is the matching node.
+      if (frame.pos >= path.length) {
+        return frame.node;
+      }
+      const seg = segmentAt(path, frame.pos);
+      // An empty segment means the path is exhausted here (e.g. a strict-mode
+      // trailing slash) — treat this node as the terminal, as the recursive
+      // walk did after `split('/').filter(Boolean)` dropped empty segments.
+      if (seg === '') {
+        return frame.node;
+      }
+      // `segmentAt` already scanned to the next `/`; derive the following
+      // position from the segment length (no second indexOf) — a slash follows
+      // iff the segment ended before the path did.
+      const segEnd = frame.pos + seg.length;
+      frame.next = segEnd < path.length ? segEnd + 1 : path.length;
+      frame.stage = 1;
+      const staticChild = frame.node.children.get(seg);
+      if (staticChild) {
+        stack.push({ node: staticChild, pos: frame.next, stage: 0, next: 0 });
+      }
+      continue;
+    }
+
+    // Stage 1 — static child (if any) failed: try the param child.
+    if (frame.stage === 1) {
+      frame.stage = 2;
+      if (frame.node.paramChild) {
+        stack.push({ node: frame.node.paramChild, pos: frame.next, stage: 0, next: 0 });
+      }
+      continue;
+    }
+
+    // Stage 2 — static and param branches exhausted: the wildcard child is a
+    // terminal (matches the remainder). Otherwise this branch fails; backtrack.
+    if (frame.node.wildcardChild) {
+      return frame.node.wildcardChild;
+    }
+    stack.pop();
+  }
+
+  return null;
+}
+
+/**
+ * Find all HTTP methods registered for a given path via a single tree walk.
+ * `caseSensitive`/`strict` (formerly `this.opts.*`) and `root` (formerly
+ * `this.root`) are threaded explicitly.
+ */
+export function findAllowedMethods(
+  path: string,
+  root: TrieNode,
+  caseSensitive: boolean,
+  strict: boolean
+): HttpMethod[] {
+  const normalized = normalizePathForMatch(path, caseSensitive, strict);
+
+  // Walk from position 1 to skip the leading '/', matching `matchNodeIndexed`'s
+  // start offset. The iterative `findNode` scans segments off the path in place,
+  // so no `split('/')` array is allocated here.
+  const node = findNode(root, normalized, 1);
+  if (!node || node.handlers.size === 0) return [];
+
+  return Array.from(node.handlers.keys());
+}