Skip to main content

pingora_proxy_router/
lib.rs

1//! Context-preserving request routing for Pingora [`ProxyHttp`] services.
2//!
3//! Every route and decorator in a graph uses the same application-owned
4//! context type. Components access their private state through [`Lens`] values;
5//! routing stores each router's selected [`Route`] in a [`RouteSlot`] projected
6//! from that context. This keeps routing invisible to decorators outside the
7//! router, permits nested routers to share one slot safely, and supports
8//! context capabilities parameterized by the context itself.
9//!
10//! Selection runs once in `early_request_filter`. The selected route is stored
11//! before its early filter runs, so failures, retries, caching, response
12//! filtering, and logging all dispatch to the same route. Before selection,
13//! hooks safely dispatch to the fallback route.
14//!
15//! Routes are immutable `Arc` handles. A selector may load them from an
16//! atomically replaceable application-owned table; a request pins the selected
17//! handle, so replacing a complete route affects new requests without changing
18//! the route used by in-flight requests.
19//!
20//! # Example
21//!
22//! ```
23//! use pingora_core::{Result, upstreams::peer::HttpPeer};
24//! use pingora_proxy::{ProxyHttp, Session};
25//! use pingora_proxy_router::{RouteSlot, Router, context_lens, route};
26//!
27//! struct AppContext {
28//!     route: RouteSlot<Self>,
29//!     // MetricsState, TracingState, AuthState, ...
30//! }
31//!
32//! impl Default for AppContext {
33//!     fn default() -> Self {
34//!         Self { route: RouteSlot::new() }
35//!     }
36//! }
37//!
38//! struct Endpoint;
39//!
40//! #[async_trait::async_trait]
41//! impl ProxyHttp for Endpoint {
42//!     type CTX = AppContext;
43//!
44//!     fn new_ctx(&self) -> Self::CTX {
45//!         AppContext::default()
46//!     }
47//!
48//!     async fn upstream_peer(
49//!         &self,
50//!         _: &mut Session,
51//!         _: &mut Self::CTX,
52//!     ) -> Result<Box<HttpPeer>> {
53//!         unimplemented!()
54//!     }
55//! }
56//!
57//! let users = route(Endpoint);
58//! let fallback = route(Endpoint);
59//! let router = Router::new(
60//!     move |session: &Session, _ctx: &AppContext| {
61//!         Ok(session
62//!             .req_header()
63//!             .uri
64//!             .path()
65//!             .starts_with("/users")
66//!             .then(|| users.clone()))
67//!     },
68//!     fallback,
69//!     context_lens!(AppContext, ctx => ctx.route),
70//! );
71//! let _: &dyn ProxyHttp<CTX = AppContext> = &router;
72//! ```
73//!
74//! # Replacing routes
75//!
76//! The router does not own a mutable route table. A selector may load an
77//! immutable snapshot from application-owned storage such as `ArcSwap` and
78//! return a cloned route handle. Build and initialize a complete replacement
79//! route or table before publishing it. New requests see the replacement;
80//! in-flight requests retain the old route through their stored `Arc`.
81//!
82//! # Component state
83//!
84//! [`Lens`] describes containment, not delegation. A generic decorator accepts
85//! a lens from the application context to its state, reads or modifies that
86//! state in its overrides, and delegates the complete context unchanged:
87//!
88//! ```
89//! use pingora_proxy_router::{Lens, context_lens};
90//!
91//! struct AuthState;
92//! struct AppContext {
93//!     auth: AuthState,
94//! }
95//!
96//! struct Auth<P> {
97//!     inner: P,
98//!     state: Lens<AppContext, AuthState>,
99//! }
100//!
101//! impl<P> Auth<P> {
102//!     fn new(inner: P, state: Lens<AppContext, AuthState>) -> Self {
103//!         Self { inner, state }
104//!     }
105//! }
106//!
107//! let inner = ();
108//! let auth = Auth::new(
109//!     inner,
110//!     context_lens!(AppContext, ctx => ctx.auth),
111//! );
112//! let _ = auth.inner;
113//! let _ = auth.state;
114//! ```
115//!
116//! Use traits for semantic capabilities and lenses for locating component-owned
117//! state. This permits multiple instances of one component without
118//! accessor-trait coherence or tagging problems.
119//!
120//! # Downstream modules
121//!
122//! The router exclusively owns downstream HTTP module registration. Pingora
123//! builds one server-wide module registry, so route-specific initializers
124//! cannot safely be combined automatically. Configure the complete registry
125//! with `Router::with_downstream_modules`, calling
126//! [`default_downstream_modules`] first when Pingora's default disabled
127//! compression module should be retained. If compression is registered on the
128//! service instead, use `with_downstream_modules(|_| {})` to avoid registering
129//! its module type twice.
130//!
131//! With the default `upstream_modules` feature, which enables Pingora's, the
132//! router likewise owns upstream module registration through
133//! `Router::with_upstream_modules`, and forwards `adjust_upstream_modules` to
134//! the selected route. Disable default features to build without Pingora's
135//! `upstream_modules` feature; if another crate enables Pingora's feature
136//! anyway, the build fails rather than silently skipping
137//! `adjust_upstream_modules`, and this crate's feature must be enabled.
138//!
139//! # Keepalive connection context
140//!
141//! `persist_connection_context` runs after logging, so it reaches the route
142//! selected for the finished request. `on_connection_reuse` runs before the
143//! next request's `early_request_filter`, so it reaches the fallback route. A
144//! value persisted by one route is therefore delivered to the fallback; handle
145//! these hooks in a decorator outside the router when routes need them.
146
147use std::{
148    fmt,
149    sync::{
150        Arc,
151        atomic::{AtomicUsize, Ordering},
152    },
153};
154
155use pingora_core::modules::http::{HttpModules, compression::ResponseCompressionBuilder};
156use pingora_proxy::{ProxyHttp, Session};
157use pingora_proxy_delegate::proxy_http_router_impl;
158
159/// A shareable, immutable proxy selected for one request.
160pub type Route<C> = Arc<dyn ProxyHttp<CTX = C> + Send + Sync + 'static>;
161
162/// A server-wide HTTP module initializer. It runs once, when Pingora builds
163/// the service, so dynamic dispatch costs nothing per request.
164type ModulesInit = Box<dyn Fn(&mut HttpModules) + Send + Sync>;
165
166/// Erases a concrete proxy into a shareable [`Route`].
167pub fn route<P>(proxy: P) -> Route<P::CTX>
168where
169    P: ProxyHttp + Send + Sync + 'static,
170{
171    Arc::new(proxy)
172}
173
174#[derive(Clone, Copy, Debug, Eq, PartialEq)]
175struct RouterId(usize);
176
177static NEXT_ROUTER_ID: AtomicUsize = AtomicUsize::new(1);
178
179impl RouterId {
180    fn next() -> Self {
181        Self(NEXT_ROUTER_ID.fetch_add(1, Ordering::Relaxed))
182    }
183}
184
185/// Per-request storage for routes selected by one or more [`Router`] instances.
186///
187/// Put one of these in the application context and pass a [`Lens`] to it when
188/// constructing each router. Nested routers may share the same slot: selections
189/// are keyed by router identity, so an inner router cannot overwrite the route
190/// pinned by an outer router. For access-log or metric labels, have each route
191/// record its own identity in separate context state from its
192/// `early_request_filter`; selectors intentionally receive only shared context.
193pub struct RouteSlot<C> {
194    selected: Vec<(RouterId, Route<C>)>,
195}
196
197impl<C> RouteSlot<C> {
198    /// Creates an empty route slot.
199    pub const fn new() -> Self {
200        Self {
201            selected: Vec::new(),
202        }
203    }
204
205    /// Returns whether at least one router has completed selection.
206    ///
207    /// Selecting a fallback route also counts as selection.
208    pub fn is_selected(&self) -> bool {
209        !self.selected.is_empty()
210    }
211
212    fn selected_for(&self, router: RouterId) -> Option<&Route<C>> {
213        self.selected
214            .iter()
215            .find_map(|(id, route)| (*id == router).then_some(route))
216    }
217
218    fn clear(&mut self, router: RouterId) {
219        self.selected.retain(|(id, _)| *id != router);
220    }
221
222    fn select(&mut self, router: RouterId, route: Route<C>) {
223        self.clear(router);
224        self.selected.push((router, route));
225    }
226}
227
228impl<C> Default for RouteSlot<C> {
229    fn default() -> Self {
230        Self::new()
231    }
232}
233
234impl<C> fmt::Debug for RouteSlot<C> {
235    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
236        f.debug_struct("RouteSlot")
237            .field("selections", &self.selected.len())
238            .finish()
239    }
240}
241
242/// Selects an immutable route handle for the current request.
243///
244/// Returning `Ok(None)` selects the fallback. Returning an error leaves the
245/// slot empty, so Pingora's ensuing error callbacks also use the fallback.
246/// `ctx` may contain state populated by decorators outside the router. It is
247/// shared because route selection is observational; the router alone updates
248/// its [`RouteSlot`] after selection.
249/// A selector may read an application-owned atomic route-table snapshot and
250/// return a cloned route handle from it.
251pub trait RouteSelector<C>: Send + Sync + 'static {
252    /// Selects the route that should handle `session`, using application context
253    /// prepared by any outer layers.
254    fn select(&self, session: &Session, ctx: &C) -> pingora_core::Result<Option<Route<C>>>;
255}
256
257impl<C, F> RouteSelector<C> for F
258where
259    F: Fn(&Session, &C) -> pingora_core::Result<Option<Route<C>>> + Send + Sync + 'static,
260{
261    fn select(&self, session: &Session, ctx: &C) -> pingora_core::Result<Option<Route<C>>> {
262        (self)(session, ctx)
263    }
264}
265
266/// A shared and mutable projection into an application context.
267///
268/// Lenses describe containment. A decorator uses a lens to reach its own state
269/// while preserving the complete application context when it delegates.
270pub struct Lens<Outer, Target: ?Sized> {
271    get: for<'a> fn(&'a Outer) -> &'a Target,
272    get_mut: for<'a> fn(&'a mut Outer) -> &'a mut Target,
273}
274
275impl<Outer, Target: ?Sized> Clone for Lens<Outer, Target> {
276    fn clone(&self) -> Self {
277        *self
278    }
279}
280
281impl<Outer, Target: ?Sized> Copy for Lens<Outer, Target> {}
282
283impl<Outer, Target: ?Sized> Lens<Outer, Target> {
284    /// Creates a lens from shared and mutable projections.
285    pub const fn new(
286        get: for<'a> fn(&'a Outer) -> &'a Target,
287        get_mut: for<'a> fn(&'a mut Outer) -> &'a mut Target,
288    ) -> Self {
289        Self { get, get_mut }
290    }
291
292    /// Projects a shared reference.
293    pub fn get<'a>(&self, outer: &'a Outer) -> &'a Target {
294        (self.get)(outer)
295    }
296
297    /// Projects a mutable reference.
298    pub fn get_mut<'a>(&self, outer: &'a mut Outer) -> &'a mut Target {
299        (self.get_mut)(outer)
300    }
301}
302
303impl<Outer, Target: ?Sized> fmt::Debug for Lens<Outer, Target> {
304    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
305        f.debug_struct("Lens").finish_non_exhaustive()
306    }
307}
308
309/// Creates a [`Lens`] from one field or place projection.
310///
311/// ```
312/// use pingora_proxy_router::context_lens;
313///
314/// struct Outer {
315///     inner: usize,
316/// }
317///
318/// let lens = context_lens!(Outer, ctx => ctx.inner);
319/// let mut outer = Outer { inner: 1 };
320/// *lens.get_mut(&mut outer) = 2;
321/// assert_eq!(*lens.get(&outer), 2);
322/// ```
323#[macro_export]
324macro_rules! context_lens {
325    ($outer:ty, $binding:ident => $projection:expr) => {
326        $crate::Lens::new(
327            |$binding: &$outer| &$projection,
328            |$binding: &mut $outer| &mut $projection,
329        )
330    };
331}
332
333/// Initializes Pingora's default server-wide downstream modules.
334///
335/// Call this from a custom initializer before adding other shared modules when
336/// the default disabled response-compression module should be retained.
337pub fn default_downstream_modules(modules: &mut HttpModules) {
338    modules.add_module(ResponseCompressionBuilder::enable(0));
339}
340
341/// Routes requests without changing the application context type.
342///
343/// `S` selects complete immutable route handles. `F` constructs the one
344/// application context shared by global decorators, the router, route-specific
345/// decorators, and endpoint proxies. [`Router::new`] uses [`Default`]; use
346/// [`Router::with_context_factory`] when context construction needs captured
347/// configuration. The selected handle is stored through `route_slot` and
348/// remains pinned for the request lifetime.
349#[must_use]
350pub struct Router<C, S, F> {
351    id: RouterId,
352    selector: S,
353    fallback: Route<C>,
354    context_factory: F,
355    route_slot: Lens<C, RouteSlot<C>>,
356    downstream_modules: ModulesInit,
357    #[cfg(feature = "upstream_modules")]
358    upstream_modules: ModulesInit,
359}
360
361impl<C, S> Router<C, S, fn() -> C>
362where
363    C: Default,
364    S: RouteSelector<C>,
365{
366    /// Creates a context-preserving router using `C::default` and Pingora's
367    /// default downstream modules.
368    pub fn new(selector: S, fallback: Route<C>, route_slot: Lens<C, RouteSlot<C>>) -> Self {
369        Self {
370            id: RouterId::next(),
371            selector,
372            fallback,
373            context_factory: C::default,
374            route_slot,
375            downstream_modules: Box::new(default_downstream_modules),
376            #[cfg(feature = "upstream_modules")]
377            upstream_modules: Box::new(|_| {}),
378        }
379    }
380}
381
382impl<C, S, F> Router<C, S, F>
383where
384    S: RouteSelector<C>,
385    F: Fn() -> C + Send + Sync + 'static,
386{
387    /// Creates a context-preserving router with a custom context factory and
388    /// Pingora's default downstream modules.
389    pub fn with_context_factory(
390        selector: S,
391        fallback: Route<C>,
392        context_factory: F,
393        route_slot: Lens<C, RouteSlot<C>>,
394    ) -> Self {
395        Self {
396            id: RouterId::next(),
397            selector,
398            fallback,
399            context_factory,
400            route_slot,
401            downstream_modules: Box::new(default_downstream_modules),
402            #[cfg(feature = "upstream_modules")]
403            upstream_modules: Box::new(|_| {}),
404        }
405    }
406}
407
408impl<C, S, F> Router<C, S, F> {
409    /// Replaces the complete server-wide downstream-module initializer.
410    ///
411    /// Route initializers are intentionally not invoked. Put the complete
412    /// shared module configuration in this closure. If response compression is
413    /// already registered on the service, use `|_| {}` (or another initializer
414    /// that omits [`default_downstream_modules`]); Pingora rejects duplicate
415    /// module types when it builds the module context.
416    pub fn with_downstream_modules(
417        mut self,
418        modules: impl Fn(&mut HttpModules) + Send + Sync + 'static,
419    ) -> Self {
420        self.downstream_modules = Box::new(modules);
421        self
422    }
423
424    /// Replaces the complete server-wide upstream-module initializer.
425    ///
426    /// As with downstream modules, route initializers are intentionally not
427    /// invoked. The default registers no upstream modules, matching Pingora.
428    #[cfg(feature = "upstream_modules")]
429    pub fn with_upstream_modules(
430        mut self,
431        modules: impl Fn(&mut HttpModules) + Send + Sync + 'static,
432    ) -> Self {
433        self.upstream_modules = Box::new(modules);
434        self
435    }
436
437    fn selected_route(&self, ctx: &C) -> Route<C> {
438        self.route_slot
439            .get(ctx)
440            .selected_for(self.id)
441            .cloned()
442            .unwrap_or_else(|| Arc::clone(&self.fallback))
443    }
444}
445
446impl<C, S, F> fmt::Debug for Router<C, S, F> {
447    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
448        f.debug_struct("Router").finish_non_exhaustive()
449    }
450}
451
452proxy_http_router_impl!();
453
454#[cfg(test)]
455mod tests {
456    use std::sync::{
457        Arc, RwLock,
458        atomic::{AtomicUsize, Ordering},
459    };
460
461    use pingora_core::{Error, ErrorType, Result, upstreams::peer::HttpPeer};
462    use pingora_proxy_delegate::proxy_http_delegate;
463    use tokio::io::{AsyncWriteExt, DuplexStream};
464
465    use super::*;
466
467    #[derive(Default)]
468    struct AppContext {
469        route: RouteSlot<Self>,
470        value: usize,
471        auth_calls: usize,
472    }
473
474    fn route_lens() -> Lens<AppContext, RouteSlot<AppContext>> {
475        context_lens!(AppContext, ctx => ctx.route)
476    }
477
478    async fn session(path: &str) -> (Session, DuplexStream) {
479        let raw = format!("GET {path} HTTP/1.1\r\nHost: localhost\r\n\r\n");
480        let (mut client, server) = tokio::io::duplex(4096);
481        client.write_all(raw.as_bytes()).await.unwrap();
482        let mut session = Session::new_h1(Box::new(server));
483        session.downstream_session.read_request().await.unwrap();
484        (session, client)
485    }
486
487    #[derive(Default)]
488    struct Counters {
489        early: AtomicUsize,
490        request: AtomicUsize,
491        fail: AtomicUsize,
492        summary: AtomicUsize,
493        logging: AtomicUsize,
494    }
495
496    struct ProbeProxy {
497        id: usize,
498        fail_early: bool,
499        counters: Arc<Counters>,
500    }
501
502    #[async_trait::async_trait]
503    impl ProxyHttp for ProbeProxy {
504        type CTX = AppContext;
505
506        fn new_ctx(&self) -> Self::CTX {
507            AppContext::default()
508        }
509
510        async fn early_request_filter(
511            &self,
512            _session: &mut Session,
513            ctx: &mut Self::CTX,
514        ) -> Result<()> {
515            self.counters.early.fetch_add(1, Ordering::SeqCst);
516            ctx.value = self.id;
517            if self.fail_early {
518                Err(Error::explain(ErrorType::InternalError, "early failure"))
519            } else {
520                Ok(())
521            }
522        }
523
524        async fn request_filter(
525            &self,
526            _session: &mut Session,
527            ctx: &mut Self::CTX,
528        ) -> Result<bool> {
529            assert_eq!(ctx.value, self.id);
530            self.counters.request.fetch_add(1, Ordering::SeqCst);
531            Ok(false)
532        }
533
534        async fn upstream_peer(
535            &self,
536            _session: &mut Session,
537            _ctx: &mut Self::CTX,
538        ) -> Result<Box<HttpPeer>> {
539            unimplemented!()
540        }
541
542        async fn fail_to_proxy(
543            &self,
544            _session: &mut Session,
545            _error: &Error,
546            _ctx: &mut Self::CTX,
547        ) -> pingora_proxy::FailToProxy {
548            self.counters.fail.fetch_add(1, Ordering::SeqCst);
549            pingora_proxy::FailToProxy {
550                error_code: 500,
551                can_reuse_downstream: false,
552            }
553        }
554
555        fn request_summary(&self, _session: &Session, _ctx: &Self::CTX) -> String {
556            self.counters.summary.fetch_add(1, Ordering::SeqCst);
557            self.id.to_string()
558        }
559
560        async fn logging(
561            &self,
562            _session: &mut Session,
563            _error: Option<&Error>,
564            _ctx: &mut Self::CTX,
565        ) {
566            self.counters.logging.fetch_add(1, Ordering::SeqCst);
567        }
568    }
569
570    fn probe(id: usize, fail_early: bool, counters: &Arc<Counters>) -> Route<AppContext> {
571        route(ProbeProxy {
572            id,
573            fail_early,
574            counters: Arc::clone(counters),
575        })
576    }
577
578    #[tokio::test]
579    async fn selects_once_and_preserves_the_application_context_type() {
580        let selected_counters = Arc::new(Counters::default());
581        let fallback_counters = Arc::new(Counters::default());
582        let selected = probe(7, false, &selected_counters);
583        let fallback = probe(99, false, &fallback_counters);
584        let router = Router::new(
585            {
586                let selected = Arc::clone(&selected);
587                move |session: &Session, _ctx: &AppContext| {
588                    Ok((session.req_header().uri.path() == "/selected")
589                        .then(|| Arc::clone(&selected)))
590                }
591            },
592            fallback,
593            route_lens(),
594        );
595        let (mut session, _client) = session("/selected").await;
596        let mut ctx = router.new_ctx();
597
598        router
599            .early_request_filter(&mut session, &mut ctx)
600            .await
601            .unwrap();
602        router.request_filter(&mut session, &mut ctx).await.unwrap();
603
604        assert_eq!(ctx.value, 7);
605        assert!(ctx.route.is_selected());
606        assert_eq!(selected_counters.early.load(Ordering::SeqCst), 1);
607        assert_eq!(selected_counters.request.load(Ordering::SeqCst), 1);
608        assert_eq!(fallback_counters.early.load(Ordering::SeqCst), 0);
609    }
610
611    #[tokio::test]
612    async fn selector_can_read_application_context() {
613        let selected_counters = Arc::new(Counters::default());
614        let fallback_counters = Arc::new(Counters::default());
615        let selected = probe(7, false, &selected_counters);
616        let router = Router::new(
617            move |_session: &Session, ctx: &AppContext| {
618                Ok((ctx.value == 42).then(|| Arc::clone(&selected)))
619            },
620            probe(99, false, &fallback_counters),
621            route_lens(),
622        );
623        let (mut session, _client) = session("/selected-by-context").await;
624        let mut ctx = router.new_ctx();
625        ctx.value = 42;
626
627        router
628            .early_request_filter(&mut session, &mut ctx)
629            .await
630            .unwrap();
631
632        assert_eq!(selected_counters.early.load(Ordering::SeqCst), 1);
633        assert_eq!(fallback_counters.early.load(Ordering::SeqCst), 0);
634    }
635
636    #[tokio::test]
637    async fn selected_route_is_pinned_across_table_replacement() {
638        let old_counters = Arc::new(Counters::default());
639        let new_counters = Arc::new(Counters::default());
640        let fallback_counters = Arc::new(Counters::default());
641        let current = Arc::new(RwLock::new(probe(1, false, &old_counters)));
642        let router = Router::new(
643            {
644                let current = Arc::clone(&current);
645                move |_session: &Session, _ctx: &AppContext| {
646                    Ok(Some(Arc::clone(&current.read().unwrap())))
647                }
648            },
649            probe(99, false, &fallback_counters),
650            route_lens(),
651        );
652        let (mut session, _client) = session("/route").await;
653        let mut ctx = router.new_ctx();
654
655        router
656            .early_request_filter(&mut session, &mut ctx)
657            .await
658            .unwrap();
659        *current.write().unwrap() = probe(2, false, &new_counters);
660        router.request_filter(&mut session, &mut ctx).await.unwrap();
661
662        assert_eq!(ctx.value, 1);
663        assert_eq!(old_counters.request.load(Ordering::SeqCst), 1);
664        assert_eq!(new_counters.request.load(Ordering::SeqCst), 0);
665    }
666
667    #[tokio::test]
668    async fn preselection_error_hooks_use_the_fallback() {
669        let fallback_counters = Arc::new(Counters::default());
670        let router = Router::new(
671            |_session: &Session, _ctx: &AppContext| Ok(None),
672            probe(99, false, &fallback_counters),
673            route_lens(),
674        );
675        let (mut session, _client) = session("/before-selection").await;
676        let mut ctx = router.new_ctx();
677        let error = Error::explain(ErrorType::InternalError, "outer layer failed");
678
679        router.fail_to_proxy(&mut session, &error, &mut ctx).await;
680        assert_eq!(router.request_summary(&session, &ctx), "99");
681        router.logging(&mut session, Some(&error), &mut ctx).await;
682
683        assert_eq!(fallback_counters.fail.load(Ordering::SeqCst), 1);
684        assert_eq!(fallback_counters.summary.load(Ordering::SeqCst), 1);
685        assert_eq!(fallback_counters.logging.load(Ordering::SeqCst), 1);
686    }
687
688    #[tokio::test]
689    async fn selector_errors_leave_error_callbacks_on_the_fallback() {
690        let fallback_counters = Arc::new(Counters::default());
691        let router = Router::new(
692            |_session: &Session, _ctx: &AppContext| {
693                Err(Error::explain(ErrorType::InternalError, "selection failed"))
694            },
695            probe(99, false, &fallback_counters),
696            route_lens(),
697        );
698        let (mut session, _client) = session("/bad-host").await;
699        let mut ctx = router.new_ctx();
700
701        let error = router
702            .early_request_filter(&mut session, &mut ctx)
703            .await
704            .unwrap_err();
705        router.fail_to_proxy(&mut session, &error, &mut ctx).await;
706
707        assert!(!ctx.route.is_selected());
708        assert_eq!(fallback_counters.fail.load(Ordering::SeqCst), 1);
709    }
710
711    #[tokio::test]
712    async fn selected_route_handles_callbacks_after_its_early_error() {
713        let selected_counters = Arc::new(Counters::default());
714        let fallback_counters = Arc::new(Counters::default());
715        let selected = probe(4, true, &selected_counters);
716        let router = Router::new(
717            move |_session: &Session, _ctx: &AppContext| Ok(Some(Arc::clone(&selected))),
718            probe(99, false, &fallback_counters),
719            route_lens(),
720        );
721        let (mut session, _client) = session("/error").await;
722        let mut ctx = router.new_ctx();
723
724        let error = router
725            .early_request_filter(&mut session, &mut ctx)
726            .await
727            .unwrap_err();
728        router.fail_to_proxy(&mut session, &error, &mut ctx).await;
729        assert_eq!(router.request_summary(&session, &ctx), "4");
730
731        assert_eq!(selected_counters.fail.load(Ordering::SeqCst), 1);
732        assert_eq!(selected_counters.summary.load(Ordering::SeqCst), 1);
733        assert_eq!(fallback_counters.fail.load(Ordering::SeqCst), 0);
734    }
735
736    struct AuthLayer<P: ProxyHttp> {
737        inner: P,
738        state: Lens<P::CTX, usize>,
739    }
740
741    #[proxy_http_delegate(self.inner)]
742    impl<P> ProxyHttp for AuthLayer<P>
743    where
744        P: ProxyHttp + Send + Sync,
745        P::CTX: Send + Sync,
746    {
747        type CTX = P::CTX;
748
749        async fn request_filter(&self, session: &mut Session, ctx: &mut Self::CTX) -> Result<bool> {
750            *self.state.get_mut(ctx) += 1;
751            self.inner.request_filter(session, ctx).await
752        }
753    }
754
755    #[tokio::test]
756    async fn route_specific_decorator_uses_a_lens_without_changing_context() {
757        let inner_counters = Arc::new(Counters::default());
758        let fallback_counters = Arc::new(Counters::default());
759        let authenticated = route(AuthLayer {
760            inner: ProbeProxy {
761                id: 3,
762                fail_early: false,
763                counters: Arc::clone(&inner_counters),
764            },
765            state: context_lens!(AppContext, ctx => ctx.auth_calls),
766        });
767        let router = Router::new(
768            move |_session: &Session, _ctx: &AppContext| Ok(Some(Arc::clone(&authenticated))),
769            probe(99, false, &fallback_counters),
770            route_lens(),
771        );
772        let (mut session, _client) = session("/auth").await;
773        let mut ctx = router.new_ctx();
774
775        router
776            .early_request_filter(&mut session, &mut ctx)
777            .await
778            .unwrap();
779        router.request_filter(&mut session, &mut ctx).await.unwrap();
780
781        assert_eq!(ctx.auth_calls, 1);
782        assert_eq!(inner_counters.request.load(Ordering::SeqCst), 1);
783    }
784
785    #[tokio::test]
786    async fn decorator_above_a_nested_router_is_not_bypassed() {
787        let leaf_counters = Arc::new(Counters::default());
788        let inner_fallback_counters = Arc::new(Counters::default());
789        let outer_fallback_counters = Arc::new(Counters::default());
790        let leaf = probe(3, false, &leaf_counters);
791        let inner = Router::new(
792            move |_session: &Session, _ctx: &AppContext| Ok(Some(Arc::clone(&leaf))),
793            probe(98, false, &inner_fallback_counters),
794            route_lens(),
795        );
796        let decorated = route(AuthLayer {
797            inner,
798            state: context_lens!(AppContext, ctx => ctx.auth_calls),
799        });
800        let outer = Router::new(
801            move |_session: &Session, _ctx: &AppContext| Ok(Some(Arc::clone(&decorated))),
802            probe(99, false, &outer_fallback_counters),
803            route_lens(),
804        );
805        let (mut session, _client) = session("/nested").await;
806        let mut ctx = outer.new_ctx();
807
808        outer
809            .early_request_filter(&mut session, &mut ctx)
810            .await
811            .unwrap();
812        outer.request_filter(&mut session, &mut ctx).await.unwrap();
813
814        assert_eq!(ctx.auth_calls, 1);
815        assert_eq!(leaf_counters.early.load(Ordering::SeqCst), 1);
816        assert_eq!(leaf_counters.request.load(Ordering::SeqCst), 1);
817        assert_eq!(ctx.route.selected.len(), 2);
818    }
819
820    #[test]
821    fn router_owns_downstream_module_initialization() {
822        let fallback_counters = Arc::new(Counters::default());
823        let initializations = Arc::new(AtomicUsize::new(0));
824        let observed = Arc::clone(&initializations);
825        let router = Router::new(
826            |_session: &Session, _ctx: &AppContext| Ok(None),
827            probe(99, false, &fallback_counters),
828            route_lens(),
829        )
830        .with_downstream_modules(move |_modules| {
831            observed.fetch_add(1, Ordering::SeqCst);
832        });
833        let mut modules = HttpModules::new();
834
835        router.init_downstream_modules(&mut modules);
836
837        assert_eq!(initializations.load(Ordering::SeqCst), 1);
838    }
839
840    #[test]
841    fn custom_context_factory_is_used() {
842        let fallback_counters = Arc::new(Counters::default());
843        let router = Router::with_context_factory(
844            |_session: &Session, _ctx: &AppContext| Ok(None),
845            probe(99, false, &fallback_counters),
846            || AppContext {
847                value: 42,
848                ..AppContext::default()
849            },
850            route_lens(),
851        );
852
853        assert_eq!(router.new_ctx().value, 42);
854    }
855
856    #[test]
857    fn lens_projects_shared_mutable_and_unsized_state() {
858        struct Outer {
859            inner: [u8; 3],
860        }
861
862        let lens: Lens<Outer, [u8]> = context_lens!(Outer, ctx => ctx.inner[..]);
863        let mut outer = Outer { inner: [1, 2, 3] };
864
865        lens.get_mut(&mut outer)[1] = 4;
866        assert_eq!(lens.get(&outer), &[1, 4, 3]);
867    }
868}