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

Exceptions

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