feat(routerama): add HTTP routing crates by geeknoid · Pull Request #570 · microsoft/oxidizer

geeknoid · 2026-07-14T01:59:00Z

Introduce the routerama family of crates:

routerama: blazingly fast HTTP routing (static + dynamic routers).
routerama_build: build-time router code generator.
routerama_macros: procedural macros for the routerama crate.

These build on the http_path_template crate for path-template parsing.

github-actions · 2026-07-14T02:03:08Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Introduces the new routerama family of crates to the Oxidizer workspace, providing compile-time generated HTTP routing (routes! / build-time generator) plus an optional runtime router (DynRouter) that is intended to match identically to the static backend by walking the same shared trie IR.

Changes:

Adds new crates: routerama (facade + runtime), routerama_build (generator + shared trie IR), and routerama_macros (proc-macro front door).
Adds correctness/differential tests, examples, and benchmarking/reporting infrastructure for static vs dynamic routing and comparisons vs other routers.
Wires the new crates into the workspace (dependencies, lockfile, top-level README/changelog links, spelling dictionary).

Reviewed changes

Copilot reviewed 47 out of 48 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
README.md	Adds `routerama` to the workspace crate list.
crates/routerama/tests/routes_macro.rs	Behavioral tests for `routes!` macro output.
crates/routerama/tests/generated_router.rs	Drift-guard tests for the committed benchmark router fixture.
crates/routerama/tests/dynamic_parity.rs	Differential tests asserting `DynRouter` matches static routing behavior.
crates/routerama/src/route.rs	Defines core routing traits (`Route`, `RouteMatch`, `Router`).
crates/routerama/src/lib.rs	Crate-level docs and re-exports for macros/build/dynamic APIs.
crates/routerama/src/dynamic.rs	Runtime router implementation plus `EitherRouter` composition.
crates/routerama/src/codegen_helpers/scan.rs	Shared scan/split primitives used by generated routers and runtime router.
crates/routerama/src/codegen_helpers/mod.rs	Exposes codegen helper API surface for generated code.
crates/routerama/scripts/perf_report.rs	Nightly `-Zscript` benchmark runner + PERF.md generator + router regeneration.
crates/routerama/README.md	Crate README (doc2readme output).
crates/routerama/logo.png	Adds crate logo asset (Git LFS pointer).
crates/routerama/favicon.ico	Adds crate favicon asset (Git LFS pointer).
crates/routerama/examples/support/bookstore_router.rs	Committed generated router used by build-script example.
crates/routerama/examples/routing.rs	Static-routing example using `routes!`.
crates/routerama/examples/hybrid_routing.rs	Example composing static router with dynamic overlay via `EitherRouter`.
crates/routerama/examples/dynamic_routing.rs	Runtime-routing example using `DynRouter`.
crates/routerama/examples/build_script.rs	Example showing build-time generation usage pattern.
crates/routerama/docs/PERF.md	Committed performance report output.
crates/routerama/CHANGELOG.md	Initial crate changelog content.
crates/routerama/Cargo.toml	Crate manifest: features, deps, benches/examples, external-types allowlist.
crates/routerama/benches/gungraun_routers.rs	Callgrind (gungraun) benchmark suite.
crates/routerama/benches/criterion_routers.rs	Criterion benchmark suite.
crates/routerama/benches/common/routes_data.rs	Shared benchmark route/lookup data.
crates/routerama/benches/common/harness.rs	Shared benchmark harness building/comparing multiple routers.
crates/routerama/benches/common/generated_router.rs	Committed generated router for benchmarks.
crates/routerama_macros/src/lib.rs	`routes!` procedural macro implementation and parsing.
crates/routerama_macros/README.md	Proc-macro crate README (doc2readme output).
crates/routerama_macros/logo.png	Adds macros crate logo asset (Git LFS pointer).
crates/routerama_macros/favicon.ico	Adds macros crate favicon asset (Git LFS pointer).
crates/routerama_macros/CHANGELOG.md	Initial proc-macro crate changelog content.
crates/routerama_macros/Cargo.toml	Proc-macro crate manifest.
crates/routerama_build/src/trie.rs	Shared trie IR + precedence rules + capture planning.
crates/routerama_build/src/route_rule.rs	`RouteRule` definition and template handling.
crates/routerama_build/src/lib.rs	Build crate module structure + public re-exports (mostly doc-hidden).
crates/routerama_build/src/http_method.rs	`HttpMethod` enum + helpers.
crates/routerama_build/src/generator.rs	`Generator` API for producing router code (codegen feature).
crates/routerama_build/src/generator_builder.rs	`GeneratorBuilder` configuration surface.
crates/routerama_build/README.md	Build crate README (doc2readme output).
crates/routerama_build/logo.png	Adds build crate logo asset (Git LFS pointer).
crates/routerama_build/favicon.ico	Adds build crate favicon asset (Git LFS pointer).
crates/routerama_build/CHANGELOG.md	Initial build crate changelog content.
crates/routerama_build/Cargo.toml	Build crate manifest + `codegen` feature flag.
CHANGELOG.md	Adds `routerama` to the workspace changelog index.
Cargo.toml	Adds workspace deps for new crates and benchmark comparison crates.
Cargo.lock	Locks new workspace deps and benchmark dependencies.
.spelling	Adds router-related vocabulary to spellcheck dictionary.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

