mirror of https://github.com/c-cube/tiny_httpd.git synced 2025-12-06 03:05:29 -05:00

Yawar Amin cafa2a5420 Show small example of socket activation

I wasn't sure how much detail to include, so I kept it on the shorter side and
referred to Poettering's blog post for more details.

2022-02-12 17:04:07 -05:00

3.8 KiB

Raw Blame History

Tiny_httpd

Minimal HTTP server using good old threads, with stream abstractions, simple routing, URL encoding/decoding, and optional compression with camlzip. It also supports server-sent events (w3c)

Free from all forms of ppx, async monads, etc. 🙃

Note: it can be useful to add the jemalloc opam package for long running server, as it does a good job at controlling memory usage.

The basic echo server from src/examples/echo.ml:


module S = Tiny_httpd

let () =
  let server = S.create () in
  (* say hello *)
  S.add_route_handler ~meth:`GET server
    S.Route.(exact "hello" @/ string @/ return)
    (fun name _req -> S.Response.make_string (Ok ("hello " ^name ^"!\n")));
  (* echo request *)
  S.add_route_handler server
    S.Route.(exact "echo" @/ return)
    (fun req -> S.Response.make_string (Ok (Format.asprintf "echo:@ %a@." S.Request.pp req)));
  Printf.printf "listening on http://%s:%d\n%!" (S.addr server) (S.port server);
  match S.run server with
  | Ok () -> ()
  | Error e -> raise e

$ dune exec src/examples/echo.exe &
listening on http://127.0.0.1:8080

# the path "hello/name" greets you.
$ curl -X GET http://localhost:8080/hello/quadrarotaphile
hello quadrarotaphile!

# the path "echo" just prints the request.
$ curl -X GET http://localhost:8080/echo --data "howdy y'all" 
echo:
{meth=GET;
 headers=Host: localhost:8080
         User-Agent: curl/7.66.0
         Accept: */*
         Content-Length: 10
         Content-Type: application/x-www-form-urlencoded;
 path="/echo"; body="howdy y'all"}

`http_of_dir`

Similar to python -m http.server, a simple program http_of_dir is provided. It serves files from the current directory.

$ http_of_dir . -p 8080 &
$ curl -X GET http://localhost:8080
...
<html list of current dir>
...

Socket activation

Since version 0.10, socket activation is supported indirectly, by allowing a socket to be explicitly passed in to the create function:

module S = Tiny_httpd

let not_found _ _ = S.Response.fail ~code:404 "Not Found\n"

let () =
  (* Module [Daemon] is from the [ocaml-systemd] package *)
  let server = match Daemon.listen_fds () with
    (* If no socket passed in, assume server was started explicitly i.e. without
       socket activation *)
    | [] -> S.create ()

    (* If a socket passed in e.g. by systemd, listen on that *)
    | sock :: _ -> S.create ~sock ()
  in
  S.add_route_handler server S.Route.rest_of_path not_found;
  Printf.printf "Listening on http://%s:%d\n%!" (S.addr server) (S.port server);
  match S.run server with
  | Ok () -> ()
  | Error e -> raise e

On Linux, this requires the ocaml-systemd package:

opam install ocaml-systemd

Tip: in the dune file, the package name should be systemd.

In case you're not familiar with socket activation, Lennart Poettering's blog post explains it well.

Why?

Why not? If you just want a super basic local server (perhaps for exposing data from a local demon, like Cups or Syncthing do), no need for a ton of dependencies or high scalability libraries.

Use cases might include:

serve content directly from a static blog generator;
provide a web UI to some tool (like CUPS and syncthing do);
implement a basic monitoring page for a service;
provide a simple json API for a service, on top of http;
use http_of_dir to serve odoc-generated docs or some assets directory.

Documentation

See https://c-cube.github.io/tiny_httpd

License

MIT.

3.8 KiB Raw Blame History