Module header

Expand description

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
AccessControlAllowCredentials: Access-Control-Allow-Credentials header, part of CORS
AccessControlAllowHeaders: Access-Control-Allow-Headers header, part of CORS
AccessControlAllowMethods: Access-Control-Allow-Methods header, part of CORS
AccessControlExposeHeaders: Access-Control-Expose-Headers 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
ContentDisposition: A Content-Disposition header, (re)defined in RFC6266
ContentEncoding: Content-Encoding header, defined in RFC7231
ContentLanguage: Content-Language header, defined in RFC7231
ContentLength: Content-Length header, defined in RFC7230
ContentRange: Content-Range header, defined in RFC7233
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
HeaderFormatterDeprecated: 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
Link: The Link header, defined in RFC5988
LinkValue: A single link-value of a Link header, based on: RFC5988
Location: Location header, defined in RFC7231
Origin: The Origin header.
Prefer: Prefer header, defined in RFC7240
PreferenceApplied: Preference-Applied header, defined in RFC7240
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.
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 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
MediaDesc: A Media Descriptors Enum based on: https://www.w3.org/TR/html401/types.html#h-6.13
Pragma: The Pragma header defined by HTTP/1.0.
Preference: Prefer contains a list of these preferences.
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
ReferrerPolicy: Referrer-Policy header, part of Referrer Policy
RelationType: A Link Relation Type Enum based on: RFC5988
Vary: Vary header, defined in RFC7231

Traits§

Header: A trait for any object that will represent a header field and value.
HeaderClone: Internal implementation detail.
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 from a float.
qitem: Convinience function to wrap a value in a QualityItem Sets q to the default 1.0

Module headerCopy item path