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