(* $Id: nethttp.mli 1099 2007-03-28 19:35:32Z gerd $
* ----------------------------------------------------------------------
* Nethttp: Basic definitions for the HTTP protocol
*)
(** {1 Basic definitions for the HTTP protocol} *)
(** These definitions can be used by both HTTP clients and servers, and by
* protocols in the middle, e.g. CGI.
*)
type protocol_version =
int * int (* (major,minor) number *)
(** A pair of a major and minor version number *)
type protocol_attribute =
[ `Secure_https
]
type protocol =
[ `Http of (protocol_version * protocol_attribute list)
| `Other
]
(** The base protocol. RFC 2145 defines how to interpret major and
* minor numbers. In particular, we have:
* - [`Http((0,9),_)] is the ancient HTTP version 0.9
* - [`Http((1,n),_)] is the HTTP protocol 1.n. It is expected that
* all these versions are compatible to each other
* except negotiable features.
* - [`Http((m,_),_)] for m>1 is regarded as unknown protocol,
* incompatible to any [`Http((1,n),_)]
* - [`Other] is anything else (unrecognizes protocol)
*)
val string_of_protocol : protocol -> string
(** Returns the string representation, e.g. "HTTP/1.0". Fails for [`Other] *)
val protocol_of_string : string -> protocol
(** Parses the protocol string, e.g. "HTTP/1.0". Returns [`Other]
* for unrecognized strings *)
type http_status = (* Status codes from RFC 2616 *)
(* 1xx: (informational) *)
[ `Continue
| `Switching_protocols
(* 2xx: (successful) *)
| `Ok
| `Created
| `Accepted
| `Non_authoritative
| `No_content
| `Reset_content
| `Partial_content
(* 3xx: (redirection) *)
| `Multiple_choices
| `Moved_permanently
| `Found
| `See_other
| `Not_modified
| `Use_proxy
| `Temporary_redirect
(* 4xx: (client error) *)
| `Bad_request
| `Unauthorized
| `Payment_required
| `Forbidden
| `Not_found
| `Method_not_allowed
| `Not_acceptable
| `Proxy_auth_required
| `Request_timeout
| `Conflict
| `Gone
| `Length_required
| `Precondition_failed
| `Request_entity_too_large
| `Request_uri_too_long
| `Unsupported_media_type
| `Requested_range_not_satisfiable
| `Expectation_failed
(* 5xx: (server error) *)
| `Internal_server_error
| `Not_implemented
| `Bad_gateway
| `Service_unavailable
| `Gateway_timeout
| `Http_version_not_supported
]
(** HTTP response status:
*
* {b Informational (1xx):}
* - [`Continue]
* - [`Switching_protocols]
*
* {b Successful (2xx):}
* - [`Ok]
* - [`Created]
* - [`Accepted]
* - [`Non_authoritative]
* - [`No_content]
* - [`Reset_content]
* - [`Partial_content]
*
* {b Redirection (3xx):}
* - [`Multiple_choices]
* - [`Moved_permanently]
* - [`Found]
* - [`See_other]
* - [`Not_modified]
* - [`Use_proxy]
* - [`Temporary_redirect]
*
* {b Client error (4xx):}
* - [`Bad_request]
* - [`Unauthorized]
* - [`Payment_required]
* - [`Forbidden]
* - [`Not_found]
* - [`Method_not_allowed]
* - [`Not_acceptable]
* - [`Proxy_auth_required]
* - [`Request_timeout]
* - [`Conflict]
* - [`Gone]
* - [`Length_required]
* - [`Precondition_failed]
* - [`Request_entity_too_large]
* - [`Request_uri_too_long]
* - [`Unsupported_media_type]
* - [`Request_range_not_satisfiable]
* - [`Expectation_failed]
*
* {b Server Error (5xx):}
* - [`Internal_server_error]
* - [`Not_implemented]
* - [`Bad_gateway]
* - [`Service_unavailable]
* - [`Gateway_timeout]
* - [`Http_version_not_supported]
*)
val int_of_http_status : http_status -> int
(** Returns the integer code for a status value *)
val http_status_of_int : int -> http_status
(** Returns the status value for an integer code, or raises [Not_found] *)
val string_of_http_status : http_status -> string
(** Returns the informational text for a status value *)
(* See also Netcgi.status_line *)
type http_method = string * string
(** Method name, URI *)
type cache_control_token =
[ `No_store
| `Max_age of int
| `Max_stale of int option
| `Min_fresh of int
| `No_transform
| `Only_if_cached
| `Public
| `Private of string list
| `No_cache of string list
| `Must_revalidate
| `Proxy_revalidate
| `S_maxage of int
| `Extension of string * string option
]
(** The cache control token for the [Cache-control] header *)
type etag =
[ `Weak of string
| `Strong of string
]
(** Entity tags can be weak or strong *)
val weak_validator_match : etag -> etag -> bool
(** Whether the tags match weakly (see RFC 2616 for definition) *)
val strong_validator_match : etag -> etag -> bool
(** Whether the tags match strongly (see RFC 2616 for definition) *)
exception Bad_header_field of string
(** Raised when a header field cannot be parsed. The string argument
* is the name of the failing function *)
class type http_header = Netmime.mime_header
class type http_header_ro = Netmime.mime_header_ro
(** The HTTP header is represented as MIME header *)
class type http_trailer = Netmime.mime_header
class type http_trailer_ro = Netmime.mime_header_ro
(** The HTTP trailer is represented as MIME header *)
val status_of_cgi_header : http_header -> (int * string)
(** Returns the status code and the status text corresponding to the
* [Status] header *)
type cookie = (* Cgi.cookie = *)
{ cookie_name : string;
(** The name of the cookie *)
cookie_value : string;
(** The value of the cookie. There are no restrictions on the
* value of the cookie
*)
cookie_expires : float option;
(** Expiration:
* - [None]: the cookie expires when the browser session ends.
* - [Some t]: the cookie expires at the time [t] (seconds since
* the epoch)
*)
cookie_domain : string option;
(** Cookies are bound to a certain domain, i.e. the browser sends
* them only when web pages of the domain are requested:
*
* - [None]: the domain is the hostname of the server
* - [Some domain]: the domain is [domain]
*)
cookie_path : string option;
(** Cookies are also bound to certain path prefixes, i.e. the browser
* sends them only when web pages at the path or below are requested.
*
* - [None]: the path is script name + path_info
* - [Some p]: the path is [p]. With [Some "/"] you can disable the
* path restriction completely.
*)
cookie_secure : bool;
(** Cookies are also bound to the type of the web server:
* [false] means servers without SSL, [true] means servers with
* activated SSL ("https").
*)
}
val decode_query : string -> (string * string)
(** Splits the URI into a "script name" and a "query string" *)
val split_host_port : string -> (string * int option)
(** Splits the [Host] header in hostname and optional port number.
* Fails on syntax error
*)
val uripath_encode : string -> string
(** Encodes unsafe characters in URI paths. The slash character is not encoded.
* This function should only be applied to the part before '?'.
*)
val uripath_decode : string -> string
(** Decodes %XX sequences in URI paths. %2F is forbidden (failure).
* This function should only be applied to the part before '?'.
*)
(**********************************************************************)
(** {2 Parsing and Printing of Headers} *)
module Header : sig
(** This module is a parser/printer for the header fields used in HTTP/1.1.
* The [get_*] functions generally raise [Not_found] when the queried header
* is not present. If the syntax of the field is a comma-separated list of
* multiple values, the [get_*] functions generally merge all headers of
* the same type. The order is preserved in this case. The list [[]] means
* that the header exists, but only with empty value. For example,
*
* {[
* Accept: text/html
* Accept: text/plain
* ]}
*
* would be returned as [["text/html",[],[]; "text/plain", [],[]]]
* by [get_accept]. The header
*
* {[Accept:]}
*
* would be returned as [[]].
*
* The [set_*] functions generally produce only a single header with comma-
* separated values. Existing header are overwritten/removed.
*
* To remove a header, simply use the [delete_field] method of [http_header].
*
* Error behaviour: The [get_*] functions raise [Bad_header_field]
* when they cannot parse a header field. The [set_*] functions
* raise [Invalid_argument] when an invalid value is passed to them
* (only very few functions do that). The argument of both
* exceptions is the function name.
*)
val get_accept : #http_header_ro -> (string *
(string * string) list *
(string * string) list) list
(** Returns the [Accept] header as list of triples [(media_range,
