Module Http_types

module Http_types: sig .. end
Type definitions

type version = [ `HTTP_1_0 | `HTTP_1_1 ] 
HTTP version, actually only 1.0 and 1.1 are supported. Note that 'supported' here means only 'accepted inside a HTTP request line', no different behaviours are actually implemented depending on HTTP version
type meth = [ `GET | `POST ] 
HTTP method, actually only GET and POST methods are supported
type daemon_mode = [ `Fork | `Single | `Thread ] 
Daemon behaviour wrt request handling. `Single mode use a single process to handle all requests, no request is served until a previous one has been fully served. `Fork mode fork a new process for each request, the new process will execute the callback function and then exit. `Thread mode create a new thread for each request, the new thread will execute the callback function and then exit, threads can communicate using standard OCaml Thread library.
type tcp_server = sockaddr:Unix.sockaddr ->
timeout:int option ->
(Pervasives.in_channel -> Pervasives.out_channel -> unit) -> unit
A TCP server is a function taking an address on which bind and listen for connections, an optional timeout after which abort client connections and a callback function which in turn takes an input and an output channel as arguments. After receiving this argument a TCP server sits and waits for connection, on each connection it apply the callback function to channels connected to client.
type auth_info = [ `Basic of string * string ] 
authentication information
type informational_substatus = [ `Continue | `Switching_protocols ] 
See also RFC2616 informational HTTP status
type success_substatus = [ `Accepted
| `Created
| `No_content
| `Non_authoritative_information
| `OK
| `Partial_content
| `Reset_content ]
See also RFC2616 success HTTP status
type redirection_substatus = [ `Found
| `Moved_permanently
| `Multiple_choices
| `Not_modified
| `See_other
| `Temporary_redirect
| `Use_proxy ]
See also RFC2616 redirection HTTP status
type client_error_substatus = [ `Bad_request
| `Conflict
| `Expectation_failed
| `Forbidden
| `Gone
| `Length_required
| `Method_not_allowed
| `Not_acceptable
| `Not_found
| `Payment_required
| `Precondition_failed
| `Proxy_authentication_required
| `Request_URI_too_large
| `Request_entity_too_large
| `Request_time_out
| `Requested_range_not_satisfiable
| `Unauthorized
| `Unsupported_media_type ]
See also RFC2616 client error HTTP status
type server_error_substatus = [ `Bad_gateway
| `Gateway_time_out
| `HTTP_version_not_supported
| `Internal_server_error
| `Not_implemented
| `Service_unavailable ]
See also RFC2616 server error HTTP status
type informational_status = [ `Informational of informational_substatus ] 
type success_status = [ `Success of success_substatus ] 
type redirection_status = [ `Redirection of redirection_substatus ] 
type client_error_status = [ `Client_error of client_error_substatus ] 
type server_error_status = [ `Server_error of server_error_substatus ] 
type error_status = [ `Client_error of client_error_substatus
| `Server_error of server_error_substatus ]
type status = [ `Client_error of client_error_substatus
| `Informational of informational_substatus
| `Redirection of redirection_substatus
| `Server_error of server_error_substatus
| `Success of success_substatus ]
HTTP status
type status_code = [ `Code of int | `Status of status ] 

type file_source =
| FileSrc of string (*filename*)
| InChanSrc of Pervasives.in_channel (*input channel*)
File sources


exception Invalid_header of string
invalid header encountered
exception Invalid_header_name of string
invalid header name encountered
exception Invalid_header_value of string
invalid header value encountered
exception Invalid_HTTP_version of string
unsupported or invalid HTTP version encountered
exception Invalid_HTTP_method of string
unsupported or invalid HTTP method encountered
exception Invalid_code of int
invalid HTTP status code integer representation encountered
exception Malformed_URL of string
invalid URL encountered
exception Malformed_query of string
invalid query string encountered
exception Malformed_query_part of string * string
invalid query string part encountered, arguments are parameter name and parameter value
exception Malformed_request_URI of string
invalid request URI encountered
exception Malformed_cookies of string
malformed cookies
exception Malformed_request of string
malformed request received
exception Malformed_response of string
malformed response received, argument is response's first line
exception Param_not_found of string
a parameter you were looking for was not found
exception Invalid_status_line of string
invalid HTTP status line encountered
exception Header_not_found of string
an header you were looking for was not found
exception Quit
raisable by callbacks to make main daemon quit, this is the only 'clean' way to make start functions return
exception Unauthorized of string
raisable by callbacks to force a 401 (unauthorized) HTTP answer. This exception should be raised _before_ sending any data over given out channel.

OO representation of HTTP messages

class type message = object .. end
HTTP generic messages.
class type request = object .. end
HTTP requests
class type response = object .. end
HTTP responses

Daemon specification

type daemon_spec = {
   address : string;
   auth : (string * auth_info) option; (*authentication requirements (currently only basic authentication is supported). If set to None no authentication is required. If set to Some ("realm", `Basic ("foo", "bar")), only clients authenticated with baisc authentication, for realm "realm", providing username "foo" and password "bar" are accepted; others are rejected with a 401 response code*)
   callback : request -> Pervasives.out_channel -> unit; (*function which will be called each time a correct HTTP request will be received. 1st callback argument is an Http_types.request object corresponding to the request received; 2nd argument is an output channel corresponding to the socket connected to the client*)
   mode : daemon_mode; (*requests handling mode, it can have three different values:
  • `Single -> all requests will be handled by the same process,
  • `Fork -> each request will be handled by a child process,
  • `Thread -> each request will be handled by a (new) thread
   port : int; (*TCP port on which the daemon will be listening*)
   root_dir : string option; (*directory to which ocaml http will chdir before starting handling requests; if None, no chdir will be performed (i.e. stay in the current working directory)*)
   exn_handler : (exn -> Pervasives.out_channel -> unit) option; (*what to do when executing callback raises an exception. If None, the exception will be re-raised: in `Fork/`Thread mode the current process/thread will be terminated. in `Single mode the exception is ignored and the client socket closed. If Some callback, the callback will be executed before acting as per None; the callback is meant to perform some clean up actions, like releasing global mutexes in `Thread mode*)
   timeout : int option; (*timeout in seconds after which an incoming HTTP request will be terminated closing the corresponding TCP connection; None disable the timeout*)
   auto_close : bool; (*whether ocaml-http will automatically close the connection with the client after callback has completed its execution. If set to true, close will be attempted no matter if the callback raises an exception or not*)
daemon specification, describe the behaviour of an HTTP daemon.

The default daemon specification is Http_daemon.default_spec

OO representation of other HTTP entities

class type connection = object .. end
an HTTP connection from a client to a server
class type daemon = object .. end
an HTTP daemon