Headers (webs.Webs.Http.Headers)

Header names

module Name : sig ... end

Header names.

val name : string -> Name.t

name n is Name.v.

Headers

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.

val add_set_cookie : string -> t -> t

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 encode_http11 : t -> string

encode_http11 hs is hs as sequence of crlf terminated HTTP/1.1 headers. This correctly handles the Headers.set_cookie header.

Lookups

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 find' : ?lowervalue:bool -> Name.t -> t -> (string, string) Stdlib.result

find' is like find. Except if the header is absent it returns an error message of the form "%s: No such header".

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 decode_host : Scheme.t -> t -> (string * int, string) Stdlib.result

decode_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

val values_of_set_cookie_value : string -> string list

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 decode_http11_header : string -> (Name.t * string, string) Stdlib.result

decode_http11_header s decodes a header from s.

val pp_header : Stdlib.Format.formatter -> (Name.t * string) -> unit

pp_header formats a header for inspection with HTTP/1.1 syntax.