Ocamlnet 4 Reference Manual : Nethttp

# Module Nethttp

    module Nethttp: sig .. end

## 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

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 = [ `Accepted
           | `Bad_gateway
           | `Bad_request
           | `Conflict
           | `Continue
           | `Created
           | `Expectation_failed
           | `Forbidden
           | `Found
           | `Gateway_timeout
           | `Gone
           | `Http_version_not_supported
           | `Internal_server_error
           | `Length_required
           | `Method_not_allowed
           | `Moved_permanently
           | `Multiple_choices
           | `No_content
           | `Non_authoritative
           | `Not_acceptable
           | `Not_found
           | `Not_implemented
           | `Not_modified
           | `Ok
           | `Partial_content
           | `Payment_required
           | `Precondition_failed
           | `Proxy_auth_required
           | `Request_entity_too_large
           | `Request_timeout
           | `Request_uri_too_long
           | `Requested_range_not_satisfiable
           | `Reset_content
           | `See_other
           | `Service_unavailable
           | `Switching_protocols
           | `Temporary_redirect
           | `Unauthorized
           | `Unsupported_media_type
           | `Use_proxy ]

HTTP response status:

Informational (1xx):

- ``Continue`
- ``Switching_protocols`

Successful (2xx):

- ``Ok`
- ``Created`
- ``Accepted`
- ``Non_authoritative`
- ``No_content`
- ``Reset_content`
- ``Partial_content`

Redirection (3xx):

- ``Multiple_choices`
- ``Moved_permanently`
- ``Found`
- ``See_other`
- ``Not_modified`
- ``Use_proxy`
- ``Temporary_redirect`

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`

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

    val base_code : int -> int

Allows to handle unknown status codes that are untranslatable by `http_status_of_int`:

- for a code 100 to 199 the value 100 is returned
- for a code 200 to 299 the value 200 is returned
- for a code 300 to 399 the value 300 is returned
- for a code 400 to 499 the value 400 is returned
- for all other codes 500 is returned

E.g.

      let st =
        try Nethttp.http_status_of_int code
        with Not_found ->
          Nethttp.http_status_of_int (Nethttp.base_code code)

    type http_method = string * string

Method name, URI

    type cache_control_token = [ `Extension of string * string option
           | `Max_age of int
           | `Max_stale of int option
           | `Min_fresh of int
           | `Must_revalidate
           | `No_cache of string list
           | `No_store
           | `No_transform
           | `Only_if_cached
           | `Private of string list
           | `Proxy_revalidate
           | `Public
           | `S_maxage of int ]

The cache control token for the `Cache-control` header

    type etag = [ `Strong of string | `Weak 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 netscape_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"). | `*)`

}

These are old-style cookies, as introduced by Netscape. For a better representation of cookies see the `Nethttp.Cookie` module.

This type is kept for now (and is also not considered as deprecated), as the access functions in the `Nethttp.Header` module are more complete than those for `Nethttp.Cookie`.

    type cookie = netscape_cookie

Compatibility name. Deprecated

    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 '?'.

### Parsing and Printing of Headers

    module Cookie: sig .. end

    module Header: sig .. end

### HTTP transport registry

    type transport_layer_id = int

see `Nethttp_client.transport_layer_id`

    val new_trans_id : unit -> transport_layer_id

Allocates and returns a new ID

    val http_trans_id : transport_layer_id

Identifies the pure HTTP transport (without SSL), with or without web proxies

    val https_trans_id : transport_layer_id

Identifies anonymous HTTPS transport (i.e. no client certificates), with or without web proxies.

    val spnego_trans_id : transport_layer_id

Identifies an anonymous HTTPS transport that is additionally authenticated via SPNEGO (as described in RFC 4559)

    val proxy_only_trans_id : transport_layer_id

Identifies web proxy connections. Use this to e.g. send an FTP URL to a web proxy via HTTP

### Types for authentication

See also `Netsys_sasl_types.SASL_MECHANISM`. This is very similar, only that

- the messages are encapsulated as HTTP headers, and
- the "realm" parameter is commonly supported by mechanisms

In SASL terms, HTTP authentication is normally "server first". There is only one exception: re-authentication, which is "client first".

    type match_result = [ `Accept of string * string option
           | `Accept_reroute of string * string option * transport_layer_id
           | `Reject
           | `Reroute of string * transport_layer_id ]

See `Nethttp.HTTP_CLIENT_MECHANISM.client_match`

    module type HTTP_CLIENT_MECHANISM = sig .. end