use core::fmt;
use std::error::Error;
use std::str::FromStr;
pub const MAX_HEADER_NAME_BYTES: usize = 128;
pub const MAX_HEADER_VALUE_BYTES: usize = 8 * 1024;
pub const MAX_HEADERS: usize = 128;
#[derive(Clone, Debug)]
pub struct HeaderName {
text: String,
}
impl HeaderName {
pub fn new(text: impl Into<String>) -> Result<Self, HeaderError> {
let text = text.into();
if text.is_empty() {
return Err(HeaderError::EmptyName);
}
if text.len() > MAX_HEADER_NAME_BYTES {
return Err(HeaderError::NameTooLong { length: text.len() });
}
if let Some(offset) = text.bytes().position(|byte| !is_token_byte(byte)) {
return Err(HeaderError::InvalidName {
name: bounded(&text),
offset,
});
}
Ok(Self { text })
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.text
}
#[must_use]
pub fn matches(&self, other: &str) -> bool {
self.text.eq_ignore_ascii_case(other)
}
}
impl PartialEq for HeaderName {
fn eq(&self, other: &Self) -> bool {
self.text.eq_ignore_ascii_case(&other.text)
}
}
impl Eq for HeaderName {}
impl FromStr for HeaderName {
type Err = HeaderError;
fn from_str(input: &str) -> Result<Self, Self::Err> {
Self::new(input)
}
}
impl TryFrom<&str> for HeaderName {
type Error = HeaderError;
fn try_from(input: &str) -> Result<Self, Self::Error> {
Self::new(input)
}
}
impl fmt::Display for HeaderName {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.text)
}
}
const fn is_token_byte(byte: u8) -> bool {
byte.is_ascii_alphanumeric()
|| matches!(
byte,
b'!' | b'#' | b'$' | b'%' | b'&' | b'\'' | b'*' | b'+' | b'-' | b'.' | b'^' | b'_' | b'`' | b'|' | b'~'
)
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct HeaderValue {
text: String,
}
impl HeaderValue {
pub fn new(text: impl AsRef<str>) -> Result<Self, HeaderError> {
let text = text.as_ref().trim_matches(is_optional_whitespace);
if text.len() > MAX_HEADER_VALUE_BYTES {
return Err(HeaderError::ValueTooLong { length: text.len() });
}
if let Some((offset, _)) = text.char_indices().find(|(_, scalar)| !is_field_scalar(*scalar)) {
return Err(HeaderError::InvalidValue {
value: bounded(text),
offset,
});
}
Ok(Self { text: text.to_owned() })
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.text
}
}
impl FromStr for HeaderValue {
type Err = HeaderError;
fn from_str(input: &str) -> Result<Self, Self::Err> {
Self::new(input)
}
}
impl TryFrom<&str> for HeaderValue {
type Error = HeaderError;
fn try_from(input: &str) -> Result<Self, Self::Error> {
Self::new(input)
}
}
impl fmt::Display for HeaderValue {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.text)
}
}
const fn is_optional_whitespace(scalar: char) -> bool {
matches!(scalar, ' ' | '\t')
}
const fn is_field_scalar(scalar: char) -> bool {
matches!(scalar, '\t' | '\u{20}'..='\u{7e}' | '\u{a0}'..='\u{ff}')
}
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct Headers {
entries: Vec<(HeaderName, HeaderValue)>,
}
impl Headers {
#[must_use]
pub const fn new() -> Self {
Self { entries: Vec::new() }
}
pub fn from_pairs(pairs: impl IntoIterator<Item = (HeaderName, HeaderValue)>) -> Result<Self, HeaderError> {
let mut headers = Self::new();
for (name, value) in pairs {
headers.insert(name, value)?;
}
Ok(headers)
}
pub fn insert(&mut self, name: HeaderName, value: HeaderValue) -> Result<(), HeaderError> {
if self.entries.len() >= MAX_HEADERS {
return Err(HeaderError::TooManyHeaders { maximum: MAX_HEADERS });
}
if self.entries.iter().any(|(existing, _)| *existing == name) {
return Err(HeaderError::DuplicateHeader {
name: bounded(name.as_str()),
});
}
self.entries.push((name, value));
Ok(())
}
#[must_use]
pub fn get(&self, name: &str) -> Option<&str> {
self.entries
.iter()
.find(|(existing, _)| existing.matches(name))
.map(|(_, value)| value.as_str())
}
#[must_use]
pub fn contains(&self, name: &str) -> bool {
self.get(name).is_some()
}
pub fn iter(&self) -> impl Iterator<Item = (&HeaderName, &HeaderValue)> {
self.entries.iter().map(|(name, value)| (name, value))
}
#[must_use]
pub fn len(&self) -> usize {
self.entries.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
}
impl<'headers> IntoIterator for &'headers Headers {
type Item = (&'headers HeaderName, &'headers HeaderValue);
type IntoIter = std::iter::Map<
std::slice::Iter<'headers, (HeaderName, HeaderValue)>,
fn(&'headers (HeaderName, HeaderValue)) -> (&'headers HeaderName, &'headers HeaderValue),
>;
fn into_iter(self) -> Self::IntoIter {
self.entries.iter().map(|(name, value)| (name, value))
}
}
fn bounded(text: &str) -> String {
text.chars().take(32).collect()
}
#[derive(Debug)]
#[non_exhaustive]
pub enum HeaderError {
EmptyName,
NameTooLong {
length: usize,
},
InvalidName {
name: String,
offset: usize,
},
ValueTooLong {
length: usize,
},
InvalidValue {
value: String,
offset: usize,
},
DuplicateHeader {
name: String,
},
TooManyHeaders {
maximum: usize,
},
}
impl fmt::Display for HeaderError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::EmptyName => formatter.write_str("a header name is empty"),
Self::NameTooLong { length } => write!(
formatter,
"header name of {length} bytes exceeds maximum {MAX_HEADER_NAME_BYTES}"
),
Self::InvalidName { name, offset } => write!(
formatter,
"header name {name:?} holds a byte outside the token set at offset {offset}"
),
Self::ValueTooLong { length } => write!(
formatter,
"header value of {length} bytes exceeds maximum {MAX_HEADER_VALUE_BYTES}"
),
Self::InvalidValue { value, offset } => write!(
formatter,
"header value {value:?} holds an unusable character at offset {offset}"
),
Self::DuplicateHeader { name } => {
write!(formatter, "header {name:?} appears more than once")
}
Self::TooManyHeaders { maximum } => {
write!(formatter, "a message carries more than {maximum} headers")
}
}
}
}
impl Error for HeaderError {}
#[cfg(test)]
mod tests {
use super::*;
use std::error::Error;
fn headers() -> Result<Headers, Box<dyn Error>> {
Ok(Headers::from_pairs([
(
HeaderName::new("Signify-Resource")?,
HeaderValue::new("EWJkQCFvKuyxZi582yJPb0wcwuW3VXmFNuvbQuBpgmIs")?,
),
(
HeaderName::new("Signify-Timestamp")?,
HeaderValue::new("2022-09-24T00:05:48.196795+00:00")?,
),
])?)
}
#[test]
fn names_compare_and_look_up_without_regard_to_case() -> Result<(), Box<dyn Error>> {
let headers = headers()?;
assert_eq!(
headers.get("SIGNIFY-RESOURCE"),
Some("EWJkQCFvKuyxZi582yJPb0wcwuW3VXmFNuvbQuBpgmIs")
);
assert!(headers.contains("signify-timestamp"));
assert!(!headers.contains("absent"));
assert_eq!(HeaderName::new("Content-Type")?, HeaderName::new("content-type")?);
assert_eq!(HeaderName::new("Content-Type")?.as_str(), "Content-Type");
assert_eq!(HeaderName::new("Content-Type")?.to_string(), "Content-Type");
Ok(())
}
#[test]
fn a_derived_component_is_not_a_header_name() {
for name in ["@method", "@path", "@signature-params", "a b", "a:b", "a\"b", ""] {
assert!(HeaderName::new(name).is_err(), "{name:?} was accepted");
}
}
#[test]
fn header_names_are_bounded() {
assert!(matches!(
HeaderName::new("a".repeat(MAX_HEADER_NAME_BYTES + 1)),
Err(HeaderError::NameTooLong { length }) if length == MAX_HEADER_NAME_BYTES + 1
));
assert!(matches!(HeaderName::new(""), Err(HeaderError::EmptyName)));
assert!(matches!(
HeaderName::new("a@b"),
Err(HeaderError::InvalidName { offset: 1, .. })
));
}
#[test]
fn values_are_trimmed_and_control_free() -> Result<(), Box<dyn Error>> {
assert_eq!(HeaderValue::new("\t padded \t")?.as_str(), "padded");
assert_eq!(HeaderValue::new("")?.as_str(), "");
assert_eq!(HeaderValue::new("a b")?.to_string(), "a b");
for value in ["a\nb", "a\rb", "a\u{0}b", "a\u{7f}b", "a\u{85}b"] {
assert!(
matches!(HeaderValue::new(value), Err(HeaderError::InvalidValue { .. })),
"{value:?} was accepted",
);
}
assert_eq!(HeaderValue::new("héllo")?.as_str(), "héllo");
assert!(matches!(
HeaderValue::new("世界"),
Err(HeaderError::InvalidValue { offset: 0, .. })
));
assert!(matches!(
HeaderValue::new("a".repeat(MAX_HEADER_VALUE_BYTES + 1)),
Err(HeaderError::ValueTooLong { length }) if length == MAX_HEADER_VALUE_BYTES + 1
));
assert_eq!(HeaderValue::from_str(" x ")?, HeaderValue::try_from("x")?);
Ok(())
}
#[test]
fn duplicate_names_are_refused() -> Result<(), Box<dyn Error>> {
let mut headers = headers()?;
assert!(matches!(
headers.insert(HeaderName::new("signify-resource")?, HeaderValue::new("other")?),
Err(HeaderError::DuplicateHeader { .. })
));
assert_eq!(headers.len(), 2);
assert!(!headers.is_empty());
assert!(Headers::new().is_empty());
Ok(())
}
#[test]
fn collections_are_bounded_and_iterable() -> Result<(), Box<dyn Error>> {
let mut headers = Headers::new();
for position in 0..MAX_HEADERS {
headers.insert(HeaderName::new(format!("x-{position}"))?, HeaderValue::new("1")?)?;
}
assert!(matches!(
headers.insert(HeaderName::new("x-extra")?, HeaderValue::new("1")?),
Err(HeaderError::TooManyHeaders { maximum }) if maximum == MAX_HEADERS
));
let headers = self::headers()?;
let names: Vec<&str> = headers.iter().map(|(name, _)| name.as_str()).collect();
assert_eq!(names, ["Signify-Resource", "Signify-Timestamp"]);
assert_eq!((&headers).into_iter().count(), 2);
Ok(())
}
#[test]
fn errors_carry_readable_text() {
for error in [
HeaderError::EmptyName,
HeaderError::NameTooLong { length: 9 },
HeaderError::InvalidName {
name: "a@b".to_owned(),
offset: 1,
},
HeaderError::ValueTooLong { length: 9 },
HeaderError::InvalidValue {
value: "a\nb".to_owned(),
offset: 1,
},
HeaderError::DuplicateHeader { name: "x".to_owned() },
HeaderError::TooManyHeaders { maximum: MAX_HEADERS },
] {
assert_ne!(error.to_string(), "");
assert!(error.source().is_none());
}
}
}