README.rst

   1 nghttp2 - HTTP/2 C Library
   2 ==========================
   3
   4 This is an implementation of Hypertext Transfer Protocol version 2
   5 in C.
   6
   7 The framing layer of HTTP/2 is implemented as a form of reusable C
   8 library.  On top of that, we have implemented HTTP/2 client, server
   9 and proxy.  We have also developed load test and benchmarking tool for
  10 HTTP/2 and SPDY.
  11
  12 HPACK encoder and decoder are available as public API.
  13
  14 The experimental high level C++ library is also available.
  15
  16 We have Python binding of this libary, but we have not covered
  17 everything yet.
  18
  19 Development Status
  20 ------------------
  21
  22 We started to implement h2-14
  23 (http://tools.ietf.org/html/draft-ietf-httpbis-http2-14), the header
  24 compression
  25 (http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-09).
  26
  27 The nghttp2 code base was forked from spdylay project.
  28
  29 =========================== =======
  30 HTTP/2 Features             Support
  31 =========================== =======
  32 Core frames handling        Yes
  33 Dependency Tree             Yes
  34 Large header (CONTINUATION) Yes
  35 =========================== =======
  36
  37 Public Test Server
  38 ------------------
  39
  40 The following endpoints are available to try out nghttp2
  41 implementation.
  42
  43 * https://nghttp2.org/ (TLS + ALPN/NPN)
  44
  45   NPN offer ``h2-14``, ``spdy/3.1`` and ``http/1.1``.
  46
  47   This endpoint requires TLSv1.2 for HTTP/2 connection.
  48
  49 * http://nghttp2.org/ (Upgrade / Direct)
  50
  51   ``h2c-14`` and ``http/1.1``.
  52
  53 Requirements
  54 ------------
  55
  56 The following package is required to build the libnghttp2 library:
  57
  58 * pkg-config >= 0.20
  59
  60 To build and run the unit test programs, the following package is
  61 required:
  62
  63 * cunit >= 2.1
  64
  65 To build the documentation, you need to install:
  66
  67 * sphinx (http://sphinx-doc.org/)
  68
  69 To build and run the application programs (``nghttp``, ``nghttpd`` and
  70 ``nghttpx``) in ``src`` directory, the following packages are
  71 required:
  72
  73 * OpenSSL >= 1.0.1
  74 * libev >= 4.15
  75 * zlib >= 1.2.3
  76
  77 ALPN support requires unreleased version OpenSSL >= 1.0.2.
  78
  79 To enable SPDY protocol in the application program ``nghttpx`` and
  80 ``h2load``, the following package is required:
  81
  82 * spdylay >= 1.3.0
  83
  84 To enable ``-a`` option (getting linked assets from the downloaded
  85 resource) in ``nghttp``, the following package is required:
  86
  87 * libxml2 >= 2.7.7
  88
  89 The HPACK tools require the following package:
  90
  91 * jansson >= 2.5
  92
  93 To build sources under examples directory, libevent is required:
  94
  95 * libevent-openssl >= 2.0.8
  96
  97 To mitigate heap fragmentation in long running server programs
  98 (``nghttpd`` and ``nghttpx``), jemalloc is recommended:
  99
 100 * jemalloc
 101
 102 libnghttp2_asio C++ library requires the following packages:
 103
 104 * libboost-dev >= 1.54.0
 105 * libboost-thread-dev >= 1.54.0
 106
 107 The Python bindings require the following packages:
 108
 109 * cython >= 0.19
 110 * python >= 2.7
 111
 112 If you are using Ubuntu 14.04 LTS, you need the following packages
 113 installed::
 114
 115     apt-get install make binutils autoconf  automake autotools-dev libtool pkg-config zlib1g-dev libcunit1-dev libssl-dev libxml2-dev libev-dev libevent-dev libjansson-dev libjemalloc-dev cython python3.4-dev
 116
 117 spdylay is not packaged in Ubuntu, so you need to build it yourself:
 118 http://tatsuhiro-t.github.io/spdylay/
 119
 120 Build from git
 121 --------------
 122
 123 Building from git is easy, but please be sure that at least autoconf 2.68 is
 124 used::
 125
 126     $ autoreconf -i
 127     $ automake
 128     $ autoconf
 129     $ ./configure
 130     $ make
 131
 132 To compile source code, gcc >= 4.8.3 or clang >= 3.4 is required.
 133
 134 .. note::
 135
 136    Mac OS X users may need ``--disable-threads`` configure option to
 137    disable multi threading in nghttpd, nghttpx and h2load to prevent
 138    them from crashing.  Patch is welcome to make multi threading work
 139    on Mac OS X platform.
 140
 141 Building documentation
 142 ----------------------
 143
 144 .. note::
 145
 146    Documentation is still incomplete.
 147
 148 To build documentation, run::
 149
 150     $ make html
 151
 152 The documents will be generated under ``doc/manual/html/``.
 153
 154 The generated documents will not be installed with ``make install``.
 155
 156 The online documentation is available at
 157 https://nghttp2.org/documentation/
 158
 159 Unit tests
 160 ----------
 161
 162 Unit tests are done by simply running `make check`.
 163
 164 Integration tests
 165 -----------------
 166
 167 We have the integration tests for nghttpx proxy server.  The tests are
 168 written in `Go programming language <http://golang.org/>`_ and uses
 169 its testing framework.  We depend on the following libraries:
 170
 171 * https://github.com/bradfitz/http2
 172 * https://github.com/tatsuhiro-t/go-nghttp2
 173 * https://golang.org/x/net/spdy
 174
 175 To download the above packages, after settings ``GOPATH``, run the
 176 following command under ``integration-tests`` directory::
 177
 178     $ make itprep
 179
 180 To run the tests, run the following command under
 181 ``integration-tests`` directory::
 182
 183     $ make it
 184
 185 Inside the tests, we use port 3009 to run test subject server.
 186
 187 Client, Server and Proxy programs
 188 ---------------------------------
 189
 190 The src directory contains HTTP/2 client, server and proxy programs.
 191
 192 nghttp - client
 193 +++++++++++++++
 194
 195 ``nghttp`` is a HTTP/2 client.  It can connect to the HTTP/2 server
 196 with prior knowledge, HTTP Upgrade and NPN/ALPN TLS extension.
 197
 198 It has verbose output mode for framing information.  Here is sample
 199 output from ``nghttp`` client::
 200
 201     $ nghttp -nv https://nghttp2.org
 202     [  0.033][NPN] server offers:
 203               * h2-14
 204               * spdy/3.1
 205               * http/1.1
 206     The negotiated protocol: h2-14
 207     [  0.068] send SETTINGS frame <length=15, flags=0x00, stream_id=0>
 208               (niv=3)
 209               [SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
 210               [SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
 211               [SETTINGS_COMPRESS_DATA(5):1]
 212     [  0.068] send HEADERS frame <length=46, flags=0x05, stream_id=1>
 213               ; END_STREAM | END_HEADERS
 214               (padlen=0)
 215               ; Open new stream
 216               :authority: nghttp2.org
 217               :method: GET
 218               :path: /
 219               :scheme: https
 220               accept: */*
 221               accept-encoding: gzip, deflate
 222               user-agent: nghttp2/0.4.0-DEV
 223     [  0.068] recv SETTINGS frame <length=10, flags=0x00, stream_id=0>
 224               (niv=2)
 225               [SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
 226               [SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
 227     [  0.068] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
 228               ; ACK
 229               (niv=0)
 230     [  0.079] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
 231               ; ACK
 232               (niv=0)
 233     [  0.080] (stream_id=1, noind=0) :status: 200
 234     [  0.080] (stream_id=1, noind=0) accept-ranges: bytes
 235     [  0.080] (stream_id=1, noind=0) age: 15
 236     [  0.080] (stream_id=1, noind=0) content-length: 40243
 237     [  0.080] (stream_id=1, noind=0) content-type: text/html
 238     [  0.080] (stream_id=1, noind=0) date: Wed, 14 May 2014 15:14:30 GMT
 239     [  0.080] (stream_id=1, noind=0) etag: "535d0eea-9d33"
 240     [  0.080] (stream_id=1, noind=0) last-modified: Sun, 27 Apr 2014 14:06:34 GMT
 241     [  0.080] (stream_id=1, noind=0) server: nginx/1.4.6 (Ubuntu)
 242     [  0.080] (stream_id=1, noind=0) x-varnish: 2114900538 2114900537
 243     [  0.080] (stream_id=1, noind=0) via: 1.1 varnish, 1.1 nghttpx
 244     [  0.080] (stream_id=1, noind=0) strict-transport-security: max-age=31536000
 245     [  0.080] recv HEADERS frame <length=162, flags=0x04, stream_id=1>
 246               ; END_HEADERS
 247               (padlen=0)
 248               ; First response header
 249     [  0.080] recv DATA frame <length=3786, flags=0x00, stream_id=1>
 250     [  0.080] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 251     [  0.081] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 252     [  0.093] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 253     [  0.093] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 254     [  0.094] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 255     [  0.094] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 256     [  0.094] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 257     [  0.096] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 258     [  0.096] send WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=0>
 259               (window_size_increment=36554)
 260     [  0.096] send WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=1>
 261               (window_size_increment=36554)
 262     [  0.108] recv DATA frame <length=3689, flags=0x00, stream_id=1>
 263     [  0.108] recv DATA frame <length=0, flags=0x01, stream_id=1>
 264               ; END_STREAM
 265     [  0.108] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
 266               (last_stream_id=0, error_code=NO_ERROR(0), opaque_data(0)=[])
 267
 268 The HTTP Upgrade is performed like this::
 269
 270     $ nghttp -nvu http://nghttp2.org
 271     [  0.013] HTTP Upgrade request
 272     GET / HTTP/1.1
 273     Host: nghttp2.org
 274     Connection: Upgrade, HTTP2-Settings
 275     Upgrade: h2c-14
 276     HTTP2-Settings: AwAAAGQEAAD__wUAAAAB
 277     Accept: */*
 278     User-Agent: nghttp2/0.4.0-DEV
 279
 280
 281     [  0.024] HTTP Upgrade response
 282     HTTP/1.1 101 Switching Protocols
 283     Connection: Upgrade
 284     Upgrade: h2c-14
 285
 286
 287     [  0.024] HTTP Upgrade success
 288     [  0.024] send SETTINGS frame <length=15, flags=0x00, stream_id=0>
 289               (niv=3)
 290               [SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
 291               [SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
 292               [SETTINGS_COMPRESS_DATA(5):1]
 293     [  0.024] recv SETTINGS frame <length=10, flags=0x00, stream_id=0>
 294               (niv=2)
 295               [SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
 296               [SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
 297     [  0.024] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
 298               ; ACK
 299               (niv=0)
 300     [  0.024] (stream_id=1, noind=0) :status: 200
 301     [  0.024] (stream_id=1, noind=0) accept-ranges: bytes
 302     [  0.024] (stream_id=1, noind=0) age: 10
 303     [  0.024] (stream_id=1, noind=0) content-length: 40243
 304     [  0.024] (stream_id=1, noind=0) content-type: text/html
 305     [  0.024] (stream_id=1, noind=0) date: Wed, 14 May 2014 15:16:34 GMT
 306     [  0.024] (stream_id=1, noind=0) etag: "535d0eea-9d33"
 307     [  0.024] (stream_id=1, noind=0) last-modified: Sun, 27 Apr 2014 14:06:34 GMT
 308     [  0.024] (stream_id=1, noind=0) server: nginx/1.4.6 (Ubuntu)
 309     [  0.024] (stream_id=1, noind=0) x-varnish: 2114900541 2114900540
 310     [  0.024] (stream_id=1, noind=0) via: 1.1 varnish, 1.1 nghttpx
 311     [  0.024] recv HEADERS frame <length=148, flags=0x04, stream_id=1>
 312               ; END_HEADERS
 313               (padlen=0)
 314               ; First response header
 315     [  0.024] recv DATA frame <length=3786, flags=0x00, stream_id=1>
 316     [  0.025] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 317     [  0.031] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 318     [  0.031] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 319     [  0.032] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 320     [  0.032] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 321     [  0.033] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 322     [  0.033] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 323     [  0.033] send WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=0>
 324               (window_size_increment=33164)
 325     [  0.033] send WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=1>
 326               (window_size_increment=33164)
 327     [  0.038] recv DATA frame <length=4096, flags=0x00, stream_id=1>
 328     [  0.038] recv DATA frame <length=3689, flags=0x00, stream_id=1>
 329     [  0.038] recv DATA frame <length=0, flags=0x01, stream_id=1>
 330               ; END_STREAM
 331     [  0.038] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
 332               ; ACK
 333               (niv=0)
 334     [  0.038] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
 335               (last_stream_id=0, error_code=NO_ERROR(0), opaque_data(0)=[])
 336
 337 With ``-s`` option, ``nghttp`` prints out some timing information for
 338 requests, sorted by completion time::
 339
 340     $ nghttp -nas https://nghttp2.org/
 341     ***** Statistics *****
 342
 343     Request timing:
 344       complete: relative time from protocol handshake to stream close
 345        request: relative   time  from   protocol   handshake  to   request
 346                 transmission
 347        process: time for request and response
 348           code: HTTP status code
 349            URI: request URI
 350
 351     sorted by 'complete'
 352
 353     complete  request   process  code request path
 354      +17.37ms    +104us  17.27ms  200 /
 355      +17.50ms   +8.15ms   9.35ms  200 /javascripts/octopress.js
 356      +22.06ms   +8.15ms  13.91ms  200 /javascripts/modernizr-2.0.js
 357      +27.07ms   +8.15ms  18.92ms  200 /stylesheets/screen.css
 358      +98.57ms  +17.55ms  81.02ms  200 /images/posts/with-pri-blog.png
 359     +104.70ms  +17.55ms  87.15ms  200 /images/posts/without-pri-blog.png
 360
 361 With ``-r`` option, ``nghttp`` writes more detailed timing data to
 362 given file in HAR format.
 363
 364 nghttpd - server
 365 ++++++++++++++++
 366
 367 ``nghttpd`` is a multi-threaded static web server.
 368
 369 By default, it uses SSL/TLS connection.  Use ``--no-tls`` option to
 370 disable it.
 371
 372 ``nghttpd`` only accepts the HTTP/2 connection via NPN/ALPN or direct
 373 HTTP/2 connection.  No HTTP Upgrade is supported.
 374
 375 ``-p`` option allows users to configure server push.
 376
 377 Just like ``nghttp``, it has verbose output mode for framing
 378 information.  Here is sample output from ``nghttpd`` server::
 379
 380     $ nghttpd --no-tls -v 8080
 381     IPv4: listen on port 8080
 382     IPv6: listen on port 8080
 383     [id=1] [ 15.921] send SETTINGS frame <length=10, flags=0x00, stream_id=0>
 384               (niv=2)
 385               [SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
 386               [SETTINGS_COMPRESS_DATA(5):1]
 387     [id=1] [ 15.921] recv SETTINGS frame <length=15, flags=0x00, stream_id=0>
 388               (niv=3)
 389               [SETTINGS_MAX_CONCURRENT_STREAMS(3):100]
 390               [SETTINGS_INITIAL_WINDOW_SIZE(4):65535]
 391               [SETTINGS_COMPRESS_DATA(5):1]
 392     [id=1] [ 15.921] (stream_id=1, noind=0) :authority: localhost:8080
 393     [id=1] [ 15.921] (stream_id=1, noind=0) :method: GET
 394     [id=1] [ 15.921] (stream_id=1, noind=0) :path: /
 395     [id=1] [ 15.921] (stream_id=1, noind=0) :scheme: http
 396     [id=1] [ 15.921] (stream_id=1, noind=0) accept: */*
 397     [id=1] [ 15.921] (stream_id=1, noind=0) accept-encoding: gzip, deflate
 398     [id=1] [ 15.921] (stream_id=1, noind=0) user-agent: nghttp2/0.4.0-DEV
 399     [id=1] [ 15.921] recv HEADERS frame <length=48, flags=0x05, stream_id=1>
 400               ; END_STREAM | END_HEADERS
 401               (padlen=0)
 402               ; Open new stream
 403     [id=1] [ 15.921] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
 404               ; ACK
 405               (niv=0)
 406     [id=1] [ 15.921] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
 407               ; ACK
 408               (niv=0)
 409     [id=1] [ 15.921] send HEADERS frame <length=82, flags=0x04, stream_id=1>
 410               ; END_HEADERS
 411               (padlen=0)
 412               ; First response header
 413               :status: 200
 414               cache-control: max-age=3600
 415               content-length: 612
 416               date: Wed, 14 May 2014 15:19:03 GMT
 417               last-modified: Sat, 08 Mar 2014 16:04:06 GMT
 418               server: nghttpd nghttp2/0.4.0-DEV
 419     [id=1] [ 15.922] send DATA frame <length=381, flags=0x20, stream_id=1>
 420               ; COMPRESSED
 421     [id=1] [ 15.922] send DATA frame <length=0, flags=0x01, stream_id=1>
 422               ; END_STREAM
 423     [id=1] [ 15.922] stream_id=1 closed
 424     [id=1] [ 15.922] recv GOAWAY frame <length=8, flags=0x00, stream_id=0>
 425               (last_stream_id=0, error_code=NO_ERROR(0), opaque_data(0)=[])
 426     [id=1] [ 15.922] closed
 427
 428 nghttpx - proxy
 429 +++++++++++++++
 430
 431 ``nghttpx`` is a multi-threaded reverse proxy for ``h2-14``, SPDY and
 432 HTTP/1.1 and powers nghttp2.org site.  It has several operation modes:
 433
 434 ================== ============================ ============== =============
 435 Mode option        Frontend                     Backend        Note
 436 ================== ============================ ============== =============
 437 default mode       HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1       Reverse proxy
 438 ``--http2-proxy``  HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1       SPDY proxy
 439 ``--http2-bridge`` HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/2 (TLS)
 440 ``--client``       HTTP/2, HTTP/1.1             HTTP/2 (TLS)
 441 ``--client-proxy`` HTTP/2, HTTP/1.1             HTTP/2 (TLS)   Forward proxy
 442 ================== ============================ ============== =============
 443
 444 The interesting mode at the moment is the default mode.  It works like
 445 a reverse proxy and listens for ``h2-14``, SPDY and HTTP/1.1 and can
 446 be deployed SSL/TLS terminator for existing web server.
 447
 448 The default mode, ``--http2-proxy`` and ``--http2-bridge`` modes use
 449 SSL/TLS in the frontend connection by default.  To disable SSL/TLS,
 450 use ``--frontend-no-tls`` option.  If that option is used, SPDY is
 451 disabled in the frontend and incoming HTTP/1.1 connection can be
 452 upgraded to HTTP/2 through HTTP Upgrade.
 453
 454 The ``--http2-bridge``, ``--client`` and ``--client-proxy`` modes use
 455 SSL/TLS in the backend connection by deafult.  To disable SSL/TLS, use
 456 ``--backend-no-tls`` option.
 457
 458 ``nghttpx`` supports configuration file.  See ``--conf`` option and
 459 sample configuration file ``nghttpx.conf.sample``.
 460
 461 ``nghttpx`` does not support server push.
 462
 463 In the default mode, (without any of ``--http2-proxy``,
 464 ``--http2-bridge``, ``--client-proxy`` and ``--client`` options),
 465 ``nghttpx`` works as reverse proxy to the backend server::
 466
 467     Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Web Server
 468                                           [reverse proxy]
 469
 470 With ``--http2-proxy`` option, it works as so called secure proxy (aka
 471 SPDY proxy)::
 472
 473     Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy
 474                                            [secure proxy]          (e.g., Squid, ATS)
 475
 476 The ``Client`` in the above needs to be configured to use
 477 ``nghttpx`` as secure proxy.
 478
 479 At the time of this writing, Chrome is the only browser which supports
 480 secure proxy.  The one way to configure Chrome to use secure proxy is
 481 create proxy.pac script like this:
 482
 483 .. code-block:: javascript
 484
 485     function FindProxyForURL(url, host) {
 486         return "HTTPS SERVERADDR:PORT";
 487     }
 488
 489 ``SERVERADDR`` and ``PORT`` is the hostname/address and port of the
 490 machine nghttpx is running.  Please note that Chrome requires valid
 491 certificate for secure proxy.
 492
 493 Then run Chrome with the following arguments::
 494
 495     $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
 496
 497 With ``--http2-bridge``, it accepts HTTP/2, SPDY and HTTP/1.1
 498 connections and communicates with backend in HTTP/2::
 499
 500     Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web or HTTP/2 Proxy etc
 501                                                                          (e.g., nghttpx -s)
 502
 503 With ``--client-proxy`` option, it works as forward proxy and expects
 504 that the backend is HTTP/2 proxy::
 505
 506     Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> HTTP/2 Proxy
 507                                      [forward proxy]               (e.g., nghttpx -s)
 508
 509 The ``Client`` needs to be configured to use nghttpx as forward
 510 proxy.  The frontend HTTP/1.1 connection can be upgraded to HTTP/2
 511 through HTTP Upgrade.  With the above configuration, one can use
 512 HTTP/1.1 client to access and test their HTTP/2 servers.
 513
 514 With ``--client`` option, it works as reverse proxy and expects that
 515 the backend is HTTP/2 Web server::
 516
 517     Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web Server
 518                                     [reverse proxy]
 519
 520 The frontend HTTP/1.1 connection can be upgraded to HTTP/2
 521 through HTTP Upgrade.
 522
 523 For the operation modes which talk to the backend in HTTP/2 over
 524 SSL/TLS, the backend connections can be tunneled through HTTP proxy.
 525 The proxy is specified using ``--backend-http-proxy-uri`` option.  The
 526 following figure illustrates the example of ``--http2-bridge`` and
 527 ``--backend-http-proxy-uri`` options to talk to the outside HTTP/2
 528 proxy through HTTP proxy::
 529
 530     Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --
 531
 532             --===================---> HTTP/2 Proxy
 533               (HTTP proxy tunnel)     (e.g., nghttpx -s)
 534
 535 Benchmarking tool
 536 -----------------
 537
 538 The ``h2load`` program is a benchmarking tool for HTTP/2 and SPDY.
 539 The SPDY support is enabled if the program was built with spdylay
 540 library.  The UI of ``h2load`` is heavily inspired by ``weighttp``
 541 (https://github.com/lighttpd/weighttp).  The typical usage is as
 542 follows::
 543
 544     $ h2load -n100000 -c100 -m100 https://localhost:8443/
 545     starting benchmark...
 546     spawning thread #0: 100 concurrent clients, 100000 total requests
 547     Protocol: TLSv1.2
 548     Cipher: ECDHE-RSA-AES128-GCM-SHA256
 549     progress: 10% done
 550     progress: 20% done
 551     progress: 30% done
 552     progress: 40% done
 553     progress: 50% done
 554     progress: 60% done
 555     progress: 70% done
 556     progress: 80% done
 557     progress: 90% done
 558     progress: 100% done
 559
 560     finished in 7.10s, 14092 req/s, 55.67MB/s
 561     requests: 100000 total, 100000 started, 100000 done, 100000 succeeded, 0 failed, 0 errored
 562     status codes: 100000 2xx, 0 3xx, 0 4xx, 0 5xx
 563     traffic: 414200800 bytes total, 2723100 bytes headers, 409600000 bytes data
 564                          min         max         mean         sd        +/- sd
 565     time for request:   283.86ms       1.46s    659.70ms    150.87ms    84.68%
 566
 567 The above example issued total 100000 requests, using 100 concurrent
 568 clients (in other words, 100 HTTP/2 sessions), and maximum 100 streams
 569 per client.  With ``-t`` option, ``h2load`` will use multiple native
 570 threads to avoid saturating single core on client side.
 571
 572 .. warning::
 573
 574    **Don't use this tool against publicly available servers.** That is
 575    considered a DOS attack.  Please only use against your private
 576    servers.
 577
 578 HPACK tools
 579 -----------
 580
 581 The ``src`` directory contains HPACK tools.  The ``deflatehd`` is a
 582 command-line header compression tool.  The ``inflatehd`` is
 583 command-line header decompression tool.  Both tools read input from
 584 stdin and write output to stdout.  The errors are written to stderr.
 585 They take JSON as input and output.  We use (mostly) same JSON data
 586 format described at https://github.com/http2jp/hpack-test-case
 587
 588 deflatehd - header compressor
 589 +++++++++++++++++++++++++++++
 590
 591 The ``deflatehd`` reads JSON data or HTTP/1-style header fields from
 592 stdin and outputs compressed header block in JSON.
 593
 594 For the JSON input, the root JSON object must include ``cases`` key.
 595 Its value has to include the sequence of input header set.  They share
 596 the same compression context and are processed in the order they
 597 appear.  Each item in the sequence is a JSON object and it must
 598 include ``headers`` key.  Its value is an array of a JSON object,
 599 which includes exactly one name/value pair.
 600
 601 Example:
 602
 603 .. code-block:: json
 604
 605     {
 606       "cases":
 607       [
 608         {
 609           "headers": [
 610             { ":method": "GET" },
 611             { ":path": "/" }
 612           ]
 613         },
 614         {
 615           "headers": [
 616             { ":method": "POST" },
 617             { ":path": "/" }
 618           ]
 619         }
 620       ]
 621     }
 622
 623
 624 With ``-t`` option, the program can accept more familiar HTTP/1 style
 625 header field block.  Each header set is delimited by empty line:
 626
 627 Example::
 628
 629     :method: GET
 630     :scheme: https
 631     :path: /
 632
 633     :method: POST
 634     user-agent: nghttp2
 635
 636 The output is JSON object.  It should include ``cases`` key and its
 637 value is an array of JSON object, which has at least following keys:
 638
 639 seq
 640     The index of header set in the input.
 641
 642 input_length
 643     The sum of length of name/value pair in the input.
 644
 645 output_length
 646     The length of compressed header block.
 647
 648 percentage_of_original_size
 649     ``input_length`` / ``output_length`` * 100
 650
 651 wire
 652     The compressed header block in hex string.
 653
 654 headers
 655     The input header set.
 656
 657 header_table_size
 658     The header table size adjusted before deflating header set.
 659
 660 Examples:
 661
 662 .. code-block:: json
 663
 664     {
 665       "cases":
 666       [
 667         {
 668           "seq": 0,
 669           "input_length": 66,
 670           "output_length": 20,
 671           "percentage_of_original_size": 30.303030303030305,
 672           "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
 673           "headers": [
 674             {
 675               ":authority": "example.org"
 676             },
 677             {
 678               ":method": "GET"
 679             },
 680             {
 681               ":path": "/"
 682             },
 683             {
 684               ":scheme": "https"
 685             },
 686             {
 687               "user-agent": "nghttp2"
 688             }
 689           ],
 690           "header_table_size": 4096
 691         }
 692         ,
 693         {
 694           "seq": 1,
 695           "input_length": 74,
 696           "output_length": 10,
 697           "percentage_of_original_size": 13.513513513513514,
 698           "wire": "88448504252dd5918485",
 699           "headers": [
 700             {
 701               ":authority": "example.org"
 702             },
 703             {
 704               ":method": "POST"
 705             },
 706             {
 707               ":path": "/account"
 708             },
 709             {
 710               ":scheme": "https"
 711             },
 712             {
 713               "user-agent": "nghttp2"
 714             }
 715           ],
 716           "header_table_size": 4096
 717         }
 718       ]
 719     }
 720
 721
 722 The output can be used as the input for ``inflatehd`` and
 723 ``deflatehd``.
 724
 725 With ``-d`` option, the extra ``header_table`` key is added and its
 726 associated value includes the state of dynamic header table after the
 727 corresponding header set was processed.  The value includes at least
 728 the following keys:
 729
 730 entries
 731     The entry in the header table.  If ``referenced`` is ``true``, it
 732     is in the reference set.  The ``size`` includes the overhead (32
 733     bytes).  The ``index`` corresponds to the index of header table.
 734     The ``name`` is the header field name and the ``value`` is the
 735     header field value.
 736
 737 size
 738     The sum of the spaces entries occupied, this includes the
 739     entry overhead.
 740
 741 max_size
 742     The maximum header table size.
 743
 744 deflate_size
 745     The sum of the spaces entries occupied within
 746     ``max_deflate_size``.
 747
 748 max_deflate_size
 749     The maximum header table size encoder uses.  This can be smaller
 750     than ``max_size``.  In this case, encoder only uses up to first
 751     ``max_deflate_size`` buffer.  Since the header table size is still
 752     ``max_size``, the encoder has to keep track of entries ouside the
 753     ``max_deflate_size`` but inside the ``max_size`` and make sure
 754     that they are no longer referenced.
 755
 756 Example:
 757
 758 .. code-block:: json
 759
 760     {
 761       "cases":
 762       [
 763         {
 764           "seq": 0,
 765           "input_length": 66,
 766           "output_length": 20,
 767           "percentage_of_original_size": 30.303030303030305,
 768           "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
 769           "headers": [
 770             {
 771               ":authority": "example.org"
 772             },
 773             {
 774               ":method": "GET"
 775             },
 776             {
 777               ":path": "/"
 778             },
 779             {
 780               ":scheme": "https"
 781             },
 782             {
 783               "user-agent": "nghttp2"
 784             }
 785           ],
 786           "header_table_size": 4096,
 787           "header_table": {
 788             "entries": [
 789               {
 790                 "index": 1,
 791                 "name": "user-agent",
 792                 "value": "nghttp2",
 793                 "referenced": true,
 794                 "size": 49
 795               },
 796               {
 797                 "index": 2,
 798                 "name": ":scheme",
 799                 "value": "https",
 800                 "referenced": true,
 801                 "size": 44
 802               },
 803               {
 804                 "index": 3,
 805                 "name": ":path",
 806                 "value": "/",
 807                 "referenced": true,
 808                 "size": 38
 809               },
 810               {
 811                 "index": 4,
 812                 "name": ":method",
 813                 "value": "GET",
 814                 "referenced": true,
 815                 "size": 42
 816               },
 817               {
 818                 "index": 5,
 819                 "name": ":authority",
 820                 "value": "example.org",
 821                 "referenced": true,
 822                 "size": 53
 823               }
 824             ],
 825             "size": 226,
 826             "max_size": 4096,
 827             "deflate_size": 226,
 828             "max_deflate_size": 4096
 829           }
 830         }
 831         ,
 832         {
 833           "seq": 1,
 834           "input_length": 74,
 835           "output_length": 10,
 836           "percentage_of_original_size": 13.513513513513514,
 837           "wire": "88448504252dd5918485",
 838           "headers": [
 839             {
 840               ":authority": "example.org"
 841             },
 842             {
 843               ":method": "POST"
 844             },
 845             {
 846               ":path": "/account"
 847             },
 848             {
 849               ":scheme": "https"
 850             },
 851             {
 852               "user-agent": "nghttp2"
 853             }
 854           ],
 855           "header_table_size": 4096,
 856           "header_table": {
 857             "entries": [
 858               {
 859                 "index": 1,
 860                 "name": ":method",
 861                 "value": "POST",
 862                 "referenced": true,
 863                 "size": 43
 864               },
 865               {
 866                 "index": 2,
 867                 "name": "user-agent",
 868                 "value": "nghttp2",
 869                 "referenced": true,
 870                 "size": 49
 871               },
 872               {
 873                 "index": 3,
 874                 "name": ":scheme",
 875                 "value": "https",
 876                 "referenced": true,
 877                 "size": 44
 878               },
 879               {
 880                 "index": 4,
 881                 "name": ":path",
 882                 "value": "/",
 883                 "referenced": false,
 884                 "size": 38
 885               },
 886               {
 887                 "index": 5,
 888                 "name": ":method",
 889                 "value": "GET",
 890                 "referenced": false,
 891                 "size": 42
 892               },
 893               {
 894                 "index": 6,
 895                 "name": ":authority",
 896                 "value": "example.org",
 897                 "referenced": true,
 898                 "size": 53
 899               }
 900             ],
 901             "size": 269,
 902             "max_size": 4096,
 903             "deflate_size": 269,
 904             "max_deflate_size": 4096
 905           }
 906         }
 907       ]
 908     }
 909
 910 inflatehd - header decompressor
 911 +++++++++++++++++++++++++++++++
 912
 913 The ``inflatehd`` reads JSON data from stdin and outputs decompressed
 914 name/value pairs in JSON.
 915
 916 The root JSON object must include ``cases`` key.  Its value has to
 917 include the sequence of compressed header block.  They share the same
 918 compression context and are processed in the order they appear.  Each
 919 item in the sequence is a JSON object and it must have at least
 920 ``wire`` key.  Its value is a compressed header block in hex string.
 921
 922 Example:
 923
 924 .. code-block:: json
 925
 926     {
 927       "cases":
 928       [
 929         { "wire": "8285" },
 930         { "wire": "8583" }
 931       ]
 932     }
 933
 934 The output is JSON object.  It should include ``cases`` key and its
 935 value is an array of JSON object, which has at least following keys:
 936
 937 seq
 938     The index of header set in the input.
 939
 940 headers
 941     The JSON array includes decompressed name/value pairs.
 942
 943 wire
 944     The compressed header block in hex string.
 945
 946 header_table_size
 947     The header table size adjusted before inflating compressed header
 948     block.
 949
 950 Example:
 951
 952 .. code-block:: json
 953
 954     {
 955       "cases":
 956       [
 957         {
 958           "seq": 0,
 959           "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
 960           "headers": [
 961             {
 962               ":authority": "example.org"
 963             },
 964             {
 965               ":method": "GET"
 966             },
 967             {
 968               ":path": "/"
 969             },
 970             {
 971               ":scheme": "https"
 972             },
 973             {
 974               "user-agent": "nghttp2"
 975             }
 976           ],
 977           "header_table_size": 4096
 978         }
 979         ,
 980         {
 981           "seq": 1,
 982           "wire": "88448504252dd5918485",
 983           "headers": [
 984             {
 985               ":method": "POST"
 986             },
 987             {
 988               ":path": "/account"
 989             },
 990             {
 991               "user-agent": "nghttp2"
 992             },
 993             {
 994               ":scheme": "https"
 995             },
 996             {
 997               ":authority": "example.org"
 998             }
 999           ],
1000           "header_table_size": 4096
1001         }
1002       ]
1003     }
1004
1005 The output can be used as the input for ``deflatehd`` and
1006 ``inflatehd``.
1007
1008 With ``-d`` option, the extra ``header_table`` key is added and its
1009 associated value includes the state of dynamic header table after the
1010 corresponding header set was processed.  The format is the same as
1011 ``deflatehd``.
1012
1013 libnghttp2_asio: High level HTTP/2 C++ library
1014 ----------------------------------------------
1015
1016 libnghttp2_asio is C++ library built on top of libnghttp2 and provides
1017 high level abstraction API to build HTTP/2 applications.  It depends
1018 on Boost::ASIO library and OpenSSL.  Currently libnghttp2_asio
1019 provides server side API.
1020
1021 libnghttp2_asio is not built by default.  Use ``--enable-asio-lib``
1022 configure flag to build libnghttp2_asio.  The required Boost libraries
1023 are:
1024
1025 * Boost::Asio
1026 * Boost::System
1027 * Boost::Thread
1028
1029 Server API is designed to build HTTP/2 server very easily to utilize
1030 C++11 anonymous function and closure.  The bare minimum example of
1031 HTTP/2 server looks like this:
1032
1033 .. code-block:: cpp
1034
1035     #include <nghttp2/asio_http2.h>
1036
1037     using namespace nghttp2::asio_http2;
1038     using namespace nghttp2::asio_http2::server;
1039
1040     int main(int argc, char *argv[]) {
1041       http2 server;
1042
1043       server.listen("*", 3000, [](const std::shared_ptr<request> &req,
1044                                   const std::shared_ptr<response> &res) {
1045         res->write_head(200);
1046         res->end("hello, world");
1047       });
1048     }
1049
1050 For more details, see the documentation of libnghttp2_asio.
1051
1052 Python bindings
1053 ---------------
1054
1055 This ``python`` directory contains nghttp2 Python bindings.  The
1056 bindings currently provide HPACK compressor and decompressor classes
1057 and HTTP/2 server.
1058
1059 The extension module is called ``nghttp2``.
1060
1061 ``make`` will build the bindings and target Python version is
1062 determined by configure script.  If the detected Python version is not
1063 what you expect, specify a path to Python executable in ``PYTHON``
1064 variable as an argument to configure script (e.g., ``./configure
1065 PYTHON=/usr/bin/python3.4``).
1066
1067 The following example code illustrates basic usage of HPACK compressor
1068 and decompressor in Python:
1069
1070 .. code-block:: python
1071
1072     import binascii
1073     import nghttp2
1074
1075     deflater = nghttp2.HDDeflater()
1076     inflater = nghttp2.HDInflater()
1077
1078     data = deflater.deflate([(b'foo', b'bar'),
1079                              (b'baz', b'buz')])
1080     print(binascii.b2a_hex(data))
1081
1082     hdrs = inflater.inflate(data)
1083     print(hdrs)
1084
1085 The ``nghttp2.HTTP2Server`` class builds on top of the asyncio event
1086 loop.  On construction, *RequestHandlerClass* must be given, which
1087 must be a subclass of ``nghttp2.BaseRequestHandler`` class.
1088
1089 The ``BaseRequestHandler`` class is used to handle the HTTP/2 stream.
1090 By default, it does nothing.  It must be subclassed to handle each
1091 event callback method.
1092
1093 The first callback method invoked is ``on_headers()``.  It is called
1094 when HEADERS frame, which includes request header fields, has arrived.
1095
1096 If request has request body, ``on_data(data)`` is invoked for each
1097 chunk of received data.
1098
1099 When whole request is received, ``on_request_done()`` is invoked.
1100
1101 When stream is closed, ``on_close(error_code)`` is called.
1102
1103 The application can send response using ``send_response()`` method.
1104 It can be used in ``on_headers()``, ``on_data()`` or
1105 ``on_request_done()``.
1106
1107 The application can push resource using ``push()`` method.  It must be
1108 used before ``send_response()`` call.
1109
1110 The following instance variables are available:
1111
1112 client_address
1113     Contains a tuple of the form (host, port) referring to the
1114     client's address.
1115
1116 stream_id
1117     Stream ID of this stream.
1118
1119 scheme
1120     Scheme of the request URI.  This is a value of :scheme header
1121     field.
1122
1123 method
1124     Method of this stream.  This is a value of :method header field.
1125
1126 host
1127     This is a value of :authority or host header field.
1128
1129 path
1130     This is a value of :path header field.
1131
1132 The following example illustrates the HTTP2Server and
1133 BaseRequestHandler usage:
1134
1135 .. code-block:: python
1136
1137     #!/usr/bin/env python
1138
1139     import io, ssl
1140     import nghttp2
1141
1142     class Handler(nghttp2.BaseRequestHandler):
1143
1144         def on_headers(self):
1145             self.push(path='/css/bootstrap.css',
1146                       request_headers = [('content-length', '3')],
1147                       status=200,
1148                       body='foo')
1149
1150             self.push(path='/js/bootstrap.js',
1151                       method='GET',
1152                       request_headers = [('content-length', '10')],
1153                       status=200,
1154                       body='foobarbuzz')
1155
1156             self.send_response(status=200,
1157                                headers = [('content-type', 'text/plain')],
1158                                body=io.BytesIO(b'nghttp2-python FTW'))
1159
1160     ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
1161     ctx.options = ssl.OP_ALL | ssl.OP_NO_SSLv2
1162     ctx.load_cert_chain('server.crt', 'server.key')
1163
1164     # give None to ssl to make the server non-SSL/TLS
1165     server = nghttp2.HTTP2Server(('127.0.0.1', 8443), Handler, ssl=ctx)
1166     server.serve_forever()
1167
1168 Contribution
1169 ------------
1170
1171 [This text was composed based on 1.2. License section of curl/libcurl
1172 project.]
1173
1174 When contributing with code, you agree to put your changes and new
1175 code under the same license nghttp2 is already using unless stated and
1176 agreed otherwise.
1177
1178 When changing existing source code, you do not alter the copyright of
1179 the original file(s).  The copyright will still be owned by the
1180 original creator(s) or those who have been assigned copyright by the
1181 original author(s).
1182
1183 By submitting a patch to the nghttp2 project, you are assumed to have
1184 the right to the code and to be allowed by your employer or whatever
1185 to hand over that patch/code to us.  We will credit you for your
1186 changes as far as possible, to give credit but also to keep a trace
1187 back to who made what changes.  Please always provide us with your
1188 full real name when contributing!
1189
1190 See `Contribution Guidelines
1191 <https://nghttp2.org/documentation/contribute.html>`_ for more
1192 details.