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::HeaderValue
s
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
.