Module Nethttp_client

module Nethttp_client: sig .. end

• chunked message transport
• persistent connections
• connections in pipelining mode ("full duplex" connections)
• modular authentication methods, currently Basic, Digest, and Negotiate
• event-driven implementation; allows concurrent service for several network connections
• HTTP proxy support, also with Basic and Digest authentication
• SOCKS proxy support (1)
• HTTPS support is now built-in, but requires that a TLS provider is initialized (see Tls for more information). HTTPS proxies are also supported (CONNECT method) (1)
• Automatic and configurable retry of failed idempotent requests
• Redirections can be followed automatically
• Compressed message bodies can be automatically decoded (gzip only, method set_accept_encoding) (1)

• multipart messages, including multipart/byterange
• content digests specified by RFC 2068 and 2069 (2)
• content negotiation (2)
• conditional and partial GET (2)
• client-side caching (2)
• HTTP/0.9 compatibility

(2) These features can be implemented on top of this module if really needed, but there is no special support for them.

Related modules/software:

• Nethttp_fs allows you to access HTTP servers in the style of filesystems
• WebDAV: If you are looking for WebDAV there is an extension of this module: Webdav, which is separately available.

The module can be compiled such that it is thread-safe. In particular, one has to link the http_client_mt.cmxo object, and thread-safety is restricted to the following kinds of usage:

• The golden rule is that threads must not share pipeline objects. If every thread uses its own pipeline, every thread will have its own set of state variables. It is not detected if two threads errornously share a pipeline, neither by an error message nor by implicit serialization. Strange things may happen.
• The same applies to the other objects, e.g. http_call objects
• The Convenience module even serializes; see below.

Types and Exceptions

exception Bad_message of string

exception No_reply

exception Too_many_redirections

exception Name_resolution_error of string

exception URL_syntax_error of string

exception Timeout of string

exception Proxy_error of int

exception Response_too_large

exception Http_protocol of exn

exception Http_error of (int * string)

type status = [ `Client_error
       | `Http_protocol_error of exn
       | `Redirection
       | `Server_error
       | `Successful
       | `Unserved ] 

type 'a auth_status = [ `Auth_error
       | `Continue of 'a
       | `Continue_reroute of 'a * int
       | `None
       | `OK
       | `Reroute of int ] 

type 'message_class how_to_reconnect = 

type 'message_class how_to_redirect = 

type private_api 

type response_body_storage = [ `Body of unit -> Netmime.mime_body
       | `Device of unit -> Uq_io.out_device
       | `File of unit -> string
       | `Memory ] 

type synchronization = 

type resolver = Unixqueue.unix_event_system ->
       string -> (Unix.inet_addr option -> unit) -> unit 

type transport_layer_id = int 

type http_options = {

    let opts = pipeline # get_options in
    let new_opts = { opts with <field> = <value>; ... } in
    pipeline # set_options new_opts
 

type header_kind = [ `Base | `Effective ] 

class type http_call = object .. end

class type tls_cache = object .. end

val null_tls_cache : unit -> tls_cache

val unlim_tls_cache : unit -> tls_cache

class type transport_channel_type = object .. end

HTTP methods

class virtual generic_call : object .. end

class get_call : http_call

class trace_call : http_call

class options_call : http_call

class head_call : http_call

class post_call : http_call

class put_call : http_call

class delete_call : http_call

class get : string -> http_call

class trace : string -> int -> http_call

class options : string -> http_call

class head : string -> http_call

class post : string -> (string * string) list -> http_call

class post_raw : string -> string -> http_call

class put : string -> string -> http_call

class delete : string -> http_call

Authentication

class type key = object .. end

val key : user:string ->
       password:string ->
       realm:string -> domain:Neturl.url list -> key

val key_creds : user:string ->
       creds:(string * string * (string * string) list) list ->
       http_options -> key

class type key_handler = object .. end

class key_ring : ?uplink:#key_handler -> ?no_invalidation:bool -> unit -> object .. end

class type auth_session = object .. end

class type auth_handler = object .. end

class basic_auth_handler : ?enable_reauth:bool -> ?skip_challenge:bool -> #key_handler -> auth_handler

class digest_auth_handler : #key_handler -> auth_handler

class unified_auth_handler : ?insecure:bool -> #key_handler -> auth_handler

class generic_auth_handler : #key_handler -> (module Nethttp.HTTP_CLIENT_MECHANISM) list -> auth_handler

Transport

type connection_cache = Nethttp_client_conncache.connection_cache 

val close_connection_cache : connection_cache -> unit

val create_restrictive_cache : unit -> connection_cache

val create_aggressive_cache : unit -> connection_cache

val http_trans_id : transport_layer_id

val https_trans_id : transport_layer_id

val spnego_trans_id : transport_layer_id

val proxy_only_trans_id : transport_layer_id

val new_trans_id : unit -> transport_layer_id

val http_transport_channel_type : transport_channel_type

val https_transport_channel_type : Netsys_crypto_types.tls_config -> transport_channel_type

        let my_trans_id = Nethttp_client.new_trans_id()
        let my_tct = Nethttp_client.https_transport_channel_type my_tls_config
        pipeline # configure_transport my_trans_id my_tct;
      

        call # set_transport_layer my_trans_id
      

type proxy_type = [ `Http_proxy | `Socks5 ] 

Pipelines

class pipeline : object .. end

 let call = new get "http://server/path" in
 let pipeline = new pipeline in
 pipeline # add call;
 pipeline # run();    (* Now the HTTP client is working... *)
 match call # status with
 | `Successful -> ...
 | ...
 

Auxiliary pipeline functions

val parse_proxy_setting : insecure:bool -> string -> string * int * (string * string * bool) option

val parse_no_proxy : string -> string list

Convenience module for simple applications

module Convenience: sig .. end

Debugging

module Debug: sig .. end