Module mco_http::header

source ·
Expand description

Headers container, and common header fields.

mco_http 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 mco_http;
use mco_http::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 mco_http::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>]) -> mco_http::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(mco_http::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.

Macros

Structs

Enums

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