@nextrush/router 3.0.7 → 4.0.0-beta.1

package/src/matching.ts

@@ -0,0 +1,246 @@
+/**
+ * @nextrush/router - Route Matching Engine
+ *
+ * The segment-trie lookup logic extracted from the `Router` class (T014,
+ * design.md D1). These are standalone pure functions taking the trie root and
+ * other needed state as explicit parameters — not methods — so the matching
+ * engine has no implicit dependency on broader `Router` instance state beyond
+ * what's passed in. `Router` becomes a thin delegating shell around these.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { HttpMethod } from '@nextrush/types';
+import type { HandlerEntry, TrieNode } from './segment-trie';
+import { matchNodeIndexedPooled, type WalkFrame, type WalkPool } from './walk-pool';
+
+export type { WalkFrame, WalkPool } from './walk-pool';
+export { createWalkPool } from './walk-pool';
+
+/**
+ * Percent-decode an extracted param/wildcard value when `decode` is enabled.
+ * Fast-paths values with no `%`, and falls back to the raw value on malformed
+ * encoding (decodeURIComponent throws a URIError) so a bad request never crashes
+ * routing.
+ */
+export function decodeParam(value: string, decode: boolean): string {
+  if (!decode || !value.includes('%')) return value;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Return the path segment starting at `start`, up to the next `/` (or end).
+ * Scalar — no tuple array (the iterative walk tracks the next position itself).
+ * Used to recover an original-case param value from the original-case path at a
+ * position already validated against the (folded) lookup path, and by the
+ * {@link findNode} allowed-methods walk to scan segments off the lookup path.
+ */
+export function segmentAt(path: string, start: number): string {
+  const slashPos = path.indexOf('/', start);
+  return slashPos === -1 ? path.slice(start) : path.slice(start, slashPos);
+}
+
+/**
+ * True only when `path.toLowerCase()` is provably a no-op: every character is
+ * ASCII (`<= 0x7F`) and none is an ASCII uppercase letter (`A`–`Z`). Any
+ * non-ASCII byte is treated as UNCERTAIN (it could be uppercase like `Ü`), so
+ * this returns `false` and the caller folds — never skipping unicode case
+ * folding (design.md D3). This lets `normalizePathForMatch` skip the
+ * `toLowerCase()` allocation for the overwhelmingly common all-lowercase-ASCII
+ * request path while staying byte-identical to always folding.
+ */
+export function isProvablyLowerAscii(path: string): boolean {
+  for (let i = 0; i < path.length; i++) {
+    const c = path.charCodeAt(i);
+    if ((c >= 0x41 && c <= 0x5a) || c > 0x7f) return false;
+  }
+  return true;
+}
+
+/**
+ * Structural match-time normalization WITHOUT case folding: collapse repeated
+ * slashes and strip a single trailing slash (unless `strict`). Split out of
+ * {@link normalizePathForMatch} so the case-fold decision and the structural
+ * pass are separable — `matchRoute` reuses this to build the original-case path
+ * only when a fold actually happened (HP-12), rather than running the full
+ * normalize twice.
+ */
+export function collapseAndStrip(path: string, strict: boolean): string {
+  let normalized = path;
+
+  // Fast-path: skip the regex when there are no double slashes (99%+ of requests).
+  if (normalized.includes('//')) {
+    normalized = normalized.replace(/\/+/g, '/');
+  }
+
+  // Non-strict mode treats a trailing slash as insignificant; strict keeps it.
+  if (!strict && normalized.length > 1 && normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize a request path for segment-trie matching: fold case (unless
+ * `caseSensitive`), collapse repeated slashes, and strip a single trailing
+ * slash (unless `strict`). This is the one definition of the match-time
+ * normalization rules, shared by `matchRoute` (in `match-route.ts`) and
+ * {@link findAllowedMethods}.
+ *
+ * The `toLowerCase()` call is skipped when the path is provably case-stable
+ * ({@link isProvablyLowerAscii}) — byte-identical to always folding, but with
+ * no throwaway string on the common all-lowercase-ASCII path (HP-12 / D3).
+ *
+ * Query-string removal is intentionally NOT done here — it is caller-specific:
+ * `matchRoute` strips the query before calling, while `findAllowedMethods`
+ * receives an already query-free `ctx.path`. Pass `caseSensitive: true` to
+ * normalize while preserving case (used by `matchRoute` to build the
+ * original-case path from which param values are extracted).
+ *
+ * NOTE: registration-time normalization (`Router.normalizePath`) is a separate
+ * concern — it joins the router prefix, guarantees a leading slash, and never
+ * folds case — so it deliberately does not share this helper.
+ */
+export function normalizePathForMatch(
+  path: string,
+  caseSensitive: boolean,
+  strict: boolean
+): string {
+  const folded = caseSensitive || isProvablyLowerAscii(path) ? path : path.toLowerCase();
+  return collapseAndStrip(folded, strict);
+}
+
+/**
+ * One node in the iterative walk's explicit stack — see the full doc comment
+ * on {@link WalkFrame} in `walk-pool.ts` (re-exported here for callers that
+ * only import from `matching.ts`).
+ */
+
+/**
+ * Iterative, index-based segment-trie match (HP-11 / HP-13, design.md D4).
+ *
+ * Walks the trie with an EXPLICIT stack instead of recursion, so a pathological
+ * segment count cannot overflow the call stack (DoS safety) — behavior is
+ * otherwise byte-identical to the former recursive matcher: precedence is
+ * static > param > wildcard at each node, a partially-matching branch backtracks
+ * cleanly, and the first accepted terminal wins.
+ *
+ * Param/wildcard bindings are DEFERRED onto the caller-owned `bindNames` /
+ * `bindValues` stacks and popped on backtrack, so params are materialized ONCE
+ * on the accepted terminal by the caller (no eager bind + backtrack
+ * `Reflect.deleteProperty`, and no `Object.keys` post-loop — the caller reads
+ * the bind count). `decode` runs strictly on the already-split segment/remainder
+ * (design.md D9), so an encoded slash/dot decodes into the value only and can
+ * never create new path segments.
+ *
+ * `originalPath` (present only when case-folding actually occurred) supplies the
+ * original-case param value at the same position as the folded lookup path.
+ */
+export function matchNodeIndexed(
+  root: TrieNode,
+  path: string,
+  startPos: number,
+  bindNames: string[],
+  bindValues: string[],
+  method: HttpMethod,
+  decode: boolean,
+  originalPath?: string,
+  /**
+   * When provided, the walk indexes into `pool.frames` by depth (reusing
+   * each pre-allocated frame object in place) instead of `push`/`pop`-ing
+   * fresh frame literals onto a fresh array — see `walk-pool.ts`'s
+   * `matchNodeIndexedPooled`. Omitted, the walk behaves exactly as before (a
+   * fresh `stack: WalkFrame[]`) — every other caller of `matchNodeIndexed`
+   * keeps its current behavior unchanged.
+   */
+  pool?: WalkPool
+): HandlerEntry | null {
+  if (pool) {
+    return matchNodeIndexedPooled(root, path, startPos, bindNames, bindValues, method, decode, pool, originalPath);
+  }
+  const stack: WalkFrame[] = [
+    { node: root, pos: startPos, stage: 0, seg: '', next: 0, bound: false },
+  ];
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame === undefined) break;
+
+    // Stage 0 — first visit: terminal checks, then try the static child.
+    if (frame.stage === 0) {
+      if (frame.pos >= path.length) {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler; // accepted — bind stacks hold this path's params
+        stack.pop();
+        continue;
+      }
+      const slashPos = path.indexOf('/', frame.pos);
+      if (slashPos === -1) {
+        frame.seg = path.slice(frame.pos);
+        frame.next = path.length;
+      } else {
+        frame.seg = path.slice(frame.pos, slashPos);
+        frame.next = slashPos + 1;
+      }
+      if (frame.seg === '') {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler;
+        stack.pop();
+        continue;
+      }
+      frame.stage = 1;
+      const staticChild = frame.node.children.get(frame.seg);
+      if (staticChild) {
+        stack.push({ node: staticChild, pos: frame.next, stage: 0, seg: '', next: 0, bound: false });
+      }
+      continue;
+    }
+
+    // Stage 1 — static child (if any) has failed: try the param child, deferring
+    // its binding onto the shared stacks.
+    if (frame.stage === 1) {
+      frame.stage = 2;
+      const paramChild = frame.node.paramChild;
+      if (paramChild) {
+        const paramName = paramChild.paramName;
+        if (paramName === undefined) return null; // degenerate param node → whole walk fails (as before)
+        const value =
+          originalPath !== undefined
+            ? decodeParam(segmentAt(originalPath, frame.pos), decode)
+            : decodeParam(frame.seg, decode);
+        bindNames.push(paramName);
+        bindValues.push(value);
+        frame.bound = true;
+        stack.push({ node: paramChild, pos: frame.next, stage: 0, seg: '', next: 0, bound: false });
+      }
+      continue;
+    }
+
+    // Stage 2 — param branch (if taken) failed: undo its deferred bind, then try
+    // the wildcard child (a terminal — it captures the original-case remainder).
+    if (frame.bound) {
+      bindNames.pop();
+      bindValues.pop();
+      frame.bound = false;
+    }
+    const wildcardChild = frame.node.wildcardChild;
+    if (wildcardChild) {
+      const src = originalPath ?? path;
+      bindNames.push('*');
+      bindValues.push(decodeParam(src.slice(frame.pos), decode));
+      const handler = wildcardChild.handlers.get(method);
+      if (handler) return handler;
+      bindNames.pop();
+      bindValues.pop();
+    }
+    stack.pop();
+  }
+
+  return null;
+}

package/src/middleware-adapter.ts

@@ -0,0 +1,59 @@
+/**
+ * @nextrush/router - Middleware Adaptation
+ *
+ * Router-level-middleware sealing logic extracted from the `Router` class
+ * (T014, design.md D3 — extracted after the matching-engine and composition
+ * splits left `router.ts` still over the 300-line ceiling).
+ *
+ * The tree-walk that re-compiles every handler's executor is structurally
+ * pure (it only mutates the `TrieNode`/`HandlerEntry` structures passed in,
+ * same shape as `copyRoutes` in `composition.ts`) — it doesn't touch
+ * `Router`-only state like `_sealed`, so it extracts cleanly. `routes()` and
+ * `allowedMethods()` stay on `Router`: both return closures that capture
+ * `this` (for `this.match`, `this.opts`, `this.root`) and are the router's
+ * actual public middleware-producing API, not internal tree mechanics.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import { compileExecutor, type StaticRouteMap, type TrieNode } from './segment-trie';
+import type { Middleware } from '@nextrush/types';
+
+/**
+ * Re-compile every route executor in the trie (plus the static-route hash
+ * map) to include router-level middleware ahead of each route's own
+ * middleware. Idempotency (guarding against a double seal) is the caller's
+ * responsibility — this function always re-walks and re-compiles.
+ */
+export function sealRouterMiddleware(
+  root: TrieNode,
+  staticRoutes: StaticRouteMap,
+  routerMiddleware: Middleware[]
+): void {
+  const routerMw = [...routerMiddleware];
+
+  const walk = (node: TrieNode): void => {
+    for (const [method, entry] of node.handlers) {
+      const combinedMw = [...routerMw, ...entry.middleware];
+      entry.executor = compileExecutor(entry.handler, combinedMw);
+      node.handlers.set(method, entry);
+    }
+    for (const [, child] of node.children) {
+      walk(child);
+    }
+    if (node.paramChild) walk(node.paramChild);
+    if (node.wildcardChild) walk(node.wildcardChild);
+  };
+
+  walk(root);
+
+  // Also update static route entries (method-nested map, HP-9).
+  for (const [, methodMap] of staticRoutes) {
+    for (const [key, entry] of methodMap) {
+      const combinedMw = [...routerMw, ...entry.middleware];
+      entry.executor = compileExecutor(entry.handler, combinedMw);
+      methodMap.set(key, entry);
+    }
+  }
+}

package/src/redirect.ts

@@ -0,0 +1,97 @@
+/**
+ * @nextrush/router - Redirect Handler Compilation
+ *
+ * Single, shared redirect implementation used by both `Router.redirect()` and
+ * route groups (audit RT-4). Previously the group variant used a naive
+ * `replaceAll(':key', value)` that could mis-substitute overlapping param names
+ * and re-scanned the string per request; this precompiles the target template
+ * once and only substitutes route-style `:param` slots (a `:` at position 0 or
+ * preceded by `/`), so `https://` and other literal colons are never touched.
+ *
+ * @packageDocumentation
+ */
+
+import type { Context, RouteHandler } from '@nextrush/types';
+
+/** HTTP redirect status codes supported by `redirect()`. */
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+
+/**
+ * Precompile a redirect target into alternating literal / param-name parts.
+ *
+ * @param to - Target path/URL, possibly containing `:param` placeholders.
+ * @returns A parts array (`[literal, paramName, literal, …]`) when `to` has
+ *   route-style params, otherwise `undefined` (a static target).
+ */
+export function compileRedirectTarget(to: string): string[] | undefined {
+  const parts: string[] = [];
+  let pos = 0;
+  let found = false;
+
+  while (pos < to.length) {
+    let idx = -1;
+    for (let i = pos; i < to.length; i++) {
+      if (to[i] === ':' && (i === 0 || to[i - 1] === '/') && i + 1 < to.length && to[i + 1] !== '/') {
+        idx = i;
+        break;
+      }
+    }
+    if (idx === -1) break;
+
+    found = true;
+    parts.push(to.slice(pos, idx)); // literal before ':'
+    const end = to.indexOf('/', idx + 1);
+    if (end === -1) {
+      parts.push(to.slice(idx + 1)); // param name (rest of string)
+      pos = to.length;
+    } else {
+      parts.push(to.slice(idx + 1, end)); // param name
+      pos = end;
+    }
+  }
+
+  if (found) {
+    parts.push(to.slice(pos)); // trailing literal
+    return parts;
+  }
+  return undefined;
+}
+
+/**
+ * Build the redirect route handler for a `to`/`status` pair. Substitutes any
+ * `:param` placeholders from `ctx.params` using the precompiled template.
+ *
+ * @param to - Target path/URL.
+ * @param status - Redirect status code.
+ * @returns A {@link RouteHandler} that sets `Location` and the status.
+ */
+export function createRedirectHandler(to: string, status: RedirectStatus): RouteHandler {
+  const compiledParts = compileRedirectTarget(to);
+
+  return (ctx: Context) => {
+    let targetPath: string;
+
+    if (compiledParts) {
+      const params = ctx.params;
+      const head = compiledParts[0];
+      if (head === undefined) {
+        targetPath = to;
+      } else {
+        let result = head;
+        for (let i = 1; i < compiledParts.length - 1; i += 2) {
+          const paramKey = compiledParts[i];
+          const tail = compiledParts[i + 1];
+          if (paramKey === undefined || tail === undefined) break;
+          result += (params[paramKey] ?? '') + tail;
+        }
+        targetPath = result;
+      }
+    } else {
+      targetPath = to;
+    }
+
+    ctx.status = status;
+    ctx.set('Location', targetPath);
+    ctx.body = '';
+  };
+}