nghttp2/README.rst

420 lines
14 KiB
ReStructuredText
Raw Normal View History

2013-07-12 17:19:03 +02:00
nghttp2 - HTTP/2.0 C Library
============================
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
version 2.0.
2012-09-12 15:37:05 +02:00
2013-10-26 18:07:34 +02:00
There are command-line header compression test tools in hdtest
directory. Check out deflatehd and inflatehd commands.
2012-04-25 14:25:51 +02:00
Development Status
------------------
2012-03-26 16:46:02 +02:00
2013-10-27 15:16:49 +01:00
We started to implement HTTP-draft-07/2.0
(http://tools.ietf.org/html/draft-ietf-httpbis-http2-07) and the
2013-08-22 20:45:55 +02:00
header compression
2013-10-27 15:16:49 +01: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
2013-10-27 15:16:49 +01:00
========================== =================
Features HTTP-draft-07/2.0
========================== =================
:authority Done
HPACK-draft-04 Done
SETTINGS_HEADER_TABLE_SIZE Done
SETTINGS_ENABLE_PUSH
FRAME_SIZE_ERROR Done
2013-08-09 17:57:49 +02:00
Header Continuation
ALPN
2013-10-27 15:16: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
implementation. These endpoints supports ``HTTP-draft-06/2.0`` and
the earlier draft versions are not supporeted.
2013-08-10 12:06:33 +02:00
2013-08-30 17:50:09 +02:00
* https://106.186.112.116 (TLS + NPN)
NPN offers ``HTTP-draft-06/2.0``, ``spdy/3``, ``spdy/2`` and
``http/1.1``.
2013-08-10 12:06:33 +02:00
Note: certificate is self-signed and a browser will show alert
2013-08-30 17:50:09 +02:00
* http://106.186.112.116 (Upgrade + Direct)
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
To enable SPDY protocol in the application program ``nghttpx``, the
following packages are required:
* spdylay >= 1.0.0
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
2013-10-27 08:23:24 +01:00
The header compression test tools in hdtest directory require the
following package:
* jansson >= 2.5
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
2013-07-27 14:56:46 +02:00
spdylay is not packaged in Ubuntu, so you need to build it yourself:
http://spdylay.sourceforge.net/
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
---------------------------------
The src directory contains HTTP/2.0 client, server and proxy programs.
nghttp - client
+++++++++++++++
2013-08-04 11:29:31 +02:00
``nghttp`` is a HTTP/2.0 client. It can connect to the HTTP/2.0 server
with prior knowledge, HTTP Upgrade and NPN TLS extension.
2013-07-27 14:56:46 +02:00
It has verbose output mode for framing information. Here is sample
output from ``nghttp`` client::
2013-08-22 20:45:55 +02:00
$ src/nghttp -vn https://localhost:8443
2013-10-27 15:29:54 +01:00
[ 0.003] NPN select next protocol: the remote server offers:
* HTTP-draft-07/2.0
* spdy/3
* spdy/2
* http/1.1
NPN selected the protocol: HTTP-draft-07/2.0
[ 0.005] send SETTINGS frame <length=16, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(4):100]
[SETTINGS_INITIAL_WINDOW_SIZE(7):65535]
[ 0.006] send HEADERS frame <length=47, flags=0x05, stream_id=1>
; END_STREAM | END_HEADERS
; Open new stream
:authority: localhost:8443
:method: GET
:path: /
:scheme: https
accept: */*
accept-encoding: gzip, deflate
user-agent: nghttp2/0.1.0-DEV
[ 0.006] recv SETTINGS frame <length=16, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(4):100]
[SETTINGS_INITIAL_WINDOW_SIZE(7):65535]
[ 0.006] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[ 0.006] recv WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=0>
(window_size_increment=1000000007)
[ 0.006] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[ 0.006] recv HEADERS frame <length=132, flags=0x04, stream_id=1>
; END_HEADERS
; First response header
:status: 200
accept-ranges: bytes
content-encoding: gzip
content-length: 146
content-type: text/html
date: Sun, 27 Oct 2013 14:23:54 GMT
etag: "b1-4e5535a027780-gzip"
last-modified: Sun, 01 Sep 2013 14:34:22 GMT
server: Apache/2.4.6 (Debian)
vary: Accept-Encoding
via: 1.1 nghttpx
[ 0.006] recv DATA frame <length=146, flags=0x00, stream_id=1>
[ 0.006] recv DATA frame <length=0, flags=0x01, stream_id=1>
; END_STREAM
[ 0.007] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
(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::
2013-08-22 20:45:55 +02:00
$ src/nghttp -vnu 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
2013-10-27 15:29:54 +01:00
Upgrade: HTTP-draft-07/2.0
2013-08-03 12:44:13 +02:00
HTTP2-Settings: AAAABAAAAGQAAAAHAAD__w
Accept: */*
User-Agent: nghttp2/0.1.0-DEV
2013-08-22 20:45:55 +02:00
[ 0.000] HTTP Upgrade response
2013-08-03 12:44:13 +02:00
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
2013-10-27 15:29:54 +01:00
Upgrade: HTTP-draft-07/2.0
2013-08-03 12:44:13 +02:00
2013-10-27 15:29:54 +01:00
[ 0.001] HTTP Upgrade success
2013-08-22 20:45:55 +02:00
[ 0.001] send SETTINGS frame <length=16, flags=0x00, stream_id=0>
2013-10-27 15:29:54 +01:00
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(4):100]
[SETTINGS_INITIAL_WINDOW_SIZE(7):65535]
2013-08-22 20:45:55 +02:00
[ 0.001] recv SETTINGS frame <length=16, flags=0x00, stream_id=0>
2013-10-27 15:29:54 +01:00
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(4):100]
[SETTINGS_INITIAL_WINDOW_SIZE(7):65535]
2013-08-22 20:45:55 +02:00
[ 0.001] recv WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=0>
2013-10-27 15:29:54 +01:00
(window_size_increment=1000000007)
[ 0.001] recv HEADERS frame <length=121, flags=0x04, stream_id=1>
; END_HEADERS
; First response header
:status: 200
accept-ranges: bytes
content-length: 177
content-type: text/html
date: Sun, 27 Oct 2013 14:26:04 GMT
etag: "b1-4e5535a027780"
last-modified: Sun, 01 Sep 2013 14:34:22 GMT
server: Apache/2.4.6 (Debian)
vary: Accept-Encoding
via: 1.1 nghttpx
[ 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>
2013-10-27 15:29:54 +01:00
; END_STREAM
[ 0.001] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
2013-08-22 20:45:55 +02:00
[ 0.001] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
2013-10-27 15:29:54 +01:00
(last_stream_id=0, error_code=NO_ERROR(0), opaque_data(0)=[])
[ 0.001] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
2013-08-03 12:44:13 +02:00
2013-07-27 14:56:46 +02:00
nghttpd - server
++++++++++++++++
``nghttpd`` is static web server. It is single threaded and
multiplexes connections using non-blocking socket.
2013-07-27 15:40:44 +02:00
By default, it uses SSL/TLS connection. Use ``--no-tls`` option to
disable it.
2013-08-03 12:44:13 +02:00
``nghttpd`` only accept the HTTP/2.0 connection via NPN or direct
HTTP/2.0 connection. No HTTP Upgrade is supported.
2013-07-27 14:56:46 +02:00
Just like ``nghttp``, it has verbose output mode for framing
information. Here is sample output from ``nghttpd`` server::
2013-08-22 20:45:55 +02:00
$ src/nghttpd --no-tls -v 8080
IPv4: listen on port 8080
IPv6: listen on port 8080
2013-10-27 15:29:54 +01:00
[id=1] [ 1.189] send SETTINGS frame <length=8, flags=0x00, stream_id=0>
(niv=1)
[SETTINGS_MAX_CONCURRENT_STREAMS(4):100]
[id=1] [ 1.191] recv SETTINGS frame <length=16, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(4):100]
[SETTINGS_INITIAL_WINDOW_SIZE(7):65535]
[id=1] [ 1.191] recv HEADERS frame <length=47, flags=0x05, stream_id=1>
; END_STREAM | END_HEADERS
; Open new stream
:authority: localhost:8080
:method: GET
:path: /
:scheme: http
accept: */*
accept-encoding: gzip, deflate
user-agent: nghttp2/0.1.0-DEV
[id=1] [ 1.192] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[id=1] [ 1.192] send HEADERS frame <length=70, flags=0x04, stream_id=1>
; END_HEADERS
; First response header
:status: 404
content-encoding: gzip
content-type: text/html; charset=UTF-8
date: Sun, 27 Oct 2013 14:27:53 GMT
server: nghttpd nghttp2/0.1.0-DEV
[id=1] [ 1.192] send DATA frame <length=117, flags=0x00, stream_id=1>
[id=1] [ 1.192] send DATA frame <length=0, flags=0x01, stream_id=1>
; END_STREAM
[id=1] [ 1.192] stream_id=1 closed
[id=1] [ 1.192] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[id=1] [ 1.192] recv GOAWAY frame <length=8, flags=0x00, stream_id=0>
(last_stream_id=0, error_code=NO_ERROR(0), opaque_data(0)=[])
[id=1] [ 1.192] closed
2013-07-27 14:56:46 +02:00
nghttpx - proxy
+++++++++++++++
The ``nghttpx`` is a multi-threaded reverse proxy for
2013-10-27 15:29:54 +01:00
HTTP-draft-07/2.0, SPDY and HTTP/1.1. It has several operation modes:
2013-08-03 12:44:13 +02:00
================== ============================== ============== =============
Mode option Frontend Backend Note
================== ============================== ============== =============
default mode HTTP/2.0, SPDY, HTTP/1.1 (TLS) HTTP/1.1 Reverse proxy
``--spdy`` HTTP/2.0, SPDY, HTTP/1.1 (TLS) HTTP/1.1 SPDY proxy
``--spdy-bridge`` HTTP/2.0, SPDY, HTTP/1.1 (TLS) HTTP/2.0 (TLS)
``--client`` HTTP/2.0, HTTP/1.1 HTTP/2.0 (TLS)
``--client-proxy`` HTTP/2.0, HTTP/1.1 HTTP/2.0 (TLS) Forward proxy
================== ============================== ============== =============
2013-07-27 14:56:46 +02:00
The interesting mode at the moment is the default mode. It works like
2013-10-27 15:29:54 +01:00
a reverse proxy and listens HTTP-draft-07/2.0, SPDY and HTTP/1.1 and
2013-08-03 12:44:13 +02:00
can be deployed SSL/TLS terminator for existing web server.
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
The default mode, ``--spdy`` and ``--spdy-bridge`` modes use 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.0 through HTTP Upgrade.
The ``--spdy-bridge``, ``--client`` and ``--client-proxy`` modes use
SSL/TLS in the backend connection by deafult. To disable SSL/TLS, use
``--backend-no-tls`` option.
2013-07-27 15:40:44 +02:00
2013-07-27 14:56:46 +02:00
The ``nghttpx`` supports configuration file. See ``--conf`` option and
sample configuration file ``nghttpx.conf.sample``.
The ``nghttpx`` is ported from ``shrpx`` in spdylay project, and it
still has SPDY color in option names. They will be fixed as the
development goes.
2013-08-03 12:44:13 +02:00
In the default mode, (without any of ``--spdy``, ``--spdy-bridge``,
``--client-proxy`` and ``--client`` options), ``nghttpx`` works as
reverse proxy to the backend server::
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
Client <-- (HTTP/2.0, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Web Server
[reverse proxy]
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
With ``--spdy`` option, it works as so called secure proxy (aka SPDY
proxy)::
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
Client <-- (HTTP/2.0, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy
[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
2013-08-03 12:44:13 +02:00
secure proxy. The one way to configure Chrome to use secure proxy is
create proxy.pac script like this::
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::
$ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
2013-08-03 12:44:13 +02:00
With ``--spdy-bridge``, it accepts HTTP/2.0, SPDY and HTTP/1.1
2013-07-27 14:56:46 +02:00
connections and communicates with backend in HTTP/2.0::
2013-08-03 12:44:13 +02:00
Client <-- (HTTP/2.0, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2.0) --> Web or HTTP/2.0 Proxy etc
(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
that the backend is HTTP/2.0 proxy::
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
Client <-- (HTTP/2.0, HTTP/1.1) --> nghttpx <-- (HTTP/2.0) --> HTTP/2.0 Proxy
[forward proxy] (e.g., nghttpx -s)
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
The ``Client`` is needs to be configured to use nghttpx as forward
proxy. The frontend HTTP/1.1 connection can be upgraded to HTTP/2.0
through HTTP Upgrade. With the above configuration, one can use
HTTP/1.1 client to access and test their HTTP/2.0 servers.
2013-07-27 14:56:46 +02:00
With ``--client`` option, it works as reverse proxy and expects that
the backend is HTTP/2.0 Web server::
2013-08-03 12:44:13 +02:00
Client <-- (HTTP/2.0, HTTP/1.1) --> nghttpx <-- (HTTP/2.0) --> Web Server
[reverse proxy]
The frontend HTTP/1.1 connection can be upgraded to HTTP/2.0
through HTTP Upgrade.
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
For the operation modes which talk to the backend in HTTP/2.0 over
SSL/TLS, the backend connections can be tunneled though HTTP
proxy. The proxy is specified using ``--backend-http-proxy-uri``
option. The following figure illustrates the example of
``--spdy-bridge`` and ``--backend-http-proxy-uri`` option to talk to
the outside HTTP/2.0 proxy through HTTP proxy::
2013-07-27 14:56:46 +02:00
2013-08-03 12:44:13 +02:00
Client <-- (HTTP/2.0, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2.0) --
2013-07-27 14:56:46 +02:00
--===================---> HTTP/2.0 Proxy
(HTTP proxy tunnel) (e.g., nghttpx -s)