nghq is a HTTP framing layer that aims to provide support for the HTTP/QUIC mapping for running HTTP over IETF QUIC.
The nghq API is modelled after that of nghttp2. The application owns the communicating socket and feeds data into the library via a series of calls. The application is expected to act on callbacks from the library. There are a couple of important points to note:
- nghq does not own the socket. The application is expected to read data from the socket and provide it to the library. When the library has some data to send, it will call back into the application with the data to be sent on the application's socket.
- nghq does not do any encryption or decryption of the packets received. It is up to the application to manage the TLS context. The encrypt and decrypt callbacks will be fired when the library needs encryption or decryption to be done.
The public API is documented here. In addition, the library's public header file nghq.h has comment blocks for every function and callback listed above it which also serve as documentation.
Some helpful sequence diagrams, showing the expected interaction between a client/server application and nghq can be found here.
NOTE: In its current form, nghq implements only the parts of the QUIC and HTTP3 specifications required by draft-pardue-quic-http-mcast-07.
In particular, it only supports a profile of the draft-ietf-quic-transport-29, and draft-ietf-quic-http-29.
If you wish to build and run the examples, you will also need libev version 4.0 or above.
nghq uses the ls-qpack library to perform QPACK header compression and decompression routines. The ls-qpack library is included as a linked git submodule, which should be initialised and updated as part of the bootstrap script.
The build system itself uses Automake. To build the software, do the following:
$ ./bootstrap
$ ./configure
$ make
To enable some fairly verbose debugging output from the library, you can supply
the --enable-debug option to the configure script. This will write output
from nghq to the command line when the library is run.
Debugging output is disabled by default.
To install the software, use make install. To change where nghq will be
installed, use the prefix configuration parameter as below:
$ ./configure --prefix=/home/roadrunner/nghq-target
$ make install
If you had libev installed when building, then the examples in the
examples/ directory will be built. Currently, there is a simple multicast
sender and a multicast receiver application. Run them with --help to see the
available runtime options.
This software is licensed under an MIT License. See the COPYING file for more.
If you have a feature request or want to report a bug, we'd be happy to hear from you. Please either raise an issue, or fork the project and send us a pull request.
This software was written by Sam Hurst with additional contributions by David Waring.
Copyright (c) 2020 British Broadcasting Corporation