Module hyper::header [] [src]

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

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

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

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

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 from a float.

qitem

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