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