Headers (webs.Webs.Http.Headers)

Header names

module Name : sig ... end

Header names.

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.append_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 define : Name.t -> string -> t -> t

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

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

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

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

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

val undefine : Name.t -> t -> t

undefine n hs is hs with n undefined.

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

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

val append_set_cookie : string -> t -> t

append_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.

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 append_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 value_trim_ows : string -> string

value_trim_ows trims starting and ending optional whitespace (OWS).

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

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

Predicates

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

accept

val accept_charset : Name.t

accept-charset

val accept_encoding : Name.t

accept-encoding

val accept_language : Name.t

accept-language

val accept_ranges : Name.t

accept-ranges

val age : Name.t

age

val allow : Name.t

allow

val authorization : Name.t

authorization

val cache_control : Name.t

cache-control

val connection : Name.t

connection

val content_disposition : Name.t

content-disposition

val content_encoding : Name.t

content-encoding

val content_language : Name.t

content-language

val content_length : Name.t

content-length

val content_location : Name.t

content-location

val content_range : Name.t

content-range

val content_type : Name.t

content-type

val cookie : Name.t

cookie

val date : Name.t

date

val etag : Name.t

etag

val expect : Name.t

expect

val expires : Name.t

expires

val from : Name.t

from

val host : Name.t

host

val if_match : Name.t

if-match

val if_modified_since : Name.t

if-modified-since

val if_none_match : Name.t

if-none-match

val if_range : Name.t

if-range

val if_unmodified_since : Name.t

if-unmodified-since

val last_modified : Name.t

last-modified

val location : Name.t

location

val max_forwards : Name.t

max-forwards

val origin : Name.t

origin.

val pragma : Name.t

pragma

val proxy_authenticate : Name.t

proxy-authenticate

val proxy_authorization : Name.t

proxy-authorization

val range : Name.t

range

val referer : Name.t

referer

val retry_after : Name.t

retry-after

val sec_fetch_site : Name.t

sec-fetch-site

val sec_fetch_mode : Name.t

sec-fetch-mode

val sec_fetch_user : Name.t

sec-fetch-user

val sec_fetch_dest : Name.t

sec-fetch-dest

val server : Name.t

server

val set_cookie : Name.t

set-cookie

val te : Name.t

te

val trailer : Name.t

trailer

val transfer_encoding : Name.t

transfer-encoding

val upgrade : Name.t

upgrade

val user_agent : Name.t

user-agent

val vary : Name.t

vary

val via : Name.t

via

val warning : Name.t

warning

val www_authenticate : Name.t

www-authenticate