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_1t+quic>`_; or 131 `BoringSSL <https://boringssl.googlesource.com/boringssl/>`_ (commit 132 80a243e07ef77156af66efa7d22ac35aba44c1b3) 133* `ngtcp2 <https://github.com/ngtcp2/ngtcp2>`_ >= 0.13.0 134* `nghttp3 <https://github.com/ngtcp2/nghttp3>`_ >= 0.7.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.1.0>`_. 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_1t+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 v0.8.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 v0.13.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.1.0 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 1459Release schedule 1460---------------- 1461 1462In general, we follow `Semantic Versioning <http://semver.org/>`_. We 1463release MINOR version update every month, and usually we ship it 1464around 25th day of every month. 1465 1466We may release PATCH releases between the regular releases, mainly for 1467severe security bug fixes. 1468 1469We have no plan to break API compatibility changes involving soname 1470bump, so MAJOR version will stay 1 for the foreseeable future. 1471 1472License 1473------- 1474 1475The MIT License 1476