doc: Reword some of the server tutorial.
The overall meaning of the tutorial is the same, except for a couple of changes: - app_context struct was called "app_content", fixed the typo - nghttp2_session_server_new2() is mentioned, but the example uses nghttp2_session_server_new() instead, changed the text to match
This commit is contained in:
Tom Harwood
parent
a152c6346d
commit
e9e9626c2c
|
|
@ -1,30 +1,31 @@
|
|||
Tutorial: HTTP/2 server
|
||||
=========================
|
||||
|
||||
In this tutorial, we are going to write single-threaded, event-based
|
||||
HTTP/2 web server, which supports HTTPS only. It can handle
|
||||
concurrent multiple requests, but only the GET method is supported. The
|
||||
complete source code, `libevent-server.c`_, is attached at the end of
|
||||
this page. It also resides in examples directory in the archive or
|
||||
repository.
|
||||
In this tutorial, we are going to write a single-threaded, event-based
|
||||
HTTP/2 web server, which supports HTTPS only. It can handle concurrent
|
||||
multiple requests, but only the GET method is supported. The complete
|
||||
source code, `libevent-server.c`_, is attached at the end of this
|
||||
page. The source also resides in the examples directory in the
|
||||
archive or repository.
|
||||
|
||||
This simple server takes 3 arguments, a port number to listen to, a path to
|
||||
your SSL/TLS private key file and a path to your certificate file. Its
|
||||
synopsis is like this::
|
||||
This simple server takes 3 arguments: The port number to listen on,
|
||||
the path to your SSL/TLS private key file, and the path to your
|
||||
certificate file. The synopsis is::
|
||||
|
||||
$ libevent-server PORT /path/to/server.key /path/to/server.crt
|
||||
|
||||
We use libevent in this tutorial to handle networking I/O. Please
|
||||
note that nghttp2 itself does not depend on libevent.
|
||||
|
||||
First we create a setup routine for libevent and OpenSSL in the functions
|
||||
``main()`` and ``run()``. One thing in there you should look at, is the setup
|
||||
of the NPN callback. The NPN callback is used for the server to advertise
|
||||
which application protocols the server supports to a client. In this example
|
||||
program, when creating ``SSL_CTX`` object, we store the application protocol
|
||||
name in the wire format of NPN in a statically allocated buffer. This is safe
|
||||
because we only create one ``SSL_CTX`` object in the program's entire life
|
||||
time::
|
||||
The server starts with some libevent and OpenSSL setup in the
|
||||
``main()`` and ``run()`` functions. This setup isn't specific to
|
||||
nghttp2, but one thing you should look at is setup of the NPN
|
||||
callback. The NPN callback is used by the server to advertise which
|
||||
application protocols the server supports to a client. In this
|
||||
example program, when creating the ``SSL_CTX`` object, we store the
|
||||
application protocol name in the wire format of NPN in a statically
|
||||
allocated buffer. This is safe because we only create one ``SSL_CTX``
|
||||
object in the program's entire lifetime::
|
||||
|
||||
static unsigned char next_proto_list[256];
|
||||
static size_t next_proto_list_len;
|
||||
|
|
@ -53,17 +54,20 @@ time::
|
|||
return ssl_ctx;
|
||||
}
|
||||
|
||||
The wire format of NPN is a sequence of length prefixed string. Exactly one
|
||||
byte is used to specify the length of each protocol identifier. In this
|
||||
tutorial, we advertise the specific HTTP/2 protocol version the current
|
||||
nghttp2 library supports. The nghttp2 library exports its identifier in
|
||||
:macro:`NGHTTP2_PROTO_VERSION_ID`. The ``next_proto_cb()`` function is the
|
||||
server-side NPN callback. In the OpenSSL implementation, we just assign the
|
||||
pointer to the NPN buffers we filled in earlier. The NPN callback function is
|
||||
set to the ``SSL_CTX`` object using
|
||||
``SSL_CTX_set_next_protos_advertised_cb()``.
|
||||
The wire format of NPN is a sequence of length prefixed strings, with
|
||||
exactly one byte used to specify the length of each protocol
|
||||
identifier. In this tutorial, we advertise the specific HTTP/2
|
||||
protocol version the current nghttp2 library supports, which is
|
||||
exported in the identifier :macro:`NGHTTP2_PROTO_VERSION_ID`. The
|
||||
``next_proto_cb()`` function is the server-side NPN callback. In the
|
||||
OpenSSL implementation, we just assign the pointer to the NPN buffers
|
||||
we filled in earlier. The NPN callback function is set to the
|
||||
``SSL_CTX`` object using ``SSL_CTX_set_next_protos_advertised_cb()``.
|
||||
|
||||
We use the ``app_content`` structure to store application-wide data::
|
||||
Next, let's take a look at the main structures used by the example
|
||||
application:
|
||||
|
||||
We use the ``app_context`` structure to store application-wide data::
|
||||
|
||||
struct app_context {
|
||||
SSL_CTX *ssl_ctx;
|
||||
|
|
@ -90,18 +94,21 @@ We use the ``http2_stream_data`` structure to store stream-level data::
|
|||
int fd;
|
||||
} http2_stream_data;
|
||||
|
||||
A single HTTP/2 session can have multiple streams. We manage these
|
||||
multiple streams with a doubly linked list. The first element of this
|
||||
list is pointed to by the ``root->next`` in ``http2_session_data``.
|
||||
Initially, ``root->next`` is ``NULL``. We use libevent's bufferevent
|
||||
structure to perform network I/O. Note that the bufferevent object is
|
||||
kept in ``http2_session_data`` and not in ``http2_stream_data``. This
|
||||
is because ``http2_stream_data`` is just a logical stream multiplexed
|
||||
over the single connection managed by bufferevent in
|
||||
A single HTTP/2 session can have multiple streams. To manage them, we
|
||||
use a doubly linked list: The first element of this list is pointed
|
||||
to by the ``root->next`` in ``http2_session_data``. Initially,
|
||||
``root->next`` is ``NULL``.
|
||||
|
||||
libevent's bufferevent structure is used to perform network I/O, with
|
||||
the pointer to the bufferevent stored in the ``http2_session_data``
|
||||
structure. Note that the bufferevent object is kept in
|
||||
``http2_session_data`` and not in ``http2_stream_data``. This is
|
||||
because ``http2_stream_data`` is just a logical stream multiplexed
|
||||
over the single connection managed by the bufferevent in
|
||||
``http2_session_data``.
|
||||
|
||||
We first create a listener object to accept incoming connections. We use
|
||||
libevent's ``struct evconnlistener`` for this purpose::
|
||||
We first create a listener object to accept incoming connections.
|
||||
libevent's ``struct evconnlistener`` is used for this purpose::
|
||||
|
||||
static void start_listen(struct event_base *evbase, const char *service,
|
||||
app_context *app_ctx) {
|
||||
|
|
@ -135,7 +142,7 @@ libevent's ``struct evconnlistener`` for this purpose::
|
|||
errx(1, "Could not start listener");
|
||||
}
|
||||
|
||||
We specify the ``acceptcb`` callback which is called when a new connection is
|
||||
We specify the ``acceptcb`` callback, which is called when a new connection is
|
||||
accepted::
|
||||
|
||||
static void acceptcb(struct evconnlistener *listener _U_, int fd,
|
||||
|
|
@ -148,13 +155,13 @@ accepted::
|
|||
bufferevent_setcb(session_data->bev, readcb, writecb, eventcb, session_data);
|
||||
}
|
||||
|
||||
Here we create the ``http2_session_data`` object. The bufferevent for
|
||||
this connection is also initialized at this time. We specify three
|
||||
callbacks for the bufferevent: ``readcb``, ``writecb`` and
|
||||
Here we create the ``http2_session_data`` object. The connection's
|
||||
bufferevent is initialized at the same time. We specify three
|
||||
callbacks for the bufferevent: ``readcb``, ``writecb``, and
|
||||
``eventcb``.
|
||||
|
||||
The ``eventcb()`` callback is invoked by the libevent event loop when an event
|
||||
(e.g., connection has been established, timeout, etc) happens on the
|
||||
(e.g. connection has been established, timeout, etc.) occurs on the
|
||||
underlying network socket::
|
||||
|
||||
static void eventcb(struct bufferevent *bev _U_, short events, void *ptr) {
|
||||
|
|
@ -181,17 +188,19 @@ underlying network socket::
|
|||
delete_http2_session_data(session_data);
|
||||
}
|
||||
|
||||
For the ``BEV_EVENT_EOF``, ``BEV_EVENT_ERROR`` and
|
||||
For the ``BEV_EVENT_EOF``, ``BEV_EVENT_ERROR``, and
|
||||
``BEV_EVENT_TIMEOUT`` events, we just simply tear down the connection.
|
||||
The ``delete_http2_session_data()`` function destroys the
|
||||
``http2_session_data`` object and thus also its bufferevent member.
|
||||
As a result, the underlying connection is closed. The
|
||||
``BEV_EVENT_CONNECTED`` event is invoked when SSL/TLS handshake is
|
||||
finished successfully. Now we are ready to start the HTTP/2
|
||||
communication.
|
||||
``http2_session_data`` object and its associated bufferevent member.
|
||||
As a result, the underlying connection is closed.
|
||||
|
||||
We initialize a nghttp2 session object which is done in
|
||||
``initialize_nghttp2_session()``::
|
||||
The
|
||||
``BEV_EVENT_CONNECTED`` event is invoked when SSL/TLS handshake has
|
||||
completed successfully. After this we are ready to begin communicating
|
||||
via HTTP/2.
|
||||
|
||||
The ``initialize_nghttp2_session()`` function initializes the nghttp2
|
||||
session object and several callbacks::
|
||||
|
||||
static void initialize_nghttp2_session(http2_session_data *session_data) {
|
||||
nghttp2_session_callbacks *callbacks;
|
||||
|
|
@ -217,13 +226,13 @@ We initialize a nghttp2 session object which is done in
|
|||
nghttp2_session_callbacks_del(callbacks);
|
||||
}
|
||||
|
||||
Since we are creating a server and uses options, the nghttp2 session
|
||||
object is created using `nghttp2_session_server_new2()` function. We
|
||||
registers five callbacks for nghttp2 session object. We'll talk about
|
||||
these callbacks later.
|
||||
Since we are creating a server, we use `nghttp2_session_server_new()`
|
||||
to initialize the nghttp2 session object. We also setup 5 callbacks
|
||||
for the nghttp2 session, these are explained later.
|
||||
|
||||
After initialization of the nghttp2 session object, we are going to send
|
||||
a server connection header in ``send_server_connection_header()``::
|
||||
The server now begins by sending the server connection preface, which
|
||||
always consists of a SETTINGS frame.
|
||||
``send_server_connection_header()`` configures and submits it::
|
||||
|
||||
static int send_server_connection_header(http2_session_data *session_data) {
|
||||
nghttp2_settings_entry iv[1] = {
|
||||
|
|
@ -239,11 +248,10 @@ a server connection header in ``send_server_connection_header()``::
|
|||
return 0;
|
||||
}
|
||||
|
||||
The server connection header is a SETTINGS frame. We specify
|
||||
SETTINGS_MAX_CONCURRENT_STREAMS to 100 in the SETTINGS frame. To queue
|
||||
the SETTINGS frame for the transmission, we use
|
||||
`nghttp2_submit_settings()`. Note that `nghttp2_submit_settings()`
|
||||
function only queues the frame and it does not actually send it. All
|
||||
In the example SETTINGS frame we've set
|
||||
SETTINGS_MAX_CONCURRENT_STREAMS to 100. ``nghttp2_submit_settings()``
|
||||
is used to queue the frame for transmission, but note it only queues
|
||||
the frame for transmission, and doesn't actually send it. All
|
||||
functions in the ``nghttp2_submit_*()`` family have this property. To
|
||||
actually send the frame, `nghttp2_session_send()` should be used, as
|
||||
described later.
|
||||
|
|
@ -274,12 +282,14 @@ this pending data. To process the received data, we call the
|
|||
return 0;
|
||||
}
|
||||
|
||||
In this function, we feed all unprocessed but already received data to the
|
||||
nghttp2 session object using the `nghttp2_session_mem_recv()` function. The
|
||||
`nghttp2_session_mem_recv()` function processes the data and may invoke the
|
||||
nghttp2 callbacks and also queue outgoing frames. Since there may be pending
|
||||
outgoing frames, we call ``session_send()`` function to send off those
|
||||
frames. The ``session_send()`` function is defined as follows::
|
||||
In this function, we feed all unprocessed but already received data to
|
||||
the nghttp2 session object using the `nghttp2_session_mem_recv()`
|
||||
function. The `nghttp2_session_mem_recv()` function processes the data
|
||||
and may both invoke the previously setup callbacks and also queue
|
||||
outgoing frames. To send any pending outgoing frames, we immediately
|
||||
call ``session_send()``.
|
||||
|
||||
The ``session_send()`` function is defined as follows::
|
||||
|
||||
static int session_send(http2_session_data *session_data) {
|
||||
int rv;
|
||||
|
|
@ -292,7 +302,7 @@ frames. The ``session_send()`` function is defined as follows::
|
|||
}
|
||||
|
||||
The `nghttp2_session_send()` function serializes the frame into wire
|
||||
format and calls ``send_callback()`` of type
|
||||
format and calls the ``send_callback()``, which is of type
|
||||
:type:`nghttp2_send_callback`. The ``send_callback()`` is defined as
|
||||
follows::
|
||||
|
||||
|
|
@ -312,17 +322,16 @@ follows::
|
|||
Since we use bufferevent to abstract network I/O, we just write the
|
||||
data to the bufferevent object. Note that `nghttp2_session_send()`
|
||||
continues to write all frames queued so far. If we were writing the
|
||||
data to a non-blocking socket directly using ``write()`` system call
|
||||
in the ``send_callback()``, we would surely get ``EAGAIN`` or
|
||||
``EWOULDBLOCK`` back since the socket has limited send buffer. If that
|
||||
happens, we can return :macro:`NGHTTP2_ERR_WOULDBLOCK` to signal the
|
||||
nghttp2 library to stop sending further data. But when writing to the
|
||||
bufferevent, we have to regulate the amount data to get buffered
|
||||
ourselves to avoid using huge amounts of memory. To achieve this, we
|
||||
check the size of the output buffer and if it reaches more than or
|
||||
equal to ``OUTPUT_WOULDBLOCK_THRESHOLD`` bytes, we stop writing data
|
||||
and return :macro:`NGHTTP2_ERR_WOULDBLOCK` to tell the library to stop
|
||||
calling send_callback.
|
||||
data to a non-blocking socket directly using the ``write()`` system
|
||||
call in the ``send_callback()``, we'd soon receive an ``EAGAIN`` or
|
||||
``EWOULDBLOCK`` error since sockets have a limited send buffer. If
|
||||
that happens, it's possible to return :macro:`NGHTTP2_ERR_WOULDBLOCK`
|
||||
to signal the nghttp2 library to stop sending further data. But here,
|
||||
when writing to the bufferevent, we have to regulate the amount data
|
||||
to buffered ourselves to avoid using huge amounts of memory. To
|
||||
achieve this, we check the size of the output buffer and if it reaches
|
||||
more than or equal to ``OUTPUT_WOULDBLOCK_THRESHOLD`` bytes, we stop
|
||||
writing data and return :macro:`NGHTTP2_ERR_WOULDBLOCK`.
|
||||
|
||||
The next bufferevent callback is ``readcb()``, which is invoked when
|
||||
data is available to read in the bufferevent input buffer::
|
||||
|
|
@ -357,16 +366,18 @@ data in the bufferevent output buffer has been sent::
|
|||
}
|
||||
}
|
||||
|
||||
First we check whether we should drop the connection or not. The nghttp2
|
||||
session object keeps track of reception and transmission of GOAWAY frames and
|
||||
other error conditions as well. Using this information, the nghttp2 session
|
||||
object will tell whether the connection should be dropped or not. More
|
||||
specifically, if both `nghttp2_session_want_read()` and
|
||||
`nghttp2_session_want_write()` return 0, we have no business left in the
|
||||
connection. But since we are using bufferevent and its deferred callback
|
||||
option, the bufferevent output buffer may contain pending data when the
|
||||
``writecb()`` is called. To handle this, we check whether the output buffer is
|
||||
empty or not. If all these conditions are met, we drop connection.
|
||||
First we check whether we should drop the connection or not. The
|
||||
nghttp2 session object keeps track of reception and transmission of
|
||||
GOAWAY frames and other error conditions as well. Using this
|
||||
information, the nghttp2 session object can state whether the
|
||||
connection should be dropped or not. More specifically, if both
|
||||
`nghttp2_session_want_read()` and `nghttp2_session_want_write()`
|
||||
return 0, the connection is no-longer required and can be closed.
|
||||
Since we are using bufferevent and its deferred callback option, the
|
||||
bufferevent output buffer may still contain pending data when the
|
||||
``writecb()`` is called. To handle this, we check whether the output
|
||||
buffer is empty or not. If all of these conditions are met, we drop
|
||||
connection.
|
||||
|
||||
Otherwise, we call ``session_send()`` to process the pending output
|
||||
data. Remember that in ``send_callback()``, we must not write all data to
|
||||
|
|
@ -374,7 +385,7 @@ bufferevent to avoid excessive buffering. We continue processing pending data
|
|||
when the output buffer becomes empty.
|
||||
|
||||
We have already described the nghttp2 callback ``send_callback()``. Let's
|
||||
learn about the remaining nghttp2 callbacks we setup in
|
||||
learn about the remaining nghttp2 callbacks setup in
|
||||
``initialize_nghttp2_setup()`` function.
|
||||
|
||||
The ``on_begin_headers_callback()`` function is invoked when the reception of
|
||||
|
|
@ -396,13 +407,15 @@ a header block in HEADERS or PUSH_PROMISE frame is started::
|
|||
return 0;
|
||||
}
|
||||
|
||||
We are only interested in the HEADERS frame in this function. Since the
|
||||
HEADERS frame has several roles in the HTTP/2 protocol, we check that it is a
|
||||
request HEADERS, which opens new stream. If the frame is a request HEADERS, we
|
||||
create a ``http2_stream_data`` object to store the stream related data. We
|
||||
associate the created ``http2_stream_data`` object with the stream in the
|
||||
nghttp2 session object using `nghttp2_set_stream_user_data()` to get the
|
||||
object without searching through the doubly linked list.
|
||||
We are only interested in the HEADERS frame in this function. Since
|
||||
the HEADERS frame has several roles in the HTTP/2 protocol, we check
|
||||
that it is a request HEADERS, which opens new stream. If the frame is
|
||||
a request HEADERS, we create a ``http2_stream_data`` object to store
|
||||
the stream related data. We associate the created
|
||||
``http2_stream_data`` object with the stream in the nghttp2 session
|
||||
object using `nghttp2_set_stream_user_data()`. The
|
||||
``http2_stream_data`` object can later be easily retrieved from the
|
||||
stream, without searching through the doubly linked list.
|
||||
|
||||
In this example server, we want to serve files relative to the current working
|
||||
directory in which the program was invoked. Each header name/value pair is
|
||||
|
|
@ -437,10 +450,10 @@ emitted via ``on_header_callback`` function, which is called after
|
|||
return 0;
|
||||
}
|
||||
|
||||
We search for the ``:path`` header field among the request headers and store
|
||||
the requested path in the ``http2_stream_data`` object. In this example
|
||||
program, we ignore ``:method`` header field and always treat the request as a
|
||||
GET request.
|
||||
We search for the ``:path`` header field among the request headers and
|
||||
store the requested path in the ``http2_stream_data`` object. In this
|
||||
example program, we ignore the ``:method`` header field and always
|
||||
treat the request as a GET request.
|
||||
|
||||
The ``on_frame_recv_callback()`` function is invoked when a frame is
|
||||
fully received::
|
||||
|
|
@ -470,15 +483,15 @@ fully received::
|
|||
return 0;
|
||||
}
|
||||
|
||||
First we retrieve the ``http2_stream_data`` object associated with the stream
|
||||
in ``on_begin_headers_callback()``. It is done using
|
||||
`nghttp2_session_get_stream_user_data()`. If the requested path cannot be
|
||||
served for some reason (e.g., file is not found), we send a 404 response,
|
||||
which is done in ``error_reply()``. Otherwise, we open the requested file and
|
||||
send its content. We send the header field ``:status`` as a single response
|
||||
header.
|
||||
First we retrieve the ``http2_stream_data`` object associated with the
|
||||
stream in ``on_begin_headers_callback()`` using
|
||||
``nghttp2_session_get_stream_user_data()``. If the requested path
|
||||
cannot be served for some reason (e.g. file is not found), we send a
|
||||
404 response using ``error_reply()``. Otherwise, we open
|
||||
the requested file and send its content. We send the header field
|
||||
``:status`` as a single response header.
|
||||
|
||||
Sending the content of the file is done in ``send_response()`` function::
|
||||
Sending the file content is performed by the ``send_response()`` function::
|
||||
|
||||
static int send_response(nghttp2_session *session, int32_t stream_id,
|
||||
nghttp2_nv *nva, size_t nvlen, int fd) {
|
||||
|
|
@ -495,12 +508,13 @@ Sending the content of the file is done in ``send_response()`` function::
|
|||
return 0;
|
||||
}
|
||||
|
||||
The nghttp2 library uses the :type:`nghttp2_data_provider` structure to
|
||||
send entity body to the remote peer. The ``source`` member of this
|
||||
structure is a union and it can be either void pointer or int which is
|
||||
intended to be used as file descriptor. In this example server, we use
|
||||
the file descriptor. We also set the ``file_read_callback()`` callback
|
||||
function to read the contents of the file::
|
||||
nghttp2 uses the :type:`nghttp2_data_provider` structure to send the
|
||||
entity body to the remote peer. The ``source`` member of this
|
||||
structure is a union, which can be either a void pointer or an int
|
||||
(which is intended to be used as file descriptor). In this example
|
||||
server, we use it as a file descriptor. We also set the
|
||||
``file_read_callback()`` callback function to read the contents of the
|
||||
file::
|
||||
|
||||
static ssize_t file_read_callback(nghttp2_session *session _U_,
|
||||
int32_t stream_id _U_, uint8_t *buf,
|
||||
|
|
@ -520,11 +534,11 @@ function to read the contents of the file::
|
|||
return r;
|
||||
}
|
||||
|
||||
If an error happens while reading the file, we return
|
||||
If an error occurs while reading the file, we return
|
||||
:macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. This tells the
|
||||
library to send RST_STREAM to the stream. When all data has been read, set
|
||||
the :macro:`NGHTTP2_DATA_FLAG_EOF` flag to ``*data_flags`` to tell the
|
||||
nghttp2 library that we have finished reading the file.
|
||||
library to send RST_STREAM to the stream. When all data has been
|
||||
read, the :macro:`NGHTTP2_DATA_FLAG_EOF` flag is set to signal nghttp2
|
||||
that we have finished reading the file.
|
||||
|
||||
The `nghttp2_submit_response()` function is used to send the response to the
|
||||
remote peer.
|
||||
|
|
@ -546,5 +560,5 @@ is about to close::
|
|||
return 0;
|
||||
}
|
||||
|
||||
We destroy the ``http2_stream_data`` object in this function since the stream
|
||||
is about to close and we no longer use that object.
|
||||
Lastly, we destroy the ``http2_stream_data`` object in this function,
|
||||
since the stream is about to close and we no longer need the object.
|
||||
|
|
|
|||
Loading…
Reference in New Issue