3 OCaml HTTP - do it yourself (fully OCaml) HTTP daemon
5 Copyright (C) <2002-2004> Stefano Zacchiroli <zack@cs.unibo.it>
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22 (** Main OCaml HTTP module.
23 Here you can find two set of functions:
24 - functions which let you start an HTTP Daemon (start* functions)
25 - facility functions which let you sent responses back to clients *)
27 (** send a CRLF sequence on the given output channel, this is mandatory after
28 the last header was sent and before start sending the response body *)
29 val send_CRLF: out_channel -> unit
31 (** send response status line, version is the http version used in response,
32 either code or status must be given (not both, not none) which represent the
33 HTTP response code, outchan is the output channel to which send status line *)
35 ?version:Http_types.version -> code:Http_types.status_code ->
39 (** like send_status_line but additionally will also send "Date" and "Server"
41 val send_basic_headers:
42 ?version: Http_types.version -> code:Http_types.status_code ->
46 (** send an HTTP header on outchan *)
47 val send_header: header: string -> value: string -> out_channel -> unit
49 (** as send_header, but for a list of pairs <header, value> *)
50 val send_headers: headers:(string * string) list -> out_channel -> unit
53 (** send a file through an out_channel, file can be passed as an in_channel
54 (if 'file' is given) or as a file name (if 'name' is given) *)
55 val send_file: ?name:string -> ?file:in_channel -> out_channel -> unit
57 (** send a file through an out_channel *)
58 val send_file: src:Http_types.file_source -> out_channel -> unit
60 (** high level response function, respond on outchan sending: basic headers
61 (including Content-Length computed using 'body' argument), headers probided
62 via 'headers' argument, body given via 'body' argument. Default response
63 status is 200, default response HTTP version is Http_common.http_version *)
65 ?body:string -> ?headers:(string * string) list ->
66 ?version:Http_types.version -> ?code:Http_types.status_code ->
70 (** send a 404 (not found) HTTP response *)
71 val respond_not_found:
72 url:string -> ?version: Http_types.version -> out_channel -> unit
74 (** send a 403 (forbidden) HTTP response *)
75 val respond_forbidden:
76 url:string -> ?version: Http_types.version -> out_channel -> unit
78 (** send a "redirection" class response, optional body argument contains data
79 that will be displayed in the body of the response, default response status is
80 301 (moved permanently), only redirection status are accepted by this
81 function, other values will raise Failure *)
83 location:string -> ?body:string ->
84 ?version: Http_types.version -> ?code:Http_types.status_code ->
88 (** respond with a 401 (Unauthorized) response asking for authentication
89 * against given realm (default is the server name) *)
90 val respond_unauthorized:
91 ?version: Http_types.version -> ?realm:string -> out_channel -> unit
93 (** send an "error" response (i.e. 400 <= status < 600), optional body
94 argument as per send_redirect, default response status is 400 (bad request),
95 only error status are accepted by this function, other values will
99 ?version: Http_types.version -> ?code:Http_types.status_code ->
103 (** tipical static pages http daemon behaviour, if requested url is a file,
104 return it, it it is a directory return a directory listing of it *)
106 fname:string -> ?version: Http_types.version -> out_channel -> unit
108 (** respond using a prebuilt Http_types.response object *)
109 val respond_with: Http_types.response -> out_channel -> unit
111 (** start an HTTP daemon
112 * @param spec specification of daemon behaviour
114 val main: Http_types.daemon_spec -> unit
116 (** default daemon specification:
117 * - listen on 0.0.0.0, port 80
118 * - "always ok" callback (return an empty response, response code 200)
119 * - fork a child for each request
120 * - do not change to a root directory (i.e. keep cwd)
121 * - 300 seconds timeout
122 * - ignores exceptions
123 * - no authentication required *)
124 val default_spec: Http_types.daemon_spec
126 (** currified daemon_spec constructor. Each parameter of this function
127 * corresponds to one field of Http_types.daemon_spec and defaults to the
128 * corresponding field of Http_daemon.default_spec *)
131 ?auth:(string * Http_types.auth_info) option ->
132 ?callback:(Http_types.request -> out_channel -> unit) ->
133 ?mode:(Http_types.daemon_mode) ->
135 ?root_dir:string option ->
136 ?exn_handler:(exn -> out_channel -> unit) option ->
137 ?timeout:int option ->
139 Http_types.daemon_spec
141 (** starts an HTTP daemon (deprecated function)
143 * DEPRECATED, will be removed in future versions, please switch to
144 * Http_daemon.main below.
146 * see Http_types.daemon_spec for a detailed description of parameters
147 * @param addr like the "address" field of Http_types.daemon_spec, defaults to
148 * the wildcard address "0.0.0.0"
149 * @param like the "port" field of Http_types.daemon_spec, defaults to 80
150 * @param like the "timeout" field of Http_types.daemon_spec, defaults to Some
152 * @param like the "mode" field of Http_types.daemon_spec, defaults to `Fork
153 * @param like the "root_dir" field of Http_types.daemon_spec, defaults to None
154 * @param callback functional version of the "callback" field of
155 * Http_types.daemon_spec. 1st argument is the request path, 2nd argument
156 * the decoded query string, 3rd argument an output channel connect to the
160 ?addr: string -> ?port: int ->
161 ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string ->
162 (string -> (string * string) list -> out_channel -> unit) ->
165 (** starts an HTTP daemon (deprecated function)
167 * DEPRECATED, will be removed in future versions, please switch to
168 * Http_daemon.main below.
170 * parameters as above except for the callback, in this case it behaves as the
171 * "callback" field of Http_types.daemon_spec
174 ?addr: string -> ?port: int ->
175 ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string ->
176 (Http_types.request -> out_channel -> unit) ->
179 (** Object oriented interface to HTTP daemons.
180 @param addr address on which daemon will listen for connections
181 @param port port which daemon will bind
182 see {! Http_types.daemon} *)
184 ?addr: string -> ?port: int ->
188 (** Trivial static pages HTTP daemon.
189 Daemons created using this module will serve directory indexes and files found
190 starting from the working directory *)
193 (** callback function, exposed if you like to use it as a basis to define
194 a more powerful daemon *)
195 val callback : Http_types.request -> out_channel -> unit
197 (** start the "trivial" HTTP daemon
198 * @param spec trivial HTTP daemon specification, "callback" field is
199 * ignored and set to the callback above *)
200 val main : Http_types.daemon_spec -> unit