[][src]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:

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

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

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

    fn parse_header(raw: &Raw) -> 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)
    }

    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

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

ContentLocation

Content-Location header, defined in RFC7231

ContentRange

Content-Range header, defined in RFC7233

ContentType

Content-Type header, defined in RFC7231

Cookie

Cookie header, defined in RFC6265

CookieIter

Iterator for cookie.

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

Formatter

A formatter used to serialize headers to an output stream.

From

From header, defined in RFC7231

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 timestamp with HTTP formatting and parsing

IfModifiedSince

If-Modified-Since header, defined in RFC7232

IfUnmodifiedSince

If-Unmodified-Since header, defined in RFC7232

LanguageTag

A language tag as described in BCP47.

LastEventId

Last-Event-ID header, defined in RFC3864

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

ProxyAuthorization

Proxy-Authorization header, defined in RFC7235

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

Referer header, defined in RFC7231

Server

Server header, defined in RFC7231

SetCookie

Set-Cookie header, defined RFC6265

StrictTransportSecurity

StrictTransportSecurity header, defined in RFC6797

Te

TE header, defined in RFC7230

TransferEncoding

Transfer-Encoding header, defined in RFC7230

Upgrade

Upgrade header, defined in RFC7230

UserAgent

User-Agent header, defined in RFC7231

Warning

Warning header, defined in RFC7234

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 specific 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

RetryAfter

The Retry-After header.

Vary

Vary header, defined in RFC7231

Traits

Header

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 or integer.

qitem

Convenience function to wrap a value in a QualityItem Sets q to the default 1.0