nghttp2/README.rst

1025 lines
30 KiB
ReStructuredText
Raw Normal View History

2014-03-30 12:09:21 +02:00
nghttp2 - HTTP/2 C Library
2013-07-12 17:19:03 +02:00
============================
2012-01-26 17:38:35 +01:00
2013-07-12 17:19:03 +02:00
This is an experimental implementation of Hypertext Transfer Protocol
2014-03-30 12:09:21 +02:00
version 2.
2012-09-12 15:37:05 +02:00
2012-04-25 14:25:51 +02:00
Development Status
------------------
2012-03-26 16:46:02 +02:00
2014-04-05 11:20:38 +02:00
We started to implement h2-11
(http://tools.ietf.org/html/draft-ietf-httpbis-http2-11) and the
2013-08-22 20:45:55 +02:00
header compression
2014-04-05 11:20:38 +02:00
(http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-07).
2013-08-22 20:45:55 +02:00
The nghttp2 code base was forked from spdylay project.
2013-07-12 17:19:03 +02:00
2014-02-15 09:19:49 +01:00
========================== =====
2014-04-05 11:20:38 +02:00
Features h2-11
2014-02-15 09:19:49 +01:00
========================== =====
2014-04-05 11:20:38 +02:00
HPACK-draft-07 Done
Dependency based priority Done
ALTSVC frame Done
2014-02-15 09:19:49 +01:00
========================== =====
2013-07-16 17:08:05 +02:00
2013-08-10 12:06:33 +02:00
Public Test Server
------------------
2013-08-25 15:04:54 +02:00
The following endpoints are available to try out nghttp2
2014-02-16 07:50:36 +01:00
implementation.
2013-08-10 12:06:33 +02:00
2014-02-16 07:50:36 +01:00
* https://106.186.112.116/ (TLS + NPN / ALPN)
2013-08-30 17:50:09 +02:00
2014-04-06 10:23:42 +02:00
ALPN and NPN offer ``h2-11``, ``spdy/3.1`` and ``http/1.1``.
2013-08-10 12:06:33 +02:00
2014-04-06 10:23:42 +02:00
.. note::
certificate is self-signed and a browser will show alert.
2013-08-30 17:50:09 +02:00
2014-02-16 07:50:36 +01:00
* http://106.186.112.116/ (Upgrade / Direct)
2014-04-06 10:23:42 +02:00
``h2c-11`` and ``http/1.1``. We configured this server to send
ALTSVC frame or Alt-Svc header field to announce that alternative
service is available at port 443.
2013-08-10 12:06:33 +02:00
2013-07-27 14:56:46 +02:00
Requirements
------------
2013-07-16 17:08:05 +02:00
2013-07-27 14:56:46 +02:00
The following packages are needed to build the library:
2013-07-19 19:05:07 +02:00
2013-07-27 14:56:46 +02:00
* pkg-config >= 0.20
* zlib >= 1.2.3
2013-07-19 19:05:07 +02:00
2013-07-27 14:56:46 +02:00
To build and run the unit test programs, the following packages are
required:
* cunit >= 2.1
To build the documentation, you need to install:
* sphinx (http://sphinx-doc.org/)
2013-07-27 14:56:46 +02:00
To build and run the application programs (``nghttp``, ``nghttpd`` and
``nghttpx``) in ``src`` directory, the following packages are
required:
* OpenSSL >= 1.0.1
* libevent-openssl >= 2.0.8
2014-01-02 05:32:43 +01:00
ALPN support requires unreleased version OpenSSL >= 1.0.2.
2014-03-02 15:44:43 +01:00
To enable SPDY protocol in the application program ``nghttpx`` and
``h2load``, the following packages are required:
2013-07-27 14:56:46 +02:00
2014-01-04 02:44:16 +01:00
* spdylay >= 1.2.3
2013-07-27 14:56:46 +02:00
To enable ``-a`` option (getting linked assets from the downloaded
2013-10-10 18:02:24 +02:00
resource) in ``nghttp``, the following packages are needed:
2013-07-27 14:56:46 +02:00
* libxml2 >= 2.7.7
2014-01-10 13:53:48 +01:00
The HPACK tools require the following package:
2013-10-27 08:23:24 +01:00
2014-01-08 17:48:34 +01:00
* jansson >= 2.5
2013-10-27 08:23:24 +01:00
2014-03-05 13:46:26 +01:00
To mitigate heap fragmentation in long running server programs
(``nghttpd`` and ``nghttpx``), jemalloc is recommended:
* jemalloc
The Python bindings require the following packages:
* cython >= 0.19
* python >= 2.7
2013-07-27 14:56:46 +02:00
If you are using Ubuntu 12.04, you need the following packages
installed:
* autoconf
* automake
* autotools-dev
* libtool
* pkg-config
* zlib1g-dev
* libcunit1-dev
* libssl-dev
* libxml2-dev
* libevent-dev
2013-10-27 08:23:24 +01:00
* libjansson-dev
2014-03-05 13:46:26 +01:00
* libjemalloc-dev
2013-07-27 14:56:46 +02:00
spdylay is not packaged in Ubuntu, so you need to build it yourself:
2013-11-21 14:03:18 +01:00
http://tatsuhiro-t.github.io/spdylay/
2013-07-27 14:56:46 +02:00
2013-07-27 15:46:22 +02:00
Build from git
--------------
Building from git is easy, but please be sure that at least autoconf 2.68 is
used::
$ autoreconf -i
$ automake
$ autoconf
$ ./configure
$ make
2013-07-27 14:56:46 +02:00
Building documentation
----------------------
.. note::
Documentation is still incomplete.
To build documentation, run::
$ make html
The documents will be generated under ``doc/manual/html/``.
The generated documents will not be installed with ``make install``.
2013-07-28 16:00:12 +02:00
The online documentation is available at
http://tatsuhiro-t.github.io/nghttp2/
2013-07-27 14:56:46 +02:00
Client, Server and Proxy programs
---------------------------------
2014-03-30 12:09:21 +02:00
The src directory contains HTTP/2 client, server and proxy programs.
2013-07-27 14:56:46 +02:00
nghttp - client
+++++++++++++++
2014-04-08 16:12:02 +02:00
``nghttp`` is a HTTP/2 client. It can connect to the HTTP/2 server
2014-01-01 17:00:11 +01:00
with prior knowledge, HTTP Upgrade and NPN/ALPN TLS extension.
2013-07-27 14:56:46 +02:00
2014-04-08 16:12:02 +02:00
It has verbose output mode for framing information. Here is sample
2013-07-27 14:56:46 +02:00
output from ``nghttp`` client::
2014-02-15 09:19:49 +01:00
$ src/nghttp -nv https://localhost:8443
[ 0.004][NPN] server offers:
2014-04-05 11:20:38 +02:00
* h2-11
2014-02-15 09:19:49 +01:00
* spdy/3.1
2014-01-11 09:06:26 +01:00
* spdy/3
* spdy/2
* http/1.1
2014-04-05 11:20:38 +02:00
The negotiated protocol: h2-11
2014-02-15 09:19:49 +01:00
[ 0.006] send SETTINGS frame <length=10, flags=0x00, stream_id=0>
2014-01-11 09:06:26 +01:00
(niv=2)
2014-02-15 09:19:49 +01:00
[SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
[SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
[ 0.007] send HEADERS frame <length=48, flags=0x05, stream_id=1>
2014-01-11 09:06:26 +01:00
; END_STREAM | END_HEADERS
2014-02-15 09:19:49 +01:00
(padlen=0)
2014-01-11 09:06:26 +01:00
; Open new stream
:authority: localhost:8443
:method: GET
:path: /
:scheme: https
accept: */*
accept-encoding: gzip, deflate
2014-02-15 09:19:49 +01:00
user-agent: nghttp2/0.4.0-DEV
[ 0.007] recv SETTINGS frame <length=15, flags=0x00, stream_id=0>
(niv=3)
[SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
[SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
[SETTINGS_ENABLE_PUSH(2):0]
[ 0.007] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
2014-01-11 09:06:26 +01:00
; ACK
(niv=0)
2014-02-15 09:19:49 +01:00
[ 0.007] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
2014-01-11 09:06:26 +01:00
; ACK
(niv=0)
2014-02-15 09:19:49 +01:00
[ 0.008] (stream_id=1) :status: 200
[ 0.008] (stream_id=1) accept-ranges: bytes
[ 0.008] (stream_id=1) content-encoding: gzip
[ 0.008] (stream_id=1) content-length: 146
[ 0.008] (stream_id=1) content-type: text/html
[ 0.008] (stream_id=1) date: Sat, 15 Feb 2014 08:14:12 GMT
[ 0.008] (stream_id=1) etag: "b1-4e5535a027780-gzip"
[ 0.008] (stream_id=1) last-modified: Sun, 01 Sep 2013 14:34:22 GMT
[ 0.008] (stream_id=1) server: Apache/2.4.6 (Debian)
[ 0.008] (stream_id=1) vary: Accept-Encoding
[ 0.008] (stream_id=1) via: 1.1 nghttpx
[ 0.008] recv HEADERS frame <length=141, flags=0x04, stream_id=1>
2014-01-11 09:06:26 +01:00
; END_HEADERS
2014-02-15 09:19:49 +01:00
(padlen=0)
2014-01-11 09:06:26 +01:00
; First response header
2014-02-15 09:19:49 +01:00
[ 0.008] recv DATA frame <length=146, flags=0x00, stream_id=1>
[ 0.008] recv DATA frame <length=0, flags=0x01, stream_id=1>
2014-01-11 09:06:26 +01:00
; END_STREAM
2014-02-15 09:19:49 +01:00
[ 0.008] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
2014-01-11 09:06:26 +01:00
(last_stream_id=0, error_code=NO_ERROR(0), opaque_data(0)=[])
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
The HTTP Upgrade is performed like this::
2014-02-15 09:19:49 +01:00
$ src/nghttp -nvu http://localhost:8080
2013-08-03 12:44:13 +02:00
[ 0.000] HTTP Upgrade request
GET / HTTP/1.1
2013-08-22 20:45:55 +02:00
Host: localhost:8080
2013-08-03 12:44:13 +02:00
Connection: Upgrade, HTTP2-Settings
2014-04-05 11:20:38 +02:00
Upgrade: h2c-11
2014-02-15 09:19:49 +01:00
HTTP2-Settings: AwAAAGQEAAD__w
2013-08-03 12:44:13 +02:00
Accept: */*
2014-02-15 09:19:49 +01:00
User-Agent: nghttp2/0.4.0-DEV
2013-08-03 12:44:13 +02:00
2014-02-15 09:19:49 +01:00
[ 0.001] HTTP Upgrade response
2013-08-03 12:44:13 +02:00
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
2014-04-05 11:20:38 +02:00
Upgrade: h2c-11
2013-08-03 12:44:13 +02:00
2013-10-27 15:29:54 +01:00
[ 0.001] HTTP Upgrade success
2014-02-15 09:19:49 +01:00
[ 0.001] send SETTINGS frame <length=10, flags=0x00, stream_id=0>
2014-01-11 09:06:26 +01:00
(niv=2)
2014-02-15 09:19:49 +01:00
[SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
[SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
[ 0.001] recv SETTINGS frame <length=15, flags=0x00, stream_id=0>
(niv=3)
[SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
[SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
[SETTINGS_ENABLE_PUSH(2):0]
[ 0.001] (stream_id=1) :status: 200
[ 0.001] (stream_id=1) accept-ranges: bytes
[ 0.001] (stream_id=1) content-length: 177
[ 0.001] (stream_id=1) content-type: text/html
[ 0.001] (stream_id=1) date: Sat, 15 Feb 2014 08:16:23 GMT
[ 0.001] (stream_id=1) etag: "b1-4e5535a027780"
[ 0.001] (stream_id=1) last-modified: Sun, 01 Sep 2013 14:34:22 GMT
[ 0.001] (stream_id=1) server: Apache/2.4.6 (Debian)
[ 0.001] (stream_id=1) vary: Accept-Encoding
[ 0.001] (stream_id=1) via: 1.1 nghttpx
[ 0.001] recv HEADERS frame <length=132, flags=0x04, stream_id=1>
2014-01-11 09:06:26 +01:00
; END_HEADERS
2014-02-15 09:19:49 +01:00
(padlen=0)
2014-01-11 09:06:26 +01:00
; First response header
2013-10-27 15:29:54 +01:00
[ 0.001] recv DATA frame <length=177, flags=0x00, stream_id=1>
2013-08-22 20:45:55 +02:00
[ 0.001] recv DATA frame <length=0, flags=0x01, stream_id=1>
2014-01-11 09:06:26 +01:00
; END_STREAM
2014-02-15 09:19:49 +01:00
[ 0.002] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
2014-01-11 09:06:26 +01:00
; ACK
(niv=0)
2014-02-15 09:19:49 +01:00
[ 0.002] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
2014-01-11 09:06:26 +01:00
(last_stream_id=0, error_code=NO_ERROR(0), opaque_data(0)=[])
2014-02-15 09:19:49 +01:00
[ 0.002] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
2014-01-11 09:06:26 +01:00
; ACK
(niv=0)
2013-08-03 12:44:13 +02:00
2013-07-27 14:56:46 +02:00
nghttpd - server
++++++++++++++++
2014-03-04 15:16:46 +01:00
``nghttpd`` is a multi-threaded static web server.
2013-07-27 14:56:46 +02:00
2014-04-08 16:12:02 +02:00
By default, it uses SSL/TLS connection. Use ``--no-tls`` option to
2013-07-27 15:40:44 +02:00
disable it.
2014-03-30 12:09:21 +02:00
``nghttpd`` only accepts the HTTP/2 connection via NPN/ALPN or direct
2014-04-08 16:12:02 +02:00
HTTP/2 connection. No HTTP Upgrade is supported.
2013-08-03 12:44:13 +02:00
2013-12-08 16:06:53 +01:00
``-p`` option allows users to configure server push.
2013-07-27 14:56:46 +02:00
Just like ``nghttp``, it has verbose output mode for framing
2014-04-08 16:12:02 +02:00
information. Here is sample output from ``nghttpd`` server::
2013-07-27 14:56:46 +02:00
2013-08-22 20:45:55 +02:00
$ src/nghttpd --no-tls -v 8080
IPv4: listen on port 8080
IPv6: listen on port 8080
2014-02-15 09:19:49 +01:00
[id=1] [ 1.027] send SETTINGS frame <length=10, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
[SETTINGS_ENABLE_PUSH(2):0]
[id=1] [ 1.027] recv SETTINGS frame <length=10, flags=0x00, stream_id=0>
2014-01-11 09:06:26 +01:00
(niv=2)
2014-02-15 09:19:49 +01:00
[SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
[SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
[id=1] [ 1.027] (stream_id=1) :authority: localhost:8080
[id=1] [ 1.027] (stream_id=1) :method: GET
[id=1] [ 1.027] (stream_id=1) :path: /
[id=1] [ 1.027] (stream_id=1) :scheme: http
[id=1] [ 1.027] (stream_id=1) accept: */*
[id=1] [ 1.027] (stream_id=1) accept-encoding: gzip, deflate
[id=1] [ 1.027] (stream_id=1) user-agent: nghttp2/0.4.0-DEV
[id=1] [ 1.027] recv HEADERS frame <length=48, flags=0x05, stream_id=1>
2014-01-11 09:06:26 +01:00
; END_STREAM | END_HEADERS
2014-02-15 09:19:49 +01:00
(padlen=0)
2014-01-11 09:06:26 +01:00
; Open new stream
2014-02-15 09:19:49 +01:00
[id=1] [ 1.027] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
2014-01-11 09:06:26 +01:00
; ACK
(niv=0)
2014-02-15 09:19:49 +01:00
[id=1] [ 1.027] send HEADERS frame <length=72, flags=0x04, stream_id=1>
2014-01-11 09:06:26 +01:00
; END_HEADERS
2014-02-15 09:19:49 +01:00
(padlen=0)
2014-01-11 09:06:26 +01:00
; First response header
:status: 404
content-encoding: gzip
content-type: text/html; charset=UTF-8
2014-02-15 09:19:49 +01:00
date: Sat, 15 Feb 2014 08:18:53 GMT
server: nghttpd nghttp2/0.4.0-DEV
[id=1] [ 1.028] send DATA frame <length=118, flags=0x00, stream_id=1>
[id=1] [ 1.028] send DATA frame <length=0, flags=0x01, stream_id=1>
2014-01-11 09:06:26 +01:00
; END_STREAM
2014-02-15 09:19:49 +01:00
[id=1] [ 1.028] stream_id=1 closed
[id=1] [ 1.028] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
2014-01-11 09:06:26 +01:00
; ACK
(niv=0)
2014-02-15 09:19:49 +01:00
[id=1] [ 1.028] recv GOAWAY frame <length=8, flags=0x00, stream_id=0>
2014-01-11 09:06:26 +01:00
(last_stream_id=0, error_code=NO_ERROR(0), opaque_data(0)=[])
2014-02-15 09:19:49 +01:00
[id=1] [ 1.028] closed
2013-07-27 14:56:46 +02:00
nghttpx - proxy
+++++++++++++++
``nghttpx`` is a multi-threaded reverse proxy for
2014-04-05 11:20:38 +02:00
``h2-11``, SPDY and HTTP/1.1. It has several operation modes:
2013-08-03 12:44:13 +02:00
2014-03-30 12:09:21 +02:00
================== ============================ ============== =============
Mode option Frontend Backend Note
================== ============================ ============== =============
default mode HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1 Reverse proxy
``--http2-proxy`` HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1 SPDY proxy
``--http2-bridge`` HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/2 (TLS)
``--client`` HTTP/2, HTTP/1.1 HTTP/2 (TLS)
``--client-proxy`` HTTP/2, HTTP/1.1 HTTP/2 (TLS) Forward proxy
================== ============================ ============== =============
2013-07-27 14:56:46 +02:00
2014-04-08 16:12:02 +02:00
The interesting mode at the moment is the default mode. It works like
2014-04-05 11:20:38 +02:00
a reverse proxy and listens for ``h2-11``, SPDY and HTTP/1.1 and can
be deployed SSL/TLS terminator for existing web server.
2013-07-27 14:56:46 +02:00
2013-11-04 10:26:08 +01:00
The default mode, ``--http2-proxy`` and ``--http2-bridge`` modes use
2014-04-08 16:12:02 +02:00
SSL/TLS in the frontend connection by default. To disable SSL/TLS,
use ``--frontend-no-tls`` option. If that option is used, SPDY is
disabled in the frontend and incoming HTTP/1.1 connection can be
upgraded to HTTP/2 through HTTP Upgrade.
2013-08-03 12:44:13 +02:00
2013-11-04 10:26:08 +01:00
The ``--http2-bridge``, ``--client`` and ``--client-proxy`` modes use
2014-04-08 16:12:02 +02:00
SSL/TLS in the backend connection by deafult. To disable SSL/TLS, use
2013-08-03 12:44:13 +02:00
``--backend-no-tls`` option.
2013-07-27 15:40:44 +02:00
2014-04-08 16:12:02 +02:00
``nghttpx`` supports configuration file. See ``--conf`` option and
2013-07-27 14:56:46 +02:00
sample configuration file ``nghttpx.conf.sample``.
``nghttpx`` does not support server push.
2013-12-18 15:33:20 +01:00
2013-11-04 10:26:08 +01:00
In the default mode, (without any of ``--http2-proxy``,
``--http2-bridge``, ``--client-proxy`` and ``--client`` options),
``nghttpx`` works as reverse proxy to the backend server::
2013-07-27 14:56:46 +02:00
2014-03-30 12:09:21 +02:00
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Web Server
2013-08-03 12:44:13 +02:00
[reverse proxy]
2013-07-27 14:56:46 +02:00
2013-11-04 10:26:08 +01:00
With ``--http2-proxy`` option, it works as so called secure proxy (aka
SPDY proxy)::
2013-07-27 14:56:46 +02:00
2014-03-30 12:09:21 +02:00
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy
2013-08-03 12:44:13 +02:00
[secure proxy] (e.g., Squid)
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
The ``Client`` in the above is needs to be configured to use
``nghttpx`` as secure proxy.
2013-07-27 14:56:46 +02:00
At the time of this writing, Chrome is the only browser which supports
2014-04-08 16:12:02 +02:00
secure proxy. The one way to configure Chrome to use secure proxy is
2014-01-11 09:13:24 +01:00
create proxy.pac script like this:
.. code-block:: javascript
2013-07-27 14:56:46 +02:00
function FindProxyForURL(url, host) {
return "HTTPS SERVERADDR:PORT";
}
``SERVERADDR`` and ``PORT`` is the hostname/address and port of the
machine nghttpx is running. Please note that Chrome requires valid
2013-08-03 12:44:13 +02:00
certificate for secure proxy.
2013-07-27 14:56:46 +02:00
Then run Chrome with the following arguments::
2013-07-27 14:56:46 +02:00
$ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
2014-03-30 12:09:21 +02:00
With ``--http2-bridge``, it accepts HTTP/2, SPDY and HTTP/1.1
connections and communicates with backend in HTTP/2::
2013-07-27 14:56:46 +02:00
2014-03-30 12:09:21 +02:00
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web or HTTP/2 Proxy etc
2013-08-03 12:44:13 +02:00
(e.g., nghttpx -s)
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
With ``--client-proxy`` option, it works as forward proxy and expects
2014-03-30 12:09:21 +02:00
that the backend is HTTP/2 proxy::
2013-07-27 14:56:46 +02:00
2014-03-30 12:09:21 +02:00
Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> HTTP/2 Proxy
2013-08-03 12:44:13 +02:00
[forward proxy] (e.g., nghttpx -s)
2013-07-27 14:56:46 +02:00
The ``Client`` needs to be configured to use nghttpx as forward
2014-03-30 12:09:21 +02:00
proxy. The frontend HTTP/1.1 connection can be upgraded to HTTP/2
2013-08-03 12:44:13 +02:00
through HTTP Upgrade. With the above configuration, one can use
2014-03-30 12:09:21 +02:00
HTTP/1.1 client to access and test their HTTP/2 servers.
2013-07-27 14:56:46 +02:00
With ``--client`` option, it works as reverse proxy and expects that
2014-03-30 12:09:21 +02:00
the backend is HTTP/2 Web server::
2013-07-27 14:56:46 +02:00
2014-03-30 12:09:21 +02:00
Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web Server
2013-08-03 12:44:13 +02:00
[reverse proxy]
2014-03-30 12:09:21 +02:00
The frontend HTTP/1.1 connection can be upgraded to HTTP/2
2013-08-03 12:44:13 +02:00
through HTTP Upgrade.
2013-07-27 14:56:46 +02:00
2014-03-30 12:09:21 +02:00
For the operation modes which talk to the backend in HTTP/2 over
2014-04-08 16:12:02 +02:00
SSL/TLS, the backend connections can be tunneled through HTTP proxy.
The proxy is specified using ``--backend-http-proxy-uri`` option. The
following figure illustrates the example of ``--http2-bridge`` and
``--backend-http-proxy-uri`` options to talk to the outside HTTP/2
proxy through HTTP proxy::
2013-07-27 14:56:46 +02:00
2014-03-30 12:09:21 +02:00
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --
2013-07-27 14:56:46 +02:00
2014-03-30 12:09:21 +02:00
--===================---> HTTP/2 Proxy
2013-07-27 14:56:46 +02:00
(HTTP proxy tunnel) (e.g., nghttpx -s)
2013-10-28 16:22:18 +01:00
2014-03-02 15:44:43 +01:00
Benchmarking tool
-----------------
The ``h2load`` program is a benchmarking tool for HTTP/2 and SPDY.
The SPDY support is enabled if the program was built with spdylay
2014-04-08 16:12:02 +02:00
library. The UI of ``h2load`` is heavily inspired by ``weighttp``
(https://github.com/lighttpd/weighttp). The typical usage is as
follows::
2014-03-02 15:44:43 +01:00
$ src/h2load -n1000 -c10 -m10 https://127.0.0.1:8443/
starting benchmark...
progress: 10% done
progress: 20% done
progress: 30% done
progress: 40% done
progress: 50% done
progress: 60% done
progress: 70% done
progress: 80% done
progress: 90% done
progress: 100% done
finished in 0 sec, 152 millisec and 152 microsec, 6572 req/s, 749 kbytes/s
requests: 1000 total, 1000 started, 1000 done, 0 succeeded, 1000 failed, 0 errored
status codes: 0 2xx, 0 3xx, 1000 4xx, 0 5xx
traffic: 141100 bytes total, 840 bytes headers, 116000 bytes data
The above example issued total 1000 requests, using 10 concurrent
clients (thus 10 HTTP/2 sessions), and maximum 10 streams per client.
2014-03-03 17:16:15 +01:00
With ``-t`` option, ``h2load`` will use multiple native threads to
avoid saturating single core on client side.
2014-03-02 15:44:43 +01:00
.. warning::
2014-04-08 16:12:02 +02:00
**Don't use this tool against publicly available servers.** That is
considered a DOS attack. Please only use against your private
servers.
2014-03-02 15:44:43 +01:00
2014-01-10 13:53:48 +01:00
HPACK tools
-----------
2013-10-28 16:22:18 +01:00
2014-04-08 16:12:02 +02:00
The ``src`` directory contains HPACK tools. The ``deflatehd`` is a
command-line header compression tool. The ``inflatehd`` is
2014-01-10 13:53:48 +01:00
command-line header decompression tool. Both tools read input from
2014-04-08 16:12:02 +02:00
stdin and write output to stdout. The errors are written to stderr.
They take JSON as input and output. We use (mostly) same JSON data
format described at https://github.com/http2jp/hpack-test-case
2013-10-28 16:22:18 +01:00
deflatehd - header compressor
+++++++++++++++++++++++++++++
2014-01-11 09:06:26 +01:00
The ``deflatehd`` reads JSON data or HTTP/1-style header fields from
stdin and outputs compressed header block in JSON.
2013-10-28 16:22:18 +01:00
2014-04-08 16:12:02 +02:00
For the JSON input, the root JSON object must include ``cases`` key.
Its value has to include the sequence of input header set. They share
the same compression context and are processed in the order they
2014-02-15 12:00:51 +01:00
appear. Each item in the sequence is a JSON object and it must
2014-04-08 16:12:02 +02:00
include ``headers`` key. Its value is an array of a JSON object,
2014-02-15 12:00:51 +01:00
which includes exactly one name/value pair.
2013-10-28 16:22:18 +01:00
2014-01-11 09:13:24 +01:00
Example:
.. code-block:: json
2013-10-28 16:22:18 +01:00
2014-01-11 09:06:26 +01:00
{
"cases":
[
{
"headers": [
{ ":method": "GET" },
{ ":path": "/" }
]
},
{
"headers": [
{ ":method": "POST" },
{ ":path": "/" }
]
}
]
}
2013-10-28 16:22:18 +01:00
With ``-t`` option, the program can accept more familiar HTTP/1 style
2014-04-08 16:12:02 +02:00
header field block. Each header set is delimited by empty line:
2013-10-28 16:22:18 +01:00
Example::
:method: GET
:scheme: https
:path: /
:method: POST
user-agent: nghttp2
2014-04-08 16:12:02 +02:00
The output is JSON object. It should include ``cases`` key and its
2014-01-11 09:06:26 +01:00
value is an array of JSON object, which has at least following keys:
2013-10-28 16:22:18 +01:00
seq
The index of header set in the input.
2014-01-11 09:06:26 +01:00
input_length
2013-10-28 16:22:18 +01:00
The sum of length of name/value pair in the input.
2014-01-11 09:06:26 +01:00
output_length
2013-10-28 16:22:18 +01:00
The length of compressed header block.
2014-01-11 09:06:26 +01:00
percentage_of_original_size
``input_length`` / ``output_length`` * 100
2013-10-28 16:22:18 +01:00
2014-01-11 09:06:26 +01:00
wire
2013-10-28 16:22:18 +01:00
The compressed header block in hex string.
2014-01-11 09:06:26 +01:00
headers
The input header set.
header_table_size
The header table size adjusted before deflating header set.
2014-01-11 09:06:26 +01:00
2014-01-11 09:13:24 +01:00
Examples:
.. code-block:: json
2013-10-28 16:22:18 +01:00
2014-01-11 09:06:26 +01:00
{
"cases":
[
{
"seq": 0,
"input_length": 66,
"output_length": 20,
"percentage_of_original_size": 30.303030303030305,
"wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
"headers": [
{
":authority": "example.org"
},
{
":method": "GET"
},
{
":path": "/"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096
}
,
{
"seq": 1,
"input_length": 74,
"output_length": 10,
"percentage_of_original_size": 13.513513513513514,
"wire": "88448504252dd5918485",
"headers": [
{
":authority": "example.org"
},
{
":method": "POST"
},
{
":path": "/account"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096
}
]
}
The output can be used as the input for ``inflatehd`` and
``deflatehd``.
With ``-d`` option, the extra ``header_table`` key is added and its
associated value includes the state of dynamic header table after the
2014-04-08 16:12:02 +02:00
corresponding header set was processed. The value includes at least
the following keys:
2013-10-28 16:22:18 +01:00
entries
2014-04-08 16:12:02 +02:00
The entry in the header table. If ``referenced`` is ``true``, it
is in the reference set. The ``size`` includes the overhead (32
bytes). The ``index`` corresponds to the index of header table.
2013-10-28 16:22:18 +01:00
The ``name`` is the header field name and the ``value`` is the
2014-04-08 16:12:02 +02:00
header field value.
2013-10-28 16:22:18 +01:00
size
The sum of the spaces entries occupied, this includes the
entry overhead.
2014-01-11 09:06:26 +01:00
max_size
2013-10-28 16:22:18 +01:00
The maximum header table size.
2014-01-11 09:06:26 +01:00
deflate_size
The sum of the spaces entries occupied within
``max_deflate_size``.
2013-10-28 16:22:18 +01:00
2014-01-11 09:06:26 +01:00
max_deflate_size
2014-04-08 16:12:02 +02:00
The maximum header table size encoder uses. This can be smaller
than ``max_size``. In this case, encoder only uses up to first
``max_deflate_size`` buffer. Since the header table size is still
2014-01-11 09:06:26 +01:00
``max_size``, the encoder has to keep track of entries ouside the
``max_deflate_size`` but inside the ``max_size`` and make sure
that they are no longer referenced.
2013-10-28 16:22:18 +01:00
2014-01-11 09:13:24 +01:00
Example:
.. code-block:: json
2013-10-28 16:22:18 +01:00
2014-01-11 09:06:26 +01:00
{
"cases":
[
{
"seq": 0,
"input_length": 66,
"output_length": 20,
"percentage_of_original_size": 30.303030303030305,
"wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
"headers": [
{
":authority": "example.org"
},
{
":method": "GET"
},
{
":path": "/"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096,
"header_table": {
"entries": [
{
"index": 1,
"name": "user-agent",
"value": "nghttp2",
"referenced": true,
"size": 49
},
{
"index": 2,
"name": ":scheme",
"value": "https",
"referenced": true,
"size": 44
},
{
"index": 3,
"name": ":path",
"value": "/",
"referenced": true,
"size": 38
},
{
"index": 4,
"name": ":method",
"value": "GET",
"referenced": true,
"size": 42
},
{
"index": 5,
"name": ":authority",
"value": "example.org",
"referenced": true,
"size": 53
}
],
"size": 226,
"max_size": 4096,
"deflate_size": 226,
"max_deflate_size": 4096
}
}
,
{
"seq": 1,
"input_length": 74,
"output_length": 10,
"percentage_of_original_size": 13.513513513513514,
"wire": "88448504252dd5918485",
"headers": [
{
":authority": "example.org"
},
{
":method": "POST"
},
{
":path": "/account"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096,
"header_table": {
"entries": [
{
"index": 1,
"name": ":method",
"value": "POST",
"referenced": true,
"size": 43
},
{
"index": 2,
"name": "user-agent",
"value": "nghttp2",
"referenced": true,
"size": 49
},
{
"index": 3,
"name": ":scheme",
"value": "https",
"referenced": true,
"size": 44
},
{
"index": 4,
"name": ":path",
"value": "/",
"referenced": false,
"size": 38
},
{
"index": 5,
"name": ":method",
"value": "GET",
"referenced": false,
"size": 42
},
{
"index": 6,
"name": ":authority",
"value": "example.org",
"referenced": true,
"size": 53
}
],
"size": 269,
"max_size": 4096,
"deflate_size": 269,
"max_deflate_size": 4096
}
}
]
}
2013-10-28 16:22:18 +01:00
inflatehd - header decompressor
+++++++++++++++++++++++++++++++
2014-01-11 09:06:26 +01:00
The ``inflatehd`` reads JSON data from stdin and outputs decompressed
name/value pairs in JSON.
2013-10-28 16:22:18 +01:00
2014-04-08 16:12:02 +02:00
The root JSON object must include ``cases`` key. Its value has to
include the sequence of compressed header block. They share the same
compression context and are processed in the order they appear. Each
2014-02-15 12:00:51 +01:00
item in the sequence is a JSON object and it must have at least
2014-04-08 16:12:02 +02:00
``wire`` key. Its value is a compressed header block in hex string.
2013-10-28 16:22:18 +01:00
2014-01-11 09:13:24 +01:00
Example:
.. code-block:: json
2013-10-28 16:22:18 +01:00
2014-01-11 09:06:26 +01:00
{
"cases":
[
{ "wire": "8285" },
{ "wire": "8583" }
]
}
2013-10-28 16:22:18 +01:00
2014-04-08 16:12:02 +02:00
The output is JSON object. It should include ``cases`` key and its
2014-01-11 09:06:26 +01:00
value is an array of JSON object, which has at least following keys:
2013-10-28 16:22:18 +01:00
seq
The index of header set in the input.
headers
2014-02-15 12:00:51 +01:00
The JSON array includes decompressed name/value pairs.
2014-01-11 09:06:26 +01:00
wire
The compressed header block in hex string.
header_table_size
The header table size adjusted before inflating compressed header
2014-01-11 09:06:26 +01:00
block.
2013-10-28 16:22:18 +01:00
2014-01-11 09:13:24 +01:00
Example:
.. code-block:: json
2013-10-28 16:22:18 +01:00
2014-01-11 09:06:26 +01:00
{
"cases":
[
{
"seq": 0,
"wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
"headers": [
{
":authority": "example.org"
},
{
":method": "GET"
},
{
":path": "/"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096
}
,
{
"seq": 1,
"wire": "88448504252dd5918485",
"headers": [
{
":method": "POST"
},
{
":path": "/account"
},
{
"user-agent": "nghttp2"
},
{
":scheme": "https"
},
{
":authority": "example.org"
}
],
"header_table_size": 4096
}
]
}
The output can be used as the input for ``deflatehd`` and
``inflatehd``.
With ``-d`` option, the extra ``header_table`` key is added and its
associated value includes the state of dynamic header table after the
2014-04-08 16:12:02 +02:00
corresponding header set was processed. The format is the same as
2013-10-28 16:22:18 +01:00
``deflatehd``.
Python bindings
---------------
2014-04-08 16:12:02 +02:00
This ``python`` directory contains nghttp2 Python bindings. The
bindings currently provide HPACK compressor and decompressor classes
and HTTP/2 server.
The extension module is called ``nghttp2``.
``make`` will build the bindings and target Python version is
2014-04-08 16:12:02 +02:00
determined by configure script. If the detected Python version is not
what you expect, specify a path to Python executable in ``PYTHON``
variable as an argument to configure script (e.g., ``./configure
PYTHON=/usr/bin/python3.3``).
The following example code illustrates basic usage of HPACK compressor
2014-01-10 18:02:53 +01:00
and decompressor in Python:
.. code-block:: python
import binascii
import nghttp2
2014-02-16 07:30:46 +01:00
deflater = nghttp2.HDDeflater()
inflater = nghttp2.HDInflater()
data = deflater.deflate([(b'foo', b'bar'),
2014-01-11 09:06:26 +01:00
(b'baz', b'buz')])
print(binascii.b2a_hex(data))
hdrs = inflater.inflate(data)
print(hdrs)
2014-02-24 17:46:38 +01:00
The ``nghttp2.HTTP2Server`` class builds on top of the asyncio event
2014-04-08 16:12:02 +02:00
loop. On construction, *RequestHandlerClass* must be given, which
must be a subclass of ``nghttp2.BaseRequestHandler`` class.
2014-02-24 17:46:38 +01:00
2014-04-08 16:12:02 +02:00
The ``BaseRequestHandler`` class is used to handle the HTTP/2 stream.
By default, it does nothing. It must be subclassed to handle each
event callback method.
2014-02-24 17:46:38 +01:00
2014-04-08 16:12:02 +02:00
The first callback method invoked is ``on_headers()``. It is called
when HEADERS frame, which includes request header fields, has arrived.
2014-02-24 17:46:38 +01:00
If request has request body, ``on_data(data)`` is invoked for each
chunk of received data.
When whole request is received, ``on_request_done()`` is invoked.
When stream is closed, ``on_close(error_code)`` is called.
2014-04-08 16:12:02 +02:00
The application can send response using ``send_response()`` method.
It can be used in ``on_headers()``, ``on_data()`` or
2014-02-24 17:46:38 +01:00
``on_request_done()``.
2014-04-08 16:12:02 +02:00
The application can push resource using ``push()`` method. It must be
2014-02-24 17:46:38 +01:00
used before ``send_response()`` call.
The following instance variables are available:
client_address
Contains a tuple of the form (host, port) referring to the
client's address.
stream_id
Stream ID of this stream.
2014-02-24 17:46:38 +01:00
scheme
2014-04-08 16:12:02 +02:00
Scheme of the request URI. This is a value of :scheme header
field.
2014-02-24 17:46:38 +01:00
method
2014-04-08 16:12:02 +02:00
Method of this stream. This is a value of :method header field.
2014-02-24 17:46:38 +01:00
host
This is a value of :authority or host header field.
path
This is a value of :path header field.
The following example illustrates the HTTP2Server and
BaseRequestHandler usage:
.. code-block:: python
#!/usr/bin/env python
import io, ssl
import nghttp2
class Handler(nghttp2.BaseRequestHandler):
def on_headers(self):
self.push(path='/css/bootstrap.css',
2014-02-25 13:25:51 +01:00
request_headers = [('content-length', '3')],
2014-02-24 17:46:38 +01:00
status=200,
body='foo')
self.push(path='/js/bootstrap.js',
method='GET',
2014-02-25 13:25:51 +01:00
request_headers = [('content-length', '10')],
2014-02-24 17:46:38 +01:00
status=200,
body='foobarbuzz')
self.send_response(status=200,
2014-02-25 13:25:51 +01:00
headers = [('content-type', 'text/plain')],
2014-02-24 17:46:38 +01:00
body=io.BytesIO(b'nghttp2-python FTW'))
ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
ctx.options = ssl.OP_ALL | ssl.OP_NO_SSLv2
ctx.load_cert_chain('server.crt', 'server.key')
# give None to ssl to make the server non-SSL/TLS
server = nghttp2.HTTP2Server(('127.0.0.1', 8443), Handler, ssl=ctx)
server.serve_forever()