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:

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:

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:

open Lwt.Infix

module Make (HTTP_client : Http_mirage_client.S) = struct
  let start http_client =
    Http_mirage_client.one_request http_client "https://mirage.io/"
    >>= 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