1use 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
159pub type Route<C> = Arc<dyn ProxyHttp<CTX = C> + Send + Sync + 'static>;
161
162type ModulesInit = Box<dyn Fn(&mut HttpModules) + Send + Sync>;
165
166pub 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
185pub struct RouteSlot<C> {
194 selected: Vec<(RouterId, Route<C>)>,
195}
196
197impl<C> RouteSlot<C> {
198 pub const fn new() -> Self {
200 Self {
201 selected: Vec::new(),
202 }
203 }
204
205 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
242pub trait RouteSelector<C>: Send + Sync + 'static {
252 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
266pub 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 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 pub fn get<'a>(&self, outer: &'a Outer) -> &'a Target {
294 (self.get)(outer)
295 }
296
297 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#[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
333pub fn default_downstream_modules(modules: &mut HttpModules) {
338 modules.add_module(ResponseCompressionBuilder::enable(0));
339}
340
341#[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 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 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 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 #[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(¤t);
645 move |_session: &Session, _ctx: &AppContext| {
646 Ok(Some(Arc::clone(¤t.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}