The nghttp3 programmers' guide
==============================

This document describes a basic usage of nghttp3 library and common
pitfalls which programmers might encounter.

Assumptions
-----------

nghttp3 is a thin HTTP/3 layer over an underlying QUIC stack.  It
relies on an underlying QUIC stack for flow control and connection
management.  Although nghttp3 is QUIC stack agnostic, it expects some
particular interfaces from QUIC stack.  We will describe them below.

QPACK operations are done behind the scenes.  Application can use
:type:`nghttp3_settings` to change the behaviour of QPACK
encoder/decoder.

We define some keywords to avoid ambiguity in this document:

* HTTP payload: HTTP request/response body
* HTTP stream data: Series of HTTP header fields, HTTP payload, and
  HTTP trailer fields, serialized into HTTP/3 wire format, which is
  passed to or received from QUIC stack.

Initialization
--------------

The :type:`nghttp3_conn` is a basic building block of nghttp3 library.
It is created per HTTP/3 connection.  If an endpoint is a client, use
`nghttp3_conn_client_new` to initialize it as client.  If it is a
server, use `nghttp3_conn_server_new` to initialize it as server.

Those initialization functions take :type:`nghttp3_callbacks`.  All
callbacks are optional, but setting no callback functions makes
nghttp3 library useless for the most cases.  We list callbacks which
effectively required to do HTTP/3 transaction below:

* :member:`acked_stream_data <nghttp3_callbacks.acked_stream_data>`:
  Application has to retain HTTP payload (HTTP request/response body)
  until they are no longer used by :type:`nghttp3_conn`.  This
  callback functions tells the largest offset of HTTP payload
  acknowledged by a remote endpoint, and no longer used.
* :member:`stream_close <nghttp3_callbacks.stream_close>`: It is
  called when a stream is closed.  It is useful to free resources
  allocated for a stream.
* :member:`recv_data <nghttp3_callbacks.recv_data>`: It is called when
  HTTP payload (HTTP request/response body) is received.
* :member:`deferred_consume <nghttp3_callbacks.deferred_consume>`: It
  is called when :type:`nghttp3_conn` consumed HTTP stream data which
  had been blocked for synchronization between streams.  Application
  has to tell QUIC stack the number of bytes consumed which affects
  flow control.  We will discuss more about this callback later when
  explaining `nghttp3_conn_read_stream2`.
* :member:`recv_header <nghttp3_callbacks.recv_header>`: It is called
  when an HTTP header field is received.
* :member:`send_stop_sending <nghttp3_callbacks.send_stop_sending>`:
  It is called when QUIC STOP_SENDING frame must be sent for a
  particular stream.  Sending STOP_SENDING frame means that
  :type:`nghttp3_conn` no longer reads an incoming data for a
  particular stream.  Application has to tell QUIC stack to send
  STOP_SENDING frame.
* :member:`reset_stream <nghttp3_callbacks.reset_stream>`: It is
  called when QUIC RESET_STREAM frame must be sent for a particular
  stream.  Sending RESET_STREAM frame means that :type:`nghttp3_conn`
  stops sending any HTTP stream data to a particular stream.
  Application has to tell QUIC stack to send RESET_STREAM frame.
* :member:`rand <nghttp3_callbacks.rand>`: It is called when
  unpredictable data are needed.  Although this field is optional due
  to the backward compatibility, it is strongly recommended to specify
  this field to harden the runtime behavior against suspicious
  activities of a remote endpoint.  Most notably, it is used to
  randomize map key hashing which may be crucial for server side
  endpoints.

The initialization functions also takes :type:`nghttp3_settings` which
is a set of options to tweak HTTP3/ connection settings.
`nghttp3_settings_default` fills the default values.

The *user_data* parameter to the initialization function is an opaque
pointer and it is passed to callback functions.

Binding control streams
-----------------------

HTTP/3 requires at least 3 local unidirectional streams for a control
stream and QPACK encoder/decoder streams.

Use the following functions to bind those streams to their purposes:

* `nghttp3_conn_bind_control_stream`: Bind a given stream ID to a HTTP
  control stream.
* `nghttp3_conn_bind_qpack_streams`: Bind given 2 stream IDs to QPACK
  encoder and decoder streams.

Reading HTTP stream data
------------------------

`nghttp3_conn_read_stream2` reads HTTP stream data from a particular
stream.  It returns the number of bytes "consumed".  "Consumed" means
that the those bytes are completely processed and QUIC stack can
increase the flow control credit of both stream and connection by that
amount.

