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}