Skip to main content

spider_route/
router.rs

1//! The boundary between deciding and fetching.
2//!
3//! A [`Router`] answers one question with no input or output of any kind:
4//! given the shape of a request, what should the first attempt use. Everything
5//! after that answer belongs to the policy engine in the client, which reads
6//! what came back and decides where to go next.
7//!
8//! The trait exists so the shipped rules, a set of weights, and whatever a
9//! caller writes themselves are all the same thing to the client. That is also
10//! what keeps the no weights path honest: it is not a fallback bolted on, it
11//! is one implementation of the same trait, tested on its own.
12
13use crate::decision::RouteDecision;
14use crate::features::{RouteInput, StatusClass};
15use std::sync::Arc;
16
17/// Which layer of the router answered, and at what version.
18///
19/// Recorded next to every decision so a run can be read back later. A model
20/// number is the version of the weights, not of the crate, because the two
21/// move independently.
22#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
23#[non_exhaustive]
24pub enum RouterVersion {
25    /// Rules only, no weights involved.
26    #[default]
27    Heuristic,
28    /// Weights, at this version.
29    Model(u16),
30}
31
32/// How one attempt ended.
33///
34/// Coarse, because this is what a caller folds into its own records and hands
35/// back as [`crate::SiteMemory`] next time. Anything finer would be a response
36/// feature, and those belong to the escalation half of the problem rather than
37/// to this one.
38#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
39#[non_exhaustive]
40pub struct AttemptOutcome {
41    /// Whether the attempt got what the caller asked for.
42    pub success: bool,
43    /// How the attempt ended.
44    pub status: StatusClass,
45    /// How many bytes of content came back.
46    pub bytes: u32,
47    /// How long it took, in milliseconds.
48    pub millis: u32,
49}
50
51impl AttemptOutcome {
52    /// An attempt that worked.
53    pub const fn ok(bytes: u32, millis: u32) -> AttemptOutcome {
54        AttemptOutcome {
55            success: true,
56            status: StatusClass::Ok,
57            bytes,
58            millis,
59        }
60    }
61
62    /// An attempt that did not.
63    pub const fn failed(status: StatusClass, millis: u32) -> AttemptOutcome {
64        AttemptOutcome {
65            success: false,
66            status,
67            bytes: 0,
68            millis,
69        }
70    }
71}
72
73/// Picks the settings for a first attempt.
74///
75/// Implementations answer from local state only. A `route` call that reaches
76/// the network has broken the contract this crate exists for: the decision has
77/// to be cheaper than the call it is deciding about.
78pub trait Router: Send + Sync {
79    /// Pick the settings for the first attempt.
80    fn route(&self, input: &RouteInput<'_>) -> RouteDecision;
81
82    /// Take note of how an attempt ended.
83    ///
84    /// The default does nothing, which is the honest answer for a router with
85    /// no state. A caller that wants adaptivity keeps its own records and
86    /// passes them back through [`crate::SiteMemory`], which is what lets per
87    /// site learning happen without any site reaching the weights.
88    fn observe(&self, _input: &RouteInput<'_>, _outcome: &AttemptOutcome) {}
89
90    /// Which layer this is, for the record.
91    fn version(&self) -> RouterVersion {
92        RouterVersion::Heuristic
93    }
94}
95
96impl<T: Router + ?Sized> Router for Arc<T> {
97    fn route(&self, input: &RouteInput<'_>) -> RouteDecision {
98        (**self).route(input)
99    }
100
101    fn observe(&self, input: &RouteInput<'_>, outcome: &AttemptOutcome) {
102        (**self).observe(input, outcome);
103    }
104
105    fn version(&self) -> RouterVersion {
106        (**self).version()
107    }
108}
109
110impl<T: Router + ?Sized> Router for &T {
111    fn route(&self, input: &RouteInput<'_>) -> RouteDecision {
112        (**self).route(input)
113    }
114
115    fn observe(&self, input: &RouteInput<'_>, outcome: &AttemptOutcome) {
116        (**self).observe(input, outcome);
117    }
118
119    fn version(&self) -> RouterVersion {
120        (**self).version()
121    }
122}
123
124impl<T: Router + ?Sized> Router for Box<T> {
125    fn route(&self, input: &RouteInput<'_>) -> RouteDecision {
126        (**self).route(input)
127    }
128
129    fn observe(&self, input: &RouteInput<'_>, outcome: &AttemptOutcome) {
130        (**self).observe(input, outcome);
131    }
132
133    fn version(&self) -> RouterVersion {
134        (**self).version()
135    }
136}
137
138#[cfg(test)]
139mod tests {
140    // A test may unwrap and may panic: a test that cannot set itself up should
141    // fail loudly rather than quietly measure nothing.
142    #![allow(
143        clippy::unwrap_used,
144        clippy::expect_used,
145        clippy::panic,
146        clippy::unreachable,
147        clippy::indexing_slicing,
148        clippy::string_slice
149    )]
150    use super::*;
151    use crate::action::RequestMode;
152    use crate::decision::{Action, RouteSource};
153    use crate::features::DeclaredNeed;
154    use crate::HeuristicRouter;
155    use std::sync::atomic::{AtomicUsize, Ordering};
156    use url::Url;
157
158    /// A caller's own router, which is the case the trait exists for.
159    struct AlwaysRendered {
160        seen: AtomicUsize,
161    }
162
163    impl Router for AlwaysRendered {
164        fn route(&self, _input: &RouteInput<'_>) -> RouteDecision {
165            RouteDecision::new(Action::new(RequestMode::Browser), RouteSource::Caller, 1.0)
166        }
167
168        fn observe(&self, _input: &RouteInput<'_>, _outcome: &AttemptOutcome) {
169            self.seen.fetch_add(1, Ordering::Relaxed);
170        }
171
172        fn version(&self) -> RouterVersion {
173            RouterVersion::Model(7)
174        }
175    }
176
177    fn route_through(router: &impl Router) -> RouteDecision {
178        let url = Url::parse("https://example.com/a").unwrap();
179        router.route(&RouteInput::new(&url, DeclaredNeed::Markdown))
180    }
181
182    #[test]
183    fn a_wrapped_router_behaves_like_the_router_it_wraps() {
184        let own = Arc::new(AlwaysRendered {
185            seen: AtomicUsize::new(0),
186        });
187        let url = Url::parse("https://example.com/a").unwrap();
188        let input = RouteInput::new(&url, DeclaredNeed::Markdown);
189
190        assert_eq!(route_through(&own).mode(), RequestMode::Browser);
191        assert_eq!(own.version(), RouterVersion::Model(7));
192
193        own.observe(&input, &AttemptOutcome::ok(1_000, 200));
194        assert_eq!(own.seen.load(Ordering::Relaxed), 1);
195
196        let boxed: Box<dyn Router> = Box::new(HeuristicRouter::new());
197        assert_eq!(boxed.version(), RouterVersion::Heuristic);
198        // The default `observe` has to be callable and has to do nothing.
199        boxed.observe(&input, &AttemptOutcome::failed(StatusClass::Blocked, 900));
200    }
201
202    #[test]
203    fn the_shipped_router_reports_that_no_weights_are_involved() {
204        assert_eq!(HeuristicRouter::new().version(), RouterVersion::Heuristic);
205    }
206
207    #[test]
208    fn an_outcome_says_what_it_is() {
209        let ok = AttemptOutcome::ok(2_048, 310);
210        assert!(ok.success);
211        assert_eq!(ok.status, StatusClass::Ok);
212
213        let refused = AttemptOutcome::failed(StatusClass::Blocked, 120);
214        assert!(!refused.success);
215        assert_eq!(refused.bytes, 0);
216        assert!(refused.status.is_refusal());
217    }
218}