@nextrush/router 3.0.6 → 4.0.0-beta.0

package/src/__tests__/audit-fixes.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @nextrush/router - Audit Remediation Tests
+ *
+ * RT-1 (reset clears the introspection registry), RT-5 (param-name conflict
+ * throws at registration), RT-7 (routes() is idempotent — no double-seal).
+ */
+
+import type { Context } from '@nextrush/types';
+import { describe, expect, it, vi } from 'vitest';
+import { createRouter } from '../router';
+
+// ---------------------------------------------------------------------------
+// RT-1 — reset() must also clear routeDefinitions (getRoutes introspection)
+// ---------------------------------------------------------------------------
+
+describe('RT-1: reset() clears the introspection registry', () => {
+  it('getRoutes() is empty after reset()', () => {
+    const router = createRouter();
+    router.get('/users', vi.fn());
+    router.get('/users/:id', vi.fn());
+    expect(router.getRoutes().length).toBeGreaterThan(0);
+
+    router.reset();
+    expect(router.getRoutes()).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RT-5 — conflicting param names at the same position must throw, not warn
+// ---------------------------------------------------------------------------
+
+describe('RT-5: param-name conflict throws at registration', () => {
+  it('throws when the same position uses two different param names', () => {
+    const router = createRouter();
+    router.get('/users/:id', vi.fn());
+    expect(() => router.get('/users/:userId/posts', vi.fn())).toThrow(/param/i);
+  });
+
+  it('does not throw when the param name is consistent', () => {
+    const router = createRouter();
+    router.get('/users/:id', vi.fn());
+    expect(() => router.get('/users/:id/posts', vi.fn())).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RT-7 — routes() called twice must not seal router middleware twice
+// ---------------------------------------------------------------------------
+
+describe('RT-7: routes() is idempotent w.r.t. router middleware sealing', () => {
+  it('runs router-level middleware exactly once even if routes() is called twice', async () => {
+    const router = createRouter();
+    const calls = { n: 0 };
+    router.use(async (_ctx: Context, next) => {
+      calls.n++;
+      if (next) await next();
+    });
+    router.get('/x', (ctx: Context) => {
+      ctx.body = 'ok';
+    });
+
+    router.routes();
+    router.routes(); // second call must not re-seal
+
+    const match = router.match('GET', '/x');
+    expect(match).not.toBeNull();
+    const ctx = { method: 'GET', path: '/x', params: {}, body: undefined } as unknown as Context;
+    await match!.executor!(ctx);
+    expect(calls.n).toBe(1);
+  });
+});

package/src/__tests__/dispatch-deasync.test.ts

@@ -0,0 +1,312 @@
+/**
+ * @nextrush/router — Dispatch de-async regression contract (NF-1)
+ *
+ * Executable contract for OpenSpec change
+ * `hot-path-dispatch-deasync-and-lazy-state`. The router's primary dispatch
+ * middleware (`createRoutesMiddleware`, dispatch.ts) and the no-middleware
+ * (`len === 0`) compiled executor (`compileExecutor`, segment-trie.ts) forward
+ * the route's promise directly instead of crossing an extra `async` frame,
+ * while preserving every observable dispatch semantic.
+ *
+ * Two kinds of tests:
+ *  - STRUCTURAL PROBES (RED before the change): the de-async is proven by
+ *    PROMISE IDENTITY — a non-`async` `createRoutesMiddleware` returns the exact
+ *    promise its executor returned, and a non-`async` `len === 0` executor
+ *    returns a native handler promise unwrapped (`Promise.resolve(p) === p`).
+ *    An `async` wrapper necessarily allocates a NEW promise, so these fail
+ *    against the current code and pass only once the frames are removed.
+ *  - BEHAVIOR CONTRACTS (guarding a *correct* de-async): sync-throw → reject,
+ *    async/returned-promise rejection propagation, thenable adoption (RED
+ *    against a naive `instanceof Promise` de-async that would drop it),
+ *    non-`Error` wrapping, the 404 → `next()` fall-through, the load-bearing
+ *    `setNext(NOOP_NEXT)` chain termination (RED against a de-async that drops
+ *    the guard), and the untouched `len >= 1` chain.
+ */
+
+import type { Context, RouteHandler } from '@nextrush/types';
+import { compose } from '@nextrush/core';
+import { describe, expect, it, vi } from 'vitest';
+import { createRoutesMiddleware } from '../dispatch';
+import { compileExecutor } from '../segment-trie';
+import { createRouter, type Router } from '../router';
+
+/**
+ * Context mock whose setNext/next behave like a real adapter context:
+ * setNext stores the wired next; ctx.next() invokes it. Mirrors the helper in
+ * middleware-pipeline.test.ts so dispatch behavior is exercised realistically.
+ */
+function createCtx(overrides: Partial<Context> = {}): Context {
+  let stored: () => Promise<void> = () => Promise.resolve();
+  return {
+    method: 'GET',
+    path: '/',
+    params: {},
+    query: {},
+    body: undefined,
+    headers: {},
+    status: 200,
+    state: {},
+    responded: false,
+    json: vi.fn(),
+    send: vi.fn(),
+    html: vi.fn(),
+    redirect: vi.fn(),
+    set: vi.fn(),
+    get: vi.fn(),
+    setNext: (fn: () => Promise<void>) => {
+      stored = fn;
+    },
+    next: () => stored(),
+    raw: { req: {}, res: {} },
+    ...overrides,
+  } as unknown as Context;
+}
+
+const run = (router: Router, ctx: Context): Promise<void> =>
+  router.routes()(ctx, async () => {});
+
+/** Settle a promise into its resolution or rejection reason without throwing. */
+const settle = (p: Promise<unknown>): Promise<unknown> => p.then((v) => v, (e) => e);
+
+// ===========================================================================
+// §2.1 — no extra async frame (structural identity probes, RED before change)
+// ===========================================================================
+
+describe('NF-1 §2.1: dispatch forwards without an extra async frame', () => {
+  it('createRoutesMiddleware returns the executor promise directly (identity)', () => {
+    const sentinel = Promise.resolve();
+    const match = () => ({
+      params: {},
+      middleware: [],
+      executor: () => sentinel,
+      handler: (() => {}) as RouteHandler,
+    });
+    const mw = createRoutesMiddleware(match as never);
+
+    const returned = mw(createCtx());
+
+    // An `async` wrapper allocates a new promise; a direct forward returns the
+    // very promise the executor produced.
+    expect(returned).toBe(sentinel);
+  });
+
+  it('the len === 0 executor forwards a native handler promise unwrapped (identity)', () => {
+    const p = Promise.resolve();
+    const exec = compileExecutor((() => p) as RouteHandler, []);
+
+    // Promise.resolve(p) === p for a native promise; an `async` wrapper would
+    // return a distinct promise.
+    expect(exec(createCtx())).toBe(p);
+  });
+
+  it('a matched synchronous handler still produces a byte-identical response', async () => {
+    const router = createRouter();
+    router.get('/', ((ctx: Context) => {
+      ctx.json({ ok: true });
+    }) as RouteHandler);
+
+    const ctx = createCtx();
+    await run(router, ctx);
+
+    expect(ctx.json).toHaveBeenCalledWith({ ok: true });
+    expect(ctx.status).toBe(200);
+  });
+});
+
+// ===========================================================================
+// §2.2–§2.5 — error / return-shape propagation (behavior contracts)
+// ===========================================================================
+
+describe('NF-1 §2.2: a synchronous throw becomes a rejected promise', () => {
+  it('the executor never throws synchronously out of dispatch', async () => {
+    const exec = compileExecutor((() => {
+      throw new Error('sync boom');
+    }) as RouteHandler, []);
+
+    let returned: Promise<void> | undefined;
+    expect(() => {
+      returned = exec(createCtx());
+    }).not.toThrow();
+    await expect(returned).rejects.toThrow('sync boom');
+  });
+
+  it('a synchronous throw reaching the composer still rejects (reaches error handler)', async () => {
+    const router = createRouter();
+    router.get('/error', (() => {
+      throw new Error('kaboom');
+    }) as RouteHandler);
+
+    // compose wraps the router like the app does; the rejection must surface.
+    const stack = compose([router.routes()]);
+    await expect(stack(createCtx({ path: '/error' }), async () => {})).rejects.toThrow('kaboom');
+  });
+});
+
+describe('NF-1 §2.3: async / returned-promise rejections propagate', () => {
+  it('an async handler rejection propagates', async () => {
+    const exec = compileExecutor((async () => {
+      throw new Error('async boom');
+    }) as RouteHandler, []);
+    await expect(exec(createCtx())).rejects.toThrow('async boom');
+  });
+
+  it('a handler returning a rejected promise propagates', async () => {
+    const exec = compileExecutor((() =>
+      Promise.reject(new Error('rejected promise'))) as RouteHandler, []);
+    await expect(exec(createCtx())).rejects.toThrow('rejected promise');
+  });
+});
+
+describe('NF-1 §2.4: a thenable handler return is adopted (not dropped)', () => {
+  it('awaits a non-Promise thenable so its async work completes', async () => {
+    let sideEffectRan = false;
+    const thenable = {
+      then(resolve: (v?: unknown) => void): void {
+        setTimeout(() => {
+          sideEffectRan = true;
+          resolve();
+        }, 5);
+      },
+    };
+    const exec = compileExecutor((() => thenable) as unknown as RouteHandler, []);
+
+    await exec(createCtx());
+
+    // A naive `x instanceof Promise ? x : RESOLVED` de-async would drop the
+    // thenable and resolve immediately, leaving this false.
+    expect(sideEffectRan).toBe(true);
+  });
+});
+
+describe('NF-1 §2.5: a non-Error throw is wrapped as Error(String(thrown))', () => {
+  it.each([
+    ['a string', 'string-error', 'string-error'],
+    ['a number', 42, '42'],
+    ['null', null, 'null'],
+    ['undefined', undefined, 'undefined'],
+  ])('wraps %s', async (_label, thrown, expectedMessage) => {
+    const exec = compileExecutor((() => {
+      throw thrown;
+    }) as RouteHandler, []);
+
+    const err = await settle(exec(createCtx()));
+
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toBe(expectedMessage);
+  });
+});
+
+// ===========================================================================
+// §2.6 — miss → 404 → next() fall-through (allowedMethods 405)
+// ===========================================================================
+
+describe('NF-1 §2.6: a miss sets 404 and forwards next()', () => {
+  it('a known-path/unregistered-method miss becomes 405 with Allow via allowedMethods', async () => {
+    const router = createRouter();
+    router.get('/users', ((ctx: Context) => ctx.json([])) as RouteHandler);
+
+    const ctx = createCtx({ method: 'POST', path: '/users' });
+    // routes() sets 404 + forwards next; allowedMethods() (as next) turns it into 405.
+    await router.routes()(ctx, () => router.allowedMethods()(ctx, async () => {}));
+
+    expect(ctx.status).toBe(405);
+    expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('GET'));
+  });
+
+  it('a total miss with no next resolves and leaves 404', async () => {
+    const router = createRouter();
+    router.get('/users', (() => {}) as RouteHandler);
+
+    const ctx = createCtx({ method: 'GET', path: '/nope' });
+    await expect(router.routes()(ctx)).resolves.toBeUndefined();
+    expect(ctx.status).toBe(404);
+  });
+});
+
+// ===========================================================================
+// §2.7 — load-bearing setNext(NOOP_NEXT) chain termination (NF-4a KEPT)
+// ===========================================================================
+
+describe('NF-1 §2.7: setNext(NOOP_NEXT) terminates the chain at the handler', () => {
+  it('a route handler calling ctx.next() does NOT advance into app middleware after the router', async () => {
+    const router = createRouter();
+    let handlerNextResolved = false;
+    router.get('/', (async (ctx: Context) => {
+      await ctx.next(); // must be a safe no-op, NOT advance into appMw
+      handlerNextResolved = true;
+    }) as RouteHandler);
+
+    const appMw = vi.fn(async (_ctx: Context, next: () => Promise<void>) => {
+      await next();
+    });
+
+    // General compose dispatch: middleware mounted AFTER the router. compose
+    // wires ctx._next to advance into appMw before running the router; the
+    // executor's setNext(NOOP_NEXT) must overwrite that so the handler's
+    // ctx.next() cannot leak into appMw.
+    const stack = compose([router.routes(), appMw]);
+    await stack(createCtx(), async () => {});
+
+    expect(appMw).not.toHaveBeenCalled();
+    expect(handlerNextResolved).toBe(true);
+  });
+});
+
+// ===========================================================================
+// §2.8 — the len >= 1 per-route middleware chain is unchanged
+// ===========================================================================
+
+describe('NF-1 §2.8: the len >= 1 executor path is unchanged', () => {
+  it('preserves onion ordering across a 5-layer ctx.next() chain', async () => {
+    const router = createRouter();
+    const order: string[] = [];
+    const layer = (n: number) =>
+      (async (ctx: Context) => {
+        order.push(`${n}-before`);
+        await ctx.next();
+        order.push(`${n}-after`);
+      }) as never;
+
+    router.get(
+      '/',
+      layer(1),
+      layer(2),
+      layer(3),
+      layer(4),
+      layer(5),
+      (async () => {
+        order.push('handler');
+      }) as RouteHandler
+    );
+
+    await run(router, createCtx());
+
+    expect(order).toEqual([
+      '1-before',
+      '2-before',
+      '3-before',
+      '4-before',
+      '5-before',
+      'handler',
+      '5-after',
+      '4-after',
+      '3-after',
+      '2-after',
+      '1-after',
+    ]);
+  });
+
+  it('still rejects when a layer calls next() more than once', async () => {
+    const router = createRouter();
+    router.get(
+      '/',
+      (async (_ctx: Context, next: () => Promise<void>) => {
+        await next();
+        await next();
+      }) as never,
+      (async () => {}) as RouteHandler
+    );
+
+    await expect(run(router, createCtx())).rejects.toThrow('next() called multiple times');
+  });
+});

package/src/__tests__/find-node-differential.test.ts

@@ -0,0 +1,220 @@
+/**
+ * @nextrush/router - HP-17 findNode iterative-rewrite differential contract
+ *
+ * Regression + safety contract for OpenSpec change `router-context-final-cleanup`
+ * (HP-17). `findNode` (used by `findAllowedMethods`, the 405/OPTIONS path) is
+ * being rewritten from recursion to an explicit-stack walk so a pathological
+ * segment count can't overflow the call stack — the same DoS class HP-11 closed
+ * for the match path.
+ *
+ * This file pins two things:
+ *  1. DIFFERENTIAL PARITY — the production `findNode` returns the byte-identical
+ *     node (by reference) and `findAllowedMethods` the byte-identical method set
+ *     as a FROZEN reference copy of the pre-rewrite recursive walk, across a
+ *     corpus (static, nested static, param, wildcard, backtrack, trailing-slash,
+ *     method-miss, miss, precedence). The reference recursion is embedded here
+ *     because the old and new impls cannot coexist in one process (same
+ *     characterization technique as `match-differential.test.ts`'s golden).
+ *  2. DEEP-PATH SAFETY (RED before the rewrite) — a many-segment path resolves
+ *     without a stack overflow. This FAILS against the recursive form and PASSES
+ *     once `findNode` is iterative.
+ */
+
+import type { HttpMethod, RouteHandler } from '@nextrush/types';
+import { describe, expect, it } from 'vitest';
+import { findAllowedMethods, findNode } from '../find-node';
+import { normalizePathForMatch } from '../matching';
+import { addRoute, type RegistrationState } from '../registration';
+import { createNode, type TrieNode } from '../segment-trie';
+
+const noop: RouteHandler = async () => {
+  /* no-op */
+};
+
+/** Build a bare trie root from a route list, mirroring how `Router` inserts. */
+function buildRoot(
+  routes: ReadonlyArray<readonly [HttpMethod, string]>,
+  caseSensitive = false
+): TrieNode {
+  const root = createNode('');
+  const state: RegistrationState = {
+    root,
+    caseSensitive,
+    staticRoutes: new Map(),
+    routeDefinitions: [],
+  };
+  for (const [method, path] of routes) {
+    addRoute(method, path, [noop], [], state);
+  }
+  return root;
+}
+
+/**
+ * FROZEN reference copy of the PRE-REWRITE recursive `findNode`. The production
+ * `findNode` must stay byte-identical to this for every non-pathological input;
+ * it diverges only by being iterative (stack-safe), which the deep-path test
+ * covers separately.
+ */
+function findNodeRecursive(node: TrieNode, segments: string[], index: number): TrieNode | null {
+  if (index === segments.length) return node;
+  const segment = segments[index];
+  if (segment === undefined) return null;
+
+  const staticChild = node.children.get(segment);
+  if (staticChild) {
+    const result = findNodeRecursive(staticChild, segments, index + 1);
+    if (result) return result;
+  }
+  if (node.paramChild) {
+    const result = findNodeRecursive(node.paramChild, segments, index + 1);
+    if (result) return result;
+  }
+  if (node.wildcardChild) return node.wildcardChild;
+  return null;
+}
+
+/** Reference `findAllowedMethods` over the recursive walk (mirrors production). */
+function refAllowedMethods(
+  path: string,
+  root: TrieNode,
+  caseSensitive: boolean,
+  strict: boolean
+): HttpMethod[] {
+  const normalized = normalizePathForMatch(path, caseSensitive, strict);
+  const segments = normalized.split('/').filter(Boolean);
+  const node = findNodeRecursive(root, segments, 0);
+  if (!node || node.handlers.size === 0) return [];
+  return Array.from(node.handlers.keys());
+}
+
+/** Split a request path exactly as the pre-rewrite `findAllowedMethods` did. */
+function toSegments(path: string, caseSensitive: boolean, strict: boolean): string[] {
+  return normalizePathForMatch(path, caseSensitive, strict).split('/').filter(Boolean);
+}
+
+/** Production `findNode` over the normalized path (new path-based signature). */
+function prodNode(
+  path: string,
+  root: TrieNode,
+  caseSensitive: boolean,
+  strict: boolean
+): TrieNode | null {
+  return findNode(root, normalizePathForMatch(path, caseSensitive, strict), 1);
+}
+
+/** Reference `findNode` over the recursive walk (pre-rewrite segments-based). */
+function refNode(
+  path: string,
+  root: TrieNode,
+  caseSensitive: boolean,
+  strict: boolean
+): TrieNode | null {
+  return findNodeRecursive(root, toSegments(path, caseSensitive, strict), 0);
+}
+
+// A corpus exercising every findNode branch: static, nested static, param,
+// wildcard, backtracking, trailing slash (non-strict), method variety, misses.
+const ROUTES: ReadonlyArray<readonly [HttpMethod, string]> = [
+  ['GET', '/'],
+  ['GET', '/users'],
+  ['POST', '/users'],
+  ['GET', '/users/me'], // static beats param at this node
+  ['GET', '/users/:id'],
+  ['DELETE', '/users/:id'],
+  ['GET', '/a/b/c'], // nested static
+  ['GET', '/a/:x/c'], // backtracking target
+  ['GET', '/a/b/d'],
+  ['GET', '/files/*'], // wildcard (incl. empty capture)
+  ['GET', '/g/:x/*'], // param + trailing wildcard
+];
+
+const PROBES: readonly string[] = [
+  '/',
+  '/users',
+  '/users/',
+  '/users/me',
+  '/users/42',
+  '/users/42/',
+  '/a/b/c',
+  '/a/b/d',
+  '/a/b/x', // backtrack: static b fails at x → param :x=b
+  '/files', // wildcard empty capture
+  '/files/a/b/c', // wildcard multi-segment
+  '/g/1/rest/of/path', // param + trailing wildcard
+  '/nope', // miss
+  '/users/1/2/3', // overshoot miss
+  '//a//b//c', // repeated-slash collapse
+];
+
+describe('HP-17 — findNode iterative rewrite: differential parity with recursion', () => {
+  const root = buildRoot(ROUTES);
+
+  it.each(PROBES)('returns the identical node (by reference) for %s', (path) => {
+    expect(prodNode(path, root, false, false)).toBe(refNode(path, root, false, false));
+  });
+
+  it.each(PROBES)('findAllowedMethods returns the identical method set for %s', (path) => {
+    expect(findAllowedMethods(path, root, false, false)).toEqual(
+      refAllowedMethods(path, root, false, false)
+    );
+  });
+
+  it('preserves static > param > wildcard precedence at a shared node', () => {
+    // /p/me (static), /p/:id (param), /p/* (wildcard) all branch from /p.
+    const r = buildRoot([
+      ['GET', '/p/me'],
+      ['GET', '/p/:id'],
+      ['GET', '/p/*'],
+    ]);
+    // Static wins.
+    expect(findAllowedMethods('/p/me', r, false, false)).toEqual(['GET']);
+    // Param wins over wildcard for a single leftover segment.
+    const paramNode = prodNode('/p/other', r, false, false);
+    expect(paramNode).toBe(refNode('/p/other', r, false, false));
+    expect(paramNode?.paramName).toBe('id');
+    // Wildcard only when neither static nor param can complete.
+    const wildNode = prodNode('/p/a/b', r, false, false);
+    expect(wildNode).toBe(refNode('/p/a/b', r, false, false));
+    expect(wildNode?.type).toBe(2 /* NodeType.WILDCARD */);
+  });
+
+  it('returns null identically on a miss', () => {
+    expect(prodNode('/definitely/not/here', root, false, false)).toBeNull();
+    expect(refNode('/definitely/not/here', root, false, false)).toBeNull();
+  });
+
+  it('treats an empty segment as a terminal (defensive: startPos landing on a slash)', () => {
+    // Normalization collapses `//`, so findAllowedMethods never feeds an empty
+    // mid-segment; this exercises findNode's empty-segment guard directly. A
+    // walk position sitting on a `/` yields an empty segment, which the walker
+    // treats as "path exhausted here" and returns the current node.
+    const r = buildRoot([['GET', '/a']]);
+    // '/a/' walked from the leading slash: after 'a' the trailing slash makes
+    // the next position land at the end; feed a raw double-slash to hit the
+    // seg === '' branch at a non-terminal position.
+    const node = findNode(r, '/a//', 3);
+    expect(node).not.toBeNull();
+  });
+});
+
+describe('HP-17 — deep-path 405/OPTIONS safety (RED before the iterative rewrite)', () => {
+  it('resolves a very deep matching path without a stack overflow', () => {
+    const depth = 60_000;
+    const root = buildRoot([['GET', '/' + Array.from({ length: depth }, () => ':p').join('/')]]);
+    const deepPath = '/' + Array.from({ length: depth }, (_, i) => `x${i}`).join('/');
+    expect(() => findAllowedMethods(deepPath, root, false, false)).not.toThrow();
+    expect(findAllowedMethods(deepPath, root, false, false)).toEqual(['GET']);
+  });
+
+  it('misses a deep-but-overshooting path without a stack overflow', () => {
+    const depth = 60_000;
+    // A deep param chain that DOES descend `depth` levels, then the request
+    // overshoots by one segment — so the walk recurses the full depth before
+    // failing (unlike a shallow miss that bails at level 1). This is the real
+    // deep-recursion miss case, matching the DoS surface HP-11 closed.
+    const root = buildRoot([['GET', '/' + Array.from({ length: depth }, () => ':p').join('/')]]);
+    const overshoot = '/' + Array.from({ length: depth + 1 }, (_, i) => `x${i}`).join('/');
+    expect(() => findAllowedMethods(overshoot, root, false, false)).not.toThrow();
+    expect(findAllowedMethods(overshoot, root, false, false)).toEqual([]);
+  });
+});