codecov · 2026-07-14T02:12:21Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.8%. Comparing base (2cf0ffe) to head (1d0d1db).

❌ Your project check has failed because the head coverage (99.8%) is below the target coverage (100.0%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #570     +/-   ##
========================================
- Coverage   100.0%   99.8%   -0.2%     
========================================
  Files         360     369      +9     
  Lines       27886   29640   +1754     
========================================
+ Hits        27886   29586   +1700     
- Misses          0      54     +54

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

github-actions · 2026-07-14T02:56:12Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 2 comments.

github-actions · 2026-07-14T03:37:34Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 1 comment.

github-actions · 2026-07-14T04:05:17Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 3 comments.

github-actions · 2026-07-14T04:34:01Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated no new comments.

github-actions · 2026-07-14T05:18:47Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Copilot reviewed 51 out of 54 changed files in this pull request and generated 7 comments.

github-actions · 2026-07-14T05:26:29Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Copilot reviewed 51 out of 54 changed files in this pull request and generated 5 comments.

github-actions · 2026-07-14T05:37:04Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Copilot reviewed 51 out of 54 changed files in this pull request and generated 3 comments.

ralfbiedert · 2026-07-14T11:18:38Z

+//!   # #[cfg(feature = "macros")]
+//!   # fn main() {
+//!   routerama::routes! {
+//!       pub enum BookRoute {


I'm not very fond of this syntax. It introduces a new "language" to define an enum and its variants, and its unclear (at least reading top level docs so far) whether I need to use / match the variants myself; which would be bad for discoverability.

Hm ok, I now played with it and I see the merit of it being short; still the syntax is somewhat weird, esp. once you add a struct Foo; to it.

ralfbiedert · 2026-07-14T12:22:08Z

What's the story how this composes with axum or similar?

ralfbiedert · 2026-07-14T12:29:26Z

+//!
+//! A fixed set of built-in routes plus a set registered at run time can be served
+//! through one [`EitherRouter`] (requires the `dynamic` feature): declare a
+//! companion `struct` in `routes!` to get a zero-sized [`Router`] for the static


It's unclear from the examples or descriptions why I would want that. What does an ApiRouter give me that Api combined with an EitherRouter won't?
I suspect it has something to do with avoiding generics and / or naming an empty Api type, but if so that feels hacky.

ralfbiedert · 2026-07-14T12:35:50Z

To clarify, I think there's a deeper discussion about scope and composability of this with an actual web server using this. In Axum a Router<T> has an app state T, which is used for type-safely registering routes and resolving their dependencies; and a router there type-safely ties URL paths to functions to be invoked.

Maybe this here is still a router, but it feels less like one I'd expect coming from other Rust libs ... more of a "route decoder" (in lack of a better word)?

ralfbiedert · 2026-07-14T12:43:36Z

My Github UI is really sluggish on this PR, inlining a few more comments:

route_field_name why is this public? Does anyone need this, it's not like I can use reflection with that knowledge to actually "find" the field then
Router::resolve (method, path) should be impl AsRef<str>? Route::resolve has that already.
Not a fan of the Route Debug / Display supertraits. As a rule of thumb, supertraits should be minimal and actual methods needing something should ask for these in addition.
Why is there a HttpMethod enum, but resolve still accept strings for their method?

github-actions · 2026-07-14T14:20:58Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

geeknoid · 2026-07-14T14:24:18Z

@ralfbiedert

Fixed.

Fixed.

Removed.

The docs now explain the rationale. The API signature did change though, so it now transparently supports HttpMethod too.

Copilot

Pull request overview

Copilot reviewed 52 out of 55 changed files in this pull request and generated 5 comments.

Introduce the routerama family of crates: - routerama: blazingly fast HTTP routing (static + dynamic routers). - routerama_build: build-time router code generator. - routerama_macros: procedural macros for the routerama crate. These build on the http_path_template crate for path-template parsing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 867c37d0-9e7a-46b0-b5a9-dc9f551ed128

github-actions · 2026-07-14T14:59:57Z

✅ Version increments look sufficient

cargo semver-checks compared the 3 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
`routerama`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_build`	new crate	—	0.1.0	0.1.0	✅ ok
`routerama_macros`	new crate	—	0.1.0	0.1.0	✅ ok

View the check run

Copilot

Pull request overview

Copilot reviewed 52 out of 55 changed files in this pull request and generated no new comments.

Copilot AI review requested due to automatic review settings July 14, 2026 01:59

Copilot started reviewing on behalf of geeknoid July 14, 2026 02:00 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 14, 2026 02:54

geeknoid force-pushed the routerama branch from c08a07a to 87d3d44 Compare July 14, 2026 02:54

Copilot started reviewing on behalf of geeknoid July 14, 2026 02:55 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread crates/routerama/tests/routes_macro.rs Outdated

Comment thread CHANGELOG.md

Copilot AI review requested due to automatic review settings July 14, 2026 03:35

geeknoid force-pushed the routerama branch from 87d3d44 to 833a1e3 Compare July 14, 2026 03:35

Copilot started reviewing on behalf of geeknoid July 14, 2026 03:36 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread CHANGELOG.md

Copilot AI review requested due to automatic review settings July 14, 2026 04:02

geeknoid force-pushed the routerama branch from 833a1e3 to 487c070 Compare July 14, 2026 04:02

Copilot started reviewing on behalf of geeknoid July 14, 2026 04:03 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread crates/routerama/README.md

Comment thread crates/routerama_build/README.md

Comment thread crates/routerama_macros/README.md

Copilot AI review requested due to automatic review settings July 14, 2026 04:31

geeknoid force-pushed the routerama branch from 487c070 to 7d199fc Compare July 14, 2026 04:31

Copilot started reviewing on behalf of geeknoid July 14, 2026 04:32 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 14, 2026 05:16

geeknoid force-pushed the routerama branch from 7d199fc to 2097bcc Compare July 14, 2026 05:16

Copilot started reviewing on behalf of geeknoid July 14, 2026 05:17 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 14, 2026 05:24

geeknoid force-pushed the routerama branch from 2097bcc to b7fab06 Compare July 14, 2026 05:24

Copilot started reviewing on behalf of geeknoid July 14, 2026 05:25 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread crates/routerama/README.md

Comment thread crates/routerama_build/README.md

Comment thread crates/routerama_macros/README.md

Comment thread crates/routerama/src/route.rs

Comment thread crates/routerama/src/lib.rs

Copilot AI review requested due to automatic review settings July 14, 2026 05:35

geeknoid force-pushed the routerama branch from b7fab06 to 16fd69d Compare July 14, 2026 05:35

Copilot started reviewing on behalf of geeknoid July 14, 2026 05:36 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread crates/routerama/README.md

Comment thread crates/routerama_macros/README.md

Comment thread crates/routerama_build/README.md

sandersaares mentioned this pull request Jul 14, 2026

ci(semver): restore sticky PR comment for version-increment check #573

Open

ralfbiedert reviewed Jul 14, 2026

View reviewed changes

Comment thread crates/routerama/src/dynamic.rs

ralfbiedert reviewed Jul 14, 2026

View reviewed changes

Comment thread crates/routerama_build/src/generator_builder.rs Outdated

ralfbiedert reviewed Jul 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 14, 2026 14:19

geeknoid force-pushed the routerama branch from 16fd69d to 115eed7 Compare July 14, 2026 14:19

Copilot started reviewing on behalf of geeknoid July 14, 2026 14:20 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread crates/routerama/README.md

Comment thread crates/routerama_build/README.md

Comment thread crates/routerama_macros/README.md

Comment thread crates/routerama_build/src/trie.rs Outdated

Comment thread crates/routerama/examples/support/bookstore_router.rs Outdated

Copilot AI review requested due to automatic review settings July 14, 2026 14:58

geeknoid force-pushed the routerama branch from 115eed7 to 1d0d1db Compare July 14, 2026 14:58

Copilot started reviewing on behalf of geeknoid July 14, 2026 14:59 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Uh oh!

Conversation

geeknoid commented Jul 14, 2026

Uh oh!

github-actions Bot commented Jul 14, 2026

✅ Version increments look sufficient

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jul 14, 2026

✅ Version increments look sufficient

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 14, 2026

✅ Version increments look sufficient

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

github-actions Bot commented Jul 14, 2026

✅ Version increments look sufficient

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 14, 2026

✅ Version increments look sufficient

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

github-actions Bot commented Jul 14, 2026

✅ Version increments look sufficient

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 14, 2026

✅ Version increments look sufficient

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 14, 2026 •

edited

Loading