Skip to main content

spider_optimize/
params.rs

1//! How this crate reads and writes a request.
2//!
3//! The request body is `RequestParams` in the client crate, and the client
4//! depends on this crate, so this crate cannot name that type. It asks for
5//! the handful of reads and writes an edit needs instead, and the client
6//! implements them for its own type. Every rule about what may be written,
7//! the caller's precedence above all, lives in [`crate::EditSet::apply`] and
8//! [`crate::validate()`], not in an implementation of this trait.
9//!
10//! An implementation is plain field access. It must not allocate on the read
11//! methods, because candidates are validated and featurized on every request.
12
13use crate::schema::Key;
14use spider_route::{ProxyPool, RequestMode};
15
16/// Field access on a request body, keyed by [`Key`].
17///
18/// Object safe, so a [`crate::Context`] can hold the request as it is about to
19/// go out and the caller's own snapshot side by side without a type parameter.
20pub trait Params {
21    /// Whether the field this key names holds a value. For
22    /// [`Key::WaitIdleMillis`] that is whether `wait_for` holds anything.
23    fn is_set(&self, key: Key) -> bool;
24
25    /// The fetch mode, when one is set.
26    fn request(&self) -> Option<RequestMode>;
27
28    /// The proxy pool, when one is set.
29    fn proxy(&self) -> Option<ProxyPool>;
30
31    /// The idle network timeout in milliseconds, when `wait_for` holds one.
32    /// Any other kind of wait answers `None`.
33    fn idle_wait_millis(&self) -> Option<u32>;
34
35    /// The value of a field whose [`crate::Kind`] is `Bool`, when it is set.
36    /// Any other key answers `None`.
37    fn flag(&self, key: Key) -> Option<bool>;
38
39    /// The entries of a field whose [`crate::Kind`] is `StringList`, when it
40    /// is set. Any other key answers `None`.
41    fn list(&self, key: Key) -> Option<&[String]>;
42
43    /// Set the fetch mode.
44    fn set_request(&mut self, mode: RequestMode);
45
46    /// Set the proxy pool.
47    fn set_proxy(&mut self, pool: ProxyPool);
48
49    /// Replace `wait_for` with an idle network wait of this many milliseconds.
50    fn set_idle_wait(&mut self, millis: u32);
51
52    /// Set a `Bool` field. Only learnable keys are ever passed, and any other
53    /// key may be ignored.
54    fn set_flag(&mut self, key: Key, value: bool);
55
56    /// Replace a `StringList` field. Only [`Key::NetworkBlacklist`] is ever
57    /// passed, and any other key may be ignored.
58    fn set_list(&mut self, key: Key, list: Option<Vec<String>>);
59}