Module hyper::header

source ·
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

Utility functions for Header implementations.

Macros

Structs

Accept header, defined in RFC7231
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
Allow header, defined in RFC7231
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-Range header, defined in RFC7233
Content-Type header, defined in RFC7231
Cookie header, defined in RFC6265
Date header, defined in RFC7231
ETag header, defined in RFC7232
An entity tag, defined in RFC7232
Expires header, defined in RFC7234
From header, defined in RFC7231
HeaderFormatterDeprecated
A wrapper around any Header with a Display impl that calls fmt_header.
Returned with the HeadersItems iterator.
A map of header fields on requests and responses.
An Iterator over the fields in a Headers map.
The Host header.
A time::Time with HTTP formatting and parsing
If-Modified-Since header, defined in RFC7232
If-Unmodified-Since header, defined in RFC7232
Last-Modified header, defined in RFC7232
The Link header, defined in RFC5988
A single link-value of a Link header, based on: RFC5988
Location header, defined in RFC7231
The Origin header.
Prefer header, defined in RFC7240
Preference-Applied header, defined in RFC7240
Protocols that appear in the Upgrade header field
Represents a quality used in quality values.
Represents an item with a quality value as defined in RFC7231.
Referer header, defined in RFC7231
Server header, defined in RFC7231
Set-Cookie header, defined RFC6265
StrictTransportSecurity header, defined in RFC6797
Transfer-Encoding header, defined in RFC7230
Upgrade header, defined in RFC7230
User-Agent header, defined in RFC7231

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-Match header, defined in RFC7232
If-None-Match header, defined in RFC7232
If-Range header, defined in RFC7233
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 spefic protocol. Names are case-sensitive except for the WebSocket value.
Range header, defined in RFC7233
Range Units, described in RFC7233
Referrer-Policy header, part of Referrer Policy
A Link Relation Type Enum based on: RFC5988
Vary header, defined in RFC7231

Traits

A trait for any object that will represent a header field and value.
Internal implementation detail.
A trait for any object that will represent a header field and value.
An Authorization scheme to be used in the header.

Functions

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