stygian-proxy 0.15.0

High-performance, resilient proxy rotation for the Stygian scraping ecosystem.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! Protocol-aware routing path resolution.
//!
//! [`resolve_routing_path`] translates a proxy's advertised capabilities and
//! the caller's transport preference into a concrete [`RoutingPath`] that the
//! HTTP client layer uses when opening a connection.

use crate::types::{ProxyCapabilities, RoutingPath};

/// Preference expressed by the caller when acquiring a proxy.
///
/// # Example
/// ```
/// use stygian_proxy::routing::TransportPreference;
/// assert_eq!(TransportPreference::default(), TransportPreference::PreferH3);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TransportPreference {
    /// Use HTTP/3 over QUIC if the proxy supports it; fall back to TCP.
    #[default]
    PreferH3,
    /// Always use HTTP/1.1 or HTTP/2 over a TCP CONNECT tunnel.
    ForceTcp,
    /// Prefer a persistent TCP connection that spans multiple logical requests.
    ///
    /// Forces a TCP CONNECT tunnel and signals the HTTP client layer to keep
    /// the underlying connection open between requests.  Connection lifetime
    /// and per-connection request limits are governed by
    /// [`crate::types::ProxyConfig::max_requests_per_connection`] and
    /// [`crate::types::ProxyConfig::connection_max_age_secs`].
    PersistentTcp,
}

/// Resolve the [`RoutingPath`] for a request given proxy capabilities and the
/// caller's transport preference.
///
/// # Decision logic
///
/// | Preference       | `supports_http3_tunnel` | Result           |
/// |------------------|------------------------|------------------|
/// | `PreferH3`       | `true`                 | `H3OverUdp`      |
/// | `PreferH3`       | `false`                | `H1H2OverTcp`    |
/// | `ForceTcp`       | any                    | `H1H2OverTcp`    |
/// | `PersistentTcp`  | any                    | `PersistentTcp`  |
///
/// # Example
/// ```
/// use stygian_proxy::routing::{resolve_routing_path, TransportPreference};
/// use stygian_proxy::types::{ProxyCapabilities, RoutingPath};
///
/// let caps = ProxyCapabilities { supports_http3_tunnel: true, ..Default::default() };
/// assert_eq!(
///     resolve_routing_path(&caps, TransportPreference::PreferH3),
///     RoutingPath::H3OverUdp,
/// );
/// assert_eq!(
///     resolve_routing_path(&caps, TransportPreference::ForceTcp),
///     RoutingPath::H1H2OverTcp,
/// );
/// let fallback = ProxyCapabilities::default();
/// assert_eq!(
///     resolve_routing_path(&fallback, TransportPreference::PreferH3),
///     RoutingPath::H1H2OverTcp,
/// );
/// ```
#[must_use]
pub const fn resolve_routing_path(
    capabilities: &ProxyCapabilities,
    preference: TransportPreference,
) -> RoutingPath {
    match preference {
        TransportPreference::ForceTcp => RoutingPath::H1H2OverTcp,
        TransportPreference::PersistentTcp => RoutingPath::PersistentTcp,
        TransportPreference::PreferH3 => {
            if capabilities.supports_http3_tunnel {
                RoutingPath::H3OverUdp
            } else {
                RoutingPath::H1H2OverTcp
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::ProxyCapabilities;

    #[test]
    fn prefer_h3_with_udp_support_returns_h3() {
        let caps = ProxyCapabilities {
            supports_http3_tunnel: true,
            ..Default::default()
        };
        assert_eq!(
            resolve_routing_path(&caps, TransportPreference::PreferH3),
            RoutingPath::H3OverUdp,
        );
    }

    #[test]
    fn prefer_h3_without_udp_support_falls_back_to_tcp() {
        let caps = ProxyCapabilities::default();
        assert_eq!(
            resolve_routing_path(&caps, TransportPreference::PreferH3),
            RoutingPath::H1H2OverTcp,
        );
    }

    #[test]
    fn force_tcp_always_returns_tcp() {
        let caps = ProxyCapabilities {
            supports_http3_tunnel: true,
            ..Default::default()
        };
        assert_eq!(
            resolve_routing_path(&caps, TransportPreference::ForceTcp),
            RoutingPath::H1H2OverTcp,
        );
    }

    #[test]
    fn persistent_tcp_returns_persistent_tcp() {
        let caps = ProxyCapabilities {
            supports_http3_tunnel: true,
            ..Default::default()
        };
        assert_eq!(
            resolve_routing_path(&caps, TransportPreference::PersistentTcp),
            RoutingPath::PersistentTcp,
        );
    }
}