Module hyperx::header [−][src]
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::HeaderValues
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]
));TypedHeaders extension to http::HeaderMap
The TypedHeaders extension trait provides more
convenient encode/decode methods on HeaderMap generically for the
standard header types named in the http crate:
use http::header::HeaderMap;
use hyperx::header::{ContentEncoding, Encoding, TypedHeaders};
let mut hmap = http::HeaderMap::new();
hmap.encode(
&ContentEncoding(vec![Encoding::Identity]));
hmap.encode_append(
&ContentEncoding(vec![Encoding::Gzip, Encoding::Chunked]));
let ce: ContentEncoding = hmap.decode()?;
assert_eq!(
*ce,
vec![Encoding::Identity, Encoding::Gzip, Encoding::Chunked]
);Defining Custom Headers
Hyperx provides all 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.
header! { (XRequestGuid, "X-Request-Guid") => [String] }
fn main () {
let mut headers = http::HeaderMap::new();
headers.insert(
"x-request-guid",
XRequestGuid("a proper guid".to_owned()).to_string().parse().unwrap()
);
}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
Utility functions for Header implementations.
Macros
Create a custom header type.
Structs
Accept-Charset header, defined in
RFC7231
Accept-Encoding header, defined in
RFC7231
Accept-Language header, defined in
RFC7231
Accept-Ranges header, defined in
RFC7233
Access-Control-Allow-Credentials header, part of
CORS
Access-Control-Allow-Headers header, part of
CORS
Access-Control-Allow-Methods header, part of
CORS
Access-Control-Expose-Headers header, part of
CORS
Access-Control-Max-Age header, part of
CORS
Access-Control-Request-Headers header, part of
CORS
Access-Control-Request-Method header, part of
CORS
Authorization header, defined in RFC7235
Credential holder for Basic Authentication
Token holder for Bearer Authentication, most often seen with oauth
Cache-Control header, defined in RFC7234
Connection header, defined in
RFC7230
A Content-Disposition header, (re)defined in RFC6266.
Content-Encoding header, defined in
RFC7231
Content-Language header, defined in
RFC7231
Content-Length header, defined in
RFC7230
Content-Location header, defined in
RFC7231
Content-Range header, defined in
RFC7233
Content-Type header, defined in
RFC7231
Iterator for cookie.
A formatter used to serialize headers to an output stream.
Returned with the HeadersItems iterator.
A specialized map of typed headers.
An Iterator over the fields in a Headers map.
The Host header.
A timestamp with HTTP formatting and parsing
If-Modified-Since header, defined in
RFC7232
If-Unmodified-Since header, defined in
RFC7232
A language tag as described in RFC 5646.
Last-Event-ID header, defined in
RFC3864
Last-Modified header, defined in
RFC7232
The Origin header.
Preference-Applied header, defined in RFC7240
Protocols that appear in the Upgrade header field
Proxy-Authorization header, defined in RFC7235
Represents a quality used in quality values.
Represents an item with a quality value as defined in RFC7231.
A raw header value.
StrictTransportSecurity header, defined in RFC6797
Transfer-Encoding header, defined in
RFC7230
Iterator adaptor for HeaderValue
Enums
The Access-Control-Allow-Origin response header,
part of CORS
Each Range::Bytes header can contain one or more ByteRangeSpecs.
Each ByteRangeSpec defines a range of bytes to fetch
CacheControl contains a list of these directives.
A Mime charset.
Values that can be in the Connection header.
Content-Range, described in RFC7233
A parameter to the disposition type.
The implied disposition of the content of the HTTP body.
A value to represent an encoding used in Transfer-Encoding
or Accept-Encoding header.
The Expect header.
If-None-Match header, defined in
RFC7232
A Media Descriptors Enum based on: https://www.w3.org/TR/html401/types.html#h-6.13
The Pragma header defined by HTTP/1.0.
Prefer contains a list of these preferences.
A protocol name used to identify a specific protocol. Names are case-sensitive
except for the WebSocket value.
Referrer-Policy header, part of
Referrer Policy
A Link Relation Type Enum based on: RFC5988
The Retry-After header.
Traits
A trait for any object that will represent a header field and value.
Trait for raw bytes parsing access to header values (aka lines) for a single header name.
An Authorization scheme to be used in the header.
A trait for the “standard” headers that have an associated HeaderName
constant in the http crate.
Extension trait for decode (parsing) and encode (serialization) of
typed headers from/to a collection of headers such as http::HeaderMap.