Module headers

Help

Expand description

typed http headers

rama 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

§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 rama_http::{headers::Header, HeaderName, HeaderValue};
use rama_http_types::{header, headers};

struct Dnt(bool);

impl Header for Dnt {
    fn name() -> &'static HeaderName {
         &header::DNT
    }

    fn decode<'i, I>(values: &mut I) -> Result<Self, headers::Error>
    where
        I: Iterator<Item = &'i HeaderValue>,
    {
        let value = values
            .next()
            .ok_or_else(headers::Error::invalid)?;

        if value == "0" {
            Ok(Dnt(false))
        } else if value == "1" {
            Ok(Dnt(true))
        } else {
            Err(headers::Error::invalid())
        }
    }

    fn encode<E>(&self, values: &mut E)
    where
        E: Extend<HeaderValue>,
    {
        let s = if self.0 {
            "1"
        } else {
            "0"
        };

        let value = HeaderValue::from_static(s);

        values.extend(std::iter::once(value));
    }
}

Modules§

authorization: Authorization header and types.
client_hints: Http (UA) Client Hints
util

Structs§

Accept: Accept 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
AccessControlAllowOrigin: The Access-Control-Allow-Origin response 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
Age: Age header, defined in RFC7234
Allow: Allow header, defined in RFC7231
Authorization: Authorization header, defined in RFC7235
CFConnectingIp: CF-Connecting-IP provides the client IP address connecting to Cloudflare to the origin web server.
CacheControl: Cache-Control header, defined in RFC7234 with extensions in RFC8246
ClientIp: Client-Ip is used by some proxy software to set the real client Ip Address (known to them).
Connection: Connection header, defined in RFC7230
ContentDisposition: A Content-Disposition header, (re)defined in RFC6266.
ContentEncoding: Content-Encoding header, defined in RFC7231
ContentLength: Content-Length header, defined in RFC7230
ContentLocation: Content-Location header, defined in RFC7231
ContentRange: Content-Range, described 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
Error: Errors trying to decode a header.
Expect: The Expect header.
Expires: Expires header, defined in RFC7234
Forwarded: Forwarding information stored as a chain.
Host: The Host header.
IfMatch: If-Match header, defined in RFC7232
IfModifiedSince: If-Modified-Since header, defined in RFC7232
IfNoneMatch: If-None-Match header, defined in RFC7232
IfRange: If-Range header, defined in RFC7233
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.
Pragma: The Pragma header defined by HTTP/1.0.
ProxyAuthorization: Proxy-Authorization header, defined in RFC7235
Quality: Represents a quality used in quality values.
QualityValue: Represents an item with a quality value as defined in RFC7231.
Range: Range header, defined in RFC7233
Referer: Referer header, defined in RFC7231
ReferrerPolicy: Referrer-Policy header, part of Referrer Policy
RetryAfter: The Retry-After header.
SecWebsocketAccept: The Sec-Websocket-Accept header.
SecWebsocketKey: The Sec-Websocket-Key header.
SecWebsocketVersion: The Sec-Websocket-Version header.
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
TrueClientIp: True-Client-IP provides the original client IP address to the origin web server (Cloudflare Enterprise).
Upgrade: Upgrade header, defined in RFC7230
UserAgent: User-Agent header, defined in RFC7231
Vary: Vary header, defined in RFC7231
Via: The Via general header is added by proxies, both forward and reverse.
XClientIp: X-Client-Ip is used by some proxy software to set the real client Ip Address (known to them).
XForwardedFor: The X-Forwarded-For (XFF) request header is a de-facto standard header for identifying the originating IP address of a client connecting to a web server through a proxy server.
XForwardedHost: The X-Forwarded-Host (XFH) header is a de-facto standard header for identifying the original host requested by the client in the Host HTTP request header.
XForwardedProto: The X-Forwarded-Proto (XFP) header is a de-facto standard header for identifying the protocol (HTTP or HTTPS) that a client used to connect to your proxy or load balancer.
XRealIp: X-Real-Ip is used by some proxy software to set the real client Ip Address (known to them).

Enums§

ClientHint

Traits§

ForwardHeader: A trait for types headers that is used by middleware which supports headers that can be converted into and from Forward data.
Header: A trait for any object that will represent a header field and value.
HeaderExt: An external trait adding helper methods to types which implement Header trait.
HeaderMapExt: An extension trait adding “typed” methods to http::HeaderMap.

Module headersCopy item path