<liclass="toctree-l2"><aclass="reference internal"href="package_README.html#client-server-and-proxy-programs">Client, Server and Proxy programs</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="package_README.html#libnghttp2-asio-high-level-http-2-c-library">libnghttp2_asio: High level HTTP/2 C++ library</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="nghttpx-howto.html#specifying-additional-ca-certificate">Specifying additional CA certificate</a></li>
<h2>HPACK API<aclass="headerlink"href="#hpack-api"title="Permalink to this headline">¶</a></h2>
<dlclass="class">
<dtid="nghttp2.HDDeflater">
<emclass="property">class </em><ttclass="descclassname">nghttp2.</tt><ttclass="descname">HDDeflater</tt><big>(</big><em>hd_table_bufsize_max=DEFLATE_MAX_HEADER_TABLE_SIZE</em><big>)</big><aclass="headerlink"href="#nghttp2.HDDeflater"title="Permalink to this definition">¶</a></dt>
<dd><p>This class is used to perform header compression. The
<em>hd_table_bufsize_max</em> limits the usage of header table in the
given amount of bytes. The default value is
<aclass="reference internal"href="#nghttp2.DEFLATE_MAX_HEADER_TABLE_SIZE"title="nghttp2.DEFLATE_MAX_HEADER_TABLE_SIZE"><ttclass="xref py py-data docutils literal"><spanclass="pre">DEFLATE_MAX_HEADER_TABLE_SIZE</span></tt></a>. This is necessary
because the deflater and inflater share the same amount of header
table and the inflater decides that number. The deflater may not
want to use all header table size because of limited memory
availability. In that case, <em>hd_table_bufsize_max</em> can be used to
cap the upper limit of table size whatever the header table size is
chosen by the inflater.</p>
<dlclass="method">
<dtid="nghttp2.HDDeflater.deflate">
<ttclass="descname">deflate</tt><big>(</big><em>headers</em><big>)</big><aclass="headerlink"href="#nghttp2.HDDeflater.deflate"title="Permalink to this definition">¶</a></dt>
<dd><p>Deflates the <em>headers</em>. The <em>headers</em> must be sequence of tuple
of name/value pair, which are byte strings (not unicode string).</p>
<p>This method returns the deflated header block in byte string.
Raises the exception if any error occurs.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.HDDeflater.set_no_refset">
<ttclass="descname">set_no_refset</tt><big>(</big><em>no_refset</em><big>)</big><aclass="headerlink"href="#nghttp2.HDDeflater.set_no_refset"title="Permalink to this definition">¶</a></dt>
<dd><p>Tells the deflater not to use reference set if <em>no_refset</em> is
evaluated to <ttclass="docutils literal"><spanclass="pre">True</span></tt>. If that happens, on each subsequent
invocation of <aclass="reference internal"href="#nghttp2.HDDeflater.deflate"title="nghttp2.HDDeflater.deflate"><ttclass="xref py py-meth docutils literal"><spanclass="pre">deflate()</span></tt></a>, deflater will clear up
refersent set.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.HDDeflater.change_table_size">
<ttclass="descname">change_table_size</tt><big>(</big><em>hd_table_bufsize_max</em><big>)</big><aclass="headerlink"href="#nghttp2.HDDeflater.change_table_size"title="Permalink to this definition">¶</a></dt>
<dd><p>Changes header table size to <em>hd_table_bufsize_max</em> byte. if
<em>hd_table_bufsize_max</em> is strictly larger than
<ttclass="docutils literal"><spanclass="pre">hd_table_bufsize_max</span></tt> given in constructor,
<ttclass="docutils literal"><spanclass="pre">hd_table_bufsize_max</span></tt> is used as header table size instead.</p>
<p>Raises the exception if any error occurs.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.HDDeflater.get_hd_table">
<ttclass="descname">get_hd_table</tt><big>(</big><big>)</big><aclass="headerlink"href="#nghttp2.HDDeflater.get_hd_table"title="Permalink to this definition">¶</a></dt>
<dd><p>Returns copy of current dynamic header table.</p>
</dd></dl>
</dd></dl>
<p>The following example shows how to deflate header name/value pairs:</p>
<emclass="property">class </em><ttclass="descclassname">nghttp2.</tt><ttclass="descname">HDInflater</tt><aclass="headerlink"href="#nghttp2.HDInflater"title="Permalink to this definition">¶</a></dt>
<dd><p>This class is used to perform header decompression.</p>
<dlclass="method">
<dtid="nghttp2.HDInflater.inflate">
<ttclass="descname">inflate</tt><big>(</big><em>data</em><big>)</big><aclass="headerlink"href="#nghttp2.HDInflater.inflate"title="Permalink to this definition">¶</a></dt>
<dd><p>Inflates the deflated header block <em>data</em>. The <em>data</em> must be
byte string.</p>
<p>Raises the exception if any error occurs.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.HDInflater.change_table_size">
<ttclass="descname">change_table_size</tt><big>(</big><em>hd_table_bufsize_max</em><big>)</big><aclass="headerlink"href="#nghttp2.HDInflater.change_table_size"title="Permalink to this definition">¶</a></dt>
<dd><p>Changes header table size to <em>hd_table_bufsize_max</em> byte.</p>
<p>Raises the exception if any error occurs.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.HDInflater.get_hd_table">
<ttclass="descname">get_hd_table</tt><big>(</big><big>)</big><aclass="headerlink"href="#nghttp2.HDInflater.get_hd_table"title="Permalink to this definition">¶</a></dt>
<dd><p>Returns copy of current dynamic header table.</p>
</dd></dl>
</dd></dl>
<p>The following example shows how to inflate deflated header block:</p>
<ttclass="descclassname">nghttp2.</tt><ttclass="descname">print_hd_table</tt><big>(</big><em>hdtable</em><big>)</big><aclass="headerlink"href="#nghttp2.print_hd_table"title="Permalink to this definition">¶</a></dt>
<dd><p>Convenient function to print <em>hdtable</em> to the standard output. The
<em>hdtable</em> is the one retrieved by
<aclass="reference internal"href="#nghttp2.HDDeflater.get_hd_table"title="nghttp2.HDDeflater.get_hd_table"><ttclass="xref py py-meth docutils literal"><spanclass="pre">HDDeflater.get_hd_table()</span></tt></a> or
<aclass="reference internal"href="#nghttp2.HDInflater.get_hd_table"title="nghttp2.HDInflater.get_hd_table"><ttclass="xref py py-meth docutils literal"><spanclass="pre">HDInflater.get_hd_table()</span></tt></a>. This function does not work
if header name/value cannot be decoded using UTF-8 encoding.</p>
<p>In output, <ttclass="docutils literal"><spanclass="pre">s=N</span></tt> means the entry occupies <ttclass="docutils literal"><spanclass="pre">N</span></tt> bytes in header
table. If <ttclass="docutils literal"><spanclass="pre">r=y</span></tt>, then the entry is in the reference set.</p>
</dd></dl>
<dlclass="data">
<dtid="nghttp2.DEFAULT_HEADER_TABLE_SIZE">
<ttclass="descclassname">nghttp2.</tt><ttclass="descname">DEFAULT_HEADER_TABLE_SIZE</tt><aclass="headerlink"href="#nghttp2.DEFAULT_HEADER_TABLE_SIZE"title="Permalink to this definition">¶</a></dt>
<dd><p>The default header table size, which is 4096 as per HTTP/2
specification.</p>
</dd></dl>
<dlclass="data">
<dtid="nghttp2.DEFLATE_MAX_HEADER_TABLE_SIZE">
<ttclass="descclassname">nghttp2.</tt><ttclass="descname">DEFLATE_MAX_HEADER_TABLE_SIZE</tt><aclass="headerlink"href="#nghttp2.DEFLATE_MAX_HEADER_TABLE_SIZE"title="Permalink to this definition">¶</a></dt>
<dd><p>The default header table size for deflater. The initial value
is 4096.</p>
</dd></dl>
</div>
<divclass="section"id="http-2-servers">
<h2>HTTP/2 servers<aclass="headerlink"href="#http-2-servers"title="Permalink to this headline">¶</a></h2>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<p>We use <ttclass="xref py py-mod docutils literal"><spanclass="pre">asyncio</span></tt> for HTTP/2 server classes. Therefore,
Python 3.4 or later is required to use these objects. To
explicitly configure nghttp2 build to use Python 3.4, specify the
<ttclass="docutils literal"><spanclass="pre">PYTHON</span></tt> variable to the path to Python 3.4 executable when
<emclass="property">class </em><ttclass="descclassname">nghttp2.</tt><ttclass="descname">HTTP2Server</tt><big>(</big><em>address</em>, <em>RequestHandlerClass</em>, <em>ssl=None</em><big>)</big><aclass="headerlink"href="#nghttp2.HTTP2Server"title="Permalink to this definition">¶</a></dt>
<dd><p>This class builds on top of the <ttclass="xref py py-mod docutils literal"><spanclass="pre">asyncio</span></tt> event loop. On
construction, <em>RequestHandlerClass</em> must be given, which must be a
subclass of <aclass="reference internal"href="#nghttp2.BaseRequestHandler"title="nghttp2.BaseRequestHandler"><ttclass="xref py py-class docutils literal"><spanclass="pre">BaseRequestHandler</span></tt></a> class.</p>
<p>The <em>address</em> must be a tuple of hostname/IP address and port to
bind. If hostname/IP address is <ttclass="docutils literal"><spanclass="pre">None</span></tt>, all interfaces are
are set using <ttclass="xref py py-meth docutils literal"><spanclass="pre">ssl.SSLContext.set_npn_protocols()</span></tt>.</p>
<p>To disable SSL/TLS, omit <em>ssl</em> or specify <ttclass="docutils literal"><spanclass="pre">None</span></tt>.</p>
<dlclass="method">
<dtid="nghttp2.HTTP2Server.serve_forever">
<ttclass="descname">serve_forever</tt><big>(</big><big>)</big><aclass="headerlink"href="#nghttp2.HTTP2Server.serve_forever"title="Permalink to this definition">¶</a></dt>
<dd><p>Runs server and processes incoming requests forever.</p>
</dd></dl>
</dd></dl>
<dlclass="class">
<dtid="nghttp2.BaseRequestHandler">
<emclass="property">class </em><ttclass="descclassname">nghttp2.</tt><ttclass="descname">BaseRequestHandler</tt><big>(</big><em>http2</em>, <em>stream_id</em><big>)</big><aclass="headerlink"href="#nghttp2.BaseRequestHandler"title="Permalink to this definition">¶</a></dt>
<dd><p>The class is used to handle the single HTTP/2 stream. By default,
it does not nothing. It must be subclassed to handle each event
callback method.</p>
<p>The first callback method invoked is <aclass="reference internal"href="#nghttp2.BaseRequestHandler.on_headers"title="nghttp2.BaseRequestHandler.on_headers"><ttclass="xref py py-meth docutils literal"><spanclass="pre">on_headers()</span></tt></a>. It is
called when HEADERS frame, which includes request header fields, is
arrived.</p>
<p>If request has request body, <aclass="reference internal"href="#nghttp2.BaseRequestHandler.on_data"title="nghttp2.BaseRequestHandler.on_data"><ttclass="xref py py-meth docutils literal"><spanclass="pre">on_data()</span></tt></a> is invoked for
each chunk of received data chunk.</p>
<p>When whole request is received, <aclass="reference internal"href="#nghttp2.BaseRequestHandler.on_request_done"title="nghttp2.BaseRequestHandler.on_request_done"><ttclass="xref py py-meth docutils literal"><spanclass="pre">on_request_done()</span></tt></a> is
invoked.</p>
<p>When stream is closed, <aclass="reference internal"href="#nghttp2.BaseRequestHandler.on_close"title="nghttp2.BaseRequestHandler.on_close"><ttclass="xref py py-meth docutils literal"><spanclass="pre">on_close()</span></tt></a> is called.</p>
<p>The application can send response using <aclass="reference internal"href="#nghttp2.BaseRequestHandler.send_response"title="nghttp2.BaseRequestHandler.send_response"><ttclass="xref py py-meth docutils literal"><spanclass="pre">send_response()</span></tt></a>
method. It can be used in <aclass="reference internal"href="#nghttp2.BaseRequestHandler.on_headers"title="nghttp2.BaseRequestHandler.on_headers"><ttclass="xref py py-meth docutils literal"><spanclass="pre">on_headers()</span></tt></a>,
<p>The application can push resource using <aclass="reference internal"href="#nghttp2.BaseRequestHandler.push"title="nghttp2.BaseRequestHandler.push"><ttclass="xref py py-meth docutils literal"><spanclass="pre">push()</span></tt></a> method.
It must be used before <aclass="reference internal"href="#nghttp2.BaseRequestHandler.send_response"title="nghttp2.BaseRequestHandler.send_response"><ttclass="xref py py-meth docutils literal"><spanclass="pre">send_response()</span></tt></a> call.</p>
<p>A <aclass="reference internal"href="#nghttp2.BaseRequestHandler"title="nghttp2.BaseRequestHandler"><ttclass="xref py py-class docutils literal"><spanclass="pre">BaseRequestHandler</span></tt></a> has the following instance
<ttclass="descname">client_address</tt><aclass="headerlink"href="#nghttp2.BaseRequestHandler.client_address"title="Permalink to this definition">¶</a></dt>
<dd><p>Contains a tuple of the form <ttclass="docutils literal"><spanclass="pre">(host,</span><spanclass="pre">port)</span></tt> referring to the
client’s address.</p>
</dd></dl>
<dlclass="attribute">
<dtid="nghttp2.BaseRequestHandler.stream_id">
<ttclass="descname">stream_id</tt><aclass="headerlink"href="#nghttp2.BaseRequestHandler.stream_id"title="Permalink to this definition">¶</a></dt>
<dd><p>Stream ID of this stream</p>
</dd></dl>
<dlclass="attribute">
<dtid="nghttp2.BaseRequestHandler.scheme">
<ttclass="descname">scheme</tt><aclass="headerlink"href="#nghttp2.BaseRequestHandler.scheme"title="Permalink to this definition">¶</a></dt>
<dd><p>Scheme of the request URI. This is a value of <ttclass="docutils literal"><spanclass="pre">:scheme</span></tt>
header field.</p>
</dd></dl>
<dlclass="attribute">
<dtid="nghttp2.BaseRequestHandler.method">
<ttclass="descname">method</tt><aclass="headerlink"href="#nghttp2.BaseRequestHandler.method"title="Permalink to this definition">¶</a></dt>
<dd><p>Method of this stream. This is a value of <ttclass="docutils literal"><spanclass="pre">:method</span></tt> header
field.</p>
</dd></dl>
<dlclass="attribute">
<dtid="nghttp2.BaseRequestHandler.host">
<ttclass="descname">host</tt><aclass="headerlink"href="#nghttp2.BaseRequestHandler.host"title="Permalink to this definition">¶</a></dt>
<dd><p>This is a value of <ttclass="docutils literal"><spanclass="pre">:authority</span></tt> or <ttclass="docutils literal"><spanclass="pre">host</span></tt> header field.</p>
</dd></dl>
<dlclass="attribute">
<dtid="nghttp2.BaseRequestHandler.path">
<ttclass="descname">path</tt><aclass="headerlink"href="#nghttp2.BaseRequestHandler.path"title="Permalink to this definition">¶</a></dt>
<dd><p>This is a value of <ttclass="docutils literal"><spanclass="pre">:path</span></tt> header field.</p>
</dd></dl>
<p>A <aclass="reference internal"href="#nghttp2.BaseRequestHandler"title="nghttp2.BaseRequestHandler"><ttclass="xref py py-class docutils literal"><spanclass="pre">BaseRequestHandler</span></tt></a> has the following methods:</p>
<dlclass="method">
<dtid="nghttp2.BaseRequestHandler.on_headers">
<ttclass="descname">on_headers</tt><big>(</big><big>)</big><aclass="headerlink"href="#nghttp2.BaseRequestHandler.on_headers"title="Permalink to this definition">¶</a></dt>
<dd><p>Called when request HEADERS is arrived. By default, this method
does nothing.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.BaseRequestHandler.on_data">
<ttclass="descname">on_data</tt><big>(</big><em>data</em><big>)</big><aclass="headerlink"href="#nghttp2.BaseRequestHandler.on_data"title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a chunk of request body <em>data</em> is arrived. This
method will be called multiple times until all data are
received. By default, this method does nothing.</p>
<ttclass="descname">on_request_done</tt><big>(</big><big>)</big><aclass="headerlink"href="#nghttp2.BaseRequestHandler.on_request_done"title="Permalink to this definition">¶</a></dt>
<dd><p>Called when whole request was received. By default, this method
does nothing.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.BaseRequestHandler.on_close">
<ttclass="descname">on_close</tt><big>(</big><em>error_code</em><big>)</big><aclass="headerlink"href="#nghttp2.BaseRequestHandler.on_close"title="Permalink to this definition">¶</a></dt>
<dd><p>Called when stream is about to close. The <em>error_code</em>
indicates the reason of closure. If it is <ttclass="docutils literal"><spanclass="pre">0</span></tt>, the stream is
going to close without error.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.BaseRequestHandler.send_response">
<ttclass="descname">send_response</tt><big>(</big><em>status=200</em>, <em>headers=None</em>, <em>body=None</em><big>)</big><aclass="headerlink"href="#nghttp2.BaseRequestHandler.send_response"title="Permalink to this definition">¶</a></dt>
<dd><p>Send response. The <em>status</em> is HTTP status code. The <em>headers</em>
is additional response headers. The <em>:status</em> header field will
be appended by the library. The <em>body</em> is the response body.
It could be <ttclass="docutils literal"><spanclass="pre">None</span></tt> if response body is empty. Or it must be
instance of either <ttclass="docutils literal"><spanclass="pre">str</span></tt>, <ttclass="docutils literal"><spanclass="pre">bytes</span></tt> or <ttclass="xref py py-class docutils literal"><spanclass="pre">io.IOBase</span></tt>.
If instance of <ttclass="docutils literal"><spanclass="pre">str</span></tt> is specified, it will be encoded using
UTF-8.</p>
<p>The <em>headers</em> is a list of tuple of the form <ttclass="docutils literal"><spanclass="pre">(name,</span>
<spanclass="pre">value)</span></tt>. The <ttclass="docutils literal"><spanclass="pre">name</span></tt> and <ttclass="docutils literal"><spanclass="pre">value</span></tt> can be either byte string
or unicode string. In the latter case, they will be encoded
using UTF-8.</p>
<p>Raises the exception if any error occurs.</p>
</dd></dl>
<dlclass="method">
<dtid="nghttp2.BaseRequestHandler.push">
<ttclass="descname">push</tt><big>(</big><em>path</em>, <em>method='GET'</em>, <em>request_headers=None</em>, <em>status=200</em>, <em>headers=None</em>, <em>body=None</em><big>)</big><aclass="headerlink"href="#nghttp2.BaseRequestHandler.push"title="Permalink to this definition">¶</a></dt>
<dd><p>Push a specified resource. The <em>path</em> is a path portion of
request URI for this resource. The <em>method</em> is a method to
access this resource. The <em>request_headers</em> is additional
request headers to access this resource. The <ttclass="docutils literal"><spanclass="pre">:scheme</span></tt>,
<ttclass="docutils literal"><spanclass="pre">:method</span></tt>, <ttclass="docutils literal"><spanclass="pre">:authority</span></tt> and <ttclass="docutils literal"><spanclass="pre">:path</span></tt> are appended by the
library. The <ttclass="docutils literal"><spanclass="pre">:scheme</span></tt> and <ttclass="docutils literal"><spanclass="pre">:authority</span></tt> are inherited from
request header fields of the associated stream.</p>
<p>The <em>status</em> is HTTP status code. The <em>headers</em> is additional
response headers. The <ttclass="docutils literal"><spanclass="pre">:status</span></tt> header field is appended by
the library. The <em>body</em> is the response body. It could be
<ttclass="docutils literal"><spanclass="pre">None</span></tt> if response body is empty. Or it must be instance of
either <ttclass="docutils literal"><spanclass="pre">str</span></tt>, <ttclass="docutils literal"><spanclass="pre">bytes</span></tt> or <ttclass="docutils literal"><spanclass="pre">io.IOBase</span></tt>. If instance of
<ttclass="docutils literal"><spanclass="pre">str</span></tt> is specified, it is encoded using UTF-8.</p>
<p>The headers and request_headers are a list of tuple of the form
<ttclass="docutils literal"><spanclass="pre">(name,</span><spanclass="pre">value)</span></tt>. The <ttclass="docutils literal"><spanclass="pre">name</span></tt> and <ttclass="docutils literal"><spanclass="pre">value</span></tt> can be either byte
string or unicode string. In the latter case, they will be
encoded using UTF-8.</p>
<p>Returns an instance of <ttclass="docutils literal"><spanclass="pre">RequestHandlerClass</span></tt> specified in
<aclass="reference internal"href="#nghttp2.HTTP2Server"title="nghttp2.HTTP2Server"><ttclass="xref py py-class docutils literal"><spanclass="pre">HTTP2Server</span></tt></a> constructor for the pushed resource.</p>
<p>Raises the exception if any error occurs.</p>
</dd></dl>
</dd></dl>
<p>The following example illustrates <aclass="reference internal"href="#nghttp2.HTTP2Server"title="nghttp2.HTTP2Server"><ttclass="xref py py-class docutils literal"><spanclass="pre">HTTP2Server</span></tt></a> and
<ahref="libnghttp2_asio.html"class="btn btn-neutral"title="libnghttp2_asio: High level HTTP/2 C++ library"><spanclass="fa fa-arrow-circle-left"></span> Previous</a>
