perf(route): match routes by walking a trie of route segments

FA
3d ago
+318-24

All Submissions:

  • Have you followed the guidelines stated in CONTRIBUTING.md file?
  • Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

  • Performance improvement (non-breaking change): backend route matching

Describe your changes

get_router resolved a path by trying each route's regex in turn until one matched. Every event calls the router (EventNamespace.on_event, App.get_load_events). An lru_cache makes repeat paths a dictionary hit, but each new path paid one regex call per route.

RoutesRegex scan, new pathTrie, new path
101.19 µs0.48 µs
1005.38 µs0.49 µs
100049.11 µs0.49 µs

It also kept test_route_matching flaky after #7878. CodSpeed runs Python with PYTHONMALLOC=malloc, and every fullmatch allocates through glibc. That was about half the benchmark's measured time, and glibc's heap state moved it between 90 and 96.8 ms. 24 of the 59 CodSpeed reports on PRs based after #7878 flag it, including docs-only and README-only PRs.

The trie. Following the radix-trie design of routers like Rust's matchit:

  • Each level matches one path segment. Static children are keyed by the segment with ASCII letters lowercased. Each node has one child for [arg] and one for [[arg]], plus a slot for a [[...splat]] route.
  • Every route keeps the rank the regex scan tried it in: route_specificity, ties in the order given.
  • A lookup walks the path, collects the routes that match, and returns the lowest-ranked one. A branch whose best rank can't beat the current answer is skipped, so a typical lookup is a single walk down the path.

Unlike matchit, it doesn't let a static segment win at each position. The winner is still the route the regex scan picked, so on_load events resolve exactly as before.

Same matching rules as the regexes:

  • ASCII-only case folding (/\N{KELVIN SIGN}it still doesn't match kit).
  • One trailing slash stripped from the path, plus one more allowed by the route.
  • [arg] can match an empty segment.
  • [[arg]] matches nothing or one non-empty segment.
  • A catch-all stops at a newline, as the regex . did.
  • /index resolves to the index route.
  • Duplicate templates resolve as before.

test_get_router_matches_the_regex_scan keeps the old regex scan as a reference, built from the unchanged public get_route_regex and route_specificity. It checks that both pick the same route on 24,000 seeded random route tables and paths: mixed case, non-ASCII, empty segments, extra slashes, /index and newlines.

One behavior change: a [[...splat]] that isn't the route's last segment now raises ValueError in get_router. verify_route_validity already rejects such routes for every page added to an app, so only a direct get_router call with an invalid route sees it.

Benchmark. test_route_matching keeps only its 1000-route case, as a guard against going back to scanning every route, and now does 400 lookups per measured call (235 µs uninstrumented).

  • Before: running under CodSpeed's settings locally (PYTHONMALLOC=malloc, fixed cache sizes, no address randomization), changing only the size of the environment moved the old benchmark's instruction count by up to 3.7%.
  • Now: the instruction count moves 0.02% and the cache-weighted estimate 0.83%.

New Feature Submission:

  • Does your submission pass the tests?
  • Have you linted your code locally prior to submission?

Changes To Core Features:

  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your core changes, as applicable? The equivalence test above, plus explicit tests for ranking ties, segment edge cases and the catch-all error.
  • Have you successfully ran tests with your changes locally?
    • tests/units/test_route.py, tests/units/test_app.py and tests/units/utils/test_exec.py pass, as do ruff and pyright on the changed files.
    • The full unit run fails only in two places, and neither is from this change:
      • The Playwright tests in tests/units/reflex_bench/drivers/test_browser.py need a Chromium build this container doesn't have.
      • Two pyright errors in tests/units/components/graphing/test_plotly.py also fail on unmodified main locally.
    • CI runs everything.

https://claude.ai/code/session_01LwJUCWYQL5BocrPjnH5hFX


Generated by Claude Code