perf(templated_uri): reuse the rendered path across build and routing

Eliminate the redundant per-attempt template render and validation scan on the
per-request URI construction hot path. The templated path was rendered twice -
once in `HttpRequestBuilder::build` and again in `Router::resolve_request_uri`
(which only swaps the base, never the path) - and every base join re-parsed and
re-validated the whole path.

- `build` now renders the path once, caches it in a `RenderedPath` extension, and
  assembles the initial `http::Uri` by reuse (new `Uri::to_http_uri`).
- `resolve_request_uri` reuses that rendering to join only the resolved base on every
  attempt (never re-rendering), trusting the cache only for built requests.
- `BasePath::join_path_and_query` returns the already-validated path directly when the
  base path is root (`/`), skipping the allocation and re-validation scan.

Output-preserving (no `unsafe`), verified with differential tests. Benchmarks added
here; the isolated `hot_path_cg` and `escaped_string` benches are unchanged baselines.

| Benchmark (per attempt)   | Cycles before | Cycles after | Time before | Time after |
|---------------------------|--------------:|-------------:|------------:|-----------:|
| routing_rerender short    |          4126 |         1952 |      182 ns |      65 ns |
| routing_rerender heavy    |          7208 |         2173 |      352 ns |      65 ns |
| router_resolve root base  |          6322 |         4877 |      305 ns |     193 ns |
| router_resolve prefixed   |          6773 |         6133 |      308 ns |     261 ns |

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 10499452-0720-40ab-9e9f-506e1fd3ccaf

Author: Martin Taillefer

Cargo.lock

@@ -94,6 +94,10 @@ tick = { path = "../tick", features = ["test-util", "tokio"] }
 tokio = { workspace = true, features = ["macros", "rt-multi-thread", "net"] }
 uuid = { workspace = true }
 
+# Callgrind instruction-count benchmarks (Valgrind is Linux-only).
+[target.'cfg(target_os = "linux")'.dev-dependencies]
+gungraun = { workspace = true, features = ["default"] }
+
 [lints]
 workspace = true
 
@@ -110,3 +114,13 @@ required-features = ["test-util", "json"]
 harness = false
 name = "http_response_builder"
 required-features = ["test-util", "json"]
+
+[[bench]]
+harness = false
+name = "router_resolve"
+required-features = ["test-util"]
+
+[[bench]]
+harness = false
+name = "router_resolve_cg"
+required-features = ["test-util"]

crates/http_extensions/Cargo.toml

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Wall-clock benchmarks for [`Router::resolve_request_uri`], the per-request routing step.
+//!
+//! For every outgoing request an HTTP client resolves the target URI against the configured
+//! endpoint: it picks the [`BaseUri`] and materializes the request's `http::Uri`. This is run
+//! once per request, and again per attempt under retry/hedging. The benchmark exercises it on
+//! a request built through [`HttpRequestBuilder`] (so the build-time path rendering is cached
+//! and reused) for a fixed base endpoint.
+//!
+//! Paired with `router_resolve_cg.rs`, which measures the same operation under Callgrind.
+//! Instruction counts are the authoritative signal here; wall-clock cannot resolve the small
+//! per-attempt differences this path involves.
+
+#![allow(
+    clippy::missing_panics_doc,
+    clippy::unwrap_used,
+    missing_docs,
+    reason = "improves readability in benchmarks"
+)]
+
+use std::hint::black_box;
+
+use criterion::{Criterion, criterion_group, criterion_main};
+use http_extensions::routing::{Router, RouterContext};
+use http_extensions::{HttpRequest, HttpRequestBuilder};
+use templated_uri::BaseUri;
+
+fn built_request(path: &'static str) -> HttpRequest {
+    HttpRequestBuilder::new_fake().get(path).build().unwrap()
+}
+
+fn entry(c: &mut Criterion) {
+    let mut group = c.benchmark_group("router_resolve");
+
+    // A fixed endpoint with a root base path (the common case): the reused rendered path is
+    // returned directly without a re-validation scan.
+    let router = Router::fixed(BaseUri::from_static("https://api.example.com"));
+    let mut request = built_request("/users/42/posts/hello-world?active=true");
+
+    // `resolve_request_uri` re-routes idempotently from the request's preserved original
+    // target, so repeated calls do identical work - exactly the per-attempt cost.
+    group.bench_function("fixed_root_base", |b| {
+        b.iter(|| {
+            black_box(&router)
+                .resolve_request_uri(RouterContext::new(), black_box(&mut request))
+                .unwrap();
+        });
+    });
+
+    // A fixed endpoint with a non-root base path: the join must concatenate and re-validate.
+    let router_prefixed = Router::fixed(BaseUri::from_static("https://api.example.com/v1/"));
+    let mut request_prefixed = built_request("/users/42/posts/hello-world?active=true");
+
+    group.bench_function("fixed_prefixed_base", |b| {
+        b.iter(|| {
+            black_box(&router_prefixed)
+                .resolve_request_uri(RouterContext::new(), black_box(&mut request_prefixed))
+                .unwrap();
+        });
+    });
+
+    group.finish();
+}
+
+criterion_group!(benches, entry);
+criterion_main!(benches);

