/home/fresvfqn/waterdamagerestorationandrepairsmithtown.com/Compressed/nghttp2.tar
share/doc/nghttp2/README.rst 0000644 00000140611 15053606574 0011506 0 ustar 00 nghttp2 - HTTP/2 C Library
==========================
This is an implementation of the Hypertext Transfer Protocol version 2
in C.
The framing layer of HTTP/2 is implemented as a reusable C library.
On top of that, we have implemented an HTTP/2 client, server and
proxy. We have also developed load test and benchmarking tools for
HTTP/2.
An HPACK encoder and decoder are available as a public API.
Development Status
------------------
nghttp2 was originally developed based on `RFC 7540
<https://tools.ietf.org/html/rfc7540>`_ HTTP/2 and `RFC 7541
<https://tools.ietf.org/html/rfc7541>`_ HPACK - Header Compression for
HTTP/2. Now we are updating our code to implement `RFC 9113
<https://datatracker.ietf.org/doc/html/rfc9113>`_.
The nghttp2 code base was forked from the spdylay
(https://github.com/tatsuhiro-t/spdylay) project.
Public Test Server
------------------
The following endpoints are available to try out our nghttp2
implementation.
* https://nghttp2.org/ (TLS + ALPN and HTTP/3)
This endpoint supports ``h2`` and ``http/1.1`` via ALPN and requires
TLSv1.2 for HTTP/2 connection.
It also supports HTTP/3.
* http://nghttp2.org/ (HTTP Upgrade and HTTP/2 Direct)
``h2c`` and ``http/1.1``.
Requirements
------------
The following package is required to build the libnghttp2 library:
* pkg-config >= 0.20
To build the documentation, you need to install:
* sphinx (http://sphinx-doc.org/)
If you need libnghttp2 (C library) only, then the above packages are
all you need. Use ``--enable-lib-only`` to ensure that only
libnghttp2 is built. This avoids potential build error related to
building bundled applications.
To build and run the application programs (``nghttp``, ``nghttpd``,
``nghttpx`` and ``h2load``) in the ``src`` directory, the following packages
are required:
* OpenSSL >= 1.1.1; or wolfSSL >= 5.7.0; or LibreSSL >= 3.8.1; or
aws-lc >= 1.19.0; or BoringSSL
* libev >= 4.11
* zlib >= 1.2.3
* libc-ares >= 1.7.5
To enable ``-a`` option (getting linked assets from the downloaded
resource) in ``nghttp``, the following package is required:
* libxml2 >= 2.6.26
To enable systemd support in nghttpx, the following package is
required:
* libsystemd-dev >= 209
The HPACK tools require the following package:
* jansson >= 2.5
To build sources under the examples directory, libevent is required:
* libevent-openssl >= 2.0.8
To mitigate heap fragmentation in long running server programs
(``nghttpd`` and ``nghttpx``), jemalloc is recommended:
* jemalloc
.. note::
Alpine Linux currently does not support malloc replacement
due to musl limitations. See details in issue `#762 <https://github.com/nghttp2/nghttp2/issues/762>`_.
For BoringSSL or aws-lc build, to enable :rfc:`8879` TLS Certificate
Compression in applications, the following library is required:
* libbrotli-dev >= 1.0.9
To enable mruby support for nghttpx, `mruby
<https://github.com/mruby/mruby>`_ is required. We need to build
mruby with C++ ABI explicitly turned on, and probably need other
mrgems, mruby is managed by git submodule under third-party/mruby
directory. Currently, mruby support for nghttpx is disabled by
default. To enable mruby support, use ``--with-mruby`` configure
option. Note that at the time of this writing, libmruby-dev and mruby
packages in Debian/Ubuntu are not usable for nghttp2, since they do
not enable C++ ABI. To build mruby, the following packages are
required:
* ruby
* bison
nghttpx supports `neverbleed <https://github.com/h2o/neverbleed>`_,
privilege separation engine for OpenSSL. In short, it minimizes the
risk of private key leakage when serious bug like Heartbleed is
exploited. The neverbleed is disabled by default. To enable it, use
``--with-neverbleed`` configure option.
To enable the experimental HTTP/3 support for h2load and nghttpx, the
following libraries are required:
* `quictls
<https://github.com/quictls/openssl/tree/OpenSSL_1_1_1w+quic>`_; or
wolfSSL; or LibreSSL (does not support 0RTT); or aws-lc; or
`BoringSSL <https://boringssl.googlesource.com/boringssl/>`_ (commit
9295969e1dad2c31d0d99481734c1c68dcbc6403); or OpenSSL >= 3.5.0
* `ngtcp2 <https://github.com/ngtcp2/ngtcp2>`_ >= 1.12.0
* `nghttp3 <https://github.com/ngtcp2/nghttp3>`_ >= 1.1.0
Use ``--enable-http3`` configure option to enable HTTP/3 feature for
h2load and nghttpx.
In order to build optional eBPF program to direct an incoming QUIC UDP
datagram to a correct socket for nghttpx, the following libraries are
required:
* libbpf-dev >= 0.7.0
Use ``--with-libbpf`` configure option to build eBPF program.
libelf-dev is needed to build libbpf.
For Ubuntu 20.04, you can build libbpf from `the source code
<https://github.com/libbpf/libbpf/releases>`_. nghttpx requires eBPF
program for reloading its configuration and hot swapping its
executable.
Compiling libnghttp2 C source code requires a C99 compiler. gcc 4.8
is known to be adequate. In order to compile the C++ source code,
C++20 compliant compiler is required. At least g++ >= 12 and
clang++ >= 18 are known to work.
.. note::
To enable mruby support in nghttpx, and use ``--with-mruby``
configure option.
.. note::
Mac OS X users may need the ``--disable-threads`` configure option to
disable multi-threading in nghttpd, nghttpx and h2load to prevent
them from crashing. A patch is welcome to make multi threading work
on Mac OS X platform.
.. note::
To compile the associated applications (nghttp, nghttpd, nghttpx
and h2load), you must use the ``--enable-app`` configure option and
ensure that the specified requirements above are met. Normally,
configure script checks required dependencies to build these
applications, and enable ``--enable-app`` automatically, so you
don't have to use it explicitly. But if you found that
applications were not built, then using ``--enable-app`` may find
that cause, such as the missing dependency.
.. note::
In order to detect third party libraries, pkg-config is used
(however we don't use pkg-config for some libraries (e.g., libev)).
By default, pkg-config searches ``*.pc`` file in the standard
locations (e.g., /usr/lib/pkgconfig). If it is necessary to use
``*.pc`` file in the custom location, specify paths to
``PKG_CONFIG_PATH`` environment variable, and pass it to configure
script, like so:
.. code-block:: text
$ ./configure PKG_CONFIG_PATH=/path/to/pkgconfig
For pkg-config managed libraries, ``*_CFLAG`` and ``*_LIBS``
environment variables are defined (e.g., ``OPENSSL_CFLAGS``,
``OPENSSL_LIBS``). Specifying non-empty string to these variables
completely overrides pkg-config. In other words, if they are
specified, pkg-config is not used for detection, and user is
responsible to specify the correct values to these variables. For
complete list of these variables, run ``./configure -h``.
If you are using Ubuntu 22.04 LTS, run the following to install the
required packages:
.. code-block:: text
sudo apt-get install g++ clang make binutils autoconf automake \
autotools-dev libtool pkg-config \
zlib1g-dev libssl-dev libxml2-dev libev-dev \
libevent-dev libjansson-dev \
libc-ares-dev libjemalloc-dev libsystemd-dev \
ruby-dev bison libelf-dev
Building nghttp2 from release tar archive
-----------------------------------------
The nghttp2 project regularly releases tar archives which includes
nghttp2 source code, and generated build files. They can be
downloaded from `Releases
<https://github.com/nghttp2/nghttp2/releases>`_ page.
Building nghttp2 from git requires autotools development packages.
Building from tar archives does not require them, and thus it is much
easier. The usual build step is as follows:
.. code-block:: text
$ tar xf nghttp2-X.Y.Z.tar.bz2
$ cd nghttp2-X.Y.Z
$ ./configure
$ make
Building from git
-----------------
Building from git is easy, but please be sure that at least autoconf 2.68 is
used:
.. code-block:: text
$ git submodule update --init
$ autoreconf -i
$ automake
$ autoconf
$ ./configure
$ make
Notes for building on Windows (MSVC)
------------------------------------
The easiest way to build native Windows nghttp2 dll is use `cmake
<https://cmake.org/>`_. The free version of `Visual C++ Build Tools
<http://landinghub.visualstudio.com/visual-cpp-build-tools>`_ works
fine.
1. Install cmake for windows
2. Open "Visual C++ ... Native Build Tool Command Prompt", and inside
nghttp2 directly, run ``cmake``.
3. Then run ``cmake --build`` to build library.
4. nghttp2.dll, nghttp2.lib, nghttp2.exp are placed under lib directory.
Note that the above steps most likely produce nghttp2 library only.
No bundled applications are compiled.
Notes for building on Windows (Mingw/Cygwin)
--------------------------------------------
Under Mingw environment, you can only compile the library, it's
``libnghttp2-X.dll`` and ``libnghttp2.a``.
If you want to compile the applications(``h2load``, ``nghttp``,
``nghttpx``, ``nghttpd``), you need to use the Cygwin environment.
Under Cygwin environment, to compile the applications you need to
compile and install the libev first.
Secondly, you need to undefine the macro ``__STRICT_ANSI__``, if you
not, the functions ``fdopen``, ``fileno`` and ``strptime`` will not
available.
the sample command like this:
.. code-block:: text
$ export CFLAGS="-U__STRICT_ANSI__ -I$libev_PREFIX/include -L$libev_PREFIX/lib"
$ export CXXFLAGS=$CFLAGS
$ ./configure
$ make
If you want to compile the applications under ``examples/``, you need
to remove or rename the ``event.h`` from libev's installation, because
it conflicts with libevent's installation.
Notes for installation on Linux systems
--------------------------------------------
After installing nghttp2 tool suite with ``make install`` one might experience a similar error:
.. code-block:: text
nghttpx: error while loading shared libraries: libnghttp2.so.14: cannot open shared object file: No such file or directory
This means that the tool is unable to locate the ``libnghttp2.so`` shared library.
To update the shared library cache run ``sudo ldconfig``.
Building the documentation
--------------------------
.. note::
Documentation is still incomplete.
To build the documentation, run:
.. code-block:: text
$ make html
The documents will be generated under ``doc/manual/html/``.
The generated documents will not be installed with ``make install``.
The online documentation is available at
https://nghttp2.org/documentation/
Build HTTP/3 enabled h2load and nghttpx
---------------------------------------
To build h2load and nghttpx with HTTP/3 feature enabled, run the
configure script with ``--enable-http3``.
For nghttpx to reload configurations and swapping its executable while
gracefully terminating old worker processes, eBPF is required. Run
the configure script with ``--enable-http3 --with-libbpf`` to build
eBPF program. The QUIC keying material must be set with
``--frontend-quic-secret-file`` in order to keep the existing
connections alive during reload.
The detailed steps to build HTTP/3 enabled h2load and nghttpx follow.
Build aws-lc:
.. code-block:: text
$ git clone --depth 1 -b v1.52.0 https://github.com/aws/aws-lc
$ cd aws-lc
$ cmake -B build -DDISABLE_GO=ON --install-prefix=$PWD/opt
$ make -j$(nproc) -C build
$ cmake --install build
$ cd ..
Build nghttp3:
.. code-block:: text
$ git clone --depth 1 -b v1.9.0 https://github.com/ngtcp2/nghttp3
$ cd nghttp3
$ git submodule update --init --depth 1
$ autoreconf -i
$ ./configure --prefix=$PWD/build --enable-lib-only
$ make -j$(nproc)
$ make install
$ cd ..
Build ngtcp2:
.. code-block:: text
$ git clone --depth 1 -b v1.12.0 https://github.com/ngtcp2/ngtcp2
$ cd ngtcp2
$ git submodule update --init --depth 1
$ autoreconf -i
$ ./configure --prefix=$PWD/build --enable-lib-only --with-boringssl \
BORINGSSL_CFLAGS="-I$PWD/../aws-lc/opt/include" \
BORINGSSL_LIBS="-L$PWD/../aws-lc/opt/lib -lssl -lcrypto"
$ make -j$(nproc)
$ make install
$ cd ..
If your Linux distribution does not have libbpf-dev >= 0.7.0, build
from source:
.. code-block:: text
$ git clone --depth 1 -b v1.5.1 https://github.com/libbpf/libbpf
$ cd libbpf
$ PREFIX=$PWD/build make -C src install
$ cd ..
Build nghttp2:
.. code-block:: text
$ git clone https://github.com/nghttp2/nghttp2
$ cd nghttp2
$ git submodule update --init
$ autoreconf -i
$ ./configure --with-mruby --enable-http3 --with-libbpf \
CC=clang-18 CXX=clang++-18 \
PKG_CONFIG_PATH="$PWD/../aws-lc/opt/lib/pkgconfig:$PWD/../nghttp3/build/lib/pkgconfig:$PWD/../ngtcp2/build/lib/pkgconfig:$PWD/../libbpf/build/lib64/pkgconfig" \
LDFLAGS="$LDFLAGS -Wl,-rpath,$PWD/../aws-lc/opt/lib -Wl,-rpath,$PWD/../libbpf/build/lib64"
$ make -j$(nproc)
The eBPF program ``reuseport_kern.o`` should be found under bpf
directory. Pass ``--quic-bpf-program-file=bpf/reuseport_kern.o``
option to nghttpx to load it. See also `HTTP/3 section in nghttpx -
HTTP/2 proxy - HOW-TO
<https://nghttp2.org/documentation/nghttpx-howto.html#http-3>`_.
Unit tests
----------
Unit tests are done by simply running ``make check``.
Integration tests
-----------------
We have the integration tests for the nghttpx proxy server. The tests are
written in the `Go programming language <http://golang.org/>`_ and uses
its testing framework. We depend on the following libraries:
* golang.org/x/net/http2
* golang.org/x/net/websocket
* https://github.com/tatsuhiro-t/go-nghttp2
Go modules will download these dependencies automatically.
To run the tests, run the following command under
``integration-tests`` directory:
.. code-block:: text
$ make it
Inside the tests, we use port 3009 to run the test subject server.
Migration from v0.7.15 or earlier
---------------------------------
nghttp2 v1.0.0 introduced several backward incompatible changes. In
this section, we describe these changes and how to migrate to v1.0.0.
ALPN protocol ID is now ``h2`` and ``h2c``
++++++++++++++++++++++++++++++++++++++++++
Previously we announced ``h2-14`` and ``h2c-14``. v1.0.0 implements
final protocol version, and we changed ALPN ID to ``h2`` and ``h2c``.
The macros ``NGHTTP2_PROTO_VERSION_ID``,
``NGHTTP2_PROTO_VERSION_ID_LEN``,
``NGHTTP2_CLEARTEXT_PROTO_VERSION_ID``, and
``NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN`` have been updated to
reflect this change.
Basically, existing applications do not have to do anything, just
recompiling is enough for this change.
Use word "client magic" where we use "client connection preface"
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
We use "client connection preface" to mean first 24 bytes of client
connection preface. This is technically not correct, since client
connection preface is composed of 24 bytes client magic byte string
followed by SETTINGS frame. For clarification, we call "client magic"
for this 24 bytes byte string and updated API.
* ``NGHTTP2_CLIENT_CONNECTION_PREFACE`` was replaced with
``NGHTTP2_CLIENT_MAGIC``.
* ``NGHTTP2_CLIENT_CONNECTION_PREFACE_LEN`` was replaced with
``NGHTTP2_CLIENT_MAGIC_LEN``.
* ``NGHTTP2_BAD_PREFACE`` was renamed as ``NGHTTP2_BAD_CLIENT_MAGIC``
The already deprecated ``NGHTTP2_CLIENT_CONNECTION_HEADER`` and
``NGHTTP2_CLIENT_CONNECTION_HEADER_LEN`` were removed.
If application uses these macros, just replace old ones with new ones.
Since v1.0.0, client magic is sent by library (see next subsection),
so client application may just remove these macro use.
Client magic is sent by library
+++++++++++++++++++++++++++++++
Previously nghttp2 library did not send client magic, which is first
24 bytes byte string of client connection preface, and client
applications have to send it by themselves. Since v1.0.0, client
magic is sent by library via first call of ``nghttp2_session_send()``
or ``nghttp2_session_mem_send2()``.
The client applications which send client magic must remove the
relevant code.
Remove HTTP Alternative Services (Alt-Svc) related code
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
Alt-Svc specification is not finalized yet. To make our API stable,
we have decided to remove all Alt-Svc related API from nghttp2.
* ``NGHTTP2_EXT_ALTSVC`` was removed.
* ``nghttp2_ext_altsvc`` was removed.
We have already removed the functionality of Alt-Svc in v0.7 series
and they have been essentially noop. The application using these
macro and struct, remove those lines.
Use nghttp2_error in nghttp2_on_invalid_frame_recv_callback
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Previously ``nghttp2_on_invalid_frame_recv_cb_called`` took the
``error_code``, defined in ``nghttp2_error_code``, as parameter. But
they are not detailed enough to debug. Therefore, we decided to use
more detailed ``nghttp2_error`` values instead.
The application using this callback should update the callback
signature. If it treats ``error_code`` as HTTP/2 error code, update
the code so that it is treated as ``nghttp2_error``.
Receive client magic by default
+++++++++++++++++++++++++++++++
Previously nghttp2 did not process client magic (24 bytes byte
string). To make it deal with it, we had to use
``nghttp2_option_set_recv_client_preface()``. Since v1.0.0, nghttp2
processes client magic by default and
``nghttp2_option_set_recv_client_preface()`` was removed.
Some application may want to disable this behaviour, so we added
``nghttp2_option_set_no_recv_client_magic()`` to achieve this.
The application using ``nghttp2_option_set_recv_client_preface()``
with nonzero value, just remove it.
The application using ``nghttp2_option_set_recv_client_preface()``
with zero value or not using it must use
``nghttp2_option_set_no_recv_client_magic()`` with nonzero value.
Client, Server and Proxy programs
---------------------------------
The ``src`` directory contains the HTTP/2 client, server and proxy programs.
nghttp - client
+++++++++++++++
``nghttp`` is a HTTP/2 client. It can connect to the HTTP/2 server
with prior knowledge, HTTP Upgrade and ALPN TLS extension.
It has verbose output mode for framing information. Here is sample
output from ``nghttp`` client:
.. code-block:: text
$ nghttp -nv https://nghttp2.org
[ 0.190] Connected
The negotiated protocol: h2
[ 0.212] recv SETTINGS frame <length=12, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
[SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
[ 0.212] send SETTINGS frame <length=12, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
[SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
[ 0.212] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[ 0.212] send PRIORITY frame <length=5, flags=0x00, stream_id=3>
(dep_stream_id=0, weight=201, exclusive=0)
[ 0.212] send PRIORITY frame <length=5, flags=0x00, stream_id=5>
(dep_stream_id=0, weight=101, exclusive=0)
[ 0.212] send PRIORITY frame <length=5, flags=0x00, stream_id=7>
(dep_stream_id=0, weight=1, exclusive=0)
[ 0.212] send PRIORITY frame <length=5, flags=0x00, stream_id=9>
(dep_stream_id=7, weight=1, exclusive=0)
[ 0.212] send PRIORITY frame <length=5, flags=0x00, stream_id=11>
(dep_stream_id=3, weight=1, exclusive=0)
[ 0.212] send HEADERS frame <length=39, flags=0x25, stream_id=13>
; END_STREAM | END_HEADERS | PRIORITY
(padlen=0, dep_stream_id=11, weight=16, exclusive=0)
; Open new stream
:method: GET
:path: /
:scheme: https
:authority: nghttp2.org
accept: */*
accept-encoding: gzip, deflate
user-agent: nghttp2/1.0.1-DEV
[ 0.221] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[ 0.221] recv (stream_id=13) :method: GET
[ 0.221] recv (stream_id=13) :scheme: https
[ 0.221] recv (stream_id=13) :path: /stylesheets/screen.css
[ 0.221] recv (stream_id=13) :authority: nghttp2.org
[ 0.221] recv (stream_id=13) accept-encoding: gzip, deflate
[ 0.222] recv (stream_id=13) user-agent: nghttp2/1.0.1-DEV
[ 0.222] recv PUSH_PROMISE frame <length=50, flags=0x04, stream_id=13>
; END_HEADERS
(padlen=0, promised_stream_id=2)
[ 0.222] recv (stream_id=13) :status: 200
[ 0.222] recv (stream_id=13) date: Thu, 21 May 2015 16:38:14 GMT
[ 0.222] recv (stream_id=13) content-type: text/html
[ 0.222] recv (stream_id=13) last-modified: Fri, 15 May 2015 15:38:06 GMT
[ 0.222] recv (stream_id=13) etag: W/"555612de-19f6"
[ 0.222] recv (stream_id=13) link: </stylesheets/screen.css>; rel=preload; as=stylesheet
[ 0.222] recv (stream_id=13) content-encoding: gzip
[ 0.222] recv (stream_id=13) server: nghttpx nghttp2/1.0.1-DEV
[ 0.222] recv (stream_id=13) via: 1.1 nghttpx
[ 0.222] recv (stream_id=13) strict-transport-security: max-age=31536000
[ 0.222] recv HEADERS frame <length=166, flags=0x04, stream_id=13>
; END_HEADERS
(padlen=0)
; First response header
[ 0.222] recv DATA frame <length=2601, flags=0x01, stream_id=13>
; END_STREAM
[ 0.222] recv (stream_id=2) :status: 200
[ 0.222] recv (stream_id=2) date: Thu, 21 May 2015 16:38:14 GMT
[ 0.222] recv (stream_id=2) content-type: text/css
[ 0.222] recv (stream_id=2) last-modified: Fri, 15 May 2015 15:38:06 GMT
[ 0.222] recv (stream_id=2) etag: W/"555612de-9845"
[ 0.222] recv (stream_id=2) content-encoding: gzip
[ 0.222] recv (stream_id=2) server: nghttpx nghttp2/1.0.1-DEV
[ 0.222] recv (stream_id=2) via: 1.1 nghttpx
[ 0.222] recv (stream_id=2) strict-transport-security: max-age=31536000
[ 0.222] recv HEADERS frame <length=32, flags=0x04, stream_id=2>
; END_HEADERS
(padlen=0)
; First push response header
[ 0.228] recv DATA frame <length=8715, flags=0x01, stream_id=2>
; END_STREAM
[ 0.228] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
(last_stream_id=2, error_code=NO_ERROR(0x00), opaque_data(0)=[])
The HTTP Upgrade is performed like so:
.. code-block:: text
$ nghttp -nvu http://nghttp2.org
[ 0.011] Connected
[ 0.011] HTTP Upgrade request
GET / HTTP/1.1
Host: nghttp2.org
Connection: Upgrade, HTTP2-Settings
Upgrade: h2c
HTTP2-Settings: AAMAAABkAAQAAP__
Accept: */*
User-Agent: nghttp2/1.0.1-DEV
[ 0.018] HTTP Upgrade response
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: h2c
[ 0.018] HTTP Upgrade success
[ 0.018] recv SETTINGS frame <length=12, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
[SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
[ 0.018] send SETTINGS frame <length=12, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
[SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
[ 0.018] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[ 0.018] send PRIORITY frame <length=5, flags=0x00, stream_id=3>
(dep_stream_id=0, weight=201, exclusive=0)
[ 0.018] send PRIORITY frame <length=5, flags=0x00, stream_id=5>
(dep_stream_id=0, weight=101, exclusive=0)
[ 0.018] send PRIORITY frame <length=5, flags=0x00, stream_id=7>
(dep_stream_id=0, weight=1, exclusive=0)
[ 0.018] send PRIORITY frame <length=5, flags=0x00, stream_id=9>
(dep_stream_id=7, weight=1, exclusive=0)
[ 0.018] send PRIORITY frame <length=5, flags=0x00, stream_id=11>
(dep_stream_id=3, weight=1, exclusive=0)
[ 0.018] send PRIORITY frame <length=5, flags=0x00, stream_id=1>
(dep_stream_id=11, weight=16, exclusive=0)
[ 0.019] recv (stream_id=1) :method: GET
[ 0.019] recv (stream_id=1) :scheme: http
[ 0.019] recv (stream_id=1) :path: /stylesheets/screen.css
[ 0.019] recv (stream_id=1) host: nghttp2.org
[ 0.019] recv (stream_id=1) user-agent: nghttp2/1.0.1-DEV
[ 0.019] recv PUSH_PROMISE frame <length=49, flags=0x04, stream_id=1>
; END_HEADERS
(padlen=0, promised_stream_id=2)
[ 0.019] recv (stream_id=1) :status: 200
[ 0.019] recv (stream_id=1) date: Thu, 21 May 2015 16:39:16 GMT
[ 0.019] recv (stream_id=1) content-type: text/html
[ 0.019] recv (stream_id=1) content-length: 6646
[ 0.019] recv (stream_id=1) last-modified: Fri, 15 May 2015 15:38:06 GMT
[ 0.019] recv (stream_id=1) etag: "555612de-19f6"
[ 0.019] recv (stream_id=1) link: </stylesheets/screen.css>; rel=preload; as=stylesheet
[ 0.019] recv (stream_id=1) accept-ranges: bytes
[ 0.019] recv (stream_id=1) server: nghttpx nghttp2/1.0.1-DEV
[ 0.019] recv (stream_id=1) via: 1.1 nghttpx
[ 0.019] recv HEADERS frame <length=157, flags=0x04, stream_id=1>
; END_HEADERS
(padlen=0)
; First response header
[ 0.019] recv DATA frame <length=6646, flags=0x01, stream_id=1>
; END_STREAM
[ 0.019] recv (stream_id=2) :status: 200
[ 0.019] recv (stream_id=2) date: Thu, 21 May 2015 16:39:16 GMT
[ 0.019] recv (stream_id=2) content-type: text/css
[ 0.019] recv (stream_id=2) content-length: 38981
[ 0.019] recv (stream_id=2) last-modified: Fri, 15 May 2015 15:38:06 GMT
[ 0.019] recv (stream_id=2) etag: "555612de-9845"
[ 0.019] recv (stream_id=2) accept-ranges: bytes
[ 0.019] recv (stream_id=2) server: nghttpx nghttp2/1.0.1-DEV
[ 0.019] recv (stream_id=2) via: 1.1 nghttpx
[ 0.019] recv HEADERS frame <length=36, flags=0x04, stream_id=2>
; END_HEADERS
(padlen=0)
; First push response header
[ 0.026] recv DATA frame <length=16384, flags=0x00, stream_id=2>
[ 0.027] recv DATA frame <length=7952, flags=0x00, stream_id=2>
[ 0.027] send WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=0>
(window_size_increment=33343)
[ 0.032] send WINDOW_UPDATE frame <length=4, flags=0x00, stream_id=2>
(window_size_increment=33707)
[ 0.032] recv DATA frame <length=14645, flags=0x01, stream_id=2>
; END_STREAM
[ 0.032] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[ 0.032] send GOAWAY frame <length=8, flags=0x00, stream_id=0>
(last_stream_id=2, error_code=NO_ERROR(0x00), opaque_data(0)=[])
Using the ``-s`` option, ``nghttp`` prints out some timing information for
requests, sorted by completion time:
.. code-block:: text
$ nghttp -nas https://nghttp2.org/
***** Statistics *****
Request timing:
responseEnd: the time when last byte of response was received
relative to connectEnd
requestStart: the time just before first byte of request was sent
relative to connectEnd. If '*' is shown, this was
pushed by server.
process: responseEnd - requestStart
code: HTTP status code
size: number of bytes received as response body without
inflation.
URI: request URI
see http://www.w3.org/TR/resource-timing/#processing-model
sorted by 'complete'
id responseEnd requestStart process code size request path
13 +37.19ms +280us 36.91ms 200 2K /
2 +72.65ms * +36.38ms 36.26ms 200 8K /stylesheets/screen.css
17 +77.43ms +38.67ms 38.75ms 200 3K /javascripts/octopress.js
15 +78.12ms +38.66ms 39.46ms 200 3K /javascripts/modernizr-2.0.js
Using the ``-r`` option, ``nghttp`` writes more detailed timing data to
the given file in HAR format.
nghttpd - server
++++++++++++++++
``nghttpd`` is a multi-threaded static web server.
By default, it uses SSL/TLS connection. Use ``--no-tls`` option to
disable it.
``nghttpd`` only accepts HTTP/2 connections via ALPN or direct HTTP/2
connections. No HTTP Upgrade is supported.
The ``-p`` option allows users to configure server push.
Just like ``nghttp``, it has a verbose output mode for framing
information. Here is sample output from ``nghttpd``:
.. code-block:: text
$ nghttpd --no-tls -v 8080
IPv4: listen 0.0.0.0:8080
IPv6: listen :::8080
[id=1] [ 1.521] send SETTINGS frame <length=6, flags=0x00, stream_id=0>
(niv=1)
[SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
[id=1] [ 1.521] recv SETTINGS frame <length=12, flags=0x00, stream_id=0>
(niv=2)
[SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
[SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
[id=1] [ 1.521] recv SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[id=1] [ 1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=3>
(dep_stream_id=0, weight=201, exclusive=0)
[id=1] [ 1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=5>
(dep_stream_id=0, weight=101, exclusive=0)
[id=1] [ 1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=7>
(dep_stream_id=0, weight=1, exclusive=0)
[id=1] [ 1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=9>
(dep_stream_id=7, weight=1, exclusive=0)
[id=1] [ 1.521] recv PRIORITY frame <length=5, flags=0x00, stream_id=11>
(dep_stream_id=3, weight=1, exclusive=0)
[id=1] [ 1.521] recv (stream_id=13) :method: GET
[id=1] [ 1.521] recv (stream_id=13) :path: /
[id=1] [ 1.521] recv (stream_id=13) :scheme: http
[id=1] [ 1.521] recv (stream_id=13) :authority: localhost:8080
[id=1] [ 1.521] recv (stream_id=13) accept: */*
[id=1] [ 1.521] recv (stream_id=13) accept-encoding: gzip, deflate
[id=1] [ 1.521] recv (stream_id=13) user-agent: nghttp2/1.0.0-DEV
[id=1] [ 1.521] recv HEADERS frame <length=41, flags=0x25, stream_id=13>
; END_STREAM | END_HEADERS | PRIORITY
(padlen=0, dep_stream_id=11, weight=16, exclusive=0)
; Open new stream
[id=1] [ 1.521] send SETTINGS frame <length=0, flags=0x01, stream_id=0>
; ACK
(niv=0)
[id=1] [ 1.521] send HEADERS frame <length=86, flags=0x04, stream_id=13>
; END_HEADERS
(padlen=0)
; First response header
:status: 200
server: nghttpd nghttp2/1.0.0-DEV
content-length: 10
cache-control: max-age=3600
date: Fri, 15 May 2015 14:49:04 GMT
last-modified: Tue, 30 Sep 2014 12:40:52 GMT
[id=1] [ 1.522] send DATA frame <length=10, flags=0x01, stream_id=13>
; END_STREAM
[id=1] [ 1.522] stream_id=13 closed
[id=1] [ 1.522] recv GOAWAY frame <length=8, flags=0x00, stream_id=0>
(last_stream_id=0, error_code=NO_ERROR(0x00), opaque_data(0)=[])
[id=1] [ 1.522] closed
nghttpx - proxy
+++++++++++++++
``nghttpx`` is a multi-threaded reverse proxy for HTTP/3, HTTP/2, and
HTTP/1.1, and powers http://nghttp2.org and supports HTTP/2 server
push.
We reworked ``nghttpx`` command-line interface, and as a result, there
are several incompatibles from 1.8.0 or earlier. This is necessary to
extend its capability, and secure the further feature enhancements in
the future release. Please read `Migration from nghttpx v1.8.0 or
earlier
<https://nghttp2.org/documentation/nghttpx-howto.html#migration-from-nghttpx-v1-8-0-or-earlier>`_
to know how to migrate from earlier releases.
``nghttpx`` implements `important performance-oriented features
<https://istlsfastyet.com/#server-performance>`_ in TLS, such as
session IDs, session tickets (with automatic key rotation), dynamic
record sizing, ALPN, forward secrecy and HTTP/2. ``nghttpx`` also
offers the functionality to share ticket keys among multiple
``nghttpx`` instances via memcached.
``nghttpx`` has 2 operation modes:
================== ======================== ================ =============
Mode option Frontend Backend Note
================== ======================== ================ =============
default mode HTTP/3, HTTP/2, HTTP/1.1 HTTP/1.1, HTTP/2 Reverse proxy
``--http2-proxy`` HTTP/3, HTTP/2, HTTP/1.1 HTTP/1.1, HTTP/2 Forward proxy
================== ======================== ================ =============
The interesting mode at the moment is the default mode. It works like
a reverse proxy and listens for HTTP/3, HTTP/2, and HTTP/1.1 and can
be deployed as a SSL/TLS terminator for existing web server.
In all modes, the frontend connections are encrypted by SSL/TLS by
default. To disable encryption, use the ``no-tls`` keyword in
``--frontend`` option. If encryption is disabled, incoming HTTP/1.1
connections can be upgraded to HTTP/2 through HTTP Upgrade. On the
other hard, backend connections are not encrypted by default. To
encrypt backend connections, use ``tls`` keyword in ``--backend``
option.
``nghttpx`` supports a configuration file. See the ``--conf`` option and
sample configuration file ``nghttpx.conf.sample``.
In the default mode, ``nghttpx`` works as reverse proxy to the backend
server:
.. code-block:: text
Client <-- (HTTP/3, HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/1.1, HTTP/2) --> Web Server
[reverse proxy]
With the ``--http2-proxy`` option, it works as forward proxy, and it
is so called secure HTTP/2 proxy:
.. code-block:: text
Client <-- (HTTP/3, HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy
[secure proxy] (e.g., Squid, ATS)
The ``Client`` in the above example needs to be configured to use
``nghttpx`` as secure proxy.
At the time of this writing, both Chrome and Firefox support secure
HTTP/2 proxy. One way to configure Chrome to use a secure proxy is to
create a proxy.pac script like this:
.. code-block:: javascript
function FindProxyForURL(url, host) {
return "HTTPS SERVERADDR:PORT";
}
``SERVERADDR`` and ``PORT`` is the hostname/address and port of the
machine nghttpx is running on. Please note that Chrome requires a valid
certificate for secure proxy.
Then run Chrome with the following arguments:
.. code-block:: text
$ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
The backend HTTP/2 connections can be tunneled through an HTTP proxy.
The proxy is specified using ``--backend-http-proxy-uri``. The
following figure illustrates how nghttpx talks to the outside HTTP/2
proxy through an HTTP proxy:
.. code-block:: text
Client <-- (HTTP/3, HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --
--===================---> HTTP/2 Proxy
(HTTP proxy tunnel) (e.g., nghttpx -s)
Benchmarking tool
-----------------
The ``h2load`` program is a benchmarking tool for HTTP/3, HTTP/2, and
HTTP/1.1. The UI of ``h2load`` is heavily inspired by ``weighttp``
(https://github.com/lighttpd/weighttp). The typical usage is as
follows:
.. code-block:: text
$ h2load -n100000 -c100 -m100 https://localhost:8443/
starting benchmark...
spawning thread #0: 100 concurrent clients, 100000 total requests
Protocol: TLSv1.2
Cipher: ECDHE-RSA-AES128-GCM-SHA256
Server Temp Key: ECDH P-256 256 bits
progress: 10% done
progress: 20% done
progress: 30% done
progress: 40% done
progress: 50% done
progress: 60% done
progress: 70% done
progress: 80% done
progress: 90% done
progress: 100% done
finished in 771.26ms, 129658 req/s, 4.71MB/s
requests: 100000 total, 100000 started, 100000 done, 100000 succeeded, 0 failed, 0 errored
status codes: 100000 2xx, 0 3xx, 0 4xx, 0 5xx
traffic: 3812300 bytes total, 1009900 bytes headers, 1000000 bytes data
min max mean sd +/- sd
time for request: 25.12ms 124.55ms 51.07ms 15.36ms 84.87%
time for connect: 208.94ms 254.67ms 241.38ms 7.95ms 63.00%
time to 1st byte: 209.11ms 254.80ms 241.51ms 7.94ms 63.00%
The above example issued total 100,000 requests, using 100 concurrent
clients (in other words, 100 HTTP/2 sessions), and a maximum of 100 streams
per client. With the ``-t`` option, ``h2load`` will use multiple native
threads to avoid saturating a single core on client side.
.. warning::
**Don't use this tool against publicly available servers.** That is
considered a DOS attack. Please only use it against your private
servers.
If the experimental HTTP/3 is enabled, h2load can send requests to
HTTP/3 server. To do this, specify ``h3`` to ``--alpn-list`` option
like so:
.. code-block:: text
$ h2load --alpn-list h3 https://127.0.0.1:4433
For nghttp2 v1.58 or earlier, use ``--npn-list`` instead of
``--alpn-list``.
HPACK tools
-----------
The ``src`` directory contains the HPACK tools. The ``deflatehd`` program is a
command-line header compression tool. The ``inflatehd`` program is a
command-line header decompression tool. Both tools read input from
stdin and write output to stdout. Errors are written to stderr.
They take JSON as input and output. We (mostly) use the same JSON data
format described at https://github.com/http2jp/hpack-test-case.
deflatehd - header compressor
+++++++++++++++++++++++++++++
The ``deflatehd`` program reads JSON data or HTTP/1-style header fields from
stdin and outputs compressed header block in JSON.
For the JSON input, the root JSON object must include a ``cases`` key.
Its value has to include the sequence of input header set. They share
the same compression context and are processed in the order they
appear. Each item in the sequence is a JSON object and it must
include a ``headers`` key. Its value is an array of JSON objects,
which includes exactly one name/value pair.
Example:
.. code-block:: json
{
"cases":
[
{
"headers": [
{ ":method": "GET" },
{ ":path": "/" }
]
},
{
"headers": [
{ ":method": "POST" },
{ ":path": "/" }
]
}
]
}
With the ``-t`` option, the program can accept more familiar HTTP/1 style
header field blocks. Each header set is delimited by an empty line:
Example:
.. code-block:: text
:method: GET
:scheme: https
:path: /
:method: POST
user-agent: nghttp2
The output is in JSON object. It should include a ``cases`` key and its
value is an array of JSON objects, which has at least the following keys:
seq
The index of header set in the input.
input_length
The sum of the length of the name/value pairs in the input.
output_length
The length of the compressed header block.
percentage_of_original_size
``output_length`` / ``input_length`` * 100
wire
The compressed header block as a hex string.
headers
The input header set.
header_table_size
The header table size adjusted before deflating the header set.
Examples:
.. code-block:: json
{
"cases":
[
{
"seq": 0,
"input_length": 66,
"output_length": 20,
"percentage_of_original_size": 30.303030303030305,
"wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
"headers": [
{
":authority": "example.org"
},
{
":method": "GET"
},
{
":path": "/"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096
}
,
{
"seq": 1,
"input_length": 74,
"output_length": 10,
"percentage_of_original_size": 13.513513513513514,
"wire": "88448504252dd5918485",
"headers": [
{
":authority": "example.org"
},
{
":method": "POST"
},
{
":path": "/account"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096
}
]
}
The output can be used as the input for ``inflatehd`` and
``deflatehd``.
With the ``-d`` option, the extra ``header_table`` key is added and its
associated value includes the state of dynamic header table after the
corresponding header set was processed. The value includes at least
the following keys:
entries
The entry in the header table. If ``referenced`` is ``true``, it
is in the reference set. The ``size`` includes the overhead (32
bytes). The ``index`` corresponds to the index of header table.
The ``name`` is the header field name and the ``value`` is the
header field value.
size
The sum of the spaces entries occupied, this includes the
entry overhead.
max_size
The maximum header table size.
deflate_size
The sum of the spaces entries occupied within
``max_deflate_size``.
max_deflate_size
The maximum header table size the encoder uses. This can be smaller
than ``max_size``. In this case, the encoder only uses up to first
``max_deflate_size`` buffer. Since the header table size is still
``max_size``, the encoder has to keep track of entries outside the
``max_deflate_size`` but inside the ``max_size`` and make sure
that they are no longer referenced.
Example:
.. code-block:: json
{
"cases":
[
{
"seq": 0,
"input_length": 66,
"output_length": 20,
"percentage_of_original_size": 30.303030303030305,
"wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
"headers": [
{
":authority": "example.org"
},
{
":method": "GET"
},
{
":path": "/"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096,
"header_table": {
"entries": [
{
"index": 1,
"name": "user-agent",
"value": "nghttp2",
"referenced": true,
"size": 49
},
{
"index": 2,
"name": ":scheme",
"value": "https",
"referenced": true,
"size": 44
},
{
"index": 3,
"name": ":path",
"value": "/",
"referenced": true,
"size": 38
},
{
"index": 4,
"name": ":method",
"value": "GET",
"referenced": true,
"size": 42
},
{
"index": 5,
"name": ":authority",
"value": "example.org",
"referenced": true,
"size": 53
}
],
"size": 226,
"max_size": 4096,
"deflate_size": 226,
"max_deflate_size": 4096
}
}
,
{
"seq": 1,
"input_length": 74,
"output_length": 10,
"percentage_of_original_size": 13.513513513513514,
"wire": "88448504252dd5918485",
"headers": [
{
":authority": "example.org"
},
{
":method": "POST"
},
{
":path": "/account"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096,
"header_table": {
"entries": [
{
"index": 1,
"name": ":method",
"value": "POST",
"referenced": true,
"size": 43
},
{
"index": 2,
"name": "user-agent",
"value": "nghttp2",
"referenced": true,
"size": 49
},
{
"index": 3,
"name": ":scheme",
"value": "https",
"referenced": true,
"size": 44
},
{
"index": 4,
"name": ":path",
"value": "/",
"referenced": false,
"size": 38
},
{
"index": 5,
"name": ":method",
"value": "GET",
"referenced": false,
"size": 42
},
{
"index": 6,
"name": ":authority",
"value": "example.org",
"referenced": true,
"size": 53
}
],
"size": 269,
"max_size": 4096,
"deflate_size": 269,
"max_deflate_size": 4096
}
}
]
}
inflatehd - header decompressor
+++++++++++++++++++++++++++++++
The ``inflatehd`` program reads JSON data from stdin and outputs decompressed
name/value pairs in JSON.
The root JSON object must include the ``cases`` key. Its value has to
include the sequence of compressed header blocks. They share the same
compression context and are processed in the order they appear. Each
item in the sequence is a JSON object and it must have at least a
``wire`` key. Its value is a compressed header block as a hex string.
Example:
.. code-block:: json
{
"cases":
[
{ "wire": "8285" },
{ "wire": "8583" }
]
}
The output is a JSON object. It should include a ``cases`` key and its
value is an array of JSON objects, which has at least following keys:
seq
The index of the header set in the input.
headers
A JSON array that includes decompressed name/value pairs.
wire
The compressed header block as a hex string.
header_table_size
The header table size adjusted before inflating compressed header
block.
Example:
.. code-block:: json
{
"cases":
[
{
"seq": 0,
"wire": "01881f3468e5891afcbf83868a3d856659c62e3f",
"headers": [
{
":authority": "example.org"
},
{
":method": "GET"
},
{
":path": "/"
},
{
":scheme": "https"
},
{
"user-agent": "nghttp2"
}
],
"header_table_size": 4096
}
,
{
"seq": 1,
"wire": "88448504252dd5918485",
"headers": [
{
":method": "POST"
},
{
":path": "/account"
},
{
"user-agent": "nghttp2"
},
{
":scheme": "https"
},
{
":authority": "example.org"
}
],
"header_table_size": 4096
}
]
}
The output can be used as the input for ``deflatehd`` and
``inflatehd``.
With the ``-d`` option, the extra ``header_table`` key is added and its
associated value includes the state of the dynamic header table after the
corresponding header set was processed. The format is the same as
``deflatehd``.
Contribution
------------
[This text was composed based on 1.2. License section of curl/libcurl
project.]
When contributing with code, you agree to put your changes and new
code under the same license nghttp2 is already using unless stated and
agreed otherwise.
When changing existing source code, do not alter the copyright of
the original file(s). The copyright will still be owned by the
original creator(s) or those who have been assigned copyright by the
original author(s).
By submitting a patch to the nghttp2 project, you (or your employer, as
the case may be) agree to assign the copyright of your submission to us.
.. the above really needs to be reworded to pass legal muster.
We will credit you for your
changes as far as possible, to give credit but also to keep a trace
back to who made what changes. Please always provide us with your
full real name when contributing!
See `Contribution Guidelines
<https://nghttp2.org/documentation/contribute.html>`_ for more
details.
Versioning
----------
In general, we follow `Semantic Versioning <http://semver.org/>`_.
We may release PATCH releases between the regular releases, mainly for
severe security bug fixes.
We have no plan to break API compatibility changes involving soname
bump, so MAJOR version will stay 1 for the foreseeable future.
License
-------
The MIT License
share/man/man1/nghttpx.1 0000644 00000261721 15053606574 0011057 0 ustar 00 .\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "NGHTTPX" "1" "Jun 17, 2025" "1.66.0" "nghttp2"
.SH NAME
nghttpx \- HTTP/2 proxy
.SH SYNOPSIS
.sp
\fBnghttpx\fP [OPTIONS]... [<PRIVATE_KEY> <CERT>]
.SH DESCRIPTION
.sp
A reverse proxy for HTTP/3, HTTP/2, and HTTP/1.
.INDENT 0.0
.TP
.B <PRIVATE_KEY>
Set path to server\(aqs private key. Required unless
\(dqno\-tls\(dq parameter is used in \fI\%\-\-frontend\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B <CERT>
Set path to server\(aqs certificate. Required unless
\(dqno\-tls\(dq parameter is used in \fI\%\-\-frontend\fP option.
.UNINDENT
.SH OPTIONS
.sp
The options are categorized into several groups.
.SS Connections
.INDENT 0.0
.TP
.B \-b, \-\-backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PATTERN>[:...]][[;<PARAM>]...]
Set backend host and port. The multiple backend
addresses are accepted by repeating this option. UNIX
domain socket can be specified by prefixing path name
with \(dqunix:\(dq (e.g., unix:/var/run/backend.sock).
.sp
Optionally, if <PATTERN>s are given, the backend address
is only used if request matches the pattern. The
pattern matching is closely designed to ServeMux in
net/http package of Go programming language. <PATTERN>
consists of path, host + path or just host. The path
must start with \(dq\fI/\fP\(dq. If it ends with \(dq\fI/\fP\(dq, it matches
all request path in its subtree. To deal with the
request to the directory without trailing slash, the
path which ends with \(dq\fI/\fP\(dq also matches the request path
which only lacks trailing \(aq\fI/\fP\(aq (e.g., path \(dq\fI/foo/\fP\(dq
matches request path \(dq\fI/foo\fP\(dq). If it does not end with
\(dq\fI/\fP\(dq, it performs exact match against the request path.
If host is given, it performs a match against the
request host. For a request received on the frontend
listener with \(dqsni\-fwd\(dq parameter enabled, SNI host is
used instead of a request host. If host alone is given,
\(dq\fI/\fP\(dq is appended to it, so that it matches all request
paths under the host (e.g., specifying \(dqnghttp2.org\(dq
equals to \(dqnghttp2.org/\(dq). CONNECT method is treated
specially. It does not have path, and we don\(aqt allow
empty path. To workaround this, we assume that CONNECT
method has \(dq\fI/\fP\(dq as path.
.sp
Patterns with host take precedence over patterns with
just path. Then, longer patterns take precedence over
shorter ones.
.sp
Host can include \(dq*\(dq in the left most position to
indicate wildcard match (only suffix match is done).
The \(dq*\(dq must match at least one character. For example,
host pattern \(dq*.nghttp2.org\(dq matches against
\(dqwww.nghttp2.org\(dq and \(dqgit.ngttp2.org\(dq, but does not
match against \(dqnghttp2.org\(dq. The exact hosts match
takes precedence over the wildcard hosts match.
.sp
If path part ends with \(dq*\(dq, it is treated as wildcard
path. The wildcard path behaves differently from the
normal path. For normal path, match is made around the
boundary of path component separator,\(dq\fI/\fP\(dq. On the other
hand, the wildcard path does not take into account the
path component separator. All paths which include the
wildcard path without last \(dq*\(dq as prefix, and are
strictly longer than wildcard path without last \(dq*\(dq are
matched. \(dq*\(dq must match at least one character. For
example, the pattern \(dq\fI/foo*\fP\(dq matches \(dq\fI/foo/\fP\(dq and
\(dq\fI/foobar\fP\(dq. But it does not match \(dq\fI/foo\fP\(dq, or \(dq\fI/fo\fP\(dq.
.sp
If <PATTERN> is omitted or empty string, \(dq\fI/\fP\(dq is used as
pattern, which matches all request paths (catch\-all
pattern). The catch\-all backend must be given.
.sp
When doing a match, nghttpx made some normalization to
pattern, request host and path. For host part, they are
converted to lower case. For path part, percent\-encoded
unreserved characters defined in RFC 3986 are decoded,
and any dot\-segments (\(dq..\(dq and \(dq.\(dq) are resolved and
removed.
.sp
For example, \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org/httpbin/\(aq
matches the request host \(dqnghttp2.org\(dq and the request
path \(dq\fI/httpbin/get\fP\(dq, but does not match the request host
\(dqnghttp2.org\(dq and the request path \(dq\fI/index.html\fP\(dq.
.sp
The multiple <PATTERN>s can be specified, delimiting
them by \(dq:\(dq. Specifying
\fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org:www.nghttp2.org\(aq has the
same effect to specify \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org\(aq
and \fI\%\-b\fP\(aq127.0.0.1,8080;www.nghttp2.org\(aq.
.sp
The backend addresses sharing same <PATTERN> are grouped
together forming load balancing group.
.sp
Several parameters <PARAM> are accepted after <PATTERN>.
The parameters are delimited by \(dq;\(dq. The available
parameters are: \(dqproto=<PROTO>\(dq, \(dqtls\(dq,
\(dqsni=<SNI_HOST>\(dq, \(dqfall=<N>\(dq, \(dqrise=<N>\(dq,
\(dqaffinity=<METHOD>\(dq, \(dqdns\(dq, \(dqredirect\-if\-not\-tls\(dq,
\(dqupgrade\-scheme\(dq, \(dqmruby=<PATH>\(dq,
\(dqread\-timeout=<DURATION>\(dq, \(dqwrite\-timeout=<DURATION>\(dq,
\(dqgroup=<GROUP>\(dq, \(dqgroup\-weight=<N>\(dq, \(dqweight=<N>\(dq, and
\(dqdnf\(dq. The parameter consists of keyword, and
optionally followed by \(dq=\(dq and value. For example, the
parameter \(dqproto=h2\(dq consists of the keyword \(dqproto\(dq and
value \(dqh2\(dq. The parameter \(dqtls\(dq consists of the keyword
\(dqtls\(dq without value. Each parameter is described as
follows.
.sp
The backend application protocol can be specified using
optional \(dqproto\(dq parameter, and in the form of
\(dqproto=<PROTO>\(dq. <PROTO> should be one of the following
list without quotes: \(dqh2\(dq, \(dqhttp/1.1\(dq. The default
value of <PROTO> is \(dqhttp/1.1\(dq. Note that usually \(dqh2\(dq
refers to HTTP/2 over TLS. But in this option, it may
mean HTTP/2 over cleartext TCP unless \(dqtls\(dq keyword is
used (see below).
.sp
TLS can be enabled by specifying optional \(dqtls\(dq
parameter. TLS is not enabled by default.
.sp
With \(dqsni=<SNI_HOST>\(dq parameter, it can override the TLS
SNI field value with given <SNI_HOST>. This will
default to the backend <HOST> name
.sp
The feature to detect whether backend is online or
offline can be enabled using optional \(dqfall\(dq and \(dqrise\(dq
parameters. Using \(dqfall=<N>\(dq parameter, if nghttpx
cannot connect to a this backend <N> times in a row,
this backend is assumed to be offline, and it is
excluded from load balancing. If <N> is 0, this backend
never be excluded from load balancing whatever times
nghttpx cannot connect to it, and this is the default.
There is also \(dqrise=<N>\(dq parameter. After backend was
excluded from load balancing group, nghttpx periodically
attempts to make a connection to the failed backend, and
if the connection is made successfully <N> times in a
row, the backend is assumed to be online, and it is now
eligible for load balancing target. If <N> is 0, a
backend is permanently offline, once it goes in that
state, and this is the default behaviour.
.sp
The session affinity is enabled using
\(dqaffinity=<METHOD>\(dq parameter. If \(dqip\(dq is given in
<METHOD>, client IP based session affinity is enabled.
If \(dqcookie\(dq is given in <METHOD>, cookie based session
affinity is enabled. If \(dqnone\(dq is given in <METHOD>,
session affinity is disabled, and this is the default.
The session affinity is enabled per <PATTERN>. If at
least one backend has \(dqaffinity\(dq parameter, and its
<METHOD> is not \(dqnone\(dq, session affinity is enabled for
all backend servers sharing the same <PATTERN>. It is
advised to set \(dqaffinity\(dq parameter to all backend
explicitly if session affinity is desired. The session
affinity may break if one of the backend gets
unreachable, or backend settings are reloaded or
replaced by API.
.sp
If \(dqaffinity=cookie\(dq is used, the additional
configuration is required.
\(dqaffinity\-cookie\-name=<NAME>\(dq must be used to specify a
name of cookie to use. Optionally,
\(dqaffinity\-cookie\-path=<PATH>\(dq can be used to specify a
path which cookie is applied. The optional
\(dqaffinity\-cookie\-secure=<SECURE>\(dq controls the Secure
attribute of a cookie. The default value is \(dqauto\(dq, and
the Secure attribute is determined by a request scheme.
If a request scheme is \(dqhttps\(dq, then Secure attribute is
set. Otherwise, it is not set. If <SECURE> is \(dqyes\(dq,
the Secure attribute is always set. If <SECURE> is
\(dqno\(dq, the Secure attribute is always omitted.
\(dqaffinity\-cookie\-stickiness=<STICKINESS>\(dq controls
stickiness of this affinity. If <STICKINESS> is
\(dqloose\(dq, removing or adding a backend server might break
the affinity and the request might be forwarded to a
different backend server. If <STICKINESS> is \(dqstrict\(dq,
removing the designated backend server breaks affinity,
but adding new backend server does not cause breakage.
If the designated backend server becomes unavailable,
new backend server is chosen as if the request does not
have an affinity cookie. <STICKINESS> defaults to
\(dqloose\(dq.
.sp
By default, name resolution of backend host name is done
at start up, or reloading configuration. If \(dqdns\(dq
parameter is given, name resolution takes place
dynamically. This is useful if backend address changes
frequently. If \(dqdns\(dq is given, name resolution of
backend host name at start up, or reloading
configuration is skipped.
.sp
If \(dqredirect\-if\-not\-tls\(dq parameter is used, the matched
backend requires that frontend connection is TLS
encrypted. If it isn\(aqt, nghttpx responds to the request
with 308 status code, and https URI the client should
use instead is included in Location header field. The
port number in redirect URI is 443 by default, and can
be changed using \fI\%\-\-redirect\-https\-port\fP option. If at
least one backend has \(dqredirect\-if\-not\-tls\(dq parameter,
this feature is enabled for all backend servers sharing
the same <PATTERN>. It is advised to set
\(dqredirect\-if\-no\-tls\(dq parameter to all backends
explicitly if this feature is desired.
.sp
If \(dqupgrade\-scheme\(dq parameter is used along with \(dqtls\(dq
parameter, HTTP/2 :scheme pseudo header field is changed
to \(dqhttps\(dq from \(dqhttp\(dq when forwarding a request to this
particular backend. This is a workaround for a backend
server which requires \(dqhttps\(dq :scheme pseudo header
field on TLS encrypted connection.
.sp
\(dqmruby=<PATH>\(dq parameter specifies a path to mruby
script file which is invoked when this pattern is
matched. All backends which share the same pattern must
have the same mruby path.
.sp
\(dqread\-timeout=<DURATION>\(dq and \(dqwrite\-timeout=<DURATION>\(dq
parameters specify the read and write timeout of the
backend connection when this pattern is matched. All
backends which share the same pattern must have the same
timeouts. If these timeouts are entirely omitted for a
pattern, \fI\%\-\-backend\-read\-timeout\fP and
\fI\%\-\-backend\-write\-timeout\fP are used.
.sp
\(dqgroup=<GROUP>\(dq parameter specifies the name of group
this backend address belongs to. By default, it belongs
to the unnamed default group. The name of group is
unique per pattern. \(dqgroup\-weight=<N>\(dq parameter
specifies the weight of the group. The higher weight
gets more frequently selected by the load balancing
algorithm. <N> must be [1, 256] inclusive. The weight
8 has 4 times more weight than 2. <N> must be the same
for all addresses which share the same <GROUP>. If
\(dqgroup\-weight\(dq is omitted in an address, but the other
address which belongs to the same group specifies
\(dqgroup\-weight\(dq, its weight is used. If no
\(dqgroup\-weight\(dq is specified for all addresses, the
weight of a group becomes 1. \(dqgroup\(dq and \(dqgroup\-weight\(dq
are ignored if session affinity is enabled.
.sp
\(dqweight=<N>\(dq parameter specifies the weight of the
backend address inside a group which this address
belongs to. The higher weight gets more frequently
selected by the load balancing algorithm. <N> must be
[1, 256] inclusive. The weight 8 has 4 times more
weight than weight 2. If this parameter is omitted,
weight becomes 1. \(dqweight\(dq is ignored if session
affinity is enabled.
.sp
If \(dqdnf\(dq parameter is specified, an incoming request is
not forwarded to a backend and just consumed along with
the request body (actually a backend server never be
contacted). It is expected that the HTTP response is
generated by mruby script (see \(dqmruby=<PATH>\(dq parameter
above). \(dqdnf\(dq is an abbreviation of \(dqdo not forward\(dq.
.sp
Since \(dq;\(dq and \(dq:\(dq are used as delimiter, <PATTERN> must
not contain these characters. In order to include \(dq:\(dq
in <PATTERN>, one has to specify \(dq%3A\(dq (which is
percent\-encoded from of \(dq:\(dq) instead. Since \(dq;\(dq has
special meaning in shell, the option value must be
quoted.
.sp
Default: \fB127.0.0.1,80\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-f, \-\-frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
Set frontend host and port. If <HOST> is \(aq*\(aq, it
assumes all addresses including both IPv4 and IPv6.
UNIX domain socket can be specified by prefixing path
name with \(dqunix:\(dq (e.g., unix:/var/run/nghttpx.sock).
This option can be used multiple times to listen to
multiple addresses.
.sp
This option can take 0 or more parameters, which are
described below. Note that \(dqapi\(dq and \(dqhealthmon\(dq
parameters are mutually exclusive.
.sp
Optionally, TLS can be disabled by specifying \(dqno\-tls\(dq
parameter. TLS is enabled by default.
.sp
If \(dqsni\-fwd\(dq parameter is used, when performing a match
to select a backend server, SNI host name received from
the client is used instead of the request host. See
\fI\%\-\-backend\fP option about the pattern match.
.sp
To make this frontend as API endpoint, specify \(dqapi\(dq
parameter. This is disabled by default. It is
important to limit the access to the API frontend.
Otherwise, someone may change the backend server, and
break your services, or expose confidential information
to the outside the world.
.sp
To make this frontend as health monitor endpoint,
specify \(dqhealthmon\(dq parameter. This is disabled by
default. Any requests which come through this address
are replied with 200 HTTP status, without no body.
.sp
To accept PROXY protocol version 1 and 2 on frontend
connection, specify \(dqproxyproto\(dq parameter. This is
disabled by default.
.sp
To receive HTTP/3 (QUIC) traffic, specify \(dqquic\(dq
parameter. It makes nghttpx listen on UDP port rather
than TCP port. UNIX domain socket, \(dqapi\(dq, and
\(dqhealthmon\(dq parameters cannot be used with \(dqquic\(dq
parameter.
.sp
Default: \fB*,3000\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backlog=<N>
Set listen backlog size.
.sp
Default: \fB65536\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-address\-family=(auto|IPv4|IPv6)
Specify address family of backend connections. If
\(dqauto\(dq is given, both IPv4 and IPv6 are considered. If
\(dqIPv4\(dq is given, only IPv4 address is considered. If
\(dqIPv6\(dq is given, only IPv6 address is considered.
.sp
Default: \fBauto\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-http\-proxy\-uri=<URI>
Specify proxy URI in the form
\X'tty: link http:/'\fI\%http:/\fP\X'tty: link'/[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy
requires authentication, specify <USER> and <PASS>.
Note that they must be properly percent\-encoded. This
proxy is used when the backend connection is HTTP/2.
First, make a CONNECT request to the proxy and it
connects to the backend on behalf of nghttpx. This
forms tunnel. After that, nghttpx performs SSL/TLS
handshake with the downstream through the tunnel. The
timeouts when connecting and making CONNECT request can
be specified by \fI\%\-\-backend\-read\-timeout\fP and
\fI\%\-\-backend\-write\-timeout\fP options.
.UNINDENT
.SS Performance
.INDENT 0.0
.TP
.B \-n, \-\-workers=<N>
Set the number of worker threads.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-single\-thread
Run everything in one thread inside the worker process.
This feature is provided for better debugging
experience, or for the platforms which lack thread
support. If threading is disabled, this option is
always enabled.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-read\-rate=<SIZE>
Set maximum average read rate on frontend connection.
Setting 0 to this option means read rate is unlimited.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-read\-burst=<SIZE>
Set maximum read burst size on frontend connection.
Setting 0 to this option means read burst size is
unlimited.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-write\-rate=<SIZE>
Set maximum average write rate on frontend connection.
Setting 0 to this option means write rate is unlimited.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-write\-burst=<SIZE>
Set maximum write burst size on frontend connection.
Setting 0 to this option means write burst size is
unlimited.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-worker\-read\-rate=<SIZE>
Set maximum average read rate on frontend connection per
worker. Setting 0 to this option means read rate is
unlimited. Not implemented yet.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-worker\-read\-burst=<SIZE>
Set maximum read burst size on frontend connection per
worker. Setting 0 to this option means read burst size
is unlimited. Not implemented yet.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-worker\-write\-rate=<SIZE>
Set maximum average write rate on frontend connection
per worker. Setting 0 to this option means write rate
is unlimited. Not implemented yet.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-worker\-write\-burst=<SIZE>
Set maximum write burst size on frontend connection per
worker. Setting 0 to this option means write burst size
is unlimited. Not implemented yet.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-worker\-frontend\-connections=<N>
Set maximum number of simultaneous connections frontend
accepts. Setting 0 means unlimited.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-connections\-per\-host=<N>
Set maximum number of backend concurrent connections
(and/or streams in case of HTTP/2) per origin host.
This option is meaningful when \fI\%\-\-http2\-proxy\fP option is
used. The origin host is determined by authority
portion of request URI (or :authority header field for
HTTP/2). To limit the number of connections per
frontend for default mode, use
\fI\%\-\-backend\-connections\-per\-frontend\fP\&.
.sp
Default: \fB8\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-connections\-per\-frontend=<N>
Set maximum number of backend concurrent connections
(and/or streams in case of HTTP/2) per frontend. This
option is only used for default mode. 0 means
unlimited. To limit the number of connections per host
with \fI\%\-\-http2\-proxy\fP option, use
\fI\%\-\-backend\-connections\-per\-host\fP\&.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rlimit\-nofile=<N>
Set maximum number of open files (RLIMIT_NOFILE) to <N>.
If 0 is given, nghttpx does not set the limit.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rlimit\-memlock=<N>
Set maximum number of bytes of memory that may be locked
into RAM. If 0 is given, nghttpx does not set the
limit.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-request\-buffer=<SIZE>
Set buffer size used to store backend request.
.sp
Default: \fB16K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-response\-buffer=<SIZE>
Set buffer size used to store backend response.
.sp
Default: \fB128K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-fastopen=<N>
Enables \(dqTCP Fast Open\(dq for the listening socket and
limits the maximum length for the queue of connections
that have not yet completed the three\-way handshake. If
value is 0 then fast open is disabled.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-kqueue
Don\(aqt use kqueue. This option is only applicable for
the platforms which have kqueue. For other platforms,
this option will be simply ignored.
.UNINDENT
.SS Timeout
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-idle\-timeout=<DURATION>
Specify idle timeout for HTTP/2 frontend connection. If
no active streams exist for this duration, connection is
closed.
.sp
Default: \fB3m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http3\-idle\-timeout=<DURATION>
Specify idle timeout for HTTP/3 frontend connection. If
no active streams exist for this duration, connection is
closed.
.sp
Default: \fB3m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-write\-timeout=<DURATION>
Specify write timeout for all frontend connections.
.sp
Default: \fB30s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-keep\-alive\-timeout=<DURATION>
Specify keep\-alive timeout for frontend HTTP/1
connection.
.sp
Default: \fB1m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-header\-timeout=<DURATION>
Specify duration that the server waits for an HTTP
request header fields to be received completely. On
timeout, HTTP/1 and HTTP/2 connections are closed. For
HTTP/3, the stream is shutdown, and the connection
itself is left intact.
.sp
Default: \fB1m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-stream\-read\-timeout=<DURATION>
Specify read timeout for HTTP/2 streams. 0 means no
timeout.
.sp
Default: \fB0\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-stream\-write\-timeout=<DURATION>
Specify write timeout for HTTP/2 streams. 0 means no
timeout.
.sp
Default: \fB1m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-read\-timeout=<DURATION>
Specify read timeout for backend connection.
.sp
Default: \fB1m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-write\-timeout=<DURATION>
Specify write timeout for backend connection.
.sp
Default: \fB30s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-connect\-timeout=<DURATION>
Specify timeout before establishing TCP connection to
backend.
.sp
Default: \fB30s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-keep\-alive\-timeout=<DURATION>
Specify keep\-alive timeout for backend HTTP/1
connection.
.sp
Default: \fB2s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-listener\-disable\-timeout=<DURATION>
After accepting connection failed, connection listener
is disabled for a given amount of time. Specifying 0
disables this feature.
.sp
Default: \fB30s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-setting\-timeout=<DURATION>
Specify timeout before SETTINGS ACK is received from
client.
.sp
Default: \fB10s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-http2\-settings\-timeout=<DURATION>
Specify timeout before SETTINGS ACK is received from
backend server.
.sp
Default: \fB10s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-max\-backoff=<DURATION>
Specify maximum backoff interval. This is used when
doing health check against offline backend (see \(dqfail\(dq
parameter in \fI\%\-\-backend\fP option). It is also used to
limit the maximum interval to temporarily disable
backend when nghttpx failed to connect to it. These
intervals are calculated using exponential backoff, and
consecutive failed attempts increase the interval. This
option caps its maximum value.
.sp
Default: \fB2m\fP
.UNINDENT
.SS SSL/TLS
.INDENT 0.0
.TP
.B \-\-ciphers=<SUITE>
Set allowed cipher list for frontend connection. The
format of the string is described in OpenSSL ciphers(1).
This option sets cipher suites for TLSv1.2 or earlier.
Use \fI\%\-\-tls13\-ciphers\fP for TLSv1.3.
.sp
Default: \fBECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-RSA\-AES256\-GCM\-SHA384\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls13\-ciphers=<SUITE>
Set allowed cipher list for frontend connection. The
format of the string is described in OpenSSL ciphers(1).
This option sets cipher suites for TLSv1.3. Use
\fI\%\-\-ciphers\fP for TLSv1.2 or earlier.
.sp
Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-client\-ciphers=<SUITE>
Set allowed cipher list for backend connection. The
format of the string is described in OpenSSL ciphers(1).
This option sets cipher suites for TLSv1.2 or earlier.
Use \fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.3.
.sp
Default: \fBECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-RSA\-AES256\-GCM\-SHA384\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls13\-client\-ciphers=<SUITE>
Set allowed cipher list for backend connection. The
format of the string is described in OpenSSL ciphers(1).
This option sets cipher suites for TLSv1.3. Use
\fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.2 or earlier.
.sp
Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ecdh\-curves=<LIST>
Set supported curve list for frontend connections.
<LIST> is a colon separated list of curve NID or names
in the preference order. The supported curves depend on
the linked OpenSSL library. This function requires
OpenSSL >= 1.0.2.
.sp
Default: \fBX25519:P\-256:P\-384:P\-521\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-k, \-\-insecure
Don\(aqt verify backend server\(aqs certificate if TLS is
enabled for backend connections.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-cacert=<PATH>
Set path to trusted CA certificate file. It is used in
backend TLS connections to verify peer\(aqs certificate.
The file must be in PEM format. It can contain multiple
certificates. If the linked OpenSSL is configured to
load system wide certificates, they are loaded at
startup regardless of this option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-private\-key\-passwd\-file=<PATH>
Path to file that contains password for the server\(aqs
private key. If none is given and the private key is
password protected it\(aqll be requested interactively.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
Specify additional certificate and private key file.
nghttpx will choose certificates based on the hostname
indicated by client using TLS SNI extension. If nghttpx
is built with OpenSSL >= 1.0.2, the shared elliptic
curves (e.g., P\-256) between client and server are also
taken into consideration. This allows nghttpx to send
ECDSA certificate to modern clients, while sending RSA
based certificate to older clients. This option can be
used multiple times.
.sp
Additional parameter can be specified in <PARAM>. The
available <PARAM> is \(dqsct\-dir=<DIR>\(dq.
.sp
\(dqsct\-dir=<DIR>\(dq specifies the path to directory which
contains *.sct files for TLS
signed_certificate_timestamp extension (RFC 6962). This
feature requires OpenSSL >= 1.0.2. See also
\fI\%\-\-tls\-sct\-dir\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dh\-param\-file=<PATH>
Path to file that contains DH parameters in PEM format.
Without this option, DHE cipher suites are not
available.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-alpn\-list=<LIST>
Comma delimited list of ALPN protocol identifier sorted
in the order of preference. That means most desirable
protocol comes first. The parameter must be delimited
by a single comma only and any white spaces are treated
as a part of protocol string.
.sp
Default: \fBh2,http/1.1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-verify\-client
Require and verify client certificate.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-verify\-client\-cacert=<PATH>
Path to file that contains CA certificates to verify
client certificate. The file must be in PEM format. It
can contain multiple certificates.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-verify\-client\-tolerate\-expired
Accept expired client certificate. Operator should
handle the expired client certificate by some means
(e.g., mruby script). Otherwise, this option might
cause a security risk.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-client\-private\-key\-file=<PATH>
Path to file that contains client private key used in
backend client authentication.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-client\-cert\-file=<PATH>
Path to file that contains client certificate used in
backend client authentication.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-min\-proto\-version=<VER>
Specify minimum SSL/TLS protocol. The name matching is
done in case\-insensitive manner. The versions between
\fI\%\-\-tls\-min\-proto\-version\fP and \fI\%\-\-tls\-max\-proto\-version\fP are
enabled. If the protocol list advertised by client does
not overlap this range, you will receive the error
message \(dqunknown protocol\(dq. If a protocol version lower
than TLSv1.2 is specified, make sure that the compatible
ciphers are included in \fI\%\-\-ciphers\fP option. The default
cipher list only includes ciphers compatible with
TLSv1.2 or above. The available versions are:
TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
.sp
Default: \fBTLSv1.2\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-max\-proto\-version=<VER>
Specify maximum SSL/TLS protocol. The name matching is
done in case\-insensitive manner. The versions between
\fI\%\-\-tls\-min\-proto\-version\fP and \fI\%\-\-tls\-max\-proto\-version\fP are
enabled. If the protocol list advertised by client does
not overlap this range, you will receive the error
message \(dqunknown protocol\(dq. The available versions are:
TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
.sp
Default: \fBTLSv1.3\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-file=<PATH>
Path to file that contains random data to construct TLS
session ticket parameters. If aes\-128\-cbc is given in
\fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly
48 bytes. If aes\-256\-cbc is given in
\fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly
80 bytes. This options can be used repeatedly to
specify multiple ticket parameters. If several files
are given, only the first key is used to encrypt TLS
session tickets. Other keys are accepted but server
will issue new session ticket with first key. This
allows session key rotation. Please note that key
rotation does not occur automatically. User should
rearrange files or change options values and restart
nghttpx gracefully. If opening or reading given file
fails, all loaded keys are discarded and it is treated
as if none of this option is given. If this option is
not given or an error occurred while opening or reading
a file, key is generated every 1 hour internally and
they are valid for 12 hours. This is recommended if
ticket key sharing between nghttpx instances is not
required.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached=<HOST>,<PORT>[;tls]
Specify address of memcached server to get TLS ticket
keys for session resumption. This enables shared TLS
ticket key between multiple nghttpx instances. nghttpx
does not set TLS ticket key to memcached. The external
ticket key generator is required. nghttpx just gets TLS
ticket keys from memcached, and use them, possibly
replacing current set of keys. It is up to extern TLS
ticket key generator to rotate keys frequently. See
\(dqTLS SESSION TICKET RESUMPTION\(dq section in manual page
to know the data format in memcached entry. Optionally,
memcached connection can be encrypted with TLS by
specifying \(dqtls\(dq parameter.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-address\-family=(auto|IPv4|IPv6)
Specify address family of memcached connections to get
TLS ticket keys. If \(dqauto\(dq is given, both IPv4 and IPv6
are considered. If \(dqIPv4\(dq is given, only IPv4 address
is considered. If \(dqIPv6\(dq is given, only IPv6 address is
considered.
.sp
Default: \fBauto\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-interval=<DURATION>
Set interval to get TLS ticket keys from memcached.
.sp
Default: \fB10m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-max\-retry=<N>
Set maximum number of consecutive retries before
abandoning TLS ticket key retrieval. If this number is
reached, the attempt is considered as failure, and
\(dqfailure\(dq count is incremented by 1, which contributed
to the value controlled
\fI\%\-\-tls\-ticket\-key\-memcached\-max\-fail\fP option.
.sp
Default: \fB3\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-max\-fail=<N>
Set maximum number of consecutive failure before
disabling TLS ticket until next scheduled key retrieval.
.sp
Default: \fB2\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-cipher=<CIPHER>
Specify cipher to encrypt TLS session ticket. Specify
either aes\-128\-cbc or aes\-256\-cbc. By default,
aes\-128\-cbc is used.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-cert\-file=<PATH>
Path to client certificate for memcached connections to
get TLS ticket keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-private\-key\-file=<PATH>
Path to client private key for memcached connections to
get TLS ticket keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-dyn\-rec\-warmup\-threshold=<SIZE>
Specify the threshold size for TLS dynamic record size
behaviour. During a TLS session, after the threshold
number of bytes have been written, the TLS record size
will be increased to the maximum allowed (16K). The max
record size will continue to be used on the active TLS
session. After \fI\%\-\-tls\-dyn\-rec\-idle\-timeout\fP has elapsed,
the record size is reduced to 1300 bytes. Specify 0 to
always use the maximum record size, regardless of idle
period. This behaviour applies to all TLS based
frontends, and TLS HTTP/2 backends.
.sp
Default: \fB1M\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-dyn\-rec\-idle\-timeout=<DURATION>
Specify TLS dynamic record size behaviour timeout. See
\fI\%\-\-tls\-dyn\-rec\-warmup\-threshold\fP for more information.
This behaviour applies to all TLS based frontends, and
TLS HTTP/2 backends.
.sp
Default: \fB1s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-http2\-cipher\-block\-list
Allow block listed cipher suite on frontend HTTP/2
connection. See
\X'tty: link https://tools.ietf.org/html/rfc7540#appendix-A'\fI\%https://tools.ietf.org/html/rfc7540#appendix\-A\fP\X'tty: link' for the
complete HTTP/2 cipher suites block list.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-client\-no\-http2\-cipher\-block\-list
Allow block listed cipher suite on backend HTTP/2
connection. See
\X'tty: link https://tools.ietf.org/html/rfc7540#appendix-A'\fI\%https://tools.ietf.org/html/rfc7540#appendix\-A\fP\X'tty: link' for the
complete HTTP/2 cipher suites block list.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-sct\-dir=<DIR>
Specifies the directory where *.sct files exist. All
*.sct files in <DIR> are read, and sent as
extension_data of TLS signed_certificate_timestamp (RFC
6962) to client. These *.sct files are for the
certificate specified in positional command\-line
argument <CERT>, or certificate option in configuration
file. For additional certificates, use \fI\%\-\-subcert\fP
option. This option requires OpenSSL >= 1.0.2.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-psk\-secrets=<PATH>
Read list of PSK identity and secrets from <PATH>. This
is used for frontend connection. The each line of input
file is formatted as <identity>:<hex\-secret>, where
<identity> is PSK identity, and <hex\-secret> is secret
in hex. An empty line, and line which starts with \(aq#\(aq
are skipped. The default enabled cipher list might not
contain any PSK cipher suite. In that case, desired PSK
cipher suites must be enabled using \fI\%\-\-ciphers\fP option.
The desired PSK cipher suite may be block listed by
HTTP/2. To use those cipher suites with HTTP/2,
consider to use \fI\%\-\-no\-http2\-cipher\-block\-list\fP option.
But be aware its implications.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-client\-psk\-secrets=<PATH>
Read PSK identity and secrets from <PATH>. This is used
for backend connection. The each line of input file is
formatted as <identity>:<hex\-secret>, where <identity>
is PSK identity, and <hex\-secret> is secret in hex. An
empty line, and line which starts with \(aq#\(aq are skipped.
The first identity and secret pair encountered is used.
The default enabled cipher list might not contain any
PSK cipher suite. In that case, desired PSK cipher
suites must be enabled using \fI\%\-\-client\-ciphers\fP option.
The desired PSK cipher suite may be block listed by
HTTP/2. To use those cipher suites with HTTP/2,
consider to use \fI\%\-\-client\-no\-http2\-cipher\-block\-list\fP
option. But be aware its implications.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-no\-postpone\-early\-data
By default, except for QUIC connections, nghttpx
postpones forwarding HTTP requests sent in early data,
including those sent in partially in it, until TLS
handshake finishes. If all backend server recognizes
\(dqEarly\-Data\(dq header field, using this option makes
nghttpx not postpone forwarding request and get full
potential of 0\-RTT data.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-max\-early\-data=<SIZE>
Sets the maximum amount of 0\-RTT data that server
accepts.
.sp
Default: \fB16K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ktls
Enable ktls.
.UNINDENT
.SS HTTP/2
.INDENT 0.0
.TP
.B \-c, \-\-frontend\-http2\-max\-concurrent\-streams=<N>
Set the maximum number of the concurrent streams in one
frontend HTTP/2 session.
.sp
Default: \fB100\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-http2\-max\-concurrent\-streams=<N>
Set the maximum number of the concurrent streams in one
backend HTTP/2 session. This sets maximum number of
concurrent opened pushed streams. The maximum number of
concurrent requests are set by a remote server.
.sp
Default: \fB100\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-window\-size=<SIZE>
Sets the per\-stream initial window size of HTTP/2
frontend connection.
.sp
Default: \fB65535\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-connection\-window\-size=<SIZE>
Sets the per\-connection window size of HTTP/2 frontend
connection.
.sp
Default: \fB65535\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-http2\-window\-size=<SIZE>
Sets the initial window size of HTTP/2 backend
connection.
.sp
Default: \fB65535\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-http2\-connection\-window\-size=<SIZE>
Sets the per\-connection window size of HTTP/2 backend
connection.
.sp
Default: \fB2147483647\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-http2\-no\-cookie\-crumbling
Don\(aqt crumble cookie header field.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-padding=<N>
Add at most <N> bytes to a HTTP/2 frame payload as
padding. Specify 0 to disable padding. This option is
meant for debugging purpose and not intended to enhance
protocol security.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-server\-push
Disable HTTP/2 server push. Server push is supported by
default mode and HTTP/2 frontend via Link header field.
It is also supported if both frontend and backend are
HTTP/2 in default mode. In this case, server push from
backend session is relayed to frontend, and server push
via Link header field is also supported.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-optimize\-write\-buffer\-size
(Experimental) Enable write buffer size optimization in
frontend HTTP/2 TLS connection. This optimization aims
to reduce write buffer size so that it only contains
bytes which can send immediately. This makes server
more responsive to prioritized HTTP/2 stream because the
buffering of lower priority stream is reduced. This
option is only effective on recent Linux platform.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-optimize\-window\-size
(Experimental) Automatically tune connection level
window size of frontend HTTP/2 TLS connection. If this
feature is enabled, connection window size starts with
the default window size, 65535 bytes. nghttpx
automatically adjusts connection window size based on
TCP receiving window size. The maximum window size is
capped by the value specified by
\fI\%\-\-frontend\-http2\-connection\-window\-size\fP\&. Since the
stream is subject to stream level window size, it should
be adjusted using \fI\%\-\-frontend\-http2\-window\-size\fP option as
well. This option is only effective on recent Linux
platform.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-encoder\-dynamic\-table\-size=<SIZE>
Specify the maximum dynamic table size of HPACK encoder
in the frontend HTTP/2 connection. The decoder (client)
specifies the maximum dynamic table size it accepts.
Then the negotiated dynamic table size is the minimum of
this option value and the value which client specified.
.sp
Default: \fB4K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-decoder\-dynamic\-table\-size=<SIZE>
Specify the maximum dynamic table size of HPACK decoder
in the frontend HTTP/2 connection.
.sp
Default: \fB4K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-http2\-encoder\-dynamic\-table\-size=<SIZE>
Specify the maximum dynamic table size of HPACK encoder
in the backend HTTP/2 connection. The decoder (backend)
specifies the maximum dynamic table size it accepts.
Then the negotiated dynamic table size is the minimum of
this option value and the value which backend specified.
.sp
Default: \fB4K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-http2\-decoder\-dynamic\-table\-size=<SIZE>
Specify the maximum dynamic table size of HPACK decoder
in the backend HTTP/2 connection.
.sp
Default: \fB4K\fP
.UNINDENT
.SS Mode
.INDENT 0.0
.TP
.B (default mode)
Accept HTTP/2, and HTTP/1.1 over SSL/TLS. \(dqno\-tls\(dq
parameter is used in \fI\%\-\-frontend\fP option, accept HTTP/2
and HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1
connection can be upgraded to HTTP/2 through HTTP
Upgrade.
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-http2\-proxy
Like default mode, but enable forward proxy. This is so
called HTTP/2 proxy mode.
.UNINDENT
.SS Logging
.INDENT 0.0
.TP
.B \-L, \-\-log\-level=<LEVEL>
Set the severity level of log output. <LEVEL> must be
one of INFO, NOTICE, WARN, ERROR and FATAL.
.sp
Default: \fBNOTICE\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-accesslog\-file=<PATH>
Set path to write access log. To reopen file, send USR1
signal to nghttpx.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-accesslog\-syslog
Send access log to syslog. If this option is used,
\fI\%\-\-accesslog\-file\fP option is ignored.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-accesslog\-format=<FORMAT>
Specify format string for access log. The default
format is combined format. The following variables are
available:
.INDENT 7.0
.IP \(bu 2
$remote_addr: client IP address.
.IP \(bu 2
$time_local: local time in Common Log format.
.IP \(bu 2
$time_iso8601: local time in ISO 8601 format.
.IP \(bu 2
$request: HTTP request line.
.IP \(bu 2
$status: HTTP response status code.
.IP \(bu 2
$body_bytes_sent: the number of bytes sent to client
as response body.
.IP \(bu 2
$http_<VAR>: value of HTTP request header <VAR> where
\(aq_\(aq in <VAR> is replaced with \(aq\-\(aq.
.IP \(bu 2
$remote_port: client port.
.IP \(bu 2
$server_port: server port.
.IP \(bu 2
$request_time: request processing time in seconds with
milliseconds resolution.
.IP \(bu 2
$pid: PID of the running process.
.IP \(bu 2
$alpn: ALPN identifier of the protocol which generates
the response. For HTTP/1, ALPN is always http/1.1,
regardless of minor version.
.IP \(bu 2
$tls_cipher: cipher used for SSL/TLS connection.
.IP \(bu 2
$tls_client_fingerprint_sha256: SHA\-256 fingerprint of
client certificate.
.IP \(bu 2
$tls_client_fingerprint_sha1: SHA\-1 fingerprint of
client certificate.
.IP \(bu 2
$tls_client_subject_name: subject name in client
certificate.
.IP \(bu 2
$tls_client_issuer_name: issuer name in client
certificate.
.IP \(bu 2
$tls_client_serial: serial number in client
certificate.
.IP \(bu 2
$tls_protocol: protocol for SSL/TLS connection.
.IP \(bu 2
$tls_session_id: session ID for SSL/TLS connection.
.IP \(bu 2
$tls_session_reused: \(dqr\(dq if SSL/TLS session was
reused. Otherwise, \(dq.\(dq
.IP \(bu 2
$tls_sni: SNI server name for SSL/TLS connection.
.IP \(bu 2
$backend_host: backend host used to fulfill the
request. \(dq\-\(dq if backend host is not available.
.IP \(bu 2
$backend_port: backend port used to fulfill the
request. \(dq\-\(dq if backend host is not available.
.IP \(bu 2
$method: HTTP method
.IP \(bu 2
$path: Request path including query. For CONNECT
request, authority is recorded.
.IP \(bu 2
$path_without_query: $path up to the first \(aq?\(aq
character. For CONNECT request, authority is
recorded.
.IP \(bu 2
$protocol_version: HTTP version (e.g., HTTP/1.1,
HTTP/2)
.UNINDENT
.sp
The variable can be enclosed by \(dq{\(dq and \(dq}\(dq for
disambiguation (e.g., ${remote_addr}).
.sp
Default: \fB$remote_addr \- \- [$time_local] \(dq$request\(dq $status $body_bytes_sent \(dq$http_referer\(dq \(dq$http_user_agent\(dq\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-accesslog\-write\-early
Write access log when response header fields are
received from backend rather than when request
transaction finishes.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-errorlog\-file=<PATH>
Set path to write error log. To reopen file, send USR1
signal to nghttpx. stderr will be redirected to the
error log file unless \fI\%\-\-errorlog\-syslog\fP is used.
.sp
Default: \fB/dev/stderr\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-errorlog\-syslog
Send error log to syslog. If this option is used,
\fI\%\-\-errorlog\-file\fP option is ignored.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-syslog\-facility=<FACILITY>
Set syslog facility to <FACILITY>.
.sp
Default: \fBdaemon\fP
.UNINDENT
.SS HTTP
.INDENT 0.0
.TP
.B \-\-add\-x\-forwarded\-for
Append X\-Forwarded\-For header field to the downstream
request.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-incoming\-x\-forwarded\-for
Strip X\-Forwarded\-For header field from inbound client
requests.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-add\-x\-forwarded\-proto
Don\(aqt append additional X\-Forwarded\-Proto header field
to the backend request. If inbound client sets
X\-Forwarded\-Proto, and
\fI\%\-\-no\-strip\-incoming\-x\-forwarded\-proto\fP option is used,
they are passed to the backend.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-strip\-incoming\-x\-forwarded\-proto
Don\(aqt strip X\-Forwarded\-Proto header field from inbound
client requests.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-add\-forwarded=<LIST>
Append RFC 7239 Forwarded header field with parameters
specified in comma delimited list <LIST>. The supported
parameters are \(dqby\(dq, \(dqfor\(dq, \(dqhost\(dq, and \(dqproto\(dq. By
default, the value of \(dqby\(dq and \(dqfor\(dq parameters are
obfuscated string. See \fI\%\-\-forwarded\-by\fP and
\fI\%\-\-forwarded\-for\fP options respectively. Note that nghttpx
does not translate non\-standard X\-Forwarded\-* header
fields into Forwarded header field, and vice versa.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-incoming\-forwarded
Strip Forwarded header field from inbound client
requests.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-forwarded\-by=(obfuscated|ip|<VALUE>)
Specify the parameter value sent out with \(dqby\(dq parameter
of Forwarded header field. If \(dqobfuscated\(dq is given,
the string is randomly generated at startup. If \(dqip\(dq is
given, the interface address of the connection,
including port number, is sent with \(dqby\(dq parameter. In
case of UNIX domain socket, \(dqlocalhost\(dq is used instead
of address and port. User can also specify the static
obfuscated string. The limitation is that it must start
with \(dq_\(dq, and only consists of character set
[A\-Za\-z0\-9._\-], as described in RFC 7239.
.sp
Default: \fBobfuscated\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-forwarded\-for=(obfuscated|ip)
Specify the parameter value sent out with \(dqfor\(dq
parameter of Forwarded header field. If \(dqobfuscated\(dq is
given, the string is randomly generated for each client
connection. If \(dqip\(dq is given, the remote client address
of the connection, without port number, is sent with
\(dqfor\(dq parameter. In case of UNIX domain socket,
\(dqlocalhost\(dq is used instead of address.
.sp
Default: \fBobfuscated\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-via
Don\(aqt append to Via header field. If Via header field
is received, it is left unaltered.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-strip\-incoming\-early\-data
Don\(aqt strip Early\-Data header field from inbound client
requests.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-location\-rewrite
Don\(aqt rewrite location header field in default mode.
When \fI\%\-\-http2\-proxy\fP is used, location header field will
not be altered regardless of this option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-host\-rewrite
Rewrite host and :authority header fields in default
mode. When \fI\%\-\-http2\-proxy\fP is used, these headers will
not be altered regardless of this option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
Specify protocol ID, port, host and origin of
alternative service. <HOST>, <ORIGIN> and <PARAMS> are
optional. Empty <HOST> and <ORIGIN> are allowed and
they are treated as nothing is specified. They are
advertised in alt\-svc header field only in HTTP/1.1
frontend. This option can be used multiple times to
specify multiple alternative services.
Example: \fI\%\-\-altsvc\fP=\(dqh2,443,,,ma=3600; persist=1\(dq
.UNINDENT
.INDENT 0.0
.TP
.B \-\-http2\-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
Just like \fI\%\-\-altsvc\fP option, but this altsvc is only sent
in HTTP/2 frontend.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-add\-request\-header=<HEADER>
Specify additional header field to add to request header
set. The field name must be lowercase. This option
just appends header field and won\(aqt replace anything
already set. This option can be used several times to
specify multiple header fields.
Example: \fI\%\-\-add\-request\-header\fP=\(dqfoo: bar\(dq
.UNINDENT
.INDENT 0.0
.TP
.B \-\-add\-response\-header=<HEADER>
Specify additional header field to add to response
header set. The field name must be lowercase. This
option just appends header field and won\(aqt replace
anything already set. This option can be used several
times to specify multiple header fields.
Example: \fI\%\-\-add\-response\-header\fP=\(dqfoo: bar\(dq
.UNINDENT
.INDENT 0.0
.TP
.B \-\-request\-header\-field\-buffer=<SIZE>
Set maximum buffer size for incoming HTTP request header
field list. This is the sum of header name and value in
bytes. If trailer fields exist, they are counted
towards this number.
.sp
Default: \fB64K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-request\-header\-fields=<N>
Set maximum number of incoming HTTP request header
fields. If trailer fields exist, they are counted
towards this number.
.sp
Default: \fB100\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-response\-header\-field\-buffer=<SIZE>
Set maximum buffer size for incoming HTTP response
header field list. This is the sum of header name and
value in bytes. If trailer fields exist, they are
counted towards this number.
.sp
Default: \fB64K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-response\-header\-fields=<N>
Set maximum number of incoming HTTP response header
fields. If trailer fields exist, they are counted
towards this number.
.sp
Default: \fB500\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-error\-page=(<CODE>|*)=<PATH>
Set file path to custom error page served when nghttpx
originally generates HTTP error status code <CODE>.
<CODE> must be greater than or equal to 400, and at most
599. If \(dq*\(dq is used instead of <CODE>, it matches all
HTTP status code. If error status code comes from
backend server, the custom error pages are not used.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-server\-name=<NAME>
Change server response header field value to <NAME>.
.sp
Default: \fBnghttpx\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-server\-rewrite
Don\(aqt rewrite server header field in default mode. When
\fI\%\-\-http2\-proxy\fP is used, these headers will not be altered
regardless of this option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-redirect\-https\-port=<PORT>
Specify the port number which appears in Location header
field when redirect to HTTPS URI is made due to
\(dqredirect\-if\-not\-tls\(dq parameter in \fI\%\-\-backend\fP option.
.sp
Default: \fB443\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-require\-http\-scheme
Always require http or https scheme in HTTP request. It
also requires that https scheme must be used for an
encrypted connection. Otherwise, http scheme must be
used. This option is recommended for a server
deployment which directly faces clients and the services
it provides only require http or https scheme.
.UNINDENT
.SS API
.INDENT 0.0
.TP
.B \-\-api\-max\-request\-body=<SIZE>
Set the maximum size of request body for API request.
.sp
Default: \fB32M\fP
.UNINDENT
.SS DNS
.INDENT 0.0
.TP
.B \-\-dns\-cache\-timeout=<DURATION>
Set duration that cached DNS results remain valid. Note
that nghttpx caches the unsuccessful results as well.
.sp
Default: \fB10s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dns\-lookup\-timeout=<DURATION>
Set timeout that DNS server is given to respond to the
initial DNS query. For the 2nd and later queries,
server is given time based on this timeout, and it is
scaled linearly.
.sp
Default: \fB250ms\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dns\-max\-try=<N>
Set the number of DNS query before nghttpx gives up name
lookup.
.sp
Default: \fB3\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-max\-requests=<N>
The number of requests that single frontend connection
can process. For HTTP/2, this is the number of streams
in one HTTP/2 connection. For HTTP/1, this is the
number of keep alive requests. This is hint to nghttpx,
and it may allow additional few requests. The default
value is unlimited.
.UNINDENT
.SS Debug
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-dump\-request\-header=<PATH>
Dumps request headers received by HTTP/2 frontend to the
file denoted in <PATH>. The output is done in HTTP/1
header field format and each header block is followed by
an empty line. This option is not thread safe and MUST
NOT be used with option \fI\%\-n\fP<N>, where <N> >= 2.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http2\-dump\-response\-header=<PATH>
Dumps response headers sent from HTTP/2 frontend to the
file denoted in <PATH>. The output is done in HTTP/1
header field format and each header block is followed by
an empty line. This option is not thread safe and MUST
NOT be used with option \fI\%\-n\fP<N>, where <N> >= 2.
.UNINDENT
.INDENT 0.0
.TP
.B \-o, \-\-frontend\-frame\-debug
Print HTTP/2 frames in frontend to stderr. This option
is not thread safe and MUST NOT be used with option
\fI\%\-n\fP=N, where N >= 2.
.UNINDENT
.SS Process
.INDENT 0.0
.TP
.B \-D, \-\-daemon
Run in a background. If \fI\%\-D\fP is used, the current working
directory is changed to \(aq\fI/\fP\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pid\-file=<PATH>
Set path to save PID of this program.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-user=<USER>
Run this program as <USER>. This option is intended to
be used to drop root privileges.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-single\-process
Run this program in a single process mode for debugging
purpose. Without this option, nghttpx creates at least
2 processes: main and worker processes. If this option
is used, main and worker are unified into a single
process. nghttpx still spawns additional process if
neverbleed is used. In the single process mode, the
signal handling feature is disabled.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-worker\-processes=<N>
The maximum number of worker processes. nghttpx spawns
new worker process when it reloads its configuration.
The previous worker process enters graceful termination
period and will terminate when it finishes handling the
existing connections. However, if reloading
configurations happen very frequently, the worker
processes might be piled up if they take a bit long time
to finish the existing connections. With this option,
if the number of worker processes exceeds the given
value, the oldest worker process is terminated
immediately. Specifying 0 means no limit and it is the
default behaviour.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-worker\-process\-grace\-shutdown\-period=<DURATION>
Maximum period for a worker process to terminate
gracefully. When a worker process enters in graceful
shutdown period (e.g., when nghttpx reloads its
configuration) and it does not finish handling the
existing connections in the given period of time, it is
immediately terminated. Specifying 0 means no limit and
it is the default behaviour.
.UNINDENT
.SS Scripting
.INDENT 0.0
.TP
.B \-\-mruby\-file=<PATH>
Set mruby script file
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ignore\-per\-pattern\-mruby\-error
Ignore mruby compile error for per\-pattern mruby script
file. If error occurred, it is treated as if no mruby
file were specified for the pattern.
.UNINDENT
.SS HTTP/3 and QUIC
.INDENT 0.0
.TP
.B \-\-frontend\-quic\-idle\-timeout=<DURATION>
Specify an idle timeout for QUIC connection.
.sp
Default: \fB30s\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-quic\-debug\-log
Output QUIC debug log to \fI/dev/stderr.\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-quic\-bpf\-program\-file=<PATH>
Specify a path to eBPF program file reuseport_kern.o to
direct an incoming QUIC UDP datagram to a correct
socket.
.sp
Default: \fB/usr/local/lib/nghttp2/reuseport_kern.o\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-quic\-early\-data
Enable early data on frontend QUIC connections. nghttpx
sends \(dqEarly\-Data\(dq header field to a backend server if a
request is received in early data and handshake has not
finished. All backend servers should deal with possibly
replayed requests.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-quic\-qlog\-dir=<DIR>
Specify a directory where a qlog file is written for
frontend QUIC connections. A qlog file is created per
each QUIC connection. The file name is ISO8601 basic
format, followed by \(dq\-\(dq, server Source Connection ID and
\(dq.sqlog\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-quic\-require\-token
Require an address validation token for a frontend QUIC
connection. Server sends a token in Retry packet or
NEW_TOKEN frame in the previous connection.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-quic\-congestion\-controller=<CC>
Specify a congestion controller algorithm for a frontend
QUIC connection. <CC> should be either \(dqcubic\(dq or
\(dqbbr\(dq.
.sp
Default: \fBcubic\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-quic\-secret\-file=<PATH>
Path to file that contains secure random data to be used
as QUIC keying materials. It is used to derive keys for
encrypting tokens and Connection IDs. It is not used to
encrypt QUIC packets. Each line of this file must
contain exactly 136 bytes hex\-encoded string (when
decoded the byte string is 68 bytes long). The first 3
bits of decoded byte string are used to identify the
keying material. An empty line or a line which starts
\(aq#\(aq is ignored. The file can contain more than one
keying materials. Because the identifier is 3 bits, at
most 8 keying materials are read and the remaining data
is discarded. The first keying material in the file is
primarily used for encryption and decryption for new
connection. The other ones are used to decrypt data for
the existing connections. Specifying multiple keying
materials enables key rotation. Please note that key
rotation does not occur automatically. User should
update files or change options values and restart
nghttpx gracefully. If opening or reading given file
fails, all loaded keying materials are discarded and it
is treated as if none of this option is given. If this
option is not given or an error occurred while opening
or reading a file, a keying material is generated
internally on startup and reload.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-quic\-server\-id=<HEXSTRING>
Specify server ID encoded in Connection ID to identify
this particular server instance. Connection ID is
encrypted and this part is not visible in public. It
must be 4 bytes long and must be encoded in hex string
(which is 8 bytes long). If this option is omitted, a
random server ID is generated on startup and
configuration reload.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-quic\-initial\-rtt=<DURATION>
Specify the initial RTT of the frontend QUIC connection.
.sp
Default: \fB333ms\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-quic\-bpf
Disable eBPF.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http3\-window\-size=<SIZE>
Sets the per\-stream initial window size of HTTP/3
frontend connection.
.sp
Default: \fB256K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http3\-connection\-window\-size=<SIZE>
Sets the per\-connection window size of HTTP/3 frontend
connection.
.sp
Default: \fB1M\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http3\-max\-window\-size=<SIZE>
Sets the maximum per\-stream window size of HTTP/3
frontend connection. The window size is adjusted based
on the receiving rate of stream data. The initial value
is the value specified by \fI\%\-\-frontend\-http3\-window\-size\fP
and the window size grows up to <SIZE> bytes.
.sp
Default: \fB6M\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http3\-max\-connection\-window\-size=<SIZE>
Sets the maximum per\-connection window size of HTTP/3
frontend connection. The window size is adjusted based
on the receiving rate of stream data. The initial value
is the value specified by
\fI\%\-\-frontend\-http3\-connection\-window\-size\fP and the window
size grows up to <SIZE> bytes.
.sp
Default: \fB8M\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-http3\-max\-concurrent\-streams=<N>
Set the maximum number of the concurrent streams in one
frontend HTTP/3 connection.
.sp
Default: \fB100\fP
.UNINDENT
.SS Misc
.INDENT 0.0
.TP
.B \-\-conf=<PATH>
Load configuration from <PATH>. Please note that
nghttpx always tries to read the default configuration
file if \fI\%\-\-conf\fP is not given.
.sp
Default: \fB/etc/nghttpx/nghttpx.conf\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-include=<PATH>
Load additional configurations from <PATH>. File <PATH>
is read when configuration parser encountered this
option. This option can be used multiple times, or even
recursively.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-version
Print version and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Print this help and exit.
.UNINDENT
.sp
The <SIZE> argument is an integer and an optional unit (e.g., 10K is
10 * 1024). Units are K, M and G (powers of 1024).
.sp
The <DURATION> argument is an integer and an optional unit (e.g., 1s
is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively). If a unit
is omitted, a second is used as unit.
.SH FILES
.INDENT 0.0
.TP
.B \fI/etc/nghttpx/nghttpx.conf\fP
The default configuration file path nghttpx searches at startup.
The configuration file path can be changed using \fI\%\-\-conf\fP
option.
.sp
Those lines which are staring \fB#\fP are treated as comment.
.sp
The option name in the configuration file is the long command\-line
option name with leading \fB\-\-\fP stripped (e.g., \fBfrontend\fP). Put
\fB=\fP between option name and value. Don\(aqt put extra leading or
trailing spaces.
.sp
When specifying arguments including characters which have special
meaning to a shell, we usually use quotes so that shell does not
interpret them. When writing this configuration file, quotes for
this purpose must not be used. For example, specify additional
request header field, do this:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
add\-request\-header=foo: bar
.EE
.UNINDENT
.UNINDENT
.sp
instead of:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
add\-request\-header=\(dqfoo: bar\(dq
.EE
.UNINDENT
.UNINDENT
.sp
The options which do not take argument in the command\-line \fItake\fP
argument in the configuration file. Specify \fByes\fP as an argument
(e.g., \fBhttp2\-proxy=yes\fP). If other string is given, it is
ignored.
.sp
To specify private key and certificate file which are given as
positional arguments in command\-line, use \fBprivate\-key\-file\fP and
\fBcertificate\-file\fP\&.
.sp
\fI\%\-\-conf\fP option cannot be used in the configuration file and
will be ignored if specified.
.TP
.B Error log
Error log is written to stderr by default. It can be configured
using \fI\%\-\-errorlog\-file\fP\&. The format of log message is as
follows:
.sp
<datetime> <main\-pid> <current\-pid> <thread\-id> <level> (<filename>:<line>) <msg>
.INDENT 7.0
.TP
.B <datetime>
It is a combination of date and time when the log is written. It
is in ISO 8601 format.
.TP
.B <main\-pid>
It is a main process ID.
.TP
.B <current\-pid>
It is a process ID which writes this log.
.TP
.B <thread\-id>
It is a thread ID which writes this log. It would be unique
within <current\-pid>.
.TP
.B <filename> and <line>
They are source file name, and line number which produce this log.
.TP
.B <msg>
It is a log message body.
.UNINDENT
.UNINDENT
.SH SIGNALS
.INDENT 0.0
.TP
.B SIGQUIT
Shutdown gracefully. First accept pending connections and stop
accepting connection. After all connections are handled, nghttpx
exits.
.TP
.B SIGHUP
Reload configuration file given in \fI\%\-\-conf\fP\&.
.TP
.B SIGUSR1
Reopen log files.
.UNINDENT
.sp
SIGUSR2
.INDENT 0.0
.INDENT 3.5
Fork and execute nghttpx. It will execute the binary in the same
path with same command\-line arguments and environment variables. As
of nghttpx version 1.20.0, the new main process sends SIGQUIT to the
original main process when it is ready to serve requests. For the
earlier versions of nghttpx, user has to send SIGQUIT to the
original main process.
.sp
The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
is usually used to execute new binary, and the main process is newly
spawned. On the other hand, the latter just reloads configuration
file, and the same main process continues to exist.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
nghttpx consists of multiple processes: one process for processing
these signals, and another one for processing requests. The former
spawns the latter. The former is called main process, and the
latter is called worker process. If neverbleed is enabled, the
worker process spawns neverbleed daemon process which does RSA key
processing. The above signal must be sent to the main process. If
the other processes received one of them, it is ignored. This
behaviour of these processes may change in the future release. In
other words, in the future release, the processes other than main
process may terminate upon the reception of these signals.
Therefore these signals should not be sent to the processes other
than main process.
.UNINDENT
.UNINDENT
.SH SERVER PUSH
.sp
nghttpx supports HTTP/2 server push in default mode with Link header
field. nghttpx looks for Link header field (\X'tty: link http://tools.ietf.org/html/rfc5988'\fI\%RFC 5988\fP\X'tty: link') in response headers from
backend server and extracts URI\-reference with parameter
\fBrel=preload\fP (see \X'tty: link http://w3c.github.io/preload/#interoperability-with-http-link-header'\fI\%preload\fP\X'tty: link')
and pushes those URIs to the frontend client. Here is a sample Link
header field to initiate server push:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Link: </fonts/font.woff>; rel=preload
Link: </css/theme.css>; rel=preload
.EE
.UNINDENT
.UNINDENT
.sp
Currently, the following restriction is applied for server push:
.INDENT 0.0
.IP 1. 3
The associated stream must have method \(dqGET\(dq or \(dqPOST\(dq. The
associated stream\(aqs status code must be 200.
.UNINDENT
.sp
This limitation may be loosened in the future release.
.sp
nghttpx also supports server push if both frontend and backend are
HTTP/2 in default mode. In this case, in addition to server push via
Link header field, server push from backend is forwarded to frontend
HTTP/2 session.
.sp
HTTP/2 server push will be disabled if \fI\%\-\-http2\-proxy\fP is
used.
.SH UNIX DOMAIN SOCKET
.sp
nghttpx supports UNIX domain socket with a filename for both frontend
and backend connections.
.sp
Please note that current nghttpx implementation does not delete a
socket with a filename. And on start up, if nghttpx detects that the
specified socket already exists in the file system, nghttpx first
deletes it. However, if SIGUSR2 is used to execute new binary and
both old and new configurations use same filename, new binary does not
delete the socket and continues to use it.
.SH TLS SESSION RESUMPTION
.sp
nghttpx supports TLS session resumption through both session ID and
session ticket.
.SS SESSION ID RESUMPTION
.sp
By default, session ID is shared by all worker threads.
.SS TLS SESSION TICKET RESUMPTION
.sp
By default, session ticket is shared by all worker threads. The
automatic key rotation is also enabled by default. Every an hour, new
encryption key is generated, and previous encryption key becomes
decryption only key. We set session timeout to 12 hours, and thus we
keep at most 12 keys.
.sp
If \fI\%\-\-tls\-ticket\-key\-memcached\fP is given, encryption keys are
retrieved from memcached. nghttpx just reads keys from memcached; one
has to deploy key generator program to update keys frequently (e.g.,
every 1 hour). The example key generator tlsticketupdate.go is
available under contrib directory in nghttp2 archive. The memcached
entry key is \fBnghttpx:tls\-ticket\-key\fP\&. The data format stored in
memcached is the binary format described below:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| VERSION (4) |LEN (2)|KEY(48 or 80) ...
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
^ |
| |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
(LEN, KEY) pair can be repeated
.EE
.UNINDENT
.UNINDENT
.sp
All numbers in the above figure is bytes. All integer fields are
network byte order.
.sp
First 4 bytes integer VERSION field, which must be 1. The 2 bytes
integer LEN field gives the length of following KEY field, which
contains key. If \fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-128\-cbc is
used, LEN must be 48. If
\fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-256\-cbc is used, LEN must be
80. LEN and KEY pair can be repeated multiple times to store multiple
keys. The key appeared first is used as encryption key. All the
remaining keys are used as decryption only.
.sp
By default, connections to memcached server are not encrypted. To
enable encryption, use \fBtls\fP keyword in
\fI\%\-\-tls\-ticket\-key\-memcached\fP option.
.sp
If \fI\%\-\-tls\-ticket\-key\-file\fP is given, encryption key is read
from the given file. In this case, nghttpx does not rotate key
automatically. To rotate key, one has to restart nghttpx (see
SIGNALS).
.SH CERTIFICATE TRANSPARENCY
.sp
nghttpx supports TLS \fBsigned_certificate_timestamp\fP extension (\X'tty: link https://tools.ietf.org/html/rfc6962'\fI\%RFC
6962\fP\X'tty: link'). The relevant options
are \fI\%\-\-tls\-sct\-dir\fP and \fBsct\-dir\fP parameter in
\fI\%\-\-subcert\fP\&. They takes a directory, and nghttpx reads all
files whose extension is \fB\&.sct\fP under the directory. The \fB*.sct\fP
files are encoded as \fBSignedCertificateTimestamp\fP struct described
in \X'tty: link https://tools.ietf.org/html/rfc6962#section-3.2'\fI\%section 3.2 of RFC 69662\fP\X'tty: link'\&. This format is
the same one used by \X'tty: link https://github.com/grahamedgecombe/nginx-ct'\fI\%nginx\-ct\fP\X'tty: link' and \X'tty: link https://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html'\fI\%mod_ssl_ct\fP\X'tty: link'\&.
\X'tty: link https://github.com/grahamedgecombe/ct-submit'\fI\%ct\-submit\fP\X'tty: link' can be
used to submit certificates to log servers, and obtain the
\fBSignedCertificateTimestamp\fP struct which can be used with nghttpx.
.SH MRUBY SCRIPTING
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
The current mruby extension API is experimental and not frozen. The
API is subject to change in the future release.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Almost all string value returned from method, or attribute is a
fresh new mruby string, which involves memory allocation, and
copies. Therefore, it is strongly recommended to store a return
value in a local variable, and use it, instead of calling method or
accessing attribute repeatedly.
.UNINDENT
.UNINDENT
.sp
nghttpx allows users to extend its capability using mruby scripts.
nghttpx has 2 hook points to execute mruby script: request phase and
response phase. The request phase hook is invoked after all request
header fields are received from client. The response phase hook is
invoked after all response header fields are received from backend
server. These hooks allows users to modify header fields, or common
HTTP variables, like authority or request path, and even return custom
response without forwarding request to backend servers.
.sp
There are 2 levels of mruby script invocations: global and
per\-pattern. The global mruby script is set by \fI\%\-\-mruby\-file\fP
option and is called for all requests. The per\-pattern mruby script
is set by \(dqmruby\(dq parameter in \fI\%\-b\fP option. It is invoked for
a request which matches the particular pattern. The order of hook
invocation is: global request phase hook, per\-pattern request phase
hook, per\-pattern response phase hook, and finally global response
phase hook. If a hook returns a response, any later hooks are not
invoked. The global request hook is invoked before the pattern
matching is made and changing request path may affect the pattern
matching.
.sp
Please note that request and response hooks of per\-pattern mruby
script for a single request might not come from the same script. This
might happen after a request hook is executed, backend failed for some
reason, and at the same time, backend configuration is replaced by API
request, and then the request uses new configuration on retry. The
response hook from new configuration, if it is specified, will be
invoked.
.sp
The all mruby script will be evaluated once per thread on startup, and
it must instantiate object and evaluate it as the return value (e.g.,
\fBApp.new\fP). This object is called app object. If app object
defines \fBon_req\fP method, it is called with \fI\%Nghttpx::Env\fP
object on request hook. Similarly, if app object defines \fBon_resp\fP
method, it is called with \fI\%Nghttpx::Env\fP object on response
hook. For each method invocation, user can can access
\fI\%Nghttpx::Request\fP and \fI\%Nghttpx::Response\fP objects
via \fI\%Nghttpx::Env#req\fP and \fI\%Nghttpx::Env#resp\fP
respectively.
.INDENT 0.0
.TP
.B Nghttpx::REQUEST_PHASE
Constant to represent request phase.
.UNINDENT
.INDENT 0.0
.TP
.B Nghttpx::RESPONSE_PHASE
Constant to represent response phase.
.UNINDENT
.INDENT 0.0
.TP
.B class Nghttpx::Env
Object to represent current request specific context.
.INDENT 7.0
.TP
.B attribute [R] req
Return \fI\%Request\fP object.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] resp
Return \fI\%Response\fP object.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] ctx
Return Ruby hash object. It persists until request finishes.
So values set in request phase hook can be retrieved in
response phase hook.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] phase
Return the current phase.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] remote_addr
Return IP address of a remote client. If connection is made
via UNIX domain socket, this returns the string \(dqlocalhost\(dq.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] server_addr
Return address of server that accepted the connection. This
is a string which specified in \fI\%\-\-frontend\fP option,
excluding port number, and not a resolved IP address. For
UNIX domain socket, this is a path to UNIX domain socket.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] server_port
Return port number of the server frontend which accepted the
connection from client.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_used
Return true if TLS is used on the connection.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_sni
Return the TLS SNI value which client sent in this connection.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_client_fingerprint_sha256
Return the SHA\-256 fingerprint of a client certificate.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_client_fingerprint_sha1
Return the SHA\-1 fingerprint of a client certificate.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_client_issuer_name
Return the issuer name of a client certificate.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_client_subject_name
Return the subject name of a client certificate.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_client_serial
Return the serial number of a client certificate.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_client_not_before
Return the start date of a client certificate in seconds since
the epoch.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_client_not_after
Return the end date of a client certificate in seconds since
the epoch.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_cipher
Return a TLS cipher negotiated in this connection.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_protocol
Return a TLS protocol version negotiated in this connection.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_session_id
Return a session ID for this connection in hex string.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_session_reused
Return true if, and only if a SSL/TLS session is reused.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] alpn
Return ALPN identifier negotiated in this connection.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] tls_handshake_finished
Return true if SSL/TLS handshake has finished. If it returns
false in the request phase hook, the request is received in
TLSv1.3 early data (0\-RTT) and might be vulnerable to the
replay attack. nghttpx will send Early\-Data header field to
backend servers to indicate this.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class Nghttpx::Request
Object to represent request from client. The modification to
Request object is allowed only in request phase hook.
.INDENT 7.0
.TP
.B attribute [R] http_version_major
Return HTTP major version.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] http_version_minor
Return HTTP minor version.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] method
HTTP method. On assignment, copy of given value is assigned.
We don\(aqt accept arbitrary method name. We will document them
later, but well known methods, like GET, PUT and POST, are all
supported.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] authority
Authority (i.e., example.org), including optional port
component . On assignment, copy of given value is assigned.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] scheme
Scheme (i.e., http, https). On assignment, copy of given
value is assigned.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] path
Request path, including query component (i.e., /index.html).
On assignment, copy of given value is assigned. The path does
not include authority component of URI. This may include
query component. nghttpx makes certain normalization for
path. It decodes percent\-encoding for unreserved characters
(see \X'tty: link https://tools.ietf.org/html/rfc3986#section-2.3'\fI\%https://tools.ietf.org/html/rfc3986#section\-2.3\fP\X'tty: link'), and
resolves \(dq..\(dq and \(dq.\(dq. But it may leave characters which
should be percent\-encoded as is. So be careful when comparing
path against desired string.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] headers
Return Ruby hash containing copy of request header fields.
Changing values in returned hash does not change request
header fields actually used in request processing. Use
\fI\%Nghttpx::Request#add_header\fP or
\fI\%Nghttpx::Request#set_header\fP to change request
header fields.
.UNINDENT
.INDENT 7.0
.TP
.B add_header(key, value)
Add header entry associated with key. The value can be single
string or array of string. It does not replace any existing
values associated with key.
.UNINDENT
.INDENT 7.0
.TP
.B set_header(key, value)
Set header entry associated with key. The value can be single
string or array of string. It replaces any existing values
associated with key.
.UNINDENT
.INDENT 7.0
.TP
.B clear_headers()
Clear all existing request header fields.
.UNINDENT
.INDENT 7.0
.TP
.B push(uri)
Initiate to push resource identified by \fIuri\fP\&. Only HTTP/2
protocol supports this feature. For the other protocols, this
method is noop. \fIuri\fP can be absolute URI, absolute path or
relative path to the current request. For absolute or
relative path, scheme and authority are inherited from the
current request. Currently, method is always GET. nghttpx
will issue request to backend servers to fulfill this request.
The request and response phase hooks will be called for pushed
resource as well.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class Nghttpx::Response
Object to represent response from backend server.
.INDENT 7.0
.TP
.B attribute [R] http_version_major
Return HTTP major version.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] http_version_minor
Return HTTP minor version.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] status
HTTP status code. It must be in the range [200, 999],
inclusive. The non\-final status code is not supported in
mruby scripting at the moment.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] headers
Return Ruby hash containing copy of response header fields.
Changing values in returned hash does not change response
header fields actually used in response processing. Use
\fI\%Nghttpx::Response#add_header\fP or
\fI\%Nghttpx::Response#set_header\fP to change response
header fields.
.UNINDENT
.INDENT 7.0
.TP
.B add_header(key, value)
Add header entry associated with key. The value can be single
string or array of string. It does not replace any existing
values associated with key.
.UNINDENT
.INDENT 7.0
.TP
.B set_header(key, value)
Set header entry associated with key. The value can be single
string or array of string. It replaces any existing values
associated with key.
.UNINDENT
.INDENT 7.0
.TP
.B clear_headers()
Clear all existing response header fields.
.UNINDENT
.INDENT 7.0
.TP
.B return(body)
Return custom response \fIbody\fP to a client. When this method
is called in request phase hook, the request is not forwarded
to the backend, and response phase hook for this request will
not be invoked. When this method is called in response phase
hook, response from backend server is canceled and discarded.
The status code and response header fields should be set
before using this method. To set status code, use
\fI\%Nghttpx::Response#status\fP\&. If status code is not
set, 200 is used. To set response header fields,
\fI\%Nghttpx::Response#add_header\fP and
\fI\%Nghttpx::Response#set_header\fP\&. When this method is
invoked in response phase hook, the response headers are
filled with the ones received from backend server. To send
completely custom header fields, first call
\fI\%Nghttpx::Response#clear_headers\fP to erase all
existing header fields, and then add required header fields.
It is an error to call this method twice for a given request.
.UNINDENT
.INDENT 7.0
.TP
.B send_info(status, headers)
Send non\-final (informational) response to a client. \fIstatus\fP
must be in the range [100, 199], inclusive. \fIheaders\fP is a
hash containing response header fields. Its key must be a
string, and the associated value must be either string or
array of strings. Since this is not a final response, even if
this method is invoked, request is still forwarded to a
backend unless \fI\%Nghttpx::Response#return\fP is called.
This method can be called multiple times. It cannot be called
after \fI\%Nghttpx::Response#return\fP is called.
.UNINDENT
.UNINDENT
.SS MRUBY EXAMPLES
.sp
Modify request path:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class App
def on_req(env)
env.req.path = \(dq/apps#{env.req.path}\(dq
end
end
App.new
.EE
.UNINDENT
.UNINDENT
.sp
Don\(aqt forget to instantiate and evaluate object at the last line.
.sp
Restrict permission of viewing a content to a specific client
addresses:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class App
def on_req(env)
allowed_clients = [\(dq127.0.0.1\(dq, \(dq::1\(dq]
if env.req.path.start_with?(\(dq/log/\(dq) &&
!allowed_clients.include?(env.remote_addr) then
env.resp.status = 404
env.resp.return \(dqpermission denied\(dq
end
end
end
App.new
.EE
.UNINDENT
.UNINDENT
.SH API ENDPOINTS
.sp
nghttpx exposes API endpoints to manipulate it via HTTP based API. By
default, API endpoint is disabled. To enable it, add a dedicated
frontend for API using \fI\%\-\-frontend\fP option with \(dqapi\(dq
parameter. All requests which come from this frontend address, will
be treated as API request.
.sp
The response is normally JSON dictionary, and at least includes the
following keys:
.INDENT 0.0
.TP
.B status
The status of the request processing. The following values are
defined:
.INDENT 7.0
.TP
.B Success
The request was successful.
.TP
.B Failure
The request was failed. No change has been made.
.UNINDENT
.TP
.B code
HTTP status code
.UNINDENT
.sp
Additionally, depending on the API endpoint, \fBdata\fP key may be
present, and its value contains the API endpoint specific data.
.sp
We wrote \(dqnormally\(dq, since nghttpx may return ordinal HTML response in
some cases where the error has occurred before reaching API endpoint
(e.g., header field is too large).
.sp
The following section describes available API endpoints.
.SS POST /api/v1beta1/backendconfig
.sp
This API replaces the current backend server settings with the
requested ones. The request method should be POST, but PUT is also
acceptable. The request body must be nghttpx configuration file
format. For configuration file format, see \fI\%FILES\fP section. The
line separator inside the request body must be single LF (0x0A).
Currently, only \fI\%backend\fP option is parsed, the
others are simply ignored. The semantics of this API is replace the
current backend with the backend options in request body. Describe
the desired set of backend severs, and nghttpx makes it happen. If
there is no \fI\%backend\fP option is found in request
body, the current set of backend is replaced with the \fI\%backend\fP option\(aqs default value, which is \fB127.0.0.1,80\fP\&.
.sp
The replacement is done instantly without breaking existing
connections or requests. It also avoids any process creation as is
the case with hot swapping with signals.
.sp
The one limitation is that only numeric IP address is allowed in
\fI\%backend\fP in request body unless \(dqdns\(dq parameter
is used while non numeric hostname is allowed in command\-line or
configuration file is read using \fI\%\-\-conf\fP\&.
.SS GET /api/v1beta1/configrevision
.sp
This API returns configuration revision of the current nghttpx. The
configuration revision is opaque string, and it changes after each
reloading by SIGHUP. With this API, an external application knows
that whether nghttpx has finished reloading its configuration by
comparing the configuration revisions between before and after
reloading. It is recommended to disable persistent (keep\-alive)
connection for this purpose in order to avoid to send a request using
the reused connection which may bound to an old process.
.sp
This API returns response including \fBdata\fP key. Its value is JSON
object, and it contains at least the following key:
.INDENT 0.0
.TP
.B configRevision
The configuration revision of the current nghttpx
.UNINDENT
.SH SEE ALSO
.sp
\fBnghttp(1)\fP, \fBnghttpd(1)\fP, \fBh2load(1)\fP
.SH AUTHOR
Tatsuhiro Tsujikawa
.SH COPYRIGHT
2012, 2015, 2016, Tatsuhiro Tsujikawa
.\" Generated by docutils manpage writer.
.
share/man/man1/h2load.1 0000644 00000036640 15053606574 0010534 0 ustar 00 .\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "H2LOAD" "1" "Jun 17, 2025" "1.66.0" "nghttp2"
.SH NAME
h2load \- HTTP/2 benchmarking tool
.SH SYNOPSIS
.sp
\fBh2load\fP [OPTIONS]... [URI]...
.SH DESCRIPTION
.sp
benchmarking tool for HTTP/2 server
.INDENT 0.0
.TP
.B <URI>
Specify URI to access. Multiple URIs can be specified.
URIs are used in this order for each client. All URIs
are used, then first URI is used and then 2nd URI, and
so on. The scheme, host and port in the subsequent
URIs, if present, are ignored. Those in the first URI
are used solely. Definition of a base URI overrides all
scheme, host or port values.
.UNINDENT
.SH OPTIONS
.INDENT 0.0
.TP
.B \-n, \-\-requests=<N>
Number of requests across all clients. If it is used
with \fI\%\-\-timing\-script\-file\fP option, this option specifies
the number of requests each client performs rather than
the number of requests across all clients. This option
is ignored if timing\-based benchmarking is enabled (see
\fI\%\-\-duration\fP option).
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-c, \-\-clients=<N>
Number of concurrent clients. With \fI\%\-r\fP option, this
specifies the maximum number of connections to be made.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-t, \-\-threads=<N>
Number of native threads.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-i, \-\-input\-file=<PATH>
Path of a file with multiple URIs are separated by EOLs.
This option will disable URIs getting from command\-line.
If \(aq\-\(aq is given as <PATH>, URIs will be read from stdin.
URIs are used in this order for each client. All URIs
are used, then first URI is used and then 2nd URI, and
so on. The scheme, host and port in the subsequent
URIs, if present, are ignored. Those in the first URI
are used solely. Definition of a base URI overrides all
scheme, host or port values.
.UNINDENT
.INDENT 0.0
.TP
.B \-m, \-\-max\-concurrent\-streams=<N>
Max concurrent streams to issue per session. When
http/1.1 is used, this specifies the number of HTTP
pipelining requests in\-flight.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-f, \-\-max\-frame\-size=<SIZE>
Maximum frame size that the local endpoint is willing to
receive.
.sp
Default: \fB16K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-w, \-\-window\-bits=<N>
Sets the stream level initial window size to (2**<N>)\-1.
For QUIC, <N> is capped to 26 (roughly 64MiB).
.sp
Default: \fB30\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-W, \-\-connection\-window\-bits=<N>
Sets the connection level initial window size to
(2**<N>)\-1.
.sp
Default: \fB30\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-H, \-\-header=<HEADER>
Add/Override a header to the requests.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ciphers=<SUITE>
Set allowed cipher list for TLSv1.2 or earlier. The
format of the string is described in OpenSSL ciphers(1).
.sp
Default: \fBECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-RSA\-AES256\-GCM\-SHA384\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls13\-ciphers=<SUITE>
Set allowed cipher list for TLSv1.3. The format of the
string is described in OpenSSL ciphers(1).
.sp
Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-p, \-\-no\-tls\-proto=<PROTOID>
Specify ALPN identifier of the protocol to be used when
accessing http URI without SSL/TLS.
Available protocols: h2c and http/1.1
.sp
Default: \fBh2c\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-data=<PATH>
Post FILE to server. The request method is changed to
POST. For http/1.1 connection, if \fI\%\-d\fP is used, the
maximum number of in\-flight pipelined requests is set to
1.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-rate=<N>
Specifies the fixed rate at which connections are
created. The rate must be a positive integer,
representing the number of connections to be made per
rate period. The maximum number of connections to be
made is given in \fI\%\-c\fP option. This rate will be
distributed among threads as evenly as possible. For
example, with \fI\%\-t\fP2 and \fI\%\-r\fP4, each thread gets 2
connections per period. When the rate is 0, the program
will run as it normally does, creating connections at
whatever variable rate it wants. The default value for
this option is 0. \fI\%\-r\fP and \fI\%\-D\fP are mutually exclusive.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rate\-period=<DURATION>
Specifies the time period between creating connections.
The period must be a positive number, representing the
length of the period in time. This option is ignored if
the rate option is not used. The default value for this
option is 1s.
.UNINDENT
.INDENT 0.0
.TP
.B \-D, \-\-duration=<DURATION>
Specifies the main duration for the measurements in case
of timing\-based benchmarking. \fI\%\-D\fP and \fI\%\-r\fP are mutually
exclusive.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-warm\-up\-time=<DURATION>
Specifies the time period before starting the actual
measurements, in case of timing\-based benchmarking.
Needs to provided along with \fI\%\-D\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \-T, \-\-connection\-active\-timeout=<DURATION>
Specifies the maximum time that h2load is willing to
keep a connection open, regardless of the activity on
said connection. <DURATION> must be a positive integer,
specifying the amount of time to wait. When no timeout
value is set (either active or inactive), h2load will
keep a connection open indefinitely, waiting for a
response.
.UNINDENT
.INDENT 0.0
.TP
.B \-N, \-\-connection\-inactivity\-timeout=<DURATION>
Specifies the amount of time that h2load is willing to
wait to see activity on a given connection. <DURATION>
must be a positive integer, specifying the amount of
time to wait. When no timeout value is set (either
active or inactive), h2load will keep a connection open
indefinitely, waiting for a response.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-timing\-script\-file=<PATH>
Path of a file containing one or more lines separated by
EOLs. Each script line is composed of two tab\-separated
fields. The first field represents the time offset from
the start of execution, expressed as a positive value of
milliseconds with microsecond resolution. The second
field represents the URI. This option will disable URIs
getting from command\-line. If \(aq\-\(aq is given as <PATH>,
script lines will be read from stdin. Script lines are
used in order for each client. If \fI\%\-n\fP is given, it must
be less than or equal to the number of script lines,
larger values are clamped to the number of script lines.
If \fI\%\-n\fP is not given, the number of requests will default
to the number of script lines. The scheme, host and
port defined in the first URI are used solely. Values
contained in other URIs, if present, are ignored.
Definition of a base URI overrides all scheme, host or
port values. \fI\%\-\-timing\-script\-file\fP and \fI\%\-\-rps\fP are
mutually exclusive.
.UNINDENT
.INDENT 0.0
.TP
.B \-B, \-\-base\-uri=(<URI>|unix:<PATH>)
Specify URI from which the scheme, host and port will be
used for all requests. The base URI overrides all
values defined either at the command line or inside
input files. If argument starts with \(dqunix:\(dq, then the
rest of the argument will be treated as UNIX domain
socket path. The connection is made through that path
instead of TCP. In this case, scheme is inferred from
the first URI appeared in the command line or inside
input files as usual.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-alpn\-list=<LIST>
Comma delimited list of ALPN protocol identifier sorted
in the order of preference. That means most desirable
protocol comes first. The parameter must be delimited
by a single comma only and any white spaces are treated
as a part of protocol string.
.sp
Default: \fBh2,http/1.1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-h1
Short hand for \fI\%\-\-alpn\-list\fP=http/1.1
\fI\%\-\-no\-tls\-proto\fP=http/1.1, which effectively force
http/1.1 for both http and https URI.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-header\-table\-size=<SIZE>
Specify decoder header table size.
.sp
Default: \fB4K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-encoder\-header\-table\-size=<SIZE>
Specify encoder header table size. The decoder (server)
specifies the maximum dynamic table size it accepts.
Then the negotiated dynamic table size is the minimum of
this option value and the value which server specified.
.sp
Default: \fB4K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=<PATH>
Write per\-request information to a file as tab\-separated
columns: start time as microseconds since epoch; HTTP
status code; microseconds until end of response. More
columns may be added later. Rows are ordered by end\-of\-
response time when using one worker thread, but may
appear slightly out of order with multiple threads due
to buffering. Status code is \-1 for failed streams.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-qlog\-file\-base=<PATH>
Enable qlog output and specify base file name for qlogs.
Qlog is emitted for each connection. For a given base
name \(dqbase\(dq, each output file name becomes
\(dqbase.M.N.sqlog\(dq where M is worker ID and N is client ID
(e.g. \(dqbase.0.3.sqlog\(dq). Only effective in QUIC runs.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-connect\-to=<HOST>[:<PORT>]
Host and port to connect instead of using the authority
in <URI>.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rps=<N>
Specify request per second for each client. \fI\%\-\-rps\fP and
\fI\%\-\-timing\-script\-file\fP are mutually exclusive.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-groups=<GROUPS>
Specify the supported groups.
.sp
Default: \fBX25519:P\-256:P\-384:P\-521\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-udp\-gso
Disable UDP GSO.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-udp\-payload\-size=<SIZE>
Specify the maximum outgoing UDP datagram payload size.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ktls
Enable ktls.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-sni=<DNSNAME>
Send <DNSNAME> in TLS SNI, overriding the host name
specified in URI.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Output debug information.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Display version information and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Display this help and exit.
.UNINDENT
.sp
The <SIZE> argument is an integer and an optional unit (e.g., 10K is
10 * 1024). Units are K, M and G (powers of 1024).
.sp
The <DURATION> argument is an integer and an optional unit (e.g., 1s
is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively). If a unit
is omitted, a second is used as unit.
.SH OUTPUT
.INDENT 0.0
.TP
.B requests
.INDENT 7.0
.TP
.B total
The number of requests h2load was instructed to make.
.TP
.B started
The number of requests h2load has started.
.TP
.B done
The number of requests completed.
.TP
.B succeeded
The number of requests completed successfully. Only HTTP status
code 2xx or3xx are considered as success.
.TP
.B failed
The number of requests failed, including HTTP level failures
(non\-successful HTTP status code).
.TP
.B errored
The number of requests failed, except for HTTP level failures.
This is the subset of the number reported in \fBfailed\fP and most
likely the network level failures or stream was reset by
RST_STREAM.
.TP
.B timeout
The number of requests whose connection timed out before they were
completed. This is the subset of the number reported in
\fBerrored\fP\&.
.UNINDENT
.TP
.B status codes
The number of status code h2load received.
.TP
.B traffic
.INDENT 7.0
.TP
.B total
The number of bytes received from the server \(dqon the wire\(dq. If
requests were made via TLS, this value is the number of decrypted
bytes.
.TP
.B headers
The number of response header bytes from the server without
decompression. The \fBspace savings\fP shows efficiency of header
compression. Let \fBdecompressed(headers)\fP to the number of bytes
used for header fields after decompression. The \fBspace savings\fP
is calculated by (1 \- \fBheaders\fP / \fBdecompressed(headers)\fP) *
100. For HTTP/1.1, this is usually 0.00%, since it does not have
header compression. For HTTP/2, it shows some insightful numbers.
.TP
.B data
The number of response body bytes received from the server.
.UNINDENT
.TP
.B time for request
.INDENT 7.0
.TP
.B min
The minimum time taken for request and response.
.TP
.B max
The maximum time taken for request and response.
.TP
.B mean
The mean time taken for request and response.
.TP
.B sd
The standard deviation of the time taken for request and response.
.TP
.B +/\- sd
The fraction of the number of requests within standard deviation
range (mean +/\- sd) against total number of successful requests.
.UNINDENT
.TP
.B time for connect
.INDENT 7.0
.TP
.B min
The minimum time taken to connect to a server including TLS
handshake.
.TP
.B max
The maximum time taken to connect to a server including TLS
handshake.
.TP
.B mean
The mean time taken to connect to a server including TLS
handshake.
.TP
.B sd
The standard deviation of the time taken to connect to a server.
.TP
.B +/\- sd
The fraction of the number of connections within standard
deviation range (mean +/\- sd) against total number of successful
connections.
.UNINDENT
.TP
.B time for 1st byte (of (decrypted in case of TLS) application data)
.INDENT 7.0
.TP
.B min
The minimum time taken to get 1st byte from a server.
.TP
.B max
The maximum time taken to get 1st byte from a server.
.TP
.B mean
The mean time taken to get 1st byte from a server.
.TP
.B sd
The standard deviation of the time taken to get 1st byte from a
server.
.TP
.B +/\- sd
The fraction of the number of connections within standard
deviation range (mean +/\- sd) against total number of successful
connections.
.UNINDENT
.TP
.B req/s
.INDENT 7.0
.TP
.B min
The minimum request per second among all clients.
.TP
.B max
The maximum request per second among all clients.
.TP
.B mean
The mean request per second among all clients.
.TP
.B sd
The standard deviation of request per second among all clients.
server.
.TP
.B +/\- sd
The fraction of the number of connections within standard
deviation range (mean +/\- sd) against total number of successful
connections.
.UNINDENT
.UNINDENT
.SH FLOW CONTROL
.sp
h2load sets large flow control window by default, and effectively
disables flow control to avoid under utilization of server
performance. To set smaller flow control window, use \fI\%\-w\fP and
\fI\%\-W\fP options. For example, use \fB\-w16 \-W16\fP to set default
window size described in HTTP/2 protocol specification.
.SH SEE ALSO
.sp
\fBnghttp(1)\fP, \fBnghttpd(1)\fP, \fBnghttpx(1)\fP
.SH AUTHOR
Tatsuhiro Tsujikawa
.SH COPYRIGHT
2012, 2015, 2016, Tatsuhiro Tsujikawa
.\" Generated by docutils manpage writer.
.
share/man/man1/nghttpd.1 0000644 00000012511 15053606574 0011022 0 ustar 00 .\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "NGHTTPD" "1" "Jun 17, 2025" "1.66.0" "nghttp2"
.SH NAME
nghttpd \- HTTP/2 server
.SH SYNOPSIS
.sp
\fBnghttpd\fP [OPTION]... <PORT> [<PRIVATE_KEY> <CERT>]
.SH DESCRIPTION
.sp
HTTP/2 server
.INDENT 0.0
.TP
.B <PORT>
Specify listening port number.
.UNINDENT
.INDENT 0.0
.TP
.B <PRIVATE_KEY>
Set path to server\(aqs private key. Required unless
\fI\%\-\-no\-tls\fP is specified.
.UNINDENT
.INDENT 0.0
.TP
.B <CERT>
Set path to server\(aqs certificate. Required unless
\fI\%\-\-no\-tls\fP is specified.
.UNINDENT
.SH OPTIONS
.INDENT 0.0
.TP
.B \-a, \-\-address=<ADDR>
The address to bind to. If not specified the default IP
address determined by getaddrinfo is used.
.UNINDENT
.INDENT 0.0
.TP
.B \-D, \-\-daemon
Run in a background. If \fI\%\-D\fP is used, the current working
directory is changed to \(aq\fI/\fP\(aq. Therefore if this option
is used, \fI\%\-d\fP option must be specified.
.UNINDENT
.INDENT 0.0
.TP
.B \-V, \-\-verify\-client
The server sends a client certificate request. If the
client did not return a certificate, the handshake is
terminated. Currently, this option just requests a
client certificate and does not verify it.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-htdocs=<PATH>
Specify document root. If this option is not specified,
the document root is the current working directory.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Print debug information such as reception/ transmission
of frames and name/value pairs.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-tls
Disable SSL/TLS.
.UNINDENT
.INDENT 0.0
.TP
.B \-c, \-\-header\-table\-size=<SIZE>
Specify decoder header table size.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-encoder\-header\-table\-size=<SIZE>
Specify encoder header table size. The decoder (client)
specifies the maximum dynamic table size it accepts.
Then the negotiated dynamic table size is the minimum of
this option value and the value which client specified.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-color
Force colored log output.
.UNINDENT
.INDENT 0.0
.TP
.B \-p, \-\-push=<PATH>=<PUSH_PATH,...>
Push resources <PUSH_PATH>s when <PATH> is requested.
This option can be used repeatedly to specify multiple
push configurations. <PATH> and <PUSH_PATH>s are
relative to document root. See \fI\%\-\-htdocs\fP option.
Example: \fI\%\-p\fP/=/foo.png \fI\%\-p\fP/doc=/bar.css
.UNINDENT
.INDENT 0.0
.TP
.B \-b, \-\-padding=<N>
Add at most <N> bytes to a frame payload as padding.
Specify 0 to disable padding.
.UNINDENT
.INDENT 0.0
.TP
.B \-m, \-\-max\-concurrent\-streams=<N>
Set the maximum number of the concurrent streams in one
HTTP/2 session.
.sp
Default: \fB100\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-n, \-\-workers=<N>
Set the number of worker threads.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-e, \-\-error\-gzip
Make error response gzipped.
.UNINDENT
.INDENT 0.0
.TP
.B \-w, \-\-window\-bits=<N>
Sets the stream level initial window size to 2**<N>\-1.
.UNINDENT
.INDENT 0.0
.TP
.B \-W, \-\-connection\-window\-bits=<N>
Sets the connection level initial window size to
2**<N>\-1.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dh\-param\-file=<PATH>
Path to file that contains DH parameters in PEM format.
Without this option, DHE cipher suites are not
available.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-early\-response
Start sending response when request HEADERS is received,
rather than complete request is received.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-trailer=<HEADER>
Add a trailer header to a response. <HEADER> must not
include pseudo header field (header field name starting
with \(aq:\(aq). The trailer is sent only if a response has
body part. Example: \fI\%\-\-trailer\fP \(aqfoo: bar\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-hexdump
Display the incoming traffic in hexadecimal (Canonical
hex+ASCII display). If SSL/TLS is used, decrypted data
are used.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-echo\-upload
Send back uploaded content if method is POST or PUT.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-mime\-types\-file=<PATH>
Path to file that contains MIME media types and the
extensions that represent them.
.sp
Default: \fB/etc/mime.types\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-content\-length
Don\(aqt send content\-length header field.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ktls
Enable ktls.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Display version information and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Display this help and exit.
.UNINDENT
.sp
The <SIZE> argument is an integer and an optional unit (e.g., 10K is
10 * 1024). Units are K, M and G (powers of 1024).
.SH SEE ALSO
.sp
\fBnghttp(1)\fP, \fBnghttpx(1)\fP, \fBh2load(1)\fP
.SH AUTHOR
Tatsuhiro Tsujikawa
.SH COPYRIGHT
2012, 2015, 2016, Tatsuhiro Tsujikawa
.\" Generated by docutils manpage writer.
.
share/man/man1/nghttp.1 0000644 00000015336 15053606574 0010666 0 ustar 00 .\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "NGHTTP" "1" "Jun 17, 2025" "1.66.0" "nghttp2"
.SH NAME
nghttp \- HTTP/2 client
.SH SYNOPSIS
.sp
\fBnghttp\fP [OPTIONS]... <URI>...
.SH DESCRIPTION
.sp
HTTP/2 client
.INDENT 0.0
.TP
.B <URI>
Specify URI to access.
.UNINDENT
.SH OPTIONS
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Print debug information such as reception and
transmission of frames and name/value pairs. Specifying
this option multiple times increases verbosity.
.UNINDENT
.INDENT 0.0
.TP
.B \-n, \-\-null\-out
Discard downloaded data.
.UNINDENT
.INDENT 0.0
.TP
.B \-O, \-\-remote\-name
Save download data in the current directory. The
filename is derived from URI. If URI ends with \(aq\fI/\fP\(aq,
\(aqindex.html\(aq is used as a filename. Not implemented
yet.
.UNINDENT
.INDENT 0.0
.TP
.B \-t, \-\-timeout=<DURATION>
Timeout each request after <DURATION>. Set 0 to disable
timeout.
.UNINDENT
.INDENT 0.0
.TP
.B \-w, \-\-window\-bits=<N>
Sets the stream level initial window size to 2**<N>\-1.
.UNINDENT
.INDENT 0.0
.TP
.B \-W, \-\-connection\-window\-bits=<N>
Sets the connection level initial window size to
2**<N>\-1.
.UNINDENT
.INDENT 0.0
.TP
.B \-a, \-\-get\-assets
Download assets such as stylesheets, images and script
files linked from the downloaded resource. Only links
whose origins are the same with the linking resource
will be downloaded. nghttp prioritizes resources using
HTTP/2 dependency based priority. The priority order,
from highest to lowest, is html itself, css, javascript
and images.
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-stat
Print statistics.
.UNINDENT
.INDENT 0.0
.TP
.B \-H, \-\-header=<HEADER>
Add a header to the requests. Example: \fI\%\-H\fP\(aq:method: PUT\(aq
.UNINDENT
.INDENT 0.0
.TP
.B \-\-trailer=<HEADER>
Add a trailer header to the requests. <HEADER> must not
include pseudo header field (header field name starting
with \(aq:\(aq). To send trailer, one must use \fI\%\-d\fP option to
send request body. Example: \fI\%\-\-trailer\fP \(aqfoo: bar\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-cert=<CERT>
Use the specified client certificate file. The file
must be in PEM format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-key=<KEY>
Use the client private key file. The file must be in
PEM format.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-data=<PATH>
Post FILE to server. If \(aq\-\(aq is given, data will be read
from stdin.
.UNINDENT
.INDENT 0.0
.TP
.B \-m, \-\-multiply=<N>
Request each URI <N> times. By default, same URI is not
requested twice. This option disables it too.
.UNINDENT
.INDENT 0.0
.TP
.B \-u, \-\-upgrade
Perform HTTP Upgrade for HTTP/2. This option is ignored
if the request URI has https scheme. If \fI\%\-d\fP is used, the
HTTP upgrade request is performed with OPTIONS method.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-extpri=<PRI>
Sets RFC 9218 priority of given URI. <PRI> must be the
wire format of priority header field (e.g., \(dqu=3,i\(dq).
This option can be used multiple times, and N\-th
\fI\%\-\-extpri\fP option sets priority of N\-th URI in the command
line. If the number of this option is less than the
number of URI, the last option value is repeated. If
there is no \fI\%\-\-extpri\fP option, urgency is 3, and
incremental is false.
.UNINDENT
.INDENT 0.0
.TP
.B \-M, \-\-peer\-max\-concurrent\-streams=<N>
Use <N> as SETTINGS_MAX_CONCURRENT_STREAMS value of
remote endpoint as if it is received in SETTINGS frame.
.sp
Default: \fB100\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-c, \-\-header\-table\-size=<SIZE>
Specify decoder header table size. If this option is
used multiple times, and the minimum value among the
given values except for last one is strictly less than
the last value, that minimum value is set in SETTINGS
frame payload before the last value, to simulate
multiple header table size change.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-encoder\-header\-table\-size=<SIZE>
Specify encoder header table size. The decoder (server)
specifies the maximum dynamic table size it accepts.
Then the negotiated dynamic table size is the minimum of
this option value and the value which server specified.
.UNINDENT
.INDENT 0.0
.TP
.B \-b, \-\-padding=<N>
Add at most <N> bytes to a frame payload as padding.
Specify 0 to disable padding.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-har=<PATH>
Output HTTP transactions <PATH> in HAR format. If \(aq\-\(aq
is given, data is written to stdout.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-color
Force colored log output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-continuation
Send large header to test CONTINUATION.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-content\-length
Don\(aqt send content\-length header field.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-hexdump
Display the incoming traffic in hexadecimal (Canonical
hex+ASCII display). If SSL/TLS is used, decrypted data
are used.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-push
Disable server push.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-concurrent\-streams=<N>
The number of concurrent pushed streams this client
accepts.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-expect\-continue
Perform an Expect/Continue handshake: wait to send DATA
(up to a short timeout) until the server sends a 100
Continue interim response. This option is ignored unless
combined with the \fI\%\-d\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \-y, \-\-no\-verify\-peer
Suppress warning on server certificate verification
failure.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ktls
Enable ktls.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Display version information and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Display this help and exit.
.UNINDENT
.sp
The <SIZE> argument is an integer and an optional unit (e.g., 10K is
10 * 1024). Units are K, M and G (powers of 1024).
.sp
The <DURATION> argument is an integer and an optional unit (e.g., 1s
is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively). If a unit
is omitted, a second is used as unit.
.SH SEE ALSO
.sp
\fBnghttpd(1)\fP, \fBnghttpx(1)\fP, \fBh2load(1)\fP
.SH AUTHOR
Tatsuhiro Tsujikawa
.SH COPYRIGHT
2012, 2015, 2016, Tatsuhiro Tsujikawa
.\" Generated by docutils manpage writer.
.
include/nghttp2/nghttp2ver.h 0000644 00000003105 15053606574 0012043 0 ustar 00 /*
* nghttp2 - HTTP/2 C Library
*
* Copyright (c) 2012, 2013 Tatsuhiro Tsujikawa
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
* LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#ifndef NGHTTP2VER_H
#define NGHTTP2VER_H
/**
* @macro
* Version number of the nghttp2 library release
*/
#define NGHTTP2_VERSION "1.66.0"
/**
* @macro
* Numerical representation of the version number of the nghttp2 library
* release. This is a 24 bit number with 8 bits for major number, 8 bits
* for minor and 8 bits for patch. Version 1.2.3 becomes 0x010203.
*/
#define NGHTTP2_VERSION_NUM 0x014200
#endif /* NGHTTP2VER_H */
include/nghttp2/nghttp2.h 0000644 00000725757 15053606574 0011356 0 ustar 00 /*
* nghttp2 - HTTP/2 C Library
*
* Copyright (c) 2013, 2014 Tatsuhiro Tsujikawa
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
* LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#ifndef NGHTTP2_H
#define NGHTTP2_H
/* Define WIN32 when build target is Win32 API (borrowed from
libcurl) */
#if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32)
# define WIN32
#endif
/* Compatibility for non-Clang compilers */
#ifndef __has_declspec_attribute
# define __has_declspec_attribute(x) 0
#endif
#ifdef __cplusplus
extern "C" {
#endif
#include <stdlib.h>
#if defined(_MSC_VER) && (_MSC_VER < 1800)
/* MSVC < 2013 does not have inttypes.h because it is not C99
compliant. See compiler macros and version number in
https://sourceforge.net/p/predef/wiki/Compilers/ */
# include <stdint.h>
#else /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */
# include <inttypes.h>
#endif /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */
#include <sys/types.h>
#include <stdarg.h>
#include <stddef.h>
#include <nghttp2/nghttp2ver.h>
#ifdef NGHTTP2_STATICLIB
# define NGHTTP2_EXTERN
#elif defined(WIN32) || \
(__has_declspec_attribute(dllexport) && __has_declspec_attribute(dllimport))
# ifdef BUILDING_NGHTTP2
# define NGHTTP2_EXTERN __declspec(dllexport)
# else /* !BUILDING_NGHTTP2 */
# define NGHTTP2_EXTERN __declspec(dllimport)
# endif /* !BUILDING_NGHTTP2 */
#else /* !defined(WIN32) */
# ifdef BUILDING_NGHTTP2
# define NGHTTP2_EXTERN __attribute__((visibility("default")))
# else /* !BUILDING_NGHTTP2 */
# define NGHTTP2_EXTERN
# endif /* !BUILDING_NGHTTP2 */
#endif /* !defined(WIN32) */
#ifdef BUILDING_NGHTTP2
# undef NGHTTP2_NO_SSIZE_T
#endif /* BUILDING_NGHTTP2 */
/**
* @typedef
*
* :type:`nghttp2_ssize` is a signed counterpart of size_t.
*/
typedef ptrdiff_t nghttp2_ssize;
/**
* @macro
*
* The protocol version identification string of this library
* supports. This identifier is used if HTTP/2 is used over TLS.
*/
#define NGHTTP2_PROTO_VERSION_ID "h2"
/**
* @macro
*
* The length of :macro:`NGHTTP2_PROTO_VERSION_ID`.
*/
#define NGHTTP2_PROTO_VERSION_ID_LEN 2
/**
* @macro
*
* The serialized form of ALPN protocol identifier this library
* supports. Notice that first byte is the length of following
* protocol identifier. This is the same wire format of `TLS ALPN
* extension <https://tools.ietf.org/html/rfc7301>`_. This is useful
* to process incoming ALPN tokens in wire format.
*/
#define NGHTTP2_PROTO_ALPN "\x2h2"
/**
* @macro
*
* The length of :macro:`NGHTTP2_PROTO_ALPN`.
*/
#define NGHTTP2_PROTO_ALPN_LEN (sizeof(NGHTTP2_PROTO_ALPN) - 1)
/**
* @macro
*
* The protocol version identification string of this library
* supports. This identifier is used if HTTP/2 is used over cleartext
* TCP.
*/
#define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID "h2c"
/**
* @macro
*
* The length of :macro:`NGHTTP2_CLEARTEXT_PROTO_VERSION_ID`.
*/
#define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN 3
struct nghttp2_session;
/**
* @struct
*
* The primary structure to hold the resources needed for a HTTP/2
* session. The details of this structure are intentionally hidden
* from the public API.
*/
typedef struct nghttp2_session nghttp2_session;
/**
* @macro
*
* The age of :type:`nghttp2_info`
*/
#define NGHTTP2_VERSION_AGE 1
/**
* @struct
*
* This struct is what `nghttp2_version()` returns. It holds
* information about the particular nghttp2 version.
*/
typedef struct {
/**
* Age of this struct. This instance of nghttp2 sets it to
* :macro:`NGHTTP2_VERSION_AGE` but a future version may bump it and
* add more struct fields at the bottom
*/
int age;
/**
* the :macro:`NGHTTP2_VERSION_NUM` number (since age ==1)
*/
int version_num;
/**
* points to the :macro:`NGHTTP2_VERSION` string (since age ==1)
*/
const char *version_str;
/**
* points to the :macro:`NGHTTP2_PROTO_VERSION_ID` string this
* instance implements (since age ==1)
*/
const char *proto_str;
/* -------- the above fields all exist when age == 1 */
} nghttp2_info;
/**
* @macro
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* The default weight of stream dependency.
*/
#define NGHTTP2_DEFAULT_WEIGHT 16
/**
* @macro
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* The maximum weight of stream dependency.
*/
#define NGHTTP2_MAX_WEIGHT 256
/**
* @macro
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* The minimum weight of stream dependency.
*/
#define NGHTTP2_MIN_WEIGHT 1
/**
* @macro
*
* The maximum window size
*/
#define NGHTTP2_MAX_WINDOW_SIZE ((int32_t)((1U << 31) - 1))
/**
* @macro
*
* The initial window size for stream level flow control.
*/
#define NGHTTP2_INITIAL_WINDOW_SIZE ((1 << 16) - 1)
/**
* @macro
*
* The initial window size for connection level flow control.
*/
#define NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE ((1 << 16) - 1)
/**
* @macro
*
* The default header table size.
*/
#define NGHTTP2_DEFAULT_HEADER_TABLE_SIZE (1 << 12)
/**
* @macro
*
* The client magic string, which is the first 24 bytes byte string of
* client connection preface.
*/
#define NGHTTP2_CLIENT_MAGIC "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
/**
* @macro
*
* The length of :macro:`NGHTTP2_CLIENT_MAGIC`.
*/
#define NGHTTP2_CLIENT_MAGIC_LEN 24
/**
* @macro
*
* The default max number of settings per SETTINGS frame
*/
#define NGHTTP2_DEFAULT_MAX_SETTINGS 32
/**
* @enum
*
* Error codes used in this library. The code range is [-999, -500],
* inclusive. The following values are defined:
*/
typedef enum {
/**
* Invalid argument passed.
*/
NGHTTP2_ERR_INVALID_ARGUMENT = -501,
/**
* Out of buffer space.
*/
NGHTTP2_ERR_BUFFER_ERROR = -502,
/**
* The specified protocol version is not supported.
*/
NGHTTP2_ERR_UNSUPPORTED_VERSION = -503,
/**
* Used as a return value from :type:`nghttp2_send_callback2`,
* :type:`nghttp2_recv_callback` and
* :type:`nghttp2_send_data_callback` to indicate that the operation
* would block.
*/
NGHTTP2_ERR_WOULDBLOCK = -504,
/**
* General protocol error
*/
NGHTTP2_ERR_PROTO = -505,
/**
* The frame is invalid.
*/
NGHTTP2_ERR_INVALID_FRAME = -506,
/**
* The peer performed a shutdown on the connection.
*/
NGHTTP2_ERR_EOF = -507,
/**
* Used as a return value from
* :func:`nghttp2_data_source_read_callback2` to indicate that data
* transfer is postponed. See
* :func:`nghttp2_data_source_read_callback2` for details.
*/
NGHTTP2_ERR_DEFERRED = -508,
/**
* Stream ID has reached the maximum value. Therefore no stream ID
* is available.
*/
NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE = -509,
/**
* The stream is already closed; or the stream ID is invalid.
*/
NGHTTP2_ERR_STREAM_CLOSED = -510,
/**
* RST_STREAM has been added to the outbound queue. The stream is
* in closing state.
*/
NGHTTP2_ERR_STREAM_CLOSING = -511,
/**
* The transmission is not allowed for this stream (e.g., a frame
* with END_STREAM flag set has already sent).
*/
NGHTTP2_ERR_STREAM_SHUT_WR = -512,
/**
* The stream ID is invalid.
*/
NGHTTP2_ERR_INVALID_STREAM_ID = -513,
/**
* The state of the stream is not valid (e.g., DATA cannot be sent
* to the stream if response HEADERS has not been sent).
*/
NGHTTP2_ERR_INVALID_STREAM_STATE = -514,
/**
* Another DATA frame has already been deferred.
*/
NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515,
/**
* Starting new stream is not allowed (e.g., GOAWAY has been sent
* and/or received).
*/
NGHTTP2_ERR_START_STREAM_NOT_ALLOWED = -516,
/**
* GOAWAY has already been sent.
*/
NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517,
/**
* The received frame contains the invalid header block (e.g., There
* are duplicate header names; or the header names are not encoded
* in US-ASCII character set and not lower cased; or the header name
* is zero-length string; or the header value contains multiple
* in-sequence NUL bytes).
*/
NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518,
/**
* Indicates that the context is not suitable to perform the
* requested operation.
*/
NGHTTP2_ERR_INVALID_STATE = -519,
/**
* The user callback function failed due to the temporal error.
*/
NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE = -521,
/**
* The length of the frame is invalid, either too large or too small.
*/
NGHTTP2_ERR_FRAME_SIZE_ERROR = -522,
/**
* Header block inflate/deflate error.
*/
NGHTTP2_ERR_HEADER_COMP = -523,
/**
* Flow control error
*/
NGHTTP2_ERR_FLOW_CONTROL = -524,
/**
* Insufficient buffer size given to function.
*/
NGHTTP2_ERR_INSUFF_BUFSIZE = -525,
/**
* Callback was paused by the application
*/
NGHTTP2_ERR_PAUSE = -526,
/**
* There are too many in-flight SETTING frame and no more
* transmission of SETTINGS is allowed.
*/
NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGS = -527,
/**
* The server push is disabled.
*/
NGHTTP2_ERR_PUSH_DISABLED = -528,
/**
* DATA or HEADERS frame for a given stream has been already
* submitted and has not been fully processed yet. Application
* should wait for the transmission of the previously submitted
* frame before submitting another.
*/
NGHTTP2_ERR_DATA_EXIST = -529,
/**
* The current session is closing due to a connection error or
* `nghttp2_session_terminate_session()` is called.
*/
NGHTTP2_ERR_SESSION_CLOSING = -530,
/**
* Invalid HTTP header field was received and stream is going to be
* closed.
*/
NGHTTP2_ERR_HTTP_HEADER = -531,
/**
* Violation in HTTP messaging rule.
*/
NGHTTP2_ERR_HTTP_MESSAGING = -532,
/**
* Stream was refused.
*/
NGHTTP2_ERR_REFUSED_STREAM = -533,
/**
* Unexpected internal error, but recovered.
*/
NGHTTP2_ERR_INTERNAL = -534,
/**
* Indicates that a processing was canceled.
*/
NGHTTP2_ERR_CANCEL = -535,
/**
* When a local endpoint expects to receive SETTINGS frame, it
* receives an other type of frame.
*/
NGHTTP2_ERR_SETTINGS_EXPECTED = -536,
/**
* When a local endpoint receives too many settings entries
* in a single SETTINGS frame.
*/
NGHTTP2_ERR_TOO_MANY_SETTINGS = -537,
/**
* The errors < :enum:`nghttp2_error.NGHTTP2_ERR_FATAL` mean that
* the library is under unexpected condition and processing was
* terminated (e.g., out of memory). If application receives this
* error code, it must stop using that :type:`nghttp2_session`
* object and only allowed operation for that object is deallocate
* it using `nghttp2_session_del()`.
*/
NGHTTP2_ERR_FATAL = -900,
/**
* Out of memory. This is a fatal error.
*/
NGHTTP2_ERR_NOMEM = -901,
/**
* The user callback function failed. This is a fatal error.
*/
NGHTTP2_ERR_CALLBACK_FAILURE = -902,
/**
* Invalid client magic (see :macro:`NGHTTP2_CLIENT_MAGIC`) was
* received and further processing is not possible.
*/
NGHTTP2_ERR_BAD_CLIENT_MAGIC = -903,
/**
* Possible flooding by peer was detected in this HTTP/2 session.
* Flooding is measured by how many PING and SETTINGS frames with
* ACK flag set are queued for transmission. These frames are
* response for the peer initiated frames, and peer can cause memory
* exhaustion on server side to send these frames forever and does
* not read network.
*/
NGHTTP2_ERR_FLOODED = -904,
/**
* When a local endpoint receives too many CONTINUATION frames
* following a HEADER frame.
*/
NGHTTP2_ERR_TOO_MANY_CONTINUATIONS = -905,
} nghttp2_error;
/**
* @struct
*
* The object representing single contiguous buffer.
*/
typedef struct {
/**
* The pointer to the buffer.
*/
uint8_t *base;
/**
* The length of the buffer.
*/
size_t len;
} nghttp2_vec;
struct nghttp2_rcbuf;
/**
* @struct
*
* The object representing reference counted buffer. The details of
* this structure are intentionally hidden from the public API.
*/
typedef struct nghttp2_rcbuf nghttp2_rcbuf;
/**
* @function
*
* Increments the reference count of |rcbuf| by 1.
*/
NGHTTP2_EXTERN void nghttp2_rcbuf_incref(nghttp2_rcbuf *rcbuf);
/**
* @function
*
* Decrements the reference count of |rcbuf| by 1. If the reference
* count becomes zero, the object pointed by |rcbuf| will be freed.
* In this case, application must not use |rcbuf| again.
*/
NGHTTP2_EXTERN void nghttp2_rcbuf_decref(nghttp2_rcbuf *rcbuf);
/**
* @function
*
* Returns the underlying buffer managed by |rcbuf|.
*/
NGHTTP2_EXTERN nghttp2_vec nghttp2_rcbuf_get_buf(nghttp2_rcbuf *rcbuf);
/**
* @function
*
* Returns nonzero if the underlying buffer is statically allocated,
* and 0 otherwise. This can be useful for language bindings that wish
* to avoid creating duplicate strings for these buffers.
*/
NGHTTP2_EXTERN int nghttp2_rcbuf_is_static(const nghttp2_rcbuf *rcbuf);
/**
* @enum
*
* The flags for header field name/value pair.
*/
typedef enum {
/**
* No flag set.
*/
NGHTTP2_NV_FLAG_NONE = 0,
/**
* Indicates that this name/value pair must not be indexed ("Literal
* Header Field never Indexed" representation must be used in HPACK
* encoding). Other implementation calls this bit as "sensitive".
*/
NGHTTP2_NV_FLAG_NO_INDEX = 0x01,
/**
* This flag is set solely by application. If this flag is set, the
* library does not make a copy of header field name. This could
* improve performance.
*/
NGHTTP2_NV_FLAG_NO_COPY_NAME = 0x02,
/**
* This flag is set solely by application. If this flag is set, the
* library does not make a copy of header field value. This could
* improve performance.
*/
NGHTTP2_NV_FLAG_NO_COPY_VALUE = 0x04
} nghttp2_nv_flag;
/**
* @struct
*
* The name/value pair, which mainly used to represent header fields.
*/
typedef struct {
/**
* The |name| byte string. If this struct is presented from library
* (e.g., :type:`nghttp2_on_frame_recv_callback`), |name| is
* guaranteed to be NULL-terminated. For some callbacks
* (:type:`nghttp2_before_frame_send_callback`,
* :type:`nghttp2_on_frame_send_callback`, and
* :type:`nghttp2_on_frame_not_send_callback`), it may not be
* NULL-terminated if header field is passed from application with
* the flag :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`).
* When application is constructing this struct, |name| is not
* required to be NULL-terminated.
*/
uint8_t *name;
/**
* The |value| byte string. If this struct is presented from
* library (e.g., :type:`nghttp2_on_frame_recv_callback`), |value|
* is guaranteed to be NULL-terminated. For some callbacks
* (:type:`nghttp2_before_frame_send_callback`,
* :type:`nghttp2_on_frame_send_callback`, and
* :type:`nghttp2_on_frame_not_send_callback`), it may not be
* NULL-terminated if header field is passed from application with
* the flag :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE`).
* When application is constructing this struct, |value| is not
* required to be NULL-terminated.
*/
uint8_t *value;
/**
* The length of the |name|, excluding terminating NULL.
*/
size_t namelen;
/**
* The length of the |value|, excluding terminating NULL.
*/
size_t valuelen;
/**
* Bitwise OR of one or more of :type:`nghttp2_nv_flag`.
*/
uint8_t flags;
} nghttp2_nv;
/**
* @enum
*
* The frame types in HTTP/2 specification.
*/
typedef enum {
/**
* The DATA frame.
*/
NGHTTP2_DATA = 0,
/**
* The HEADERS frame.
*/
NGHTTP2_HEADERS = 0x01,
/**
* The PRIORITY frame.
*/
NGHTTP2_PRIORITY = 0x02,
/**
* The RST_STREAM frame.
*/
NGHTTP2_RST_STREAM = 0x03,
/**
* The SETTINGS frame.
*/
NGHTTP2_SETTINGS = 0x04,
/**
* The PUSH_PROMISE frame.
*/
NGHTTP2_PUSH_PROMISE = 0x05,
/**
* The PING frame.
*/
NGHTTP2_PING = 0x06,
/**
* The GOAWAY frame.
*/
NGHTTP2_GOAWAY = 0x07,
/**
* The WINDOW_UPDATE frame.
*/
NGHTTP2_WINDOW_UPDATE = 0x08,
/**
* The CONTINUATION frame. This frame type won't be passed to any
* callbacks because the library processes this frame type and its
* preceding HEADERS/PUSH_PROMISE as a single frame.
*/
NGHTTP2_CONTINUATION = 0x09,
/**
* The ALTSVC frame, which is defined in `RFC 7383
* <https://tools.ietf.org/html/rfc7838#section-4>`_.
*/
NGHTTP2_ALTSVC = 0x0a,
/**
* The ORIGIN frame, which is defined by `RFC 8336
* <https://tools.ietf.org/html/rfc8336>`_.
*/
NGHTTP2_ORIGIN = 0x0c,
/**
* The PRIORITY_UPDATE frame, which is defined by :rfc:`9218`.
*/
NGHTTP2_PRIORITY_UPDATE = 0x10
} nghttp2_frame_type;
/**
* @enum
*
* The flags for HTTP/2 frames. This enum defines all flags for all
* frames.
*/
typedef enum {
/**
* No flag set.
*/
NGHTTP2_FLAG_NONE = 0,
/**
* The END_STREAM flag.
*/
NGHTTP2_FLAG_END_STREAM = 0x01,
/**
* The END_HEADERS flag.
*/
NGHTTP2_FLAG_END_HEADERS = 0x04,
/**
* The ACK flag.
*/
NGHTTP2_FLAG_ACK = 0x01,
/**
* The PADDED flag.
*/
NGHTTP2_FLAG_PADDED = 0x08,
/**
* The PRIORITY flag.
*/
NGHTTP2_FLAG_PRIORITY = 0x20
} nghttp2_flag;
/**
* @enum
* The SETTINGS ID.
*/
typedef enum {
/**
* SETTINGS_HEADER_TABLE_SIZE
*/
NGHTTP2_SETTINGS_HEADER_TABLE_SIZE = 0x01,
/**
* SETTINGS_ENABLE_PUSH
*/
NGHTTP2_SETTINGS_ENABLE_PUSH = 0x02,
/**
* SETTINGS_MAX_CONCURRENT_STREAMS
*/
NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS = 0x03,
/**
* SETTINGS_INITIAL_WINDOW_SIZE
*/
NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE = 0x04,
/**
* SETTINGS_MAX_FRAME_SIZE
*/
NGHTTP2_SETTINGS_MAX_FRAME_SIZE = 0x05,
/**
* SETTINGS_MAX_HEADER_LIST_SIZE
*/
NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE = 0x06,
/**
* SETTINGS_ENABLE_CONNECT_PROTOCOL
* (`RFC 8441 <https://tools.ietf.org/html/rfc8441>`_)
*/
NGHTTP2_SETTINGS_ENABLE_CONNECT_PROTOCOL = 0x08,
/**
* SETTINGS_NO_RFC7540_PRIORITIES (:rfc:`9218`)
*/
NGHTTP2_SETTINGS_NO_RFC7540_PRIORITIES = 0x09
} nghttp2_settings_id;
/* Note: If we add SETTINGS, update the capacity of
NGHTTP2_INBOUND_NUM_IV as well */
/**
* @macro
*
* .. warning::
*
* Deprecated. The initial max concurrent streams is 0xffffffffu.
*
* Default maximum number of incoming concurrent streams. Use
* `nghttp2_submit_settings()` with
* :enum:`nghttp2_settings_id.NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS`
* to change the maximum number of incoming concurrent streams.
*
* .. note::
*
* The maximum number of outgoing concurrent streams is 100 by
* default.
*/
#define NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS ((1U << 31) - 1)
/**
* @enum
* The status codes for the RST_STREAM and GOAWAY frames.
*/
typedef enum {
/**
* No errors.
*/
NGHTTP2_NO_ERROR = 0x00,
/**
* PROTOCOL_ERROR
*/
NGHTTP2_PROTOCOL_ERROR = 0x01,
/**
* INTERNAL_ERROR
*/
NGHTTP2_INTERNAL_ERROR = 0x02,
/**
* FLOW_CONTROL_ERROR
*/
NGHTTP2_FLOW_CONTROL_ERROR = 0x03,
/**
* SETTINGS_TIMEOUT
*/
NGHTTP2_SETTINGS_TIMEOUT = 0x04,
/**
* STREAM_CLOSED
*/
NGHTTP2_STREAM_CLOSED = 0x05,
/**
* FRAME_SIZE_ERROR
*/
NGHTTP2_FRAME_SIZE_ERROR = 0x06,
/**
* REFUSED_STREAM
*/
NGHTTP2_REFUSED_STREAM = 0x07,
/**
* CANCEL
*/
NGHTTP2_CANCEL = 0x08,
/**
* COMPRESSION_ERROR
*/
NGHTTP2_COMPRESSION_ERROR = 0x09,
/**
* CONNECT_ERROR
*/
NGHTTP2_CONNECT_ERROR = 0x0a,
/**
* ENHANCE_YOUR_CALM
*/
NGHTTP2_ENHANCE_YOUR_CALM = 0x0b,
/**
* INADEQUATE_SECURITY
*/
NGHTTP2_INADEQUATE_SECURITY = 0x0c,
/**
* HTTP_1_1_REQUIRED
*/
NGHTTP2_HTTP_1_1_REQUIRED = 0x0d
} nghttp2_error_code;
/**
* @struct
* The frame header.
*/
typedef struct {
/**
* The length field of this frame, excluding frame header.
*/
size_t length;
/**
* The stream identifier (aka, stream ID)
*/
int32_t stream_id;
/**
* The type of this frame. See `nghttp2_frame_type`.
*/
uint8_t type;
/**
* The flags.
*/
uint8_t flags;
/**
* Reserved bit in frame header. Currently, this is always set to 0
* and application should not expect something useful in here.
*/
uint8_t reserved;
} nghttp2_frame_hd;
/**
* @union
*
* This union represents the some kind of data source passed to
* :type:`nghttp2_data_source_read_callback2`.
*/
typedef union {
/**
* The integer field, suitable for a file descriptor.
*/
int fd;
/**
* The pointer to an arbitrary object.
*/
void *ptr;
} nghttp2_data_source;
/**
* @enum
*
* The flags used to set in |data_flags| output parameter in
* :type:`nghttp2_data_source_read_callback2`.
*/
typedef enum {
/**
* No flag set.
*/
NGHTTP2_DATA_FLAG_NONE = 0,
/**
* Indicates EOF was sensed.
*/
NGHTTP2_DATA_FLAG_EOF = 0x01,
/**
* Indicates that END_STREAM flag must not be set even if
* NGHTTP2_DATA_FLAG_EOF is set. Usually this flag is used to send
* trailer fields with `nghttp2_submit_request2()` or
* `nghttp2_submit_response2()`.
*/
NGHTTP2_DATA_FLAG_NO_END_STREAM = 0x02,
/**
* Indicates that application will send complete DATA frame in
* :type:`nghttp2_send_data_callback`.
*/
NGHTTP2_DATA_FLAG_NO_COPY = 0x04
} nghttp2_data_flag;
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @functypedef
*
* .. warning::
*
* Deprecated. Use :type:`nghttp2_data_source_read_callback2`
* instead.
*
* Callback function invoked when the library wants to read data from
* the |source|. The read data is sent in the stream |stream_id|.
* The implementation of this function must read at most |length|
* bytes of data from |source| (or possibly other places) and store
* them in |buf| and return number of data stored in |buf|. If EOF is
* reached, set :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` flag
* in |*data_flags|.
*
* Sometime it is desirable to avoid copying data into |buf| and let
* application to send data directly. To achieve this, set
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` to
* |*data_flags| (and possibly other flags, just like when we do
* copy), and return the number of bytes to send without copying data
* into |buf|. The library, seeing
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY`, will invoke
* :type:`nghttp2_send_data_callback`. The application must send
* complete DATA frame in that callback.
*
* If this callback is set by `nghttp2_submit_request()`,
* `nghttp2_submit_response()` or `nghttp2_submit_headers()` and
* `nghttp2_submit_data()` with flag parameter
* :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` set, and
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` flag is set to
* |*data_flags|, DATA frame will have END_STREAM flag set. Usually,
* this is expected behaviour and all are fine. One exception is send
* trailer fields. You cannot send trailer fields after sending frame
* with END_STREAM set. To avoid this problem, one can set
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_END_STREAM` along
* with :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` to signal the
* library not to set END_STREAM in DATA frame. Then application can
* use `nghttp2_submit_trailer()` to send trailer fields.
* `nghttp2_submit_trailer()` can be called inside this callback.
*
* If the application wants to postpone DATA frames (e.g.,
* asynchronous I/O, or reading data blocks for long time), it is
* achieved by returning :enum:`nghttp2_error.NGHTTP2_ERR_DEFERRED`
* without reading any data in this invocation. The library removes
* DATA frame from the outgoing queue temporarily. To move back
* deferred DATA frame to outgoing queue, call
* `nghttp2_session_resume_data()`.
*
* By default, |length| is limited to 16KiB at maximum. If peer
* allows larger frames, application can enlarge transmission buffer
* size. See :type:`nghttp2_data_source_read_length_callback` for
* more details.
*
* If the application just wants to return from
* `nghttp2_session_send()` or `nghttp2_session_mem_send()` without
* sending anything, return :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE`.
*
* In case of error, there are 2 choices. Returning
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will
* close the stream by issuing RST_STREAM with
* :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. If a different
* error code is desirable, use `nghttp2_submit_rst_stream()` with a
* desired error code and then return
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
* Returning :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will
* signal the entire session failure.
*/
typedef ssize_t (*nghttp2_data_source_read_callback)(
nghttp2_session *session, int32_t stream_id, uint8_t *buf, size_t length,
uint32_t *data_flags, nghttp2_data_source *source, void *user_data);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @functypedef
*
* Callback function invoked when the library wants to read data from
* the |source|. The read data is sent in the stream |stream_id|.
* The implementation of this function must read at most |length|
* bytes of data from |source| (or possibly other places) and store
* them in |buf| and return number of data stored in |buf|. If EOF is
* reached, set :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` flag
* in |*data_flags|.
*
* Sometime it is desirable to avoid copying data into |buf| and let
* application to send data directly. To achieve this, set
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` to
* |*data_flags| (and possibly other flags, just like when we do
* copy), and return the number of bytes to send without copying data
* into |buf|. The library, seeing
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY`, will invoke
* :type:`nghttp2_send_data_callback`. The application must send
* complete DATA frame in that callback.
*
* If this callback is set by `nghttp2_submit_request2()`,
* `nghttp2_submit_response2()` or `nghttp2_submit_headers()` and
* `nghttp2_submit_data2()` with flag parameter
* :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` set, and
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` flag is set to
* |*data_flags|, DATA frame will have END_STREAM flag set. Usually,
* this is expected behaviour and all are fine. One exception is send
* trailer fields. You cannot send trailer fields after sending frame
* with END_STREAM set. To avoid this problem, one can set
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_END_STREAM` along
* with :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` to signal the
* library not to set END_STREAM in DATA frame. Then application can
* use `nghttp2_submit_trailer()` to send trailer fields.
* `nghttp2_submit_trailer()` can be called inside this callback.
*
* If the application wants to postpone DATA frames (e.g.,
* asynchronous I/O, or reading data blocks for long time), it is
* achieved by returning :enum:`nghttp2_error.NGHTTP2_ERR_DEFERRED`
* without reading any data in this invocation. The library removes
* DATA frame from the outgoing queue temporarily. To move back
* deferred DATA frame to outgoing queue, call
* `nghttp2_session_resume_data()`.
*
* By default, |length| is limited to 16KiB at maximum. If peer
* allows larger frames, application can enlarge transmission buffer
* size. See :type:`nghttp2_data_source_read_length_callback` for
* more details.
*
* If the application just wants to return from
* `nghttp2_session_send()` or `nghttp2_session_mem_send2()` without
* sending anything, return :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE`.
*
* In case of error, there are 2 choices. Returning
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will
* close the stream by issuing RST_STREAM with
* :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. If a different
* error code is desirable, use `nghttp2_submit_rst_stream()` with a
* desired error code and then return
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
* Returning :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will
* signal the entire session failure.
*/
typedef nghttp2_ssize (*nghttp2_data_source_read_callback2)(
nghttp2_session *session, int32_t stream_id, uint8_t *buf, size_t length,
uint32_t *data_flags, nghttp2_data_source *source, void *user_data);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @struct
*
* .. warning::
*
* Deprecated. Use :type:`nghttp2_data_provider2` instead.
*
* This struct represents the data source and the way to read a chunk
* of data from it.
*/
typedef struct {
/**
* The data source.
*/
nghttp2_data_source source;
/**
* The callback function to read a chunk of data from the |source|.
*/
nghttp2_data_source_read_callback read_callback;
} nghttp2_data_provider;
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @struct
*
* This struct represents the data source and the way to read a chunk
* of data from it.
*/
typedef struct {
/**
* The data source.
*/
nghttp2_data_source source;
/**
* The callback function to read a chunk of data from the |source|.
*/
nghttp2_data_source_read_callback2 read_callback;
} nghttp2_data_provider2;
/**
* @struct
*
* The DATA frame. The received data is delivered via
* :type:`nghttp2_on_data_chunk_recv_callback`.
*/
typedef struct {
nghttp2_frame_hd hd;
/**
* The length of the padding in this frame. This includes PAD_HIGH
* and PAD_LOW.
*/
size_t padlen;
} nghttp2_data;
/**
* @enum
*
* The category of HEADERS, which indicates the role of the frame. In
* HTTP/2 spec, request, response, push response and other arbitrary
* headers (e.g., trailer fields) are all called just HEADERS. To
* give the application the role of incoming HEADERS frame, we define
* several categories.
*/
typedef enum {
/**
* The HEADERS frame is opening new stream, which is analogous to
* SYN_STREAM in SPDY.
*/
NGHTTP2_HCAT_REQUEST = 0,
/**
* The HEADERS frame is the first response headers, which is
* analogous to SYN_REPLY in SPDY.
*/
NGHTTP2_HCAT_RESPONSE = 1,
/**
* The HEADERS frame is the first headers sent against reserved
* stream.
*/
NGHTTP2_HCAT_PUSH_RESPONSE = 2,
/**
* The HEADERS frame which does not apply for the above categories,
* which is analogous to HEADERS in SPDY. If non-final response
* (e.g., status 1xx) is used, final response HEADERS frame will be
* categorized here.
*/
NGHTTP2_HCAT_HEADERS = 3
} nghttp2_headers_category;
/**
* @struct
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* The structure to specify stream dependency.
*/
typedef struct {
/**
* The stream ID of the stream to depend on. Specifying 0 makes
* stream not depend any other stream.
*/
int32_t stream_id;
/**
* The weight of this dependency.
*/
int32_t weight;
/**
* nonzero means exclusive dependency
*/
uint8_t exclusive;
} nghttp2_priority_spec;
/**
* @struct
*
* The HEADERS frame. It has the following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The length of the padding in this frame. This includes PAD_HIGH
* and PAD_LOW.
*/
size_t padlen;
/**
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* The priority specification
*/
nghttp2_priority_spec pri_spec;
/**
* The name/value pairs.
*/
nghttp2_nv *nva;
/**
* The number of name/value pairs in |nva|.
*/
size_t nvlen;
/**
* The category of this HEADERS frame.
*/
nghttp2_headers_category cat;
} nghttp2_headers;
/**
* @struct
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* The PRIORITY frame. It has the following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The priority specification.
*/
nghttp2_priority_spec pri_spec;
} nghttp2_priority;
/**
* @struct
*
* The RST_STREAM frame. It has the following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The error code. See :type:`nghttp2_error_code`.
*/
uint32_t error_code;
} nghttp2_rst_stream;
/**
* @struct
*
* The SETTINGS ID/Value pair. It has the following members:
*/
typedef struct {
/**
* The SETTINGS ID. See :type:`nghttp2_settings_id`.
*/
int32_t settings_id;
/**
* The value of this entry.
*/
uint32_t value;
} nghttp2_settings_entry;
/**
* @struct
*
* The SETTINGS frame. It has the following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The number of SETTINGS ID/Value pairs in |iv|.
*/
size_t niv;
/**
* The pointer to the array of SETTINGS ID/Value pair.
*/
nghttp2_settings_entry *iv;
} nghttp2_settings;
/**
* @struct
*
* The PUSH_PROMISE frame. It has the following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The length of the padding in this frame. This includes PAD_HIGH
* and PAD_LOW.
*/
size_t padlen;
/**
* The name/value pairs.
*/
nghttp2_nv *nva;
/**
* The number of name/value pairs in |nva|.
*/
size_t nvlen;
/**
* The promised stream ID
*/
int32_t promised_stream_id;
/**
* Reserved bit. Currently this is always set to 0 and application
* should not expect something useful in here.
*/
uint8_t reserved;
} nghttp2_push_promise;
/**
* @struct
*
* The PING frame. It has the following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The opaque data
*/
uint8_t opaque_data[8];
} nghttp2_ping;
/**
* @struct
*
* The GOAWAY frame. It has the following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The last stream stream ID.
*/
int32_t last_stream_id;
/**
* The error code. See :type:`nghttp2_error_code`.
*/
uint32_t error_code;
/**
* The additional debug data
*/
uint8_t *opaque_data;
/**
* The length of |opaque_data| member.
*/
size_t opaque_data_len;
/**
* Reserved bit. Currently this is always set to 0 and application
* should not expect something useful in here.
*/
uint8_t reserved;
} nghttp2_goaway;
/**
* @struct
*
* The WINDOW_UPDATE frame. It has the following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The window size increment.
*/
int32_t window_size_increment;
/**
* Reserved bit. Currently this is always set to 0 and application
* should not expect something useful in here.
*/
uint8_t reserved;
} nghttp2_window_update;
/**
* @struct
*
* The extension frame. It has following members:
*/
typedef struct {
/**
* The frame header.
*/
nghttp2_frame_hd hd;
/**
* The pointer to extension payload. The exact pointer type is
* determined by hd.type.
*
* Currently, no extension is supported. This is a place holder for
* the future extensions.
*/
void *payload;
} nghttp2_extension;
/**
* @union
*
* This union includes all frames to pass them to various function
* calls as nghttp2_frame type. The CONTINUATION frame is omitted
* from here because the library deals with it internally.
*/
typedef union {
/**
* The frame header, which is convenient to inspect frame header.
*/
nghttp2_frame_hd hd;
/**
* The DATA frame.
*/
nghttp2_data data;
/**
* The HEADERS frame.
*/
nghttp2_headers headers;
/**
* The PRIORITY frame.
*/
nghttp2_priority priority;
/**
* The RST_STREAM frame.
*/
nghttp2_rst_stream rst_stream;
/**
* The SETTINGS frame.
*/
nghttp2_settings settings;
/**
* The PUSH_PROMISE frame.
*/
nghttp2_push_promise push_promise;
/**
* The PING frame.
*/
nghttp2_ping ping;
/**
* The GOAWAY frame.
*/
nghttp2_goaway goaway;
/**
* The WINDOW_UPDATE frame.
*/
nghttp2_window_update window_update;
/**
* The extension frame.
*/
nghttp2_extension ext;
} nghttp2_frame;
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @functypedef
*
* .. warning::
*
* Deprecated. Use :type:`nghttp2_send_callback2` instead.
*
* Callback function invoked when |session| wants to send data to the
* remote peer. The implementation of this function must send at most
* |length| bytes of data stored in |data|. The |flags| is currently
* not used and always 0. It must return the number of bytes sent if
* it succeeds. If it cannot send any single byte without blocking,
* it must return :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. For
* other errors, it must return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. The
* |user_data| pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* This callback is required if the application uses
* `nghttp2_session_send()` to send data to the remote endpoint. If
* the application uses solely `nghttp2_session_mem_send()` instead,
* this callback function is unnecessary.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_send_callback()`.
*
* .. note::
*
* The |length| may be very small. If that is the case, and
* application disables Nagle algorithm (``TCP_NODELAY``), then just
* writing |data| to the network stack leads to very small packet,
* and it is very inefficient. An application should be responsible
* to buffer up small chunks of data as necessary to avoid this
* situation.
*/
typedef ssize_t (*nghttp2_send_callback)(nghttp2_session *session,
const uint8_t *data, size_t length,
int flags, void *user_data);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @functypedef
*
* Callback function invoked when |session| wants to send data to the
* remote peer. The implementation of this function must send at most
* |length| bytes of data stored in |data|. The |flags| is currently
* not used and always 0. It must return the number of bytes sent if
* it succeeds. If it cannot send any single byte without blocking,
* it must return :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. For
* other errors, it must return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. The
* |user_data| pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* This callback is required if the application uses
* `nghttp2_session_send()` to send data to the remote endpoint. If
* the application uses solely `nghttp2_session_mem_send2()` instead,
* this callback function is unnecessary.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_send_callback2()`.
*
* .. note::
*
* The |length| may be very small. If that is the case, and
* application disables Nagle algorithm (``TCP_NODELAY``), then just
* writing |data| to the network stack leads to very small packet,
* and it is very inefficient. An application should be responsible
* to buffer up small chunks of data as necessary to avoid this
* situation.
*/
typedef nghttp2_ssize (*nghttp2_send_callback2)(nghttp2_session *session,
const uint8_t *data,
size_t length, int flags,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` is used in
* :type:`nghttp2_data_source_read_callback` to send complete DATA
* frame.
*
* The |frame| is a DATA frame to send. The |framehd| is the
* serialized frame header (9 bytes). The |length| is the length of
* application data to send (this does not include padding). The
* |source| is the same pointer passed to
* :type:`nghttp2_data_source_read_callback`.
*
* The application first must send frame header |framehd| of length 9
* bytes. If ``frame->data.padlen > 0``, send 1 byte of value
* ``frame->data.padlen - 1``. Then send exactly |length| bytes of
* application data. Finally, if ``frame->data.padlen > 1``, send
* ``frame->data.padlen - 1`` bytes of zero as padding.
*
* The application has to send complete DATA frame in this callback.
* If all data were written successfully, return 0.
*
* If it cannot send any data at all, just return
* :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`; the library will call
* this callback with the same parameters later (It is recommended to
* send complete DATA frame at once in this function to deal with
* error; if partial frame data has already sent, it is impossible to
* send another data in that state, and all we can do is tear down
* connection). When data is fully processed, but application wants
* to make `nghttp2_session_mem_send2()` or `nghttp2_session_send()`
* return immediately without processing next frames, return
* :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE`. If application decided to
* reset this stream, return
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`, then
* the library will send RST_STREAM with INTERNAL_ERROR as error code.
* The application can also return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, which will
* result in connection closure. Returning any other value is treated
* as :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned.
*/
typedef int (*nghttp2_send_data_callback)(nghttp2_session *session,
nghttp2_frame *frame,
const uint8_t *framehd, size_t length,
nghttp2_data_source *source,
void *user_data);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @functypedef
*
* .. warning::
*
* Deprecated. Use :type:`nghttp2_recv_callback2` instead.
*
* Callback function invoked when |session| wants to receive data from
* the remote peer. The implementation of this function must read at
* most |length| bytes of data and store it in |buf|. The |flags| is
* currently not used and always 0. It must return the number of
* bytes written in |buf| if it succeeds. If it cannot read any
* single byte without blocking, it must return
* :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. If it gets EOF
* before it reads any single byte, it must return
* :enum:`nghttp2_error.NGHTTP2_ERR_EOF`. For other errors, it must
* return :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
* Returning 0 is treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. The |user_data|
* pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* This callback is required if the application uses
* `nghttp2_session_recv()` to receive data from the remote endpoint.
* If the application uses solely `nghttp2_session_mem_recv()`
* instead, this callback function is unnecessary.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_recv_callback()`.
*/
typedef ssize_t (*nghttp2_recv_callback)(nghttp2_session *session, uint8_t *buf,
size_t length, int flags,
void *user_data);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @functypedef
*
* Callback function invoked when |session| wants to receive data from
* the remote peer. The implementation of this function must read at
* most |length| bytes of data and store it in |buf|. The |flags| is
* currently not used and always 0. It must return the number of
* bytes written in |buf| if it succeeds. If it cannot read any
* single byte without blocking, it must return
* :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. If it gets EOF
* before it reads any single byte, it must return
* :enum:`nghttp2_error.NGHTTP2_ERR_EOF`. For other errors, it must
* return :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
* Returning 0 is treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. The |user_data|
* pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* This callback is required if the application uses
* `nghttp2_session_recv()` to receive data from the remote endpoint.
* If the application uses solely `nghttp2_session_mem_recv2()`
* instead, this callback function is unnecessary.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_recv_callback2()`.
*/
typedef nghttp2_ssize (*nghttp2_recv_callback2)(nghttp2_session *session,
uint8_t *buf, size_t length,
int flags, void *user_data);
/**
* @functypedef
*
* Callback function invoked by `nghttp2_session_recv()` and
* `nghttp2_session_mem_recv2()` when a frame is received. The
* |user_data| pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
* member of their data structure are always ``NULL`` and 0
* respectively. The header name/value pairs are emitted via
* :type:`nghttp2_on_header_callback`.
*
* Only HEADERS and DATA frame can signal the end of incoming data.
* If ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
* |frame| is the last frame from the remote peer in this stream.
*
* This callback won't be called for CONTINUATION frames.
* HEADERS/PUSH_PROMISE + CONTINUATIONs are treated as single frame.
*
* The implementation of this function must return 0 if it succeeds.
* If nonzero value is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_frame_recv_callback()`.
*/
typedef int (*nghttp2_on_frame_recv_callback)(nghttp2_session *session,
const nghttp2_frame *frame,
void *user_data);
/**
* @functypedef
*
* Callback function invoked by `nghttp2_session_recv()` and
* `nghttp2_session_mem_recv2()` when an invalid non-DATA frame is
* received. The error is indicated by the |lib_error_code|, which is
* one of the values defined in :type:`nghttp2_error`. When this
* callback function is invoked, the library automatically submits
* either RST_STREAM or GOAWAY frame. The |user_data| pointer is the
* third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
* member of their data structure are always ``NULL`` and 0
* respectively.
*
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_invalid_frame_recv_callback()`.
*/
typedef int (*nghttp2_on_invalid_frame_recv_callback)(
nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when a chunk of data in DATA frame is
* received. The |stream_id| is the stream ID this DATA frame belongs
* to. The |flags| is the flags of DATA frame which this data chunk
* is contained. ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
* necessarily mean this chunk of data is the last one in the stream.
* You should use :type:`nghttp2_on_frame_recv_callback` to know all
* data frames are received. The |user_data| pointer is the third
* argument passed in to the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* If the application uses `nghttp2_session_mem_recv2()`, it can
* return :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` to make
* `nghttp2_session_mem_recv2()` return without processing further
* input bytes. The memory by pointed by the |data| is retained until
* `nghttp2_session_mem_recv2()` or `nghttp2_session_recv()` is
* called. The application must retain the input bytes which was used
* to produce the |data| parameter, because it may refer to the memory
* region included in the input bytes.
*
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error, and
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_data_chunk_recv_callback()`.
*/
typedef int (*nghttp2_on_data_chunk_recv_callback)(nghttp2_session *session,
uint8_t flags,
int32_t stream_id,
const uint8_t *data,
size_t len, void *user_data);
/**
* @functypedef
*
* Callback function invoked just before the non-DATA frame |frame| is
* sent. The |user_data| pointer is the third argument passed in to
* the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* The implementation of this function must return 0 if it succeeds.
* It can also return :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL` to
* cancel the transmission of the given frame.
*
* If there is a fatal error while executing this callback, the
* implementation should return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, which makes
* `nghttp2_session_send()` and `nghttp2_session_mem_send2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* If the other value is returned, it is treated as if
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned.
* But the implementation should not rely on this since the library
* may define new return value to extend its capability.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_before_frame_send_callback()`.
*/
typedef int (*nghttp2_before_frame_send_callback)(nghttp2_session *session,
const nghttp2_frame *frame,
void *user_data);
/**
* @functypedef
*
* Callback function invoked after the frame |frame| is sent. The
* |user_data| pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_send()` and `nghttp2_session_mem_send2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_frame_send_callback()`.
*/
typedef int (*nghttp2_on_frame_send_callback)(nghttp2_session *session,
const nghttp2_frame *frame,
void *user_data);
/**
* @functypedef
*
* Callback function invoked after the non-DATA frame |frame| is not
* sent because of the error. The error is indicated by the
* |lib_error_code|, which is one of the values defined in
* :type:`nghttp2_error`. The |user_data| pointer is the third
* argument passed in to the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_send()` and `nghttp2_session_mem_send2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* `nghttp2_session_get_stream_user_data()` can be used to get
* associated data.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_frame_not_send_callback()`.
*/
typedef int (*nghttp2_on_frame_not_send_callback)(nghttp2_session *session,
const nghttp2_frame *frame,
int lib_error_code,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when the stream |stream_id| is closed.
* The reason of closure is indicated by the |error_code|. The
* |error_code| is usually one of :enum:`nghttp2_error_code`, but that
* is not guaranteed. The stream_user_data, which was specified in
* `nghttp2_submit_request2()` or `nghttp2_submit_headers()`, is still
* available in this function. The |user_data| pointer is the third
* argument passed in to the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* This function is also called for a stream in reserved state.
*
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()`, `nghttp2_session_mem_recv2()`,
* `nghttp2_session_send()`, and `nghttp2_session_mem_send2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_stream_close_callback()`.
*/
typedef int (*nghttp2_on_stream_close_callback)(nghttp2_session *session,
int32_t stream_id,
uint32_t error_code,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when the reception of header block in
* HEADERS or PUSH_PROMISE is started. Each header name/value pair
* will be emitted by :type:`nghttp2_on_header_callback`.
*
* The ``frame->hd.flags`` may not have
* :enum:`nghttp2_flag.NGHTTP2_FLAG_END_HEADERS` flag set, which
* indicates that one or more CONTINUATION frames are involved. But
* the application does not need to care about that because the header
* name/value pairs are emitted transparently regardless of
* CONTINUATION frames.
*
* The server applications probably create an object to store
* information about new stream if ``frame->hd.type ==
* NGHTTP2_HEADERS`` and ``frame->headers.cat ==
* NGHTTP2_HCAT_REQUEST``. If |session| is configured as server side,
* ``frame->headers.cat`` is either ``NGHTTP2_HCAT_REQUEST``
* containing request headers or ``NGHTTP2_HCAT_HEADERS`` containing
* trailer fields and never get PUSH_PROMISE in this callback.
*
* For the client applications, ``frame->hd.type`` is either
* ``NGHTTP2_HEADERS`` or ``NGHTTP2_PUSH_PROMISE``. In case of
* ``NGHTTP2_HEADERS``, ``frame->headers.cat ==
* NGHTTP2_HCAT_RESPONSE`` means that it is the first response
* headers, but it may be non-final response which is indicated by 1xx
* status code. In this case, there may be zero or more HEADERS frame
* with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS`` which has
* non-final response code and finally client gets exactly one HEADERS
* frame with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS``
* containing final response headers (non-1xx status code). The
* trailer fields also has ``frame->headers.cat ==
* NGHTTP2_HCAT_HEADERS`` which does not contain any status code.
*
* Returning
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will
* close the stream (promised stream if frame is PUSH_PROMISE) by
* issuing RST_STREAM with
* :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. In this case,
* :type:`nghttp2_on_header_callback` and
* :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a
* different error code is desirable, use
* `nghttp2_submit_rst_stream()` with a desired error code and then
* return :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
* Again, use ``frame->push_promise.promised_stream_id`` as stream_id
* parameter in `nghttp2_submit_rst_stream()` if frame is
* PUSH_PROMISE.
*
* The implementation of this function must return 0 if it succeeds.
* It can return
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` to
* reset the stream (promised stream if frame is PUSH_PROMISE). For
* critical errors, it must return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
* value is returned, it is treated as if
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned. If
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
* `nghttp2_session_mem_recv2()` function will immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_begin_headers_callback()`.
*/
typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session,
const nghttp2_frame *frame,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when a header name/value pair is received
* for the |frame|. The |name| of length |namelen| is header name.
* The |value| of length |valuelen| is header value. The |flags| is
* bitwise OR of one or more of :type:`nghttp2_nv_flag`.
*
* If :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_INDEX` is set in
* |flags|, the receiver must not index this name/value pair when
* forwarding it to the next hop. More specifically, "Literal Header
* Field never Indexed" representation must be used in HPACK encoding.
*
* When this callback is invoked, ``frame->hd.type`` is either
* :enum:`nghttp2_frame_type.NGHTTP2_HEADERS` or
* :enum:`nghttp2_frame_type.NGHTTP2_PUSH_PROMISE`. After all header
* name/value pairs are processed with this callback, and no error has
* been detected, :type:`nghttp2_on_frame_recv_callback` will be
* invoked. If there is an error in decompression,
* :type:`nghttp2_on_frame_recv_callback` for the |frame| will not be
* invoked.
*
* Both |name| and |value| are guaranteed to be NULL-terminated. The
* |namelen| and |valuelen| do not include terminal NULL. If
* `nghttp2_option_set_no_http_messaging()` is used with nonzero
* value, NULL character may be included in |name| or |value| before
* terminating NULL.
*
* Please note that unless `nghttp2_option_set_no_http_messaging()` is
* used, nghttp2 library does perform validation against the |name|
* and the |value| using `nghttp2_check_header_name()` and
* `nghttp2_check_header_value()`. In addition to this, nghttp2
* performs validation based on HTTP Messaging rule, which is briefly
* explained in :ref:`http-messaging` section.
*
* If the application uses `nghttp2_session_mem_recv2()`, it can
* return :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` to make
* `nghttp2_session_mem_recv2()` return without processing further
* input bytes. The memory pointed by |frame|, |name| and |value|
* parameters are retained until `nghttp2_session_mem_recv2()` or
* `nghttp2_session_recv()` is called. The application must retain
* the input bytes which was used to produce these parameters, because
* it may refer to the memory region included in the input bytes.
*
* Returning
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will
* close the stream (promised stream if frame is PUSH_PROMISE) by
* issuing RST_STREAM with
* :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. In this case,
* :type:`nghttp2_on_header_callback` and
* :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a
* different error code is desirable, use
* `nghttp2_submit_rst_stream()` with a desired error code and then
* return :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
* Again, use ``frame->push_promise.promised_stream_id`` as stream_id
* parameter in `nghttp2_submit_rst_stream()` if frame is
* PUSH_PROMISE.
*
* The implementation of this function must return 0 if it succeeds.
* It may return :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` or
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. For
* other critical failures, it must return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
* nonzero value is returned, it is treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_header_callback()`.
*
* .. warning::
*
* Application should properly limit the total buffer size to store
* incoming header fields. Without it, peer may send large number
* of header fields or large header fields to cause out of memory in
* local endpoint. Due to how HPACK works, peer can do this
* effectively without using much memory on their own.
*/
typedef int (*nghttp2_on_header_callback)(nghttp2_session *session,
const nghttp2_frame *frame,
const uint8_t *name, size_t namelen,
const uint8_t *value, size_t valuelen,
uint8_t flags, void *user_data);
/**
* @functypedef
*
* Callback function invoked when a header name/value pair is received
* for the |frame|. The |name| is header name. The |value| is header
* value. The |flags| is bitwise OR of one or more of
* :type:`nghttp2_nv_flag`.
*
* This callback behaves like :type:`nghttp2_on_header_callback`,
* except that |name| and |value| are stored in reference counted
* buffer. If application wishes to keep these references without
* copying them, use `nghttp2_rcbuf_incref()` to increment their
* reference count. It is the application's responsibility to call
* `nghttp2_rcbuf_decref()` if they called `nghttp2_rcbuf_incref()` so
* as not to leak memory. If the |session| is created by
* `nghttp2_session_server_new3()` or `nghttp2_session_client_new3()`,
* the function to free memory is the one belongs to the mem
* parameter. As long as this free function alives, |name| and
* |value| can live after |session| was destroyed.
*/
typedef int (*nghttp2_on_header_callback2)(nghttp2_session *session,
const nghttp2_frame *frame,
nghttp2_rcbuf *name,
nghttp2_rcbuf *value, uint8_t flags,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when a invalid header name/value pair is
* received for the |frame|.
*
* The parameter and behaviour are similar to
* :type:`nghttp2_on_header_callback`. The difference is that this
* callback is only invoked when a invalid header name/value pair is
* received which is treated as stream error if this callback is not
* set. Only invalid regular header field are passed to this
* callback. In other words, invalid pseudo header field is not
* passed to this callback. Also header fields which includes upper
* cased latter are also treated as error without passing them to this
* callback.
*
* This callback is only considered if HTTP messaging validation is
* turned on (which is on by default, see
* `nghttp2_option_set_no_http_messaging()`).
*
* With this callback, application inspects the incoming invalid
* field, and it also can reset stream from this callback by returning
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. By
* default, the error code is
* :enum:`nghttp2_error_code.NGHTTP2_PROTOCOL_ERROR`. To change the
* error code, call `nghttp2_submit_rst_stream()` with the error code
* of choice in addition to returning
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
*
* If 0 is returned, the header field is ignored, and the stream is
* not reset.
*/
typedef int (*nghttp2_on_invalid_header_callback)(
nghttp2_session *session, const nghttp2_frame *frame, const uint8_t *name,
size_t namelen, const uint8_t *value, size_t valuelen, uint8_t flags,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when a invalid header name/value pair is
* received for the |frame|.
*
* The parameter and behaviour are similar to
* :type:`nghttp2_on_header_callback2`. The difference is that this
* callback is only invoked when a invalid header name/value pair is
* received which is silently ignored if this callback is not set.
* Only invalid regular header field are passed to this callback. In
* other words, invalid pseudo header field is not passed to this
* callback. Also header fields which includes upper cased latter are
* also treated as error without passing them to this callback.
*
* This callback is only considered if HTTP messaging validation is
* turned on (which is on by default, see
* `nghttp2_option_set_no_http_messaging()`).
*
* With this callback, application inspects the incoming invalid
* field, and it also can reset stream from this callback by returning
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. By
* default, the error code is
* :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. To change the
* error code, call `nghttp2_submit_rst_stream()` with the error code
* of choice in addition to returning
* :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
*/
typedef int (*nghttp2_on_invalid_header_callback2)(
nghttp2_session *session, const nghttp2_frame *frame, nghttp2_rcbuf *name,
nghttp2_rcbuf *value, uint8_t flags, void *user_data);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @functypedef
*
* .. warning::
*
* Deprecated. Use :type:`nghttp2_select_padding_callback2`
* instead.
*
* Callback function invoked when the library asks application how
* many padding bytes are required for the transmission of the
* |frame|. The application must choose the total length of payload
* including padded bytes in range [frame->hd.length, max_payloadlen],
* inclusive. Choosing number not in this range will be treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Returning
* ``frame->hd.length`` means no padding is added. Returning
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will make
* `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
* immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_select_padding_callback()`.
*/
typedef ssize_t (*nghttp2_select_padding_callback)(nghttp2_session *session,
const nghttp2_frame *frame,
size_t max_payloadlen,
void *user_data);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @functypedef
*
* Callback function invoked when the library asks application how
* many padding bytes are required for the transmission of the
* |frame|. The application must choose the total length of payload
* including padded bytes in range [frame->hd.length, max_payloadlen],
* inclusive. Choosing number not in this range will be treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Returning
* ``frame->hd.length`` means no padding is added. Returning
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will make
* `nghttp2_session_send()` and `nghttp2_session_mem_send2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_select_padding_callback2()`.
*/
typedef nghttp2_ssize (*nghttp2_select_padding_callback2)(
nghttp2_session *session, const nghttp2_frame *frame, size_t max_payloadlen,
void *user_data);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @functypedef
*
* .. warning::
*
* Deprecated. Use
* :type:`nghttp2_data_source_read_length_callback2` instead.
*
* Callback function invoked when library wants to get max length of
* data to send data to the remote peer. The implementation of this
* function should return a value in the following range. [1,
* min(|session_remote_window_size|, |stream_remote_window_size|,
* |remote_max_frame_size|)]. If a value greater than this range is
* returned than the max allow value will be used. Returning a value
* smaller than this range is treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. The
* |frame_type| is provided for future extensibility and identifies
* the type of frame (see :type:`nghttp2_frame_type`) for which to get
* the length for. Currently supported frame types are:
* :enum:`nghttp2_frame_type.NGHTTP2_DATA`.
*
* This callback can be used to control the length in bytes for which
* :type:`nghttp2_data_source_read_callback` is allowed to send to the
* remote endpoint. This callback is optional. Returning
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will signal the
* entire session failure.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_data_source_read_length_callback()`.
*/
typedef ssize_t (*nghttp2_data_source_read_length_callback)(
nghttp2_session *session, uint8_t frame_type, int32_t stream_id,
int32_t session_remote_window_size, int32_t stream_remote_window_size,
uint32_t remote_max_frame_size, void *user_data);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @functypedef
*
* Callback function invoked when library wants to get max length of
* data to send data to the remote peer. The implementation of this
* function should return a value in the following range. [1,
* min(|session_remote_window_size|, |stream_remote_window_size|,
* |remote_max_frame_size|)]. If a value greater than this range is
* returned than the max allow value will be used. Returning a value
* smaller than this range is treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. The
* |frame_type| is provided for future extensibility and identifies
* the type of frame (see :type:`nghttp2_frame_type`) for which to get
* the length for. Currently supported frame types are:
* :enum:`nghttp2_frame_type.NGHTTP2_DATA`.
*
* This callback can be used to control the length in bytes for which
* :type:`nghttp2_data_source_read_callback` is allowed to send to the
* remote endpoint. This callback is optional. Returning
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will signal the
* entire session failure.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_data_source_read_length_callback2()`.
*/
typedef nghttp2_ssize (*nghttp2_data_source_read_length_callback2)(
nghttp2_session *session, uint8_t frame_type, int32_t stream_id,
int32_t session_remote_window_size, int32_t stream_remote_window_size,
uint32_t remote_max_frame_size, void *user_data);
/**
* @functypedef
*
* Callback function invoked when a frame header is received. The
* |hd| points to received frame header.
*
* Unlike :type:`nghttp2_on_frame_recv_callback`, this callback will
* also be called when frame header of CONTINUATION frame is received.
*
* If both :type:`nghttp2_on_begin_frame_callback` and
* :type:`nghttp2_on_begin_headers_callback` are set and HEADERS or
* PUSH_PROMISE is received, :type:`nghttp2_on_begin_frame_callback`
* will be called first.
*
* The implementation of this function must return 0 if it succeeds.
* If nonzero value is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*
* To set this callback to :type:`nghttp2_session_callbacks`, use
* `nghttp2_session_callbacks_set_on_begin_frame_callback()`.
*/
typedef int (*nghttp2_on_begin_frame_callback)(nghttp2_session *session,
const nghttp2_frame_hd *hd,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when chunk of extension frame payload is
* received. The |hd| points to frame header. The received
* chunk is |data| of length |len|.
*
* The implementation of this function must return 0 if it succeeds.
*
* To abort processing this extension frame, return
* :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`.
*
* If fatal error occurred, application should return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
* values are returned, currently they are treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
typedef int (*nghttp2_on_extension_chunk_recv_callback)(
nghttp2_session *session, const nghttp2_frame_hd *hd, const uint8_t *data,
size_t len, void *user_data);
/**
* @functypedef
*
* Callback function invoked when library asks the application to
* unpack extension payload from its wire format. The extension
* payload has been passed to the application using
* :type:`nghttp2_on_extension_chunk_recv_callback`. The frame header
* is already unpacked by the library and provided as |hd|.
*
* To receive extension frames, the application must tell desired
* extension frame type to the library using
* `nghttp2_option_set_user_recv_extension_type()`.
*
* The implementation of this function may store the pointer to the
* created object as a result of unpacking in |*payload|, and returns
* 0. The pointer stored in |*payload| is opaque to the library, and
* the library does not own its pointer. |*payload| is initialized as
* ``NULL``. The |*payload| is available as ``frame->ext.payload`` in
* :type:`nghttp2_on_frame_recv_callback`. Therefore if application
* can free that memory inside :type:`nghttp2_on_frame_recv_callback`
* callback. Of course, application has a liberty not to use
* |*payload|, and do its own mechanism to process extension frames.
*
* To abort processing this extension frame, return
* :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`.
*
* If fatal error occurred, application should return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
* values are returned, currently they are treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
typedef int (*nghttp2_unpack_extension_callback)(nghttp2_session *session,
void **payload,
const nghttp2_frame_hd *hd,
void *user_data);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @functypedef
*
* .. warning::
*
* Deprecated. Use :type:`nghttp2_pack_extension_callback2`
* instead.
*
* Callback function invoked when library asks the application to pack
* extension payload in its wire format. The frame header will be
* packed by library. Application must pack payload only.
* ``frame->ext.payload`` is the object passed to
* `nghttp2_submit_extension()` as payload parameter. Application
* must pack extension payload to the |buf| of its capacity |len|
* bytes. The |len| is at least 16KiB.
*
* The implementation of this function should return the number of
* bytes written into |buf| when it succeeds.
*
* To abort processing this extension frame, return
* :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`, and
* :type:`nghttp2_on_frame_not_send_callback` will be invoked.
*
* If fatal error occurred, application should return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
* `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
* immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
* values are returned, currently they are treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the return
* value is strictly larger than |len|, it is treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
typedef ssize_t (*nghttp2_pack_extension_callback)(nghttp2_session *session,
uint8_t *buf, size_t len,
const nghttp2_frame *frame,
void *user_data);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @functypedef
*
* Callback function invoked when library asks the application to pack
* extension payload in its wire format. The frame header will be
* packed by library. Application must pack payload only.
* ``frame->ext.payload`` is the object passed to
* `nghttp2_submit_extension()` as payload parameter. Application
* must pack extension payload to the |buf| of its capacity |len|
* bytes. The |len| is at least 16KiB.
*
* The implementation of this function should return the number of
* bytes written into |buf| when it succeeds.
*
* To abort processing this extension frame, return
* :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`, and
* :type:`nghttp2_on_frame_not_send_callback` will be invoked.
*
* If fatal error occurred, application should return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
* `nghttp2_session_send()` and `nghttp2_session_mem_send2()`
* functions immediately return
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
* values are returned, currently they are treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the return
* value is strictly larger than |len|, it is treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
typedef nghttp2_ssize (*nghttp2_pack_extension_callback2)(
nghttp2_session *session, uint8_t *buf, size_t len,
const nghttp2_frame *frame, void *user_data);
/**
* @functypedef
*
* .. warning::
*
* Deprecated. Use :type:`nghttp2_error_callback2` instead.
*
* Callback function invoked when library provides the error message
* intended for human consumption. This callback is solely for
* debugging purpose. The |msg| is typically NULL-terminated string
* of length |len|. |len| does not include the sentinel NULL
* character.
*
* The format of error message may change between nghttp2 library
* versions. The application should not depend on the particular
* format.
*
* Normally, application should return 0 from this callback. If fatal
* error occurred while doing something in this callback, application
* should return :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
* In this case, library will return immediately with return value
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Currently, if
* nonzero value is returned from this callback, they are treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, but application
* should not rely on this details.
*/
typedef int (*nghttp2_error_callback)(nghttp2_session *session, const char *msg,
size_t len, void *user_data);
/**
* @functypedef
*
* Callback function invoked when library provides the error code, and
* message. This callback is solely for debugging purpose.
* |lib_error_code| is one of error code defined in
* :enum:`nghttp2_error`. The |msg| is typically NULL-terminated
* string of length |len|, and intended for human consumption. |len|
* does not include the sentinel NULL character.
*
* The format of error message may change between nghttp2 library
* versions. The application should not depend on the particular
* format.
*
* Normally, application should return 0 from this callback. If fatal
* error occurred while doing something in this callback, application
* should return :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
* In this case, library will return immediately with return value
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Currently, if
* nonzero value is returned from this callback, they are treated as
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, but application
* should not rely on this details.
*/
typedef int (*nghttp2_error_callback2)(nghttp2_session *session,
int lib_error_code, const char *msg,
size_t len, void *user_data);
struct nghttp2_session_callbacks;
/**
* @struct
*
* Callback functions for :type:`nghttp2_session`. The details of
* this structure are intentionally hidden from the public API.
*/
typedef struct nghttp2_session_callbacks nghttp2_session_callbacks;
/**
* @function
*
* Initializes |*callbacks_ptr| with NULL values.
*
* The initialized object can be used when initializing multiple
* :type:`nghttp2_session` objects.
*
* When the application finished using this object, it can use
* `nghttp2_session_callbacks_del()` to free its memory.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int
nghttp2_session_callbacks_new(nghttp2_session_callbacks **callbacks_ptr);
/**
* @function
*
* Frees any resources allocated for |callbacks|. If |callbacks| is
* ``NULL``, this function does nothing.
*/
NGHTTP2_EXTERN void
nghttp2_session_callbacks_del(nghttp2_session_callbacks *callbacks);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_session_callbacks_set_send_callback2()`
* with :type:`nghttp2_send_callback2` instead.
*
* Sets callback function invoked when a session wants to send data to
* the remote peer. This callback is not necessary if the application
* uses solely `nghttp2_session_mem_send()` to serialize data to
* transmit.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_callback(
nghttp2_session_callbacks *cbs, nghttp2_send_callback send_callback);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Sets callback function invoked when a session wants to send data to
* the remote peer. This callback is not necessary if the application
* uses solely `nghttp2_session_mem_send2()` to serialize data to
* transmit.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_callback2(
nghttp2_session_callbacks *cbs, nghttp2_send_callback2 send_callback);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_session_callbacks_set_recv_callback2()`
* with :type:`nghttp2_recv_callback2` instead.
*
* Sets callback function invoked when the a session wants to receive
* data from the remote peer. This callback is not necessary if the
* application uses solely `nghttp2_session_mem_recv()` to process
* received data.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_recv_callback(
nghttp2_session_callbacks *cbs, nghttp2_recv_callback recv_callback);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Sets callback function invoked when the a session wants to receive
* data from the remote peer. This callback is not necessary if the
* application uses solely `nghttp2_session_mem_recv2()` to process
* received data.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_recv_callback2(
nghttp2_session_callbacks *cbs, nghttp2_recv_callback2 recv_callback);
/**
* @function
*
* Sets callback function invoked by `nghttp2_session_recv()` and
* `nghttp2_session_mem_recv2()` when a frame is received.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_recv_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_frame_recv_callback on_frame_recv_callback);
/**
* @function
*
* Sets callback function invoked by `nghttp2_session_recv()` and
* `nghttp2_session_mem_recv2()` when an invalid non-DATA frame is
* received.
*/
NGHTTP2_EXTERN void
nghttp2_session_callbacks_set_on_invalid_frame_recv_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_invalid_frame_recv_callback on_invalid_frame_recv_callback);
/**
* @function
*
* Sets callback function invoked when a chunk of data in DATA frame
* is received.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_data_chunk_recv_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_data_chunk_recv_callback on_data_chunk_recv_callback);
/**
* @function
*
* Sets callback function invoked before a non-DATA frame is sent.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_before_frame_send_callback(
nghttp2_session_callbacks *cbs,
nghttp2_before_frame_send_callback before_frame_send_callback);
/**
* @function
*
* Sets callback function invoked after a frame is sent.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_send_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_frame_send_callback on_frame_send_callback);
/**
* @function
*
* Sets callback function invoked when a non-DATA frame is not sent
* because of an error.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_not_send_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_frame_not_send_callback on_frame_not_send_callback);
/**
* @function
*
* Sets callback function invoked when the stream is closed.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_stream_close_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_stream_close_callback on_stream_close_callback);
/**
* @function
*
* Sets callback function invoked when the reception of header block
* in HEADERS or PUSH_PROMISE is started.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_begin_headers_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_begin_headers_callback on_begin_headers_callback);
/**
* @function
*
* Sets callback function invoked when a header name/value pair is
* received. If both
* `nghttp2_session_callbacks_set_on_header_callback()` and
* `nghttp2_session_callbacks_set_on_header_callback2()` are used to
* set callbacks, the latter has the precedence.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_header_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_header_callback on_header_callback);
/**
* @function
*
* Sets callback function invoked when a header name/value pair is
* received.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_header_callback2(
nghttp2_session_callbacks *cbs,
nghttp2_on_header_callback2 on_header_callback2);
/**
* @function
*
* Sets callback function invoked when a invalid header name/value
* pair is received. If both
* `nghttp2_session_callbacks_set_on_invalid_header_callback()` and
* `nghttp2_session_callbacks_set_on_invalid_header_callback2()` are
* used to set callbacks, the latter takes the precedence.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_invalid_header_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_invalid_header_callback on_invalid_header_callback);
/**
* @function
*
* Sets callback function invoked when a invalid header name/value
* pair is received.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_invalid_header_callback2(
nghttp2_session_callbacks *cbs,
nghttp2_on_invalid_header_callback2 on_invalid_header_callback2);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use
* `nghttp2_session_callbacks_set_select_padding_callback2()` with
* :type:`nghttp2_select_padding_callback2` instead.
*
* Sets callback function invoked when the library asks application
* how many padding bytes are required for the transmission of the
* given frame.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_select_padding_callback(
nghttp2_session_callbacks *cbs,
nghttp2_select_padding_callback select_padding_callback);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Sets callback function invoked when the library asks application
* how many padding bytes are required for the transmission of the
* given frame.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_select_padding_callback2(
nghttp2_session_callbacks *cbs,
nghttp2_select_padding_callback2 select_padding_callback);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use
* `nghttp2_session_callbacks_set_data_source_read_length_callback2()`
* with :type:`nghttp2_data_source_read_length_callback2` instead.
*
* Sets callback function determine the length allowed in
* :type:`nghttp2_data_source_read_callback`.
*/
NGHTTP2_EXTERN void
nghttp2_session_callbacks_set_data_source_read_length_callback(
nghttp2_session_callbacks *cbs,
nghttp2_data_source_read_length_callback data_source_read_length_callback);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Sets callback function determine the length allowed in
* :type:`nghttp2_data_source_read_callback2`.
*/
NGHTTP2_EXTERN void
nghttp2_session_callbacks_set_data_source_read_length_callback2(
nghttp2_session_callbacks *cbs,
nghttp2_data_source_read_length_callback2 data_source_read_length_callback);
/**
* @function
*
* Sets callback function invoked when a frame header is received.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_begin_frame_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_begin_frame_callback on_begin_frame_callback);
/**
* @function
*
* Sets callback function invoked when
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` is used in
* :type:`nghttp2_data_source_read_callback2` to avoid data copy.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_data_callback(
nghttp2_session_callbacks *cbs,
nghttp2_send_data_callback send_data_callback);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use
* `nghttp2_session_callbacks_set_pack_extension_callback2()` with
* :type:`nghttp2_pack_extension_callback2` instead.
*
* Sets callback function invoked when the library asks the
* application to pack extension frame payload in wire format.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_pack_extension_callback(
nghttp2_session_callbacks *cbs,
nghttp2_pack_extension_callback pack_extension_callback);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Sets callback function invoked when the library asks the
* application to pack extension frame payload in wire format.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_pack_extension_callback2(
nghttp2_session_callbacks *cbs,
nghttp2_pack_extension_callback2 pack_extension_callback);
/**
* @function
*
* Sets callback function invoked when the library asks the
* application to unpack extension frame payload from wire format.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_unpack_extension_callback(
nghttp2_session_callbacks *cbs,
nghttp2_unpack_extension_callback unpack_extension_callback);
/**
* @function
*
* Sets callback function invoked when chunk of extension frame
* payload is received.
*/
NGHTTP2_EXTERN void
nghttp2_session_callbacks_set_on_extension_chunk_recv_callback(
nghttp2_session_callbacks *cbs,
nghttp2_on_extension_chunk_recv_callback on_extension_chunk_recv_callback);
/**
* @function
*
* .. warning::
*
* Deprecated. Use
* `nghttp2_session_callbacks_set_error_callback2()` with
* :type:`nghttp2_error_callback2` instead.
*
* Sets callback function invoked when library tells error message to
* the application.
*
* If both :type:`nghttp2_error_callback` and
* :type:`nghttp2_error_callback2` are set, the latter takes
* precedence.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_error_callback(
nghttp2_session_callbacks *cbs, nghttp2_error_callback error_callback);
/**
* @function
*
* Sets callback function invoked when library tells error code, and
* message to the application.
*
* If both :type:`nghttp2_error_callback` and
* :type:`nghttp2_error_callback2` are set, the latter takes
* precedence.
*/
NGHTTP2_EXTERN void nghttp2_session_callbacks_set_error_callback2(
nghttp2_session_callbacks *cbs, nghttp2_error_callback2 error_callback2);
/**
* @functypedef
*
* Custom memory allocator to replace malloc(). The |mem_user_data|
* is the mem_user_data member of :type:`nghttp2_mem` structure.
*/
typedef void *(*nghttp2_malloc)(size_t size, void *mem_user_data);
/**
* @functypedef
*
* Custom memory allocator to replace free(). The |mem_user_data| is
* the mem_user_data member of :type:`nghttp2_mem` structure.
*/
typedef void (*nghttp2_free)(void *ptr, void *mem_user_data);
/**
* @functypedef
*
* Custom memory allocator to replace calloc(). The |mem_user_data|
* is the mem_user_data member of :type:`nghttp2_mem` structure.
*/
typedef void *(*nghttp2_calloc)(size_t nmemb, size_t size, void *mem_user_data);
/**
* @functypedef
*
* Custom memory allocator to replace realloc(). The |mem_user_data|
* is the mem_user_data member of :type:`nghttp2_mem` structure.
*/
typedef void *(*nghttp2_realloc)(void *ptr, size_t size, void *mem_user_data);
/**
* @struct
*
* Custom memory allocator functions and user defined pointer. The
* |mem_user_data| member is passed to each allocator function. This
* can be used, for example, to achieve per-session memory pool.
*
* In the following example code, ``my_malloc``, ``my_free``,
* ``my_calloc`` and ``my_realloc`` are the replacement of the
* standard allocators ``malloc``, ``free``, ``calloc`` and
* ``realloc`` respectively::
*
* void *my_malloc_cb(size_t size, void *mem_user_data) {
* return my_malloc(size);
* }
*
* void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); }
*
* void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) {
* return my_calloc(nmemb, size);
* }
*
* void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) {
* return my_realloc(ptr, size);
* }
*
* void session_new() {
* nghttp2_session *session;
* nghttp2_session_callbacks *callbacks;
* nghttp2_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb,
* my_realloc_cb};
*
* ...
*
* nghttp2_session_client_new3(&session, callbacks, NULL, NULL, &mem);
*
* ...
* }
*/
typedef struct {
/**
* An arbitrary user supplied data. This is passed to each
* allocator function.
*/
void *mem_user_data;
/**
* Custom allocator function to replace malloc().
*/
nghttp2_malloc malloc;
/**
* Custom allocator function to replace free().
*/
nghttp2_free free;
/**
* Custom allocator function to replace calloc().
*/
nghttp2_calloc calloc;
/**
* Custom allocator function to replace realloc().
*/
nghttp2_realloc realloc;
} nghttp2_mem;
struct nghttp2_option;
/**
* @struct
*
* Configuration options for :type:`nghttp2_session`. The details of
* this structure are intentionally hidden from the public API.
*/
typedef struct nghttp2_option nghttp2_option;
/**
* @function
*
* Initializes |*option_ptr| with default values.
*
* When the application finished using this object, it can use
* `nghttp2_option_del()` to free its memory.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_option_new(nghttp2_option **option_ptr);
/**
* @function
*
* Frees any resources allocated for |option|. If |option| is
* ``NULL``, this function does nothing.
*/
NGHTTP2_EXTERN void nghttp2_option_del(nghttp2_option *option);
/**
* @function
*
* This option prevents the library from sending WINDOW_UPDATE for a
* connection automatically. If this option is set to nonzero, the
* library won't send WINDOW_UPDATE for DATA until application calls
* `nghttp2_session_consume()` to indicate the consumed amount of
* data. Don't use `nghttp2_submit_window_update()` for this purpose.
* By default, this option is set to zero.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_no_auto_window_update(nghttp2_option *option, int val);
/**
* @function
*
* This option sets the SETTINGS_MAX_CONCURRENT_STREAMS value of
* remote endpoint as if it is received in SETTINGS frame. Without
* specifying this option, the maximum number of outgoing concurrent
* streams is initially limited to 100 to avoid issues when the local
* endpoint submits lots of requests before receiving initial SETTINGS
* frame from the remote endpoint, since sending them at once to the
* remote endpoint could lead to rejection of some of the requests.
* This value will be overwritten when the local endpoint receives
* initial SETTINGS frame from the remote endpoint, either to the
* value advertised in SETTINGS_MAX_CONCURRENT_STREAMS or to the
* default value (unlimited) if none was advertised.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
uint32_t val);
/**
* @function
*
* By default, nghttp2 library, if configured as server, requires
* first 24 bytes of client magic byte string (MAGIC). In most cases,
* this will simplify the implementation of server. But sometimes
* server may want to detect the application protocol based on first
* few bytes on clear text communication.
*
* If this option is used with nonzero |val|, nghttp2 library does not
* handle MAGIC. It still checks following SETTINGS frame. This
* means that applications should deal with MAGIC by themselves.
*
* If this option is not used or used with zero value, if MAGIC does
* not match :macro:`NGHTTP2_CLIENT_MAGIC`, `nghttp2_session_recv()`
* and `nghttp2_session_mem_recv2()` will return error
* :enum:`nghttp2_error.NGHTTP2_ERR_BAD_CLIENT_MAGIC`, which is fatal
* error.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_no_recv_client_magic(nghttp2_option *option, int val);
/**
* @function
*
* By default, nghttp2 library enforces subset of HTTP Messaging rules
* described in `HTTP/2 specification, section 8
* <https://tools.ietf.org/html/rfc7540#section-8>`_. See
* :ref:`http-messaging` section for details. For those applications
* who use nghttp2 library as non-HTTP use, give nonzero to |val| to
* disable this enforcement. Please note that disabling this feature
* does not change the fundamental client and server model of HTTP.
* That is, even if the validation is disabled, only client can send
* requests.
*/
NGHTTP2_EXTERN void nghttp2_option_set_no_http_messaging(nghttp2_option *option,
int val);
/**
* @function
*
* RFC 7540 does not enforce any limit on the number of incoming
* reserved streams (in RFC 7540 terms, streams in reserved (remote)
* state). This only affects client side, since only server can push
* streams. Malicious server can push arbitrary number of streams,
* and make client's memory exhausted. This option can set the
* maximum number of such incoming streams to avoid possible memory
* exhaustion. If this option is set, and pushed streams are
* automatically closed on reception, without calling user provided
* callback, if they exceed the given limit. The default value is
* 200. If session is configured as server side, this option has no
* effect. Server can control the number of streams to push.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_max_reserved_remote_streams(nghttp2_option *option,
uint32_t val);
/**
* @function
*
* Sets extension frame type the application is willing to handle with
* user defined callbacks (see
* :type:`nghttp2_on_extension_chunk_recv_callback` and
* :type:`nghttp2_unpack_extension_callback`). The |type| is
* extension frame type, and must be strictly greater than 0x9.
* Otherwise, this function does nothing. The application can call
* this function multiple times to set more than one frame type to
* receive. The application does not have to call this function if it
* just sends extension frames.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_user_recv_extension_type(nghttp2_option *option,
uint8_t type);
/**
* @function
*
* Sets extension frame type the application is willing to receive
* using builtin handler. The |type| is the extension frame type to
* receive, and must be strictly greater than 0x9. Otherwise, this
* function does nothing. The application can call this function
* multiple times to set more than one frame type to receive. The
* application does not have to call this function if it just sends
* extension frames.
*
* If same frame type is passed to both
* `nghttp2_option_set_builtin_recv_extension_type()` and
* `nghttp2_option_set_user_recv_extension_type()`, the latter takes
* precedence.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_builtin_recv_extension_type(nghttp2_option *option,
uint8_t type);
/**
* @function
*
* This option prevents the library from sending PING frame with ACK
* flag set automatically when PING frame without ACK flag set is
* received. If this option is set to nonzero, the library won't send
* PING frame with ACK flag set in the response for incoming PING
* frame. The application can send PING frame with ACK flag set using
* `nghttp2_submit_ping()` with :enum:`nghttp2_flag.NGHTTP2_FLAG_ACK`
* as flags parameter.
*/
NGHTTP2_EXTERN void nghttp2_option_set_no_auto_ping_ack(nghttp2_option *option,
int val);
/**
* @function
*
* This option sets the maximum length of header block (a set of
* header fields per one HEADERS frame) to send. The length of a
* given set of header fields is calculated using
* `nghttp2_hd_deflate_bound()`. The default value is 64KiB. If
* application attempts to send header fields larger than this limit,
* the transmission of the frame fails with error code
* :enum:`nghttp2_error.NGHTTP2_ERR_FRAME_SIZE_ERROR`.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_max_send_header_block_length(nghttp2_option *option,
size_t val);
/**
* @function
*
* This option sets the maximum dynamic table size for deflating
* header fields. The default value is 4KiB. In HTTP/2, receiver of
* deflated header block can specify maximum dynamic table size. The
* actual maximum size is the minimum of the size receiver specified
* and this option value.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_max_deflate_dynamic_table_size(nghttp2_option *option,
size_t val);
/**
* @function
*
* .. warning::
*
* Deprecated. Closed streams are not retained anymore.
*
* This function works as before, but it does not take any effect
* against :type:`nghttp2_session`.
*/
NGHTTP2_EXTERN void nghttp2_option_set_no_closed_streams(nghttp2_option *option,
int val);
/**
* @function
*
* This function sets the maximum number of outgoing SETTINGS ACK and
* PING ACK frames retained in :type:`nghttp2_session` object. If
* more than those frames are retained, the peer is considered to be
* misbehaving and session will be closed. The default value is 1000.
*/
NGHTTP2_EXTERN void nghttp2_option_set_max_outbound_ack(nghttp2_option *option,
size_t val);
/**
* @function
*
* This function sets the maximum number of SETTINGS entries per
* SETTINGS frame that will be accepted. If more than those entries
* are received, the peer is considered to be misbehaving and session
* will be closed. The default value is 32.
*/
NGHTTP2_EXTERN void nghttp2_option_set_max_settings(nghttp2_option *option,
size_t val);
/**
* @function
*
* .. warning::
* Deprecated. :rfc:`7540` priorities have been removed.
*
* This function works as before, but it does not take any effect
* against :type:`nghttp2_session`.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_server_fallback_rfc7540_priorities(nghttp2_option *option,
int val);
/**
* @function
*
* This option, if set to nonzero, turns off RFC 9113 leading and
* trailing white spaces validation against HTTP field value. Some
* important fields, such as HTTP/2 pseudo header fields, are
* validated more strictly and this option does not apply to them.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_no_rfc9113_leading_and_trailing_ws_validation(
nghttp2_option *option, int val);
/**
* @function
*
* This function sets the rate limit for the incoming stream reset
* (RST_STREAM frame). It is server use only. It is a token-bucket
* based rate limiter. |burst| specifies the number of tokens that is
* initially available. The maximum number of tokens is capped to
* this value. |rate| specifies the number of tokens that are
* regenerated per second. An incoming RST_STREAM consumes one token.
* If there is no token available, GOAWAY is sent to tear down the
* connection. |burst| and |rate| default to 1000 and 33
* respectively.
*/
NGHTTP2_EXTERN void
nghttp2_option_set_stream_reset_rate_limit(nghttp2_option *option,
uint64_t burst, uint64_t rate);
/**
* @function
*
* This function sets the maximum number of CONTINUATION frames
* following an incoming HEADER frame. If more than those frames are
* received, the remote endpoint is considered to be misbehaving and
* session will be closed. The default value is 8.
*/
NGHTTP2_EXTERN void nghttp2_option_set_max_continuations(nghttp2_option *option,
size_t val);
/**
* @function
*
* Initializes |*session_ptr| for client use. The all members of
* |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
* does not store |callbacks|. The |user_data| is an arbitrary user
* supplied data, which will be passed to the callback functions.
*
* The :type:`nghttp2_send_callback2` must be specified. If the
* application code uses `nghttp2_session_recv()`, the
* :type:`nghttp2_recv_callback` must be specified. The other members
* of |callbacks| can be ``NULL``.
*
* If this function fails, |*session_ptr| is left untouched.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int
nghttp2_session_client_new(nghttp2_session **session_ptr,
const nghttp2_session_callbacks *callbacks,
void *user_data);
/**
* @function
*
* Initializes |*session_ptr| for server use. The all members of
* |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
* does not store |callbacks|. The |user_data| is an arbitrary user
* supplied data, which will be passed to the callback functions.
*
* The :type:`nghttp2_send_callback2` must be specified. If the
* application code uses `nghttp2_session_recv()`, the
* :type:`nghttp2_recv_callback` must be specified. The other members
* of |callbacks| can be ``NULL``.
*
* If this function fails, |*session_ptr| is left untouched.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int
nghttp2_session_server_new(nghttp2_session **session_ptr,
const nghttp2_session_callbacks *callbacks,
void *user_data);
/**
* @function
*
* Like `nghttp2_session_client_new()`, but with additional options
* specified in the |option|.
*
* The |option| can be ``NULL`` and the call is equivalent to
* `nghttp2_session_client_new()`.
*
* This function does not take ownership |option|. The application is
* responsible for freeing |option| if it finishes using the object.
*
* The library code does not refer to |option| after this function
* returns.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int
nghttp2_session_client_new2(nghttp2_session **session_ptr,
const nghttp2_session_callbacks *callbacks,
void *user_data, const nghttp2_option *option);
/**
* @function
*
* Like `nghttp2_session_server_new()`, but with additional options
* specified in the |option|.
*
* The |option| can be ``NULL`` and the call is equivalent to
* `nghttp2_session_server_new()`.
*
* This function does not take ownership |option|. The application is
* responsible for freeing |option| if it finishes using the object.
*
* The library code does not refer to |option| after this function
* returns.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int
nghttp2_session_server_new2(nghttp2_session **session_ptr,
const nghttp2_session_callbacks *callbacks,
void *user_data, const nghttp2_option *option);
/**
* @function
*
* Like `nghttp2_session_client_new2()`, but with additional custom
* memory allocator specified in the |mem|.
*
* The |mem| can be ``NULL`` and the call is equivalent to
* `nghttp2_session_client_new2()`.
*
* This function does not take ownership |mem|. The application is
* responsible for freeing |mem|.
*
* The library code does not refer to |mem| pointer after this
* function returns, so the application can safely free it.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_session_client_new3(
nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks,
void *user_data, const nghttp2_option *option, nghttp2_mem *mem);
/**
* @function
*
* Like `nghttp2_session_server_new2()`, but with additional custom
* memory allocator specified in the |mem|.
*
* The |mem| can be ``NULL`` and the call is equivalent to
* `nghttp2_session_server_new2()`.
*
* This function does not take ownership |mem|. The application is
* responsible for freeing |mem|.
*
* The library code does not refer to |mem| pointer after this
* function returns, so the application can safely free it.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_session_server_new3(
nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks,
void *user_data, const nghttp2_option *option, nghttp2_mem *mem);
/**
* @function
*
* Frees any resources allocated for |session|. If |session| is
* ``NULL``, this function does nothing.
*/
NGHTTP2_EXTERN void nghttp2_session_del(nghttp2_session *session);
/**
* @function
*
* Sends pending frames to the remote peer.
*
* This function retrieves the highest prioritized frame from the
* outbound queue and sends it to the remote peer. It does this as
* many times as possible until the user callback
* :type:`nghttp2_send_callback2` returns
* :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`, the outbound queue
* becomes empty or flow control is triggered (remote window size
* becomes depleted or maximum number of concurrent streams is
* reached). This function calls several callback functions which are
* passed when initializing the |session|. Here is the simple time
* chart which tells when each callback is invoked:
*
* 1. Get the next frame to send from outbound queue.
*
* 2. Prepare transmission of the frame.
*
* 3. If the control frame cannot be sent because some preconditions
* are not met (e.g., request HEADERS cannot be sent after GOAWAY),
* :type:`nghttp2_on_frame_not_send_callback` is invoked. Abort
* the following steps.
*
* 4. If the frame is HEADERS, PUSH_PROMISE or DATA,
* :type:`nghttp2_select_padding_callback` is invoked.
*
* 5. If the frame is request HEADERS, the stream is opened here.
*
* 6. :type:`nghttp2_before_frame_send_callback` is invoked.
*
* 7. If :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL` is returned from
* :type:`nghttp2_before_frame_send_callback`, the current frame
* transmission is canceled, and
* :type:`nghttp2_on_frame_not_send_callback` is invoked. Abort
* the following steps.
*
* 8. :type:`nghttp2_send_callback2` is invoked one or more times to
* send the frame.
*
* 9. :type:`nghttp2_on_frame_send_callback` is invoked.
*
* 10. If the transmission of the frame triggers closure of the
* stream, the stream is closed and
* :type:`nghttp2_on_stream_close_callback` is invoked.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`
* The callback function failed.
*/
NGHTTP2_EXTERN int nghttp2_session_send(nghttp2_session *session);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_session_mem_send2()` instead.
*
* Returns the serialized data to send.
*
* This function behaves like `nghttp2_session_send()` except that it
* does not use :type:`nghttp2_send_callback` to transmit data.
* Instead, it assigns the pointer to the serialized data to the
* |*data_ptr| and returns its length. The other callbacks are called
* in the same way as they are in `nghttp2_session_send()`.
*
* If no data is available to send, this function returns 0.
*
* This function may not return all serialized data in one invocation.
* To get all data, call this function repeatedly until it returns 0
* or one of negative error codes.
*
* The assigned |*data_ptr| is valid until the next call of
* `nghttp2_session_mem_send()` or `nghttp2_session_send()`.
*
* The caller must send all data before sending the next chunk of
* data.
*
* This function returns the length of the data pointed by the
* |*data_ptr| if it succeeds, or one of the following negative error
* codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*
* .. note::
*
* This function may produce very small byte string. If that is the
* case, and application disables Nagle algorithm (``TCP_NODELAY``),
* then writing this small chunk leads to very small packet, and it
* is very inefficient. An application should be responsible to
* buffer up small chunks of data as necessary to avoid this
* situation.
*/
NGHTTP2_EXTERN ssize_t nghttp2_session_mem_send(nghttp2_session *session,
const uint8_t **data_ptr);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Returns the serialized data to send.
*
* This function behaves like `nghttp2_session_send()` except that it
* does not use :type:`nghttp2_send_callback2` to transmit data.
* Instead, it assigns the pointer to the serialized data to the
* |*data_ptr| and returns its length. The other callbacks are called
* in the same way as they are in `nghttp2_session_send()`.
*
* If no data is available to send, this function returns 0.
*
* This function may not return all serialized data in one invocation.
* To get all data, call this function repeatedly until it returns 0
* or one of negative error codes.
*
* The assigned |*data_ptr| is valid until the next call of
* `nghttp2_session_mem_send2()` or `nghttp2_session_send()`.
*
* The caller must send all data before sending the next chunk of
* data.
*
* This function returns the length of the data pointed by the
* |*data_ptr| if it succeeds, or one of the following negative error
* codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*
* .. note::
*
* This function may produce very small byte string. If that is the
* case, and application disables Nagle algorithm (``TCP_NODELAY``),
* then writing this small chunk leads to very small packet, and it
* is very inefficient. An application should be responsible to
* buffer up small chunks of data as necessary to avoid this
* situation.
*/
NGHTTP2_EXTERN nghttp2_ssize
nghttp2_session_mem_send2(nghttp2_session *session, const uint8_t **data_ptr);
/**
* @function
*
* Receives frames from the remote peer.
*
* This function receives as many frames as possible until the user
* callback :type:`nghttp2_recv_callback` returns
* :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. This function calls
* several callback functions which are passed when initializing the
* |session|. Here is the simple time chart which tells when each
* callback is invoked:
*
* 1. :type:`nghttp2_recv_callback` is invoked one or more times to
* receive frame header.
*
* 2. When frame header is received,
* :type:`nghttp2_on_begin_frame_callback` is invoked.
*
* 3. If the frame is DATA frame:
*
* 1. :type:`nghttp2_recv_callback` is invoked to receive DATA
* payload. For each chunk of data,
* :type:`nghttp2_on_data_chunk_recv_callback` is invoked.
*
* 2. If one DATA frame is completely received,
* :type:`nghttp2_on_frame_recv_callback` is invoked. If the
* reception of the frame triggers the closure of the stream,
* :type:`nghttp2_on_stream_close_callback` is invoked.
*
* 4. If the frame is the control frame:
*
* 1. :type:`nghttp2_recv_callback` is invoked one or more times to
* receive whole frame.
*
* 2. If the received frame is valid, then following actions are
* taken. If the frame is either HEADERS or PUSH_PROMISE,
* :type:`nghttp2_on_begin_headers_callback` is invoked. Then
* :type:`nghttp2_on_header_callback` is invoked for each header
* name/value pair. For invalid header field,
* :type:`nghttp2_on_invalid_header_callback` is called. After
* all name/value pairs are emitted successfully,
* :type:`nghttp2_on_frame_recv_callback` is invoked. For other
* frames, :type:`nghttp2_on_frame_recv_callback` is invoked.
* If the reception of the frame triggers the closure of the
* stream, :type:`nghttp2_on_stream_close_callback` is invoked.
*
* 3. If the received frame is unpacked but is interpreted as
* invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is
* invoked.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_EOF`
* The remote peer did shutdown on the connection.
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`
* The callback function failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_BAD_CLIENT_MAGIC`
* Invalid client magic was detected. This error only returns
* when |session| was configured as server and
* `nghttp2_option_set_no_recv_client_magic()` is not used with
* nonzero value.
* :enum:`nghttp2_error.NGHTTP2_ERR_FLOODED`
* Flooding was detected in this HTTP/2 session, and it must be
* closed. This is most likely caused by misbehaviour of peer.
*/
NGHTTP2_EXTERN int nghttp2_session_recv(nghttp2_session *session);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_session_mem_recv2()` instead.
*
* Processes data |in| as an input from the remote endpoint. The
* |inlen| indicates the number of bytes to receive in the |in|.
*
* This function behaves like `nghttp2_session_recv()` except that it
* does not use :type:`nghttp2_recv_callback` to receive data; the
* |in| is the only data for the invocation of this function. If all
* bytes are processed, this function returns. The other callbacks
* are called in the same way as they are in `nghttp2_session_recv()`.
*
* In the current implementation, this function always tries to
* processes |inlen| bytes of input data unless either an error occurs or
* :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` is returned from
* :type:`nghttp2_on_header_callback` or
* :type:`nghttp2_on_data_chunk_recv_callback`. If
* :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` is used, the return value
* includes the number of bytes which was used to produce the data or
* frame for the callback.
*
* This function returns the number of processed bytes, or one of the
* following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`
* The callback function failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_BAD_CLIENT_MAGIC`
* Invalid client magic was detected. This error only returns
* when |session| was configured as server and
* `nghttp2_option_set_no_recv_client_magic()` is not used with
* nonzero value.
* :enum:`nghttp2_error.NGHTTP2_ERR_FLOODED`
* Flooding was detected in this HTTP/2 session, and it must be
* closed. This is most likely caused by misbehaviour of peer.
*/
NGHTTP2_EXTERN ssize_t nghttp2_session_mem_recv(nghttp2_session *session,
const uint8_t *in,
size_t inlen);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Processes data |in| as an input from the remote endpoint. The
* |inlen| indicates the number of bytes to receive in the |in|.
*
* This function behaves like `nghttp2_session_recv()` except that it
* does not use :type:`nghttp2_recv_callback` to receive data; the
* |in| is the only data for the invocation of this function. If all
* bytes are processed, this function returns. The other callbacks
* are called in the same way as they are in `nghttp2_session_recv()`.
*
* In the current implementation, this function always tries to
* processes |inlen| bytes of input data unless either an error occurs or
* :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` is returned from
* :type:`nghttp2_on_header_callback` or
* :type:`nghttp2_on_data_chunk_recv_callback`. If
* :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` is used, the return value
* includes the number of bytes which was used to produce the data or
* frame for the callback.
*
* This function returns the number of processed bytes, or one of the
* following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`
* The callback function failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_BAD_CLIENT_MAGIC`
* Invalid client magic was detected. This error only returns
* when |session| was configured as server and
* `nghttp2_option_set_no_recv_client_magic()` is not used with
* nonzero value.
* :enum:`nghttp2_error.NGHTTP2_ERR_FLOODED`
* Flooding was detected in this HTTP/2 session, and it must be
* closed. This is most likely caused by misbehaviour of peer.
*/
NGHTTP2_EXTERN nghttp2_ssize nghttp2_session_mem_recv2(nghttp2_session *session,
const uint8_t *in,
size_t inlen);
/**
* @function
*
* Puts back previously deferred DATA frame in the stream |stream_id|
* to the outbound queue.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The stream does not exist; or no deferred data exist.
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_session_resume_data(nghttp2_session *session,
int32_t stream_id);
/**
* @function
*
* Returns nonzero value if |session| wants to receive data from the
* remote peer.
*
* If both `nghttp2_session_want_read()` and
* `nghttp2_session_want_write()` return 0, the application should
* drop the connection.
*/
NGHTTP2_EXTERN int nghttp2_session_want_read(nghttp2_session *session);
/**
* @function
*
* Returns nonzero value if |session| wants to send data to the remote
* peer.
*
* If both `nghttp2_session_want_read()` and
* `nghttp2_session_want_write()` return 0, the application should
* drop the connection.
*/
NGHTTP2_EXTERN int nghttp2_session_want_write(nghttp2_session *session);
/**
* @function
*
* Returns stream_user_data for the stream |stream_id|. The
* stream_user_data is provided by `nghttp2_submit_request2()`,
* `nghttp2_submit_headers()` or
* `nghttp2_session_set_stream_user_data()`. Unless it is set using
* `nghttp2_session_set_stream_user_data()`, if the stream is
* initiated by the remote endpoint, stream_user_data is always
* ``NULL``. If the stream does not exist, this function returns
* ``NULL``.
*/
NGHTTP2_EXTERN void *
nghttp2_session_get_stream_user_data(nghttp2_session *session,
int32_t stream_id);
/**
* @function
*
* Sets the |stream_user_data| to the stream denoted by the
* |stream_id|. If a stream user data is already set to the stream,
* it is replaced with the |stream_user_data|. It is valid to specify
* ``NULL`` in the |stream_user_data|, which nullifies the associated
* data pointer.
*
* It is valid to set the |stream_user_data| to the stream reserved by
* PUSH_PROMISE frame.
*
* This function returns 0 if it succeeds, or one of following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The stream does not exist
*/
NGHTTP2_EXTERN int
nghttp2_session_set_stream_user_data(nghttp2_session *session,
int32_t stream_id, void *stream_user_data);
/**
* @function
*
* Sets |user_data| to |session|, overwriting the existing user data
* specified in `nghttp2_session_client_new()`, or
* `nghttp2_session_server_new()`.
*/
NGHTTP2_EXTERN void nghttp2_session_set_user_data(nghttp2_session *session,
void *user_data);
/**
* @function
*
* Returns the number of frames in the outbound queue. This does not
* include the deferred DATA frames.
*/
NGHTTP2_EXTERN size_t
nghttp2_session_get_outbound_queue_size(nghttp2_session *session);
/**
* @function
*
* Returns the number of DATA payload in bytes received without
* WINDOW_UPDATE transmission for the stream |stream_id|. The local
* (receive) window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* that and returns effective data length. In particular, if the
* local window size is reduced by submitting negative
* window_size_increment with `nghttp2_submit_window_update()`, this
* function returns the number of bytes less than actually received.
*
* This function returns -1 if it fails.
*/
NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_effective_recv_data_length(
nghttp2_session *session, int32_t stream_id);
/**
* @function
*
* Returns the local (receive) window size for the stream |stream_id|.
* The local window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* that and returns effective window size.
*
* This function does not take into account the amount of received
* data from the remote endpoint. Use
* `nghttp2_session_get_stream_local_window_size()` to know the amount
* of data the remote endpoint can send without receiving stream level
* WINDOW_UPDATE frame. Note that each stream is still subject to the
* connection level flow control.
*
* This function returns -1 if it fails.
*/
NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_effective_local_window_size(
nghttp2_session *session, int32_t stream_id);
/**
* @function
*
* Returns the amount of flow-controlled payload (e.g., DATA) that the
* remote endpoint can send without receiving stream level
* WINDOW_UPDATE frame. It is also subject to the connection level
* flow control. So the actual amount of data to send is
* min(`nghttp2_session_get_stream_local_window_size()`,
* `nghttp2_session_get_local_window_size()`).
*
* This function returns -1 if it fails.
*/
NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_local_window_size(
nghttp2_session *session, int32_t stream_id);
/**
* @function
*
* Returns the number of DATA payload in bytes received without
* WINDOW_UPDATE transmission for a connection. The local (receive)
* window size can be adjusted by `nghttp2_submit_window_update()`.
* This function takes into account that and returns effective data
* length. In particular, if the local window size is reduced by
* submitting negative window_size_increment with
* `nghttp2_submit_window_update()`, this function returns the number
* of bytes less than actually received.
*
* This function returns -1 if it fails.
*/
NGHTTP2_EXTERN int32_t
nghttp2_session_get_effective_recv_data_length(nghttp2_session *session);
/**
* @function
*
* Returns the local (receive) window size for a connection. The
* local window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* that and returns effective window size.
*
* This function does not take into account the amount of received
* data from the remote endpoint. Use
* `nghttp2_session_get_local_window_size()` to know the amount of
* data the remote endpoint can send without receiving
* connection-level WINDOW_UPDATE frame. Note that each stream is
* still subject to the stream level flow control.
*
* This function returns -1 if it fails.
*/
NGHTTP2_EXTERN int32_t
nghttp2_session_get_effective_local_window_size(nghttp2_session *session);
/**
* @function
*
* Returns the amount of flow-controlled payload (e.g., DATA) that the
* remote endpoint can send without receiving connection level
* WINDOW_UPDATE frame. Note that each stream is still subject to the
* stream level flow control (see
* `nghttp2_session_get_stream_local_window_size()`).
*
* This function returns -1 if it fails.
*/
NGHTTP2_EXTERN int32_t
nghttp2_session_get_local_window_size(nghttp2_session *session);
/**
* @function
*
* Returns the remote window size for a given stream |stream_id|.
*
* This is the amount of flow-controlled payload (e.g., DATA) that the
* local endpoint can send without stream level WINDOW_UPDATE. There
* is also connection level flow control, so the effective size of
* payload that the local endpoint can actually send is
* min(`nghttp2_session_get_stream_remote_window_size()`,
* `nghttp2_session_get_remote_window_size()`).
*
* This function returns -1 if it fails.
*/
NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_remote_window_size(
nghttp2_session *session, int32_t stream_id);
/**
* @function
*
* Returns the remote window size for a connection.
*
* This function always succeeds.
*/
NGHTTP2_EXTERN int32_t
nghttp2_session_get_remote_window_size(nghttp2_session *session);
/**
* @function
*
* Returns 1 if local peer half closed the given stream |stream_id|.
* Returns 0 if it did not. Returns -1 if no such stream exists.
*/
NGHTTP2_EXTERN int
nghttp2_session_get_stream_local_close(nghttp2_session *session,
int32_t stream_id);
/**
* @function
*
* Returns 1 if remote peer half closed the given stream |stream_id|.
* Returns 0 if it did not. Returns -1 if no such stream exists.
*/
NGHTTP2_EXTERN int
nghttp2_session_get_stream_remote_close(nghttp2_session *session,
int32_t stream_id);
/**
* @function
*
* Returns the current dynamic table size of HPACK inflater, including
* the overhead 32 bytes per entry described in RFC 7541.
*/
NGHTTP2_EXTERN size_t
nghttp2_session_get_hd_inflate_dynamic_table_size(nghttp2_session *session);
/**
* @function
*
* Returns the current dynamic table size of HPACK deflater including
* the overhead 32 bytes per entry described in RFC 7541.
*/
NGHTTP2_EXTERN size_t
nghttp2_session_get_hd_deflate_dynamic_table_size(nghttp2_session *session);
/**
* @function
*
* Signals the session so that the connection should be terminated.
*
* The last stream ID is the minimum value between the stream ID of a
* stream for which :type:`nghttp2_on_frame_recv_callback` was called
* most recently and the last stream ID we have sent to the peer
* previously.
*
* The |error_code| is the error code of this GOAWAY frame. The
* pre-defined error code is one of :enum:`nghttp2_error_code`.
*
* After the transmission, both `nghttp2_session_want_read()` and
* `nghttp2_session_want_write()` return 0.
*
* This function should be called when the connection should be
* terminated after sending GOAWAY. If the remaining streams should
* be processed after GOAWAY, use `nghttp2_submit_goaway()` instead.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_session_terminate_session(nghttp2_session *session,
uint32_t error_code);
/**
* @function
*
* Signals the session so that the connection should be terminated.
*
* This function behaves like `nghttp2_session_terminate_session()`,
* but the last stream ID can be specified by the application for fine
* grained control of stream. The HTTP/2 specification does not allow
* last_stream_id to be increased. So the actual value sent as
* last_stream_id is the minimum value between the given
* |last_stream_id| and the last_stream_id we have previously sent to
* the peer.
*
* The |last_stream_id| is peer's stream ID or 0. So if |session| is
* initialized as client, |last_stream_id| must be even or 0. If
* |session| is initialized as server, |last_stream_id| must be odd or
* 0.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |last_stream_id| is invalid.
*/
NGHTTP2_EXTERN int nghttp2_session_terminate_session2(nghttp2_session *session,
int32_t last_stream_id,
uint32_t error_code);
/**
* @function
*
* Signals to the client that the server started graceful shutdown
* procedure.
*
* This function is only usable for server. If this function is
* called with client side session, this function returns
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`.
*
* To gracefully shutdown HTTP/2 session, server should call this
* function to send GOAWAY with last_stream_id (1u << 31) - 1. And
* after some delay (e.g., 1 RTT), send another GOAWAY with the stream
* ID that the server has some processing using
* `nghttp2_submit_goaway()`. See also
* `nghttp2_session_get_last_proc_stream_id()`.
*
* Unlike `nghttp2_submit_goaway()`, this function just sends GOAWAY
* and does nothing more. This is a mere indication to the client
* that session shutdown is imminent. The application should call
* `nghttp2_submit_goaway()` with appropriate last_stream_id after
* this call.
*
* If one or more GOAWAY frame have been already sent by either
* `nghttp2_submit_goaway()` or `nghttp2_session_terminate_session()`,
* this function has no effect.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* The |session| is initialized as client.
*/
NGHTTP2_EXTERN int nghttp2_submit_shutdown_notice(nghttp2_session *session);
/**
* @function
*
* Returns the value of SETTINGS |id| notified by a remote endpoint.
* The |id| must be one of values defined in
* :enum:`nghttp2_settings_id`.
*/
NGHTTP2_EXTERN uint32_t nghttp2_session_get_remote_settings(
nghttp2_session *session, nghttp2_settings_id id);
/**
* @function
*
* Returns the value of SETTINGS |id| of local endpoint acknowledged
* by the remote endpoint. The |id| must be one of the values defined
* in :enum:`nghttp2_settings_id`.
*/
NGHTTP2_EXTERN uint32_t nghttp2_session_get_local_settings(
nghttp2_session *session, nghttp2_settings_id id);
/**
* @function
*
* Tells the |session| that next stream ID is |next_stream_id|. The
* |next_stream_id| must be equal or greater than the value returned
* by `nghttp2_session_get_next_stream_id()`.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |next_stream_id| is strictly less than the value
* `nghttp2_session_get_next_stream_id()` returns; or
* |next_stream_id| is invalid (e.g., even integer for client, or
* odd integer for server).
*/
NGHTTP2_EXTERN int nghttp2_session_set_next_stream_id(nghttp2_session *session,
int32_t next_stream_id);
/**
* @function
*
* Returns the next outgoing stream ID. Notice that return type is
* uint32_t. If we run out of stream ID for this session, this
* function returns 1 << 31.
*/
NGHTTP2_EXTERN uint32_t
nghttp2_session_get_next_stream_id(nghttp2_session *session);
/**
* @function
*
* Tells the |session| that |size| bytes for a stream denoted by
* |stream_id| were consumed by application and are ready to
* WINDOW_UPDATE. The consumed bytes are counted towards both
* connection and stream level WINDOW_UPDATE (see
* `nghttp2_session_consume_connection()` and
* `nghttp2_session_consume_stream()` to update consumption
* independently). This function is intended to be used without
* automatic window update (see
* `nghttp2_option_set_no_auto_window_update()`).
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* Automatic WINDOW_UPDATE is not disabled.
*/
NGHTTP2_EXTERN int nghttp2_session_consume(nghttp2_session *session,
int32_t stream_id, size_t size);
/**
* @function
*
* Like `nghttp2_session_consume()`, but this only tells library that
* |size| bytes were consumed only for connection level. Note that
* HTTP/2 maintains connection and stream level flow control windows
* independently.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* Automatic WINDOW_UPDATE is not disabled.
*/
NGHTTP2_EXTERN int nghttp2_session_consume_connection(nghttp2_session *session,
size_t size);
/**
* @function
*
* Like `nghttp2_session_consume()`, but this only tells library that
* |size| bytes were consumed only for stream denoted by |stream_id|.
* Note that HTTP/2 maintains connection and stream level flow control
* windows independently.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* Automatic WINDOW_UPDATE is not disabled.
*/
NGHTTP2_EXTERN int nghttp2_session_consume_stream(nghttp2_session *session,
int32_t stream_id,
size_t size);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function is noop. It always returns 0.
*/
NGHTTP2_EXTERN int
nghttp2_session_change_stream_priority(nghttp2_session *session,
int32_t stream_id,
const nghttp2_priority_spec *pri_spec);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function is noop. It always returns 0.
*/
NGHTTP2_EXTERN int
nghttp2_session_create_idle_stream(nghttp2_session *session, int32_t stream_id,
const nghttp2_priority_spec *pri_spec);
/**
* @function
*
* .. warning::
*
* This function is deprecated in favor of
* `nghttp2_session_upgrade2()`, because this function lacks the
* parameter to tell the library the request method used in the
* original HTTP request. This information is required for client
* to validate actual response body length against content-length
* header field (see `nghttp2_option_set_no_http_messaging()`). If
* HEAD is used in request, the length of response body must be 0
* regardless of value included in content-length header field.
*
* Performs post-process of HTTP Upgrade request. This function can
* be called from both client and server, but the behavior is very
* different in each other.
*
* If called from client side, the |settings_payload| must be the
* value sent in ``HTTP2-Settings`` header field and must be decoded
* by base64url decoder. The |settings_payloadlen| is the length of
* |settings_payload|. The |settings_payload| is unpacked and its
* setting values will be submitted using `nghttp2_submit_settings()`.
* This means that the client application code does not need to submit
* SETTINGS by itself. The stream with stream ID=1 is opened and the
* |stream_user_data| is used for its stream_user_data. The opened
* stream becomes half-closed (local) state.
*
* If called from server side, the |settings_payload| must be the
* value received in ``HTTP2-Settings`` header field and must be
* decoded by base64url decoder. The |settings_payloadlen| is the
* length of |settings_payload|. It is treated as if the SETTINGS
* frame with that payload is received. Thus, callback functions for
* the reception of SETTINGS frame will be invoked. The stream with
* stream ID=1 is opened. The |stream_user_data| is ignored. The
* opened stream becomes half-closed (remote).
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |settings_payload| is badly formed.
* :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
* The stream ID 1 is already used or closed; or is not available.
*/
NGHTTP2_EXTERN int nghttp2_session_upgrade(nghttp2_session *session,
const uint8_t *settings_payload,
size_t settings_payloadlen,
void *stream_user_data);
/**
* @function
*
* Performs post-process of HTTP Upgrade request. This function can
* be called from both client and server, but the behavior is very
* different in each other.
*
* If called from client side, the |settings_payload| must be the
* value sent in ``HTTP2-Settings`` header field and must be decoded
* by base64url decoder. The |settings_payloadlen| is the length of
* |settings_payload|. The |settings_payload| is unpacked and its
* setting values will be submitted using `nghttp2_submit_settings()`.
* This means that the client application code does not need to submit
* SETTINGS by itself. The stream with stream ID=1 is opened and the
* |stream_user_data| is used for its stream_user_data. The opened
* stream becomes half-closed (local) state.
*
* If called from server side, the |settings_payload| must be the
* value received in ``HTTP2-Settings`` header field and must be
* decoded by base64url decoder. The |settings_payloadlen| is the
* length of |settings_payload|. It is treated as if the SETTINGS
* frame with that payload is received. Thus, callback functions for
* the reception of SETTINGS frame will be invoked. The stream with
* stream ID=1 is opened. The |stream_user_data| is ignored. The
* opened stream becomes half-closed (remote).
*
* If the request method is HEAD, pass nonzero value to
* |head_request|. Otherwise, pass 0.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |settings_payload| is badly formed.
* :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
* The stream ID 1 is already used or closed; or is not available.
*/
NGHTTP2_EXTERN int nghttp2_session_upgrade2(nghttp2_session *session,
const uint8_t *settings_payload,
size_t settings_payloadlen,
int head_request,
void *stream_user_data);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_pack_settings_payload2()` instead.
*
* Serializes the SETTINGS values |iv| in the |buf|. The size of the
* |buf| is specified by |buflen|. The number of entries in the |iv|
* array is given by |niv|. The required space in |buf| for the |niv|
* entries is ``6*niv`` bytes and if the given buffer is too small, an
* error is returned. This function is used mainly for creating a
* SETTINGS payload to be sent with the ``HTTP2-Settings`` header
* field in an HTTP Upgrade request. The data written in |buf| is NOT
* base64url encoded and the application is responsible for encoding.
*
* This function returns the number of bytes written in |buf|, or one
* of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |iv| contains duplicate settings ID or invalid value.
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
* The provided |buflen| size is too small to hold the output.
*/
NGHTTP2_EXTERN ssize_t nghttp2_pack_settings_payload(
uint8_t *buf, size_t buflen, const nghttp2_settings_entry *iv, size_t niv);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Serializes the SETTINGS values |iv| in the |buf|. The size of the
* |buf| is specified by |buflen|. The number of entries in the |iv|
* array is given by |niv|. The required space in |buf| for the |niv|
* entries is ``6*niv`` bytes and if the given buffer is too small, an
* error is returned. This function is used mainly for creating a
* SETTINGS payload to be sent with the ``HTTP2-Settings`` header
* field in an HTTP Upgrade request. The data written in |buf| is NOT
* base64url encoded and the application is responsible for encoding.
*
* This function returns the number of bytes written in |buf|, or one
* of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |iv| contains duplicate settings ID or invalid value.
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
* The provided |buflen| size is too small to hold the output.
*/
NGHTTP2_EXTERN nghttp2_ssize nghttp2_pack_settings_payload2(
uint8_t *buf, size_t buflen, const nghttp2_settings_entry *iv, size_t niv);
/**
* @function
*
* Returns string describing the |lib_error_code|. The
* |lib_error_code| must be one of the :enum:`nghttp2_error`.
*/
NGHTTP2_EXTERN const char *nghttp2_strerror(int lib_error_code);
/**
* @function
*
* Returns string representation of HTTP/2 error code |error_code|
* (e.g., ``PROTOCOL_ERROR`` is returned if ``error_code ==
* NGHTTP2_PROTOCOL_ERROR``). If string representation is unknown for
* given |error_code|, this function returns string ``unknown``.
*/
NGHTTP2_EXTERN const char *nghttp2_http2_strerror(uint32_t error_code);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* Initializes |pri_spec| with the |stream_id| of the stream to depend
* on with |weight| and its exclusive flag. If |exclusive| is
* nonzero, exclusive flag is set.
*
* The |weight| must be in [:macro:`NGHTTP2_MIN_WEIGHT`,
* :macro:`NGHTTP2_MAX_WEIGHT`], inclusive.
*/
NGHTTP2_EXTERN void nghttp2_priority_spec_init(nghttp2_priority_spec *pri_spec,
int32_t stream_id,
int32_t weight, int exclusive);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* Initializes |pri_spec| with the default values. The default values
* are: stream_id = 0, weight = :macro:`NGHTTP2_DEFAULT_WEIGHT` and
* exclusive = 0.
*/
NGHTTP2_EXTERN void
nghttp2_priority_spec_default_init(nghttp2_priority_spec *pri_spec);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* Returns nonzero if the |pri_spec| is filled with default values.
*/
NGHTTP2_EXTERN int
nghttp2_priority_spec_check_default(const nghttp2_priority_spec *pri_spec);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_submit_request2()` instead.
*
* Submits HEADERS frame and optionally one or more DATA frames.
*
* The |pri_spec| is ignored.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The application is responsible to include
* required pseudo-header fields (header field whose name starts with
* ":") in |nva| and must place pseudo-headers before regular header
* fields.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|. The order of elements in
* |nva| is preserved. For header fields with
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
* header field name and value are not copied respectively. With
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
* is responsible to pass header field name in lowercase. The
* application should maintain the references to them until
* :type:`nghttp2_on_frame_send_callback` or
* :type:`nghttp2_on_frame_not_send_callback` is called.
*
* HTTP/2 specification has requirement about header fields in the
* request HEADERS. See the specification for more details.
*
* If |data_prd| is not ``NULL``, it provides data which will be sent
* in subsequent DATA frames. In this case, a method that allows
* request message bodies
* (https://tools.ietf.org/html/rfc7231#section-4) must be specified
* with ``:method`` key in |nva| (e.g. ``POST``). This function does
* not take ownership of the |data_prd|. The function copies the
* members of the |data_prd|. If |data_prd| is ``NULL``, HEADERS have
* END_STREAM set. The |stream_user_data| is data associated to the
* stream opened by this request and can be an arbitrary pointer,
* which can be retrieved later by
* `nghttp2_session_get_stream_user_data()`.
*
* This function returns assigned stream ID if it succeeds, or one of
* the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
* No stream ID is available because maximum stream ID was
* reached.
* :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
* The |session| is server session.
*
* .. warning::
*
* This function returns assigned stream ID if it succeeds. But
* that stream is not created yet. The application must not submit
* frame to that stream ID before
* :type:`nghttp2_before_frame_send_callback` is called for this
* frame. This means `nghttp2_session_get_stream_user_data()` does
* not work before the callback. But
* `nghttp2_session_set_stream_user_data()` handles this situation
* specially, and it can set data to a stream during this period.
*
*/
NGHTTP2_EXTERN int32_t nghttp2_submit_request(
nghttp2_session *session, const nghttp2_priority_spec *pri_spec,
const nghttp2_nv *nva, size_t nvlen, const nghttp2_data_provider *data_prd,
void *stream_user_data);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Submits HEADERS frame and optionally one or more DATA frames.
*
* The |pri_spec| is ignored.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The application is responsible to include
* required pseudo-header fields (header field whose name starts with
* ":") in |nva| and must place pseudo-headers before regular header
* fields.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|. The order of elements in
* |nva| is preserved. For header fields with
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
* header field name and value are not copied respectively. With
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
* is responsible to pass header field name in lowercase. The
* application should maintain the references to them until
* :type:`nghttp2_on_frame_send_callback` or
* :type:`nghttp2_on_frame_not_send_callback` is called.
*
* HTTP/2 specification has requirement about header fields in the
* request HEADERS. See the specification for more details.
*
* If |data_prd| is not ``NULL``, it provides data which will be sent
* in subsequent DATA frames. In this case, a method that allows
* request message bodies
* (https://tools.ietf.org/html/rfc7231#section-4) must be specified
* with ``:method`` key in |nva| (e.g. ``POST``). This function does
* not take ownership of the |data_prd|. The function copies the
* members of the |data_prd|. If |data_prd| is ``NULL``, HEADERS have
* END_STREAM set. The |stream_user_data| is data associated to the
* stream opened by this request and can be an arbitrary pointer,
* which can be retrieved later by
* `nghttp2_session_get_stream_user_data()`.
*
* This function returns assigned stream ID if it succeeds, or one of
* the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
* No stream ID is available because maximum stream ID was
* reached.
* :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
* The |session| is server session.
*
* .. warning::
*
* This function returns assigned stream ID if it succeeds. But
* that stream is not created yet. The application must not submit
* frame to that stream ID before
* :type:`nghttp2_before_frame_send_callback` is called for this
* frame. This means `nghttp2_session_get_stream_user_data()` does
* not work before the callback. But
* `nghttp2_session_set_stream_user_data()` handles this situation
* specially, and it can set data to a stream during this period.
*
*/
NGHTTP2_EXTERN int32_t nghttp2_submit_request2(
nghttp2_session *session, const nghttp2_priority_spec *pri_spec,
const nghttp2_nv *nva, size_t nvlen, const nghttp2_data_provider2 *data_prd,
void *stream_user_data);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_submit_response2()` instead.
*
* Submits response HEADERS frame and optionally one or more DATA
* frames against the stream |stream_id|.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The application is responsible to include
* required pseudo-header fields (header field whose name starts with
* ":") in |nva| and must place pseudo-headers before regular header
* fields.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|. The order of elements in
* |nva| is preserved. For header fields with
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
* header field name and value are not copied respectively. With
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
* is responsible to pass header field name in lowercase. The
* application should maintain the references to them until
* :type:`nghttp2_on_frame_send_callback` or
* :type:`nghttp2_on_frame_not_send_callback` is called.
*
* HTTP/2 specification has requirement about header fields in the
* response HEADERS. See the specification for more details.
*
* If |data_prd| is not ``NULL``, it provides data which will be sent
* in subsequent DATA frames. This function does not take ownership
* of the |data_prd|. The function copies the members of the
* |data_prd|. If |data_prd| is ``NULL``, HEADERS will have
* END_STREAM flag set.
*
* This method can be used as normal HTTP response and push response.
* When pushing a resource using this function, the |session| must be
* configured using `nghttp2_session_server_new()` or its variants and
* the target stream denoted by the |stream_id| must be reserved using
* `nghttp2_submit_push_promise()`.
*
* To send non-final response headers (e.g., HTTP status 101), don't
* use this function because this function half-closes the outbound
* stream. Instead, use `nghttp2_submit_headers()` for this purpose.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
* :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
* DATA or HEADERS has been already submitted and not fully
* processed yet. Normally, this does not happen, but when
* application wrongly calls `nghttp2_submit_response()` twice,
* this may happen.
* :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
* The |session| is client session.
*
* .. warning::
*
* Calling this function twice for the same stream ID may lead to
* program crash. It is generally considered to a programming error
* to commit response twice.
*/
NGHTTP2_EXTERN int
nghttp2_submit_response(nghttp2_session *session, int32_t stream_id,
const nghttp2_nv *nva, size_t nvlen,
const nghttp2_data_provider *data_prd);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Submits response HEADERS frame and optionally one or more DATA
* frames against the stream |stream_id|.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The application is responsible to include
* required pseudo-header fields (header field whose name starts with
* ":") in |nva| and must place pseudo-headers before regular header
* fields.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|. The order of elements in
* |nva| is preserved. For header fields with
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
* header field name and value are not copied respectively. With
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
* is responsible to pass header field name in lowercase. The
* application should maintain the references to them until
* :type:`nghttp2_on_frame_send_callback` or
* :type:`nghttp2_on_frame_not_send_callback` is called.
*
* HTTP/2 specification has requirement about header fields in the
* response HEADERS. See the specification for more details.
*
* If |data_prd| is not ``NULL``, it provides data which will be sent
* in subsequent DATA frames. This function does not take ownership
* of the |data_prd|. The function copies the members of the
* |data_prd|. If |data_prd| is ``NULL``, HEADERS will have
* END_STREAM flag set.
*
* This method can be used as normal HTTP response and push response.
* When pushing a resource using this function, the |session| must be
* configured using `nghttp2_session_server_new()` or its variants and
* the target stream denoted by the |stream_id| must be reserved using
* `nghttp2_submit_push_promise()`.
*
* To send non-final response headers (e.g., HTTP status 101), don't
* use this function because this function half-closes the outbound
* stream. Instead, use `nghttp2_submit_headers()` for this purpose.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
* :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
* DATA or HEADERS has been already submitted and not fully
* processed yet. Normally, this does not happen, but when
* application wrongly calls `nghttp2_submit_response2()` twice,
* this may happen.
* :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
* The |session| is client session.
*
* .. warning::
*
* Calling this function twice for the same stream ID may lead to
* program crash. It is generally considered to a programming error
* to commit response twice.
*/
NGHTTP2_EXTERN int
nghttp2_submit_response2(nghttp2_session *session, int32_t stream_id,
const nghttp2_nv *nva, size_t nvlen,
const nghttp2_data_provider2 *data_prd);
/**
* @function
*
* Submits trailer fields HEADERS against the stream |stream_id|.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The application must not include pseudo-header
* fields (headers whose names starts with ":") in |nva|.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|. The order of elements in
* |nva| is preserved. For header fields with
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
* header field name and value are not copied respectively. With
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
* is responsible to pass header field name in lowercase. The
* application should maintain the references to them until
* :type:`nghttp2_on_frame_send_callback` or
* :type:`nghttp2_on_frame_not_send_callback` is called.
*
* For server, trailer fields must follow response HEADERS or response
* DATA without END_STREAM flat set. The library does not enforce
* this requirement, and applications should do this for themselves.
* If `nghttp2_submit_trailer()` is called before any response HEADERS
* submission (usually by `nghttp2_submit_response2()`), the content
* of |nva| will be sent as response headers, which will result in
* error.
*
* This function has the same effect with `nghttp2_submit_headers()`,
* with flags = :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` and both
* pri_spec and stream_user_data to NULL.
*
* To submit trailer fields after `nghttp2_submit_response2()` is
* called, the application has to specify
* :type:`nghttp2_data_provider2` to `nghttp2_submit_response2()`.
* Inside of :type:`nghttp2_data_source_read_callback2`, when setting
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF`, also set
* :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_END_STREAM`. After
* that, the application can send trailer fields using
* `nghttp2_submit_trailer()`. `nghttp2_submit_trailer()` can be used
* inside :type:`nghttp2_data_source_read_callback2`.
*
* This function returns 0 if it succeeds and |stream_id| is -1.
* Otherwise, this function returns 0 if it succeeds, or one of the
* following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
*/
NGHTTP2_EXTERN int nghttp2_submit_trailer(nghttp2_session *session,
int32_t stream_id,
const nghttp2_nv *nva, size_t nvlen);
/**
* @function
*
* Submits HEADERS frame. The |flags| is bitwise OR of the
* following values:
*
* * :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`
*
* If |flags| includes :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`,
* this frame has END_STREAM flag set.
*
* The library handles the CONTINUATION frame internally and it
* correctly sets END_HEADERS to the last sequence of the PUSH_PROMISE
* or CONTINUATION frame.
*
* If the |stream_id| is -1, this frame is assumed as request (i.e.,
* request HEADERS frame which opens new stream). In this case, the
* assigned stream ID will be returned. Otherwise, specify stream ID
* in |stream_id|.
*
* The |pri_spec| is ignored.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The application is responsible to include
* required pseudo-header fields (header field whose name starts with
* ":") in |nva| and must place pseudo-headers before regular header
* fields.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|. The order of elements in
* |nva| is preserved. For header fields with
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
* header field name and value are not copied respectively. With
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
* is responsible to pass header field name in lowercase. The
* application should maintain the references to them until
* :type:`nghttp2_on_frame_send_callback` or
* :type:`nghttp2_on_frame_not_send_callback` is called.
*
* The |stream_user_data| is a pointer to an arbitrary data which is
* associated to the stream this frame will open. Therefore it is
* only used if this frame opens streams, in other words, it changes
* stream state from idle or reserved to open.
*
* This function is low-level in a sense that the application code can
* specify flags directly. For usual HTTP request,
* `nghttp2_submit_request2()` is useful. Likewise, for HTTP
* response, prefer `nghttp2_submit_response2()`.
*
* This function returns newly assigned stream ID if it succeeds and
* |stream_id| is -1. Otherwise, this function returns 0 if it
* succeeds, or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
* No stream ID is available because maximum stream ID was
* reached.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
* :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
* DATA or HEADERS has been already submitted and not fully
* processed yet. This happens if stream denoted by |stream_id|
* is in reserved state.
* :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
* The |stream_id| is -1, and |session| is server session.
*
* .. warning::
*
* This function returns assigned stream ID if it succeeds and
* |stream_id| is -1. But that stream is not opened yet. The
* application must not submit frame to that stream ID before
* :type:`nghttp2_before_frame_send_callback` is called for this
* frame.
*
*/
NGHTTP2_EXTERN int32_t nghttp2_submit_headers(
nghttp2_session *session, uint8_t flags, int32_t stream_id,
const nghttp2_priority_spec *pri_spec, const nghttp2_nv *nva, size_t nvlen,
void *stream_user_data);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_submit_data2()` instead.
*
* Submits one or more DATA frames to the stream |stream_id|. The
* data to be sent are provided by |data_prd|. If |flags| contains
* :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`, the last DATA frame
* has END_STREAM flag set.
*
* This function does not take ownership of the |data_prd|. The
* function copies the members of the |data_prd|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
* DATA or HEADERS has been already submitted and not fully
* processed yet.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
* :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_CLOSED`
* The stream was already closed; or the |stream_id| is invalid.
*
* .. note::
*
* Currently, only one DATA or HEADERS is allowed for a stream at a
* time. Submitting these frames more than once before first DATA
* or HEADERS is finished results in
* :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST` error code. The
* earliest callback which tells that previous frame is done is
* :type:`nghttp2_on_frame_send_callback`. In side that callback,
* new data can be submitted using `nghttp2_submit_data()`. Of
* course, all data except for last one must not have
* :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` flag set in |flags|.
* This sounds a bit complicated, and we recommend to use
* `nghttp2_submit_request()` and `nghttp2_submit_response()` to
* avoid this cascading issue. The experience shows that for HTTP
* use, these two functions are enough to implement both client and
* server.
*/
NGHTTP2_EXTERN int nghttp2_submit_data(nghttp2_session *session, uint8_t flags,
int32_t stream_id,
const nghttp2_data_provider *data_prd);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Submits one or more DATA frames to the stream |stream_id|. The
* data to be sent are provided by |data_prd|. If |flags| contains
* :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`, the last DATA frame
* has END_STREAM flag set.
*
* This function does not take ownership of the |data_prd|. The
* function copies the members of the |data_prd|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
* DATA or HEADERS has been already submitted and not fully
* processed yet.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
* :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_CLOSED`
* The stream was already closed; or the |stream_id| is invalid.
*
* .. note::
*
* Currently, only one DATA or HEADERS is allowed for a stream at a
* time. Submitting these frames more than once before first DATA
* or HEADERS is finished results in
* :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST` error code. The
* earliest callback which tells that previous frame is done is
* :type:`nghttp2_on_frame_send_callback`. In side that callback,
* new data can be submitted using `nghttp2_submit_data2()`. Of
* course, all data except for last one must not have
* :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` flag set in |flags|.
* This sounds a bit complicated, and we recommend to use
* `nghttp2_submit_request2()` and `nghttp2_submit_response2()` to
* avoid this cascading issue. The experience shows that for HTTP
* use, these two functions are enough to implement both client and
* server.
*/
NGHTTP2_EXTERN int nghttp2_submit_data2(nghttp2_session *session, uint8_t flags,
int32_t stream_id,
const nghttp2_data_provider2 *data_prd);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function is noop. It always returns 0.
*/
NGHTTP2_EXTERN int
nghttp2_submit_priority(nghttp2_session *session, uint8_t flags,
int32_t stream_id,
const nghttp2_priority_spec *pri_spec);
/**
* @macro
*
* :macro:`NGHTTP2_EXTPRI_DEFAULT_URGENCY` is the default urgency
* level for :rfc:`9218` extensible priorities.
*/
#define NGHTTP2_EXTPRI_DEFAULT_URGENCY 3
/**
* @macro
*
* :macro:`NGHTTP2_EXTPRI_URGENCY_HIGH` is the highest urgency level
* for :rfc:`9218` extensible priorities.
*/
#define NGHTTP2_EXTPRI_URGENCY_HIGH 0
/**
* @macro
*
* :macro:`NGHTTP2_EXTPRI_URGENCY_LOW` is the lowest urgency level for
* :rfc:`9218` extensible priorities.
*/
#define NGHTTP2_EXTPRI_URGENCY_LOW 7
/**
* @macro
*
* :macro:`NGHTTP2_EXTPRI_URGENCY_LEVELS` is the number of urgency
* levels for :rfc:`9218` extensible priorities.
*/
#define NGHTTP2_EXTPRI_URGENCY_LEVELS (NGHTTP2_EXTPRI_URGENCY_LOW + 1)
/**
* @struct
*
* :type:`nghttp2_extpri` is :rfc:`9218` extensible priorities
* specification for a stream.
*/
typedef struct nghttp2_extpri {
/**
* :member:`urgency` is the urgency of a stream, it must be in
* [:macro:`NGHTTP2_EXTPRI_URGENCY_HIGH`,
* :macro:`NGHTTP2_EXTPRI_URGENCY_LOW`], inclusive, and 0 is the
* highest urgency.
*/
uint32_t urgency;
/**
* :member:`inc` indicates that a content can be processed
* incrementally or not. If inc is 0, it cannot be processed
* incrementally. If inc is 1, it can be processed incrementally.
* Other value is not permitted.
*/
int inc;
} nghttp2_extpri;
/**
* @function
*
* Submits RST_STREAM frame to cancel/reject the stream |stream_id|
* with the error code |error_code|.
*
* The pre-defined error code is one of :enum:`nghttp2_error_code`.
*
* The |flags| is currently ignored and should be
* :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0.
*/
NGHTTP2_EXTERN int nghttp2_submit_rst_stream(nghttp2_session *session,
uint8_t flags, int32_t stream_id,
uint32_t error_code);
/**
* @function
*
* Stores local settings and submits SETTINGS frame. The |iv| is the
* pointer to the array of :type:`nghttp2_settings_entry`. The |niv|
* indicates the number of :type:`nghttp2_settings_entry`.
*
* The |flags| is currently ignored and should be
* :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* This function does not take ownership of the |iv|. This function
* copies all the elements in the |iv|.
*
* While updating individual stream's local window size, if the window
* size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE,
* RST_STREAM is issued against such a stream.
*
* SETTINGS with :enum:`nghttp2_flag.NGHTTP2_FLAG_ACK` is
* automatically submitted by the library and application could not
* send it at its will.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |iv| contains invalid value (e.g., initial window size
* strictly greater than (1 << 31) - 1.
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_submit_settings(nghttp2_session *session,
uint8_t flags,
const nghttp2_settings_entry *iv,
size_t niv);
/**
* @function
*
* Submits PUSH_PROMISE frame.
*
* The |flags| is currently ignored. The library handles the
* CONTINUATION frame internally and it correctly sets END_HEADERS to
* the last sequence of the PUSH_PROMISE or CONTINUATION frame.
*
* The |stream_id| must be client initiated stream ID.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The application is responsible to include
* required pseudo-header fields (header field whose name starts with
* ":") in |nva| and must place pseudo-headers before regular header
* fields.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|. The order of elements in
* |nva| is preserved. For header fields with
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
* header field name and value are not copied respectively. With
* :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
* is responsible to pass header field name in lowercase. The
* application should maintain the references to them until
* :type:`nghttp2_on_frame_send_callback` or
* :type:`nghttp2_on_frame_not_send_callback` is called.
*
* The |promised_stream_user_data| is a pointer to an arbitrary data
* which is associated to the promised stream this frame will open and
* make it in reserved state. It is available using
* `nghttp2_session_get_stream_user_data()`. The application can
* access it in :type:`nghttp2_before_frame_send_callback` and
* :type:`nghttp2_on_frame_send_callback` of this frame.
*
* The client side is not allowed to use this function.
*
* To submit response headers and data, use
* `nghttp2_submit_response2()`.
*
* This function returns assigned promised stream ID if it succeeds,
* or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
* This function was invoked when |session| is initialized as
* client.
* :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
* No stream ID is available because maximum stream ID was
* reached.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is 0; The |stream_id| does not designate stream
* that peer initiated.
* :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_CLOSED`
* The stream was already closed; or the |stream_id| is invalid.
*
* .. warning::
*
* This function returns assigned promised stream ID if it succeeds.
* As of 1.16.0, stream object for pushed resource is created when
* this function succeeds. In that case, the application can submit
* push response for the promised frame.
*
* In 1.15.0 or prior versions, pushed stream is not opened yet when
* this function succeeds. The application must not submit frame to
* that stream ID before :type:`nghttp2_before_frame_send_callback`
* is called for this frame.
*
*/
NGHTTP2_EXTERN int32_t nghttp2_submit_push_promise(
nghttp2_session *session, uint8_t flags, int32_t stream_id,
const nghttp2_nv *nva, size_t nvlen, void *promised_stream_user_data);
/**
* @function
*
* Submits PING frame. You don't have to send PING back when you
* received PING frame. The library automatically submits PING frame
* in this case.
*
* The |flags| is bitwise OR of 0 or more of the following value.
*
* * :enum:`nghttp2_flag.NGHTTP2_FLAG_ACK`
*
* Unless `nghttp2_option_set_no_auto_ping_ack()` is used, the |flags|
* should be :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* If the |opaque_data| is non ``NULL``, then it should point to the 8
* bytes array of memory to specify opaque data to send with PING
* frame. If the |opaque_data| is ``NULL``, zero-cleared 8 bytes will
* be sent as opaque data.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_submit_ping(nghttp2_session *session, uint8_t flags,
const uint8_t *opaque_data);
/**
* @function
*
* Submits GOAWAY frame with the last stream ID |last_stream_id| and
* the error code |error_code|.
*
* The pre-defined error code is one of :enum:`nghttp2_error_code`.
*
* The |flags| is currently ignored and should be
* :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* The |last_stream_id| is peer's stream ID or 0. So if |session| is
* initialized as client, |last_stream_id| must be even or 0. If
* |session| is initialized as server, |last_stream_id| must be odd or
* 0.
*
* The HTTP/2 specification says last_stream_id must not be increased
* from the value previously sent. So the actual value sent as
* last_stream_id is the minimum value between the given
* |last_stream_id| and the last_stream_id previously sent to the
* peer.
*
* If the |opaque_data| is not ``NULL`` and |opaque_data_len| is not
* zero, those data will be sent as additional debug data. The
* library makes a copy of the memory region pointed by |opaque_data|
* with the length |opaque_data_len|, so the caller does not need to
* keep this memory after the return of this function. If the
* |opaque_data_len| is 0, the |opaque_data| could be ``NULL``.
*
* After successful transmission of GOAWAY, following things happen.
* All incoming streams having strictly more than |last_stream_id| are
* closed. All incoming HEADERS which starts new stream are simply
* ignored. After all active streams are handled, both
* `nghttp2_session_want_read()` and `nghttp2_session_want_write()`
* return 0 and the application can close session.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |opaque_data_len| is too large; the |last_stream_id| is
* invalid.
*/
NGHTTP2_EXTERN int nghttp2_submit_goaway(nghttp2_session *session,
uint8_t flags, int32_t last_stream_id,
uint32_t error_code,
const uint8_t *opaque_data,
size_t opaque_data_len);
/**
* @function
*
* Returns the last stream ID of a stream for which
* :type:`nghttp2_on_frame_recv_callback` was invoked most recently.
* The returned value can be used as last_stream_id parameter for
* `nghttp2_submit_goaway()` and
* `nghttp2_session_terminate_session2()`.
*
* This function always succeeds.
*/
NGHTTP2_EXTERN int32_t
nghttp2_session_get_last_proc_stream_id(nghttp2_session *session);
/**
* @function
*
* Returns nonzero if new request can be sent from local endpoint.
*
* This function return 0 if request is not allowed for this session.
* There are several reasons why request is not allowed. Some of the
* reasons are: session is server; stream ID has been spent; GOAWAY
* has been sent or received.
*
* The application can call `nghttp2_submit_request2()` without
* consulting this function. In that case,
* `nghttp2_submit_request2()` may return error. Or, request is
* failed to sent, and :type:`nghttp2_on_stream_close_callback` is
* called.
*/
NGHTTP2_EXTERN int
nghttp2_session_check_request_allowed(nghttp2_session *session);
/**
* @function
*
* Returns nonzero if |session| is initialized as server side session.
*/
NGHTTP2_EXTERN int
nghttp2_session_check_server_session(nghttp2_session *session);
/**
* @function
*
* Submits WINDOW_UPDATE frame.
*
* The |flags| is currently ignored and should be
* :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* The |stream_id| is the stream ID to send this WINDOW_UPDATE. To
* send connection level WINDOW_UPDATE, specify 0 to |stream_id|.
*
* If the |window_size_increment| is positive, the WINDOW_UPDATE with
* that value as window_size_increment is queued. If the
* |window_size_increment| is larger than the received bytes from the
* remote endpoint, the local window size is increased by that
* difference. If the sole purpose is to increase the local window
* size, consider to use `nghttp2_session_set_local_window_size()`.
*
* If the |window_size_increment| is negative, the local window size
* is decreased by -|window_size_increment|. If automatic
* WINDOW_UPDATE is enabled
* (`nghttp2_option_set_no_auto_window_update()`), and the library
* decided that the WINDOW_UPDATE should be submitted, then
* WINDOW_UPDATE is queued with the current received bytes count. If
* the sole purpose is to decrease the local window size, consider to
* use `nghttp2_session_set_local_window_size()`.
*
* If the |window_size_increment| is 0, the function does nothing and
* returns 0.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_FLOW_CONTROL`
* The local window size overflow or gets negative.
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_submit_window_update(nghttp2_session *session,
uint8_t flags,
int32_t stream_id,
int32_t window_size_increment);
/**
* @function
*
* Set local window size (local endpoints's window size) to the given
* |window_size| for the given stream denoted by |stream_id|. To
* change connection level window size, specify 0 to |stream_id|. To
* increase window size, this function may submit WINDOW_UPDATE frame
* to transmission queue.
*
* The |flags| is currently ignored and should be
* :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* This sounds similar to `nghttp2_submit_window_update()`, but there
* are 2 differences. The first difference is that this function
* takes the absolute value of window size to set, rather than the
* delta. To change the window size, this may be easier to use since
* the application just declares the intended window size, rather than
* calculating delta. The second difference is that
* `nghttp2_submit_window_update()` affects the received bytes count
* which has not acked yet. By the specification of
* `nghttp2_submit_window_update()`, to strictly increase the local
* window size, we have to submit delta including all received bytes
* count, which might not be desirable in some cases. On the other
* hand, this function does not affect the received bytes count. It
* just sets the local window size to the given value.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |stream_id| is negative.
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int
nghttp2_session_set_local_window_size(nghttp2_session *session, uint8_t flags,
int32_t stream_id, int32_t window_size);
/**
* @function
*
* Submits extension frame.
*
* Application can pass arbitrary frame flags and stream ID in |flags|
* and |stream_id| respectively. The |payload| is opaque pointer, and
* it can be accessible though ``frame->ext.payload`` in
* :type:`nghttp2_pack_extension_callback2`. The library will not own
* passed |payload| pointer.
*
* The application must set :type:`nghttp2_pack_extension_callback2`
* using `nghttp2_session_callbacks_set_pack_extension_callback2()`.
*
* The application should retain the memory pointed by |payload| until
* the transmission of extension frame is done (which is indicated by
* :type:`nghttp2_on_frame_send_callback`), or transmission fails
* (which is indicated by :type:`nghttp2_on_frame_not_send_callback`).
* If application does not touch this memory region after packing it
* into a wire format, application can free it inside
* :type:`nghttp2_pack_extension_callback2`.
*
* The standard HTTP/2 frame cannot be sent with this function, so
* |type| must be strictly grater than 0x9. Otherwise, this function
* will fail with error code
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* If :type:`nghttp2_pack_extension_callback2` is not set.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* If |type| specifies standard HTTP/2 frame type. The frame
* types in the rage [0x0, 0x9], both inclusive, are standard
* HTTP/2 frame type, and cannot be sent using this function.
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory
*/
NGHTTP2_EXTERN int nghttp2_submit_extension(nghttp2_session *session,
uint8_t type, uint8_t flags,
int32_t stream_id, void *payload);
/**
* @struct
*
* The payload of ALTSVC frame. ALTSVC frame is a non-critical
* extension to HTTP/2. If this frame is received, and
* `nghttp2_option_set_user_recv_extension_type()` is not set, and
* `nghttp2_option_set_builtin_recv_extension_type()` is set for
* :enum:`nghttp2_frame_type.NGHTTP2_ALTSVC`,
* ``nghttp2_extension.payload`` will point to this struct.
*
* It has the following members:
*/
typedef struct {
/**
* The pointer to origin which this alternative service is
* associated with. This is not necessarily NULL-terminated.
*/
uint8_t *origin;
/**
* The length of the |origin|.
*/
size_t origin_len;
/**
* The pointer to Alt-Svc field value contained in ALTSVC frame.
* This is not necessarily NULL-terminated.
*/
uint8_t *field_value;
/**
* The length of the |field_value|.
*/
size_t field_value_len;
} nghttp2_ext_altsvc;
/**
* @function
*
* Submits ALTSVC frame.
*
* ALTSVC frame is a non-critical extension to HTTP/2, and defined in
* `RFC 7383 <https://tools.ietf.org/html/rfc7838#section-4>`_.
*
* The |flags| is currently ignored and should be
* :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* The |origin| points to the origin this alternative service is
* associated with. The |origin_len| is the length of the origin. If
* |stream_id| is 0, the origin must be specified. If |stream_id| is
* not zero, the origin must be empty (in other words, |origin_len|
* must be 0).
*
* The ALTSVC frame is only usable from server side. If this function
* is invoked with client side session, this function returns
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* The function is called from client side session
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The sum of |origin_len| and |field_value_len| is larger than
* 16382; or |origin_len| is 0 while |stream_id| is 0; or
* |origin_len| is not 0 while |stream_id| is not 0.
*/
NGHTTP2_EXTERN int nghttp2_submit_altsvc(nghttp2_session *session,
uint8_t flags, int32_t stream_id,
const uint8_t *origin,
size_t origin_len,
const uint8_t *field_value,
size_t field_value_len);
/**
* @struct
*
* The single entry of an origin.
*/
typedef struct {
/**
* The pointer to origin. No validation is made against this field
* by the library. This is not necessarily NULL-terminated.
*/
uint8_t *origin;
/**
* The length of the |origin|.
*/
size_t origin_len;
} nghttp2_origin_entry;
/**
* @struct
*
* The payload of ORIGIN frame. ORIGIN frame is a non-critical
* extension to HTTP/2 and defined by `RFC 8336
* <https://tools.ietf.org/html/rfc8336>`_.
*
* If this frame is received, and
* `nghttp2_option_set_user_recv_extension_type()` is not set, and
* `nghttp2_option_set_builtin_recv_extension_type()` is set for
* :enum:`nghttp2_frame_type.NGHTTP2_ORIGIN`,
* ``nghttp2_extension.payload`` will point to this struct.
*
* It has the following members:
*/
typedef struct {
/**
* The number of origins contained in |ov|.
*/
size_t nov;
/**
* The pointer to the array of origins contained in ORIGIN frame.
*/
nghttp2_origin_entry *ov;
} nghttp2_ext_origin;
/**
* @function
*
* Submits ORIGIN frame.
*
* ORIGIN frame is a non-critical extension to HTTP/2 and defined by
* `RFC 8336 <https://tools.ietf.org/html/rfc8336>`_.
*
* The |flags| is currently ignored and should be
* :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* The |ov| points to the array of origins. The |nov| specifies the
* number of origins included in |ov|. This function creates copies
* of all elements in |ov|.
*
* The ORIGIN frame is only usable by a server. If this function is
* invoked with client side session, this function returns
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`.
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* The function is called from client side session.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* There are too many origins, or an origin is too large to fit
* into a default frame payload.
*/
NGHTTP2_EXTERN int nghttp2_submit_origin(nghttp2_session *session,
uint8_t flags,
const nghttp2_origin_entry *ov,
size_t nov);
/**
* @struct
*
* The payload of PRIORITY_UPDATE frame. PRIORITY_UPDATE frame is a
* non-critical extension to HTTP/2. If this frame is received, and
* `nghttp2_option_set_user_recv_extension_type()` is not set, and
* `nghttp2_option_set_builtin_recv_extension_type()` is set for
* :enum:`nghttp2_frame_type.NGHTTP2_PRIORITY_UPDATE`,
* ``nghttp2_extension.payload`` will point to this struct.
*
* It has the following members:
*/
typedef struct {
/**
* The stream ID of the stream whose priority is updated.
*/
int32_t stream_id;
/**
* The pointer to Priority field value. It is not necessarily
* NULL-terminated.
*/
uint8_t *field_value;
/**
* The length of the :member:`field_value`.
*/
size_t field_value_len;
} nghttp2_ext_priority_update;
/**
* @function
*
* Submits PRIORITY_UPDATE frame.
*
* PRIORITY_UPDATE frame is a non-critical extension to HTTP/2, and
* defined in :rfc:`9218#section-7.1`.
*
* The |flags| is currently ignored and should be
* :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
*
* The |stream_id| is the ID of stream which is prioritized. The
* |field_value| points to the Priority field value. The
* |field_value_len| is the length of the Priority field value.
*
* If this function is called by server,
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` is returned.
*
* If
* :enum:`nghttp2_settings_id.NGHTTP2_SETTINGS_NO_RFC7540_PRIORITIES`
* of value of 0 is received by a remote endpoint (or it is omitted),
* this function does nothing and returns 0.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* The function is called from server side session
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* The |field_value_len| is larger than 16380; or |stream_id| is
* 0.
*/
NGHTTP2_EXTERN int nghttp2_submit_priority_update(nghttp2_session *session,
uint8_t flags,
int32_t stream_id,
const uint8_t *field_value,
size_t field_value_len);
/**
* @function
*
* Changes the priority of the existing stream denoted by |stream_id|.
* The new priority is |extpri|. This function is meant to be used by
* server for :rfc:`9218` extensible prioritization scheme.
*
* If |session| is initialized as client, this function returns
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`. For client, use
* `nghttp2_submit_priority_update()` instead.
*
* If :member:`extpri->urgency <nghttp2_extpri.urgency>` is out of
* bound, it is set to :macro:`NGHTTP2_EXTPRI_URGENCY_LOW`.
*
* If |ignore_client_signal| is nonzero, server starts to ignore
* client priority signals for this stream.
*
* If
* :enum:`nghttp2_settings_id.NGHTTP2_SETTINGS_NO_RFC7540_PRIORITIES`
* of value of 1 is not submitted via `nghttp2_submit_settings()`,
* this function does nothing and returns 0.
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* The |session| is initialized as client.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* |stream_id| is zero; or a stream denoted by |stream_id| is not
* found.
*/
NGHTTP2_EXTERN int nghttp2_session_change_extpri_stream_priority(
nghttp2_session *session, int32_t stream_id, const nghttp2_extpri *extpri,
int ignore_client_signal);
/**
* @function
*
* Stores the stream priority of the existing stream denoted by
* |stream_id| in the object pointed by |extpri|. This function is
* meant to be used by server for :rfc:`9218` extensible
* prioritization scheme.
*
* If |session| is initialized as client, this function returns
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`.
*
* If
* :enum:`nghttp2_settings_id.NGHTTP2_SETTINGS_NO_RFC7540_PRIORITIES`
* of value of 1 is not submitted via `nghttp2_submit_settings()`,
* this function does nothing and returns 0.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* The |session| is initialized as client.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* |stream_id| is zero; or a stream denoted by |stream_id| is not
* found.
*/
NGHTTP2_EXTERN int nghttp2_session_get_extpri_stream_priority(
nghttp2_session *session, nghttp2_extpri *extpri, int32_t stream_id);
/**
* @function
*
* Parses Priority header field value pointed by |value| of length
* |len|, and stores the result in the object pointed by |extpri|.
* Priority header field is defined in :rfc:`9218`.
*
* This function does not initialize the object pointed by |extpri|
* before storing the result. It only assigns the values that the
* parser correctly extracted to fields.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
* Failed to parse the header field value.
*/
NGHTTP2_EXTERN int nghttp2_extpri_parse_priority(nghttp2_extpri *extpri,
const uint8_t *value,
size_t len);
/**
* @function
*
* Compares ``lhs->name`` of length ``lhs->namelen`` bytes and
* ``rhs->name`` of length ``rhs->namelen`` bytes. Returns negative
* integer if ``lhs->name`` is found to be less than ``rhs->name``; or
* returns positive integer if ``lhs->name`` is found to be greater
* than ``rhs->name``; or returns 0 otherwise.
*/
NGHTTP2_EXTERN int nghttp2_nv_compare_name(const nghttp2_nv *lhs,
const nghttp2_nv *rhs);
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_select_alpn` instead.
*
* A helper function for dealing with ALPN in server side. The |in|
* contains peer's protocol list in preferable order. The format of
* |in| is length-prefixed and not null-terminated. For example,
* ``h2`` and ``http/1.1`` stored in |in| like this::
*
* in[0] = 2
* in[1..2] = "h2"
* in[3] = 8
* in[4..11] = "http/1.1"
* inlen = 12
*
* The selection algorithm is as follows:
*
* 1. If peer's list contains HTTP/2 protocol the library supports,
* it is selected and returns 1. The following step is not taken.
*
* 2. If peer's list contains ``http/1.1``, this function selects
* ``http/1.1`` and returns 0. The following step is not taken.
*
* 3. This function selects nothing and returns -1 (So called
* non-overlap case). In this case, |out| and |outlen| are left
* untouched.
*
* Selecting ``h2`` means that ``h2`` is written into |*out| and its
* length (which is 2) is assigned to |*outlen|.
*
* For ALPN, refer to https://tools.ietf.org/html/rfc7301
*
* To use this method you should do something like::
*
* static int alpn_select_proto_cb(SSL* ssl,
* const unsigned char **out,
* unsigned char *outlen,
* const unsigned char *in,
* unsigned int inlen,
* void *arg)
* {
* int rv;
* rv = nghttp2_select_next_protocol((unsigned char**)out, outlen,
* in, inlen);
* if (rv == -1) {
* return SSL_TLSEXT_ERR_NOACK;
* }
* if (rv == 1) {
* ((MyType*)arg)->http2_selected = 1;
* }
* return SSL_TLSEXT_ERR_OK;
* }
* ...
* SSL_CTX_set_alpn_select_cb(ssl_ctx, alpn_select_proto_cb, my_obj);
*
*/
NGHTTP2_EXTERN int nghttp2_select_next_protocol(unsigned char **out,
unsigned char *outlen,
const unsigned char *in,
unsigned int inlen);
/**
* @function
*
* A helper function for dealing with ALPN in server side. The |in|
* contains peer's protocol list in preferable order. The format of
* |in| is length-prefixed and not null-terminated. For example,
* ``h2`` and ``http/1.1`` stored in |in| like this::
*
* in[0] = 2
* in[1..2] = "h2"
* in[3] = 8
* in[4..11] = "http/1.1"
* inlen = 12
*
* The selection algorithm is as follows:
*
* 1. If peer's list contains HTTP/2 protocol the library supports,
* it is selected and returns 1. The following step is not taken.
*
* 2. If peer's list contains ``http/1.1``, this function selects
* ``http/1.1`` and returns 0. The following step is not taken.
*
* 3. This function selects nothing and returns -1 (So called
* non-overlap case). In this case, |out| and |outlen| are left
* untouched.
*
* Selecting ``h2`` means that ``h2`` is written into |*out| and its
* length (which is 2) is assigned to |*outlen|.
*
* For ALPN, refer to https://tools.ietf.org/html/rfc7301
*
* To use this method you should do something like::
*
* static int alpn_select_proto_cb(SSL* ssl,
* const unsigned char **out,
* unsigned char *outlen,
* const unsigned char *in,
* unsigned int inlen,
* void *arg)
* {
* int rv;
* rv = nghttp2_select_alpn(out, outlen, in, inlen);
* if (rv == -1) {
* return SSL_TLSEXT_ERR_NOACK;
* }
* if (rv == 1) {
* ((MyType*)arg)->http2_selected = 1;
* }
* return SSL_TLSEXT_ERR_OK;
* }
* ...
* SSL_CTX_set_alpn_select_cb(ssl_ctx, alpn_select_proto_cb, my_obj);
*
*/
NGHTTP2_EXTERN int nghttp2_select_alpn(const unsigned char **out,
unsigned char *outlen,
const unsigned char *in,
unsigned int inlen);
/**
* @function
*
* Returns a pointer to a nghttp2_info struct with version information
* about the run-time library in use. The |least_version| argument
* can be set to a 24 bit numerical value for the least accepted
* version number and if the condition is not met, this function will
* return a ``NULL``. Pass in 0 to skip the version checking.
*/
NGHTTP2_EXTERN nghttp2_info *nghttp2_version(int least_version);
/**
* @function
*
* Returns nonzero if the :type:`nghttp2_error` library error code
* |lib_error| is fatal.
*/
NGHTTP2_EXTERN int nghttp2_is_fatal(int lib_error_code);
/**
* @function
*
* Returns nonzero if HTTP header field name |name| of length |len| is
* valid according to http://tools.ietf.org/html/rfc7230#section-3.2
*
* Because this is a header field name in HTTP2, the upper cased alphabet
* is treated as error.
*/
NGHTTP2_EXTERN int nghttp2_check_header_name(const uint8_t *name, size_t len);
/**
* @function
*
* Returns nonzero if HTTP header field value |value| of length |len|
* is valid according to
* http://tools.ietf.org/html/rfc7230#section-3.2
*
* This function is considered obsolete, and application should
* consider to use `nghttp2_check_header_value_rfc9113()` instead.
*/
NGHTTP2_EXTERN int nghttp2_check_header_value(const uint8_t *value, size_t len);
/**
* @function
*
* Returns nonzero if HTTP header field value |value| of length |len|
* is valid according to
* http://tools.ietf.org/html/rfc7230#section-3.2, plus
* https://datatracker.ietf.org/doc/html/rfc9113#section-8.2.1
*/
NGHTTP2_EXTERN int nghttp2_check_header_value_rfc9113(const uint8_t *value,
size_t len);
/**
* @function
*
* Returns nonzero if the |value| which is supposed to be the value of
* the :method header field is valid according to
* https://datatracker.ietf.org/doc/html/rfc7231#section-4 and
* https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6
*/
NGHTTP2_EXTERN int nghttp2_check_method(const uint8_t *value, size_t len);
/**
* @function
*
* Returns nonzero if the |value| which is supposed to be the value of
* the :path header field is valid according to
* https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2.3
*
* |value| is valid if it merely consists of the allowed characters.
* In particular, it does not check whether |value| follows the syntax
* of path. The allowed characters are all characters valid by
* `nghttp2_check_header_value` minus SPC and HT.
*/
NGHTTP2_EXTERN int nghttp2_check_path(const uint8_t *value, size_t len);
/**
* @function
*
* Returns nonzero if the |value| which is supposed to be the value of the
* :authority or host header field is valid according to
* https://tools.ietf.org/html/rfc3986#section-3.2
*
* Note that :authority and host field values are not authority. They
* do not include userinfo in RFC 3986, see
* https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2, that
* is, it does not include '@'. This function treats '@' as a valid
* character.
*
* |value| is valid if it merely consists of the allowed characters.
* In particular, it does not check whether |value| follows the syntax
* of authority.
*/
NGHTTP2_EXTERN int nghttp2_check_authority(const uint8_t *value, size_t len);
/* HPACK API */
struct nghttp2_hd_deflater;
/**
* @struct
*
* HPACK deflater object.
*/
typedef struct nghttp2_hd_deflater nghttp2_hd_deflater;
/**
* @function
*
* Initializes |*deflater_ptr| for deflating name/values pairs.
*
* The |max_deflate_dynamic_table_size| is the upper bound of header
* table size the deflater will use.
*
* If this function fails, |*deflater_ptr| is left untouched.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int
nghttp2_hd_deflate_new(nghttp2_hd_deflater **deflater_ptr,
size_t max_deflate_dynamic_table_size);
/**
* @function
*
* Like `nghttp2_hd_deflate_new()`, but with additional custom memory
* allocator specified in the |mem|.
*
* The |mem| can be ``NULL`` and the call is equivalent to
* `nghttp2_hd_deflate_new()`.
*
* This function does not take ownership |mem|. The application is
* responsible for freeing |mem|.
*
* The library code does not refer to |mem| pointer after this
* function returns, so the application can safely free it.
*/
NGHTTP2_EXTERN int
nghttp2_hd_deflate_new2(nghttp2_hd_deflater **deflater_ptr,
size_t max_deflate_dynamic_table_size,
nghttp2_mem *mem);
/**
* @function
*
* Deallocates any resources allocated for |deflater|.
*/
NGHTTP2_EXTERN void nghttp2_hd_deflate_del(nghttp2_hd_deflater *deflater);
/**
* @function
*
* Changes header table size of the |deflater| to
* |settings_max_dynamic_table_size| bytes. This may trigger eviction
* in the dynamic table.
*
* The |settings_max_dynamic_table_size| should be the value received
* in SETTINGS_HEADER_TABLE_SIZE.
*
* The deflater never uses more memory than
* ``max_deflate_dynamic_table_size`` bytes specified in
* `nghttp2_hd_deflate_new()`. Therefore, if
* |settings_max_dynamic_table_size| >
* ``max_deflate_dynamic_table_size``, resulting maximum table size
* becomes ``max_deflate_dynamic_table_size``.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int
nghttp2_hd_deflate_change_table_size(nghttp2_hd_deflater *deflater,
size_t settings_max_dynamic_table_size);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_hd_deflate_hd2()` instead.
*
* Deflates the |nva|, which has the |nvlen| name/value pairs, into
* the |buf| of length |buflen|.
*
* If |buf| is not large enough to store the deflated header block,
* this function fails with
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`. The caller
* should use `nghttp2_hd_deflate_bound()` to know the upper bound of
* buffer size required to deflate given header name/value pairs.
*
* Once this function fails, subsequent call of this function always
* returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`.
*
* After this function returns, it is safe to delete the |nva|.
*
* This function returns the number of bytes written to |buf| if it
* succeeds, or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
* Deflation process has failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
* The provided |buflen| size is too small to hold the output.
*/
NGHTTP2_EXTERN ssize_t nghttp2_hd_deflate_hd(nghttp2_hd_deflater *deflater,
uint8_t *buf, size_t buflen,
const nghttp2_nv *nva,
size_t nvlen);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Deflates the |nva|, which has the |nvlen| name/value pairs, into
* the |buf| of length |buflen|.
*
* If |buf| is not large enough to store the deflated header block,
* this function fails with
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`. The caller
* should use `nghttp2_hd_deflate_bound()` to know the upper bound of
* buffer size required to deflate given header name/value pairs.
*
* Once this function fails, subsequent call of this function always
* returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`.
*
* After this function returns, it is safe to delete the |nva|.
*
* This function returns the number of bytes written to |buf| if it
* succeeds, or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
* Deflation process has failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
* The provided |buflen| size is too small to hold the output.
*/
NGHTTP2_EXTERN nghttp2_ssize
nghttp2_hd_deflate_hd2(nghttp2_hd_deflater *deflater, uint8_t *buf,
size_t buflen, const nghttp2_nv *nva, size_t nvlen);
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_hd_deflate_hd_vec2()` instead.
*
* Deflates the |nva|, which has the |nvlen| name/value pairs, into
* the |veclen| size of buf vector |vec|. The each size of buffer
* must be set in len field of :type:`nghttp2_vec`. If and only if
* one chunk is filled up completely, next chunk will be used. If
* |vec| is not large enough to store the deflated header block, this
* function fails with
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`. The caller
* should use `nghttp2_hd_deflate_bound()` to know the upper bound of
* buffer size required to deflate given header name/value pairs.
*
* Once this function fails, subsequent call of this function always
* returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`.
*
* After this function returns, it is safe to delete the |nva|.
*
* This function returns the number of bytes written to |vec| if it
* succeeds, or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
* Deflation process has failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
* The provided |buflen| size is too small to hold the output.
*/
NGHTTP2_EXTERN ssize_t nghttp2_hd_deflate_hd_vec(nghttp2_hd_deflater *deflater,
const nghttp2_vec *vec,
size_t veclen,
const nghttp2_nv *nva,
size_t nvlen);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Deflates the |nva|, which has the |nvlen| name/value pairs, into
* the |veclen| size of buf vector |vec|. The each size of buffer
* must be set in len field of :type:`nghttp2_vec`. If and only if
* one chunk is filled up completely, next chunk will be used. If
* |vec| is not large enough to store the deflated header block, this
* function fails with
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`. The caller
* should use `nghttp2_hd_deflate_bound()` to know the upper bound of
* buffer size required to deflate given header name/value pairs.
*
* Once this function fails, subsequent call of this function always
* returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`.
*
* After this function returns, it is safe to delete the |nva|.
*
* This function returns the number of bytes written to |vec| if it
* succeeds, or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
* Deflation process has failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
* The provided |buflen| size is too small to hold the output.
*/
NGHTTP2_EXTERN nghttp2_ssize nghttp2_hd_deflate_hd_vec2(
nghttp2_hd_deflater *deflater, const nghttp2_vec *vec, size_t veclen,
const nghttp2_nv *nva, size_t nvlen);
/**
* @function
*
* Returns an upper bound on the compressed size after deflation of
* |nva| of length |nvlen|.
*/
NGHTTP2_EXTERN size_t nghttp2_hd_deflate_bound(nghttp2_hd_deflater *deflater,
const nghttp2_nv *nva,
size_t nvlen);
/**
* @function
*
* Returns the number of entries that header table of |deflater|
* contains. This is the sum of the number of static table and
* dynamic table, so the return value is at least 61.
*/
NGHTTP2_EXTERN
size_t nghttp2_hd_deflate_get_num_table_entries(nghttp2_hd_deflater *deflater);
/**
* @function
*
* Returns the table entry denoted by |idx| from header table of
* |deflater|. The |idx| is 1-based, and idx=1 returns first entry of
* static table. idx=62 returns first entry of dynamic table if it
* exists. Specifying idx=0 is error, and this function returns NULL.
* If |idx| is strictly greater than the number of entries the tables
* contain, this function returns NULL.
*/
NGHTTP2_EXTERN
const nghttp2_nv *
nghttp2_hd_deflate_get_table_entry(nghttp2_hd_deflater *deflater, size_t idx);
/**
* @function
*
* Returns the used dynamic table size, including the overhead 32
* bytes per entry described in RFC 7541.
*/
NGHTTP2_EXTERN
size_t nghttp2_hd_deflate_get_dynamic_table_size(nghttp2_hd_deflater *deflater);
/**
* @function
*
* Returns the maximum dynamic table size.
*/
NGHTTP2_EXTERN
size_t
nghttp2_hd_deflate_get_max_dynamic_table_size(nghttp2_hd_deflater *deflater);
struct nghttp2_hd_inflater;
/**
* @struct
*
* HPACK inflater object.
*/
typedef struct nghttp2_hd_inflater nghttp2_hd_inflater;
/**
* @function
*
* Initializes |*inflater_ptr| for inflating name/values pairs.
*
* If this function fails, |*inflater_ptr| is left untouched.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
NGHTTP2_EXTERN int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr);
/**
* @function
*
* Like `nghttp2_hd_inflate_new()`, but with additional custom memory
* allocator specified in the |mem|.
*
* The |mem| can be ``NULL`` and the call is equivalent to
* `nghttp2_hd_inflate_new()`.
*
* This function does not take ownership |mem|. The application is
* responsible for freeing |mem|.
*
* The library code does not refer to |mem| pointer after this
* function returns, so the application can safely free it.
*/
NGHTTP2_EXTERN int nghttp2_hd_inflate_new2(nghttp2_hd_inflater **inflater_ptr,
nghttp2_mem *mem);
/**
* @function
*
* Deallocates any resources allocated for |inflater|.
*/
NGHTTP2_EXTERN void nghttp2_hd_inflate_del(nghttp2_hd_inflater *inflater);
/**
* @function
*
* Changes header table size in the |inflater|. This may trigger
* eviction in the dynamic table.
*
* The |settings_max_dynamic_table_size| should be the value
* transmitted in SETTINGS_HEADER_TABLE_SIZE.
*
* This function must not be called while header block is being
* inflated. In other words, this function must be called after
* initialization of |inflater|, but before calling
* `nghttp2_hd_inflate_hd3()`, or after
* `nghttp2_hd_inflate_end_headers()`. Otherwise,
* `NGHTTP2_ERR_INVALID_STATE` was returned.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
* The function is called while header block is being inflated.
* Probably, application missed to call
* `nghttp2_hd_inflate_end_headers()`.
*/
NGHTTP2_EXTERN int
nghttp2_hd_inflate_change_table_size(nghttp2_hd_inflater *inflater,
size_t settings_max_dynamic_table_size);
/**
* @enum
*
* The flags for header inflation.
*/
typedef enum {
/**
* No flag set.
*/
NGHTTP2_HD_INFLATE_NONE = 0,
/**
* Indicates all headers were inflated.
*/
NGHTTP2_HD_INFLATE_FINAL = 0x01,
/**
* Indicates a header was emitted.
*/
NGHTTP2_HD_INFLATE_EMIT = 0x02
} nghttp2_hd_inflate_flag;
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_hd_inflate_hd2()` instead.
*
* Inflates name/value block stored in |in| with length |inlen|. This
* function performs decompression. For each successful emission of
* header name/value pair,
* :enum:`nghttp2_hd_inflate_flag.NGHTTP2_HD_INFLATE_EMIT` is set in
* |*inflate_flags| and name/value pair is assigned to the |nv_out|
* and the function returns. The caller must not free the members of
* |nv_out|.
*
* The |nv_out| may include pointers to the memory region in the |in|.
* The caller must retain the |in| while the |nv_out| is used.
*
* The application should call this function repeatedly until the
* ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
* return value is non-negative. This means the all input values are
* processed successfully. Then the application must call
* `nghttp2_hd_inflate_end_headers()` to prepare for the next header
* block input.
*
* The caller can feed complete compressed header block. It also can
* feed it in several chunks. The caller must set |in_final| to
* nonzero if the given input is the last block of the compressed
* header.
*
* This function returns the number of bytes processed if it succeeds,
* or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
* Inflation process has failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_BUFFER_ERROR`
* The header field name or value is too large.
*
* Example follows::
*
* int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
* uint8_t *in, size_t inlen, int final)
* {
* ssize_t rv;
*
* for(;;) {
* nghttp2_nv nv;
* int inflate_flags = 0;
*
* rv = nghttp2_hd_inflate_hd(hd_inflater, &nv, &inflate_flags,
* in, inlen, final);
*
* if(rv < 0) {
* fprintf(stderr, "inflate failed with error code %zd", rv);
* return -1;
* }
*
* in += rv;
* inlen -= rv;
*
* if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
* fwrite(nv.name, nv.namelen, 1, stderr);
* fprintf(stderr, ": ");
* fwrite(nv.value, nv.valuelen, 1, stderr);
* fprintf(stderr, "\n");
* }
* if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
* nghttp2_hd_inflate_end_headers(hd_inflater);
* break;
* }
* if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
* inlen == 0) {
* break;
* }
* }
*
* return 0;
* }
*
*/
NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd(nghttp2_hd_inflater *inflater,
nghttp2_nv *nv_out,
int *inflate_flags, uint8_t *in,
size_t inlen, int in_final);
#endif /* NGHTTP2_NO_SSIZE_T */
#ifndef NGHTTP2_NO_SSIZE_T
/**
* @function
*
* .. warning::
*
* Deprecated. Use `nghttp2_hd_inflate_hd3()` instead.
*
* Inflates name/value block stored in |in| with length |inlen|. This
* function performs decompression. For each successful emission of
* header name/value pair,
* :enum:`nghttp2_hd_inflate_flag.NGHTTP2_HD_INFLATE_EMIT` is set in
* |*inflate_flags| and name/value pair is assigned to the |nv_out|
* and the function returns. The caller must not free the members of
* |nv_out|.
*
* The |nv_out| may include pointers to the memory region in the |in|.
* The caller must retain the |in| while the |nv_out| is used.
*
* The application should call this function repeatedly until the
* ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
* return value is non-negative. If that happens, all given input
* data (|inlen| bytes) are processed successfully. Then the
* application must call `nghttp2_hd_inflate_end_headers()` to prepare
* for the next header block input.
*
* In other words, if |in_final| is nonzero, and this function returns
* |inlen|, you can assert that
* :enum:`nghttp2_hd_inflate_final.NGHTTP2_HD_INFLATE_FINAL` is set in
* |*inflate_flags|.
*
* The caller can feed complete compressed header block. It also can
* feed it in several chunks. The caller must set |in_final| to
* nonzero if the given input is the last block of the compressed
* header.
*
* This function returns the number of bytes processed if it succeeds,
* or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
* Inflation process has failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_BUFFER_ERROR`
* The header field name or value is too large.
*
* Example follows::
*
* int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
* uint8_t *in, size_t inlen, int final)
* {
* ssize_t rv;
*
* for(;;) {
* nghttp2_nv nv;
* int inflate_flags = 0;
*
* rv = nghttp2_hd_inflate_hd2(hd_inflater, &nv, &inflate_flags,
* in, inlen, final);
*
* if(rv < 0) {
* fprintf(stderr, "inflate failed with error code %zd", rv);
* return -1;
* }
*
* in += rv;
* inlen -= rv;
*
* if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
* fwrite(nv.name, nv.namelen, 1, stderr);
* fprintf(stderr, ": ");
* fwrite(nv.value, nv.valuelen, 1, stderr);
* fprintf(stderr, "\n");
* }
* if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
* nghttp2_hd_inflate_end_headers(hd_inflater);
* break;
* }
* if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
* inlen == 0) {
* break;
* }
* }
*
* return 0;
* }
*
*/
NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd2(nghttp2_hd_inflater *inflater,
nghttp2_nv *nv_out,
int *inflate_flags,
const uint8_t *in, size_t inlen,
int in_final);
#endif /* NGHTTP2_NO_SSIZE_T */
/**
* @function
*
* Inflates name/value block stored in |in| with length |inlen|. This
* function performs decompression. For each successful emission of
* header name/value pair,
* :enum:`nghttp2_hd_inflate_flag.NGHTTP2_HD_INFLATE_EMIT` is set in
* |*inflate_flags| and name/value pair is assigned to the |nv_out|
* and the function returns. The caller must not free the members of
* |nv_out|.
*
* The |nv_out| may include pointers to the memory region in the |in|.
* The caller must retain the |in| while the |nv_out| is used.
*
* The application should call this function repeatedly until the
* ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
* return value is non-negative. If that happens, all given input
* data (|inlen| bytes) are processed successfully. Then the
* application must call `nghttp2_hd_inflate_end_headers()` to prepare
* for the next header block input.
*
* In other words, if |in_final| is nonzero, and this function returns
* |inlen|, you can assert that
* :enum:`nghttp2_hd_inflate_final.NGHTTP2_HD_INFLATE_FINAL` is set in
* |*inflate_flags|.
*
* The caller can feed complete compressed header block. It also can
* feed it in several chunks. The caller must set |in_final| to
* nonzero if the given input is the last block of the compressed
* header.
*
* This function returns the number of bytes processed if it succeeds,
* or one of the following negative error codes:
*
* :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
* Inflation process has failed.
* :enum:`nghttp2_error.NGHTTP2_ERR_BUFFER_ERROR`
* The header field name or value is too large.
*
* Example follows::
*
* int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
* uint8_t *in, size_t inlen, int final)
* {
* nghttp2_ssize rv;
*
* for(;;) {
* nghttp2_nv nv;
* int inflate_flags = 0;
*
* rv = nghttp2_hd_inflate_hd3(hd_inflater, &nv, &inflate_flags,
* in, inlen, final);
*
* if(rv < 0) {
* fprintf(stderr, "inflate failed with error code %td", rv);
* return -1;
* }
*
* in += rv;
* inlen -= rv;
*
* if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
* fwrite(nv.name, nv.namelen, 1, stderr);
* fprintf(stderr, ": ");
* fwrite(nv.value, nv.valuelen, 1, stderr);
* fprintf(stderr, "\n");
* }
* if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
* nghttp2_hd_inflate_end_headers(hd_inflater);
* break;
* }
* if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
* inlen == 0) {
* break;
* }
* }
*
* return 0;
* }
*
*/
NGHTTP2_EXTERN nghttp2_ssize nghttp2_hd_inflate_hd3(
nghttp2_hd_inflater *inflater, nghttp2_nv *nv_out, int *inflate_flags,
const uint8_t *in, size_t inlen, int in_final);
/**
* @function
*
* Signals the end of decompression for one header block.
*
* This function returns 0 if it succeeds. Currently this function
* always succeeds.
*/
NGHTTP2_EXTERN int
nghttp2_hd_inflate_end_headers(nghttp2_hd_inflater *inflater);
/**
* @function
*
* Returns the number of entries that header table of |inflater|
* contains. This is the sum of the number of static table and
* dynamic table, so the return value is at least 61.
*/
NGHTTP2_EXTERN
size_t nghttp2_hd_inflate_get_num_table_entries(nghttp2_hd_inflater *inflater);
/**
* @function
*
* Returns the table entry denoted by |idx| from header table of
* |inflater|. The |idx| is 1-based, and idx=1 returns first entry of
* static table. idx=62 returns first entry of dynamic table if it
* exists. Specifying idx=0 is error, and this function returns NULL.
* If |idx| is strictly greater than the number of entries the tables
* contain, this function returns NULL.
*/
NGHTTP2_EXTERN
const nghttp2_nv *
nghttp2_hd_inflate_get_table_entry(nghttp2_hd_inflater *inflater, size_t idx);
/**
* @function
*
* Returns the used dynamic table size, including the overhead 32
* bytes per entry described in RFC 7541.
*/
NGHTTP2_EXTERN
size_t nghttp2_hd_inflate_get_dynamic_table_size(nghttp2_hd_inflater *inflater);
/**
* @function
*
* Returns the maximum dynamic table size.
*/
NGHTTP2_EXTERN
size_t
nghttp2_hd_inflate_get_max_dynamic_table_size(nghttp2_hd_inflater *inflater);
struct nghttp2_stream;
/**
* @struct
*
* The structure to represent HTTP/2 stream. The details of this
* structure are intentionally hidden from the public API.
*/
typedef struct nghttp2_stream nghttp2_stream;
/**
* @function
*
* Returns pointer to :type:`nghttp2_stream` object denoted by
* |stream_id|. If stream was not found, returns NULL.
*
* Returns imaginary root stream (see
* `nghttp2_session_get_root_stream()`) if 0 is given in |stream_id|.
*
* Unless |stream_id| == 0, the returned pointer is valid until next
* call of `nghttp2_session_send()`, `nghttp2_session_mem_send2()`,
* `nghttp2_session_recv()`, and `nghttp2_session_mem_recv2()`.
*/
NGHTTP2_EXTERN nghttp2_stream *
nghttp2_session_find_stream(nghttp2_session *session, int32_t stream_id);
/**
* @enum
*
* State of stream as described in RFC 7540.
*/
typedef enum {
/**
* idle state.
*/
NGHTTP2_STREAM_STATE_IDLE = 1,
/**
* open state.
*/
NGHTTP2_STREAM_STATE_OPEN,
/**
* reserved (local) state.
*/
NGHTTP2_STREAM_STATE_RESERVED_LOCAL,
/**
* reserved (remote) state.
*/
NGHTTP2_STREAM_STATE_RESERVED_REMOTE,
/**
* half closed (local) state.
*/
NGHTTP2_STREAM_STATE_HALF_CLOSED_LOCAL,
/**
* half closed (remote) state.
*/
NGHTTP2_STREAM_STATE_HALF_CLOSED_REMOTE,
/**
* closed state.
*/
NGHTTP2_STREAM_STATE_CLOSED
} nghttp2_stream_proto_state;
/**
* @function
*
* Returns state of |stream|. The root stream retrieved by
* `nghttp2_session_get_root_stream()` will have stream state
* :enum:`nghttp2_stream_proto_state.NGHTTP2_STREAM_STATE_IDLE`.
*/
NGHTTP2_EXTERN nghttp2_stream_proto_state
nghttp2_stream_get_state(nghttp2_stream *stream);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* Returns root of dependency tree, which is imaginary stream with
* stream ID 0. The returned pointer is valid until |session| is
* freed by `nghttp2_session_del()`.
*/
NGHTTP2_EXTERN nghttp2_stream *
nghttp2_session_get_root_stream(nghttp2_session *session);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function always returns NULL.
*/
NGHTTP2_EXTERN nghttp2_stream *
nghttp2_stream_get_parent(nghttp2_stream *stream);
NGHTTP2_EXTERN int32_t nghttp2_stream_get_stream_id(nghttp2_stream *stream);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function always returns NULL.
*/
NGHTTP2_EXTERN nghttp2_stream *
nghttp2_stream_get_next_sibling(nghttp2_stream *stream);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function always returns NULL.
*/
NGHTTP2_EXTERN nghttp2_stream *
nghttp2_stream_get_previous_sibling(nghttp2_stream *stream);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function always returns NULL.
*/
NGHTTP2_EXTERN nghttp2_stream *
nghttp2_stream_get_first_child(nghttp2_stream *stream);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function always returns :macro:`NGHTTP2_DEFAULT_WEIGHT`.
*/
NGHTTP2_EXTERN int32_t nghttp2_stream_get_weight(nghttp2_stream *stream);
/**
* @function
*
* .. warning::
*
* Deprecated. :rfc:`7540` priorities are deprecated by
* :rfc:`9113`. Consider migrating to :rfc:`9218` extensible
* prioritization scheme.
*
* This function always returns 0.
*/
NGHTTP2_EXTERN int32_t
nghttp2_stream_get_sum_dependency_weight(nghttp2_stream *stream);
/**
* @functypedef
*
* Callback function invoked when the library outputs debug logging.
* The function is called with arguments suitable for ``vfprintf(3)``
*
* The debug output is only enabled if the library is built with
* ``DEBUGBUILD`` macro defined.
*/
typedef void (*nghttp2_debug_vprintf_callback)(const char *format,
va_list args);
/**
* @function
*
* Sets a debug output callback called by the library when built with
* ``DEBUGBUILD`` macro defined. If this option is not used, debug
* log is written into standard error output.
*
* For builds without ``DEBUGBUILD`` macro defined, this function is
* noop.
*
* Note that building with ``DEBUGBUILD`` may cause significant
* performance penalty to libnghttp2 because of extra processing. It
* should be used for debugging purpose only.
*
* .. Warning::
*
* Building with ``DEBUGBUILD`` may cause significant performance
* penalty to libnghttp2 because of extra processing. It should be
* used for debugging purpose only. We write this two times because
* this is important.
*/
NGHTTP2_EXTERN void nghttp2_set_debug_vprintf_callback(
nghttp2_debug_vprintf_callback debug_vprintf_callback);
#ifdef __cplusplus
}
#endif
#endif /* NGHTTP2_H */
lib/libnghttp2.so.14.28.5 0000755 00000535770 15053606574 0010607 0 ustar 00 ELF >