80d2a5fddff39376a27a9a779b68595acc806762
[homepage.git] / hacking / software / ocaml-http.mdwn
1 [[meta title="OCaml HTTP"]]
2 # do it yourself (OCaml) HTTP daemon
3
4 **OCaml HTTP** is an [OCaml](http://caml.inria.fr) library freely inspired from
5 [Perl's HTTP::Daemon
6 module](http://search.cpan.org/~gaas/libwww-perl-5.808/lib/HTTP/Daemon.pm) that
7 permits you to write simple HTTP daemons in OCaml.
8
9 The main API let you define a HTTP daemon *specification*, which contains, among
10 other parameters, a **callback** function that is invoked each time a request is
11 received. The callback function will be invoked with an instance of an object
12 representing the received HTTP request and an `out_channel` connected to the
13 remote HTTP client socket.
14
15 Then you can start your HTTP daemon invoking the `main` function passing your
16 specification. Each time a client connect to the TCP port bound by your daemon,
17 OCaml HTTP will parse the request and instantiate the request object. If all
18 goes well your callback will be invoked, otherwise appropriate error messages
19 will be sent back to the client without disturbing your callback.
20
21 You can use a lot of *facility* functions in your callback that permits you to
22 send easily headers, error responses, file, or abstract HTTP response objects.
23 Otherwise you can also choose the 'hard way' and send data directly to the
24 `out_channel` (expecially useful for *sending data incrementally* to the
25 client). You can also mix the two approaches.
26
27 Daemon specifications are used also to specify other parameters governing daemon
28 behaviour like: TCP *port and address* to bind, way of handling incoming
29 requests (handle all of them in a *single process*, *fork* a new process or
30 spawn a new *thread* for each incoming request), *timeout*, *authentication*
31 requirements (username and password for HTTP basic authentication).
32
33 OCaml HTTP contains also a tiny implementation of a **HTTP client** which can be
34 used to retrieve resources via GET HTTP method and to *iter* on them (useful for
35 huge resources which can't be kept in memory).
36
37 * [[changelog]] for the latest version (0.1.3)
38 * [[API|html/index.html]] documentation
39 * some trivial [examples](examples/)
40
41 OCaml HTTP is freely distributed under the GNU Library General Public License
42 (GPL) and is available here for **download**:
43
44 * tarball (sources) [[ocaml-http-0.1.3.tar.gz]]
45 * official Debian packages are available: [[debpkg libhttp-ocaml-dev]]
46 * browse the [Subversion
47 repository](http://helm.cs.unibo.it/websvn/listing.php?repname=helm&path=/trunk/helm/software/DEVEL/ocaml-http/&rev=0&sc=0)
48
49 To build OCaml HTTP from sources you will need:
50
51 * [the ocaml compiler](http://caml.inria.fr)
52 * [findlib](http://www.ocaml-programming.de/programming/findlib.html)
53 * [ocamlnet](http://sourceforge.net/projects/ocamlnet)
54 * [pcre-ocaml](http://www.ocaml.info/home/ocaml_sources.html)
55