crates/http_extensions/benches/router_resolve.rs

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Callgrind benchmarks for [`Router::resolve_request_uri`], the per-request routing step.
+//!
+//! For every outgoing request (and again per retry/hedge attempt) the router picks the
+//! [`BaseUri`] and materializes the request's `http::Uri`. This benchmark isolates that step
+//! on a request built through [`HttpRequestBuilder`] (so the build-time path rendering is
+//! cached and reused) for both a root and a prefixed base path.
+//!
+//! Paired with `router_resolve.rs`, which covers the same operation under wall-clock
+//! (Criterion) measurement.
+
+#![allow(missing_docs, reason = "no need for API documentation on benchmark code")]
+#![allow(
+    clippy::needless_pass_by_value,
+    clippy::unwrap_used,
+    reason = "gungraun benchmark inputs are passed and returned by value by the framework"
+)]
+#![cfg_attr(
+    target_os = "linux",
+    expect(
+        clippy::exit,
+        clippy::missing_docs_in_private_items,
+        unused_qualifications,
+        reason = "Triggered by Gungraun macro expansion. Upstream tracking issues are pending."
+    )
+)]
+
+#[cfg(not(target_os = "linux"))]
+fn main() {
+    // Gungraun requires Valgrind, which is Linux-only.
+}
+
+#[cfg(target_os = "linux")]
+mod linux {
+    use std::hint::black_box;
+
+    use gungraun::{library_benchmark, library_benchmark_group};
+    use http_extensions::routing::{Router, RouterContext};
+    use http_extensions::{HttpRequest, HttpRequestBuilder};
+    use templated_uri::BaseUri;
+
+    fn setup(base: &'static str) -> (Router, HttpRequest) {
+        let router = Router::fixed(BaseUri::from_static(base));
+        let request = HttpRequestBuilder::new_fake()
+            .get("/users/42/posts/hello-world?active=true")
+            .build()
+            .unwrap();
+        (router, request)
+    }
+
+    // Fixed endpoint, root base path (common case): the reused rendered path is returned
+    // without a re-validation scan.
+    #[library_benchmark]
+    #[bench::root(setup("https://api.example.com"))]
+    fn resolve_root(input: (Router, HttpRequest)) -> HttpRequest {
+        let (router, mut request) = input;
+        router.resolve_request_uri(RouterContext::new(), black_box(&mut request)).unwrap();
+        request
+    }
+
+    // Fixed endpoint, non-root base path: the join concatenates and re-validates.
+    #[library_benchmark]
+    #[bench::prefixed(setup("https://api.example.com/v1/"))]
+    fn resolve_prefixed(input: (Router, HttpRequest)) -> HttpRequest {
+        let (router, mut request) = input;
+        router.resolve_request_uri(RouterContext::new(), black_box(&mut request)).unwrap();
+        request
+    }
+
+    library_benchmark_group!(
+        name = router_resolve;
+        benchmarks = resolve_root, resolve_prefixed
+    );
+}
+
+#[cfg(target_os = "linux")]
+use gungraun::{Callgrind, LibraryBenchmarkConfig};
+#[cfg(target_os = "linux")]
+pub use linux::router_resolve;
+
+#[cfg(target_os = "linux")]
+gungraun::main!(
+    config = LibraryBenchmarkConfig::default()
+        .tool(Callgrind::with_args(["--branch-sim=yes"]));
+    library_benchmark_groups = router_resolve
+);

crates/http_extensions/benches/router_resolve_cg.rs

@@ -371,19 +371,21 @@ impl<R> HttpRequestBuilder<'_, R> {
             .uri
             .ok_or_else(|| HttpError::validation_with_label("URI is required when building the request", LABEL_URI_MISSING))??;
 
-        // Attach both a `RequestUris` carrying the caller's templated target
-        // and its `PathAndQuery`:
-        //   - `RequestUris::original` preserves the unrouted target so
-        //     `Router::resolve_request_uri` can re-route from it on every retry.
-        //   - `PathAndQuery` backs `RequestExt::path_and_query` and
-        //     `ExtensionsExt::uri_template_label`.
+        // Attach a `RequestUris` (its `original` lets `Router::resolve_request_uri` re-route
+        // on every retry) and the `PathAndQuery` (backing `RequestExt::path_and_query` and
+        // `ExtensionsExt::uri_template_label`). The templated path is rendered once here and
+        // cached as a `RenderedPath` so routing can reuse it without re-rendering the template.
         let path = uri.to_path_and_query();
-        let http_uri = http::Uri::try_from(uri.clone())?;
+        let rendered = path.as_ref().map(http::uri::PathAndQuery::try_from).transpose()?;
+        let http_uri = uri.to_http_uri(rendered.as_ref())?;
         let mut request = self.builder.uri(http_uri).body(body)?;
         request.extensions_mut().insert(crate::routing::RequestUris::new(uri));
         if let Some(path) = path {
             request.extensions_mut().insert(path);
         }
+        if let Some(rendered) = rendered {
+            request.extensions_mut().insert(crate::routing::RenderedPath(rendered));
+        }
 
         Ok(request)
     }

crates/http_extensions/src/http_request_builder.rs

@@ -57,6 +57,7 @@
 //! [`Uri`]: templated_uri::Uri
 
 mod router;
+pub(crate) use router::RenderedPath;
 pub use router::{BaseUriConflict, RequestUris, Router};
 
 mod router_context;