hyper/ext/mod.rs
1//! Extensions for HTTP messages in Hyper.
2//!
3//! This module provides types and utilities that extend the capabilities of HTTP requests and responses
4//! in Hyper. Extensions are additional pieces of information or features that can be attached to HTTP
5//! messages via the [`http::Extensions`] map, which is
6//! accessible through methods like [`http::Request::extensions`] and [`http::Response::extensions`].
7//!
8//! # What are extensions?
9//!
10//! Extensions allow Hyper to associate extra metadata or behaviors with HTTP messages, beyond the standard
11//! headers and body. These can be used by advanced users and library authors to access protocol-specific
12//! features, track original header casing, handle informational responses, and more.
13//!
14//! # How to access extensions
15//!
16//! Extensions are stored in the `Extensions` map of a request or response. You can access them using:
17//!
18//! ```rust
19//! # let response = http::Response::new(());
20//! if let Some(ext) = response.extensions().get::<hyper::ext::ReasonPhrase>() {
21//! // use the extension
22//! }
23//! ```
24//!
25//! # Extension Groups
26//!
27//! The extensions in this module can be grouped as follows:
28//!
29//! - **HTTP/1 Reason Phrase**: [`ReasonPhrase`] — Access non-canonical reason phrases in HTTP/1 responses.
30//! - **Informational Responses**: [`on_informational`] — Register callbacks for 1xx HTTP/1 responses on the client.
31//! - **Header Case Tracking**: Internal types for tracking the original casing and order of headers as received.
32//! - **HTTP/2 Protocol Extensions**: [`Protocol`] — Access the `:protocol` pseudo-header for Extended CONNECT in HTTP/2.
33//!
34//! Some extensions are only available for specific protocols (HTTP/1 or HTTP/2) or use cases (client, server, FFI).
35//!
36//! See the documentation on each item for details about its usage and requirements.
37
38#[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
39use bytes::Bytes;
40#[cfg(any(
41 all(any(feature = "client", feature = "server"), feature = "http1"),
42 feature = "ffi"
43))]
44use http::header::HeaderName;
45#[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
46use http::header::{HeaderMap, IntoHeaderName, ValueIter};
47#[cfg(feature = "ffi")]
48use std::collections::HashMap;
49#[cfg(feature = "http2")]
50use std::fmt;
51
52#[cfg(any(feature = "http1", feature = "ffi"))]
53mod h1_reason_phrase;
54#[cfg(any(feature = "http1", feature = "ffi"))]
55pub use h1_reason_phrase::ReasonPhrase;
56
57#[cfg(all(feature = "http1", feature = "client"))]
58mod informational;
59#[cfg(all(feature = "http1", feature = "client"))]
60pub use informational::on_informational;
61#[cfg(all(feature = "http1", feature = "client"))]
62pub(crate) use informational::OnInformational;
63#[cfg(all(feature = "http1", feature = "client", feature = "ffi"))]
64pub(crate) use informational::{on_informational_raw, OnInformationalCallback};
65
66#[cfg(feature = "http2")]
67/// Extension type representing the `:protocol` pseudo-header in HTTP/2.
68///
69/// The `Protocol` extension allows access to the value of the `:protocol` pseudo-header
70/// used by the [Extended CONNECT Protocol](https://datatracker.ietf.org/doc/html/rfc8441#section-4).
71/// This extension is only sent on HTTP/2 CONNECT requests, most commonly with the value `websocket`.
72///
73/// # Example
74///
75/// ```rust
76/// use hyper::ext::Protocol;
77/// use http::{Request, Method, Version};
78///
79/// let mut req = Request::new(());
80/// *req.method_mut() = Method::CONNECT;
81/// *req.version_mut() = Version::HTTP_2;
82/// req.extensions_mut().insert(Protocol::from_static("websocket"));
83/// // Now the request will include the `:protocol` pseudo-header with value "websocket"
84/// ```
85#[derive(Clone, Eq, PartialEq)]
86pub struct Protocol {
87 inner: h2::ext::Protocol,
88}
89
90#[cfg(feature = "http2")]
91impl Protocol {
92 /// Converts a static string to a protocol name.
93 pub const fn from_static(value: &'static str) -> Self {
94 Self {
95 inner: h2::ext::Protocol::from_static(value),
96 }
97 }
98
99 /// Returns a str representation of the header.
100 pub fn as_str(&self) -> &str {
101 self.inner.as_str()
102 }
103
104 #[cfg(feature = "server")]
105 pub(crate) fn from_inner(inner: h2::ext::Protocol) -> Self {
106 Self { inner }
107 }
108
109 #[cfg(all(feature = "client", feature = "http2"))]
110 pub(crate) fn into_inner(self) -> h2::ext::Protocol {
111 self.inner
112 }
113}
114
115#[cfg(feature = "http2")]
116impl<'a> From<&'a str> for Protocol {
117 fn from(value: &'a str) -> Self {
118 Self {
119 inner: h2::ext::Protocol::from(value),
120 }
121 }
122}
123
124#[cfg(feature = "http2")]
125impl AsRef<[u8]> for Protocol {
126 fn as_ref(&self) -> &[u8] {
127 self.inner.as_ref()
128 }
129}
130
131#[cfg(feature = "http2")]
132impl fmt::Debug for Protocol {
133 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
134 self.inner.fmt(f)
135 }
136}
137
138/// A map from header names to their original casing as received in an HTTP message.
139///
140/// If an HTTP/1 response `res` is parsed on a connection whose option
141/// [`preserve_header_case`] was set to true and the response included
142/// the following headers:
143///
144/// ```ignore
145/// x-Bread: Baguette
146/// X-BREAD: Pain
147/// x-bread: Ficelle
148/// ```
149///
150/// Then `res.extensions().get::<HeaderCaseMap>()` will return a map with:
151///
152/// ```ignore
153/// HeaderCaseMap({
154/// "x-bread": ["x-Bread", "X-BREAD", "x-bread"],
155/// })
156/// ```
157///
158/// [`preserve_header_case`]: /client/struct.Client.html#method.preserve_header_case
159#[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
160#[derive(Clone, Debug)]
161pub(crate) struct HeaderCaseMap(HeaderMap<Bytes>);
162
163#[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
164impl HeaderCaseMap {
165 /// Returns a view of all spellings associated with that header name,
166 /// in the order they were found.
167 #[cfg(feature = "client")]
168 pub(crate) fn get_all<'a>(
169 &'a self,
170 name: &HeaderName,
171 ) -> impl Iterator<Item = impl AsRef<[u8]> + 'a> + 'a {
172 self.get_all_internal(name)
173 }
174
175 /// Returns a view of all spellings associated with that header name,
176 /// in the order they were found.
177 #[cfg(any(feature = "client", feature = "server"))]
178 pub(crate) fn get_all_internal(&self, name: &HeaderName) -> ValueIter<'_, Bytes> {
179 self.0.get_all(name).into_iter()
180 }
181
182 #[cfg(any(feature = "client", feature = "server"))]
183 pub(crate) fn default() -> Self {
184 Self(Default::default())
185 }
186
187 #[cfg(any(test, feature = "ffi"))]
188 pub(crate) fn insert(&mut self, name: HeaderName, orig: Bytes) {
189 self.0.insert(name, orig);
190 }
191
192 #[cfg(any(feature = "client", feature = "server"))]
193 pub(crate) fn append<N>(&mut self, name: N, orig: Bytes)
194 where
195 N: IntoHeaderName,
196 {
197 self.0.append(name, orig);
198 }
199}
200
201#[cfg(feature = "ffi")]
202#[derive(Clone, Debug)]
203/// Hashmap<Headername, numheaders with that name>
204pub(crate) struct OriginalHeaderOrder {
205 /// Stores how many entries a Headername maps to. This is used
206 /// for accounting.
207 num_entries: HashMap<HeaderName, usize>,
208 /// Stores the ordering of the headers. ex: `vec[i] = (headerName, idx)`,
209 /// The vector is ordered such that the ith element
210 /// represents the ith header that came in off the line.
211 /// The `HeaderName` and `idx` are then used elsewhere to index into
212 /// the multi map that stores the header values.
213 entry_order: Vec<(HeaderName, usize)>,
214}
215
216#[cfg(all(feature = "http1", feature = "ffi"))]
217impl OriginalHeaderOrder {
218 pub(crate) fn default() -> Self {
219 OriginalHeaderOrder {
220 num_entries: HashMap::new(),
221 entry_order: Vec::new(),
222 }
223 }
224
225 pub(crate) fn insert(&mut self, name: HeaderName) {
226 if !self.num_entries.contains_key(&name) {
227 let idx = 0;
228 self.num_entries.insert(name.clone(), 1);
229 self.entry_order.push((name, idx));
230 }
231 // Replacing an already existing element does not
232 // change ordering, so we only care if its the first
233 // header name encountered
234 }
235
236 pub(crate) fn append<N>(&mut self, name: N)
237 where
238 N: IntoHeaderName + Into<HeaderName> + Clone,
239 {
240 let name: HeaderName = name.into();
241 let idx;
242 if self.num_entries.contains_key(&name) {
243 idx = self.num_entries[&name];
244 *self.num_entries.get_mut(&name).unwrap() += 1;
245 } else {
246 idx = 0;
247 self.num_entries.insert(name.clone(), 1);
248 }
249 self.entry_order.push((name, idx));
250 }
251
252 // No doc test is run here because `RUSTFLAGS='--cfg hyper_unstable_ffi'`
253 // is needed to compile. Once ffi is stabilized `no_run` should be removed
254 // here.
255 /// This returns an iterator that provides header names and indexes
256 /// in the original order received.
257 ///
258 /// # Examples
259 /// ```no_run
260 /// use hyper::ext::OriginalHeaderOrder;
261 /// use hyper::header::{HeaderName, HeaderValue, HeaderMap};
262 ///
263 /// let mut h_order = OriginalHeaderOrder::default();
264 /// let mut h_map = Headermap::new();
265 ///
266 /// let name1 = b"Set-CookiE";
267 /// let value1 = b"a=b";
268 /// h_map.append(name1);
269 /// h_order.append(name1);
270 ///
271 /// let name2 = b"Content-Encoding";
272 /// let value2 = b"gzip";
273 /// h_map.append(name2, value2);
274 /// h_order.append(name2);
275 ///
276 /// let name3 = b"SET-COOKIE";
277 /// let value3 = b"c=d";
278 /// h_map.append(name3, value3);
279 /// h_order.append(name3)
280 ///
281 /// let mut iter = h_order.get_in_order()
282 ///
283 /// let (name, idx) = iter.next();
284 /// assert_eq!(b"a=b", h_map.get_all(name).nth(idx).unwrap());
285 ///
286 /// let (name, idx) = iter.next();
287 /// assert_eq!(b"gzip", h_map.get_all(name).nth(idx).unwrap());
288 ///
289 /// let (name, idx) = iter.next();
290 /// assert_eq!(b"c=d", h_map.get_all(name).nth(idx).unwrap());
291 /// ```
292 pub(crate) fn get_in_order(&self) -> impl Iterator<Item = &(HeaderName, usize)> {
293 self.entry_order.iter()
294 }
295}