From 8b7a8fb5280da677389fafa12a77452db1e94f57 Mon Sep 17 00:00:00 2001
From: Romain Calascibetta <romain.calascibetta@gmail.com>
Date: Mon, 17 Oct 2022 14:36:34 +0200
Subject: [PATCH] Improve the README.md

---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/README.md b/README.md
index e69de29..52bd9ec 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,61 @@
+# An HTTP (http/1.1 or h2) client for MirageOS
+
+This little library provides an HTTP client which can be usable inside a
+unikernel/[MirageOS][mirage]. It follows the same API as
+[http-lwt-client][http-lwt-client] which is pretty simple and uses:
+- [happy-eyeballs][happy-eyeballs] to resolve domain-name
+- [ocaml-tls][ocaml-tls] for the TLS layer
+- [paf][paf] for the HTTP protocol
+
+This library wants to be easy to use and it is associated to a MirageOS
+_device_ in order to facilite `functoria` to compose everything (mainly the
+TCP/IP stack) according to the user's target and give a _witness_ so as to
+be able to allocate a new connection to a peer and process the HTTP flow.
+
+## How to use it?
+
+First, you need to describe a new `http_client` device:
+```ocaml
+open Mirage
+
+type http_client = HTTP_client
+let http_client = typ HTTP_client
+
+let http_client =
+  let connect _ modname = function
+    | [ _pclock; _tcpv4v6; ctx ] ->
+      Fmt.str {ocaml|%s.connect %s|ocaml} modname ctx
+    | _ -> assert false in
+  impl ~connect "Http_mirage_client.Make"
+    (pclock @-> tcpv4v6 @-> git_client @-> http_client)
+```
+
+Then, you can decide how to construct such device:
+```ocaml
+let stack = generic_stackv4v6 default_network
+let dns   = generic_dns_client stack
+let tcp   = tcpv4v6_of_stackv4v6 stack
+
+let http_client =
+  let happy_eyeballs = git_happy_eyeballs stack dns
+    (generic_happy_eyeballs stack dns) in
+  http_client $ default_posix_clock $ tcp $ happy_eyeballs
+```
+
+Finally, you can use the _witness_ into your `unikernel.ml`:
+```ocaml
+open Lwt.Infix
+
+module Make (HTTP_client : Http_mirage_client.S) = struct
+  let start http_client =
+    Http_mirage_client.one_request http_client "https://google.com/"
+    >>= function
+    | Ok (resp, body) -> ...
+    | Error _ -> ...
+end
+
+[mirage]: https://mirage.io/
+[happy-eyeballs]: https://github.com/roburio/happy-eyeballs
+[ocaml-tls]: https://github.com/mirleft/ocaml-tls
+[paf]: https://github.com/dinosaure/paf-le-chien
+[http-lwt-client]: https://github.com/roburio/http-lwt-client