APIs.txt revision 10c492f0 
1# Copyright (c) 2017 - 2018 LiteSpeed Technologies Inc.  See LICENSE.
2LSQUIC APIs
3===========
4
5LSQUIC exposes the following object types to the user:
6
7    - Engine Settings   (struct lsquic_engine_settings)
8    - Stream Interface  (struct lsquic_stream_if) 
9    - Engine API        (struct lsquic_engine_api)
10    - Engine
11    - Connection
12    - Stream
13
14The first three -- engine settings, engine APIs, and stream interface --
15are used to instantiate the engine.  After engine is instantiated, the
16user code need only concern itself with engine, connections, and streams.
17
18
19Engine Settings
20---------------
21
22Engine settings is the struct lsquic_engine_settings.  It contains various
23QUIC settings and LSQUIC parameters.  The usual way to use it is to initialize
24it to default values using lsquic_engine_init_settings(), modify any values
25if necessary, and pass it as parameter to lsquic_engine_new().
26
27QUIC settings are specified by the following members:
28
29    lsquic_engine_settings      QUIC
30    member                      parameter
31    ----------------------      ---------
32    es_cfcw                     CFCW
33    es_sfcw                     SFCW
34    es_max_streams_in           MIDS
35    es_ua                       UAID
36    es_versions                 VER
37    es_idle_conn_to             ICSL
38    es_silent_close             SCLS
39    es_support_srej             COPT/SREJ
40    es_support_nstp             COPT/NSTP
41    es_support_tcid0            TCID
42
43The following parameters affect run-time behavior:
44
45    es_rw_once                  Important: affects event dispatch
46    es_handshake_to
47    es_support_push
48    es_pace_packets
49
50Other noteworthy settings:
51
52    es_max_header_list_size
53    es_progress_check
54
55To be sure your settings are good (in other words, passing this struct won't
56trip up the engine constructor), use lsquic_engine_check_settings().
57
58
59Stream Interface
60----------------
61
62The stream interface, lsquic_stream_if, specifies callbacks LSQUIC engine
63will call for connections and streams.
64
65The following callbacks should be specified for connection:
66
67    on_new_conn             This is called when connection is created.
68
69    on_goaway_received      This function is called when we receive GOAWAY
70                            frame from peer.  This callback is optional.
71
72    on_conn_closed          Connection is closed: all streams have been
73                            destroyed.
74
75The streams have four callbacks:
76
77    on_new_stream           Stream has been created.
78
79    on_read                 Stream can be read from (see Events).
80
81    on_write                Stream can be written to (see Events).
82
83    on_close                Stream has been closed.
84
85For both connections and streams, the "on new" callback return value can
86be use to specify user-supplied data.  This data pointer is optional and
87can be NULL.  It can also refer to the same data for the connection and
88its streams.  "on close" callbacks should be used to free user-supplied
89data.
90
91
92Engine API
93----------
94
95The engine API, struct lsquic_engine_api, is a combination structure to
96make calling lsquic_engine_new() manageable.  It holds references to
97struct lsquic_engine_settings and struct lsquic_stream_if, as well as:
98
99    - Interface for sending outgoing packets, ea_packets_out
100    - Interface for allocating memory for outgoing packet buffers
101      (optional).
102
103ea_packets_out is a pointer to a function of type lsquic_packets_out_f.
104The engine calls this function when it is appropriate to send out packets
105for one or more connections, which it gives to the function in a batch.
106This batch is an array of struct lsquic_out_spec.
107
108
109Engine
110------
111
112The engine is instantiated using lsquic_engine_new().  The first parameter
113is a list flags and the second parameter is the reference to the engine
114api.  The engine settings are specified, they are copied; changing
115the setting after the engine has been created will not affect engine's
116behavior.  If the settings are not specified, the engine will use default
117settings created by lsquic_engine_init_settings().
118
119Once the engine is instantiated, there are four main ways to use it to
120drive QUIC connections:
121
122    1. Create a connection using lsquic_engine_connect().
123    2. Feed it incoming packets using lsquic_engine_packet_in() function.
124    3. Process connections using one of the connection queue functions
125       (see Connection Queues).
126    4. Accept outgoing packets for sending (and send them!) using
127       ea_packets_out callback.
128
129
130Connection Queues
131-----------------
132
133Each connection lives in one or more queues.  These are:
134
135    - "All" queue.  This is not really a queue, but rather a hash where
136      connections can be looked up by ID.  It is possible for a connection
137      to exist *outside* of this queue: this happens when the connection is
138      closed, but still has packets to send.  In this case, the connection
139      is present in
140    - Outgoing queue.  This queue contains connections which have packets
141      to send.  The connection in this queue are ordered by priority: the
142      connection that has gone longest without sending is first.
143    - Incoming queue.  This queue contains connections that have incoming
144      packets.
145    - Pending RW Events queue.  (See Connection Read-Write Events).
146    - Advisory Tick Time queue.  This queue is used when packet pacing is
147      turned on (see es_pace_packets option).
148
149Each of these queues can be processed by a specialized function.  They are,
150respectively:
151
152    - lsquic_engine_proc_all()
153    - lsquic_engine_send_unsent_packets()
154    - lsquic_engine_process_conns_with_incoming()
155    - lsquic_engine_process_conns_with_pend_rw()
156    - lsquic_engine_process_conns_to_tick()
157
158Processing, or "ticking," a connection removes it from Incoming, Pending
159RW Events, and Advisory Tick Time queues.  The connection gets placed
160onto these queues as necessary.
161
162A simple approach is to
163    - Read packets from socket, give it to the engine using
164      lsquic_engine_packet_in(), and call
165      lsquic_engine_process_conns_with_incoming(); and
166    - Call lsquic_engine_proc_all() every few dozen milliseconds.
167
168
169Connection
170----------
171
172A connection is created using lsquic_engine_connect().  When on_new_conn()
173is called, the client code should call lsquic_conn_make_stream() one or
174more times.  One new stream will be created for each one of those calls.
175
176Several auxiliary functions are available:
177
178    - lsquic_conn_id()
179    - lsquic_conn_going_away()
180    - lsquic_conn_get_peer_ctx()
181    - lsquic_conn_get_stream_by_id()
182    - lsquic_conn_get_ctx()
183
184
185Stream
186------
187
188LSQUIC stream hides QUIC and HTTP/2 framing complexities from the user.
189What it presents is a way to send HTTP headers and, optionally, body to
190peer.  On read side, the user gets what looks like HTTP/1.1 stream.
191
192Expected usage for client is to express the desire to write to stream
193using lsquic_stream_wantwrite() call.  Once on_write() is called:
194
195    1. Write headers using lsquic_stream_send_headers()
196    2. Optionally write payload body using of of lsquic_stream_write(),
197       lsquic_stream_writev(), or lsquic_stream_writef().
198
199That done, shutdown write side using lsquic_stream_shutdown(), unregister
200for write events and register for read events using lsquic_stream_wantread().
201
202Read and parse HTTP/1.1 stream from on_read() callback until end-of-stream
203or an error is encountered.
204
205Then unregister the read event and shutdown the read side.  The stream will
206be closed after that at some point and on_close() callback will be called,
207at which point resources can be freed.  (Internally, the stream object is
208not destroyed until either all the packets carrying its data are ACKed or
209the connection is destroyed).
210
211on_read() and on_write() callbacks are dispatched differently based on the
212value of es_rw_once:
213
214If es_rw_once is false, then the callbacks are dispatched in a loop until
215the user unregisters the event or the stream becomes unreadable (or
216unwriteable).
217
218If es_rw_once is true, on_read() and on_write() are called once "per tick".
219It is the up to the user to read and write enough data.
220
221
222Events
223------
224
225Stream events are persistent: once call lsquic_stream_wantwrite() or
226lsquic_stream_wantread(), the event stays active until turned off.
227
228Note that when an error is encountered (such as a stream reset), the
229stream becomes readable and writeable: this allows user code to collect
230the error.
231
232
233Versions
234--------
235
236QUIC version are listed in enum lsquic_version.  To specify a list of
237versions, they are usually placed in a bitmask, e.g. es_versions.
238
239
240Connection Read-Write Events
241----------------------------
242
243TODO.
244
245(Do not worry about it if you are not writing to streams outside
246of on_write() callback.)
247