Module Http.Headers


A datatype to handle the quirky HTTP headers.

Header names

module Name : sig ... end

Header names.

val name : string -> Name.t

name n is Name.v.


type t

The type for HTTP headers. Maps header names to string values such that for:

  • Single valued headers, the string is the value.
  • Multi-valued headers, the string is the values separated by commas ','. Use Headers.values_of_string on the string.
  • The set_cookie header, must be treated specially since it can be repeated but does not follow the syntax of multi-valued headers. The values are stored in the string separated by '\x00' values. Use Headers.add_set_cookie and Headers.values_of_set_cookie_value to handle the field. Encoders must write the cookies in separate set_cookie headers.
val empty : t

empty has no header definition.

val def : Name.t -> string -> t -> t

def n v hs is hs with n defined to v.

val def_if_some : Name.t -> string option -> t -> t

def_some n o hs is hs with n defined to v if o is Some v and hs otherwise.

val def_if_undef : Name.t -> string -> t -> t

def_if_undef n v hs is hs with n defined to v if n is not defined in hs.

val undef : Name.t -> t -> t

undef n hs is hs with n undefined.

val add_value : Name.t -> string -> t -> t

add_value n v hs appends v to the multi-valued header n in hs.

add_set_cookie c hs adds a set_cookie header with value c. This appends to set_cookie, see t.

val override : t -> by:t -> t

override hs ~by are the headers of both hs and by with those of by taking over.

val pp : Stdlib.Format.formatter -> t -> unit

pp ppf hs prints an unspecified representation of hs on ppf.


val find : ?lowervalue:bool -> Name.t -> t -> string option

find n hs is the value of n in hs (if any). If lowervalue is true (defaults to false) the US-ASCII uppercase letter are mapped on lowercase.

If n is a multi-valued header use values_of_string on the result. If n is set_cookie you must use values_of_set_cookie_value.

val get : ?lowervalue:bool -> Name.t -> t -> string

get n hs is like find but raises Invalid_argument if n is not defined in hs.

val fold : (Name.t -> string -> 'a -> 'a) -> t -> 'a -> 'a

fold f m acc folds f over the bindings of hs starting with acc.

Header specific

val request_body_length : t -> ([ `Length of int | `Chunked ], string) Stdlib.result

request_body_length hs determines the message body length of a request (the rules for responses is a bit different) as per HTTP/1.1 specification, by looking at the content_type and transfer_encoding in hs.

val get_host : Scheme.t -> t -> (string * int, string) Stdlib.result

get_host scheme r decodes the host header into a hostname and a port number. If no port number is found in the header one is derived from scheme with Scheme.tcp_port. Errors if the header is missing or on decoding errors.

val for_connector : t -> Body.t -> t

for_connector hs body are the headers of hs prepared for output a connector that will write a request or response with body body. It performs the logic described in the service responses and client requests conventions.

Header values

values_of_set_cookie_value v decodes v as stored in by add_set_cookie in the t type to a list of cookies.

val values_of_string : ?sep:char -> string -> string list

values_of_string s splits the string s at ',' (or sep if specified) characters and trims the resulting strings from optional whitespace, and lowercases the result if lowercase is true.

Note that by definition the result is never the empty list, the function returns [""] on "".

val values_to_string : ?sep:char -> string list -> string

values_to_string vs is String.concat "," vs but raise Invalid_argument if vs is []. TODO why ?

val value_is_token : string -> bool

value_is_token s is true iff s in an HTTP a token.


val is_empty : t -> bool

is_empty hs is true iff hs is has no definition.

val mem : Name.t -> t -> bool

mem n hs is true iff n is defined in hs.

Standard header names

val accept : Name.t
val accept_charset : Name.t
val accept_encoding : Name.t
val accept_language : Name.t
val accept_ranges : Name.t
val age : Name.t
val allow : Name.t
val authorization : Name.t
val cache_control : Name.t
val connection : Name.t
val content_encoding : Name.t
val content_language : Name.t
val content_length : Name.t
val content_location : Name.t
val content_range : Name.t
val content_type : Name.t
val date : Name.t
val etag : Name.t
val expect : Name.t
val expires : Name.t
val from : Name.t
val host : Name.t
val if_match : Name.t
val if_modified_since : Name.t
val if_none_match : Name.t
val if_range : Name.t
val if_unmodified_since : Name.t
val last_modified : Name.t
val location : Name.t
val max_forwards : Name.t
val pragma : Name.t
val proxy_authenticate : Name.t
val proxy_authorization : Name.t
val range : Name.t
val referer : Name.t
val retry_after : Name.t
val server : Name.t
val te : Name.t
val trailer : Name.t
val transfer_encoding : Name.t
val upgrade : Name.t
val user_agent : Name.t
val vary : Name.t
val via : Name.t
val warning : Name.t
val www_authenticate : Name.t