The HTTP payload notified by :member:`nghttp3_callbacks.recv_data` is
not included in the return value.  This is because the consumption of
those data is done by application and nghttp3 library does not know
when that happens.

Some HTTP stream data might be consumed later because of
synchronization between streams.  In this case, those bytes are
notified by :member:`nghttp3_callbacks.deferred_consume`.

In every case, the number of consumed HTTP stream data must be
notified to QUIC stack so that it can extend flow control limits.

Writing HTTP stream data
------------------------

`nghttp3_conn_writev_stream` writes HTTP stream data to a particular
stream.  The order of streams to produce HTTP stream data is
determined by the nghttp3 library.  In general, the control streams
have higher priority.  The regular HTTP streams are ordered by
header-based HTTP priority (see
https://datatracker.ietf.org/doc/html/rfc9218).

When HTTP stream data is generated, its stream ID is assigned to
*\*pstream_id*.  The pointer to HTTP stream data is assigned to *vec*,
and the function returns the number of *vec* it filled.  If the
generated data is the final part of the stream, *\*pfin* gets nonzero
value.  If no HTTP stream data is generated, the function returns 0
and *\*pstream_id* gets -1.

The function might return 0 and *\*pstream_id* has proper stream ID
and *\*pfin* set to nonzero.  In this case, no data is written, but it
signals the end of the stream.  Even though no data is written, QUIC
stack should be notified of the end of the stream.

The produced HTTP stream data is passed to QUIC stack.  Then call
`nghttp3_conn_add_write_offset` with the number of bytes accepted by
QUIC stack.  This must be done even when the written data is 0 bytes
with fin (refer to the previous paragraph for this corner case).

If QUIC stack indicates that a stream is blocked by stream level flow
control limit, call `nghttp3_conn_block_stream`.  It makes the library
not to generate HTTP stream data for the stream.  Call
`nghttp3_conn_unblock_stream` when stream level flow control limit is
increased.

If QUIC stack indicates that the write side of stream is closed, call
`nghttp3_conn_shutdown_stream_write` instead of
`nghttp3_conn_block_stream` so that the stream never be scheduled in
the future.

Creating HTTP request or response
---------------------------------

In order to create HTTP request, client application calls
`nghttp3_conn_submit_request`.  :type:`nghttp3_data_reader` is used to
send HTTP payload (HTTP request body).

Similarly, server application calls `nghttp3_conn_submit_response` to
create HTTP response.  :type:`nghttp3_data_reader` is also used to
send HTTP payload (HTTP response body).

In both cases, if :type:`nghttp3_data_reader` is not provided, no HTTP
payload is generated.

The :member:`nghttp3_data_reader.read_data` is a callback function to
generate HTTP payload.  Application must retain the data passed to the
library until those data are acknowledged by
:member:`nghttp3_callbacks.acked_stream_data`.  When no data is
available but will become available in the future, application returns
:macro:`NGHTTP3_ERR_WOULDBLOCK` from this callback.  Then the callback
is not called for the particular stream until
`nghttp3_conn_resume_stream` is called.

Reading HTTP request or response
--------------------------------

The :member:`nghttp3_callbacks.recv_header` is called when an HTTP
header field is received.

The :member:`nghttp3_callbacks.recv_data` is called when HTTP payload
is received.

Acknowledgement of HTTP stream data
-----------------------------------

QUIC stack must provide an interface to notify the amount of data
acknowledged by a remote endpoint.  `nghttp3_conn_add_ack_offset` must
be called with the largest offset of acknowledged HTTP stream data.

Handling QUIC stream events
---------------------------

If underlying QUIC stream is closed, call `nghttp3_conn_close_stream`.

If underlying QUIC stream is reset by a remote endpoint (that is when
RESET_STREAM is received) or no longer read by a local endpoint (that
is when STOP_SENDING is sent), call
`nghttp3_conn_shutdown_stream_read`.

Closing HTTP/3 connection gracefully
------------------------------------

`nghttp3_conn_submit_shutdown_notice` creates a message to a remote
endpoint that HTTP/3 connection is going down.  The receiving endpoint
should stop sending HTTP request after reading this signal.  After a
couple of RTTs, call `nghttp3_conn_submit_shutdown` to start graceful
shutdown.  After calling this function, the local endpoint starts
rejecting new incoming streams.  The existing streams are processed
normally.  When all those streams are completely processed, the
connection can be closed.  Clients inherently know whether their
requests have completed or not.  For server, `nghttp3_conn_is_drained`
tells whether all those streams have been completely processed.  When
it returns nonzero, the connection can be closed.
