Struct RotatingClientBuilder 

pub struct RotatingClientBuilder { /* private fields */ }

Builder for RotatingClient. Construct one with RotatingClient::builder.

Implementations

impl RotatingClientBuilder

pub fn proxies<I, S>(self, proxies: I) -> Self

where I: IntoIterator<Item = S>, S: AsRef<str>,

Sets the proxy pool to rotate over: "http://user:pass@host:port" entries, "https://...", a bare "host:port" (treated as HTTP), or "socks5://..." with the socks feature. Leave it unset (the default) to send requests directly, with no proxy. Ignored if proxy_list is also set.

Proxies are only ever taken from here: the HTTP_PROXY, HTTPS_PROXY and ALL_PROXY environment variables that a bare reqwest::Client picks up are ignored. Pass them explicitly if you want them.

Each proxy gets its own underlying reqwest::Client, built eagerly with its own connection pool and TLS configuration. For pools of hundreds of proxies, share one TLS config across them via configure and use_preconfigured_tls.

pub fn proxy_list(self, proxy_list: ProxyList) -> Self

Sets the proxy pool directly from a pre-built ProxyList, e.g. one you validated up front or already put some proxies on cooldown in. Overrides proxies if both are set.

pub const fn rate_limit(self, interval: Duration) -> Self

Minimum interval between two requests to the same host name (port and scheme are not part of the key). Unset by default, meaning no rate limiting; zero disables it too. An interval over a year is capped there.

Every attempt, retries included, waits its turn: a call that retries twice takes three slots.

The limiter sees the host of the URL you request. Redirects are followed inside reqwest, so a redirect to another host is not rate-limited separately.

A call cancelled while it is queued for a host (a tokio::time::timeout, say) gives its slot back, unless another call has already queued behind it.

pub const fn retries(self, retries: u32) -> Self

How many retries follow the first try. Default: 3, so up to 4 attempts. 0 disables retries.

pub const fn backoff(self, base: Duration, max: Duration) -> Self

Exponential backoff base delay and the cap applied to it. Default: 200 ms base, 30 s max, both capped at a year. These pace the delays this client computes itself; a wait the server asks for in Retry-After is bounded separately by max_retry_after.

pub const fn max_retry_after(self, max: Duration) -> Self

Longest Retry-After wait that is honoured. Default: 30 s, capped at a year.

A Retry-After header on a retryable response replaces the computed backoff delay. If the server asks for more than this, the response is returned instead of retrying early against its wishes. Check the status and the header yourself in that case.

pub const fn proxy_cooldown(self, cooldown: Duration) -> Self

How long a proxy is skipped after it fails, at most: the mark also clears the first time the proxy answers again. Default: 60 s. Zero never takes a proxy out of rotation, but a retry with nowhere else to go is still paced by the backoff.

pub fn user_agent(self, user_agent: impl Into<String>) -> Self

User-Agent header sent with every request. Unset by default, in which case reqwest sends none.

pub const fn timeout(self, timeout: Duration) -> Self

Total timeout for one attempt: from starting the request until the response body is fully read. Default: 30 s. An attempt that times out before the response headers arrive is retried for idempotent requests; a POST may already be running on the server, so it is not. A timeout while you read the body surfaces from that read.

This bounds one attempt, not the whole call: with the default four attempts a get() can take up to about two minutes. Wrap the call in tokio::time::timeout for a hard overall budget.

Pass something huge such as Duration::MAX to effectively disable it. Not recommended with proxies: one that accepts the connection and never answers would then hang a request forever.

pub const fn connect_timeout(self, timeout: Duration) -> Self

Timeout for establishing a TCP connection, to the proxy if one is used. Default: 10 s.

pub fn configure<F>(self, configure: F) -> Self

where F: Fn(ClientBuilder) -> ClientBuilder + Send + Sync + 'static,

Applies your own settings to every underlying reqwest::ClientBuilder (one direct client plus one per proxy): default headers, redirect policy, TLS options, and so on. Runs after this builder’s own settings, so it can override them.

Anything behind a reqwest cargo feature (gzip, brotli, cookies, …) needs that feature enabled on your reqwest dependency; by default this crate turns on rustls-tls, http2 and charset (swap to the native-tls feature, with default-features = false, for your platform’s own TLS instead). json and multipart are this crate’s own features, forwarded to reqwest’s. Once enabled, gzip/brotli decoding is on by default in reqwest and needs no call here.

Examples

use reqwest_rotate::RotatingClient;

let client = RotatingClient::builder()
    .configure(|builder| {
        builder.redirect(reqwest::redirect::Policy::none())
    })
    .build()
    .unwrap();

pub fn build(self) -> Result<RotatingClient, Error>

Builds the RotatingClient, constructing one underlying reqwest::Client per configured proxy plus one direct client.

Errors

Returns Error::InvalidProxy if a proxy URL is blank, cannot be parsed, or uses an unsupported scheme; or Error::Build if the underlying TLS/client setup fails.

Trait Implementations

impl Debug for RotatingClientBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RotatingClientBuilder

fn default() -> RotatingClientBuilder

Returns the “default value” for a type.