nghttp2/doc/sources/python-apiref.rst

Python API Reference
====================

.. py:module:: nghttp2

nghttp2 offers some high level Python API to C library.  The bindings
currently provide HPACK compressor and decompressor classes and HTTP/2
server class.

The extension module is called ``nghttp2``.

``make`` will build the bindings.  The target Python version is
determined by configure script.  If the detected Python version is not
what you expect, specify a path to Python executable in ``PYTHON``
variable as an argument to configure script (e.g., ``./configure
PYTHON=/usr/bin/python3.8``).

HPACK API
---------

.. py:class:: HDDeflater(hd_table_bufsize_max=DEFLATE_MAX_HEADER_TABLE_SIZE)

   This class is used to perform header compression.  The
   *hd_table_bufsize_max* limits the usage of header table in the
   given amount of bytes.  The default value is
   :py:data:`DEFLATE_MAX_HEADER_TABLE_SIZE`.  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, *hd_table_bufsize_max* can be used to
   cap the upper limit of table size whatever the header table size is
   chosen by the inflater.

   .. py:method:: deflate(headers)

      Deflates the *headers*. The *headers* must be sequence of tuple
      of name/value pair, which are byte strings (not unicode string).

      This method returns the deflated header block in byte string.
      Raises the exception if any error occurs.

   .. py:method:: set_no_refset(no_refset)

      Tells the deflater not to use reference set if *no_refset* is
      evaluated to ``True``.  If that happens, on each subsequent
      invocation of :py:meth:`deflate()`, deflater will clear up
      refersent set.

   .. py:method:: change_table_size(hd_table_bufsize_max)

      Changes header table size to *hd_table_bufsize_max* byte.  if
      *hd_table_bufsize_max* is strictly larger than
      ``hd_table_bufsize_max`` given in constructor,
      ``hd_table_bufsize_max`` is used as header table size instead.

      Raises the exception if any error occurs.

   .. py:method:: get_hd_table()

      Returns copy of current dynamic header table.

The following example shows how to deflate header name/value pairs:

.. code-block:: python

   import binascii, nghttp2

   deflater = nghttp2.HDDeflater()

   res = deflater.deflate([(b'foo', b'bar'),
                           (b'baz', b'buz')])

   print(binascii.b2a_hex(res))


.. py:class:: HDInflater()

   This class is used to perform header decompression.

   .. py:method:: inflate(data)

      Inflates the deflated header block *data*. The *data* must be
      byte string.

      Raises the exception if any error occurs.

   .. py:method:: change_table_size(hd_table_bufsize_max)

      Changes header table size to *hd_table_bufsize_max* byte.

      Raises the exception if any error occurs.

   .. py:method:: get_hd_table()

      Returns copy of current dynamic header table.

The following example shows how to inflate deflated header block:

.. code-block:: python

   deflater = nghttp2.HDDeflater()

   data = deflater.deflate([(b'foo', b'bar'),
                            (b'baz', b'buz')])

   inflater = nghttp2.HDInflater()

   hdrs = inflater.inflate(data)

   print(hdrs)


.. py:function:: print_hd_table(hdtable)

   Convenient function to print *hdtable* to the standard output.  The
   *hdtable* is the one retrieved by
   :py:meth:`HDDeflater.get_hd_table()` or
   :py:meth:`HDInflater.get_hd_table()`.  This function does not work
   if header name/value cannot be decoded using UTF-8 encoding.

   In output, ``s=N`` means the entry occupies ``N`` bytes in header
   table.  If ``r=y``, then the entry is in the reference set.

.. py:data:: DEFAULT_HEADER_TABLE_SIZE

   The default header table size, which is 4096 as per HTTP/2
   specification.

.. py:data:: DEFLATE_MAX_HEADER_TABLE_SIZE

   The default header table size for deflater.  The initial value
   is 4096.

HTTP/2 servers
--------------

.. note::

   We use :py:mod:`asyncio` for HTTP/2 server classes, and ALPN.
   Therefore, Python 3.8 or later is required to use these objects.
   To explicitly configure nghttp2 build to use Python 3.8, specify
   the ``PYTHON`` variable to the path to Python 3.8 executable when
   invoking configure script like this:

   .. code-block:: text

       $ ./configure PYTHON=/usr/bin/python3.8

