/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at
http://mozilla.org/MPL/2.0/. */
pub use name::{HeaderName, InvalidHeaderName};
use std::collections::HashMap;
use std::iter::FromIterator;
use std::str::FromStr;
mod name;
/// A single header. Headers have a name (case insensitive) and a value. The
/// character set for header and values are both restrictive.
/// - Names must only contain a-zA-Z0-9 and and ('!' | '#' | '$' | '%' | '&' |
/// '\'' | '*' | '+' | '-' | '.' | '^' | '_' | '`' | '|' | '~') characters
/// (the field-name token production defined at
///
https://tools.ietf.org/html/rfc7230#section-3.2).
/// For request headers, we expect these to all be specified statically,
/// and so we panic if you provide an invalid one. (For response headers, we
/// ignore headers with invalid names, but emit a warning).
///
/// Header names are case insensitive, and we have several pre-defined ones in
/// the [`header_names`] module.
///
/// - Values may only contain printable ascii characters, and may not contain
/// \r or \n. Strictly speaking, HTTP is more flexible for header values,
/// however we don't need to support binary header values, and so we do not.
///
/// Note that typically you should not interact with this directly, and instead
/// use the methods on [`Request`] or [`Headers`] to manipulate these.
#[derive(Clone, Debug, PartialEq, PartialOrd, Hash, Eq, Ord)]
pub struct Header {
pub(crate) name: HeaderName,
pub(crate) value: String,
}
// Trim `s` without copying if it can be avoided.
fn trim_string<S: AsRef<str> + Into<String>>(s: S) -> String {
let sr = s.as_ref();
let trimmed = sr.trim();
if sr.len() != trimmed.len() {
trimmed.into()
} else {
s.into()
}
}
fn is_valid_header_value(value: &str) -> bool {
value.bytes().all(|b| (32..127).contains(&b) || b == b'\t')
}
impl Header {
pub fn new<Name, Value>(name: Name, value: Value) -> Result<Self, crate::Error>
where
Name: Into<HeaderName>,
Value: AsRef<str> + Into<String>,
{
let name = name.into();
let value = trim_string(value);
if !is_valid_header_value(&value) {
return Err(crate::Error::RequestHeaderError(name));
}
Ok(Self { name, value })
}
pub fn new_unchecked<Value>(name: HeaderName, value: Value) -> Self
where
Value: AsRef<str> + Into<String>,
{
Self {
name,
value: value.into(),
}
}
#[inline]
pub fn name(&self) -> &HeaderName {
&self.name
}
#[inline]
pub fn value(&self) -> &str {
&self.value
}
#[inline]
fn set_value<V: AsRef<str>>(&mut self, s: V) -> Result<(), crate::Error> {
let value = s.as_ref();
if !is_valid_header_value(value) {
Err(crate::Error::RequestHeaderError(self.name.clone()))
} else {
self.value.clear();
self.value.push_str(s.as_ref().trim());
Ok(())
}
}
}
impl std::fmt::Display for Header {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}: {}", self.name, self.value)
}
}
/// A list of headers.
#[derive(Clone, Debug, PartialEq, Eq, Default)]
pub struct Headers {
headers: Vec<Header>,
}
impl Headers {
/// Initialize an empty list of headers.
#[inline]
pub fn new() -> Self {
Default::default()
}
/// Initialize an empty list of headers backed by a vector with the provided
/// capacity.
pub fn with_capacity(c: usize) -> Self {
Self {
headers: Vec::with_capacity(c),
}
}
/// Convert this list of headers to a Vec<Header>
#[inline]
pub fn into_vec(self) -> Vec<Header> {
self.headers
}
/// Returns the number of headers.
#[inline]
pub fn len(&self) -> usize {
self.headers.len()
}
/// Returns true if `len()` is zero.
#[inline]
pub fn is_empty(&self) -> bool {
self.headers.is_empty()
}
/// Clear this set of headers.
#[inline]
pub fn clear(&mut self) {
self.headers.clear();
}
/// Insert or update a new header.
///
/// This returns an error if you attempt to specify a header with an
/// invalid value (values must be printable ASCII and may not contain
/// \r or \n)
///
/// ## Example
/// ```
/// # use viaduct::Headers;
/// # fn main() -> Result<(), viaduct::Error> {
/// let mut h = Headers::new();
/// h.insert("My-Cool-Header", "example")?;
/// assert_eq!(h.get("My-Cool-Header"), Some("example"));
///
/// // Note: names are sensitive
/// assert_eq!(h.get("my-cool-header"), Some("example"));
///
/// // Also note, constants for headers are in `viaduct::header_names`, and
/// // you can chain the result of this function.
/// h.insert(viaduct::header_names::CONTENT_TYPE, "something...")?
/// .insert("Something-Else", "etc")?;
/// # Ok(())
/// # }
/// ```
pub fn insert<N, V>(&mut self, name: N, value: V) -> Result<&mut Self, crate::Error>
where
N: Into<HeaderName> + PartialEq<HeaderName>,
V: Into<String> + AsRef<str>,
{
if let Some(entry) = self.headers.iter_mut().find(|h| name == h.name) {
entry.set_value(value)?;
} else {
self.headers.push(Header::new(name, value)?);
}
Ok(self)
}
/// Insert the provided header unless a header is already specified.
/// Mostly used internally, e.g. to set "Content-Type: application/json"
/// in `Request::json()` unless it has been set specifically.
pub fn insert_if_missing<N, V>(&mut self, name: N, value: V) -> Result<&mut Self, crate::Error>
where
N: Into<HeaderName> + PartialEq<HeaderName>,
V: Into<String> + AsRef<str>,
{
if !self.headers.iter_mut().any(|h| name == h.name) {
self.headers.push(Header::new(name, value)?);
}
Ok(self)
}
/// Insert or update a header directly. Typically you will want to use
/// `insert` over this, as it performs less work if the header needs
/// updating instead of insertion.
pub fn insert_header(&mut self, new: Header) -> &mut Self {
if let Some(entry) = self.headers.iter_mut().find(|h| h.name == new.name) {
entry.value = new.value;
} else {
self.headers.push(new);
}
self
}
/// Add all the headers in the provided iterator to this list of headers.
pub fn extend<I>(&mut self, iter: I) -> &mut Self
where
I: IntoIterator<Item = Header>,
{
let it = iter.into_iter();
self.headers.reserve(it.size_hint().0);
for h in it {
self.insert_header(h);
}
self
}
/// Add all the headers in the provided iterator, unless any of them are Err.
pub fn try_extend<I, E>(&mut self, iter: I) -> Result<&mut Self, E>
where
I: IntoIterator<Item = Result<Header, E>>,
{
// Not the most efficient but avoids leaving us in an unspecified state
// if one returns Err.
self.extend(iter.into_iter().collect::<Result<Vec<_>, E>>()?);
Ok(self)
}
/// Get the header object with the requested name. Usually, you will
/// want to use `get()` or `get_as::<T>()` instead.
pub fn get_header<S>(&self, name: S) -> Option<&Header>
where
S: PartialEq<HeaderName>,
{
self.headers.iter().find(|h| name == h.name)
}
/// Get the value of the header with the provided name.
///
/// See also `get_as`.
///
/// ## Example
/// ```
/// # use viaduct::{Headers, header_names::CONTENT_TYPE};
/// # fn main() -> Result<(), viaduct::Error> {
/// let mut h = Headers::new();
/// h.insert(CONTENT_TYPE, "application/json")?;
/// assert_eq!(h.get(CONTENT_TYPE), Some("application/json"));
/// assert_eq!(h.get("Something-Else"), None);
/// # Ok(())
/// # }
/// ```
pub fn get<S>(&self, name: S) -> Option<&str>
where
S: PartialEq<HeaderName>,
{
self.get_header(name).map(|h| h.value.as_str())
}
/// Get the value of the header with the provided name, and
/// attempt to parse it using [`std::str::FromStr`].
///
/// - If the header is missing, it returns None.
/// - If the header is present but parsing failed, returns
/// `Some(Err(<error returned by parsing>))`.
/// - Otherwise, returns `Some(Ok(result))`.
///
/// Note that if `Option<Result<T, E>>` is inconvenient for you,
/// and you wish this returned `Result<Option<T>, E>`, you may use
/// the built-in `transpose()` method to convert between them.
///
/// ```
/// # use viaduct::Headers;
/// # fn main() -> Result<(), viaduct::Error> {
/// let mut h = Headers::new();
/// h.insert("Example", "1234")?.insert("Illegal", "abcd")?;
/// let v: Option<Result<i64, _>> = h.get_as("Example");
/// assert_eq!(v, Some(Ok(1234)));
/// assert_eq!(h.get_as::<i64, _>("Example"), Some(Ok(1234)));
/// assert_eq!(h.get_as::<i64, _>("Illegal"), Some("abcd".parse::<i64>()));
/// assert_eq!(h.get_as::<i64, _>("Something-Else"), None);
/// # Ok(())
/// # }
/// ```
pub fn get_as<T, S>(&self, name: S) -> Option<Result<T, <T as FromStr>::Err>>
where
T: FromStr,
S: PartialEq<HeaderName>,
{
self.get(name).map(str::parse)
}
/// Get the value of the header with the provided name, and
/// attempt to parse it using [`std::str::FromStr`].
///
/// This is a variant of `get_as` that returns None on error,
/// intended to be used for cases where missing and invalid
/// headers should be treated the same. (With `get_as` this
/// requires `h.get_as(...).and_then(|r| r.ok())`, which is
/// somewhat opaque.
pub fn try_get<T, S>(&self, name: S) -> Option<T>
where
T: FromStr,
S: PartialEq<HeaderName>,
{
self.get(name).and_then(|val| val.parse::<T>().ok())
}
/// Get an iterator over the headers in no particular order.
///
/// Note that we also implement IntoIterator.
pub fn iter(&self) -> <&Headers as IntoIterator>::IntoIter {
self.into_iter()
}
}
impl std::iter::IntoIterator for Headers {
type IntoIter = <Vec<Header> as IntoIterator>::IntoIter;
type Item = Header;
fn into_iter(self) -> Self::IntoIter {
self.headers.into_iter()
}
}
impl<'a> std::iter::IntoIterator for &'a Headers {
type IntoIter = <&'a [Header] as IntoIterator>::IntoIter;
type Item = &'a Header;
fn into_iter(self) -> Self::IntoIter {
self.headers[..].iter()
}
}
impl FromIterator<Header> for Headers {
fn from_iter<T>(iter: T) -> Self
where
T: IntoIterator<Item = Header>,
{
let mut v = iter.into_iter().collect::<Vec<Header>>();
v.sort_by(|a, b| a.name.cmp(&b.name));
v.reverse();
v.dedup_by(|a, b| a.name == b.name);
Headers { headers: v }
}
}
#[allow(clippy::implicit_hasher)] //
https://github.com/rust-lang/rust-clippy/issues/3899
impl From<Headers> for HashMap<String, String> {
fn from(headers: Headers) -> HashMap<String, String> {
headers
.into_iter()
.map(|h| (String::from(h.name), h.value))
.collect()
}
}
pub mod consts {
use super::name::HeaderName;
macro_rules! def_header_consts {
($(($NAME:ident, $string:literal)),* $(,)?) => {
$(pub const $NAME: HeaderName = HeaderName(std::borrow::Cow::Borrowed($string));)*
};
}
macro_rules! headers {
($(($NAME:ident, $string:literal)),* $(,)?) => {
def_header_consts!($(($NAME, $string)),*);
// Unused except for tests.
const _ALL: &[&str] = &[$($string),*];
};
}
// Predefined header names, for convenience.
// Feel free to add to these.
headers!(
(ACCEPT_ENCODING, "accept-encoding"),
(ACCEPT, "accept"),
(AUTHORIZATION, "authorization"),
(CONTENT_TYPE, "content-type"),
(ETAG, "etag"),
(IF_NONE_MATCH, "if-none-match"),
(USER_AGENT, "user-agent"),
// non-standard, but it's convenient to have these.
(RETRY_AFTER, "retry-after"),
(X_IF_UNMODIFIED_SINCE, "x-if-unmodified-since"),
(X_KEYID, "x-keyid"),
(X_LAST_MODIFIED, "x-last-modified"),
(X_TIMESTAMP, "x-timestamp"),
(X_WEAVE_NEXT_OFFSET, "x-weave-next-offset"),
(X_WEAVE_RECORDS, "x-weave-records"),
(X_WEAVE_TIMESTAMP, "x-weave-timestamp"),
(X_WEAVE_BACKOFF, "x-weave-backoff"),
);
#[test]
fn test_predefined() {
for &name in _ALL {
assert!(
HeaderName::new(name).is_ok(),
"Invalid header name in predefined header constants: {}",
name
);
assert_eq!(
name.to_ascii_lowercase(),
name,
"Non-lowercase name in predefined header constants: {}",
name
);
}
}
}
