(*
OCaml HTTP - do it yourself (fully OCaml) HTTP daemon
- Copyright (C) <2002> Stefano Zacchiroli <zack@cs.unibo.it>
+ Copyright (C) <2002-2004> Stefano Zacchiroli <zack@cs.unibo.it>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
+(** Main OCaml HTTP module.
+ Here you can find two set of functions:
+ - functions which let you start an HTTP Daemon (start* functions)
+ - facility functions which let you sent responses back to clients *)
+
(** send a CRLF sequence on the given output channel, this is mandatory after
the last header was sent and before start sending the response body *)
val send_CRLF: out_channel -> unit
either code or status must be given (not both, not none) which represent the
HTTP response code, outchan is the output channel to which send status line *)
val send_status_line:
- ?version: Http_types.version -> ?code: int -> ?status: Http_types.status ->
+ ?version:Http_types.version -> code:Http_types.status_code ->
out_channel ->
unit
(** like send_status_line but additionally will also send "Date" and "Server"
standard headers *)
val send_basic_headers:
- ?version: Http_types.version -> ?code: int -> ?status: Http_types.status ->
+ ?version: Http_types.version -> code:Http_types.status_code ->
out_channel ->
unit
(** as send_header, but for a list of pairs <header, value> *)
val send_headers: headers:(string * string) list -> out_channel -> unit
+(*
(** send a file through an out_channel, file can be passed as an in_channel
(if 'file' is given) or as a file name (if 'name' is given) *)
val send_file: ?name:string -> ?file:in_channel -> out_channel -> unit
+*)
+ (** send a file through an out_channel *)
+val send_file: src:Http_types.file_source -> out_channel -> unit
- (** high level response function, respond on outchan sending: basic headers,
- headers probided via 'headers' argument, body given via 'body' argument.
- Default response status is 200, default response HTTP version is
- Http_common.http_version *)
+ (** high level response function, respond on outchan sending: basic headers
+ (including Content-Length computed using 'body' argument), headers probided
+ via 'headers' argument, body given via 'body' argument. Default response
+ status is 200, default response HTTP version is Http_common.http_version *)
val respond:
?body:string -> ?headers:(string * string) list ->
- ?version:Http_types.version -> ?code:int -> ?status:Http_types.status ->
+ ?version:Http_types.version -> ?code:Http_types.status_code ->
out_channel ->
unit
(** send a "redirection" class response, optional body argument contains data
that will be displayed in the body of the response, default response status is
- 302 (moved permanently), only redirection status are accepted by this
- function, other values will @raise Failure *)
+ 301 (moved permanently), only redirection status are accepted by this
+ function, other values will raise Failure *)
val respond_redirect:
location:string -> ?body:string ->
- ?version: Http_types.version ->
- ?code: int -> ?status: Http_types.redirection_status ->
+ ?version: Http_types.version -> ?code:Http_types.status_code ->
out_channel ->
unit
+ (** respond with a 401 (Unauthorized) response asking for authentication
+ * against given realm (default is the server name) *)
+val respond_unauthorized:
+ ?version: Http_types.version -> ?realm:string -> out_channel -> unit
+
(** send an "error" response (i.e. 400 <= status < 600), optional body
argument as per send_redirect, default response status is 400 (bad request),
only error status are accepted by this function, other values will
- @raise Failure *)
+ raise Failure *)
val respond_error:
?body:string ->
- ?version: Http_types.version ->
- ?code: int -> ?status: Http_types.error_status ->
+ ?version: Http_types.version -> ?code:Http_types.status_code ->
out_channel ->
unit
(** respond using a prebuilt Http_types.response object *)
val respond_with: Http_types.response -> out_channel -> unit
- (** create an HTTP daemon listening on 'addr':'port' (defaults are
- addr:"0.0.0.0" and port:80), callback is the user supplied function which
- receive as a first parameter the path required by the the HTTP client as a
- string, and a list of pair <parameter, value> representing parameters passed
- via GET. The last argument of the callback is an output_channel connected to
- the HTTP client to which the user can write directly. 'timeout' parameter sets
- a timeout for each request processed by the daemon, if it's set to None,
- daemon waits forever for completed requests (use with care!), default is 5
- minute. 'mode' parameter has 3 possible values: `Single means that all request
- are handled by the same process, `Fork means that each request is handled by a
- separate process, `Thread means that each request is handled by a separate
- thread, default is `Fork; 'root' (mnemonic "document root") is the directory
- where the daemon chdir before starting up, default is current working
- directory *)
+ (** starts an HTTP daemon listening
+ * @param addr adress on which daemon will be listening, can be both a numeric
+ * address (e.g. "127.0.0.1") and an hostname (e.g. "localhost"). Default is
+ * the wildcard address "0.0.0.0"
+ * @param port TCP port on which the daemon will be listening. Default is the
+ * HTTP port 80
+ * @param timeout timeout in seconds after which an incoming HTTP request will
+ * be terminated closing the corresponding TCP connection. Passing None will
+ * disable the timeout. Default is 5 minutes (300 seconds)
+ * @param 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 separate process
+ * `Thread -> each request will be handled by a separate thread
+ * Default is `Fork
+ * @param root document root (i.e. directory to which ocaml http will chdir
+ * before starting handling requests). Default is current working directory
+ * @param callback function which will be called each time a correct HTTP
+ * request will be received. 1st callback argument is the path requested by
+ * the HTTP client; 2nd argument is a list of pairs <parameter, value>
+ * representing decoded query string; 3rd argument is an output channel
+ * connected with the client
+ *)
val start:
?addr: string -> ?port: int ->
?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string ->
(Http_types.request -> out_channel -> unit) ->
unit
-(*
- (** OO interface to HTTP daemons *)
+ (** Object oriented interface to HTTP daemons.
+ @param addr address on which daemon will listen for connections
+ @param port port which daemon will bind
+ see {! Http_types.daemon} *)
class daemon:
?addr: string -> ?port: int ->
- ?timeout: int option -> ?mode: Http_types.daemon_mode ->?root:; string ->
- (Http_types.request -> out_channel -> unit) ->
- Http_types.daemon
-*)
+ unit ->
+ Http_types.daemon
- (** Trivial static pages HTTP daemon *)
+ (** Trivial static pages HTTP daemon.
+ Daemons created using this module will serve directory indexes and files found
+ starting from the working directory *)
module Trivial :
sig
+ (** callback function, exposed if you like to use it as a basis to define
+ a more powerful daemon *)
val callback : string -> 'a -> out_channel -> unit
+
+ (** start the "trivial" HTTP daemon *)
val start : ?addr:string -> ?port:int -> unit -> unit
end
projects / helm.git / blobdiff