1use std::fmt;
4
5use http::header::{HeaderMap, HeaderName, HeaderValue};
6
7use crate::error::{Error, Result};
8
9pub(crate) const MAX_REQUEST_HEADER_BYTES: usize = 64 * 1024;
11
12#[derive(Default, Clone)]
21pub struct Headers {
22 inner: HeaderMap,
23}
24
25impl Headers {
26 #[must_use]
28 pub fn new() -> Self {
29 Self::default()
30 }
31
32 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 #[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 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 #[must_use]
82 pub fn get(&self, name: &str) -> Option<&HeaderValue> {
83 self.inner.get(name)
84 }
85
86 #[must_use]
88 pub fn get_all(&self, name: &str) -> Vec<&HeaderValue> {
89 self.inner.get_all(name).iter().collect()
90 }
91
92 #[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 #[must_use]
103 pub fn contains(&self, name: &str) -> bool {
104 self.inner.contains_key(name)
105 }
106
107 #[must_use]
109 pub fn len(&self) -> usize {
110 self.inner.len()
111 }
112
113 #[must_use]
115 pub fn is_empty(&self) -> bool {
116 self.inner.is_empty()
117 }
118
119 pub fn iter(&self) -> impl Iterator<Item = (&HeaderName, &HeaderValue)> {
121 self.inner.iter()
122 }
123
124 pub fn keys(&self) -> impl Iterator<Item = &HeaderName> {
126 self.inner.keys()
127 }
128
129 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 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 pub fn remove(&mut self, name: &str) -> Option<HeaderValue> {
162 self.inner.remove(name)
163 }
164
165 #[must_use]
167 pub fn into_inner(self) -> HeaderMap {
168 self.inner
169 }
170
171 pub(crate) fn validate_request_size(
173 &self,
174 method: &http::Method,
175 request_target: &[u8],
176 ) -> Result<()> {
177 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 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 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
281fn 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}