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}