.. py:class:: HTTP2Server(address, RequestHandlerClass, ssl=None)

   This class builds on top of the :py:mod:`asyncio` event loop.  On
   construction, *RequestHandlerClass* must be given, which must be a
   subclass of :py:class:`BaseRequestHandler` class.

   The *address* must be a tuple of hostname/IP address and port to
   bind.  If hostname/IP address is ``None``, all interfaces are
   assumed.

   To enable SSL/TLS, specify instance of :py:class:`ssl.SSLContext`
   in *ssl*.  Before passing *ssl* to
   :py:func:`BaseEventLoop.create_server`, ALPN protocol identifiers
   are set using :py:meth:`ssl.SSLContext.set_npn_protocols`.

   To disable SSL/TLS, omit *ssl* or specify ``None``.

   .. py:method:: serve_forever()

      Runs server and processes incoming requests forever.

.. py:class:: BaseRequestHandler(http2, stream_id)

   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.

   The first callback method invoked is :py:meth:`on_headers()`. It is
   called when HEADERS frame, which includes request header fields, is
   arrived.

   If request has request body, :py:meth:`on_data()` is invoked for
   each chunk of received data chunk.

   When whole request is received, :py:meth:`on_request_done()` is
   invoked.

   When stream is closed, :py:meth:`on_close()` is called.

   The application can send response using :py:meth:`send_response()`
   method.  It can be used in :py:meth:`on_headers()`,
   :py:meth:`on_data()` or :py:meth:`on_request_done()`.

   The application can push resource using :py:meth:`push()` method.
   It must be used before :py:meth:`send_response()` call.

   A :py:class:`BaseRequestHandler` has the following instance
   variables:

   .. py:attribute:: client_address

      Contains a tuple of the form ``(host, port)`` referring to the
      client's address.

   .. py:attribute:: stream_id

      Stream ID of this stream

   .. py:attribute:: scheme

      Scheme of the request URI.  This is a value of ``:scheme``
      header field.

   .. py:attribute:: method

      Method of this stream.  This is a value of ``:method`` header
      field.

   .. py:attribute:: host

      This is a value of ``:authority`` or ``host`` header field.

   .. py:attribute:: path

      This is a value of ``:path`` header field.

   .. py:attribute:: headers

      Request header fields.

   A :py:class:`BaseRequestHandler` has the following methods:

   .. py:method:: on_headers()

      Called when request HEADERS is arrived.  By default, this method
      does nothing.

   .. py:method:: on_data(data)

      Called when a chunk of request body *data* is arrived.  This
      method will be called multiple times until all data are
      received.  By default, this method does nothing.

   .. py:method:: on_request_done()

      Called when whole request was received.  By default, this method
      does nothing.

   .. py:method:: on_close(error_code)

      Called when stream is about to close.  The *error_code*
      indicates the reason of closure.  If it is ``0``, the stream is
      going to close without error.

   .. py:method:: send_response(status=200, headers=None, body=None)

      Send response.  The *status* is HTTP status code.  The *headers*
      is additional response headers.  The *:status* header field will
      be appended by the library.  The *body* is the response body.
      It could be ``None`` if response body is empty.  Or it must be
      instance of either ``str``, ``bytes``, :py:class:`io.IOBase` or
      callable, called body generator, which takes one parameter,
      size.  The body generator generates response body.  It can pause
      generation of response so that it can wait for slow backend data
      generation.  When invoked, it should return tuple, byte string
      at most size length and flag.  The flag is either
      :py:data:`DATA_OK`, :py:data:`DATA_EOF` or
      :py:data:`DATA_DEFERRED`.  For non-empty byte string and it is
      not the last chunk of response, :py:data:`DATA_OK` must be
      returned as flag.  If this is the last chunk of the response
      (byte string could be ``None``), :py:data:`DATA_EOF` must be
      returned as flag.  If there is no data available right now, but
      additional data are anticipated, return tuple (``None``,
      :py:data:`DATA_DEFERRED`).  When data arrived, call
      :py:meth:`resume()` and restart response body transmission.

      Only the body generator can pause response body generation;
      instance of :py:class:`io.IOBase` must not block.

      If instance of ``str`` is specified as *body*, it will be
      encoded using UTF-8.

      The *headers* is a list of tuple of the form ``(name,
      value)``. The ``name`` and ``value`` can be either byte string
      or unicode string.  In the latter case, they will be encoded
      using UTF-8.

      Raises the exception if any error occurs.

   .. py:method:: push(path, method='GET', request_headers=None, status=200, headers=None, body=None)

      Push a specified resource.  The *path* is a path portion of
      request URI for this resource.  The *method* is a method to
      access this resource.  The *request_headers* is additional
      request headers to access this resource.  The ``:scheme``,
      ``:method``, ``:authority`` and ``:path`` are appended by the
      library.  The ``:scheme`` and ``:authority`` are inherited from
      request header fields of the associated stream.

      The *status* is HTTP status code.  The *headers* is additional
      response headers.  The ``:status`` header field is appended by
      the library.  The *body* is the response body.  It has the same
      semantics of *body* parameter of :py:meth:`send_response()`.

      The headers and request_headers are a list of tuple of the form
      ``(name, value)``. The ``name`` and ``value`` can be either byte
      string or unicode string.  In the latter case, they will be
      encoded using UTF-8.

      Returns an instance of ``RequestHandlerClass`` specified in
      :py:class:`HTTP2Server` constructor for the pushed resource.

      Raises the exception if any error occurs.

   .. py:method:: resume()

      Signals the restarting of response body transmission paused by
      ``DATA_DEFERRED`` from the body generator (see
      :py:meth:`send_response()` about the body generator).  It is not
      an error calling this method while response body transmission is
      not paused.

