package h2-lwt
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=8512fd4934e9ad4122b9305036a897556d66c9aade1f973c633c6e4d7ae06be6
md5=c883927ce8a9f3f7159ef7b20988f051
README.md.html
h2
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:
Unit tests using the HPACK stories in the http2jp/hpack-test-case. repository
Unit tests using the test cases provided by the http2jp/http2-frame-test-case repository.
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