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_with_rendered`).
- `resolve_request_uri` reuses that rendering to join only the resolved base on every
  attempt (never re-rendering), and clones the typed `Uri` once instead of twice.
- `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 |         4403 |      305 ns |     163 ns |
| router_resolve prefixed   |          6773 |         5689 |      308 ns |     220 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

@@ -377,13 +377,22 @@ impl<R> HttpRequestBuilder<'_, R> {
         //     `Router::resolve_request_uri` can re-route from it on every retry.
         //   - `PathAndQuery` backs `RequestExt::path_and_query` and
         //     `ExtensionsExt::uri_template_label`.
+        //
+        // The templated path is rendered to a standalone `http::PathAndQuery` exactly once
+        // here; that single rendering backs the request's initial `http::Uri` (assembled
+        // without a second render) and is cached as a `RenderedPath` so the router can join it
+        // onto the resolved base on every attempt without ever 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_with_rendered(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;

crates/http_extensions/src/routing/mod.rs

@@ -86,6 +86,16 @@ pub struct RequestUris {
     routed: Option<Uri>,
 }
 
+/// Request extension caching the standalone rendering of the request's templated
+/// path-and-query, produced once by
+/// [`HttpRequestBuilder::build`][crate::HttpRequestBuilder::build].
+///
+/// Routing only ever swaps the [`BaseUri`], never the path, so
+/// [`Router::resolve_request_uri`] reuses this rendering to join the resolved base without
+/// re-rendering the template - on the first attempt and on every retry/hedge attempt.
+#[derive(Clone, Debug)]
+pub(crate) struct RenderedPath(pub(crate) http::uri::PathAndQuery);
+
 impl RequestUris {
     /// Creates a [`RequestUris`] with the given templated [`Uri`] as the
     /// [`original`](Self::original) and no [`routed`](Self::routed) yet.
@@ -263,23 +273,50 @@ impl Router {
     /// - [`Router::resolve_uri`] fails (e.g., a [`BaseUriConflict::Fail`] conflict), or
     /// - the resolved [`Uri`] cannot be converted back to an [`http::Uri`].
     pub fn resolve_request_uri(&self, context: RouterContext, request: &mut HttpRequest) -> Result<(), HttpError> {
-        // Always route from the caller-supplied target so repeated calls
-        // are idempotent. Clone rather than take, so a failure below leaves
-        // the request unchanged.
-        let original: Uri = match request.extensions().get::<RequestUris>() {
-            Some(uris) => uris.original().clone(),
-            None => request.uri().clone().try_into()?,
+        // Route from the caller-supplied target so repeated calls are idempotent. A built
+        // request carries its original target in `RequestUris`, so route from a single clone of
+        // it and let `resolve_uri` consume that clone. A hand-built request has no such
+        // extension, so derive the original from the request's URI and keep a copy to seed a
+        // fresh `RequestUris` after routing; that extra clone is confined to the rarer branch.
+        let (original, fallback_original): (Uri, Option<Uri>) = if let Some(uris) = request.extensions().get::<RequestUris>() {
+            (uris.original().clone(), None)
+        } else {
+            let original: Uri = request.uri().clone().try_into()?;
+            (original.clone(), Some(original))
+        };
+        let resolved = self.resolve_uri(context.with_request(request), original)?;
+
+        // Routing only swaps the base, never the path, so reuse the path rendered once at
+        // build time (cached as `RenderedPath`) and join just the resolved base onto it -
+        // avoiding a second template render, including across retry/hedge attempts.
+        //
+        // Only trust `RenderedPath` when this is a built request (`RequestUris` was present,
+        // i.e. `fallback_original` is `None`): then `resolved`'s path derives from the same
+        // original the cache was rendered from, so they provably correspond. A hand-built
+        // request routes from its own `http::Uri` and may carry an unrelated `RenderedPath`,
+        // so it always full-materializes from `resolved` rather than trusting the cache.
+        let http_uri = if fallback_original.is_none() {
+            match request.extensions().get::<RenderedPath>() {
+                Some(rendered) => resolved.to_http_uri_with_rendered(Some(&rendered.0))?,
+                None => resolved.clone().try_into()?,
+            }
+        } else {
+            resolved.clone().try_into()?
         };
-        let resolved = self.resolve_uri(context.with_request(request), original.clone())?;
-        let http_uri = resolved.clone().try_into()?;
 
-        // Commit: update the request's URI and record the resolved URI.
-        // Only `routed` is mutated; `original` is preserved across attempts.
+        // Commit: update the request's URI and record the resolved URI. Only `routed` is
+        // mutated; `original` is preserved across attempts.
         *request.uri_mut() = http_uri;
-        request
-            .extensions_mut()
-            .get_or_insert_with(|| RequestUris::new(original))
-            .set_routed(resolved);
+        if let Some(original) = fallback_original {
+            // Hand-built request: seed a fresh `RequestUris` from the preserved original.
+            let mut uris = RequestUris::new(original);
+            uris.set_routed(resolved);
+            request.extensions_mut().insert(uris);
+        } else if let Some(uris) = request.extensions_mut().get_mut::<RequestUris>() {
+            // Built request: the `RequestUris` extension already exists (it is why
+            // `fallback_original` is `None`); just record the routed URI.
+            uris.set_routed(resolved);
+        }
 
         Ok(())
     }
@@ -626,6 +663,28 @@ mod tests {
         );
     }
 
+    #[test]
+    fn resolve_request_uri_ignores_stale_rendered_path_without_request_uris() {
+        // A hand-built request (no `RequestUris`) that happens to carry an unrelated
+        // `RenderedPath` must NOT trust that cache: routing derives the target from the
+        // request's own `http::Uri`, so it must full-materialize from there, never splicing in
+        // the stale rendering. Guards the correct-by-construction reuse condition.
+        let router = Router::fixed(BaseUri::from_static("https://api.example.com"));
+        let body = crate::HttpBodyBuilder::new_fake().empty();
+        let mut request = http::Request::new(body);
+        *request.uri_mut() = http::Uri::from_static("/v1/items");
+        // Inject a stale rendering that does not correspond to the request's URI.
+        request
+            .extensions_mut()
+            .insert(RenderedPath(http::uri::PathAndQuery::from_static("/stale/wrong/path")));
+        assert!(request.extensions().get::<RequestUris>().is_none(), "precondition: no RequestUris");
+
+        router.resolve_request_uri(RouterContext::new(), &mut request).unwrap();
+
+        // The routed URI reflects the request's own path, not the stale cache.
+        assert_eq!(request.uri().to_string(), "https://api.example.com/v1/items");
+    }
+
     #[test]
     fn resolve_request_uri_attaches_base_uri() {
         let router = Router::fixed(BaseUri::from_static("https://api.example.com"));
@@ -636,6 +695,40 @@ mod tests {
         assert_eq!(request.uri().to_string(), "https://api.example.com/v1/items");
     }
 
+    #[test]
+    fn resolve_request_uri_reuses_rendered_path_matching_full_render() {
+        // `resolve_request_uri` reuses the path rendered once at build time (the `RenderedPath`
+        // extension) and joins only the resolved base. Its result must be byte-identical to the
+        // pre-optimization behavior, which fully re-materialized the resolved `Uri`. This pins
+        // the reuse path against the full-render reference across base-path joins, leading-slash
+        // normalization, and query strings.
+        let bases = ["https://api.example.com", "https://api.example.com/v1/", "http://h:8080/deep/base/"];
+        let paths = ["/items", "/users/42?active=true", "/a/b/c?x=1&y=2", "/only?q=1"];
+
+        for base_str in bases {
+            for path_str in paths {
+                let router = Router::fixed(BaseUri::from_static(base_str));
+                let mut request = crate::HttpRequestBuilder::new_fake().get(path_str).build().unwrap();
+
+                // Sanity: build attached a cached rendering that the reuse path will consume.
+                assert!(
+                    request.extensions().get::<RenderedPath>().is_some(),
+                    "build should cache a RenderedPath for {path_str:?}"
+                );
+
+                router.resolve_request_uri(RouterContext::new(), &mut request).unwrap();
+                let reused = request.uri().clone();
+
+                // Reference: the old behavior - fully re-materialize the resolved `Uri`.
+                let original: Uri = request.extensions().get::<RequestUris>().unwrap().original().clone();
+                let resolved = router.resolve_uri(RouterContext::new(), original).unwrap();
+                let full_render: http::Uri = resolved.try_into().unwrap();
+
+                assert_eq!(reused, full_render, "mismatch for base {base_str:?} + path {path_str:?}");
+            }
+        }
+    }
+
     #[test]
     fn resolve_request_uri_attaches_resolved_uri_extension() {
         // After `resolve_request_uri`, the `RequestUris` extension's `routed`

crates/http_extensions/src/routing/router.rs

@@ -88,6 +88,22 @@ harness = false
 name = "hot_path_cg"
 harness = false
 
+[[bench]]
+name = "routing_rerender"
+harness = false
+
+[[bench]]
+name = "routing_rerender_cg"
+harness = false
+
+[[bench]]
+name = "escaped_string"
+harness = false
+
+[[bench]]
+name = "escaped_string_cg"
+harness = false
+
 [[example]]
 name = "classified_templating"
 path = "examples/classified_templating.rs"