Skip to main content

eggfetch_core/
http_version.rs

1//! HTTP version negotiation policy.
2
3/// Policy controlling which HTTP protocol versions the client may negotiate.
4///
5/// The default is [`HttpVersionPolicy::Auto`], which allows the client to
6/// negotiate HTTP/2 via ALPN when available and fall back to HTTP/1.1
7/// otherwise.
8///
9/// When the `http2` feature is not enabled, only [`HttpVersionPolicy::Http1Only`]
10/// is valid; attempting to use `Http2Only` or `Auto` without the `http2`
11/// feature will result in an HTTP/1.1-only client at runtime.
12///
13/// When the `http3` feature is enabled, [`HttpVersionPolicy::Http3Only`]
14/// routes requests over QUIC using the h3 protocol. HTTP/3 uses a separate
15/// transport (Quinn) and does not share connections with HTTP/1.1 or HTTP/2.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
17pub enum HttpVersionPolicy {
18    /// Only HTTP/1.1 is permitted. The client will not advertise `h2` in
19    /// ALPN and will not accept an HTTP/2 response.
20    Http1Only,
21    /// Only HTTP/2 is permitted. The client advertises `h2` via ALPN. If
22    /// the server does not negotiate HTTP/2, the connection fails.
23    Http2Only,
24    /// Only HTTP/3 is permitted. The client uses QUIC via Quinn and the h3
25    /// protocol. Requires the `http3` feature.
26    Http3Only,
27    /// Allow negotiation. The client advertises both `h2` and `http/1.1`
28    /// via ALPN and accepts whichever protocol the server selects.
29    /// When `allow_http3` is `true` and the `http3` feature is enabled,
30    /// HTTP/3 is also included in auto-negotiation. When `allow_http3`
31    /// is `false`, HTTP/3 is excluded; use `Http3Only` to explicitly
32    /// opt in.
33    Auto {
34        /// Whether to allow HTTP/3 in auto-negotiation.
35        allow_http3: bool,
36    },
37}
38
39impl Default for HttpVersionPolicy {
40    fn default() -> Self {
41        Self::Auto { allow_http3: false }
42    }
43}
44
45impl HttpVersionPolicy {
46    /// Returns `true` if HTTP/3 should be used.
47    #[cfg(any(feature = "http3", test))]
48    #[allow(dead_code)]
49    pub(crate) fn use_http3(self) -> bool {
50        matches!(self, Self::Http3Only) || matches!(self, Self::Auto { allow_http3: true })
51    }
52}
53
54/// Internal helper that resolves which protocol versions to enable on the
55/// connector based on the policy and compiled feature flags.
56#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
57pub(crate) struct HttpVersionPolicyEnabler(HttpVersionPolicy);
58
59impl HttpVersionPolicyEnabler {
60    /// Create an enabler from a policy. When the `http2` feature is not
61    /// enabled, `Http2Only` and `Auto` are silently downgraded to
62    /// `Http1Only`. When the `http3` feature is not enabled, `Http3Only`
63    /// is silently downgraded to `Http1Only`.
64    #[must_use]
65    pub(crate) fn from_policy(policy: HttpVersionPolicy) -> Self {
66        match policy {
67            #[cfg(not(feature = "http2"))]
68            HttpVersionPolicy::Http2Only => Self(HttpVersionPolicy::Http1Only),
69            #[cfg(not(feature = "http3"))]
70            HttpVersionPolicy::Http3Only => Self(HttpVersionPolicy::Http1Only),
71            #[allow(unused_variables)]
72            HttpVersionPolicy::Auto { allow_http3 } => {
73                #[cfg(not(feature = "http2"))]
74                return Self(HttpVersionPolicy::Http1Only);
75                #[cfg(all(feature = "http2", not(feature = "http3")))]
76                return Self(HttpVersionPolicy::Auto { allow_http3: false });
77                #[cfg(all(feature = "http2", feature = "http3"))]
78                return Self(HttpVersionPolicy::Auto { allow_http3 });
79            }
80            _ => Self(policy),
81        }
82    }
83
84    /// Returns `true` if HTTP/1.1 should be enabled on the connector.
85    #[must_use]
86    #[allow(dead_code)]
87    pub(crate) const fn enable_http1(self) -> bool {
88        matches!(
89            self.0,
90            HttpVersionPolicy::Http1Only | HttpVersionPolicy::Auto { .. }
91        )
92    }
93
94    /// Returns `true` if HTTP/2 should be enabled on the connector.
95    #[must_use]
96    #[allow(dead_code)]
97    pub(crate) const fn enable_http2(self) -> bool {
98        matches!(
99            self.0,
100            HttpVersionPolicy::Http2Only | HttpVersionPolicy::Auto { .. }
101        )
102    }
103
104    /// Returns `true` if HTTP/3 should be used (QUIC transport).
105    #[must_use]
106    #[allow(dead_code)]
107    pub(crate) fn use_http3(self) -> bool {
108        match self.0 {
109            HttpVersionPolicy::Http3Only => true,
110            HttpVersionPolicy::Auto { allow_http3 } => allow_http3,
111            _ => false,
112        }
113    }
114}
115
116#[cfg(test)]
117mod tests {
118    use super::*;
119
120    #[test]
121    fn default_is_auto() {
122        assert_eq!(
123            HttpVersionPolicy::default(),
124            HttpVersionPolicy::Auto { allow_http3: false }
125        );
126    }
127
128    #[test]
129    fn http1_only_enables_http1_only() {
130        let enabler = HttpVersionPolicyEnabler::from_policy(HttpVersionPolicy::Http1Only);
131        assert!(enabler.enable_http1());
132        assert!(!enabler.enable_http2());
133        assert!(!enabler.use_http3());
134    }
135
136    #[test]
137    #[cfg(feature = "http2")]
138    fn auto_enables_both() {
139        let enabler =
140            HttpVersionPolicyEnabler::from_policy(HttpVersionPolicy::Auto { allow_http3: false });
141        assert!(enabler.enable_http1());
142        assert!(enabler.enable_http2());
143        assert!(!enabler.use_http3());
144    }
145
146    #[test]
147    #[cfg(not(feature = "http2"))]
148    fn auto_downgrades_without_feature() {
149        let enabler =
150            HttpVersionPolicyEnabler::from_policy(HttpVersionPolicy::Auto { allow_http3: false });
151        assert!(enabler.enable_http1());
152        assert!(!enabler.enable_http2());
153    }
154
155    #[test]
156    #[cfg(feature = "http2")]
157    fn http2_only_enables_http2_only() {
158        let enabler = HttpVersionPolicyEnabler::from_policy(HttpVersionPolicy::Http2Only);
159        assert!(!enabler.enable_http1());
160        assert!(enabler.enable_http2());
161    }
162
163    #[test]
164    #[cfg(not(feature = "http2"))]
165    fn http2_only_downgrades_without_feature() {
166        let enabler = HttpVersionPolicyEnabler::from_policy(HttpVersionPolicy::Http2Only);
167        assert!(enabler.enable_http1());
168        assert!(!enabler.enable_http2());
169    }
170
171    #[test]
172    #[cfg(feature = "http3")]
173    fn http3_only_enables_http3_only() {
174        let enabler = HttpVersionPolicyEnabler::from_policy(HttpVersionPolicy::Http3Only);
175        assert!(!enabler.enable_http1());
176        assert!(!enabler.enable_http2());
177        assert!(enabler.use_http3());
178    }
179
180    #[test]
181    #[cfg(not(feature = "http3"))]
182    fn http3_only_downgrades_without_feature() {
183        let enabler = HttpVersionPolicyEnabler::from_policy(HttpVersionPolicy::Http3Only);
184        assert!(enabler.enable_http1());
185        assert!(!enabler.enable_http2());
186        assert!(!enabler.use_http3());
187    }
188}