Merge branch 'reword-client-tutorial' of https://github.com/skip2/nghttp2 into skip2-reword-client-tutorial
This commit is contained in:
commit
6a70f34c73
|
@ -1,25 +1,25 @@
|
|||
Tutorial: HTTP/2 client
|
||||
=========================
|
||||
|
||||
In this tutorial, we are going to write very primitive HTTP/2
|
||||
In this tutorial, we are going to write a very primitive HTTP/2
|
||||
client. The complete source code, `libevent-client.c`_, is attached at
|
||||
the end of this page. It also resides in examples directory in the
|
||||
archive or repository.
|
||||
the end of this page. It also resides in the examples directory in
|
||||
the archive or repository.
|
||||
|
||||
This simple client takes 1 argument, HTTPS URI, and retrieves the
|
||||
resource denoted by the URI. Its synopsis is like this::
|
||||
This simple client takes a single HTTPS URI and retrieves the resource
|
||||
at the URI. The synopsis is::
|
||||
|
||||
$ libevent-client HTTPS_URI
|
||||
|
||||
We use libevent in this tutorial to handle networking I/O. Please
|
||||
note that nghttp2 itself does not depend on libevent.
|
||||
|
||||
First we do some setup routine for libevent and OpenSSL library in
|
||||
function ``main()`` and ``run()``, which is not so relevant to nghttp2
|
||||
library use. The one thing you should look at is setup NPN callback.
|
||||
The NPN callback is used for the client to select the next application
|
||||
protocol over the SSL/TLS transport. In this tutorial, we use
|
||||
`nghttp2_select_next_protocol()` function to select the HTTP/2
|
||||
The client 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 client to select the next
|
||||
application protocol over TLS. In this tutorial, we use the
|
||||
`nghttp2_select_next_protocol()` helper function to select the HTTP/2
|
||||
protocol the library supports::
|
||||
|
||||
static int select_next_proto_cb(SSL *ssl _U_, unsigned char **out,
|
||||
|
@ -31,8 +31,8 @@ protocol the library supports::
|
|||
return SSL_TLSEXT_ERR_OK;
|
||||
}
|
||||
|
||||
The callback is set to the SSL_CTX object using
|
||||
``SSL_CTX_set_next_proto_select_cb()`` function::
|
||||
The callback is added to the SSL_CTX object using
|
||||
``SSL_CTX_set_next_proto_select_cb()``::
|
||||
|
||||
static SSL_CTX *create_ssl_ctx(void) {
|
||||
SSL_CTX *ssl_ctx;
|
||||
|
@ -49,8 +49,10 @@ The callback is set to the SSL_CTX object using
|
|||
return ssl_ctx;
|
||||
}
|
||||
|
||||
We use ``http2_session_data`` structure to store the data related to
|
||||
the HTTP/2 session::
|
||||
The example client defines a couple of structs:
|
||||
|
||||
We define and use a ``http2_session_data`` structure to store data
|
||||
related to the HTTP/2 session::
|
||||
|
||||
typedef struct {
|
||||
nghttp2_session *session;
|
||||
|
@ -59,10 +61,10 @@ the HTTP/2 session::
|
|||
http2_stream_data *stream_data;
|
||||
} http2_session_data;
|
||||
|
||||
Since this program only handles 1 URI, it uses only 1 stream. We store
|
||||
its stream specific data in ``http2_stream_data`` structure and the
|
||||
``stream_data`` points to it. The ``struct http2_stream_data`` is
|
||||
defined as follows::
|
||||
Since this program only handles one URI, it uses only one stream. We
|
||||
store the single stream's data in a ``http2_stream_data`` structure
|
||||
and the ``stream_data`` points to it. The ``http2_stream_data``
|
||||
structure is defined as follows::
|
||||
|
||||
typedef struct {
|
||||
/* The NULL-terminated URI string to retrieve. */
|
||||
|
@ -82,12 +84,12 @@ defined as follows::
|
|||
int32_t stream_id;
|
||||
} http2_stream_data;
|
||||
|
||||
We creates and initializes these structures in
|
||||
We create and initialize these structures in
|
||||
``create_http2_session_data()`` and ``create_http2_stream_data()``
|
||||
respectively.
|
||||
|
||||
Then we call function ``initiate_connection()`` to start connecting to
|
||||
the remote server::
|
||||
``initiate_connection()`` is called to start the connection to the
|
||||
remote server. It's defined as::
|
||||
|
||||
static void initiate_connection(struct event_base *evbase, SSL_CTX *ssl_ctx,
|
||||
const char *host, uint16_t port,
|
||||
|
@ -110,11 +112,11 @@ the remote server::
|
|||
session_data->bev = bev;
|
||||
}
|
||||
|
||||
We set 3 callbacks for the bufferevent: ``reacb``, ``writecb`` and
|
||||
``eventcb``.
|
||||
``initiate_connection()`` creates a bufferevent for the connection and
|
||||
sets up three callbacks: ``readcb``, ``writecb``, and ``eventcb``.
|
||||
|
||||
The ``eventcb()`` is invoked by libevent event loop when an event
|
||||
(e.g., connection has been established, timeout, etc) happens on the
|
||||
The ``eventcb()`` is invoked by the libevent event loop when an event
|
||||
(e.g. connection has been established, timeout, etc.) occurs on the
|
||||
underlying network socket::
|
||||
|
||||
static void eventcb(struct bufferevent *bev, short events, void *ptr) {
|
||||
|
@ -142,11 +144,15 @@ underlying network socket::
|
|||
delete_http2_session_data(session_data);
|
||||
}
|
||||
|
||||
For ``BEV_EVENT_EOF``, ``BEV_EVENT_ERROR`` and ``BEV_EVENT_TIMEOUT``
|
||||
event, we just simply tear down the connection. The
|
||||
``BEV_EVENT_CONNECTED`` event is invoked when SSL/TLS handshake is
|
||||
finished successfully. We first initialize nghttp2 session object in
|
||||
``initialize_nghttp2_session()`` function::
|
||||
For ``BEV_EVENT_EOF``, ``BEV_EVENT_ERROR``, and ``BEV_EVENT_TIMEOUT``
|
||||
events, we just simply tear down the connection.
|
||||
|
||||
The ``BEV_EVENT_CONNECTED`` event is invoked when the SSL/TLS
|
||||
handshake has completed successfully. After this we're 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;
|
||||
|
@ -175,18 +181,19 @@ finished successfully. We first initialize nghttp2 session object in
|
|||
nghttp2_session_callbacks_del(callbacks);
|
||||
}
|
||||
|
||||
Since we are creating client, we use `nghttp2_session_client_new()` to
|
||||
initialize nghttp2 session object. We setup 7 callbacks for the
|
||||
nghttp2 session. We'll explain these callbacks later.
|
||||
Since we are creating a client, we use `nghttp2_session_client_new()`
|
||||
to initialize the nghttp2 session object. The callbacks setup are
|
||||
explained later.
|
||||
|
||||
The `delete_http2_session_data()` destroys ``session_data`` and frees
|
||||
its bufferevent, so it closes underlying connection as well. It also
|
||||
calls `nghttp2_session_del()` to delete nghttp2 session object.
|
||||
The `delete_http2_session_data()` function destroys ``session_data``
|
||||
and frees its bufferevent, so the underlying connection is closed. It
|
||||
also calls `nghttp2_session_del()` to delete the nghttp2 session
|
||||
object.
|
||||
|
||||
We begin HTTP/2 communication by sending client connection preface,
|
||||
which is 24 bytes magic byte string (:macro:`NGHTTP2_CLIENT_MAGIC`)
|
||||
followed by SETTINGS frame. First 24 bytes magic string is
|
||||
automatically sent by nghttp2 library. We send SETTINGS frame in
|
||||
A HTTP/2 connection begins by sending the client connection preface,
|
||||
which is a 24 byte magic byte string (:macro:`NGHTTP2_CLIENT_MAGIC`),
|
||||
followed by a SETTINGS frame. The 24 byte magic string is sent
|
||||
automatically by nghttp2. We send the SETTINGS frame in
|
||||
``send_client_connection_header()``::
|
||||
|
||||
static void send_client_connection_header(http2_session_data *session_data) {
|
||||
|
@ -202,17 +209,17 @@ automatically sent by nghttp2 library. We send SETTINGS frame in
|
|||
}
|
||||
}
|
||||
|
||||
Here we specify SETTINGS_MAX_CONCURRENT_STREAMS to 100, which is
|
||||
really not needed for this tiny example program, but we are
|
||||
demonstrating the use of 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 not
|
||||
actually send it. All ``nghttp2_submit_*()`` family functions have
|
||||
this property. To actually send the frame, `nghttp2_session_send()` is
|
||||
used, which is described about later.
|
||||
Here we specify SETTINGS_MAX_CONCURRENT_STREAMS as 100. This is not
|
||||
needed for this tiny example program, it just demonstrates use of the
|
||||
SETTINGS frame. To queue the SETTINGS frame for transmission, we call
|
||||
`nghttp2_submit_settings()`. Note that `nghttp2_submit_settings()`
|
||||
only queues the frame for transmission, and doesn't actually send it.
|
||||
All ``nghttp2_submit_*()`` family functions have this property. To
|
||||
actually send the frame, `nghttp2_session_send()` has to be called,
|
||||
which is described (and called) later.
|
||||
|
||||
After the transmission of client connection header, we enqueue HTTP
|
||||
request in ``submit_request()`` function::
|
||||
After the transmission of the client connection header, we enqueue the
|
||||
HTTP request in the ``submit_request()`` function::
|
||||
|
||||
static void submit_request(http2_session_data *session_data) {
|
||||
int32_t stream_id;
|
||||
|
@ -236,17 +243,18 @@ request in ``submit_request()`` function::
|
|||
stream_data->stream_id = stream_id;
|
||||
}
|
||||
|
||||
We build HTTP request header fields in ``hdrs`` which is an array of
|
||||
:type:`nghttp2_nv`. There are 4 header fields to be sent: ``:method``,
|
||||
``:scheme``, ``:authority`` and ``:path``. To queue this HTTP request,
|
||||
we use `nghttp2_submit_request()` function. The `stream_data` is
|
||||
passed in *stream_user_data* parameter. It is used in nghttp2
|
||||
callbacks which we'll describe about later.
|
||||
We build the HTTP request header fields in ``hdrs``, which is an array
|
||||
of :type:`nghttp2_nv`. There are four header fields to be sent:
|
||||
``:method``, ``:scheme``, ``:authority``, and ``:path``. To queue the
|
||||
HTTP request, we call `nghttp2_submit_request()`. The ``stream_data``
|
||||
is passed via the *stream_user_data* parameter, which is helpfully
|
||||
later passed back to callback functions.
|
||||
|
||||
`nghttp2_submit_request()` returns the newly assigned stream ID for
|
||||
this request.
|
||||
the request.
|
||||
|
||||
The next bufferevent callback is ``readcb()``, which is invoked when
|
||||
data is available to read in the bufferevent input buffer::
|
||||
data is available to read from the bufferevent input buffer::
|
||||
|
||||
static void readcb(struct bufferevent *bev, void *ptr) {
|
||||
http2_session_data *session_data = (http2_session_data *)ptr;
|
||||
|
@ -272,12 +280,13 @@ data is available to read in the bufferevent input buffer::
|
|||
}
|
||||
}
|
||||
|
||||
In this function, we feed all unprocessed, received data to nghttp2
|
||||
session object using `nghttp2_session_mem_recv()` function. The
|
||||
In this function we feed all unprocessed, received data to the nghttp2
|
||||
session object using the `nghttp2_session_mem_recv()` function.
|
||||
`nghttp2_session_mem_recv()` processes the received data and may
|
||||
invoke nghttp2 callbacks and also queue frames. Since there may be
|
||||
pending frames, we call ``session_send()`` function to send those
|
||||
frames. The ``session_send()`` function is defined as follows::
|
||||
invoke nghttp2 callbacks and queue frames for transmission. Since
|
||||
there may be pending frames for transmission, we call immediately
|
||||
``session_send()`` to send them. ``session_send()`` is defined as
|
||||
follows::
|
||||
|
||||
static int session_send(http2_session_data *session_data) {
|
||||
int rv;
|
||||
|
@ -290,10 +299,10 @@ frames. The ``session_send()`` function is defined as follows::
|
|||
return 0;
|
||||
}
|
||||
|
||||
The `nghttp2_session_send()` function serializes the frame into wire
|
||||
format and call ``send_callback()`` function of type
|
||||
:type:`nghttp2_send_callback`. The ``send_callback()`` is defined as
|
||||
follows::
|
||||
The `nghttp2_session_send()` function serializes pending frames into
|
||||
wire format and calls the ``send_callback()`` function to send them.
|
||||
``send_callback()`` has type :type:`nghttp2_send_callback` and is
|
||||
defined as::
|
||||
|
||||
static ssize_t send_callback(nghttp2_session *session _U_, const uint8_t *data,
|
||||
size_t length, int flags _U_, void *user_data) {
|
||||
|
@ -306,18 +315,18 @@ 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 the non-blocking socket directly using ``write()`` system call
|
||||
in the ``send_callback()``, we will surely get ``EAGAIN`` or
|
||||
``EWOULDBLOCK`` 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 writing to the
|
||||
bufferevent, we have to regulate the amount data to be buffered by
|
||||
ourselves to avoid possible huge memory consumption. In this example
|
||||
client, we do not limit anything. To see how to regulate the amount of
|
||||
buffered data, see the ``send_callback()`` in the server tutorial.
|
||||
data to the non-blocking socket directly using the ``write()`` system
|
||||
call, 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. When writing to a bufferevent, you
|
||||
should regulate the amount of data written, to avoid possible huge
|
||||
memory consumption. In this example client however we don't implement
|
||||
a limit. To see how to regulate the amount of buffered data, see the
|
||||
``send_callback()`` in the server tutorial.
|
||||
|
||||
The third bufferevent callback is ``writecb()``, which is invoked when
|
||||
all data written in the bufferevent output buffer have been sent::
|
||||
all data written in the bufferevent output buffer has been sent::
|
||||
|
||||
static void writecb(struct bufferevent *bev _U_, void *ptr) {
|
||||
http2_session_data *session_data = (http2_session_data *)ptr;
|
||||
|
@ -329,25 +338,25 @@ all data written in the bufferevent output buffer have been sent::
|
|||
}
|
||||
|
||||
As described earlier, we just write off all data in `send_callback()`,
|
||||
we have no data to write in this function. All we have to do is check
|
||||
we have to drop connection or not. The nghttp2 session object keeps
|
||||
track of reception and transmission of GOAWAY frame and other error
|
||||
conditions as well. Using these information, nghttp2 session object
|
||||
will tell whether the connection should be dropped or not. More
|
||||
specifically, both `nghttp2_session_want_read()` and
|
||||
`nghttp2_session_want_write()` return 0, we have no business in the
|
||||
connection. But since we are using bufferevent and its deferred
|
||||
callback option, the bufferevent output buffer may contain the pending
|
||||
data when the ``writecb()`` is called. To handle this situation, we
|
||||
also check whether the output buffer is empty or not. If these
|
||||
conditions are met, we drop connection.
|
||||
so there is no data to write in this function. All we have to do is
|
||||
check if the connection should be dropped or not. The nghttp2 session
|
||||
object keeps track of reception and transmission of GOAWAY frames and
|
||||
other error conditions. Using this information, the nghttp2 session
|
||||
object can state whether the connection should be dropped or not.
|
||||
More specifically, when both `nghttp2_session_want_read()` and
|
||||
`nghttp2_session_want_write()` return 0, the connection is no-longer
|
||||
required and can be closed. Since we're using bufferevent and its
|
||||
deferred callback option, the bufferevent output buffer may still
|
||||
contain pending data when the ``writecb()`` is called. To handle this
|
||||
situation, we also check whether the output buffer is empty or not. If
|
||||
all of these conditions are met, then we drop the connection.
|
||||
|
||||
We have already described about nghttp2 callback ``send_callback()``.
|
||||
Let's describe remaining nghttp2 callbacks we setup in
|
||||
Now let's look at the remaining nghttp2 callbacks setup in the
|
||||
``initialize_nghttp2_setup()`` function.
|
||||
|
||||
Each request header name/value pair is emitted via
|
||||
``on_header_callback`` function::
|
||||
A server responds to the request by first sending a HEADERS frame.
|
||||
The HEADERS frame consists of response header name/value pairs, and
|
||||
the ``on_header_callback()`` is called for each name/value pair::
|
||||
|
||||
static int on_header_callback(nghttp2_session *session _U_,
|
||||
const nghttp2_frame *frame, const uint8_t *name,
|
||||
|
@ -367,10 +376,11 @@ Each request header name/value pair is emitted via
|
|||
return 0;
|
||||
}
|
||||
|
||||
In this tutorial, we just print the name/value pair.
|
||||
In this tutorial, we just print the name/value pairs on stdout.
|
||||
|
||||
After all name/value pairs are emitted for a frame,
|
||||
``on_frame_recv_callback`` function is called::
|
||||
After the HEADERS frame has been fully received (and thus all response
|
||||
header name/value pairs have been received), the
|
||||
``on_frame_recv_callback()`` function is called::
|
||||
|
||||
static int on_frame_recv_callback(nghttp2_session *session _U_,
|
||||
const nghttp2_frame *frame, void *user_data) {
|
||||
|
@ -386,13 +396,16 @@ After all name/value pairs are emitted for a frame,
|
|||
return 0;
|
||||
}
|
||||
|
||||
In this tutorial, we are just interested in the HTTP response
|
||||
HEADERS. We check the frame type and its category (it should be
|
||||
:macro:`NGHTTP2_HCAT_RESPONSE` for HTTP response HEADERS). Also check
|
||||
its stream ID.
|
||||
``on_frame_recv_callback()`` is called for other frame types too.
|
||||
|
||||
The ``on_data_chunk_recv_callback()`` function is invoked when a chunk
|
||||
of data is received from the remote peer::
|
||||
In this tutorial, we are just interested in the HTTP response HEADERS
|
||||
frame. We check the frame type and its category (it should be
|
||||
:macro:`NGHTTP2_HCAT_RESPONSE` for HTTP response HEADERS). We also
|
||||
check its stream ID.
|
||||
|
||||
Next, zero or more DATA frames can be received. The
|
||||
``on_data_chunk_recv_callback()`` function is invoked when a chunk of
|
||||
data is received from the remote peer::
|
||||
|
||||
static int on_data_chunk_recv_callback(nghttp2_session *session _U_,
|
||||
uint8_t flags _U_, int32_t stream_id,
|
||||
|
@ -405,10 +418,10 @@ of data is received from the remote peer::
|
|||
return 0;
|
||||
}
|
||||
|
||||
In our case, a chunk of data is response body. After checking stream
|
||||
ID, we just write the received data to the stdout. Note that the
|
||||
output in the terminal may be corrupted if the response body contains
|
||||
some binary data.
|
||||
In our case, a chunk of data is HTTP response body. After checking the
|
||||
stream ID, we just write the received data to stdout. Note the output
|
||||
in the terminal may be corrupted if the response body contains some
|
||||
binary data.
|
||||
|
||||
The ``on_stream_close_callback()`` function is invoked when the stream
|
||||
is about to close::
|
||||
|
@ -431,9 +444,9 @@ is about to close::
|
|||
}
|
||||
|
||||
If the stream ID matches the one we initiated, it means that its
|
||||
stream is going to be closed. Since we have finished to get the
|
||||
resource we want (or the stream was reset by RST_STREAM from the
|
||||
stream is going to be closed. Since we have finished receiving
|
||||
resource we wanted (or the stream was reset by RST_STREAM from the
|
||||
remote peer), we call `nghttp2_session_terminate_session()` to
|
||||
commencing the closure of the HTTP/2 session gracefully. If you have
|
||||
commence closure of the HTTP/2 session gracefully. If you have
|
||||
some data associated for the stream to be closed, you may delete it
|
||||
here.
|
||||
|
|
Loading…
Reference in New Issue