lead_oxide/lib.rs
1#![deny(unsafe_code)]
2
3//! # PbO
4//!
5//! `lead-oxide` is a wrapper around pubproxy.com's public proxy API.
6//!
7//! `lead-oxide` strives to make it impossible to use the API incorrectly while still making regular
8//! usage as ergonomic as possible.
9//!
10//! ## Keyless API Limitations
11//!
12//! ### Daily Limit
13//!
14//! At the time of writing this without an API key the pubproxy API limits users to 5 proxies per
15//! request and 50 requests per day. The maximum proxies per request is always used to minimize rate
16//! limiting along with getting the most proxies possible within the request limit meaning you
17//! should get 250 proxies per day without needing an API key.
18//!
19//! ### Rate Limiting
20//!
21//! Without an API key pubproxy limits users to one request per second so a `Fetcher` will try to
22//! ensure that at most only one request per second is done without an API key. This is synchronized
23//! between fetchers including across different threads: however, there can still be issues from
24//! running multiple programs from the same IP causing rate limiting to occur. The rate-limiting is
25//! quite severe (will deny requests for potentially several hours), so it's best to avoid by all
26//! means possible.
27//!
28//! ## Quickstart
29//!
30//! ```rust,no_run
31//! use iso_country::Country;
32//! use lead_oxide::{
33//! errors::ApiError,
34//! fetcher::Fetcher,
35//! opts::Opts,
36//! types::{Countries, Level, Protocol, TimeToConnect},
37//! };
38//!
39//! use std::{convert::TryFrom, time::Duration};
40//!
41//! fn main() -> Result<(), ApiError> {
42//! // Fetcher for SOCKS5 proxies located in the US and Canada that support POST requests
43//! let mut socks_fetcher = Fetcher::new(
44//! Opts::builder()
45//! .protocol(Protocol::Socks5)
46//! .countries(Countries::allow().countries(&[Country::US, Country::CA]))
47//! .post(true)
48//! .build(),
49//! );
50//!
51//! // Fetcher for Elite HTTPS proxies that connected in 15 seconds or less
52//! let mut https_fetcher = Fetcher::new(
53//! Opts::builder()
54//! .protocol(Protocol::Http)
55//! .https(true)
56//! .level(Level::Elite)
57//! .time_to_connect(TimeToConnect::try_from(Duration::from_secs(15)).unwrap())
58//! .build(),
59//! );
60//!
61//! // Get one SOCKS proxy and 10 HTTPS proxies
62//! let socks_proxy = &socks_fetcher.try_get(1)?[0];
63//! let https_proxies = https_fetcher.try_get(10)?;
64//!
65//! println!("SOCKS proxy: {:#?}", socks_proxy);
66//! println!("HTTPS proxies {:#?}", https_proxies);
67//!
68//! Ok(())
69//! }
70//! ```
71
72#[macro_use]
73extern crate lazy_static;
74
75mod constants;
76pub mod errors;
77pub mod fetcher;
78pub mod opts;
79pub mod proxy;
80pub mod types;