http-mirage-client/README.md

# 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