Skip to main content

eggfetch_core/
headers.rs

1//! Header container.
2
3use std::fmt;
4
5use http::header::{HeaderMap, HeaderName, HeaderValue};
6
7use crate::error::{Error, Result};
8
9/// Maximum serialized size of an outbound request's headers.
10pub(crate) const MAX_REQUEST_HEADER_BYTES: usize = 64 * 1024;
11
12/// Case-insensitive HTTP header container.
13///
14/// `Debug` formatting redacts values for header names recognised as
15/// sensitive (see [`crate::redact::SENSITIVE_HEADERS`]) so that
16/// logging, error formatting, and panic messages do not leak
17/// credentials.  Ordinary iteration (`iter`, `get`, `get_all`,
18/// `keys`) is intentionally **not** redacted — diagnostics are the
19/// only output channel that needs to be safe by default.
20#[derive(Default, Clone)]
21pub struct Headers {
22    inner: HeaderMap,
23}
24
25impl Headers {
26    /// Create an empty header container.
27    #[must_use]
28    pub fn new() -> Self {
29        Self::default()
30    }
31
32    /// Insert a header, replacing any existing value with the same name.
33    ///
34    /// # Errors
35    ///
36    /// Returns an error if the name or value is not valid.
37    pub fn insert(&mut self, name: &str, value: &str) -> Result<()> {
38        validate_header_name(name)?;
39        validate_header_value(value)?;
40        let name =
41            HeaderName::try_from(name).map_err(|e| Error::InvalidHeaderName(e.to_string()))?;
42        let value =
43            HeaderValue::try_from(value).map_err(|e| Error::InvalidHeaderValue(e.to_string()))?;
44        self.inner.insert(name, value);
45        Ok(())
46    }
47
48    /// Insert a header without validation (wire-decoded path).
49    ///
50    /// This bypasses [`validate_header_value`] intentionally: proxy and
51    /// transport decoders use `HeaderValue::from_bytes` which preserves
52    /// HTTP `obs-text` (0x80..=0xFF) and may carry wire bytes that user-
53    /// supplied validation rejects (e.g., `NUL`). User-facing `insert` /
54    /// `append` always validate; `insert_raw` is only for trusted wire
55    /// data already parsed by hyper or the proxy response reader.
56    #[allow(
57        dead_code,
58        reason = "the raw-insert path is only reached from the multipart and redirect features, so it is dead code when neither is enabled"
59    )]
60    pub(crate) fn insert_raw(&mut self, name: HeaderName, value: HeaderValue) {
61        self.inner.insert(name, value);
62    }
63
64    /// Append a header value, allowing multiple values for the same name.
65    ///
66    /// # Errors
67    ///
68    /// Returns an error if the name or value is not valid.
69    pub fn append(&mut self, name: &str, value: &str) -> Result<()> {
70        validate_header_name(name)?;
71        validate_header_value(value)?;
72        let name =
73            HeaderName::try_from(name).map_err(|e| Error::InvalidHeaderName(e.to_string()))?;
74        let value =
75            HeaderValue::try_from(value).map_err(|e| Error::InvalidHeaderValue(e.to_string()))?;
76        self.inner.append(name, value);
77        Ok(())
78    }
79
80    /// Get a header value by name.
81    #[must_use]
82    pub fn get(&self, name: &str) -> Option<&HeaderValue> {
83        self.inner.get(name)
84    }
85
86    /// Get all values for a header by name.
87    #[must_use]
88    pub fn get_all(&self, name: &str) -> Vec<&HeaderValue> {
89        self.inner.get_all(name).iter().collect()
90    }
91
92    /// Get a header value as a string by name.
93    #[must_use]
94    pub fn get_str(
95        &self,
96        name: &str,
97    ) -> Option<std::result::Result<&str, http::header::ToStrError>> {
98        self.inner.get(name).map(|v| v.to_str())
99    }
100
101    /// Returns `true` if the headers contain a value for the given name.
102    #[must_use]
103    pub fn contains(&self, name: &str) -> bool {
104        self.inner.contains_key(name)
105    }
106
107    /// Returns the number of headers.
108    #[must_use]
109    pub fn len(&self) -> usize {
110        self.inner.len()
111    }
112
113    /// Returns `true` if there are no headers.
114    #[must_use]
115    pub fn is_empty(&self) -> bool {
116        self.inner.is_empty()
117    }
118
119    /// Iterate over all header name-value pairs.
120    pub fn iter(&self) -> impl Iterator<Item = (&HeaderName, &HeaderValue)> {
121        self.inner.iter()
122    }
123
124    /// Iterate over all header names.
125    pub fn keys(&self) -> impl Iterator<Item = &HeaderName> {
126        self.inner.keys()
127    }
128
129    /// Extend these headers by appending all values from another set.
130    ///
131    /// This is **append-only**: existing values for a name are preserved and
132    /// values from `other` are appended, potentially creating duplicates
133    /// (e.g. two `Content-Type` values). This preserves multi-value headers
134    /// like `Set-Cookie`. Callers that need replacement semantics should
135    /// remove the header name first, as the request pipeline does when
136    /// applying request headers over client defaults, or use
137    /// [`Self::extend_replacing`].
138    pub fn extend(&mut self, other: &Self) {
139        for name in other.inner.keys() {
140            for value in other.inner.get_all(name) {
141                self.inner.append(name.clone(), value.clone());
142            }
143        }
144    }
145
146    /// Extend by replacing values for names present in `other`.
147    ///
148    /// For each header name in `other`, any existing values in `self` are
149    /// removed before appending the values from `other`. Multi-value headers
150    /// from `other` (e.g. `Set-Cookie`) are preserved.
151    pub fn extend_replacing(&mut self, other: &Self) {
152        for name in other.inner.keys() {
153            self.inner.remove(name);
154            for value in other.inner.get_all(name) {
155                self.inner.append(name.clone(), value.clone());
156            }
157        }
158    }
159
160    /// Remove a header by name (case-insensitive).
161    pub fn remove(&mut self, name: &str) -> Option<HeaderValue> {
162        self.inner.remove(name)
163    }
164
165    /// Consume and return the inner `HeaderMap`.
166    #[must_use]
167    pub fn into_inner(self) -> HeaderMap {
168        self.inner
169    }
170
171    /// Reject an outbound header set that would exceed the request limit.
172    pub(crate) fn validate_request_size(
173        &self,
174        method: &http::Method,
175        request_target: &[u8],
176    ) -> Result<()> {
177        // Include `METHOD request-target HTTP/1.1\r\n` because it is part of
178        // the serialized HTTP/1 request and is subject to the same bound.
179        let request_line_size = method
180            .as_str()
181            .len()
182            .checked_add(1)
183            .and_then(|size| size.checked_add(request_target.len()))
184            .and_then(|size| size.checked_add(1 + "HTTP/1.1".len() + 2));
185        // `MAX_REQUEST_HEADER_BYTES` also includes the trailing CRLF that
186        // separates headers from the body.
187        let size = request_line_size.and_then(|size| {
188            self.inner.iter().try_fold(size, |size, (name, value)| {
189                size.checked_add(name.as_str().len() + value.as_bytes().len() + 4)
190            })
191        });
192        if size.is_none_or(|size| {
193            size.checked_add(2)
194                .is_none_or(|size| size > MAX_REQUEST_HEADER_BYTES)
195        }) {
196            return Err(Error::RequestBuild(format!(
197                "request headers exceed maximum size of {MAX_REQUEST_HEADER_BYTES} bytes"
198            )));
199        }
200        Ok(())
201    }
202
203    /// Validate a request target without allocating its display string.
204    pub(crate) fn validate_request_size_uri(
205        &self,
206        method: &http::Method,
207        request_target: &http::Uri,
208    ) -> Result<()> {
209        struct CountWriter(usize);
210        impl fmt::Write for CountWriter {
211            fn write_str(&mut self, value: &str) -> fmt::Result {
212                self.0 = self.0.checked_add(value.len()).ok_or(fmt::Error)?;
213                Ok(())
214            }
215        }
216
217        let mut writer = CountWriter(0);
218        fmt::write(&mut writer, format_args!("{request_target}"))
219            .map_err(|_| Error::RequestBuild("request target serialization overflowed".into()))?;
220        self.validate_request_size_len(method, writer.0)
221    }
222
223    fn validate_request_size_len(&self, method: &http::Method, target_len: usize) -> Result<()> {
224        let request_line_size = method
225            .as_str()
226            .len()
227            .checked_add(1)
228            .and_then(|size| size.checked_add(target_len))
229            .and_then(|size| size.checked_add(1 + "HTTP/1.1".len() + 2));
230        let size = request_line_size.and_then(|size| {
231            self.inner.iter().try_fold(size, |size, (name, value)| {
232                size.checked_add(name.as_str().len() + value.as_bytes().len() + 4)
233            })
234        });
235        if size.is_none_or(|size| {
236            size.checked_add(2)
237                .is_none_or(|size| size > MAX_REQUEST_HEADER_BYTES)
238        }) {
239            return Err(Error::RequestBuild(format!(
240                "request headers exceed maximum size of {MAX_REQUEST_HEADER_BYTES} bytes"
241            )));
242        }
243        Ok(())
244    }
245}
246
247impl From<HeaderMap> for Headers {
248    fn from(inner: HeaderMap) -> Self {
249        Self { inner }
250    }
251}
252
253impl fmt::Debug for Headers {
254    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
255        let mut debug = f.debug_map();
256        for (name, value) in &self.inner {
257            if crate::redact::is_sensitive_header(name.as_str()) {
258                debug.entry(&name, &"<redacted>");
259            } else {
260                debug.entry(&name, &value);
261            }
262        }
263        debug.finish()
264    }
265}
266
267fn validate_header_name(name: &str) -> Result<()> {
268    if name.is_empty() {
269        return Err(Error::InvalidHeaderName(
270            "header name must not be empty".into(),
271        ));
272    }
273    if name.contains('\n') || name.contains('\r') {
274        return Err(Error::InvalidHeaderName(
275            "header name must not contain newlines".into(),
276        ));
277    }
278    Ok(())
279}
280
281/// Validate a header value for user-supplied headers.
282///
283/// Rejects `NUL` (`\0`) and other C0 controls except `\t`, matching the
284/// safe subset for outbound requests. Wire-decoded headers arriving via
285/// `insert_raw` bypass this check intentionally so `obs-text` (0x80..=0xFF)
286/// and proxy-decoded `HeaderValue::from_bytes` bytes are preserved
287/// (see `insert_raw` docs). The split is intentional: user input is
288/// strictly validated, trusted wire data is preserved verbatim.
289fn validate_header_value(value: &str) -> Result<()> {
290    if value
291        .bytes()
292        .any(|byte| (byte < 0x20 && byte != b'\t') || byte == 0x7f)
293    {
294        return Err(Error::InvalidHeaderValue(
295            "header value must not contain control characters".into(),
296        ));
297    }
298    Ok(())
299}
300
301#[cfg(test)]
302mod tests {
303    use super::*;
304    use proptest::prelude::*;
305
306    #[test]
307    fn insert_and_get() {
308        let mut h = Headers::new();
309        h.insert("X-Custom", "value1").unwrap();
310        assert_eq!(h.get("x-custom").unwrap().to_str().unwrap(), "value1");
311    }
312
313    #[test]
314    fn append_duplicates() {
315        let mut h = Headers::new();
316        h.append("Set-Cookie", "a=1").unwrap();
317        h.append("Set-Cookie", "b=2").unwrap();
318        let values: Vec<_> = h.inner.get_all("set-cookie").iter().collect();
319        assert_eq!(values.len(), 2);
320    }
321
322    #[test]
323    fn extend_preserves_duplicate_values() {
324        let mut first = Headers::new();
325        first.append("Set-Cookie", "a=1").unwrap();
326        let mut second = Headers::new();
327        second.append("Set-Cookie", "b=2").unwrap();
328
329        first.extend(&second);
330
331        let values: Vec<_> = first.inner.get_all("set-cookie").iter().collect();
332        assert_eq!(values.len(), 2);
333    }
334
335    #[test]
336    fn contains() {
337        let mut h = Headers::new();
338        h.insert("Content-Type", "text/plain").unwrap();
339        assert!(h.contains("content-type"));
340        assert!(!h.contains("x-missing"));
341    }
342
343    #[test]
344    fn empty_name_rejected() {
345        let mut h = Headers::new();
346        assert!(h.insert("", "value").is_err());
347    }
348
349    #[test]
350    fn newline_in_name_rejected() {
351        let mut h = Headers::new();
352        assert!(h.insert("X-Bad\n", "value").is_err());
353    }
354
355    #[test]
356    fn newline_in_value_rejected() {
357        let mut h = Headers::new();
358        assert!(h.insert("X-Bad", "value\r\ninjection").is_err());
359    }
360
361    #[test]
362    fn control_characters_in_value_rejected() {
363        for value in ["value\0", "value\x1f", "value\x7f"] {
364            let mut h = Headers::new();
365            assert!(h.insert("X-Bad", value).is_err());
366        }
367    }
368
369    #[test]
370    fn horizontal_tab_in_value_allowed() {
371        let mut h = Headers::new();
372        assert!(h.insert("X-Test", "value\twith-tab").is_ok());
373    }
374
375    #[test]
376    fn from_headermap() {
377        let mut hm = HeaderMap::new();
378        hm.insert("X-Test", HeaderValue::from_static("hello"));
379        let h = Headers::from(hm);
380        assert_eq!(h.get("x-test").unwrap().to_str().unwrap(), "hello");
381    }
382
383    #[test]
384    fn uri_size_validation_matches_display_length() {
385        let headers = Headers::new();
386        for target in [
387            "http://example.com/path?q=1",
388            "/origin-form?q=1",
389            "*",
390            "https://example.com:8443/absolute",
391        ] {
392            let uri: http::Uri = target.parse().unwrap();
393            assert_eq!(uri.to_string().len(), target.len());
394            headers
395                .validate_request_size_uri(&http::Method::GET, &uri)
396                .unwrap();
397        }
398    }
399
400    #[test]
401    fn request_header_size_is_bounded() {
402        let mut headers = Headers::new();
403        headers
404            .insert("x-large", &"x".repeat(MAX_REQUEST_HEADER_BYTES))
405            .unwrap();
406        assert!(headers
407            .validate_request_size(&http::Method::GET, b"/")
408            .is_err());
409
410        let headers = Headers::new();
411        let target = vec![b'/'; MAX_REQUEST_HEADER_BYTES];
412        assert!(headers
413            .validate_request_size(&http::Method::GET, &target)
414            .is_err());
415    }
416
417    proptest::proptest! {
418        #[test]
419        fn round_trip_insert_get(name in "[a-zA-Z][a-zA-Z0-9_-]{0,20}", value in "[a-zA-Z0-9 ]{1,30}") {
420            let mut h = Headers::new();
421            h.insert(&name, &value).unwrap();
422            let got = h.get_str(&name).unwrap().unwrap();
423            prop_assert_eq!(got, value.as_str());
424        }
425
426        #[test]
427        fn insert_replaces_previous(name in "[a-zA-Z][a-zA-Z0-9_-]{0,20}", v1 in "[a-z]{1,10}", v2 in "[a-z]{1,10}") {
428            let mut h = Headers::new();
429            h.insert(&name, &v1).unwrap();
430            h.insert(&name, &v2).unwrap();
431            let got = h.get_str(&name).unwrap().unwrap();
432            prop_assert_eq!(got, v2.as_str());
433        }
434
435        #[test]
436        fn append_preserves_all(name in "[a-zA-Z][a-zA-Z0-9_-]{0,20}", values in proptest::collection::vec("[a-z]{1,10}", 1..5)) {
437            let mut h = Headers::new();
438            for v in &values {
439                h.append(&name, v).unwrap();
440            }
441            let all = h.get_all(&name);
442            prop_assert_eq!(all.len(), values.len());
443        }
444
445        #[test]
446        fn contains_after_insert(name in "[a-zA-Z][a-zA-Z0-9_-]{0,20}", value in "[a-z]{1,10}") {
447            let mut h = Headers::new();
448            prop_assert!(!h.contains(&name));
449            h.insert(&name, &value).unwrap();
450            prop_assert!(h.contains(&name));
451        }
452
453        #[test]
454        fn prop_empty_name_rejected(value in "[a-z]{1,10}") {
455            let mut h = Headers::new();
456            prop_assert!(h.insert("", &value).is_err());
457        }
458
459        #[test]
460        fn prop_newline_in_name_rejected(name in "[a-zA-Z][a-zA-Z0-9_-]{0,10}", value in "[a-z]{1,10}") {
461            let mut h = Headers::new();
462            let bad_name = format!("{name}\n");
463            prop_assert!(h.insert(&bad_name, &value).is_err());
464        }
465
466        #[test]
467        fn prop_newline_in_value_rejected(name in "[a-zA-Z][a-zA-Z0-9_-]{0,10}", value in "[a-z]{1,10}") {
468            let mut h = Headers::new();
469            let bad_value = format!("{value}\r\ninjection");
470            prop_assert!(h.insert(&name, &bad_value).is_err());
471        }
472    }
473}