Skip to main content

litportnet_free_proxy_sdk/
lib.rs

1//! A synchronous client for Litport's verified free-proxy snapshots.
2//!
3//! Free proxies are for testing only. Do not send credentials, personal data,
4//! cookies, or payment data through them. Browse the list at
5//! <https://litport.net/free-proxy>; API documentation is available at
6//! <https://litport.net/docs/free-proxy-api>.
7
8use std::{
9    cmp::Ordering,
10    collections::BTreeMap,
11    fmt,
12    str::FromStr,
13    sync::{Arc, Mutex},
14    time::Duration,
15};
16
17use chrono::{DateTime, Duration as ChronoDuration, Utc};
18use serde_json::{Map, Value};
19use thiserror::Error;
20
21/// Default API snapshot URL.
22pub const DEFAULT_API_URL: &str =
23    "https://litport.net/api/free-proxy/snapshot?checkedWithinMin=1440";
24/// Optional GitHub dataset URL.
25pub const DEFAULT_GITHUB_URL: &str =
26    "https://raw.githubusercontent.com/litportnet/free-proxy-list/live/proxies/all.json";
27
28/// A proxy source.
29#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
30pub enum Source {
31    /// Litport's API snapshot.
32    #[default]
33    Api,
34    /// The optional GitHub dataset.
35    Github,
36}
37
38/// A proxy protocol accepted by the snapshot contract.
39#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
40pub enum Protocol {
41    Http,
42    Socks4,
43    Socks5,
44}
45
46impl Protocol {
47    fn is_valid(value: &str) -> bool {
48        matches!(value, "http" | "socks4" | "socks5")
49    }
50}
51
52impl fmt::Display for Protocol {
53    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
54        formatter.write_str(match self {
55            Self::Http => "http",
56            Self::Socks4 => "socks4",
57            Self::Socks5 => "socks5",
58        })
59    }
60}
61
62impl FromStr for Protocol {
63    type Err = Error;
64
65    fn from_str(value: &str) -> Result<Self> {
66        match value {
67            "http" => Ok(Self::Http),
68            "socks4" => Ok(Self::Socks4),
69            "socks5" => Ok(Self::Socks5),
70            _ => Err(Error::SnapshotValidation(
71                "Snapshot contains an invalid proxy row".into(),
72            )),
73        }
74    }
75}
76
77/// A normalized proxy record.
78#[derive(Clone, Debug, PartialEq)]
79pub struct Proxy {
80    pub protocol: Protocol,
81    pub ip: String,
82    pub port: u16,
83    pub url: String,
84    pub country: Option<String>,
85    pub region: Option<String>,
86    pub city: Option<String>,
87    pub timezone: Option<String>,
88    pub asn: Option<u64>,
89    pub asn_org: Option<String>,
90    pub anonymity: String,
91    pub https: Option<bool>,
92    pub latency_ms: Option<f64>,
93    pub latency_median_ms: Option<f64>,
94    pub uptime_24h: Option<f64>,
95    pub uptime_7d: Option<f64>,
96    pub checks_7d: u64,
97    pub exit_ip: Option<String>,
98    pub sources_count: u64,
99    pub first_seen: DateTime<Utc>,
100    pub last_checked: DateTime<Utc>,
101}
102
103impl Proxy {
104    /// Formats this record as `protocol://ip:port`.
105    pub fn proxy_url(&self) -> String {
106        to_proxy_url(self)
107    }
108}
109
110/// Formats a proxy record as `protocol://ip:port`.
111pub fn to_proxy_url(proxy: &Proxy) -> String {
112    format!("{}://{}:{}", proxy.protocol, proxy.ip, proxy.port)
113}
114
115/// Validated filtering options. `checked_within_min` defaults to 30 when unset.
116#[derive(Clone, Debug, Default, PartialEq, Eq)]
117pub struct Filters {
118    pub protocol: Option<Protocol>,
119    pub country: Option<String>,
120    pub anonymity: Option<String>,
121    pub https: Option<bool>,
122    pub max_latency_ms: Option<u64>,
123    pub min_uptime_7d: Option<u64>,
124    pub min_checks_7d: Option<u64>,
125    pub checked_within_min: Option<u16>,
126    pub limit: Option<usize>,
127}
128
129impl Filters {
130    pub fn protocol(mut self, value: Protocol) -> Self {
131        self.protocol = Some(value);
132        self
133    }
134
135    pub fn country(mut self, value: impl Into<String>) -> Self {
136        self.country = Some(value.into());
137        self
138    }
139
140    pub fn anonymity(mut self, value: impl Into<String>) -> Self {
141        self.anonymity = Some(value.into());
142        self
143    }
144
145    pub fn https(mut self, value: bool) -> Self {
146        self.https = Some(value);
147        self
148    }
149
150    pub fn max_latency_ms(mut self, value: u64) -> Self {
151        self.max_latency_ms = Some(value);
152        self
153    }
154
155    pub fn min_uptime_7d(mut self, value: u64) -> Self {
156        self.min_uptime_7d = Some(value);
157        self
158    }
159
160    pub fn min_checks_7d(mut self, value: u64) -> Self {
161        self.min_checks_7d = Some(value);
162        self
163    }
164
165    pub fn checked_within_min(mut self, value: u16) -> Self {
166        self.checked_within_min = Some(value);
167        self
168    }
169
170    pub fn limit(mut self, value: usize) -> Self {
171        self.limit = Some(value);
172        self
173    }
174
175    fn validate(&self) -> Result<ValidatedFilters> {
176        let country = self.country.as_deref().map(str::to_ascii_lowercase);
177        if country.as_deref().is_some_and(|value| {
178            value.len() != 2 || !value.bytes().all(|byte| byte.is_ascii_lowercase())
179        }) {
180            return Err(Error::FilterValidation(
181                "country must be a two-letter code".into(),
182            ));
183        }
184        if self.anonymity.as_deref().is_some_and(|value| {
185            !matches!(value, "transparent" | "anonymous" | "elite" | "unknown")
186        }) {
187            return Err(Error::FilterValidation("Invalid anonymity value".into()));
188        }
189        let checked_within_min = self.checked_within_min.unwrap_or(30);
190        if !(1..=1440).contains(&checked_within_min) {
191            return Err(Error::FilterValidation(
192                "checked_within_min must be an integer from 1 to 1440".into(),
193            ));
194        }
195        Ok(ValidatedFilters {
196            protocol: self.protocol,
197            country,
198            anonymity: self.anonymity.clone(),
199            https: self.https,
200            max_latency_ms: self.max_latency_ms,
201            min_uptime_7d: self.min_uptime_7d,
202            min_checks_7d: self.min_checks_7d,
203            checked_within_min,
204            limit: self.limit,
205        })
206    }
207}
208
209#[derive(Clone)]
210struct ValidatedFilters {
211    protocol: Option<Protocol>,
212    country: Option<String>,
213    anonymity: Option<String>,
214    https: Option<bool>,
215    max_latency_ms: Option<u64>,
216    min_uptime_7d: Option<u64>,
217    min_checks_7d: Option<u64>,
218    checked_within_min: u16,
219    limit: Option<usize>,
220}
221
222/// Snapshot-client errors.
223#[derive(Debug, Error)]
224pub enum Error {
225    #[error("Snapshot request timed out after {0}ms")]
226    Timeout(u64),
227    #[error("Snapshot request failed with HTTP {status}")]
228    Http { status: u16 },
229    #[error("Received 304 without a cached snapshot")]
230    NotModifiedWithoutCache,
231    #[error("{0}")]
232    SnapshotValidation(String),
233    #[error("Snapshot is truncated")]
234    SnapshotTruncated,
235    #[error("{0}")]
236    FilterValidation(String),
237    #[error("Snapshot request failed: {0}")]
238    Transport(String),
239}
240
241/// Convenient result alias for this crate.
242pub type Result<T> = std::result::Result<T, Error>;
243
244/// The response returned by a [`Transport`]. Header names are case-insensitive.
245#[derive(Clone, Debug, Default)]
246pub struct TransportResponse {
247    pub status: u16,
248    pub headers: BTreeMap<String, String>,
249    pub body: String,
250}
251
252/// Synchronous HTTP adapter used by [`Client`].
253///
254/// Provide a custom implementation in tests to avoid live network requests.
255pub trait Transport: Send + Sync {
256    fn get(
257        &self,
258        url: &str,
259        headers: &BTreeMap<String, String>,
260        timeout: Duration,
261    ) -> Result<TransportResponse>;
262}
263
264/// The default HTTPS transport, implemented with `reqwest` and rustls.
265#[derive(Clone, Debug, Default)]
266pub struct ReqwestTransport;
267
268impl Transport for ReqwestTransport {
269    fn get(
270        &self,
271        url: &str,
272        headers: &BTreeMap<String, String>,
273        timeout: Duration,
274    ) -> Result<TransportResponse> {
275        let client = reqwest::blocking::Client::builder()
276            .timeout(timeout)
277            .build()
278            .map_err(|error| Error::Transport(error.to_string()))?;
279        let mut request = client.get(url);
280        for (name, value) in headers {
281            request = request.header(name, value);
282        }
283        let response = request.send().map_err(|error| {
284            if error.is_timeout() {
285                Error::Timeout(duration_millis(timeout))
286            } else {
287                Error::Transport(error.to_string())
288            }
289        })?;
290        let status = response.status().as_u16();
291        let headers = response
292            .headers()
293            .iter()
294            .filter_map(|(name, value)| {
295                value
296                    .to_str()
297                    .ok()
298                    .map(|value| (name.to_string(), value.to_owned()))
299            })
300            .collect();
301        let body = response.text().map_err(|error| {
302            if error.is_timeout() {
303                Error::Timeout(duration_millis(timeout))
304            } else {
305                Error::Transport(error.to_string())
306            }
307        })?;
308        Ok(TransportResponse {
309            status,
310            headers,
311            body,
312        })
313    }
314}
315
316/// Source of time for freshness checks and cache expiry.
317pub trait Clock: Send + Sync {
318    fn now(&self) -> DateTime<Utc>;
319}
320
321/// The normal UTC system clock.
322#[derive(Clone, Debug, Default)]
323pub struct SystemClock;
324
325impl Clock for SystemClock {
326    fn now(&self) -> DateTime<Utc> {
327        Utc::now()
328    }
329}
330
331struct Cache {
332    rows: Vec<Proxy>,
333    etag: Option<String>,
334    generated_at: Option<DateTime<Utc>>,
335    expires_at: DateTime<Utc>,
336}
337
338/// Builder for a [`Client`].
339pub struct ClientBuilder {
340    source: Source,
341    api_url: String,
342    github_url: String,
343    transport: Arc<dyn Transport>,
344    clock: Arc<dyn Clock>,
345    timeout: Duration,
346}
347
348impl Default for ClientBuilder {
349    fn default() -> Self {
350        Self {
351            source: Source::Api,
352            api_url: DEFAULT_API_URL.into(),
353            github_url: DEFAULT_GITHUB_URL.into(),
354            transport: Arc::new(ReqwestTransport),
355            clock: Arc::new(SystemClock),
356            timeout: Duration::from_secs(10),
357        }
358    }
359}
360
361impl ClientBuilder {
362    pub fn source(mut self, value: Source) -> Self {
363        self.source = value;
364        self
365    }
366
367    pub fn api_url(mut self, value: impl Into<String>) -> Self {
368        self.api_url = value.into();
369        self
370    }
371
372    pub fn github_url(mut self, value: impl Into<String>) -> Self {
373        self.github_url = value.into();
374        self
375    }
376
377    pub fn transport(mut self, value: impl Transport + 'static) -> Self {
378        self.transport = Arc::new(value);
379        self
380    }
381
382    pub fn clock(mut self, value: impl Clock + 'static) -> Self {
383        self.clock = Arc::new(value);
384        self
385    }
386
387    pub fn timeout(mut self, value: Duration) -> Self {
388        self.timeout = value;
389        self
390    }
391
392    pub fn build(self) -> Client {
393        Client {
394            source: self.source,
395            api_url: self.api_url,
396            github_url: self.github_url,
397            transport: self.transport,
398            clock: self.clock,
399            timeout: self.timeout,
400            cache: Mutex::new(None),
401        }
402    }
403}
404
405/// Synchronous Litport free-proxy client.
406pub struct Client {
407    source: Source,
408    api_url: String,
409    github_url: String,
410    transport: Arc<dyn Transport>,
411    clock: Arc<dyn Clock>,
412    timeout: Duration,
413    cache: Mutex<Option<Cache>>,
414}
415
416impl Default for Client {
417    fn default() -> Self {
418        Self::new()
419    }
420}
421
422impl Client {
423    /// Creates an API client with the default HTTPS transport.
424    pub fn new() -> Self {
425        Self::builder().build()
426    }
427
428    pub fn builder() -> ClientBuilder {
429        ClientBuilder::default()
430    }
431
432    /// Gets normalized, fresh proxy rows sorted by uptime, latency, then URL.
433    pub fn get_proxies(&self, filters: &Filters) -> Result<Vec<Proxy>> {
434        self.get_proxies_checked(filters.validate()?)
435    }
436
437    /// Alias for [`Client::get_proxies`].
438    pub fn filter(&self, filters: &Filters) -> Result<Vec<Proxy>> {
439        self.get_proxies(filters)
440    }
441
442    /// Gets the first `n` ranked proxy rows.
443    pub fn pick_best(&self, n: usize, filters: &Filters) -> Result<Vec<Proxy>> {
444        Ok(self
445            .get_proxies_checked(filters.validate()?)?
446            .into_iter()
447            .take(n)
448            .collect())
449    }
450
451    /// Creates a rotation over the currently matching rows.
452    ///
453    /// The rotation retains its initial members but skips records that become
454    /// stale before a subsequent call to [`Iterator::next`].
455    pub fn rotate(&self, filters: &Filters) -> Result<Rotation> {
456        let filters = filters.validate()?;
457        let rows = self.get_proxies_checked(filters.clone())?;
458        Ok(Rotation {
459            rows,
460            index: 0,
461            filters,
462            clock: Arc::clone(&self.clock),
463        })
464    }
465
466    fn get_proxies_checked(&self, filters: ValidatedFilters) -> Result<Vec<Proxy>> {
467        let rows = self.rows()?;
468        let now = self.clock.now();
469        let cutoff = now - ChronoDuration::minutes(i64::from(filters.checked_within_min));
470        let mut matching = rows
471            .into_iter()
472            .filter(|row| {
473                row.last_checked >= cutoff && row.last_checked <= now + ChronoDuration::seconds(5)
474            })
475            .filter(|row| filters.protocol.is_none_or(|value| row.protocol == value))
476            .filter(|row| {
477                filters
478                    .country
479                    .as_deref()
480                    .is_none_or(|value| row.country.as_deref() == Some(value))
481            })
482            .filter(|row| {
483                filters
484                    .anonymity
485                    .as_deref()
486                    .is_none_or(|value| row.anonymity == value)
487            })
488            .filter(|row| filters.https.is_none_or(|value| row.https == Some(value)))
489            .filter(|row| {
490                filters.max_latency_ms.is_none_or(|value| {
491                    row.latency_ms
492                        .is_some_and(|latency| latency <= value as f64)
493                })
494            })
495            .filter(|row| {
496                filters
497                    .min_uptime_7d
498                    .is_none_or(|value| row.uptime_7d.is_some_and(|uptime| uptime >= value as f64))
499            })
500            .filter(|row| {
501                filters
502                    .min_checks_7d
503                    .is_none_or(|value| row.checks_7d >= value)
504            })
505            .collect::<Vec<_>>();
506        matching.sort_by(sort_proxies);
507        if let Some(limit) = filters.limit {
508            matching.truncate(limit);
509        }
510        Ok(matching)
511    }
512
513    fn rows(&self) -> Result<Vec<Proxy>> {
514        let now = self.clock.now();
515        let mut cache = self.cache.lock().expect("client cache mutex poisoned");
516        if let Some(cached) = cache.as_ref().filter(|cached| now < cached.expires_at) {
517            self.validate_generated_at(cached.generated_at, now)?;
518            return Ok(cached.rows.clone());
519        }
520        let mut headers = BTreeMap::new();
521        if let Some(etag) = cache.as_ref().and_then(|cached| cached.etag.as_ref()) {
522            headers.insert("If-None-Match".into(), etag.clone());
523        }
524        let response = self.transport.get(
525            if self.source == Source::Api {
526                &self.api_url
527            } else {
528                &self.github_url
529            },
530            &headers,
531            self.timeout,
532        )?;
533        if response.status == 304 {
534            let cached = cache.as_mut().ok_or(Error::NotModifiedWithoutCache)?;
535            self.validate_generated_at(cached.generated_at, now)?;
536            cached.expires_at = now + ChronoDuration::seconds(cache_seconds(&response.headers));
537            return Ok(cached.rows.clone());
538        }
539        if !(200..300).contains(&response.status) {
540            return Err(Error::Http {
541                status: response.status,
542            });
543        }
544        let body: Value = serde_json::from_str(&response.body)
545            .map_err(|_| Error::SnapshotValidation("Malformed snapshot JSON".into()))?;
546        let (rows, generated_at) = self.parse_snapshot(body, now)?;
547        *cache = Some(Cache {
548            rows: rows.clone(),
549            etag: header(&response.headers, "etag"),
550            generated_at,
551            expires_at: now + ChronoDuration::seconds(cache_seconds(&response.headers)),
552        });
553        Ok(rows)
554    }
555
556    fn parse_snapshot(
557        &self,
558        body: Value,
559        now: DateTime<Utc>,
560    ) -> Result<(Vec<Proxy>, Option<DateTime<Utc>>)> {
561        if self.source == Source::Github {
562            let rows = body
563                .as_array()
564                .ok_or_else(|| Error::SnapshotValidation("Malformed GitHub proxy list".into()))?;
565            return Ok((
566                rows.iter()
567                    .map(|row| map_row(row, Source::Github))
568                    .collect::<Result<_>>()?,
569                None,
570            ));
571        }
572        let snapshot = body
573            .as_object()
574            .ok_or_else(|| Error::SnapshotValidation("Malformed snapshot envelope".into()))?;
575        if snapshot.get("truncated").and_then(Value::as_bool) == Some(true) {
576            return Err(Error::SnapshotTruncated);
577        }
578        let proxies = snapshot
579            .get("proxies")
580            .and_then(Value::as_array)
581            .ok_or_else(|| Error::SnapshotValidation("Malformed snapshot envelope".into()))?;
582        if snapshot.get("count").and_then(Value::as_u64) != Some(proxies.len() as u64)
583            || snapshot
584                .get("truncated")
585                .is_some_and(|value| !value.is_boolean())
586        {
587            return Err(Error::SnapshotValidation(
588                "Malformed snapshot envelope".into(),
589            ));
590        }
591        let generated_at = parse_time(snapshot.get("generatedAt"))?;
592        self.validate_generated_at(Some(generated_at), now)?;
593        Ok((
594            proxies
595                .iter()
596                .map(|row| map_row(row, Source::Api))
597                .collect::<Result<_>>()?,
598            Some(generated_at),
599        ))
600    }
601
602    fn validate_generated_at(
603        &self,
604        value: Option<DateTime<Utc>>,
605        now: DateTime<Utc>,
606    ) -> Result<()> {
607        if self.source != Source::Api {
608            return Ok(());
609        }
610        let generated_at = value.ok_or_else(|| {
611            Error::SnapshotValidation("Snapshot generatedAt is outside the accepted window".into())
612        })?;
613        if generated_at > now + ChronoDuration::seconds(5)
614            || generated_at < now - ChronoDuration::minutes(2)
615        {
616            return Err(Error::SnapshotValidation(
617                "Snapshot generatedAt is outside the accepted window".into(),
618            ));
619        }
620        Ok(())
621    }
622}
623
624/// Iterator returned by [`Client::rotate`].
625pub struct Rotation {
626    rows: Vec<Proxy>,
627    index: usize,
628    filters: ValidatedFilters,
629    clock: Arc<dyn Clock>,
630}
631
632impl Iterator for Rotation {
633    type Item = Proxy;
634
635    fn next(&mut self) -> Option<Self::Item> {
636        if self.rows.is_empty() {
637            return None;
638        }
639        let now = self.clock.now();
640        let cutoff = now - ChronoDuration::minutes(i64::from(self.filters.checked_within_min));
641        for _ in 0..self.rows.len() {
642            let row = self.rows[self.index % self.rows.len()].clone();
643            self.index += 1;
644            if row.last_checked >= cutoff && row.last_checked <= now + ChronoDuration::seconds(5) {
645                return Some(row);
646            }
647        }
648        None
649    }
650}
651
652fn map_row(row: &Value, source: Source) -> Result<Proxy> {
653    let row = row.as_object().ok_or_else(|| {
654        Error::SnapshotValidation("Snapshot contains an invalid proxy row".into())
655    })?;
656    let key = |api, github| if source == Source::Api { api } else { github };
657    let protocol_text = required_string(row, key("protocol", "protocol"))?;
658    if !Protocol::is_valid(protocol_text) {
659        return invalid_row();
660    }
661    let protocol = Protocol::from_str(protocol_text)?;
662    let ip = required_string(row, key("host", "ip"))?.to_owned();
663    let port = required_u64(row, key("port", "port"))?;
664    let port = u16::try_from(port)
665        .map_err(|_| Error::SnapshotValidation("Snapshot contains an invalid proxy row".into()))?;
666    if port == 0 || !public_ipv4(&ip) {
667        return invalid_row();
668    }
669    let country =
670        nullable_string(row, key("geoCountry", "country"))?.map(|value| value.to_ascii_lowercase());
671    if country.as_deref().is_some_and(|value| {
672        value.len() != 2 || !value.bytes().all(|byte| byte.is_ascii_lowercase())
673    }) {
674        return Err(Error::SnapshotValidation("Invalid country".into()));
675    }
676    let asn = nullable_asn(row, key("asn", "asn"))?;
677    let anonymity = required_string(row, key("anonymity", "anonymity"))?.to_owned();
678    if !matches!(
679        anonymity.as_str(),
680        "transparent" | "anonymous" | "elite" | "unknown"
681    ) {
682        return invalid_row();
683    }
684    let https = nullable_bool(row, key("https", "https"))?;
685    let mut latency_ms = nullable_number(row, key("responseTimeMs", "latency_ms"))?;
686    if source == Source::Api {
687        latency_ms = latency_ms.map(|value| (value + 0.5).floor());
688    }
689    let checks_7d = required_u64(row, key("checks7d", "checks_7d"))?;
690    let sources_count = required_u64(row, key("sourcesCount", "sources_count"))?;
691    let first_seen = parse_time(row.get(key("createdAt", "first_seen")))?;
692    let last_checked = parse_time(row.get(key("pingAt", "last_checked")))?;
693    let uptime_7d = nullable_number(row, key("uptime7d", "uptime_7d"))?;
694    Ok(Proxy {
695        protocol,
696        ip: ip.clone(),
697        port,
698        url: format!("{protocol}://{ip}:{port}"),
699        country,
700        region: nullable_string(row, key("geoRegion", "region"))?,
701        city: nullable_string(row, key("geoCity", "city"))?,
702        timezone: nullable_string(row, key("geoTimezone", "timezone"))?,
703        asn,
704        asn_org: nullable_string(row, key("asnOrgName", "asn_org"))?,
705        anonymity,
706        https,
707        latency_ms,
708        latency_median_ms: nullable_number(row, key("responseTimeMedianMs", "latency_median_ms"))?,
709        uptime_24h: nullable_number(row, key("uptime24h", "uptime_24h"))?,
710        uptime_7d: if checks_7d < 50 { None } else { uptime_7d },
711        checks_7d,
712        exit_ip: nullable_string(row, key("externalIp", "exit_ip"))?,
713        sources_count,
714        first_seen,
715        last_checked,
716    })
717}
718
719fn required_string<'a>(row: &'a Map<String, Value>, key: &str) -> Result<&'a str> {
720    row.get(key)
721        .and_then(Value::as_str)
722        .ok_or_else(|| Error::SnapshotValidation("Snapshot contains an invalid proxy row".into()))
723}
724
725fn required_u64(row: &Map<String, Value>, key: &str) -> Result<u64> {
726    row.get(key)
727        .and_then(Value::as_u64)
728        .ok_or_else(|| Error::SnapshotValidation("Snapshot contains an invalid proxy row".into()))
729}
730
731fn nullable_string(row: &Map<String, Value>, key: &str) -> Result<Option<String>> {
732    match row.get(key) {
733        Some(Value::Null) => Ok(None),
734        Some(Value::String(value)) => Ok(Some(value.clone())),
735        _ => Err(Error::SnapshotValidation(format!("Invalid {key}"))),
736    }
737}
738
739fn nullable_bool(row: &Map<String, Value>, key: &str) -> Result<Option<bool>> {
740    match row.get(key) {
741        Some(Value::Null) => Ok(None),
742        Some(Value::Bool(value)) => Ok(Some(*value)),
743        _ => Err(Error::SnapshotValidation("Invalid https value".into())),
744    }
745}
746
747fn nullable_number(row: &Map<String, Value>, key: &str) -> Result<Option<f64>> {
748    match row.get(key) {
749        Some(Value::Null) => Ok(None),
750        Some(value) => value
751            .as_f64()
752            .filter(|value| value.is_finite())
753            .map(Some)
754            .ok_or_else(|| Error::SnapshotValidation(format!("Invalid {key}"))),
755        None => Err(Error::SnapshotValidation(format!("Invalid {key}"))),
756    }
757}
758
759fn nullable_asn(row: &Map<String, Value>, key: &str) -> Result<Option<u64>> {
760    match row.get(key) {
761        None | Some(Value::Null) => Ok(None),
762        Some(Value::Number(value)) => value
763            .as_u64()
764            .map(Some)
765            .ok_or_else(|| Error::SnapshotValidation("Invalid ASN".into())),
766        Some(Value::String(value)) => value
767            .strip_prefix("AS")
768            .or_else(|| value.strip_prefix("as"))
769            .unwrap_or(value)
770            .parse::<u64>()
771            .map(Some)
772            .map_err(|_| Error::SnapshotValidation("Invalid ASN".into())),
773        _ => Err(Error::SnapshotValidation("Invalid ASN".into())),
774    }
775}
776
777fn parse_time(value: Option<&Value>) -> Result<DateTime<Utc>> {
778    let value = value.and_then(Value::as_str).ok_or_else(|| {
779        Error::SnapshotValidation("Snapshot contains an invalid proxy row".into())
780    })?;
781    if value.len() < 20 {
782        return invalid_row();
783    }
784    DateTime::parse_from_rfc3339(value)
785        .map(|value| value.with_timezone(&Utc))
786        .map_err(|_| Error::SnapshotValidation("Snapshot contains an invalid proxy row".into()))
787}
788
789fn invalid_row<T>() -> Result<T> {
790    Err(Error::SnapshotValidation(
791        "Snapshot contains an invalid proxy row".into(),
792    ))
793}
794
795fn public_ipv4(value: &str) -> bool {
796    let parts = value
797        .split('.')
798        .map(str::parse::<u8>)
799        .collect::<std::result::Result<Vec<_>, _>>();
800    let Ok(parts) = parts else { return false };
801    if parts.len() != 4 {
802        return false;
803    }
804    let address = u32::from_be_bytes([parts[0], parts[1], parts[2], parts[3]]);
805    const RANGES: &[(u32, u8)] = &[
806        (0x0000_0000, 8),
807        (0x0a00_0000, 8),
808        (0x6440_0000, 10),
809        (0x7f00_0000, 8),
810        (0xa9fe_0000, 16),
811        (0xac10_0000, 12),
812        (0xc000_0000, 24),
813        (0xc000_0200, 24),
814        (0xc0a8_0000, 16),
815        (0xc612_0000, 15),
816        (0xc633_6400, 24),
817        (0xcb00_7100, 24),
818        (0xe000_0000, 4),
819        (0xf000_0000, 4),
820    ];
821    !RANGES
822        .iter()
823        .any(|(network, prefix)| address >> (32 - prefix) == network >> (32 - prefix))
824}
825
826fn sort_proxies(left: &Proxy, right: &Proxy) -> Ordering {
827    left.uptime_7d
828        .is_none()
829        .cmp(&right.uptime_7d.is_none())
830        .then_with(|| {
831            right
832                .uptime_7d
833                .unwrap_or(0.0)
834                .total_cmp(&left.uptime_7d.unwrap_or(0.0))
835        })
836        .then_with(|| left.latency_ms.is_none().cmp(&right.latency_ms.is_none()))
837        .then_with(|| {
838            left.latency_ms
839                .unwrap_or(0.0)
840                .total_cmp(&right.latency_ms.unwrap_or(0.0))
841        })
842        .then_with(|| left.url.cmp(&right.url))
843}
844
845fn header(headers: &BTreeMap<String, String>, name: &str) -> Option<String> {
846    headers
847        .iter()
848        .find(|(key, _)| key.eq_ignore_ascii_case(name))
849        .map(|(_, value)| value.clone())
850}
851
852fn cache_seconds(headers: &BTreeMap<String, String>) -> i64 {
853    let max_age = header(headers, "cache-control")
854        .as_deref()
855        .and_then(|value| {
856            value.split(',').find_map(|directive| {
857                let (name, value) = directive.trim().split_once('=')?;
858                name.trim()
859                    .eq_ignore_ascii_case("max-age")
860                    .then(|| value.trim().parse::<i64>().ok())
861                    .flatten()
862            })
863        })
864        .unwrap_or(60);
865    max_age.clamp(0, 60)
866}
867
868fn duration_millis(duration: Duration) -> u64 {
869    duration.as_millis().try_into().unwrap_or(u64::MAX)
870}