Module hyper::header

Headers container, and common header fields.

hyper has the opinion that Headers should be strongly-typed, because that's why we're using Rust in the first place. To set or get any header, an object must implement the Header trait from this module. Several common headers are already provided, such as Host, ContentType, UserAgent, and others.

Why Typed?

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

Defining Custom Headers

Hyper 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. Hyper includes a header! macro for defining many wrapper-style headers.

#[macro_use] extern crate hyper;
use hyper::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. But the header system actually involves 2 parts: parsing, and formatting. If you need to customize either part, you can do so.

Header and HeaderFormat

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 hyper::header::{Header, HeaderFormat};

#[derive(Debug, Clone, Copy)]
struct Dnt(bool);

impl Header for Dnt {
    fn header_name() -> &'static str {
        "DNT"
    }

    fn parse_header(raw: &[Vec<u8>]) -> hyper::Result<Dnt> {
        if raw.len() == 1 {
            let line = &raw[0];
            if line.len() == 1 {
                let byte = line[0];
                match byte {
                    b'0' => return Ok(Dnt(true)),
                    b'1' => return Ok(Dnt(false)),
                    _ => ()
                }
            }
        }
        Err(hyper::Error::Header)
    }
}

impl HeaderFormat for Dnt {
    fn fmt_header(&self, f: &mut fmt::Formatter) -> fmt::Result {
        if self.0 {
            f.write_str("1")
        } else {
            f.write_str("0")
        }
    }
}

Modules

parsing

Utility functions for Header implementations.

Structs

Accept	Accept header, defined in RFC7231
AcceptCharset	Accept-Charset header, defined in RFC7231
AcceptEncoding	Accept-Encoding header, defined in RFC7231
AcceptLanguage	Accept-Language header, defined in RFC7231
AcceptRanges	Accept-Ranges header, defined in RFC7233
AccessControlAllowHeaders	Access-Control-Allow-Headers header, part of CORS
AccessControlAllowMethods	Access-Control-Allow-Methods header, part of CORS
AccessControlMaxAge	Access-Control-Max-Age header, part of CORS
AccessControlRequestHeaders	Access-Control-Request-Headers header, part of CORS
AccessControlRequestMethod	Access-Control-Request-Method header, part of CORS
Allow	Allow header, defined in RFC7231
Authorization	Authorization header, defined in RFC7235
Basic	Credential holder for Basic Authentication
Bearer	Token holder for Bearer Authentication, most often seen with oauth
CacheControl	Cache-Control header, defined in RFC7234
Connection	Connection header, defined in RFC7230
ContentEncoding	Content-Encoding header, defined in RFC7231
ContentLanguage	Content-Language header, defined in RFC7231
ContentLength	Content-Length header, defined in RFC7230
ContentType	Content-Type header, defined in RFC7231
Cookie	Cookie header, defined in RFC6265
Date	Date header, defined in RFC7231
ETag	ETag header, defined in RFC7232
EntityTag	An entity tag, defined in RFC7232
Expires	Expires header, defined in RFC7234
From	From header, defined in RFC7231
HeaderFormatter	A wrapper around any Header with a Display impl that calls fmt_header.
HeaderView	Returned with the HeadersItems iterator.
Headers	A map of header fields on requests and responses.
HeadersItems	An Iterator over the fields in a Headers map.
Host	The Host header.
HttpDate	A time::Time with HTTP formatting and parsing
IfModifiedSince	If-Modified-Since header, defined in RFC7232
IfUnmodifiedSince	If-Unmodified-Since header, defined in RFC7232
LastModified	Last-Modified header, defined in RFC7232
Location	Location header, defined in RFC7231
Protocol	Protocols that appear in the Upgrade header field
Quality	Represents a quality used in quality values.
QualityItem	Represents an item with a quality value as defined in RFC7231.
Referer	Referer header, defined in RFC7231
Server	Server header, defined in RFC7231
SetCookie	Set-Cookie header, defined RFC6265
StrictTransportSecurity	StrictTransportSecurity header, defined in RFC6797
TransferEncoding	Transfer-Encoding header, defined in RFC7230
Upgrade	Upgrade header, defined in RFC7230
UserAgent	User-Agent header, defined in RFC7231

Enums

AccessControlAllowOrigin	The Access-Control-Allow-Origin response header, part of CORS
ByteRangeSpec	Each Range::Bytes header can contain one or more ByteRangeSpecs. Each ByteRangeSpec defines a range of bytes to fetch
CacheDirective	CacheControl contains a list of these directives.
Charset	A Mime charset.
ConnectionOption	Values that can be in the Connection header.
Encoding	A value to represent an encoding used in Transfer-Encoding or Accept-Encoding header.
Expect	The Expect header.
IfMatch	If-Match header, defined in RFC7232
IfNoneMatch	If-None-Match header, defined in RFC7232
IfRange	If-Range header, defined in RFC7233
Pragma	The Pragma header defined by HTTP/1.0.
ProtocolName	A protocol name used to identify a spefic protocol. Names are case-sensitive except for the WebSocket value.
Range	Range header, defined in RFC7233
RangeUnit	Range Units, described in RFC7233
Vary	Vary header, defined in RFC7231

Traits

Header	A trait for any object that will represent a header field and value.
HeaderFormat	A trait for any object that will represent a header field and value.
Scheme	An Authorization scheme to be used in the header.

Functions

q	Convenience function to create a Quality fromt a float.
qitem	Convinience function to wrap a value in a QualityItem Sets q to the default 1.0