Struct ProxyList 

pub struct ProxyList { /* private fields */ }

A pool of proxy URLs rotated round-robin, with a cooldown applied to proxies that were recently marked bad (e.g. after a connect failure or a 407 response from the proxy itself).

URLs are validated and canonicalised on construction: a bare host:port becomes http://host:port/, scheme and host are lowercased, default ports are dropped, duplicates (after canonicalisation) are removed, and SOCKS schemes are rejected unless the socks feature is enabled. pick and as_slice return the canonical form; mark_bad and in_cooldown accept either form.

All state lives behind an internal mutex that is never held across an .await, so a single ProxyList can be used concurrently from many tasks. Its Debug output hides proxy credentials.

Examples

use reqwest_rotate::ProxyList;

let proxies = ProxyList::new([
    "http://proxy-a.example:8080",
    "proxy-b.example:8080", // no scheme: treated as http://
])
.unwrap();

assert_eq!(proxies.pick(), Some("http://proxy-a.example:8080/"));
assert_eq!(proxies.pick(), Some("http://proxy-b.example:8080/"));
assert_eq!(proxies.pick(), Some("http://proxy-a.example:8080/"));

Implementations

impl ProxyList

pub fn new<I, S>(proxies: I) -> Result<Self, Error>

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

Builds a proxy list from proxy URLs such as "http://user:pass@host:port". An empty iterator is valid and means “no proxies”: pick then always returns None.

Errors

Returns Error::InvalidProxy if an entry is blank, cannot be parsed as a URL, or uses an unsupported scheme.

Examples

use reqwest_rotate::ProxyList;

let empty = ProxyList::new(Vec::<String>::new()).unwrap();
assert!(empty.is_empty());
assert_eq!(empty.pick(), None);

pub fn is_empty(&self) -> bool

Returns true if no proxies were configured.

pub fn len(&self) -> usize

Number of configured (distinct) proxies, regardless of cooldown state.

pub fn as_slice(&self) -> &[String]

All configured proxy URLs, canonicalised, in rotation order.

pub fn pick(&self) -> Option<&str>

Picks the next proxy in round-robin order, skipping proxies that are still in cooldown when a healthy one is available. Returns None only if the list is empty.

If every proxy is in cooldown, the one whose cooldown ends soonest is returned anyway: a proxy that might work beats no proxy at all. A proxy that then answers a request sent through a RotatingClient that rotates over this list is taken out of cooldown at once; the others stay marked until their own cooldown expires.

pub fn mark_bad(&self, proxy: &str, cooldown: Duration) -> bool

Marks a proxy as bad for cooldown: pick will skip it, unless every proxy is unhealthy, until the cooldown expires or the proxy answers a request sent through a RotatingClient, whichever comes first.

proxy is matched in canonical form, so both what pick returned and what you originally configured work. Returns false if it is not in this list, in which case nothing changes.

pub fn in_cooldown(&self, proxy: &str) -> bool

Returns true if proxy (in either form, see mark_bad) is currently in cooldown.

Trait Implementations

impl Debug for ProxyList

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

Formats the value using the given formatter.