lsquic-tutorial
lsquic-tutorial copied to clipboard
lsquic tutorial teaches one how to build an application using lsquic, an open-source QUIC and HTTP/3 library
lsquic-tutorial
lsquic tutorial teaches one how to build an application using lsquic.
Description
The tutorial program, tut.c, contains client and server logic for a simple echo program. The client connects to the server and sends lines of text; the server reverses the lines of text and sends them back.
The tutorial program was written as an educational aid. Various aspects of the ways LSQUIC is used in it are considered in Netdev 0x14 slides. In addition to the slides, please refer to the LSQUIC API Reference.
tut.c contains several versions of reading and writing from stream to illustrate different ways of using the library. There are also two ways to send packets.
Building
To build the tutorial:
git submodule update --init --recursive
cmake .
make
This clones and builds BoringSSL, so it may take a few minutes.
Usage
All options
sh$ ./tut -h
Usage: tut [-c cert -k key] [options] IP port
-c cert.file Certificate.
-k key.file Key file.
-f log.file Log message to this log file. If not specified, the
are printed to stderr.
-L level Set library-wide log level. Defaults to 'warn'.
-l module=level Set log level of specific module. Several of these
can be specified via multiple -l flags or by combining
these with comma, e.g. -l event=debug,conn=info.
-v Verbose: log program messages as well.
-b VERSION Use callbacks version VERSION.
-p VERSION Use packets_out version VERSION.
-w VERSION Use server write callback version VERSION.
-o opt=val Set lsquic engine setting to some value, overriding the
defaults. For example,
-o version=ff00001c -o cc_algo=2
-G DIR Log TLS secrets to a file in directory DIR.
-h Print this help screen and exit.
Running the server
Both client and server logic are contained in the tut
program. It knows it is meant to run in the server
mode when -c
and -k
options are specified:
sh$ ./tut -c mycert-cert.pem -k mycert-key.pem ::0 12345 -p 1 -L debug -f server.log
The server can select one of two versions of "on stream write" callbacks. Use -w
command-line option for that.
Running the client
sh$ ./tut ::1 12345 -L debug -f client.log
Hello!
!olleH
^D
sh$
The server can select one of three versions of "on stream read" callbacks. Use -b
command-line option for that.
Both client and server can use the -p
option to select one of two "send packets out" callbacks.
HTTP/3 Client
As a bonus, a simple HTTP/3 client is provided. Example:
sh$ ./h3cli -M HEAD www.litespeedtech.com 443 /
HTTP/1.1 200 OK
x-powered-by: PHP/7.3.5
x-logged-in: False
x-content-powered-by: K2 v2.7.1 (by JoomlaWorks)
content-type: text/html; charset=utf-8
expires: Wed, 17 Aug 2005 00:00:00 GMT
last-modified: Wed, 12 Aug 2020 18:54:05 GMT
cache-control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
pragma: no-cache
etag: "23485-1597258445;gz"
vary: Accept-Encoding
x-frame-options: SAMEORIGIN
x-lsadc-cache: hit
date: Thu, 13 Aug 2020 02:48:06 GMT
server: LiteSpeed
Besides www.litespeedtech.com, other websites to try are www.facebook.com and www.google.com.
More Information
Latest QUIC and HTTP/3 GitHub artefacts can be found here. The QUIC IETF Working Group materials are here.
The LSQUIC GitHub Repo contains several more advanced examples, among them HTTP/3 client and server programs.