1 nghttp2 - HTTP/2 C Library
2 ==========================
4 This is an implementation of Hypertext Transfer Protocol version 2
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
12 HPACK encoder and decoder are available as public API.
14 The experimental high level C++ library is also available.
16 We have Python binding of this libary, but we have not covered
22 We started to implement h2-14
23 (http://tools.ietf.org/html/draft-ietf-httpbis-http2-14), the header
25 (http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-09).
27 The nghttp2 code base was forked from spdylay project.
29 =========================== =======
30 HTTP/2 Features Support
31 =========================== =======
32 Core frames handling Yes
34 Large header (CONTINUATION) Yes
35 =========================== =======
40 The following endpoints are available to try out nghttp2
43 * https://nghttp2.org/ (TLS + ALPN/NPN)
45 NPN offer ``h2-14``, ``spdy/3.1`` and ``http/1.1``.
47 This endpoint requires TLSv1.2 for HTTP/2 connection.
49 * http://nghttp2.org/ (Upgrade / Direct)
51 ``h2c-14`` and ``http/1.1``.
56 The following package is required to build the libnghttp2 library:
60 To build and run the unit test programs, the following package is
65 To build the documentation, you need to install:
67 * sphinx (http://sphinx-doc.org/)
69 To build and run the application programs (``nghttp``, ``nghttpd`` and
70 ``nghttpx``) in ``src`` directory, the following packages are
77 ALPN support requires unreleased version OpenSSL >= 1.0.2.
79 To enable SPDY protocol in the application program ``nghttpx`` and
80 ``h2load``, the following package is required:
84 To enable ``-a`` option (getting linked assets from the downloaded
85 resource) in ``nghttp``, the following package is required:
89 The HPACK tools require the following package:
93 To build sources under examples directory, libevent is required:
95 * libevent-openssl >= 2.0.8
97 To mitigate heap fragmentation in long running server programs
98 (``nghttpd`` and ``nghttpx``), jemalloc is recommended:
102 libnghttp2_asio C++ library requires the following packages:
104 * libboost-dev >= 1.54.0
105 * libboost-thread-dev >= 1.54.0
107 The Python bindings require the following packages:
112 If you are using Ubuntu 14.04 LTS, you need the following packages
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
117 spdylay is not packaged in Ubuntu, so you need to build it yourself:
118 http://tatsuhiro-t.github.io/spdylay/
123 Building from git is easy, but please be sure that at least autoconf 2.68 is
132 To compile source code, gcc >= 4.8.3 or clang >= 3.4 is required.
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.
141 Building documentation
142 ----------------------
146 Documentation is still incomplete.
148 To build documentation, run::
152 The documents will be generated under ``doc/manual/html/``.
154 The generated documents will not be installed with ``make install``.
156 The online documentation is available at
157 https://nghttp2.org/documentation/
162 Unit tests are done by simply running `make check`.
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:
171 * https://github.com/bradfitz/http2
172 * https://github.com/tatsuhiro-t/go-nghttp2
173 * https://golang.org/x/net/spdy
175 To download the above packages, after settings ``GOPATH``, run the
176 following command under ``integration-tests`` directory::
180 To run the tests, run the following command under
181 ``integration-tests`` directory::
185 Inside the tests, we use port 3009 to run test subject server.
187 Client, Server and Proxy programs
188 ---------------------------------
190 The src directory contains HTTP/2 client, server and proxy programs.
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.
198 It has verbose output mode for framing information. Here is sample
199 output from ``nghttp`` client::
201 $ nghttp -nv https://nghttp2.org
202 [ 0.033][NPN] server offers:
206 The negotiated protocol: h2-14
207 [ 0.068] send SETTINGS frame <length=15, flags=0x00, stream_id=0>
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
216 :authority: nghttp2.org
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>
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>
230 [ 0.079] recv SETTINGS frame <length=0, flags=0x01, stream_id=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>
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>
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)=[])
268 The HTTP Upgrade is performed like this::
270 $ nghttp -nvu http://nghttp2.org
271 [ 0.013] HTTP Upgrade request
274 Connection: Upgrade, HTTP2-Settings
276 HTTP2-Settings: AwAAAGQEAAD__wUAAAAB
278 User-Agent: nghttp2/0.4.0-DEV
281 [ 0.024] HTTP Upgrade response
282 HTTP/1.1 101 Switching Protocols
287 [ 0.024] HTTP Upgrade success
288 [ 0.024] send SETTINGS frame <length=15, flags=0x00, stream_id=0>
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>
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>
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>
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>
331 [ 0.038] recv SETTINGS frame <length=0, flags=0x01, stream_id=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)=[])
337 With ``-s`` option, ``nghttp`` prints out some timing information for
338 requests, sorted by completion time::
340 $ nghttp -nas https://nghttp2.org/
341 ***** Statistics *****
344 complete: relative time from protocol handshake to stream close
345 request: relative time from protocol handshake to request
347 process: time for request and response
348 code: HTTP status code
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
361 With ``-r`` option, ``nghttp`` writes more detailed timing data to
362 given file in HAR format.
367 ``nghttpd`` is a multi-threaded static web server.
369 By default, it uses SSL/TLS connection. Use ``--no-tls`` option to
372 ``nghttpd`` only accepts the HTTP/2 connection via NPN/ALPN or direct
373 HTTP/2 connection. No HTTP Upgrade is supported.
375 ``-p`` option allows users to configure server push.
377 Just like ``nghttp``, it has verbose output mode for framing
378 information. Here is sample output from ``nghttpd`` server::
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>
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>
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
403 [id=1] [ 15.921] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
406 [id=1] [ 15.921] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
409 [id=1] [ 15.921] send HEADERS frame <length=82, flags=0x04, stream_id=1>
412 ; First response header
414 cache-control: max-age=3600
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>
421 [id=1] [ 15.922] send DATA frame <length=0, flags=0x01, stream_id=1>
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
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:
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 ================== ============================ ============== =============
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.
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.
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.
458 ``nghttpx`` supports configuration file. See ``--conf`` option and
459 sample configuration file ``nghttpx.conf.sample``.
461 ``nghttpx`` does not support server push.
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::
467 Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Web Server
470 With ``--http2-proxy`` option, it works as so called secure proxy (aka
473 Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy
474 [secure proxy] (e.g., Squid, ATS)
476 The ``Client`` in the above needs to be configured to use
477 ``nghttpx`` as secure proxy.
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:
483 .. code-block:: javascript
485 function FindProxyForURL(url, host) {
486 return "HTTPS SERVERADDR:PORT";
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.
493 Then run Chrome with the following arguments::
495 $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
497 With ``--http2-bridge``, it accepts HTTP/2, SPDY and HTTP/1.1
498 connections and communicates with backend in HTTP/2::
500 Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web or HTTP/2 Proxy etc
503 With ``--client-proxy`` option, it works as forward proxy and expects
504 that the backend is HTTP/2 proxy::
506 Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> HTTP/2 Proxy
507 [forward proxy] (e.g., nghttpx -s)
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.
514 With ``--client`` option, it works as reverse proxy and expects that
515 the backend is HTTP/2 Web server::
517 Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web Server
520 The frontend HTTP/1.1 connection can be upgraded to HTTP/2
521 through HTTP Upgrade.
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::
530 Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --
532 --===================---> HTTP/2 Proxy
533 (HTTP proxy tunnel) (e.g., nghttpx -s)
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
544 $ h2load -n100000 -c100 -m100 https://localhost:8443/
545 starting benchmark...
546 spawning thread #0: 100 concurrent clients, 100000 total requests
548 Cipher: ECDHE-RSA-AES128-GCM-SHA256
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%
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.
574 **Don't use this tool against publicly available servers.** That is
575 considered a DOS attack. Please only use against your private
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
588 deflatehd - header compressor
589 +++++++++++++++++++++++++++++
591 The ``deflatehd`` reads JSON data or HTTP/1-style header fields from
592 stdin and outputs compressed header block in JSON.
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.
610 { ":method": "GET" },
616 { ":method": "POST" },
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:
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:
640 The index of header set in the input.
643 The sum of length of name/value pair in the input.
646 The length of compressed header block.
648 percentage_of_original_size
649 ``input_length`` / ``output_length`` * 100
652 The compressed header block in hex string.
655 The input header set.
658 The header table size adjusted before deflating header set.
671 "percentage_of_original_size": 30.303030303030305,
672 "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
675 ":authority": "example.org"
687 "user-agent": "nghttp2"
690 "header_table_size": 4096
697 "percentage_of_original_size": 13.513513513513514,
698 "wire": "88448504252dd5918485",
701 ":authority": "example.org"
713 "user-agent": "nghttp2"
716 "header_table_size": 4096
722 The output can be used as the input for ``inflatehd`` and
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
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
738 The sum of the spaces entries occupied, this includes the
742 The maximum header table size.
745 The sum of the spaces entries occupied within
746 ``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.
767 "percentage_of_original_size": 30.303030303030305,
768 "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
771 ":authority": "example.org"
783 "user-agent": "nghttp2"
786 "header_table_size": 4096,
791 "name": "user-agent",
819 "name": ":authority",
820 "value": "example.org",
828 "max_deflate_size": 4096
836 "percentage_of_original_size": 13.513513513513514,
837 "wire": "88448504252dd5918485",
840 ":authority": "example.org"
852 "user-agent": "nghttp2"
855 "header_table_size": 4096,
867 "name": "user-agent",
895 "name": ":authority",
896 "value": "example.org",
904 "max_deflate_size": 4096
910 inflatehd - header decompressor
911 +++++++++++++++++++++++++++++++
913 The ``inflatehd`` reads JSON data from stdin and outputs decompressed
914 name/value pairs in JSON.
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.
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:
938 The index of header set in the input.
941 The JSON array includes decompressed name/value pairs.
944 The compressed header block in hex string.
947 The header table size adjusted before inflating compressed header
959 "wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
962 ":authority": "example.org"
974 "user-agent": "nghttp2"
977 "header_table_size": 4096
982 "wire": "88448504252dd5918485",
991 "user-agent": "nghttp2"
997 ":authority": "example.org"
1000 "header_table_size": 4096
1005 The output can be used as the input for ``deflatehd`` and
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
1013 libnghttp2_asio: High level HTTP/2 C++ library
1014 ----------------------------------------------
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.
1021 libnghttp2_asio is not built by default. Use ``--enable-asio-lib``
1022 configure flag to build libnghttp2_asio. The required Boost libraries
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:
1035 #include <nghttp2/asio_http2.h>
1037 using namespace nghttp2::asio_http2;
1038 using namespace nghttp2::asio_http2::server;
1040 int main(int argc, char *argv[]) {
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");
1050 For more details, see the documentation of libnghttp2_asio.
1055 This ``python`` directory contains nghttp2 Python bindings. The
1056 bindings currently provide HPACK compressor and decompressor classes
1059 The extension module is called ``nghttp2``.
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``).
1067 The following example code illustrates basic usage of HPACK compressor
1068 and decompressor in Python:
1070 .. code-block:: python
1075 deflater = nghttp2.HDDeflater()
1076 inflater = nghttp2.HDInflater()
1078 data = deflater.deflate([(b'foo', b'bar'),
1080 print(binascii.b2a_hex(data))
1082 hdrs = inflater.inflate(data)
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.
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.
1093 The first callback method invoked is ``on_headers()``. It is called
1094 when HEADERS frame, which includes request header fields, has arrived.
1096 If request has request body, ``on_data(data)`` is invoked for each
1097 chunk of received data.
1099 When whole request is received, ``on_request_done()`` is invoked.
1101 When stream is closed, ``on_close(error_code)`` is called.
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()``.
1107 The application can push resource using ``push()`` method. It must be
1108 used before ``send_response()`` call.
1110 The following instance variables are available:
1113 Contains a tuple of the form (host, port) referring to the
1117 Stream ID of this stream.
1120 Scheme of the request URI. This is a value of :scheme header
1124 Method of this stream. This is a value of :method header field.
1127 This is a value of :authority or host header field.
1130 This is a value of :path header field.
1132 The following example illustrates the HTTP2Server and
1133 BaseRequestHandler usage:
1135 .. code-block:: python
1137 #!/usr/bin/env python
1142 class Handler(nghttp2.BaseRequestHandler):
1144 def on_headers(self):
1145 self.push(path='/css/bootstrap.css',
1146 request_headers = [('content-length', '3')],
1150 self.push(path='/js/bootstrap.js',
1152 request_headers = [('content-length', '10')],
1156 self.send_response(status=200,
1157 headers = [('content-type', 'text/plain')],
1158 body=io.BytesIO(b'nghttp2-python FTW'))
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')
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()
1171 [This text was composed based on 1.2. License section of curl/libcurl
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
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
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!
1190 See `Contribution Guidelines
1191 <https://nghttp2.org/documentation/contribute.html>`_ for more