Skip to main content

spider_route/
decision.rs

1//! What a router answers with.
2//!
3//! An [`Action`] is the settings one attempt uses. A [`RouteDecision`] is that
4//! action plus where it came from, how sure the router is, and where the
5//! escalation should pick up if the attempt fails anyway.
6//!
7//! Everything here is public request vocabulary. A decision can be printed in
8//! a log, handed to a support case, or replayed by hand against the API, and
9//! none of it says anything about how a fetch is carried out.
10
11use crate::action::{Country, ProxyPool, RequestMode};
12
13/// What has to happen before the page is read.
14///
15/// Two values, because the choice worth making is whether to pay for settling
16/// time at all. Anything finer belongs in the request parameters, where a
17/// caller who knows the page can say exactly what to wait for.
18#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
19#[non_exhaustive]
20pub enum Wait {
21    /// Read the page as soon as it arrives.
22    #[default]
23    Now,
24    /// Give the page time to stop fetching things, up to this many
25    /// milliseconds, then read it regardless.
26    Settled {
27        /// The longest the page gets before it is read anyway.
28        millis: u32,
29    },
30}
31
32impl Wait {
33    /// The span a settled wait allows, in milliseconds. Zero when nothing is
34    /// waited for.
35    pub const fn millis(self) -> u32 {
36        match self {
37            Wait::Now => 0,
38            Wait::Settled { millis } => millis,
39        }
40    }
41}
42
43/// The settings one attempt uses.
44///
45/// Small on purpose. Every value here is a label a model has to learn and a
46/// promise the crate has to keep across releases, so the set grows only when
47/// something is worth both.
48#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
49#[non_exhaustive]
50pub struct Action {
51    /// How the page is fetched.
52    pub mode: RequestMode,
53    /// Which pool the request leaves from.
54    pub proxy: ProxyPool,
55    /// What has to happen before the page is read.
56    pub wait: Wait,
57}
58
59impl Action {
60    /// An action with a mode and the defaults for the rest.
61    pub const fn new(mode: RequestMode) -> Action {
62        Action {
63            mode,
64            proxy: ProxyPool::Isp,
65            wait: Wait::Now,
66        }
67    }
68
69    /// The same action from another pool.
70    pub const fn with_proxy(mut self, proxy: ProxyPool) -> Action {
71        self.proxy = proxy;
72        self
73    }
74
75    /// The same action with a settling wait.
76    pub const fn with_wait(mut self, wait: Wait) -> Action {
77        self.wait = wait;
78        self
79    }
80}
81
82/// Where a decision came from.
83///
84/// Worth reporting because the four differ in what a caller should do about a
85/// bad outcome. A caller decision is the caller's own; a memory decision says
86/// the caller's records drove it and clearing them changes the answer.
87#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
88#[non_exhaustive]
89pub enum RouteSource {
90    /// The rules decided, with nothing remembered about this site.
91    #[default]
92    Heuristic,
93    /// Weights decided.
94    Model,
95    /// The caller fixed the settings and the router passed them through.
96    Caller,
97    /// What the caller remembers about this site changed the answer.
98    Memory,
99    /// The client took a different action than the router picked, on purpose,
100    /// so that something is learned about the arms nobody pulls. A decision
101    /// marked this way is not a recommendation and should not be read as one.
102    Explore,
103}
104
105/// A routing answer.
106///
107/// The action is the whole of what the first attempt should use. `country` sits
108/// outside it because a country is not part of the reduced set of actions a
109/// model scores: which country to try is a rule, and in this version only a
110/// caller sets one.
111#[derive(Debug, Clone, PartialEq)]
112#[non_exhaustive]
113pub struct RouteDecision {
114    /// The settings for the first attempt.
115    pub action: Action,
116    /// Where the request should appear to come from, when something pinned it.
117    pub country: Option<Country>,
118    /// Where escalation starts if the first attempt fails.
119    ///
120    /// Zero means start at the top and skip nothing. A higher number says the
121    /// router already knows the cheap steps do not work here, so the ladder
122    /// begins that many steps in. It is only ever a starting point: the policy
123    /// engine decides everything after the first answer comes back.
124    pub start_rung: u8,
125    /// How sure the router is, from zero to one.
126    ///
127    /// A rule that settles the question on its own reports close to one. Cold
128    /// start reports the middle, and a caller pin reports one because there
129    /// was nothing to be unsure about.
130    pub confidence: f32,
131    /// Which layer answered.
132    pub source: RouteSource,
133}
134
135impl Default for RouteDecision {
136    fn default() -> RouteDecision {
137        RouteDecision {
138            action: Action::default(),
139            country: None,
140            start_rung: 0,
141            confidence: 0.5,
142            source: RouteSource::Heuristic,
143        }
144    }
145}
146
147impl RouteDecision {
148    /// A decision that uses this action and nothing else.
149    ///
150    /// The confidence is held to zero through one. A NaN is read as zero,
151    /// because `clamp` passes it through and a caller's confidence floor and
152    /// recorded rows both need a number.
153    pub fn new(action: Action, source: RouteSource, confidence: f32) -> RouteDecision {
154        let confidence = if confidence.is_nan() {
155            0.0
156        } else {
157            confidence.clamp(0.0, 1.0)
158        };
159
160        RouteDecision {
161            action,
162            country: None,
163            start_rung: 0,
164            confidence,
165            source,
166        }
167    }
168
169    /// Pin the country this decision asks for.
170    pub fn with_country(mut self, country: Option<Country>) -> RouteDecision {
171        self.country = country;
172        self
173    }
174
175    /// Start the escalation this many steps in.
176    pub const fn starting_at(mut self, rung: u8) -> RouteDecision {
177        self.start_rung = rung;
178        self
179    }
180
181    /// How the page is fetched.
182    pub const fn mode(&self) -> RequestMode {
183        self.action.mode
184    }
185
186    /// Which pool the request leaves from.
187    pub const fn proxy(&self) -> ProxyPool {
188        self.action.proxy
189    }
190
191    /// What has to happen before the page is read.
192    pub const fn wait(&self) -> Wait {
193        self.action.wait
194    }
195}
196
197#[cfg(test)]
198mod tests {
199    // A test may unwrap and may panic: a test that cannot set itself up should
200    // fail loudly rather than quietly measure nothing.
201    #![allow(
202        clippy::unwrap_used,
203        clippy::expect_used,
204        clippy::panic,
205        clippy::unreachable,
206        clippy::indexing_slicing,
207        clippy::string_slice
208    )]
209    use super::*;
210
211    #[test]
212    fn the_accessors_read_the_action() {
213        let action = Action::new(RequestMode::Browser)
214            .with_proxy(ProxyPool::Residential)
215            .with_wait(Wait::Settled { millis: 10_000 });
216        let decision = RouteDecision::new(action, RouteSource::Heuristic, 0.8);
217
218        assert_eq!(decision.mode(), RequestMode::Browser);
219        assert_eq!(decision.proxy(), ProxyPool::Residential);
220        assert_eq!(decision.wait().millis(), 10_000);
221        assert_eq!(Wait::Now.millis(), 0);
222    }
223
224    #[test]
225    fn confidence_cannot_leave_its_range() {
226        assert_eq!(
227            RouteDecision::new(Action::default(), RouteSource::Model, 4.0).confidence,
228            1.0
229        );
230        assert_eq!(
231            RouteDecision::new(Action::default(), RouteSource::Model, -1.0).confidence,
232            0.0
233        );
234    }
235
236    #[test]
237    fn the_default_decision_is_the_default_settings() {
238        let decision = RouteDecision::default();
239
240        assert_eq!(decision.mode(), RequestMode::Smart);
241        assert_eq!(decision.proxy(), ProxyPool::Isp);
242        assert_eq!(decision.wait(), Wait::Now);
243        assert_eq!(decision.start_rung, 0);
244        assert_eq!(decision.source, RouteSource::Heuristic);
245    }
246}