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