README.rst

   1 nghttp2 - HTTP/2 C Library
   2 ==========================
   3
   4 This is an implementation of the Hypertext Transfer Protocol version 2
   5 in C.
   6
   7 The framing layer of HTTP/2 is implemented as a reusable C
   8 library.  On top of that, we have implemented an HTTP/2 client, server
   9 and proxy.  We have also developed load test and benchmarking tools for
  10 HTTP/2 and SPDY.
  11
  12 An HPACK encoder and decoder are available as a public API.
  13
  14 An experimental high level C++ library is also available.
  15
  16 We have Python bindings of this library, but we do not have full
  17 code coverage yet.
  18
  19 Development Status
  20 ------------------
  21
  22 We have implemented `RFC 7540 <https://tools.ietf.org/html/rfc7540>`_
  23 HTTP/2 and `RFC 7541 <https://tools.ietf.org/html/rfc7541>`_ HPACK -
  24 Header Compression for HTTP/2
  25
  26 The nghttp2 code base was forked from the spdylay
  27 (https://github.com/tatsuhiro-t/spdylay) project.
  28
  29 Public Test Server
  30 ------------------
  31
  32 The following endpoints are available to try out our nghttp2
  33 implementation.
  34
  35 * https://nghttp2.org/ (TLS + ALPN/NPN)
  36
  37   This endpoint supports ``h2``, ``h2-16``, ``h2-14``, ``spdy/3.1``
  38   and ``http/1.1`` via ALPN/NPN and requires TLSv1.2 for HTTP/2
  39   connection.
  40
  41 * http://nghttp2.org/ (HTTP Upgrade and HTTP/2 Direct)
  42
  43   ``h2c`` and ``http/1.1``.
  44
  45 Requirements
  46 ------------
  47
  48 The following package is required to build the libnghttp2 library:
  49
  50 * pkg-config >= 0.20
  51
  52 To build and run the unit test programs, the following package is
  53 required:
  54
  55 * cunit >= 2.1
  56
  57 To build the documentation, you need to install:
  58
  59 * sphinx (http://sphinx-doc.org/)
  60
  61 To build and run the application programs (``nghttp``, ``nghttpd`` and
  62 ``nghttpx``) in the ``src`` directory, the following packages are
  63 required:
  64
  65 * OpenSSL >= 1.0.1
  66 * libev >= 4.15
  67 * zlib >= 1.2.3
  68
  69 ALPN support requires OpenSSL >= 1.0.2 (released 22 January 2015).
  70
  71 To enable the SPDY protocol in the application program ``nghttpx`` and
  72 ``h2load``, the following package is required:
  73
  74 * spdylay >= 1.3.2
  75
  76 To enable ``-a`` option (getting linked assets from the downloaded
  77 resource) in ``nghttp``, the following package is required:
  78
  79 * libxml2 >= 2.7.7
  80
  81 The HPACK tools require the following package:
  82
  83 * jansson >= 2.5
  84
  85 To build sources under the examples directory, libevent is required:
  86
  87 * libevent-openssl >= 2.0.8
  88
  89 To mitigate heap fragmentation in long running server programs
  90 (``nghttpd`` and ``nghttpx``), jemalloc is recommended:
  91
  92 * jemalloc
  93
  94 libnghttp2_asio C++ library requires the following packages:
  95
  96 * libboost-dev >= 1.54.0
  97 * libboost-thread-dev >= 1.54.0
  98
  99 The Python bindings require the following packages:
 100
 101 * cython >= 0.19
 102 * python >= 2.7
 103
 104 If you are using Ubuntu 14.04 LTS (trusty), run the following to install the needed packages::
 105
 106     sudo apt-get install make binutils autoconf  automake autotools-dev libtool pkg-config \
 107       zlib1g-dev libcunit1-dev libssl-dev libxml2-dev libev-dev libevent-dev libjansson-dev \
 108       libjemalloc-dev cython python3.4-dev
 109
 110 spdylay is not packaged in Ubuntu, so you need to build it yourself:
 111 http://tatsuhiro-t.github.io/spdylay/
 112
 113 Building from git
 114 -----------------
 115
 116 Building from git is easy, but please be sure that at least autoconf 2.68 is
 117 used::
 118
 119     $ autoreconf -i
 120     $ automake
 121     $ autoconf
 122     $ ./configure
 123     $ make
 124
 125 To compile the source code, gcc >= 4.8.3 or clang >= 3.4 is required.
 126
 127 .. note::
 128
 129    Mac OS X users may need the ``--disable-threads`` configure option to
 130    disable multi-threading in nghttpd, nghttpx and h2load to prevent
 131    them from crashing. A patch is welcome to make multi threading work
 132    on Mac OS X platform.
 133
 134 Notes for building on Windows (Mingw/Cygwin)
 135 --------------------------------------------
 136
 137 Under Mingw environment, you can only compile the library, it's
 138 ``libnghttp2-X.dll`` and ``libnghttp2.a``.
 139
 140 If you want to compile the applications(``h2load``, ``nghttp``,
 141 ``nghttpx``, ``nghttpd``), you need to use the Cygwin environment.
 142
 143 Under Cygwin environment, to compile the applications you need to
 144 compile and install the libev first.
 145
 146 Secondly, you need to undefine the macro ``__STRICT_ANSI__``, if you
 147 not, the functions ``fdopen``, ``fileno`` and ``strptime`` will not
 148 available.
 149
 150 the sample command like this::
 151
 152     $ export CFLAGS="-U__STRICT_ANSI__ -I$libev_PREFIX/include -L$libev_PREFIX/lib"
 153     $ export CXXFLAGS=$CFLAGS
 154     $ ./configure
 155     $ make
 156
 157 If you want to compile the applications under ``examples/``, you need
 158 to remove or rename the ``event.h`` from libev's installation, because
 159 it conflicts with libevent's installation.
 160
 161 Building the documentation
 162 --------------------------
 163
 164 .. note::
 165
 166    Documentation is still incomplete.
 167
 168 To build the documentation, run::
 169
 170     $ make html
 171
 172 The documents will be generated under ``doc/manual/html/``.
 173
 174 The generated documents will not be installed with ``make install``.
 175
 176 The online documentation is available at
 177 https://nghttp2.org/documentation/
 178
 179 Unit tests
 180 ----------
 181
 182 Unit tests are done by simply running ``make check``.
 183
 184 Integration tests
 185 -----------------
 186
 187 We have the integration tests for the nghttpx proxy server.  The tests are
 188 written in the `Go programming language <http://golang.org/>`_ and uses
 189 its testing framework.  We depend on the following libraries:
 190
 191 * https://github.com/bradfitz/http2
 192 * https://github.com/tatsuhiro-t/go-nghttp2
 193 * https://golang.org/x/net/spdy
 194
 195 To download the above packages, after settings ``GOPATH``, run the
 196 following command under ``integration-tests`` directory::
 197
 198     $ make itprep
 199
 200 To run the tests, run the following command under
 201 ``integration-tests`` directory::
 202
 203     $ make it
 204
 205 Inside the tests, we use port 3009 to run the test subject server.
 206
 207 Migration from v0.7.15 or earlier
 208 ---------------------------------
 209
 210 nghttp2 v1.0.0 introduced several backward incompatible changes.  In
 211 this section, we describe these changes and how to migrate to v1.0.0.
 212
 213 ALPN protocol ID is now ``h2`` and ``h2c``
 214 ++++++++++++++++++++++++++++++++++++++++++
 215
 216 Previously we announced ``h2-14`` and ``h2c-14``.  v1.0.0 implements
 217 final protocol version, and we changed ALPN ID to ``h2`` and ``h2c``.
 218 The macros ``NGHTTP2_PROTO_VERSION_ID``,
 219 ``NGHTTP2_PROTO_VERSION_ID_LEN``,
 220 ``NGHTTP2_CLEARTEXT_PROTO_VERSION_ID``, and
 221 ``NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN`` have been updated to
 222 reflect this change.
 223
 224 Basically, existing applications do not have to do anything, just
 225 recompiling is enough for this change.
 226
 227 Use word "client magic" where we use "client connection preface"
 228 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 229
 230 We use "client connection preface" to mean first 24 bytes of client
 231 connection preface.  This is technically not correct, since client
 232 connection preface is composed of 24 bytes client magic byte string
 233 followed by SETTINGS frame.  For clarification, we call "client magic"
 234 for this 24 bytes byte string and updated API.
 235
 236 * ``NGHTTP2_CLIENT_CONNECTION_PREFACE`` was replaced with
 237   ``NGHTTP2_CLIENT_MAGIC``.
 238 * ``NGHTTP2_CLIENT_CONNECTION_PREFACE_LEN`` was replaced with
 239   ``NGHTTP2_CLIENT_MAGIC_LEN``.
 240 * ``NGHTTP2_BAD_PREFACE`` was renamed as ``NGHTTP2_BAD_CLIENT_MAGIC``
 241
 242 The alreay deprecated ``NGHTTP2_CLIENT_CONNECTION_HEADER`` and
 243 ``NGHTTP2_CLIENT_CONNECTION_HEADER_LEN`` were removed.
 244
 245 If application uses these macros, just replace old ones with new ones.
 246 Since v1.0.0, client magic is sent by library (see next subsection),
 247 so client application may just remove these macro use.
 248
 249 Client magic is sent by library
 250 +++++++++++++++++++++++++++++++
 251
 252 Previously nghttp2 library did not send client magic, which is first
 253 24 bytes byte string of client connection preface, and client
 254 applications have to send it by themselves.  Since v1.0.0, client
 255 magic is sent by library via first call of ``nghttp2_session_send()``
 256 or ``nghttp2_session_mem_send()``.
 257
 258 The client applications which send client magic must remove the
 259 relevant code.
 260
 261 Remove HTTP Alternative Services (Alt-Svc) related code
 262 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 263
 264 Alt-Svc specification is not finalized yet.  To make our API stable,
 265 we have decided to remove all Alt-Svc related API from nghttp2.
 266
 267 * ``NGHTTP2_EXT_ALTSVC`` was removed.
 268 * ``nghttp2_ext_altsvc`` was removed.
 269
 270 We have already removed the functionality of Alt-Svc in v0.7 series
 271 and they have been essentially noop.  The application using these
 272 macro and struct, remove those lines.
 273
 274 Use nghttp2_error in nghttp2_on_invalid_frame_recv_callback
 275 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 276
 277 Previously ``nghttp2_on_invalid_frame_recv_cb_called`` took the
 278 ``error_code``, defined in ``nghttp2_error_code``, as parameter.  But
 279 they are not detailed enough to debug.  Therefore, we decided to use
 280 more detailed ``nghttp2_error`` values instead.
 281
 282 The application using this callback should update the callback
 283 signature.  If it treats ``error_code`` as HTTP/2 error code, update
 284 the code so that it is treated as ``nghttp2_error``.
 285
 286 Receive client magic by default
 287 +++++++++++++++++++++++++++++++
 288
 289 Previously nghttp2 did not process client magic (24 bytes byte
 290 string).  To make it deal with it, we had to use
 291 ``nghttp2_option_set_recv_client_preface()``.  Since v1.0.0, nghttp2
 292 processes client magic by default and
 293 ``nghttp2_option_set_recv_client_preface()`` was removed.
 294
 295 Some application may want to disable this behaviour, so we added
 296 ``nghttp2_option_set_no_recv_client_magic()`` to achieve this.
 297
 298 The application using ``nghttp2_option_set_recv_client_preface()``
 299 with nonzero value, just remove it.
 300
 301 The application using ``nghttp2_option_set_recv_client_preface()``
 302 with zero value or not using it must use
 303 ``nghttp2_option_set_no_recv_client_magic()`` with nonzero value.
 304
 305 Client, Server and Proxy programs
 306 ---------------------------------
 307
 308 The ``src`` directory contains the HTTP/2 client, server and proxy programs.
 309
 310 nghttp - client
 311 +++++++++++++++
 312
 313 ``nghttp`` is a HTTP/2 client.  It can connect to the HTTP/2 server
 314 with prior knowledge, HTTP Upgrade and NPN/ALPN TLS extension.
 315
 316 It has verbose output mode for framing information.  Here is sample
 317 output from ``nghttp`` client::
 318
 319     $ nghttp -nv https://nghttp2.org
 320     [  0.067] Connected
 321     The negotiated protocol: h2
 322     [  0.135] send SETTINGS frame <length=12, flags=0x00, stream_id=0>
 323               (niv=2)
 324               [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
 325               [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
 326     [  0.135] send PRIORITY frame <length=5, flags=0x00, stream_id=3>
 327               (dep_stream_id=0, weight=201, exclusive=0)
 328     [  0.135] send PRIORITY frame <length=5, flags=0x00, stream_id=5>
 329               (dep_stream_id=0, weight=101, exclusive=0)
 330     [  0.135] send PRIORITY frame <length=5, flags=0x00, stream_id=7>
 331               (dep_stream_id=0, weight=1, exclusive=0)
 332     [  0.135] send PRIORITY frame <length=5, flags=0x00, stream_id=9>
 333               (dep_stream_id=7, weight=1, exclusive=0)
 334     [  0.135] send PRIORITY frame <length=5, flags=0x00, stream_id=11>
 335               (dep_stream_id=3, weight=1, exclusive=0)
 336     [  0.135] send HEADERS frame <length=39, flags=0x25, stream_id=13>
 337               ; END_STREAM | END_HEADERS | PRIORITY
 338               (padlen=0, dep_stream_id=11, weight=16, exclusive=0)
 339               ; Open new stream
 340               :method: GET
 341               :path: /
 342               :scheme: https
 343               :authority: nghttp2.org
 344               accept: */*
 345               accept-encoding: gzip, deflate
 346               user-agent: nghttp2/1.0.0-DEV
 347     [  0.135] recv SETTINGS frame <length=12, flags=0x00, stream_id=0>
 348               (niv=2)
 349               [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
 350               [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
 351     [  0.135] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
 352               ; ACK
 353               (niv=0)
 354     [  0.165] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
 355               ; ACK
 356               (niv=0)
 357     [  0.166] recv (stream_id=13) :status: 200
 358     [  0.166] recv (stream_id=13) date: Fri, 15 May 2015 14:45:22 GMT
 359     [  0.166] recv (stream_id=13) content-type: text/html
 360     [  0.166] recv (stream_id=13) last-modified: Fri, 15 May 2015 14:20:46 GMT
 361     [  0.166] recv (stream_id=13) etag: W/"555600be-1a7f"
 362     [  0.166] recv (stream_id=13) link: </stylesheets/screen.css>; rel=preload; as=stylesheet
 363     [  0.166] recv (stream_id=13) content-encoding: gzip
 364     [  0.166] recv (stream_id=13) server: nghttpx nghttp2/1.0.0-DEV
 365     [  0.166] recv (stream_id=13) via: 1.1 nghttpx
 366     [  0.166] recv (stream_id=13) strict-transport-security: max-age=31536000
 367     [  0.166] recv HEADERS frame <length=166, flags=0x04, stream_id=13>
 368               ; END_HEADERS
 369               (padlen=0)
 370               ; First response header
 371     [  0.166] recv (stream_id=13) :method: GET
 372     [  0.166] recv (stream_id=13) :scheme: https
 373     [  0.166] recv (stream_id=13) :path: /stylesheets/screen.css
 374     [  0.166] recv (stream_id=13) :authority: nghttp2.org
 375     [  0.166] recv (stream_id=13) accept-encoding: gzip, deflate
 376     [  0.166] recv (stream_id=13) user-agent: nghttp2/1.0.0-DEV
 377     [  0.166] recv PUSH_PROMISE frame <length=50, flags=0x04, stream_id=13>
 378               ; END_HEADERS
 379               (padlen=0, promised_stream_id=2)
 380     [  0.166] recv DATA frame <length=2670, flags=0x01, stream_id=13>
 381               ; END_STREAM
 382     [  0.167] recv (stream_id=2) :status: 200
 383     [  0.167] recv (stream_id=2) date: Fri, 15 May 2015 14:45:22 GMT
 384     [  0.167] recv (stream_id=2) content-type: text/css
 385     [  0.167] recv (stream_id=2) last-modified: Fri, 15 May 2015 14:20:46 GMT
 386     [  0.167] recv (stream_id=2) etag: W/"555600be-9845"
 387     [  0.167] recv (stream_id=2) content-encoding: gzip
 388     [  0.167] recv (stream_id=2) server: nghttpx nghttp2/1.0.0-DEV
 389     [  0.167] recv (stream_id=2) via: 1.1 nghttpx
 390     [  0.167] recv (stream_id=2) strict-transport-security: max-age=31536000
 391     [  0.167] recv HEADERS frame <length=32, flags=0x04, stream_id=2>
 392               ; END_HEADERS
 393               (padlen=0)
 394               ; First push response header
 395     [  0.196] recv DATA frame <length=8715, flags=0x01, stream_id=2>
 396               ; END_STREAM
 397     [  0.196] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
 398               (last_stream_id=2, error_code=NO_ERROR(0x00), opaque_data(0)=[])
 399
 400 The HTTP Upgrade is performed like so::
 401
 402     $ nghttp -nvu http://nghttp2.org
 403     [  0.137] Connected
 404     [  0.137] HTTP Upgrade request
 405     GET / HTTP/1.1
 406     Host: nghttp2.org
 407     Connection: Upgrade, HTTP2-Settings
 408     Upgrade: h2c
 409     HTTP2-Settings: AAMAAABkAAQAAP__
 410     Accept: */*
 411     User-Agent: nghttp2/1.0.0-DEV
 412
 413
 414     [  0.156] HTTP Upgrade response
 415     HTTP/1.1 101 Switching Protocols
 416     Connection: Upgrade
 417     Upgrade: h2c
 418
 419
 420     [  0.156] HTTP Upgrade success
 421     [  0.157] send SETTINGS frame <length=12, flags=0x00, stream_id=0>
 422               (niv=2)
 423               [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
 424               [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
 425     [  0.157] send PRIORITY frame <length=5, flags=0x00, stream_id=3>
 426               (dep_stream_id=0, weight=201, exclusive=0)
 427     [  0.157] send PRIORITY frame <length=5, flags=0x00, stream_id=5>
 428               (dep_stream_id=0, weight=101, exclusive=0)
 429     [  0.157] send PRIORITY frame <length=5, flags=0x00, stream_id=7>
 430               (dep_stream_id=0, weight=1, exclusive=0)
 431     [  0.157] send PRIORITY frame <length=5, flags=0x00, stream_id=9>
 432               (dep_stream_id=7, weight=1, exclusive=0)
 433     [  0.157] send PRIORITY frame <length=5, flags=0x00, stream_id=11>
 434               (dep_stream_id=3, weight=1, exclusive=0)
 435     [  0.157] send PRIORITY frame <length=5, flags=0x00, stream_id=1>
 436               (dep_stream_id=11, weight=16, exclusive=0)
 437     [  0.157] recv SETTINGS frame <length=12, flags=0x00, stream_id=0>
 438               (niv=2)
 439               [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
 440               [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
 441     [  0.157] recv (stream_id=1) :status: 200
 442     [  0.157] recv (stream_id=1) date: Fri, 15 May 2015 14:46:08 GMT
 443     [  0.157] recv (stream_id=1) content-type: text/html
 444     [  0.157] recv (stream_id=1) content-length: 6783
 445     [  0.157] recv (stream_id=1) last-modified: Fri, 15 May 2015 14:20:46 GMT
 446     [  0.157] recv (stream_id=1) etag: "555600be-1a7f"
 447     [  0.157] recv (stream_id=1) link: </stylesheets/screen.css>; rel=preload; as=stylesheet
 448     [  0.157] recv (stream_id=1) accept-ranges: bytes
 449     [  0.157] recv (stream_id=1) server: nghttpx nghttp2/1.0.0-DEV
 450     [  0.157] recv (stream_id=1) via: 1.1 nghttpx
 451     [  0.157] recv HEADERS frame <length=157, flags=0x04, stream_id=1>
 452               ; END_HEADERS
 453               (padlen=0)
 454               ; First response header
 455     [  0.157] recv (stream_id=1) :method: GET
 456     [  0.157] recv (stream_id=1) :scheme: http
 457     [  0.157] recv (stream_id=1) :path: /stylesheets/screen.css
 458     [  0.157] recv (stream_id=1) host: nghttp2.org
 459     [  0.157] recv (stream_id=1) user-agent: nghttp2/1.0.0-DEV
 460     [  0.157] recv PUSH_PROMISE frame <length=49, flags=0x04, stream_id=1>
 461               ; END_HEADERS
 462               (padlen=0, promised_stream_id=2)
 463     [  0.157] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
 464               ; ACK
 465               (niv=0)
 466     [  0.161] recv DATA frame <length=6783, flags=0x01, stream_id=1>
 467               ; END_STREAM
 468     [  0.162] recv (stream_id=2) :status: 200
 469     [  0.162] recv (stream_id=2) date: Fri, 15 May 2015 14:46:08 GMT
 470     [  0.162] recv (stream_id=2) content-type: text/css
 471     [  0.162] recv (stream_id=2) content-length: 38981
 472     [  0.162] recv (stream_id=2) last-modified: Fri, 15 May 2015 14:20:46 GMT
 473     [  0.162] recv (stream_id=2) etag: "555600be-9845"
 474     [  0.162] recv (stream_id=2) accept-ranges: bytes
 475     [  0.162] recv (stream_id=2) server: nghttpx nghttp2/1.0.0-DEV
 476     [  0.162] recv (stream_id=2) via: 1.1 nghttpx
 477     [  0.162] recv HEADERS frame <length=36, flags=0x04, stream_id=2>
 478               ; END_HEADERS
 479               (padlen=0)
 480               ; First push response header
 481     [  0.191] recv DATA frame <length=16384, flags=0x00, stream_id=2>
 482     [  0.215] recv DATA frame <length=7952, flags=0x00, stream_id=2>
 483     [  0.215] send WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=0>
 484               (window_size_increment=33322)
 485     [  0.238] send WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=2>
 486               (window_size_increment=33549)
 487     [  0.238] recv DATA frame <length=14645, flags=0x01, stream_id=2>
 488               ; END_STREAM
 489     [  0.238] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
 490               ; ACK
 491               (niv=0)
 492     [  0.238] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
 493               (last_stream_id=2, error_code=NO_ERROR(0x00), opaque_data(0)=[])
 494
 495 Using the ``-s`` option, ``nghttp`` prints out some timing information for
 496 requests, sorted by completion time::
 497
 498     $ nghttp -nas https://nghttp2.org/
 499     ***** Statistics *****
 500
 501     Request timing:
 502       responseEnd: the  time  when  last  byte of  response  was  received
 503                    relative to connectEnd
 504      requestStart: the time  just before  first byte  of request  was sent
 505                    relative  to connectEnd.   If  '*' is  shown, this  was
 506                    pushed by server.
 507           process: responseEnd - requestStart
 508              code: HTTP status code
 509              size: number  of  bytes  received as  response  body  without
 510                    inflation.
 511               URI: request URI
 512
 513     see http://www.w3.org/TR/resource-timing/#processing-model
 514
 515     sorted by 'complete'
 516
 517     id  responseEnd requestStart  process code size request path
 518      13    +37.19ms       +280us  36.91ms  200   2K /
 519       2    +72.65ms *   +36.38ms  36.26ms  200   8K /stylesheets/screen.css
 520      17    +77.43ms     +38.67ms  38.75ms  200   3K /javascripts/octopress.js
 521      15    +78.12ms     +38.66ms  39.46ms  200   3K /javascripts/modernizr-2.0.js
 522
 523 Using the ``-r`` option, ``nghttp`` writes more detailed timing data to
 524 the given file in HAR format.
 525
 526 nghttpd - server
 527 ++++++++++++++++
 528
 529 ``nghttpd`` is a multi-threaded static web server.
 530
 531 By default, it uses SSL/TLS connection.  Use ``--no-tls`` option to
 532 disable it.
 533
 534 ``nghttpd`` only accepts HTTP/2 connections via NPN/ALPN or direct
 535 HTTP/2 connections.  No HTTP Upgrade is supported.
 536
 537 The ``-p`` option allows users to configure server push.
 538
 539 Just like ``nghttp``, it has a verbose output mode for framing
 540 information.  Here is sample output from ``nghttpd``::
 541
 542     $ nghttpd --no-tls -v 8080
 543     IPv4: listen 0.0.0.0:8080
 544     IPv6: listen :::8080
 545     [id=1] [  1.521] send SETTINGS frame <length=6, flags=0x00, stream_id=0>
 546               (niv=1)
 547               [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
 548     [id=1] [  1.521] recv SETTINGS frame <length=12, flags=0x00, stream_id=0>
 549               (niv=2)
 550               [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
 551               [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
 552     [id=1] [  1.521] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
 553               ; ACK
 554               (niv=0)
 555     [id=1] [  1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=3>
 556               (dep_stream_id=0, weight=201, exclusive=0)
 557     [id=1] [  1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=5>
 558               (dep_stream_id=0, weight=101, exclusive=0)
 559     [id=1] [  1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=7>
 560               (dep_stream_id=0, weight=1, exclusive=0)
 561     [id=1] [  1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=9>
 562               (dep_stream_id=7, weight=1, exclusive=0)
 563     [id=1] [  1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=11>
 564               (dep_stream_id=3, weight=1, exclusive=0)
 565     [id=1] [  1.521] recv (stream_id=13) :method: GET
 566     [id=1] [  1.521] recv (stream_id=13) :path: /
 567     [id=1] [  1.521] recv (stream_id=13) :scheme: http
 568     [id=1] [  1.521] recv (stream_id=13) :authority: localhost:8080
 569     [id=1] [  1.521] recv (stream_id=13) accept: */*
 570     [id=1] [  1.521] recv (stream_id=13) accept-encoding: gzip, deflate
 571     [id=1] [  1.521] recv (stream_id=13) user-agent: nghttp2/1.0.0-DEV
 572     [id=1] [  1.521] recv HEADERS frame <length=41, flags=0x25, stream_id=13>
 573               ; END_STREAM | END_HEADERS | PRIORITY
 574               (padlen=0, dep_stream_id=11, weight=16, exclusive=0)
 575               ; Open new stream
 576     [id=1] [  1.521] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
 577               ; ACK
 578               (niv=0)
 579     [id=1] [  1.521] send HEADERS frame <length=86, flags=0x04, stream_id=13>
 580               ; END_HEADERS
 581               (padlen=0)
 582               ; First response header
 583               :status: 200
 584               server: nghttpd nghttp2/1.0.0-DEV
 585               content-length: 10
 586               cache-control: max-age=3600
 587               date: Fri, 15 May 2015 14:49:04 GMT
 588               last-modified: Tue, 30 Sep 2014 12:40:52 GMT
 589     [id=1] [  1.522] send DATA frame <length=10, flags=0x01, stream_id=13>
 590               ; END_STREAM
 591     [id=1] [  1.522] stream_id=13 closed
 592     [id=1] [  1.522] recv GOAWAY frame <length=8, flags=0x00, stream_id=0>
 593               (last_stream_id=0, error_code=NO_ERROR(0x00), opaque_data(0)=[])
 594     [id=1] [  1.522] closed
 595
 596 nghttpx - proxy
 597 +++++++++++++++
 598
 599 ``nghttpx`` is a multi-threaded reverse proxy for HTTP/2, SPDY and
 600 HTTP/1.1, and powers http://nghttp2.org and supports HTTP/2 server
 601 push.
 602
 603 ``nghttpx`` implements `important performance-oriented features
 604 <https://istlsfastyet.com/#server-performance>`_ in TLS, such as
 605 session IDs, session tickets (with automatic key rotation), OCSP
 606 stapling, dynamic record sizing, ALPN/NPN, forward secrecy and SPDY &
 607 HTTP/2.
 608
 609 ``nghttpx`` has several operational modes:
 610
 611 ================== ============================ ============== =============
 612 Mode option        Frontend                     Backend        Note
 613 ================== ============================ ============== =============
 614 default mode       HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1       Reverse proxy
 615 ``--http2-proxy``  HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1       SPDY proxy
 616 ``--http2-bridge`` HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/2 (TLS)
 617 ``--client``       HTTP/2, HTTP/1.1             HTTP/2 (TLS)
 618 ``--client-proxy`` HTTP/2, HTTP/1.1             HTTP/2 (TLS)   Forward proxy
 619 ================== ============================ ============== =============
 620
 621 The interesting mode at the moment is the default mode.  It works like
 622 a reverse proxy and listens for HTTP/2, SPDY and HTTP/1.1 and can be
 623 deployed as a SSL/TLS terminator for existing web server.
 624
 625 The default mode, ``--http2-proxy`` and ``--http2-bridge`` modes use
 626 SSL/TLS in the frontend connection by default.  To disable SSL/TLS,
 627 use the ``--frontend-no-tls`` option.  If that option is used, SPDY is
 628 disabled in the frontend and incoming HTTP/1.1 connections can be
 629 upgraded to HTTP/2 through HTTP Upgrade.
 630
 631 The ``--http2-bridge``, ``--client`` and ``--client-proxy`` modes use
 632 SSL/TLS in the backend connection by default.  To disable SSL/TLS, use
 633 the ``--backend-no-tls`` option.
 634
 635 ``nghttpx`` supports a configuration file.  See the ``--conf`` option and
 636 sample configuration file ``nghttpx.conf.sample``.
 637
 638 In the default mode, (without any of ``--http2-proxy``,
 639 ``--http2-bridge``, ``--client-proxy`` and ``--client`` options),
 640 ``nghttpx`` works as reverse proxy to the backend server::
 641
 642     Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Web Server
 643                                           [reverse proxy]
 644
 645 With the ``--http2-proxy`` option, it works as a so called secure proxy (aka
 646 SPDY proxy)::
 647
 648     Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy
 649                                            [secure proxy]          (e.g., Squid, ATS)
 650
 651 The ``Client`` in the above example needs to be configured to use
 652 ``nghttpx`` as secure proxy.
 653
 654 At the time of this writing, Chrome is the only browser which supports
 655 secure proxy.  One way to configure Chrome to use a secure proxy is
 656 to create a proxy.pac script like this:
 657
 658 .. code-block:: javascript
 659
 660     function FindProxyForURL(url, host) {
 661         return "HTTPS SERVERADDR:PORT";
 662     }
 663
 664 ``SERVERADDR`` and ``PORT`` is the hostname/address and port of the
 665 machine nghttpx is running on.  Please note that Chrome requires a valid
 666 certificate for secure proxy.
 667
 668 Then run Chrome with the following arguments::
 669
 670     $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
 671
 672 With ``--http2-bridge``, it accepts HTTP/2, SPDY and HTTP/1.1
 673 connections and communicates with the backend in HTTP/2::
 674
 675     Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web or HTTP/2 Proxy etc
 676                                                                          (e.g., nghttpx -s)
 677
 678 With ``--client-proxy``, it works as a forward proxy and expects
 679 that the backend is an HTTP/2 proxy::
 680
 681     Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> HTTP/2 Proxy
 682                                      [forward proxy]               (e.g., nghttpx -s)
 683
 684 The ``Client`` needs to be configured to use nghttpx as a forward
 685 proxy.  The frontend HTTP/1.1 connection can be upgraded to HTTP/2
 686 through HTTP Upgrade.  With the above configuration, one can use
 687 HTTP/1.1 client to access and test their HTTP/2 servers.
 688
 689 With ``--client``, it works as a reverse proxy and expects that
 690 the backend is an HTTP/2 Web server::
 691
 692     Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web Server
 693                                     [reverse proxy]
 694
 695 The frontend HTTP/1.1 connection can be upgraded to HTTP/2
 696 through HTTP Upgrade.
 697
 698 For the operation modes which talk to the backend in HTTP/2 over
 699 SSL/TLS, the backend connections can be tunneled through an HTTP proxy.
 700 The proxy is specified using ``--backend-http-proxy-uri``.  The
 701 following figure illustrates the example of the ``--http2-bridge`` and
 702 ``--backend-http-proxy-uri`` options to talk to the outside HTTP/2
 703 proxy through an HTTP proxy::
 704
 705     Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --
 706
 707             --===================---> HTTP/2 Proxy
 708               (HTTP proxy tunnel)     (e.g., nghttpx -s)
 709
 710 Benchmarking tool
 711 -----------------
 712
 713 The ``h2load`` program is a benchmarking tool for HTTP/2 and SPDY.
 714 The SPDY support is enabled if the program was built with the spdylay
 715 library.  The UI of ``h2load`` is heavily inspired by ``weighttp``
 716 (https://github.com/lighttpd/weighttp).  The typical usage is as
 717 follows::
 718
 719     $ h2load -n100000 -c100 -m100 https://localhost:8443/
 720     starting benchmark...
 721     spawning thread #0: 100 concurrent clients, 100000 total requests
 722     Protocol: TLSv1.2
 723     Cipher: ECDHE-RSA-AES128-GCM-SHA256
 724     Server Temp Key: ECDH P-256 256 bits
 725     progress: 10% done
 726     progress: 20% done
 727     progress: 30% done
 728     progress: 40% done
 729     progress: 50% done
 730     progress: 60% done
 731     progress: 70% done
 732     progress: 80% done
 733     progress: 90% done
 734     progress: 100% done
 735
 736     finished in 771.26ms, 129658 req/s, 4.71MB/s
 737     requests: 100000 total, 100000 started, 100000 done, 100000 succeeded, 0 failed, 0 errored
 738     status codes: 100000 2xx, 0 3xx, 0 4xx, 0 5xx
 739     traffic: 3812300 bytes total, 1009900 bytes headers, 1000000 bytes data
 740                          min         max         mean         sd        +/- sd
 741     time for request:    25.12ms    124.55ms     51.07ms     15.36ms    84.87%
 742     time for connect:   208.94ms    254.67ms    241.38ms      7.95ms    63.00%
 743     time to 1st byte:   209.11ms    254.80ms    241.51ms      7.94ms    63.00%
 744
 745 The above example issued total 100,000 requests, using 100 concurrent
 746 clients (in other words, 100 HTTP/2 sessions), and a maximum of 100 streams
 747 per client.  With the ``-t`` option, ``h2load`` will use multiple native
 748 threads to avoid saturating a single core on client side.
 749
 750 .. warning::
 751
 752    **Don't use this tool against publicly available servers.** That is
 753    considered a DOS attack.  Please only use it against your private
 754    servers.
 755
 756 HPACK tools
 757 -----------
 758
 759 The ``src`` directory contains the HPACK tools.  The ``deflatehd`` program is a
 760 command-line header compression tool.  The ``inflatehd`` program is a
 761 command-line header decompression tool.  Both tools read input from
 762 stdin and write output to stdout.  Errors are written to stderr.
 763 They take JSON as input and output.  We  (mostly) use the same JSON data
 764 format described at https://github.com/http2jp/hpack-test-case.
 765
 766 deflatehd - header compressor
 767 +++++++++++++++++++++++++++++
 768
 769 The ``deflatehd`` program reads JSON data or HTTP/1-style header fields from
 770 stdin and outputs compressed header block in JSON.
 771
 772 For the JSON input, the root JSON object must include a ``cases`` key.
 773 Its value has to include the sequence of input header set.  They share
 774 the same compression context and are processed in the order they
 775 appear.  Each item in the sequence is a JSON object and it must
 776 include a ``headers`` key.  Its value is an array of JSON objects,
 777 which includes exactly one name/value pair.
 778
 779 Example:
 780
 781 .. code-block:: json
 782
 783     {
 784       "cases":
 785       [
 786         {
 787           "headers": [
 788             { ":method": "GET" },
 789             { ":path": "/" }
 790           ]
 791         },
 792         {
 793           "headers": [
 794             { ":method": "POST" },
 795             { ":path": "/" }
 796           ]
 797         }
 798       ]
 799     }
 800
 801
 802 With the ``-t`` option, the program can accept more familiar HTTP/1 style
 803 header field blocks.  Each header set is delimited by an empty line:
 804
 805 Example::
 806
 807     :method: GET
 808     :scheme: https
 809     :path: /
 810
 811     :method: POST
 812     user-agent: nghttp2
 813
 814 The output is in JSON object.  It should include a ``cases`` key and its
 815 value is an array of JSON objects, which has at least the following keys:
 816
 817 seq
 818     The index of header set in the input.
 819
 820 input_length
 821     The sum of the length of the name/value pairs in the input.
 822
 823 output_length
 824     The length of the compressed header block.
 825
 826 percentage_of_original_size
 827     ``input_length`` / ``output_length`` * 100
 828
 829 wire
 830     The compressed header block as a hex string.
 831
 832 headers
 833     The input header set.
 834
 835 header_table_size
 836     The header table size adjusted before deflating the header set.
 837
 838 Examples:
 839
 840 .. code-block:: json
 841
 842     {
 843       "cases":
 844       [
 845         {
 846           "seq": 0,
 847           "input_length": 66,
 848           "output_length": 20,
 849           "percentage_of_original_size": 30.303030303030305,
 850           "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
 851           "headers": [
 852             {
 853               ":authority": "example.org"
 854             },
 855             {
 856               ":method": "GET"
 857             },
 858             {
 859               ":path": "/"
 860             },
 861             {
 862               ":scheme": "https"
 863             },
 864             {
 865               "user-agent": "nghttp2"
 866             }
 867           ],
 868           "header_table_size": 4096
 869         }
 870         ,
 871         {
 872           "seq": 1,
 873           "input_length": 74,
 874           "output_length": 10,
 875           "percentage_of_original_size": 13.513513513513514,
 876           "wire": "88448504252dd5918485",
 877           "headers": [
 878             {
 879               ":authority": "example.org"
 880             },
 881             {
 882               ":method": "POST"
 883             },
 884             {
 885               ":path": "/account"
 886             },
 887             {
 888               ":scheme": "https"
 889             },
 890             {
 891               "user-agent": "nghttp2"
 892             }
 893           ],
 894           "header_table_size": 4096
 895         }
 896       ]
 897     }
 898
 899
 900 The output can be used as the input for ``inflatehd`` and
 901 ``deflatehd``.
 902
 903 With the ``-d`` option, the extra ``header_table`` key is added and its
 904 associated value includes the state of dynamic header table after the
 905 corresponding header set was processed.  The value includes at least
 906 the following keys:
 907
 908 entries
 909     The entry in the header table.  If ``referenced`` is ``true``, it
 910     is in the reference set.  The ``size`` includes the overhead (32
 911     bytes).  The ``index`` corresponds to the index of header table.
 912     The ``name`` is the header field name and the ``value`` is the
 913     header field value.
 914
 915 size
 916     The sum of the spaces entries occupied, this includes the
 917     entry overhead.
 918
 919 max_size
 920     The maximum header table size.
 921
 922 deflate_size
 923     The sum of the spaces entries occupied within
 924     ``max_deflate_size``.
 925
 926 max_deflate_size
 927     The maximum header table size the encoder uses.  This can be smaller
 928     than ``max_size``.  In this case, the encoder only uses up to first
 929     ``max_deflate_size`` buffer.  Since the header table size is still
 930     ``max_size``, the encoder has to keep track of entries outside the
 931     ``max_deflate_size`` but inside the ``max_size`` and make sure
 932     that they are no longer referenced.
 933
 934 Example:
 935
 936 .. code-block:: json
 937
 938     {
 939       "cases":
 940       [
 941         {
 942           "seq": 0,
 943           "input_length": 66,
 944           "output_length": 20,
 945           "percentage_of_original_size": 30.303030303030305,
 946           "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
 947           "headers": [
 948             {
 949               ":authority": "example.org"
 950             },
 951             {
 952               ":method": "GET"
 953             },
 954             {
 955               ":path": "/"
 956             },
 957             {
 958               ":scheme": "https"
 959             },
 960             {
 961               "user-agent": "nghttp2"
 962             }
 963           ],
 964           "header_table_size": 4096,
 965           "header_table": {
 966             "entries": [
 967               {
 968                 "index": 1,
 969                 "name": "user-agent",
 970                 "value": "nghttp2",
 971                 "referenced": true,
 972                 "size": 49
 973               },
 974               {
 975                 "index": 2,
 976                 "name": ":scheme",
 977                 "value": "https",
 978                 "referenced": true,
 979                 "size": 44
 980               },
 981               {
 982                 "index": 3,
 983                 "name": ":path",
 984                 "value": "/",
 985                 "referenced": true,
 986                 "size": 38
 987               },
 988               {
 989                 "index": 4,
 990                 "name": ":method",
 991                 "value": "GET",
 992                 "referenced": true,
 993                 "size": 42
 994               },
 995               {
 996                 "index": 5,
 997                 "name": ":authority",
 998                 "value": "example.org",
 999                 "referenced": true,
1000                 "size": 53
1001               }
1002             ],
1003             "size": 226,
1004             "max_size": 4096,
1005             "deflate_size": 226,
1006             "max_deflate_size": 4096
1007           }
1008         }
1009         ,
1010         {
1011           "seq": 1,
1012           "input_length": 74,
1013           "output_length": 10,
1014           "percentage_of_original_size": 13.513513513513514,
1015           "wire": "88448504252dd5918485",
1016           "headers": [
1017             {
1018               ":authority": "example.org"
1019             },
1020             {
1021               ":method": "POST"
1022             },
1023             {
1024               ":path": "/account"
1025             },
1026             {
1027               ":scheme": "https"
1028             },
1029             {
1030               "user-agent": "nghttp2"
1031             }
1032           ],
1033           "header_table_size": 4096,
1034           "header_table": {
1035             "entries": [
1036               {
1037                 "index": 1,
1038                 "name": ":method",
1039                 "value": "POST",
1040                 "referenced": true,
1041                 "size": 43
1042               },
1043               {
1044                 "index": 2,
1045                 "name": "user-agent",
1046                 "value": "nghttp2",
1047                 "referenced": true,
1048                 "size": 49
1049               },
1050               {
1051                 "index": 3,
1052                 "name": ":scheme",
1053                 "value": "https",
1054                 "referenced": true,
1055                 "size": 44
1056               },
1057               {
1058                 "index": 4,
1059                 "name": ":path",
1060                 "value": "/",
1061                 "referenced": false,
1062                 "size": 38
1063               },
1064               {
1065                 "index": 5,
1066                 "name": ":method",
1067                 "value": "GET",
1068                 "referenced": false,
1069                 "size": 42
1070               },
1071               {
1072                 "index": 6,
1073                 "name": ":authority",
1074                 "value": "example.org",
1075                 "referenced": true,
1076                 "size": 53
1077               }
1078             ],
1079             "size": 269,
1080             "max_size": 4096,
1081             "deflate_size": 269,
1082             "max_deflate_size": 4096
1083           }
1084         }
1085       ]
1086     }
1087
1088 inflatehd - header decompressor
1089 +++++++++++++++++++++++++++++++
1090
1091 The ``inflatehd`` program reads JSON data from stdin and outputs decompressed
1092 name/value pairs in JSON.
1093
1094 The root JSON object must include the ``cases`` key.  Its value has to
1095 include the sequence of compressed header blocks.  They share the same
1096 compression context and are processed in the order they appear.  Each
1097 item in the sequence is a JSON object and it must have at least a
1098 ``wire`` key.  Its value is a compressed header block as a hex string.
1099
1100 Example:
1101
1102 .. code-block:: json
1103
1104     {
1105       "cases":
1106       [
1107         { "wire": "8285" },
1108         { "wire": "8583" }
1109       ]
1110     }
1111
1112 The output is a JSON object.  It should include a ``cases`` key and its
1113 value is an array of JSON objects, which has at least following keys:
1114
1115 seq
1116     The index of the header set in the input.
1117
1118 headers
1119     A JSON array that includes decompressed name/value pairs.
1120
1121 wire
1122     The compressed header block as a hex string.
1123
1124 header_table_size
1125     The header table size adjusted before inflating compressed header
1126     block.
1127
1128 Example:
1129
1130 .. code-block:: json
1131
1132     {
1133       "cases":
1134       [
1135         {
1136           "seq": 0,
1137           "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
1138           "headers": [
1139             {
1140               ":authority": "example.org"
1141             },
1142             {
1143               ":method": "GET"
1144             },
1145             {
1146               ":path": "/"
1147             },
1148             {
1149               ":scheme": "https"
1150             },
1151             {
1152               "user-agent": "nghttp2"
1153             }
1154           ],
1155           "header_table_size": 4096
1156         }
1157         ,
1158         {
1159           "seq": 1,
1160           "wire": "88448504252dd5918485",
1161           "headers": [
1162             {
1163               ":method": "POST"
1164             },
1165             {
1166               ":path": "/account"
1167             },
1168             {
1169               "user-agent": "nghttp2"
1170             },
1171             {
1172               ":scheme": "https"
1173             },
1174             {
1175               ":authority": "example.org"
1176             }
1177           ],
1178           "header_table_size": 4096
1179         }
1180       ]
1181     }
1182
1183 The output can be used as the input for ``deflatehd`` and
1184 ``inflatehd``.
1185
1186 With the ``-d`` option, the extra ``header_table`` key is added and its
1187 associated value includes the state of the dynamic header table after the
1188 corresponding header set was processed.  The format is the same as
1189 ``deflatehd``.
1190
1191 libnghttp2_asio: High level HTTP/2 C++ library
1192 ----------------------------------------------
1193
1194 libnghttp2_asio is C++ library built on top of libnghttp2 and provides
1195 high level abstraction API to build HTTP/2 applications.  It depends
1196 on the Boost::ASIO library and OpenSSL.  Currently libnghttp2_asio
1197 provides both client and server APIs.
1198
1199 libnghttp2_asio is not built by default.  Use the ``--enable-asio-lib``
1200 configure flag to build libnghttp2_asio.  The required Boost libraries
1201 are:
1202
1203 * Boost::Asio
1204 * Boost::System
1205 * Boost::Thread
1206
1207 The server API is designed to build an HTTP/2 server very easily to utilize
1208 C++11 anonymous functions and closures.  The bare minimum example of
1209 an HTTP/2 server looks like this:
1210
1211 .. code-block:: cpp
1212
1213     #include <nghttp2/asio_http2_server.h>
1214
1215     using namespace nghttp2::asio_http2;
1216     using namespace nghttp2::asio_http2::server;
1217
1218     int main(int argc, char *argv[]) {
1219       boost::system::error_code ec;
1220       http2 server;
1221
1222       server.handle("/", [](const request &req, const response &res) {
1223         res.write_head(200);
1224         res.end("hello, world\n");
1225       });
1226
1227       if (server.listen_and_serve(ec, "localhost", "3000")) {
1228         std::cerr << "error: " << ec.message() << std::endl;
1229       }
1230     }
1231
1232 Here is sample code to use the client API:
1233
1234 .. code-block:: cpp
1235
1236     #include <iostream>
1237
1238     #include <nghttp2/asio_http2_client.h>
1239
1240     using boost::asio::ip::tcp;
1241
1242     using namespace nghttp2::asio_http2;
1243     using namespace nghttp2::asio_http2::client;
1244
1245     int main(int argc, char *argv[]) {
1246       boost::system::error_code ec;
1247       boost::asio::io_service io_service;
1248
1249       // connect to localhost:3000
1250       session sess(io_service, "localhost", "3000");
1251
1252       sess.on_connect([&sess](tcp::resolver::iterator endpoint_it) {
1253         boost::system::error_code ec;
1254
1255         auto req = sess.submit(ec, "GET", "http://localhost:3000/");
1256
1257         req->on_response([](const response &res) {
1258           // print status code and response header fields.
1259           std::cerr << "HTTP/2 " << res.status_code() << std::endl;
1260           for (auto &kv : res.header()) {
1261             std::cerr << kv.first << ": " << kv.second.value << "\n";
1262           }
1263           std::cerr << std::endl;
1264
1265           res.on_data([](const uint8_t *data, std::size_t len) {
1266             std::cerr.write(reinterpret_cast<const char *>(data), len);
1267             std::cerr << std::endl;
1268           });
1269         });
1270
1271         req->on_close([&sess](uint32_t error_code) {
1272           // shutdown session after first request was done.
1273           sess.shutdown();
1274         });
1275       });
1276
1277       sess.on_error([](const boost::system::error_code &ec) {
1278         std::cerr << "error: " << ec.message() << std::endl;
1279       });
1280
1281       io_service.run();
1282     }
1283
1284 For more details, see the documentation of libnghttp2_asio.
1285
1286 Python bindings
1287 ---------------
1288
1289 The ``python`` directory contains nghttp2 Python bindings.  The
1290 bindings currently provide HPACK compressor and decompressor classes
1291 and an HTTP/2 server.
1292
1293 The extension module is called ``nghttp2``.
1294
1295 ``make`` will build the bindings and target Python version is
1296 determined by the ``configure`` script.  If the detected Python version is not
1297 what you expect, specify a path to Python executable in a ``PYTHON``
1298 variable as an argument to configure script (e.g., ``./configure
1299 PYTHON=/usr/bin/python3.4``).
1300
1301 The following example code illustrates basic usage of the HPACK compressor
1302 and decompressor in Python:
1303
1304 .. code-block:: python
1305
1306     import binascii
1307     import nghttp2
1308
1309     deflater = nghttp2.HDDeflater()
1310     inflater = nghttp2.HDInflater()
1311
1312     data = deflater.deflate([(b'foo', b'bar'),
1313                              (b'baz', b'buz')])
1314     print(binascii.b2a_hex(data))
1315
1316     hdrs = inflater.inflate(data)
1317     print(hdrs)
1318
1319 The ``nghttp2.HTTP2Server`` class builds on top of the asyncio event
1320 loop.  On construction, *RequestHandlerClass* must be given, which
1321 must be a subclass of ``nghttp2.BaseRequestHandler`` class.
1322
1323 The ``BaseRequestHandler`` class is used to handle the HTTP/2 stream.
1324 By default, it does nothing.  It must be subclassed to handle each
1325 event callback method.
1326
1327 The first callback method invoked is ``on_headers()``.  It is called
1328 when HEADERS frame, which includes the request header fields, has arrived.
1329
1330 If the request has a request body, ``on_data(data)`` is invoked for each
1331 chunk of received data.
1332
1333 Once the entire request is received, ``on_request_done()`` is invoked.
1334
1335 When the stream is closed, ``on_close(error_code)`` is called.
1336
1337 The application can send a response using ``send_response()`` method.
1338 It can be used in ``on_headers()``, ``on_data()`` or
1339 ``on_request_done()``.
1340
1341 The application can push resources using the ``push()`` method.  It must be
1342 used before the ``send_response()`` call.
1343
1344 The following instance variables are available:
1345
1346 client_address
1347     Contains a tuple of the form (host, port) referring to the
1348     client's address.
1349
1350 stream_id
1351     Stream ID of this stream.
1352
1353 scheme
1354     Scheme of the request URI.  This is a value of :scheme header
1355     field.
1356
1357 method
1358     Method of this stream.  This is a value of :method header field.
1359
1360 host
1361     This is a value of :authority or host header field.
1362
1363 path
1364     This is a value of :path header field.
1365
1366 The following example illustrates the HTTP2Server and
1367 BaseRequestHandler usage:
1368
1369 .. code-block:: python
1370
1371     #!/usr/bin/env python
1372
1373     import io, ssl
1374     import nghttp2
1375
1376     class Handler(nghttp2.BaseRequestHandler):
1377
1378         def on_headers(self):
1379             self.push(path='/css/bootstrap.css',
1380                       request_headers = [('content-length', '3')],
1381                       status=200,
1382                       body='foo')
1383
1384             self.push(path='/js/bootstrap.js',
1385                       method='GET',
1386                       request_headers = [('content-length', '10')],
1387                       status=200,
1388                       body='foobarbuzz')
1389
1390             self.send_response(status=200,
1391                                headers = [('content-type', 'text/plain')],
1392                                body=io.BytesIO(b'nghttp2-python FTW'))
1393
1394     ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
1395     ctx.options = ssl.OP_ALL | ssl.OP_NO_SSLv2
1396     ctx.load_cert_chain('server.crt', 'server.key')
1397
1398     # give None to ssl to make the server non-SSL/TLS
1399     server = nghttp2.HTTP2Server(('127.0.0.1', 8443), Handler, ssl=ctx)
1400     server.serve_forever()
1401
1402 Contribution
1403 ------------
1404
1405 [This text was composed based on 1.2. License section of curl/libcurl
1406 project.]
1407
1408 When contributing with code, you agree to put your changes and new
1409 code under the same license nghttp2 is already using unless stated and
1410 agreed otherwise.
1411
1412 When changing existing source code, do not alter the copyright of
1413 the original file(s).  The copyright will still be owned by the
1414 original creator(s) or those who have been assigned copyright by the
1415 original author(s).
1416
1417 By submitting a patch to the nghttp2 project, you (or your employer, as
1418 the case may be) agree to assign the copyright of your submission to us.
1419 .. the above really needs to be reworded to pass legal muster.
1420 We will credit you for your
1421 changes as far as possible, to give credit but also to keep a trace
1422 back to who made what changes.  Please always provide us with your
1423 full real name when contributing!
1424
1425 See `Contribution Guidelines
1426 <https://nghttp2.org/documentation/contribute.html>`_ for more
1427 details.