From 08d90f78960fb8e6119a4a6ce30afcfa7e6e552b Mon Sep 17 00:00:00 2001
From: Rudi Grinberg <me@rgrinberg.com>
Date: Sun, 30 Jun 2024 12:35:17 +0100
Subject: [PATCH] chore: document cohttp-server-lwt-unix (#1049)

Signed-off-by: Rudi Grinberg <me@rgrinberg.com>
---
 README.md                                     |  2 +
 .../src/cohttp_server_lwt_unix.mli            | 68 +++++++++++++++++++
 2 files changed, 70 insertions(+)

diff --git a/README.md b/README.md
index 2360de7ea9..b9fc604aad 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,8 @@ libraries:
 * `Cohttp_curl` uses `libcurl`, via `ocurl`, as backend. It also comes
   with lwt (`Cohttp_curl_lwt`) and async backends (`Cohttp_curl_async`).
 * `Cohttp_eio` uses `eio` to leverage new features from multicore ocaml 5.0.
+* `Cohttp_server_lwt_unix` uses lwt to implement a more efficient web server
+  with a minimal interface.
 
 You can implement other targets using the parser very easily. Look at the `IO`
 signature in `lib/s.mli` and implement that in the desired backend.
diff --git a/cohttp-server-lwt-unix/src/cohttp_server_lwt_unix.mli b/cohttp-server-lwt-unix/src/cohttp_server_lwt_unix.mli
index e5706bab40..cafa6a7e80 100644
--- a/cohttp-server-lwt-unix/src/cohttp_server_lwt_unix.mli
+++ b/cohttp-server-lwt-unix/src/cohttp_server_lwt_unix.mli
@@ -1,34 +1,102 @@
+(** High performance lwt server
+
+    This module is an alternative to the server offered in
+    [Cohttp_lwt_unix.Server]. It's a simplified implementation that has less
+    functionality but offers more control and better performance. The
+    differences are as follows:
+
+      - Vastly improved performance due to optimized buffer handling
+      - No dependency on conduit
+      - No builtin logging
+
+   An example server: {[
+     open Lwt.Syntax
+
+     let server_callback ctx =
+       Lwt.join
+         [
+           Cohttp_server_lwt_unix.ontext.discard_body ctx;
+           Cohttp_server_lwt_unix.ontext.respond ctx
+            (Http.Response.make ())
+            (Cohttp_server_lwt_unix.Body.string "hello world");
+         ]
+
+     let main () =
+       let* _server =
+         let listen_address = Unix.(ADDR_INET (inet_addr_loopback, 8080)) in
+         let server = Cohttp_server_lwt_unix.create server_callback in
+         Lwt_io.establish_server_with_client_address ~backlog:10_000 listen_address
+           (fun _addr ch -> Cohttp_server_lwt_unix.handle_connection server ch)
+       in
+       let forever, _ = Lwt.wait () in
+       forever
+
+     let () = ignore (Lwt_main.run (main ()))
+   ]}
+ *)
+
 module Body : sig
   module Encoding : sig
     type t
+    (** HTTP body encoding *)
 
     val fixed : int64 -> t
     val chunked : t
   end
 
   type t
+  (** A response body *)
 
   val string : ?encoding:Encoding.t -> string -> t
+  (** [string ?encoding s] respond with body [s].
+
+      [?encoding] the encoding to use. by default this is [Encoding.fixed] *)
 
   module Substring : sig
     type t = { base : string; pos : int; len : int }
   end
 
   val stream : ?encoding:Encoding.t -> (unit -> Substring.t option Lwt.t) -> t
+  (** [stream ?encoding f] respond with body generated by repeatedly applying
+      [f]. When [f] returns [None], it will be considered terminated.
+
+      [?encoding] is the encoding to use. By deafult this is [Encoding.chunked]. *)
 end
 
 module Context : sig
   type t
+  (** A request context *)
 
   val request : t -> Http.Request.t
+  (** [request t] returns the HTTP request *)
+
   val read_body : t -> string Lwt.t
+  (** [read_body t] read the request body as a string *)
+
   val discard_body : t -> unit Lwt.t
+  (** [discard_body t] discard the request body *)
+
   val respond : t -> Http.Response.t -> Body.t -> unit Lwt.t
+  (** [respond t response body] respond to the request with [response] and
+      [body] *)
 end
 
 type t
+(** The type of an HTTP server able to handle requests. *)
 
 val create : ?on_exn:(exn -> unit) -> (Context.t -> unit Lwt.t) -> t
+(** [create ?on_exn f] creates an HTTP server that will handle every incoming
+    request with [f] concurrently.
+
+    [on_exn] will be called on exceptions not caught in [f] or raisedd by the
+    server itself. If [on_exn] isn't provided [Lwt.async_exception_hook] will be
+    used. *)
 
 val handle_connection :
   t -> Lwt_io.input_channel * Lwt_io.output_channel -> unit Lwt.t
+(** [handle_connection t (i, o)] will handle all HTTP requests incoming from [i]
+    and write them to [o].
+
+    This function should be used with
+    [Lwt_io.establish_server_with_client_address] to setup a running HTTP
+    server. *)