Expand description
Headers container, and common header fields.
Why Typed?
Hyper has had the opinion that:
Headers should be strongly-typed, because that’s why we’re using Rust in the first place. Or, why not stringly-typed? Types give the following advantages:
- More difficult to typo, since typos in types should be caught by the compiler
- Parsing to a proper type by default
However, it seems that for many applications, it is sufficient to use
http::header::HeaderMap
(byte values) and parse only the headers that
are of interest.
Parsing http::header::HeaderValue
s
With the default compat feature enabled, HeaderValue
(s) implement the
RawLike
trait which allows for parsing with less copying than going
through HeaderValue::to_str
or the Raw
type. See example usage below:
use http::header::{HeaderMap, CONTENT_ENCODING};
use hyperx::header::{ContentEncoding, Encoding, Header};
// Given a HeaderMap with 2 Content-Encoding headers and 3 delimited values
let mut hmap = HeaderMap::new();
hmap.insert(CONTENT_ENCODING, "chunked, gzip".parse()?);
hmap.append(CONTENT_ENCODING, "identity".parse()?);
// Parse the first header value
let first = hmap.get(CONTENT_ENCODING).unwrap();
let ce = ContentEncoding::parse_header(&first)?;
assert_eq!(ce, ContentEncoding(vec![Encoding::Chunked, Encoding::Gzip]));
// Parse all header values to a single list
let all = hmap.get_all(CONTENT_ENCODING);
let ce = ContentEncoding::parse_header(&all)?;
assert_eq!(ce, ContentEncoding(
vec![Encoding::Chunked, Encoding::Gzip, Encoding::Identity]
));
Defining Custom Headers
Hyperx provides many of the most commonly used headers in HTTP. If you
need to define a custom header, it’s easy to do while still taking
advantage of the type system. Hyperx includes a header!
macro for
defining many wrapper-style headers.
use hyperx::header::Headers;
header! { (XRequestGuid, "X-Request-Guid") => [String] }
fn main () {
let mut headers = Headers::new();
headers.set(XRequestGuid("a proper guid".to_owned()))
}
This works well for simple “string” headers. If you need more control, you can implement the trait directly.
Implementing the Header
trait
Consider a Do Not Track header. It can be true or false, but it represents
that via the numerals 1
and 0
.
use std::fmt;
use hyperx::header::{self, Header, RawLike};
#[derive(Debug, Clone, Copy)]
struct Dnt(bool);
impl Header for Dnt {
fn header_name() -> &'static str {
"DNT"
}
fn parse_header<'a, T>(raw: &'a T) -> hyperx::Result<Dnt>
where T: RawLike<'a>
{
if let Some(line) = raw.one() {
if line.len() == 1 {
let byte = line[0];
match byte {
b'0' => return Ok(Dnt(true)),
b'1' => return Ok(Dnt(false)),
_ => ()
}
}
}
Err(hyperx::Error::Header)
}
fn fmt_header(&self, f: &mut header::Formatter) -> fmt::Result {
let value = if self.0 {
"1"
} else {
"0"
};
f.fmt_line(&value)
}
}
Modules
Macros
Structs
Accept-Charset
header, defined in
RFC7231Accept-Encoding
header, defined in
RFC7231Accept-Language
header, defined in
RFC7231Accept-Ranges
header, defined in
RFC7233Access-Control-Allow-Credentials
header, part of
CORSAccess-Control-Allow-Headers
header, part of
CORSAccess-Control-Allow-Methods
header, part of
CORSAccess-Control-Expose-Headers
header, part of
CORSAccess-Control-Max-Age
header, part of
CORSAccess-Control-Request-Headers
header, part of
CORSAccess-Control-Request-Method
header, part of
CORSAuthorization
header, defined in RFC7235Cache-Control
header, defined in RFC7234Connection
header, defined in
RFC7230Content-Disposition
header, (re)defined in RFC6266.Content-Encoding
header, defined in
RFC7231Content-Language
header, defined in
RFC7231Content-Length
header, defined in
RFC7230Content-Location
header, defined in
RFC7231Content-Range
header, defined in
RFC7233Content-Type
header, defined in
RFC7231HeadersItems
iterator.Iterator
over the fields in a Headers
map.Host
header.If-Modified-Since
header, defined in
RFC7232If-Unmodified-Since
header, defined in
RFC7232Last-Event-ID
header, defined in
RFC3864Last-Modified
header, defined in
RFC7232Origin
header.Preference-Applied
header, defined in RFC7240Upgrade
header fieldProxy-Authorization
header, defined in RFC7235StrictTransportSecurity
header, defined in RFC6797Transfer-Encoding
header, defined in
RFC7230Enums
Access-Control-Allow-Origin
response header,
part of CORSRange::Bytes
header can contain one or more ByteRangeSpecs
.
Each ByteRangeSpec
defines a range of bytes to fetchCacheControl
contains a list of these directives.Connection
header.Transfer-Encoding
or Accept-Encoding
header.Expect
header.If-None-Match
header, defined in
RFC7232Pragma
header defined by HTTP/1.0.WebSocket
value.Referrer-Policy
header, part of
Referrer PolicyRetry-After
header.