[−][src]Module hyperx::header
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
parsing | Utility functions for Header implementations. |
Structs
Accept |
|
AcceptCharset |
|
AcceptEncoding |
|
AcceptLanguage |
|
AcceptRanges |
|
AccessControlAllowCredentials |
|
AccessControlAllowHeaders |
|
AccessControlAllowMethods |
|
AccessControlExposeHeaders |
|
AccessControlMaxAge |
|
AccessControlRequestHeaders |
|
AccessControlRequestMethod |
|
Allow |
|
Authorization |
|
Basic | Credential holder for Basic Authentication |
Bearer | Token holder for Bearer Authentication, most often seen with oauth |
CacheControl |
|
Connection |
|
ContentDisposition | A |
ContentEncoding |
|
ContentLanguage |
|
ContentLength |
|
ContentLocation |
|
ContentRange |
|
ContentType |
|
Cookie |
|
CookieIter | Iterator for cookie. |
Date |
|
ETag |
|
EntityTag | An entity tag, defined in RFC7232 |
Expires |
|
Formatter | A formatter used to serialize headers to an output stream. |
From |
|
HeaderView | Returned with the |
Headers | A specialized map of typed headers. |
HeadersItems | An |
Host | The |
HttpDate | A timestamp with HTTP formatting and parsing |
IfModifiedSince |
|
IfUnmodifiedSince |
|
LanguageTag | A language tag as described in BCP47. |
LastEventId |
|
LastModified |
|
Link | The |
LinkValue | A single |
Location |
|
Origin | The |
Prefer |
|
PreferenceApplied |
|
Protocol | Protocols that appear in the |
ProxyAuthorization |
|
Quality | Represents a quality used in quality values. |
QualityItem | Represents an item with a quality value as defined in RFC7231. |
Raw | A raw header value. |
Referer |
|
Server |
|
SetCookie |
|
StrictTransportSecurity |
|
Te |
|
TransferEncoding |
|
Upgrade |
|
UserAgent |
|
ValueMapIter | Iterator adaptor for HeaderValue |
Warning |
|
Enums
AccessControlAllowOrigin | The |
ByteRangeSpec | Each |
CacheDirective |
|
Charset | A Mime charset. |
ConnectionOption | Values that can be in the |
ContentRangeSpec | Content-Range, described in RFC7233 |
DispositionParam | A parameter to the disposition type. |
DispositionType | The implied disposition of the content of the HTTP body. |
Encoding | A value to represent an encoding used in |
Expect | The |
IfMatch |
|
IfNoneMatch |
|
IfRange |
|
MediaDesc | A Media Descriptors Enum based on: https://www.w3.org/TR/html401/types.html#h-6.13 |
Pragma | The |
Preference | Prefer contains a list of these preferences. |
ProtocolName | A protocol name used to identify a specific protocol. Names are case-sensitive
except for the |
Range |
|
RangeUnit | Range Units, described in RFC7233 |
ReferrerPolicy |
|
RelationType | A Link Relation Type Enum based on: RFC5988 |
RetryAfter | The |
Vary |
|
Traits
Header | A trait for any object that will represent a header field and value. |
RawLike | Trait for raw bytes parsing access to header values (aka lines) for a single header name. |
Scheme | An Authorization scheme to be used in the header. |
StandardHeader | A trait for the "standard" headers that have an associated |
TypedHeaders | Extension trait for |
Functions
q | Convenience function to create a |
qitem | Convenience function to wrap a value in a |