.. py:data:: DATA_OK

   ``DATA_OK`` indicates non empty data is generated from body generator.

.. py:data:: DATA_EOF

   ``DATA_EOF`` indicates the end of response body.

.. py:data:: DATA_DEFERRED

   ``DATA_DEFERRED`` indicates that data are not available right now
   and response should be paused.

The following example illustrates :py:class:`HTTP2Server` and
:py:class:`BaseRequestHandler` usage:

.. code-block:: python

    #!/usr/bin/env python3

    import io, ssl

    import nghttp2

    class Handler(nghttp2.BaseRequestHandler):

        def on_headers(self):
            self.push(path='/css/style.css',
                      request_headers = [('content-type', 'text/css')],
                      status=200,
                      body='body{margin:0;}')

            self.send_response(status=200,
                               headers = [('content-type', 'text/plain')],
                               body=io.BytesIO(b'nghttp2-python FTW'))

    ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
    ctx.options = ssl.OP_ALL | ssl.OP_NO_SSLv2 | ssl.OP_NO_SSLv3
    ctx.load_cert_chain('server.crt', 'server.key')

    # give None to ssl to make the server non-SSL/TLS
    server = nghttp2.HTTP2Server(('127.0.0.1', 8443), Handler, ssl=ctx)
    server.serve_forever()

The following example illustrates HTTP/2 server using asynchronous
response body generation.  This is simplified reverse proxy:

.. code-block:: python

    #!/usr/bin/env python3

    import ssl
    import os
    import urllib
    import asyncio
    import io

    import nghttp2

    @asyncio.coroutine
    def get_http_header(handler, url):
        url = urllib.parse.urlsplit(url)
        ssl = url.scheme == 'https'
        if url.port == None:
            if url.scheme == 'https':
                port = 443
            else:
                port = 80
        else:
            port = url.port

        connect = asyncio.open_connection(url.hostname, port, ssl=ssl)
        reader, writer = yield from connect
        req = 'GET {path} HTTP/1.0\r\n\r\n'.format(path=url.path or '/')
        writer.write(req.encode('utf-8'))
        # skip response header fields
        while True:
            line = yield from reader.readline()
            line = line.rstrip()
            if not line:
                break
        # read body
        while True:
            b = yield from reader.read(4096)
            if not b:
                break
            handler.buf.write(b)
        writer.close()
        handler.buf.seek(0)
        handler.eof = True
        handler.resume()

    class Body:
        def __init__(self, handler):
            self.handler = handler
            self.handler.eof = False
            self.handler.buf = io.BytesIO()

        def generate(self, n):
            buf = self.handler.buf
            data = buf.read1(n)
            if not data and not self.handler.eof:
                return None, nghttp2.DATA_DEFERRED
            return data, nghttp2.DATA_EOF if self.handler.eof else nghttp2.DATA_OK

    class Handler(nghttp2.BaseRequestHandler):

        def on_headers(self):
            body = Body(self)
            asyncio.async(get_http_header(
                self, 'http://localhost' + self.path.decode('utf-8')))
            self.send_response(status=200, body=body.generate)

    ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
    ctx.options = ssl.OP_ALL | ssl.OP_NO_SSLv2 | ssl.OP_NO_SSLv3
    ctx.load_cert_chain('server.crt', 'server.key')

    server = nghttp2.HTTP2Server(('127.0.0.1', 8443), Handler, ssl=ctx)
    server.serve_forever()