perf(router): index route matching for large route tables

[gerardp]

Route matching scanned every registered route in order on every request, so throughput depended on where a route sat in the table. With 1,000 static routes, a request for the last one served 51,492 req/s while a request for the first served 146,531.

This adds two indexes to the store and keeps the scan for tables small enough not to need them.

• Exact lookup for static routes. A static route joins a hash table keyed by its pattern, unless an earlier route matches that pattern. Only actual shadowing keeps a route out, so declaration order does not decide whether the table is populated.
• Static prefix narrowing. Routes are grouped by their leading static segments, and a request only consults the groups whose prefix its URL starts with. Groups also carry the routes that have no static prefix, so a top level /:param or /* route does not force a second pass.
• A one entry memo for the last matched URL per domain and method.
• Small tables skip the index. Slicing the path at every segment boundary costs more than scanning a short table, so the index is only consulted past 64 routes for a domain and method.

Registration order still decides which route wins. Each group is matched on its own and the winner with the lowest registration index is selected, which resolves to the same route as matching the whole table in order. Regex matchers, casts, optional parameters and wildcards are unaffected.

Results

Large table, 1,000 static and 100 dynamic routes:

Scenario	before	after	Change
static-first	146,531	152,943	+4.38%
static-last	51,492	153,769	+198.63%
dynamic-first	95,031	149,021	+56.81%
dynamic-last	84,518	148,567	+75.78%
alternating-static	74,272	151,535	+104.03%
alternating-dynamic	88,881	140,119	+57.65%
varied-static	77,501	151,383	+95.33%
varied-dynamic	89,318	137,559	+54.01%
varied-mixed	81,667	142,900	+74.98%

Small table, 83 routes shaped like an application's route file:

Scenario	before	after
varied-static	140,596	151,732
varied-dynamic	139,072	138,787
varied-mixed	138,816	144,024

Fastify runs as a control in every measurement and its numbers are recorded alongside. Full tables, the control, the noise floor and the raw JSON are in benchmarks/results/router-comparison.md.

Benchmark changes

The original workload declared every static route before any dynamic one, had no catch-all, and repeated a single URL per scenario. That combination hides what matching costs, and an earlier revision of this branch regressed small tables by up to 4% without the benchmark noticing.

BENCH_SHAPE=app now builds a table that places a dynamic route early among the static ones and closes with a top level param route and a catch-all. The varied-* scenarios spread requests over 25 paths across the table, so per-URL memoisation cannot answer them. The comparison document records that regressing revision next to the fixed one.

Notes for review

• The matching indexes added to StoreMethodNode are optional properties. The type is re-exported from the public ./types entry point, so making them required would break any code constructing that shape.
• The 64 route threshold is empirical, measured on an Apple M4. The crossover between a scan and the index sits between 50 and 100 routes depending on the table's shape.
• Matching was verified against the previous behaviour with a differential fuzz harness: 486,080 comparisons against matchit.match(url, <every token array in registration order>) over adversarial shadowing tables, generated tables, and add() interleaved with match(), in both shouldDecodeParam modes. No mismatches.
• The comparison document also records an intermediate revision of this work, where the prefix index was in place but static routes were still indexed only until the first non static registration. That revision regressed the small table, and it is kept in the results as the reason the workload above exists.