Documentation

Author: craff

Makefile

@@ -7,7 +7,7 @@ all: build test
 
 .PHONY: build
 build: ./src/field-names.csv ./src/chaml/entities.json ${TAGTABLES}
-	@dune build
+	@dune build @install
 
 .PHONY: test
 test:

doc/dune

@@ -1,3 +1,13 @@
 (documentation
 	(package simple_httpd)
 	(mld_files index vfs_pack template))
+
+(rule
+  (targets index.mld)
+  (deps index.mld.template ../examples/echo.ml)
+  (action
+    (with-stdout-to %{targets}
+    (run sed
+       -e /@@ECHO@@/r../examples/echo.ml
+       -e /@@ECHO@@/d
+       index.mld.template))))

doc/index.mld

@@ -0,0 +1,99 @@
+{0 Simple_httpd library to write web server and application}
+
+{1 Introduction}
+
+This library implements a HTTP/1.1 server for Linux using domains and
+algebraic effects. It uses [epoll] and [eventfd] to schedule the treatment of
+clients very efficiently, with one domain used to accept requests and several
+domains to handle these requests. [Simple_httpd] can listen to several
+addresses and ports and use this information together with the headers [Host]
+field to decide how to answer the request.
+
+It is fast and can handle several thousands of simultaneous connections. It
+may use memory cache, [sendfile] system call and other TCP options to reach an
+efficiency comparable or better than nginx on static files.
+
+Through a bunch of modules, described here {!Simple_httpd}, we provide:
+
+- Routing, by address, port, host and url path.
+
+- Handling of static files possibly using a memory cache or a virtual file
+  system.  More precisely, it can serves a directory dynamically (hence
+  reflecting changes has they occur on the file system) or use
+  {{:./vfs_pack.html}vfs_pack} to compile a static folder (In this can changed
+  nee recompilation and restarts), see below.
+
+- Basic management of session and cookies. Simple_httpd sessions can for
+  instance keep an open connection to a database server. Session are saved and
+  restored on server restart and the {!Simple_httpd.Auth} module provide basic
+  authentication. Its functorial interface allow for more complex
+  authentication like CAS.
+
+- Support for ssl using {{:https://github.com/savonet/ocaml-ssl}ocaml-ssl}. This
+  includes using ktls if your linux kernel supports it.
+
+- A {!Simple_httpd.Host} module dedicated to write single server handling
+  several sites or applications.
+
+- A {{:./vfs_pack.html}web site compiler vfs_pack}, the will cache small files
+  in memory and bigger files in a separate store. This allows not to store the
+  source of your websites on the server. Files in store or memory may be
+  pre-compressed with zip (a.k.a. deflate, gzip is planned).
+
+- {{:./vfs_pack.html}vfs_pack} includes an equivalent of php files named
+  [chaml] that are compiled to OCaml, but much faster than php (and also
+  safer). It will also parse [html] files allowing to detect error and minimizing them.
+  Parsing and dynamic css [are] planned.
+
+- It is fast: Here are some curves showing the performance on static files
+  compared to nginx and apache. Our 99% quantile is very good, meaning that
+  {!Simple_httpd} handles very quickly most request.
+
+{1 Benchmarks}
+
+Here is a plot of the latency obtained using
+{{:https://github.com/tsenart/vegeta} [vegeta]} with 1000 requests per seconds
+for 15s, on a small static file.  Simple_httpd uses
+{!Simple_httpd.Dir.add_vfs} using {{:./vfs_pack.html}[vfs_pack]} from the
+[example/echo.ml] file shown below:
+
+{%html: <p align="center"><img src="/simple_httpd/bench/static.svg" alt="Latencies for static files"/></p>%}
+
+Here is the same graphic for a small chaml/php dynamic file.
+
+{%html: <p align="center"><img src="/simple_httpd/bench/dynamic.svg" alt="Latencies for dynamic files"/></p>%}
+
+Here are some other graphs showing the maximum number of requests possible, using {{:https://nghttp2.org/documentation/h2load-howto.html}[h2load]}
+
+{%html: <p align="center"><img src="/simple_httpd/bench/bench_foo_1k.svg" alt="comparison for small files"/></p>%}
+
+{%html: <p align="center"><img src="/simple_httpd/bench/bench_foo_500k.svg" alt="comparison for large files"/></p>%}
+
+[apache] and [nginx] are the usual servers with [php-fpm] and their default
+configuration on debian 13 except for accepting more connections than the
+default. There is a (reproducible) problem with nginx and php without ssl with
+a few extreme value that impact the mean, and also some errors in rare
+cases. Comparatively, simple_httpd serves all requests.
+
+Here is a similar graph showing the difference between [.php] and [.chaml] on
+a similar file. It shows that simple_httpd can serve at least than 5 times
+more requests.
+
+{%html: <p align="center"><img src="/simple_httpd/bench/bench_chaml_bar.html.svg" alt="comparison chaml versus php"/></p>%}
+
+{1 Quick start}
+
+A good start is the template folder of the distribution, documented
+{{:./template.html}[here]}. It contains the skeleton for a server serving
+two sites with status report and statistics.
+
+See also [examples/echo.ml] below, that demonstrates some of the features by
+declaring a few endpoints, including one for uploading files and a virtual
+file system.
+
+To go further, you should start reading {!Simple_httpd} the main module of the library and
+look at {{:./template.html}[template]} that is provided.
+
+{[
+@@ECHO@@
+]}