h2-mirage

Mirage support for h2
README

h2 is an implementation of the
HTTP/2 specification entirely in OCaml.
It is based on the concepts in
http/af, and therefore uses the
Angstrom and Faraday libraries to implement the parsing
and serialization layers of the HTTP/2 standard. It also preserves the same API
as http/af wherever possible.

Installation

Install the library and its dependencies via OPAM:

opam install h2

Usage

There's generated documentation here

Examples TBD, see the examples folder.

Conformance

One of h2's goals is to be 100% compliant with the HTTP/2 specification.
There are currently 3 mechanisms in place to verify such conformance:

  1. Unit tests using the HPACK stories in the
    http2jp/hpack-test-case.
    repository

  2. Unit tests using the test cases provided by the
    http2jp/http2-frame-test-case
    repository.

  3. Automated test runs (in CI) using the
    h2spec conformance testing tool for
    HTTP/2 implementations.

    • These test all the Reqd.respond_with_* functions for conformance against
      the specification.

Performance

h2 aims to be a high-performance, memory-efficient, scalable, and easily
portable (with respect to different I/O runtimes) implementation. To achieve
that, it takes advantage of the unbuffered parsing interface in Angstrom using
off-heap buffers wherever possible, for both parsing and serialization.

Limitations

h2 only currently provides a server implementation. In the future, a
client library will also be provided.

Development

This source distribution provides a number of packages and examples. The
directory structure is as follows:

  • examples/: contains example applications using the various
    I/O runtimes provided in this source distribution.

  • hpack/: contains the implementation of
    HPACK, the Header Compression
    specification for HTTP/2.

  • lib/: contains the core implementation of this library, including
    HTTP/2 frame parsing, serialization and state machine implementations.

  • lib_test/: contains various unit tests for modules in the
    core h2 package.

  • lwt/: contains an implementation of a Lwt runtime for h2
    functorized over the specific input / output channel abstraction such that it
    can work in either UNIX-like systems or MirageOS.

  • lwt-unix/: contains an Lwt runtime adapter for h2 that
    communicates over UNIX file descriptors.

  • mirage/: contains a Mirage runtime adapter for h2 that
    allows using h2 to write unikernels that serve traffic over HTTP/2.

  • spec/: contains example implementations of servers using h2
    that respond with the different provided APIs to be used for conformance
    testing with the h2spec tool.

Cloning the repository

# Use --recurse-submodules to get the test git submodules
$ git clone git@github.com:anmonteiro/ocaml-h2.git --recurse-submodules

Using OPAM

To install development dependencies, pin the package from the root of the
repository:

$ opam pin add -n hpack .
$ opam pin add -n h2 .
$ opam install --deps-only h2

After this, you may install a development version of the library using the
install command as usual.

Tests can be run via dune:

dune runtest

Using Esy

There's an esy.json file at the root of this repository that can be used
to develop h2 with Esy.

To resolve and install the necessary dependencies, run:

$ esy

Build any examples or run the tests by prefixing the dune commands with
esy b or esy build. For example:

$ esy b dune runtest

License

h2 is distributed under the 3-Clause BSD License, see LICENSE.

This source distribution includes work based on
http/af. http/af's license file is
included in httpaf.LICENSE

Install
Published
08 Apr 2019
Sources
h2-0.2.0.tbz
md5=c883927ce8a9f3f7159ef7b20988f051
Dependencies
mirage-conduit
>= "3.0.0"
conduit-lwt
>= "1.0.0" & < "2.3.0"
conduit
>= "1.0.0" & < "2.3.0"
h2-lwt
= version
h2
= version
ocaml
>= "4.04"
Reverse Dependencies