Skip to main content

spider_route/
action.rs

1//! The vocabulary a routing decision is made in.
2//!
3//! These types live here rather than in the client because the client depends
4//! on this crate and not the other way round. Keeping one definition means a
5//! new routing action cannot exist on one side of the boundary and not the
6//! other. See `docs/action-vocabulary.md`.
7
8use serde::de::{Error as DeError, Unexpected, Visitor};
9use serde::{Deserialize, Deserializer, Serialize, Serializer};
10use std::fmt;
11
12/// How the page is fetched.
13///
14/// The three values are the whole of the choice. Which software performs a
15/// rendered fetch is decided by the service and is not selectable here.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
17#[non_exhaustive]
18pub enum RequestMode {
19    /// Plain HTTP fetch. Cheapest and fastest, and wrong for pages that build
20    /// their content after load.
21    Http,
22    /// Start with HTTP and switch to a rendered fetch when the first response
23    /// looks like it needs one. The default, and the right answer when you do
24    /// not know the page.
25    #[default]
26    Smart,
27    /// Always render the page before reading it. Costs more per page and takes
28    /// longer, so ask for it when you already know HTTP comes back empty.
29    Browser,
30}
31
32impl RequestMode {
33    /// The value sent on the wire.
34    pub const fn as_str(&self) -> &'static str {
35        match self {
36            RequestMode::Http => "http",
37            RequestMode::Smart => "smart",
38            RequestMode::Browser => "browser",
39        }
40    }
41
42    /// Read a mode from an API value. Older spellings still in circulation are
43    /// accepted, and matching ignores case.
44    pub fn from_wire(value: &str) -> Option<RequestMode> {
45        match value.trim().to_ascii_lowercase().as_str() {
46            "http" => Some(RequestMode::Http),
47            "smart" | "smart_mode" | "smartmode" => Some(RequestMode::Smart),
48            "browser" | "chrome" | "headless" => Some(RequestMode::Browser),
49            _ => None,
50        }
51    }
52}
53
54impl fmt::Display for RequestMode {
55    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
56        f.write_str(self.as_str())
57    }
58}
59
60impl Serialize for RequestMode {
61    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
62        serializer.serialize_str(self.as_str())
63    }
64}
65
66impl<'de> Deserialize<'de> for RequestMode {
67    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<RequestMode, D::Error> {
68        struct ModeVisitor;
69
70        impl<'de> Visitor<'de> for ModeVisitor {
71            type Value = RequestMode;
72
73            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
74                f.write_str("one of \"http\", \"smart\" or \"browser\"")
75            }
76
77            fn visit_str<E: DeError>(self, value: &str) -> Result<RequestMode, E> {
78                RequestMode::from_wire(value)
79                    .ok_or_else(|| E::invalid_value(Unexpected::Str(value), &self))
80            }
81        }
82
83        deserializer.deserialize_str(ModeVisitor)
84    }
85}
86
87/// Which pool the outbound address comes from.
88///
89/// Two pools are sold and two appear here. A request that keeps failing on
90/// `Isp` is the case for `Residential`, and a request that succeeds on `Isp`
91/// should stay there, because residential addresses cost more per page.
92#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
93#[non_exhaustive]
94pub enum ProxyPool {
95    /// Addresses held by internet service providers. Fast, stable, and the
96    /// default. `datacenter` is the older name for the same pool.
97    #[serde(rename = "isp", alias = "datacenter", alias = "ISP")]
98    #[default]
99    Isp,
100    /// Addresses assigned to home connections. Slower and dearer per page, and
101    /// what gets through when a site turns away the ISP pool.
102    #[serde(rename = "residential", alias = "RESIDENTIAL")]
103    Residential,
104}
105
106impl ProxyPool {
107    /// The value sent on the wire.
108    pub const fn as_str(&self) -> &'static str {
109        match self {
110            ProxyPool::Isp => "isp",
111            ProxyPool::Residential => "residential",
112        }
113    }
114}
115
116impl fmt::Display for ProxyPool {
117    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
118        f.write_str(self.as_str())
119    }
120}
121
122/// Every pool a request may be sent through.
123pub const PROXY_POOLS: [ProxyPool; 2] = [ProxyPool::Isp, ProxyPool::Residential];
124
125/// A two letter ISO 3166-1 country code, checked when it is built.
126///
127/// Pinning a country changes which addresses the request leaves from, which
128/// changes what the site serves: prices, stock, language, and sometimes
129/// whether the fetch is allowed at all.
130#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
131pub struct Country(String);
132
133impl Country {
134    /// Build a country from a code such as `us` or `DE`. Returns `None` unless
135    /// the input is exactly two ASCII letters. The stored form is lowercase,
136    /// which is what the API expects.
137    pub fn new(code: &str) -> Option<Country> {
138        let code = code.trim();
139
140        if code.len() == 2 && code.bytes().all(|b| b.is_ascii_alphabetic()) {
141            Some(Country(code.to_ascii_lowercase()))
142        } else {
143            None
144        }
145    }
146
147    /// The lowercase code, ready to send.
148    pub fn as_str(&self) -> &str {
149        &self.0
150    }
151}
152
153impl fmt::Display for Country {
154    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
155        f.write_str(&self.0)
156    }
157}
158
159impl std::str::FromStr for Country {
160    type Err = InvalidCountry;
161
162    fn from_str(value: &str) -> Result<Country, InvalidCountry> {
163        Country::new(value).ok_or(InvalidCountry)
164    }
165}
166
167impl TryFrom<&str> for Country {
168    type Error = InvalidCountry;
169
170    fn try_from(value: &str) -> Result<Country, InvalidCountry> {
171        Country::new(value).ok_or(InvalidCountry)
172    }
173}
174
175/// Returned when a string is not a two letter country code.
176#[derive(Debug, Clone, Copy, PartialEq, Eq)]
177pub struct InvalidCountry;
178
179impl fmt::Display for InvalidCountry {
180    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
181        f.write_str("a country code is two ASCII letters, such as us or de")
182    }
183}
184
185impl std::error::Error for InvalidCountry {}
186
187impl Serialize for Country {
188    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
189        serializer.serialize_str(&self.0)
190    }
191}
192
193impl<'de> Deserialize<'de> for Country {
194    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Country, D::Error> {
195        struct CountryVisitor;
196
197        impl<'de> Visitor<'de> for CountryVisitor {
198            type Value = Country;
199
200            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
201                f.write_str("a two letter ISO 3166-1 country code")
202            }
203
204            fn visit_str<E: DeError>(self, value: &str) -> Result<Country, E> {
205                Country::new(value).ok_or_else(|| E::invalid_value(Unexpected::Str(value), &self))
206            }
207        }
208
209        deserializer.deserialize_str(CountryVisitor)
210    }
211}