From 36fcb9aa01dcb51a8b706dbb7617d1552d54ce33 Mon Sep 17 00:00:00 2001 From: Dmitri Tikhonov Date: Fri, 21 Aug 2020 11:06:45 -0400 Subject: [PATCH] Finish LSQUIC Tutorial --- docs/index.rst | 28 +- docs/tutorial.rst | 1117 +++++++++++++++++++++++++++++++-- docs/wireshark-screenshot.png | Bin 0 -> 40852 bytes 3 files changed, 1084 insertions(+), 61 deletions(-) create mode 100644 docs/wireshark-screenshot.png diff --git a/docs/index.rst b/docs/index.rst index 4fd8c31..c1563ac 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,12 +16,38 @@ Most of the code in this distribution has been used in our own products -- `LiteSpeed Web Server`_, `LiteSpeed Web ADC`_, and OpenLiteSpeed_ -- since 2017. -Currently supported QUIC versions are Q043, Q046, Q050, ID-27, and ID-28. +Currently supported QUIC versions are Q043, Q046, Q050, ID-27, ID-28, +and ID-29. Support for newer versions will be added soon after they are released. LSQUIC is licensed under the `MIT License`_; see LICENSE in the source distribution for details. +Features +-------- + +LSQUIC supports nearly all QUIC and HTTP/3 features, including + +- DPLPMTUD +- ECN +- Spin bits (allowing network observer to calculate a connection's RTT) +- Path migration +- NAT rebinding +- Push promises +- TLS Key updates +- Extensions: + + - Loss bits extension (allowing network observer to locate source of packet loss) + - Timestamps extension (allowing for one-way delay calculation, improving performance of some congestion controllers) + - Delayed ACKs (this reduces number of ACK frames sent and processed, improving throughput) + - QUIC grease bit to reduce ossification opportunities + +Architecture +------------ + +The LSQUIC library does not use sockets to receive and send packets; that is handled by the user-supplied callbacks. The library also does not mandate the use of any particular event loop. Instead, it has functions to help the user schedule events. (Thus, using an event loop is not even strictly necessary.) The various callbacks and settings are supplied to the engine constructor. +LSQUIC keeps QUIC connections in several data structures in order to process them efficiently. Connections that need processing are kept in two priority queues: one holds connections that are ready to be processed (or "ticked") and the other orders connections by their next timer value. As a result, no connection is processed needlessly. + .. _LSQUIC: https://github.com/litespeedtech/lsquic .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php .. _`LiteSpeed Web Server`: https://www.litespeedtech.com/products/litespeed-web-server/ diff --git a/docs/tutorial.rst b/docs/tutorial.rst index e8e6c71..971d5d7 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -16,27 +16,30 @@ exposes several basic object types to operate upon: - connection; and - stream. -An engine manages connections, processes incoming packets, and schedules -outgoing packets. An engine operates in one of two modes: client or server. +Engine +------ -The LSQUIC library does not use sockets to receive and send packets; that is -handled by the user-supplied callbacks. The library also does not mandate -the use of any particular event loop. Instead, it has functions to help the -user schedule events. (Thus, using an event loop is not even strictly -necessary.) The various callbacks and settings are supplied to the engine -constructor. +An engine manages connections, processes incoming packets, and schedules outgoing packets. It can be instantiated in either server or client mode. If your program needs to have both QUIC client and server functionality, instantiate two engines. (This is what we do in our LiteSpeed ADC server.) +In addition, HTTP mode can be turned on for gQUIC and HTTP/3 support. -A connection carries one or more streams, ensures reliable data delivery, -and handles the protocol details. +Connection +---------- -A stream usually corresponds to a request/response pair: a client sends -its request over a single stream and a server sends its response back -using the same stream. This is the Google QUIC and HTTP/3 use case. -Nevertheless, the library does not limit one to this scenario. Any -application protocol can be implemented using LSQUIC -- as long as it -can be implemented using the QUIC transport protocol. The library provides -hooks for stream events: when a stream is created or closed, when it has -data to read or when it can be written to, and so on. +A connection carries one or more streams, ensures reliable data delivery, and handles the protocol details. +In client mode, a connection is created using a function call, which we will cover later in the tutorial. +In server mode, by the time the user code gets a hold of the connection object, the handshake has already been completed successfully. This is not the case in client mode. + +Stream +------ + +A connection can have several streams in parallel and many streams during its lifetime. +Streams do not exist by themselves; they belong to a connection. Streams are bidirectional and usually correspond to a request/response exchange - depending on the application protocol. +Application data is transmitted over streams. + +HTTP Mode +--------- + +The HTTP support is included directly into LSQUIC. The library hides the interaction between the HTTP application layer and the QUIC transport layer and presents a simple, unified way of sending and receiving HTTP messages. (By "unified way," I mean between Google QUIC and HTTP/3). Behind the scenes, the library will compress and decompress HTTP headers, add and remove HTTP/3 stream framing, and operate the necessary control streams. In the following sections, we will describe how to: @@ -48,12 +51,12 @@ In the following sections, we will describe how to: Include Files ------------- -A single include file, :file:`lsquic.h`, contains all the necessary -LSQUIC declarations: +In your source files, you need to include a single header, "lsquic.h". +It pulls in an auxiliary file "lsquic_types.h". :: - #include + #include "lsquic.h" Library Initialization ====================== @@ -69,6 +72,7 @@ initialized using :func:`lsquic_global_init()`: } /* OK, do something useful */ +This will initialize the crypto library, gQUIC server certificate cache, and, depending on the platform, monotonic timers. If you plan to instantiate engines only in a single mode, client or server, you can omit the appropriate flag. @@ -138,6 +142,34 @@ and streams, various timeout values, and so on. See :ref:`apiref-engine-settings` for full details. If ``ea_settings`` is set to ``NULL``, the engine will use the defaults, which should be OK. + +Receiving Packets +================= + +UDP datagrams are passed to the engine using the :func:`lsquic_engine_packet_in()` function. This is the only way to do so. +A pointer to the UDP payload is passed along with the size of the payload. +Local and peer socket addresses are passed in as well. +The void "peer ctx" pointer is associated with the peer address. It gets passed to the function that sends outgoing packets and to a few other callbacks. In a standard setup, this is most likely the socket file descriptor, but it could be pointing to something else. +The ECN value is in the range of 0 through 3, as in RFC 3168. + +:: + + /* 0: processed by real connection + * 1: handled + * -1: error: invalid arguments, malloc failure + */ + int + lsquic_engine_packet_in (lsquic_engine_t *, + const unsigned char *udp_payload, size_t sz, + const struct sockaddr *sa_local, + const struct sockaddr *sa_peer, + void *peer_ctx, int ecn); + +Why specify local address +------------------------- + +The local address is necessary because it becomes the source address of the outgoing packets. This is important in a multihomed configuration, when packets arriving at a socket can have different destination addresses. Changes in local and peer addresses are also used to detect changes in paths, such as path migration during the classic "parking lot" scenario or NAT rebinding. When path change is detected, QUIC connection performs special steps to validate the new path. + Sending Packets =============== @@ -172,51 +204,1016 @@ this: return (int) n; } -Note that the version above is very simple. :type:`lsquic_out_spec` -also specifies local address as well as ECN value. These are set -using ancillary data in a platform-dependent way. +Note that the version above is very simple: it does not use local +address and ECN value specified in :type:`lsquic_out_spec`. +These can be set using ancillary data in a platform-dependent way. -Receiving Packets -================= +When an error occurs +-------------------- -The user reads packets and provides them to an engine instance using -:func:`lsquic_engine_packet_in()`. +Errnos are examined: -*TODO* +- ``EAGAIN`` (or ``EWOULDBLOCK``) means that the packets could not be sent and to retry later. It is up to the caller to call :func:`lsquic_engine_send_unsent_packets()` when sending can resume. +- ``EMSGSIZE`` means that a packet was too large. This occurs when lsquic send MTU probes. In that case, the engine will retry sending without the offending packet immediately. +- Any other error causes the connection whose packet could not be sent to be terminated. -Running Connections -=================== - -A connection needs to be processed once in a while. It needs to be -processed when one of the following is true: - -- There are incoming packets; -- A stream is both readable by the user code and the user code wants - to read from it; -- A stream is both writeable by the user code and the user code wants - to write to it; -- User has written to stream outside of on_write() callbacks (that is - allowed) and now there are packets ready to be sent; -- A timer (pacer, retransmission, idle, etc) has expired; -- A control frame needs to be sent out; -- A stream needs to be serviced or created. - -Each of these use cases is handled by a single function, -:func:`lsquic_engine_process_conns()`. - -The connections to which the conditions above apply are processed (or -"ticked") in the least recently ticked order. After calling this function, -you can see when is the next time a connection needs to be processed using -:func:`lsquic_engine_earliest_adv_tick()`. - -Based on this value, next event can be scheduled (in the event loop of -your choice). +Outgoing Packet Specification +----------------------------- :: + struct lsquic_out_spec + { + struct iovec *iov; + size_t iovlen; + const struct sockaddr *local_sa; + const struct sockaddr *dest_sa; + void *peer_ctx; + int ecn; /* 0 - 3; see RFC 3168 */ + }; -Stream Reading and Writing -========================== -Reading from (or writing to) a stream is best down when that stream is -readable (or writeable). To register an interest in an event, +Each packet specification in the array given to the "packets out" function looks like this. In addition to the packet payload, specified via an iovec, the specification contains local and remote addresses, the peer context associated with the connection (which is just a file descriptor in tut.c), and ECN. +The reason for using iovec in the specification is that a UDP datagram may contain several QUIC packets. QUIC packets with long headers, which are used during QUIC handshake, can be coalesced and lsquic tries to do that to reduce the number of datagrams needed to be sent. On the incoming side, :func:`lsquic_engine_packet_in()` takes care of splitting incoming UDP datagrams into individual packets. + +When to process connections +=========================== + +Now that we covered how to initialize the library, instantiate an engine, and send and receive packets, it is time to see how to make the engine tick. "LSQUIC" has the concept of "tick," which is a way to describe a connection doing something productive. Other verbs could have been "kick," "prod," "poke," and so on, but we settled on "tick." + +There are several ways for a connection to do something productive. When a connection can do any of these things, it is "tickable:" + +- There are incoming packets to process +- A user wants to read from a stream and there is data that can be read +- A user wants to write to a stream and the stream is writeable +- A stream has buffered packets generated when user wrote to stream outside of the regular callback mechanism. (This is allowed as an optimization: sometimes data becomes available and it's faster to just write to stream than to buffer it in the user code and wait for the "on write" callback.) +- Internal QUIC protocol or LSQUIC maintenance action need to be taken, such as sending out a control frame or recycling a stream. + +:: + + /* Returns true if there are connections to be processed, in + * which case `diff' is set to microseconds from current time. + */ + int + lsquic_engine_earliest_adv_tick (lsquic_engine_t *, int *diff); + +There is a single function, +:func:`lsquic_engine_earliest_adv_tick()`, that can tell the user whether and when there is at least one connection managed by an engine that needs to be ticked. "Adv" in the name of the function stands for "advisory," meaning that you do not have to process connections at that exact moment; it is simply recommended. If there is a connection to be ticked, the function will return a true value and ``diff`` will be set to a relative time to when the connection is to be ticked. This value may be negative, which means that the best time to tick the connection has passed. +The engine keeps all connections in several data structures. It tracks each connection's timers and knows when it needs to fire. + +Example with libev +------------------ + +:: + + void + process_conns (struct tut *tut) + { + ev_tstamp timeout; + int diff; + ev_timer_stop(); + lsquic_engine_process_conns(engine); + if (lsquic_engine_earliest_adv_tick(engine, &diff) { + if (diff > 0) + timeout = (ev_tstamp) diff / 1000000; /* To seconds */ + else + timeout = 0.; + ev_timer_init(timeout) + ev_timer_start(); + } + } + +Here is a simple example that uses the libev library. First, we stop the timer and process connections. Then, we query the engine to tell us when the next advisory tick time is. Based on that, we calculate the timeout to reinitialize the timer with and start the timer. +If ``diff`` is negative, we set timeout to zero. +When the timer expires (not shown here), it simply calls this ``process_conns()`` again. + +Note that one could ignore the advisory tick time and simply process connections every few milliseconds and it will still work. This, however, will result in worse performance. + +Processing Connections +---------------------- + +Recap: +To process connections, call :func:`lsquic_engine_process_conns()`. +This will call necessary callbacks to read from and write to streams +and send packets out. Call `lsquic_engine_process_conns()` when advised +by `lsquic_engine_earliest_adv_tick()`. + +Do not call `lsquic_engine_process_conns()` from inside callbacks, for +this function is not reentrant. + +Another function that sends packets is +:func:`lsquic_engine_send_unsent_packets()`. Call it if there was a +previous failure to send out all packets + +Required Engine Callbacks +========================= + +Now we continue to initialize our engine instance. We have covered the callback to send out packets. This is one of the required engine callbacks. +Other required engine callbacks are a set of stream and connection callbacks that get called on various events in connections and stream lifecycles and a callback to get the default TLS context. + +:: + + struct lsquic_engine_api engine_api = { + /* --- 8< --- snip --- 8< --- */ + .ea_stream_if = &stream_callbacks, + .ea_stream_if_ctx = &some_context, + .ea_get_ssl_ctx = get_ssl_ctx, /* Server only */ + }; + + +Optional Callbacks +------------------ + +Here we mention some optional callbacks. While they are not covered by +this tutorial, it is good to know that they are available. + +- Looking up certificate and TLS context by SNI. +- Callbacks to control memory allocation for outgoing packets. These are useful when sending packets using a custom library. For example, when all packets must be in contiguous memory. +- Callbacks to observe connection ID lifecycle. These are useful in multi-process applications. +- Callbacks that provide access to a shared-memory hash. This is also used in multi-process applications. +- HTTP header set processing. These callbacks may be used in HTTP mode for HTTP/3 and Google QUIC. + +Please refer to :ref:`apiref-engine-settings` for details. + +Stream and connection callbacks +=============================== + +Stream and connection callbacks are the way that the library communicates with user code. Some of these callbacks are mandatory; others are optional. +They are all collected in :type:`lsquic_stream_if` ("if" here stands +for "interface"). +The mandatory callbacks include calls when connections and streams are created and destroyed and callbacks when streams can be read from or written to. +The optional callbacks are used to observe some events in connection lifecycle, such as being informed when handshake has succeeded (or failed) or when a goaway signal is received from peer. + +:: + + struct lsquic_stream_if + { + /* Mandatory callbacks: */ + lsquic_conn_ctx_t *(*on_new_conn)(void *stream_if_ctx, + lsquic_conn_t *c); + void (*on_conn_closed)(lsquic_conn_t *c); + lsquic_stream_ctx_t * + (*on_new_stream)(void *stream_if_ctx, lsquic_stream_t *s); + void (*on_read) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); + void (*on_write) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); + void (*on_close) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); + + /* Optional callbacks: */ + void (*on_goaway_received)(lsquic_conn_t *c); + void (*on_hsk_done)(lsquic_conn_t *c, enum lsquic_hsk_status s); + void (*on_new_token)(lsquic_conn_t *c, const unsigned char *token, + void (*on_sess_resume_info)(lsquic_conn_t *c, const unsigned char *, size_t); + }; + +On new connection +----------------- + +When a connection object is created, the "on new connection" callback is called. In server mode, the handshake is already known to have succeeded; in client mode, the connection object is created before the handshake is attempted. The client can tell when handshake succeeds or fails by relying on the optional "handshake is done" callback or the "on connection close" callback. + +:: + + /* Return pointer to per-connection context. OK to return NULL. */ + static lsquic_conn_ctx_t * + my_on_new_conn (void *ea_stream_if_ctx, lsquic_conn_t *conn) + { + struct some_context *ctx = ea_stream_if_ctx; + struct my_conn_ctx *my_ctx = my_ctx_new(ctx); + if (ctx->is_client) + /* Need a stream to send request */ + lsquic_conn_make_stream(conn); + return (void *) my_ctx; + } + +In the made-up example above, a new per-connection context is allocated and returned. This context is then associated with the connection and can be retrieved using a dedicated function. Note that it is OK to return a ``NULL`` pointer. +Note that in client mode, this is a good place to request that the connection make a new stream by calling :func:`lsquic_conn_make_stream()`. The connection will create a new stream when handshake succeeds. + +On new stream +------------- + +QUIC allows either endpoint to create streams and send and receive data on them. There are unidirectional and bidirectional streams. Thus, there are four stream types. In our tutorial, however, we use the familiar paradigm of the client sending requests to the server using bidirectional stream. + +On the server, new streams are created when client requests arrive. On the client, streams are created when possible after the user code requested stream creation by calling :func:`lsquic_conn_make_stream()`. + +:: + + /* Return pointer to per-connection context. OK to return NULL. */ + static lsquic_stream_ctx_t * + my_on_new_stream (void *ea_stream_if_ctx, lsquic_stream_t *stream) { + struct some_context *ctx = ea_stream_if_ctx; + /* Associate some data with this stream: */ + struct my_stream_ctx *stream_ctx + = my_stream_ctx_new(ea_stream_if_ctx); + stream_ctx->stream = stream; + if (ctx->is_client) + lsquic_stream_wantwrite(stream, 1); + return (void *) stream_ctx; + } + +In a pattern similar to the "on new connection" callback, a per-stream context can be created at this time. The function returns this context and other stream callbacks - "on read," "on write," and "on close" - will be passed a pointer to it. As before, it is OK to return ``NULL``. +You can register an interest in reading from or writing to the stream by using a "want read" or "want write" function. Alternatively, you can simply read or write; be prepared that this may fail and you have to try again in the "regular way." We talk about that next. + +On read +------- + +When the "on read" callback is called, there is data to be read from stream, end-of-stream has been reached, or there is an error. + +:: + + static void + my_on_read (lsquic_stream_t *stream, lsquic_stream_ctx_t *h) { + struct my_stream_ctx *my_stream_ctx = (void *) h; + unsigned char buf[BUFSZ]; + + ssize_t nr = lsquic_stream_read(stream, buf, sizeof(buf)); + /* Do something with the data.... */ + if (nr == 0) /* EOF */ { + lsquic_stream_shutdown(stream, 0); + lsquic_stream_wantwrite(stream, 1); /* Want to reply */ + } + } + +To read the data or to collect the error, call :func:`lsquic_stream_read`. If a negative value is returned, examine ``errno``. If it is not ``EWOULDBLOCK``, then an error has occurred, and you should close the stream. Here, an error means an application error, such as peer resetting the stream. A protocol error or an internal library error (such as memory allocation failure) lead to the connection being closed outright. +To reiterate, the "on read" callback is called only when the user registered interest in reading from the stream. + +On write +-------- + +The "on write" callback is called when the stream can be written to. At this point, you should be able to write at least a byte to the stream. +As with the "on read" callback, for this callback to be called, the user must have registered interest in writing to stream using :func:`lsquic_stream_wantwrite()`. + + +:: + + static void + my_on_write (lsquic_stream_t *stream, lsquic_stream_ctx_t *h) { + struct my_stream_ctx *my_stream_ctx = (void *) h; + ssize_t nw = lsquic_stream_write(stream, + my_stream_ctx->resp, my_stream_ctx->resp_sz); + if (nw == my_stream_ctx->resp_sz) + lsquic_stream_close(stream); + } + +By default, "on read" and "on write" callbacks will be called in a loop as long as there is data to read or the stream can be written to. If you are done reading from or writing to stream, you should either shutdown the appropriate end, close the stream, or unregister your interest. The library implements a circuit breaker to stop would-be infinite loops when no reading or writing progress is made. Both loop dispatch and the circuit breaker are configurable (see :member:`lsquic_engine_settings.es_progress_check` and :member:`lsquic_engine_settings.es_rw_once`). + +On stream close +--------------- + +When reading and writing ends of the stream have been closed, the "on close" callback is called. After this function returns, pointers to the stream become invalid. (The library destroys the stream object when it deems proper.) +This is a good place to perform necessary cleanup. + +:: + + static void + my_on_close (lsquic_stream_t *stream, lsquic_stream_ctx_t *h) { + lsquic_conn_t *conn = lsquic_stream_conn(stream); + struct my_conn_ctx *my_ctx = lsquic_conn_get_ctx(conn); + if (!has_more_reqs_to_send(my_ctx)) /* For example */ + lsquic_conn_close(conn); + free(h); + } + +In the made-up example above, we free the per-stream context allocated in the "on new stream" callback and we may close the connection. + +On connection close +------------------- + +When either :func:`lsquic_conn_close()` has been called; or the peer closed the connection; or an error occurred, the "on connection close" callback is called. At this point, it is time to free the per-connection context, if any. + +:: + + static void + my_on_conn_closed (lsquic_conn_t *conn) { + struct my_conn_ctx *my_ctx = lsquic_conn_get_ctx(conn); + struct some_context *ctx = my_ctx->some_context; + + --ctx->n_conns; + if (0 == ctx->n_conn && (ctx->flags & CLOSING)) + exit_event_loop(ctx); + + free(my_ctx); + } + +In the example above, you see the call to :func:`lsquic_conn_get_ctx()`. This returns the pointer returned by the "on new connection" callback. + +Using Streams +============= + +To reduce buffering, most of the time bytes written to stream are written into packets directly. Bytes are buffered in the stream until a full packet can be created. Alternatively, one call flush the data by calling :func:`lsquic_stream_flush`. +It is impossible to write more data than the congestion window. This prevents excessive buffering inside the library. +Inside the "on read" and "on write" callbacks, reading and writing should succeed. The exception is error collection inside the "on read" callback. +Outside of the callbacks, be ready to handle errors. For reading, it is -1 with ``EWOULDBLOCK`` errno. For writing, it is the return value of 0. + +More stream functions +--------------------- + +Here are a few more useful stream functions. + +:: + + /* Flush any buffered data. This triggers packetizing even a single + * byte into a separate frame. + */ + int + lsquic_stream_flush (lsquic_stream_t *); + + /* Possible values for how are 0, 1, and 2. See shutdown(2). */ + int + lsquic_stream_shutdown (lsquic_stream_t *, int how); + + int + lsquic_stream_close (lsquic_stream_t *); + +As mentioned before, calling :func:`lsquic_stream_flush()` will cause the stream to packetize the buffered data. Note that it may not happen immediately, as there may be higher-priority writes pending or there may not be sufficient congestion window to do so. Calling "flush" only schedules writing to packets. + +:func:`lsquic_stream_shutdown()` and :func:`lsquic_stream_close()` mimic the interface of the "shutdown" and "close" socket functions. After both read and write ends of a stream are closed, the "on stream close" callback will soon be called. + +Stream return values +-------------------- + +The stream read and write functions are modeled on the standard UNIX read and write functions, including the use of the ``errno``. The most important of these error codes are ``EWOULDBLOCK`` and ``ECONNRESET`` because you may encounter these even if you structure your code correctly. Other errors typically occur when the user code does something unexpected. + +Return value of 0 are different for reads and writes. For reads, it means that EOF has been reached and you need to stop reading from the stream. For writes, it means that you should try writing later. + +If writing to stream returns an error, it may mean an internal error. If the error is not recoverable, the library will abort the connection; if it is recoverable (the only recoverable error is failure to allocate memory), attempting to write later may succeed. + +Scatter/gather stream functions +------------------------------- + +There is the scatter/gather way to read from and write to stream and the interface is similar to the usual "readv" and "writev" functions. All return values and error codes are the same as in the stream read and write functions we have just discussed. Those are actually just wrappers around the scatter/gather versions. + +:: + + ssize_t + lsquic_stream_readv (lsquic_stream_t *, const struct iovec *, + int iovcnt); + ssize_t + lsquic_stream_writev (lsquic_stream_t *, const struct iovec *, + int count); + +Read using a callback +--------------------- + +The scatter/gather functions themselves are also wrappers. LSQUIC provides stream functions that skip intermediate buffering. They are used for zero-copy stream processing. + +:: + + ssize_t + lsquic_stream_readf (lsquic_stream_t *, + size_t (*readf)(void *ctx, const unsigned char *, size_t len, int fin), + void *ctx); + + +The second argument to :func:`lsquic_stream_readf()` is a callback that +returns the number of bytes processed. The callback is passed: + +- Pointer to user-supplied context; +- Pointer to the data; +- Data size (can be zero); and +- Indicator whether the FIN follows the data. + +If callback returns 0 or value smaller than `len`, reading stops. + +Read with callback: Example 1 +----------------------------- + +Here is the first example of reading from stream using a callback. Now the process of reading from stream +is split into two functions. + +:: + + static void + tut_client_on_read_v1 (lsquic_stream_t *stream, lsquic_stream_ctx_t *h) + { + struct tut *tut = (struct tut *) h; + size_t nread = lsquic_stream_readf(stream, tut_client_readf_v1, NULL); + if (nread == 0) + { + LOG("read to end-of-stream: close and read from stdin again"); + lsquic_stream_shutdown(stream, 0); + ev_io_start(tut->tut_loop, &tut->tut_u.c.stdin_w); + } + /* ... */ + } + +Here, we see the :func:`lsquic_stream_readf()` call. The return value is the same as the other read functions. +Because in this example there is no extra information to pass to the callback (we simply print data to stdout), +the third argument is NULL. + +:: + + static size_t + tut_client_readf_v1 (void *ctx, const unsigned char *data, + size_t len, int fin) + { + if (len) + { + fwrite(data, 1, len, stdout); + fflush(stdout); + } + return len; + } + +Here is the callback itself. You can see it is very simple. If there is data to be processed, +it is printed to stdout. + +Note that the data size (``len`` above) can be anything. It is not limited by UDP datagram size. This is because when incoming STREAM frames pass some fragmentation threshold, LSQUIC begins to copy incoming STREAM data to a data structure that is impervious to stream fragmentation attacks. Thus, it is possible for the callback to pass a pointer to data that is over 3KB in size. The implementation may change, so again, no guarantees. +When the fourth argument, ``fin``, is true, this indicates that the incoming data ends after ``len`` bytes have been read. + +Read with callback: Example 2: Use FIN +-------------------------------------- + +The FIN indicator passed to the callback gives us yet another way to detect end-of-stream. +The previous version checked the return value of :func:`lsquic_stream_readf()` to check for EOS. +Instead, we can use ``fin`` in the callback. + +The second zero-copy read example is a little more efficient as it saves us +an extra call to ``tut_client_on_read_v2``. +Here, we package pointers to the tut struct and stream into a special struct and pass it to +``lsquic_stream_readf()``. + +:: + + struct client_read_v2_ctx { struct tut *tut; lsquic_stream_t *stream; }; + + static void + tut_client_on_read_v2 (lsquic_stream_t *stream, + lsquic_stream_ctx_t *h) + { + struct tut *tut = (struct tut *) h; + struct client_read_v2_ctx v2ctx = { tut, stream, }; + ssize_t nread = lsquic_stream_readf(stream, tut_client_readf_v2, + &v2ctx); + if (nread < 0) + /* ERROR */ + } + +Now the callback becomes more complicated, as we moved the logic to stop reading from stream into it. We need pointer to both stream and user context when "fin" is true. In that case, we call :func:`lsquic_stream_shutdown()` and begin reading from stdin again to grab the next line of input. + +:: + + static size_t + tut_client_readf_v2 (void *ctx, const unsigned char *data, + size_t len, int fin) + { + struct client_read_v2_ctx *v2ctx = ctx; + if (len) + fwrite(data, 1, len, stdout); + if (fin) + { + fflush(stdout); + LOG("read to end-of-stream: close and read from stdin again"); + lsquic_stream_shutdown(v2ctx->stream, 0); + ev_io_start(v2ctx->tut->tut_loop, &v2ctx->tut->tut_u.c.stdin_w); + } + return len; + } + +Writing to stream: Example 1 +---------------------------- + +Now let's consider writing to stream. + +:: + + static void + tut_server_on_write_v0 (lsquic_stream_t *stream, lsquic_stream_ctx_t *h) + { + struct tut_server_stream_ctx *const tssc = (void *) h; + ssize_t nw = lsquic_stream_write(stream, + tssc->tssc_buf + tssc->tssc_off, tssc->tssc_sz - tssc->tssc_off); + if (nw > 0) + { + tssc->tssc_off += nw; + if (tssc->tssc_off == tssc->tssc_sz) + lsquic_stream_close(stream); + /* ... */ + } + +Here, we call :func:`lsquic_stream_write()` directly. If writing succeeds and we reached the +end of the buffer we wanted to write, we close the stream. + +Write using callbacks +--------------------- + +To write using a callback, we need to use :func:`lsquic_stream_writef()`. + +:: + + struct lsquic_reader { + /* Return number of bytes written to buf */ + size_t (*lsqr_read) (void *lsqr_ctx, void *buf, size_t count); + /* Return number of bytes remaining in the reader. */ + size_t (*lsqr_size) (void *lsqr_ctx); + void *lsqr_ctx; + }; + + /* Return umber of bytes written or -1 on error. */ + ssize_t + lsquic_stream_writef (lsquic_stream_t *, struct lsquic_reader *); + +We must specify not only the function that will perform the copy, but also the function that will return the number of bytes remaining. This is useful in situations where the size of the data source may change. For example, an underlying file may change size. +The :member:`lsquic_reader.lsqr_read` callback will be called in a loop until stream can write no more or until :member:`lsquic_reader.lsqr_size` returns zero. +The return value of ``lsquic_stream_writef`` is the same as :func:`lsquic_stream_write()` and :func:`lsquic_stream_writev()`, which are just wrappers around the "writef" version. + +Writing to stream: Example 2 +---------------------------- + +Here is the second version of the "on write" callback. It uses :func:`lsquic_stream_writef()`. + +:: + + static void + tut_server_on_write_v1 (lsquic_stream_t *stream, lsquic_stream_ctx_t *h) + { + struct tut_server_stream_ctx *const tssc = (void *) h; + struct lsquic_reader reader = { tssc_read, tssc_size, tssc, }; + ssize_t nw = lsquic_stream_writef(stream, &reader); + if (nw > 0 && tssc->tssc_off == tssc->tssc_sz) + lsquic_stream_close(stream); + /* ... */ + } + + +The reader struct is initialized with pointers to read and size functions and this struct is passed +to the "writef" function. + +:: + + static size_t + tssc_size (void *ctx) + { + struct tut_server_stream_ctx *tssc = ctx; + return tssc->tssc_sz - tssc->tssc_off; + } + + +The size callback simply returns the number of bytes left. + +:: + + static size_t + tssc_read (void *ctx, void *buf, size_t count) + { + struct tut_server_stream_ctx *tssc = ctx; + + if (count > tssc->tssc_sz - tssc->tssc_off) + count = tssc->tssc_sz - tssc->tssc_off; + memcpy(buf, tssc->tssc_buf + tssc->tssc_off, count); + tssc->tssc_off += count; + return count; + } + + +The read callback (so called because you *read* data from the source) writes no more that ``count`` bytes +to memory location pointed by "buf" and returns the number of bytes copied. +In our case, ``count`` is never larger than the number of bytes still left to write. +This is because the caller - the LSQUIC library - gets the value of ``count`` from the ``lsqr_size()`` callback. When reading from a file descriptor, on the other hand, this can very well happen that you don't have as much data to write as you thought you had. + +Client: making connection +========================= + +We now switch our attention to making a QUIC connection. The function :func:`lsquic_engine_connect()` does that. This function has twelve arguments. (These arguments have accreted over time.) + +:: + + lsquic_conn_t * + lsquic_engine_connect (lsquic_engine_t *, + enum lsquic_version, /* Set to N_LSQVER for default */ + const struct sockaddr *local_sa, + const struct sockaddr *peer_sa, + void *peer_ctx, + lsquic_conn_ctx_t *conn_ctx, + const char *hostname, /* Used for SNI */ + unsigned short base_plpmtu, /* 0 means default */ + const unsigned char *sess_resume, size_t sess_resume_len, + const unsigned char *token, size_t token_sz); + +- The first argument is the pointer to the engine instance. +- The second argument is the QUIC version to use. +- The third and fourth arguments specify local and destination addresses, respectively. +- The fifth argument is the so-called "peer context." +- The sixth argument is the connection context. This is used if you need to pass a pointer to the "on new connection" callback. This context is overwritten by the return value of the "on new connection" callback. +- The argument "hostname," which is the seventh argument, is used for SNI. This argument is optional, just as the rest of the arguments that follow. +- The eighth argument is the initial maximum size of the UDP payload. This will be the base PLPMTU if DPLPMTUD is enabled. Specifying zero, or default, is the safe way to go: lsquic will pick a good starting value. +- The next two arguments allow one to specify a session resumption information to establish a connection faster. In the case of IETF QUIC, this is the TLS Session Ticket. To get this ticket, specify the :member:`lsquic_stream_if.on_sess_resume_info` callback. +- The last pair of arguments is for specifying a token to try to prevent a potential stateless retry from the server. The token is learned in a previous session. See the optional callback :member:`lsquic_stream_if.on_new_token`. + +:: + + tut.tut_u.c.conn = lsquic_engine_connect( + tut.tut_engine, N_LSQVER, + (struct sockaddr *) &tut.tut_local_sas, &addr.sa, + (void *) (uintptr_t) tut.tut_sock_fd, /* Peer ctx */ + NULL, NULL, 0, NULL, 0, NULL, 0); + if (!tut.tut_u.c.conn) + { + LOG("cannot create connection"); + exit(EXIT_FAILURE); + } + tut_process_conns(&tut); + +Here is an example from a tutorial program. The connect call is a lot less intimidating in real life, as half the arguments are set to zero. +We pass a pointer to the engine instance, N_LSQVER to let the engine pick the version to use and the two socket addresses. +The peer context is simply the socket file descriptor cast to a pointer. +This is what is passed to the "send packets out" callback. + +Specifying QUIC version +======================= + +QUIC versions in LSQUIC are gathered in an enum, :type:`lsquic_version`, and have an arbitrary value. + +:: + + enum lsquic_version { + LSQVER_043, LSQVER_046, LSQVER_050, /* Google QUIC */ + LSQVER_ID27, LSQVER_ID28, LSQVER_ID29, /* IETF QUIC */ + /* ...some special entries skipped */ + N_LSQVER /* <====================== Special value */ + }; + +The special value "N_LSQVER" is used to let the engine pick the QUIC version. +It picks the latest non-experimental version, so in this case it picks ID-29. +(Experimental from the point of view of the library.) + +Because version enum values are small -- and that is by design -- a list of +versions can be passed around as bitmasks. + +:: + + /* This allows list of versions to be specified as bitmask: */ + es_versions = (1 << LSQVER_ID28) | (1 << LSQVER_ID29); + +This is done, for example, when +specifying list of versions to enable in engine settings using :member:`lsquic_engine_api.ea_versions`. +There are a couple of more places in the API where this technique is used. + +Server callbacks +================ + +The server requires SSL callbacks to be present. The basic required callback is :member:`lsquic_engine_api.ea_get_ssl_ctx`. It is used to get a pointer to an initialized ``SSL_CTX``. + +:: + + typedef struct ssl_ctx_st * (*lsquic_lookup_cert_f)( + void *lsquic_cert_lookup_ctx, const struct sockaddr *local, + const char *sni); + + struct lsquic_engine_api { + lsquic_lookup_cert_f ea_lookup_cert; + void *ea_cert_lu_ctx; + struct ssl_ctx_st * (*ea_get_ssl_ctx)(void *peer_ctx); + /* (Other members of the struct are not shown) */ + }; + +In case SNI is used, LSQUIC will call :member:`lsquic_engine_api.ea_lookup_cert`. +For example, SNI is required in HTTP/3. +In `our web server`_, each virtual host has its own SSL context. Note that besides the SNI string, the callback is also given the local socket address. This makes it possible to implement a flexible lookup mechanism. + +Engine settings +=============== + +Besides the engine API struct passed to the engine constructor, there is also an engine settings struct, :type:`lsquic_engine_settings`. :member:`lsquic_engine_api.ea_settings` in the engine API struct +can be pointed to a custom settings struct. By default, this pointer is ``NULL``. +In that case, the engine uses default settings. + +There are many settings, controlling everything from flow control windows to the number of times an "on read" callback can be called in a loop before it is deemed an infinite loop and the circuit breaker is tripped. To make changing default settings values easier, the library provides functions to initialize the settings struct to defaults and then to check these values for sanity. + +Settings helper functions +------------------------- + +:: + + /* Initialize `settings' to default values */ + void + lsquic_engine_init_settings (struct lsquic_engine_settings *, + /* Bitmask of LSENG_SERVER and LSENG_HTTP */ + unsigned lsquic_engine_flags); + + /* Check settings for errors, return 0 on success, -1 on failure. */ + int + lsquic_engine_check_settings (const struct lsquic_engine_settings *, + unsigned lsquic_engine_flags, + /* Optional, can be NULL: */ + char *err_buf, size_t err_buf_sz); + +The first function is :func:`lsquic_engine_init_settings()`, which does just that. +The second argument is a bitmask to specify whether the engine is in server mode +and whether HTTP mode is turned on. These should be the same flags as those +passed to the engine constructor. + +Once you have initialized the settings struct in this manner, change the setting +or settings you want and then call :func:`lsquic_engine_check_settings()`. The +first two arguments are the same as in the initializer. The third and fourth +argument are used to pass a pointer to a buffer into which a human-readable error +string can be placed. + +The checker function does only the basic sanity checks. If you really set out +to misconfigure LSQUIC, you can. On the bright side, each setting is clearly +documented (see :ref:`apiref-engine-settings`). Most settings are standalone; +when there is interplay between them, it is also documented. +Test before deploying! + +Settings example +---------------- + +The example is adapted from a tutorial program. Here, command-line options +are processed and appropriate options is set. The first time the ``-o`` +flag is encountered, the settings struct is initialized. Then the argument +is parsed to see which setting to alter. + +:: + + while (/* getopt */) + { + case 'o': /* For example: -o version=h3-27 -o cc_algo=2 */ + if (!settings_initialized) { + lsquic_engine_init_settings(&settings, + cert_file || key_file ? LSENG_SERVER : 0); + settings_initialized = 1; + } + /* ... */ + else if (0 == strncmp(optarg, "cc_algo=", val - optarg)) + settings.es_cc_algo = atoi(val); + /* ... */ + } + + /* Check settings */ + if (0 != lsquic_engine_check_settings(&settings, + tut.tut_flags & TUT_SERVER ? LSENG_SERVER : 0, + errbuf, sizeof(errbuf))) + { + LOG("invalid settings: %s", errbuf); + exit(EXIT_FAILURE); + } + + /* ... */ + eapi.ea_settings = &settings; + +After option processing is completed, the settings are checked. The error +buffer is used to log a configuration error. + +Finally, the settings struct is pointed to by the engine API struct before +the engine constructor is called. + +Logging +======= + +LSQUIC provides a simple logging interface using a single callback function. +By default, no messages are logged. This can be changed by calling :func:`lsquic_logger_init()`. +This will set a library-wide logger callback function. + +:: + + void lsquic_logger_init(const struct lsquic_logger_if *, + void *logger_ctx, enum lsquic_logger_timestamp_style); + + struct lsquic_logger_if { + int (*log_buf)(void *logger_ctx, const char *buf, size_t len); + }; + + enum lsquic_logger_timestamp_style { LLTS_NONE, LLTS_HHMMSSMS, + LLTS_YYYYMMDD_HHMMSSMS, LLTS_CHROMELIKE, LLTS_HHMMSSUS, + LLTS_YYYYMMDD_HHMMSSUS, N_LLTS }; + +You can instruct the library to generate a timestamp and include it as part of the message. +Several timestamp formats are available. Some display microseconds, some do not; some +display the date, some do not. One of the most useful formats is "chromelike," +which matches the somewhat weird timestamp format used by Chromium. This makes it easy to +compare the two logs side by side. + +There are eight log levels in LSQUIC: debug, info, notice, warning, error, alert, emerg, +and crit. +These correspond to the usual log levels. (For example, see ``syslog(3)``). Of these, only five are used: debug, info, notice, warning, and error. Usually, warning and error messages are printed when there is a bug in the library or something very unusual has occurred. Memory allocation failures might elicit a warning as well, to give the operator a heads up. + +LSQUIC possesses about 40 logging modules. Each module usually corresponds to a single piece +of functionality in the library. The exception is the "event" module, which logs events of note in many modules. +There are two functions to manipulate which log messages will be generated. + +:: + + /* Set log level for all modules */ + int + lsquic_set_log_level (const char *log_level); + + /* Set log level per module "event=debug" */ + int + lsquic_logger_lopt (const char *optarg); + +The first is :func:`lsquic_set_log_level()`. It sets the same log level for each module. +The second is :func:`lsquic_logger_lopt()`. This function takes a comma-separated list of name-value pairs. For example, "event=debug." + +Logging Example +--------------- + +The following example is adapted from a tutorial program. In the program, log messages +are written to a file handle. By default, this is the standard error. One can change +that by using the "-f" command-line option and specify the log file. + +:: + + static int + tut_log_buf (void *ctx, const char *buf, size_t len) { + FILE *out = ctx; + fwrite(buf, 1, len, out); + fflush(out); + return 0; + } + static const struct lsquic_logger_if logger_if = { tut_log_buf, }; + + lsquic_logger_init(&logger_if, s_log_fh, LLTS_HHMMSSUS); + + +``tut_log_buf()`` returns 0, but the truth is that the return value is ignored. +There is just nothing for the library to do when the user-supplied log function fails! + +:: + + case 'l': /* e.g. -l event=debug,cubic=info */ + if (0 != lsquic_logger_lopt(optarg)) { + fprintf(stderr, "error processing -l option\n"); + exit(EXIT_FAILURE); + } + break; + case 'L': /* e.g. -L debug */ + if (0 != lsquic_set_log_level(optarg)) { + fprintf(stderr, "error processing -L option\n"); + exit(EXIT_FAILURE); + } + break; + +Here you can see how we use ``-l`` and ``-L`` command-line options to call one of +the two log level functions. These functions can fail if the incorrect log level +or module name is passed. Both log level and module name are treated in case-insensitive manner. + +Sample log messages +------------------- + +When log messages are turned on, you may see something like this in your log file (timestamps and +log levels are elided for brevity): + +.. code-block:: text + + [QUIC:B508E8AA234E0421] event: generated STREAM frame: stream 0, offset: 0, size: 3, fin: 1 + [QUIC:B508E8AA234E0421-0] stream: flushed to or past required offset 3 + [QUIC:B508E8AA234E0421] event: sent packet 13, type Short, crypto: forw-secure, size 32, frame types: STREAM, ecn: 0, spin: 0; kp: 0, path: 0, flags: 9470472 + [QUIC:B508E8AA234E0421] event: packet in: 15, type: Short, size: 44; ecn: 0, spin: 0; path: 0 + [QUIC:B508E8AA234E0421] rechist: received 15 + [QUIC:B508E8AA234E0421] event: ACK frame in: [13-9] + [QUIC:B508E8AA234E0421] conn: about to process QUIC_FRAME_STREAM frame + [QUIC:B508E8AA234E0421] event: STREAM frame in: stream 0; offset 0; size 3; fin: 1 + [QUIC:B508E8AA234E0421-0] stream: received stream frame, offset 0x0, len 3; fin: 1 + [QUIC:B508E8AA234E0421-0] di: FIN set at 3 + +Here we see the connection ID, ``B508E8AA234E0421``, and logging for modules "event", "stream", "rechist" +(that stands for "receive history"), "conn", and "di" (the "data in" module). When the connection ID is +followed by a dash and that number, the number is the stream ID. Note that stream ID is logged not just +for the stream, but for some other modules as well. + +Key logging and Wireshark +========================= + +`Wireshark`_ supports IETF QUIC. The developers have been very good at keeping up with latest versions. +You will need version 3.3 of Wireshark to support Internet-Draft 29. Support for HTTP/3 is in progress. + +LSQUIC supports exporting TLS secrets. For that, you need to specify a set of function pointers via +:member:`lsquic_engine_api.ea_keylog_if`. + +:: + + /* Secrets are logged per connection. Interface to open file (handle), + * log lines, and close file. + */ + struct lsquic_keylog_if { + void * (*kli_open) (void *keylog_ctx, lsquic_conn_t *); + void (*kli_log_line) (void *handle, const char *line); + void (*kli_close) (void *handle); + }; + + struct lsquic_engine_api { + /* --- 8< --- snip --- 8< --- */ + const struct lsquic_keylog_if *ea_keylog_if; + void *ea_keylog_ctx; + }; + +There are three functions: one to open a file, one to write a line into the file, and one to close the file. The lines are not interpreted. +In the engine API struct, there are two members to set: one is the pointer to the struct with the function pointers, and the other is the context passed to "kli_open" function. + +Key logging example +------------------- + +:: + + static void * + keylog_open (void *ctx, lsquic_conn_t *conn) + { + const lsquic_cid_t *cid; + FILE *fh; + int sz; + unsigned i; + char id_str[MAX_CID_LEN * 2 + 1]; + char path[PATH_MAX]; + static const char b2c[16] = "0123456789ABCDEF"; + + cid = lsquic_conn_id(conn); + for (i = 0; i < cid->len; ++i) + { + id_str[i * 2 + 0] = b2c[ cid->idbuf[i] >> 4 ]; + id_str[i * 2 + 1] = b2c[ cid->idbuf[i] & 0xF ]; + } + id_str[i * 2] = '\0'; + sz = snprintf(path, sizeof(path), "/secret_dir/%s.keys", id_str); + if ((size_t) sz >= sizeof(path)) + { + LOG("WARN: %s: file too long", __func__); + return NULL; + } + fh = fopen(path, "wb"); + if (!fh) + LOG("WARN: could not open %s for writing: %s", path, strerror(errno)); + return fh; + } + + static void + keylog_log_line (void *handle, const char *line) + { + fputs(line, handle); + fputs("\n", handle); + fflush(handle); + } + + static void + keylog_close (void *handle) + { + fclose(handle); + } + +The function to open the file is passed the connection object. It can be used to generate a filename +based on the connection ID. +We see that the line logger simply writes the passed C string to the filehandle and appends a newline. + +Wireshark screenshot +-------------------- + +After jumping through those hoops, our reward is a decoded QUIC trace in Wireshark! + +.. image:: wireshark-screenshot.png + +Here, we highlighted the STREAM frame payload. +Other frames in view are ACK and TIMESTAMP frames. +In the top panel with the packet list, you can see that frames are listed after the packet number. +Another interesting item is the DCID. This stands for "Destination Connection ID," and you can +see that there are two different values there. This is because the two peers of the QUIC connection +place different connection IDs in the packets! + +Connection IDs +============== + +A QUIC connection has two sets of connection IDs: source connection IDs and destination connection IDs. The source connection IDs is what the peer uses to place in QUIC packets; the destination connection IDs is what this endpoint uses to include in the packets it sends to the peer. One's source CIDs is the other's destination CIDs and vice versa. +What interesting is that either side of the QUIC connection may change the DCID. Use CIDs with care. + +:: + + #define MAX_CID_LEN 20 + + typedef struct lsquic_cid + { + uint_fast8_t len; + union { + uint8_t buf[MAX_CID_LEN]; + uint64_t id; + } u_cid; + #define idbuf u_cid.buf + } lsquic_cid_t; + + #define LSQUIC_CIDS_EQ(a, b) ((a)->len == 8 ? \ + (b)->len == 8 && (a)->u_cid.id == (b)->u_cid.id : \ + (a)->len == (b)->len && 0 == memcmp((a)->idbuf, (b)->idbuf, (a)->len)) + +The LSQUIC representation of a CID is the struct above. The CID can be up to 20 bytes in length. +By default, LSQUIC uses 8-byte CIDs to speed up comparisons. + +Get this-and-that API +===================== + +Here are a few functions to get different LSQUIC objects from other objects. + +:: + + const lsquic_cid_t * + lsquic_conn_id (const lsquic_conn_t *); + + lsquic_conn_t * + lsquic_stream_conn (const lsquic_stream_t *); + + lsquic_engine_t * + lsquic_conn_get_engine (lsquic_conn_t *); + + int lsquic_conn_get_sockaddr (lsquic_conn_t *, + const struct sockaddr **local, const struct sockaddr **peer); + +The CID returned by :func:`lsquic_conn_id()` is that used for logging: server and client should return the same CID. As noted earlier, you should not rely on this value to identify a connection! +You can get a pointer to the connection from a stream and a pointer to the engine from a connection. +Calling :func:`lsquic_conn_get_sockaddr()` will point ``local`` and ``peer`` to the socket addressess of the current path. QUIC supports multiple paths during migration, but access to those paths has not been exposed via an API yet. This may change when or if QUIC adds true multipath support. + +.. _`our web server`: https://www.litespeedtech.com/products +.. _`Wireshark`: https://www.wireshark.org/ diff --git a/docs/wireshark-screenshot.png b/docs/wireshark-screenshot.png new file mode 100644 index 0000000000000000000000000000000000000000..350091a7c39edd124ce345a459ef3265bb5d3577 GIT binary patch literal 40852 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 literal 0 HcmV?d00001