lsquic.h revision 1bdb91d1
1/* Copyright (c) 2017 - 2020 LiteSpeed Technologies Inc.  See LICENSE. */
2#ifndef __LSQUIC_H__
3#define __LSQUIC_H__
4
5/**
6 * @file
7 * public API for using liblsquic is defined in this file.
8 *
9 */
10
11#include <stdarg.h>
12#include <lsquic_types.h>
13#ifndef WIN32
14#include <sys/uio.h>
15#include <time.h>
16#else
17#include <vc_compat.h>
18#endif
19
20struct sockaddr;
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26#define LSQUIC_MAJOR_VERSION 2
27#define LSQUIC_MINOR_VERSION 10
28#define LSQUIC_PATCH_VERSION 5
29
30/**
31 * Engine flags:
32 */
33
34/** Server mode */
35#define LSENG_SERVER (1 << 0)
36
37/** Treat stream 3 as headers stream and, in general, behave like the
38 *  regular QUIC.
39 */
40#define LSENG_HTTP  (1 << 1)
41
42#define LSENG_HTTP_SERVER (LSENG_SERVER|LSENG_HTTP)
43
44/**
45 * This is a list of QUIC versions that we know of.  List of supported
46 * versions is in LSQUIC_SUPPORTED_VERSIONS.
47 */
48enum lsquic_version
49{
50
51    /** Q035.  This is the first version to be supported by LSQUIC. */
52    /* Support for this version has been removed.  The comment remains to
53     * document the changes.
54     */
55
56    /*
57     * Q037.  This version is like Q035, except the way packet hashes are
58     * generated is different for clients and servers.  In addition, new
59     * option NSTP (no STOP_WAITING frames) is rumored to be supported at
60     * some point in the future.
61     */
62    /* Support for this version has been removed.  The comment remains to
63     * document the changes.
64     */
65
66    /*
67     * Q038.  Based on Q037, supports PADDING frames in the middle of packet
68     * and NSTP (no STOP_WAITING frames) option.
69     */
70    /* Support for this version has been removed.  The comment remains to
71     * document the changes.
72     */
73
74    /**
75     * Q039.  Switch to big endian.  Do not ack acks.  Send connection level
76     * WINDOW_UPDATE frame every 20 sent packets which do not contain
77     * retransmittable frames.
78     */
79    /* Support for this version has been removed.  The comment remains to
80     * document the changes.
81     */
82
83    /*
84     * Q041.  RST_STREAM, ACK and STREAM frames match IETF format.
85     */
86    /* Support for this version has been removed.  The comment remains to
87     * document the changes.
88     */
89
90    /*
91     * Q042.  Receiving overlapping stream data is allowed.
92     */
93    /* Support for this version has been removed.  The comment remains to
94     * document the changes.
95     */
96
97    /**
98     * Q043.  Support for processing PRIORITY frames.  Since this library
99     * has supported PRIORITY frames from the beginning, this version is
100     * exactly the same as LSQVER_042.
101     */
102    LSQVER_043,
103
104    /**
105     * Q044.  IETF-like packet headers are used.  Frames are the same as
106     * in Q043.  Server never includes CIDs in short packets.
107     */
108    /* Support for this version has been removed.  The comment remains to
109     * document the changes.
110     */
111
112    /**
113     * Q046.  Use IETF Draft-17 compatible packet headers.
114     */
115    LSQVER_046,
116
117    /**
118     * Q050.  Variable-length QUIC server connection IDs.  Use CRYPTO frames
119     * for handshake.  IETF header format matching invariants-06.  Packet
120     * number encryption.  Initial packets are obfuscated.
121     */
122    LSQVER_050,
123
124#if LSQUIC_USE_Q098
125    /**
126     * Q098.  This is a made-up, experimental version used to test version
127     * negotiation.  The choice of 98 is similar to Google's choice of 99
128     * as the "IETF" version.
129     */
130    LSQVER_098,
131#define LSQUIC_EXPERIMENTAL_Q098 (1 << LSQVER_098)
132#else
133#define LSQUIC_EXPERIMENTAL_Q098 0
134#endif
135
136    /**
137     * IETF QUIC Draft-24
138     */
139    LSQVER_ID24,
140
141    /**
142     * IETF QUIC Draft-25
143     */
144    LSQVER_ID25,
145
146    /**
147     * Special version to trigger version negotiation.
148     * [draft-ietf-quic-transport-11], Section 3.
149     */
150    LSQVER_VERNEG,
151
152    N_LSQVER
153};
154
155/**
156 * We currently support versions 43, 46, 50, and Draft-24
157 * @see lsquic_version
158 */
159#define LSQUIC_SUPPORTED_VERSIONS ((1 << N_LSQVER) - 1)
160
161/**
162 * List of versions in which the server never includes CID in short packets.
163 */
164#define LSQUIC_FORCED_TCID0_VERSIONS ((1 << LSQVER_046)|(1 << LSQVER_050))
165
166#define LSQUIC_EXPERIMENTAL_VERSIONS ( \
167                            (1 << LSQVER_VERNEG) | LSQUIC_EXPERIMENTAL_Q098)
168
169#define LSQUIC_DEPRECATED_VERSIONS 0
170
171#define LSQUIC_GQUIC_HEADER_VERSIONS (1 << LSQVER_043)
172
173#define LSQUIC_IETF_VERSIONS ((1 << LSQVER_ID24) | (1 << LSQVER_ID25) \
174                                                    | (1 << LSQVER_VERNEG))
175
176#define LSQUIC_IETF_DRAFT_VERSIONS ((1 << LSQVER_ID24) | (1 << LSQVER_ID25) \
177                                                    | (1 << LSQVER_VERNEG))
178
179enum lsquic_hsk_status
180{
181    /**
182     * The handshake failed.
183     */
184    LSQ_HSK_FAIL,
185    /**
186     * The handshake succeeded without 0-RTT.
187     */
188    LSQ_HSK_OK,
189    /**
190     * The handshake succeeded with 0-RTT.
191     */
192    LSQ_HSK_0RTT_OK,
193    /**
194     * The handshake failed because of 0-RTT (early data rejected).  Retry
195     * the connection without 0-RTT.
196     */
197    LSQ_HSK_0RTT_FAIL,
198};
199
200/**
201 * @struct lsquic_stream_if
202 * @brief The definition of callback functions call by lsquic_stream to
203 * process events.
204 *
205 */
206struct lsquic_stream_if {
207
208    /**
209     * Use @ref lsquic_conn_get_ctx to get back the context.  It is
210     * OK for this function to return NULL.
211     */
212    lsquic_conn_ctx_t *(*on_new_conn)(void *stream_if_ctx,
213                                                        lsquic_conn_t *c);
214
215    /** This is called when our side received GOAWAY frame.  After this,
216     *  new streams should not be created.  The callback is optional.
217     */
218    void (*on_goaway_received)(lsquic_conn_t *c);
219    void (*on_conn_closed)(lsquic_conn_t *c);
220
221    /** If you need to initiate a connection, call lsquic_conn_make_stream().
222     *  This will cause `on_new_stream' callback to be called when appropriate
223     *  (this operation is delayed when maximum number of outgoing streams is
224     *  reached).
225     *
226     *  After `on_close' is called, the stream is no longer accessible.
227     */
228    lsquic_stream_ctx_t *
229         (*on_new_stream)(void *stream_if_ctx, lsquic_stream_t *s);
230
231    void (*on_read)     (lsquic_stream_t *s, lsquic_stream_ctx_t *h);
232    void (*on_write)    (lsquic_stream_t *s, lsquic_stream_ctx_t *h);
233    void (*on_close)    (lsquic_stream_t *s, lsquic_stream_ctx_t *h);
234    /* This callback in only called in client mode */
235    /**
236     * When handshake is completed, this callback is called.  `ok' is set
237     * to true if handshake was successful; otherwise, `ok' is set to
238     * false.
239     *
240     * This callback is optional.
241     */
242    void (*on_hsk_done)(lsquic_conn_t *c, enum lsquic_hsk_status s);
243    /**
244     * When server sends a token in NEW_TOKEN frame, this callback is called.
245     * The callback is optional.
246     */
247    void (*on_new_token)(lsquic_conn_t *c, const unsigned char *token,
248                                                        size_t token_size);
249    /**
250     * This optional callback lets client record information needed to
251     * perform a zero-RTT handshake next time around.
252     */
253    void (*on_zero_rtt_info)(lsquic_conn_t *c, const unsigned char *, size_t);
254};
255
256struct ssl_ctx_st;
257struct ssl_st;
258
259/**
260 * QUIC engine in server role needs access to certificates.  This is
261 * accomplished by providing a callback and a context to the engine
262 * constructor.
263 */
264
265typedef struct ssl_ctx_st * (*lsquic_lookup_cert_f)(
266    void *lsquic_cert_lookup_ctx, const struct sockaddr *local, const char *sni);
267
268/**
269 * Minimum flow control window is set to 16 KB for both client and server.
270 * This means we can send up to this amount of data before handshake gets
271 * completed.
272 */
273#define      LSQUIC_MIN_FCW             (16 * 1024)
274
275/* Each LSQUIC_DF_* value corresponds to es_* entry in
276 * lsquic_engine_settings below.
277 */
278
279/**
280 * By default, deprecated and experimental versions are not included.
281 */
282#define LSQUIC_DF_VERSIONS         (LSQUIC_SUPPORTED_VERSIONS & \
283                                            ~LSQUIC_DEPRECATED_VERSIONS & \
284                                            ~LSQUIC_EXPERIMENTAL_VERSIONS)
285
286#define LSQUIC_DF_CFCW_SERVER      (3 * 1024 * 1024 / 2)
287#define LSQUIC_DF_CFCW_CLIENT      (15 * 1024 * 1024)
288#define LSQUIC_DF_SFCW_SERVER      (1 * 1024 * 1024)
289#define LSQUIC_DF_SFCW_CLIENT      (6 * 1024 * 1024)
290#define LSQUIC_DF_MAX_STREAMS_IN   100
291
292/* IQUIC uses different names for these: */
293#define LSQUIC_DF_INIT_MAX_DATA_SERVER LSQUIC_DF_CFCW_SERVER
294#define LSQUIC_DF_INIT_MAX_DATA_CLIENT LSQUIC_DF_CFCW_CLIENT
295#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_SERVER LSQUIC_DF_SFCW_SERVER
296#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_SERVER 0
297#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_CLIENT 0
298#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_CLIENT LSQUIC_DF_SFCW_CLIENT
299#define LSQUIC_DF_INIT_MAX_STREAMS_BIDI LSQUIC_DF_MAX_STREAMS_IN
300#define LSQUIC_DF_INIT_MAX_STREAMS_UNI_CLIENT 100
301#define LSQUIC_DF_INIT_MAX_STREAMS_UNI_SERVER 3
302/* XXX What's a good value here? */
303#define LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_CLIENT   (32 * 1024)
304#define LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER   (12 * 1024)
305
306/**
307 * Default idle connection time in seconds.
308 */
309#define LSQUIC_DF_IDLE_TIMEOUT 30
310
311/**
312 * Default ping period in seconds.
313 */
314#define LSQUIC_DF_PING_PERIOD 15
315
316/**
317 * Default handshake timeout in microseconds.
318 */
319#define LSQUIC_DF_HANDSHAKE_TO     (10 * 1000 * 1000)
320
321#define LSQUIC_DF_IDLE_CONN_TO     (LSQUIC_DF_IDLE_TIMEOUT * 1000 * 1000)
322#define LSQUIC_DF_SILENT_CLOSE     1
323
324/** Default value of maximum header list size.  If set to non-zero value,
325 *  SETTINGS_MAX_HEADER_LIST_SIZE will be sent to peer after handshake is
326 *  completed (assuming the peer supports this setting frame type).
327 */
328#define LSQUIC_DF_MAX_HEADER_LIST_SIZE 0
329
330/** Default value of UAID (user-agent ID). */
331#define LSQUIC_DF_UA               "LSQUIC"
332
333#define LSQUIC_DF_STTL               86400
334#define LSQUIC_DF_MAX_INCHOATE     (1 * 1000 * 1000)
335/** Do not use NSTP by default */
336#define LSQUIC_DF_SUPPORT_NSTP     0
337/** TODO: IETF QUIC clients do not support push */
338#define LSQUIC_DF_SUPPORT_PUSH         1
339#define LSQUIC_DF_SUPPORT_TCID0    1
340/** By default, LSQUIC ignores Public Reset packets. */
341#define LSQUIC_DF_HONOR_PRST       0
342
343/**
344 * By default, LSQUIC will not send Public Reset packets in response to
345 * packets that specify unknown connections.
346 */
347#define LSQUIC_DF_SEND_PRST        0
348
349/** By default, infinite loop checks are turned on */
350#define LSQUIC_DF_PROGRESS_CHECK    1000
351
352/** By default, read/write events are dispatched in a loop */
353#define LSQUIC_DF_RW_ONCE           0
354
355/** By default, the threshold is not enabled */
356#define LSQUIC_DF_PROC_TIME_THRESH  0
357
358/** By default, packets are paced */
359#define LSQUIC_DF_PACE_PACKETS      1
360
361/** Default clock granularity is 1000 microseconds */
362#define LSQUIC_DF_CLOCK_GRANULARITY      1000
363
364/** The default value is 8 for simplicity */
365#define LSQUIC_DF_SCID_LEN 8
366
367/** The default value is 60 CIDs per minute */
368#define LSQUIC_DF_SCID_ISS_RATE   60
369
370#define LSQUIC_DF_QPACK_DEC_MAX_BLOCKED 100
371#define LSQUIC_DF_QPACK_DEC_MAX_SIZE 4096
372#define LSQUIC_DF_QPACK_ENC_MAX_BLOCKED 100
373#define LSQUIC_DF_QPACK_ENC_MAX_SIZE 4096
374
375/** ECN is disabled by default */
376#define LSQUIC_DF_ECN 0
377
378/** Allow migration by default */
379#define LSQUIC_DF_ALLOW_MIGRATION 1
380
381/** Use QL loss bits by default */
382#define LSQUIC_DF_QL_BITS 2
383
384/** Turn spin bit on by default */
385#define LSQUIC_DF_SPIN 1
386
387/* 1: Cubic; 2: BBR */
388#define LSQUIC_DF_CC_ALGO 1
389
390struct lsquic_engine_settings {
391    /**
392     * This is a bit mask wherein each bit corresponds to a value in
393     * enum lsquic_version.  Client starts negotiating with the highest
394     * version and goes down.  Server supports either of the versions
395     * specified here.
396     *
397     * This setting applies to both Google and IETF QUIC.
398     *
399     * @see lsquic_version
400     */
401    unsigned        es_versions;
402
403    /**
404     * Initial default CFCW.
405     *
406     * In server mode, per-connection values may be set lower than
407     * this if resources are scarce.
408     *
409     * Do not set es_cfcw and es_sfcw lower than @ref LSQUIC_MIN_FCW.
410     *
411     * @see es_max_cfcw
412     */
413    unsigned        es_cfcw;
414
415    /**
416     * Initial default SFCW.
417     *
418     * In server mode, per-connection values may be set lower than
419     * this if resources are scarce.
420     *
421     * Do not set es_cfcw and es_sfcw lower than @ref LSQUIC_MIN_FCW.
422     *
423     * @see es_max_sfcw
424     */
425    unsigned        es_sfcw;
426
427    /**
428     * This value is used to specify maximum allowed value CFCW is allowed
429     * to reach due to window auto-tuning.  By default, this value is zero,
430     * which means that CFCW is not allowed to increase from its initial
431     * value.
432     *
433     * @see es_cfcw
434     */
435    unsigned        es_max_cfcw;
436
437    unsigned        es_max_sfcw;
438
439    /** MIDS */
440    unsigned        es_max_streams_in;
441
442    /**
443     * Handshake timeout in microseconds.
444     *
445     * For client, this can be set to an arbitrary value (zero turns the
446     * timeout off).
447     *
448     * For server, this value is limited to about 16 seconds.  Do not set
449     * it to zero.
450     */
451    unsigned long   es_handshake_to;
452
453    /** ICSL in microseconds; GQUIC only */
454    unsigned long   es_idle_conn_to;
455
456    /** SCLS (silent close) */
457    int             es_silent_close;
458
459    /**
460     * This corresponds to SETTINGS_MAX_HEADER_LIST_SIZE
461     * (RFC 7540, Section 6.5.2).  0 means no limit.  Defaults
462     * to @ref LSQUIC_DF_MAX_HEADER_LIST_SIZE.
463     */
464    unsigned        es_max_header_list_size;
465
466    /** UAID -- User-Agent ID.  Defaults to @ref LSQUIC_DF_UA. */
467    const char     *es_ua;
468
469    /**
470     * More parameters for server
471     */
472    uint64_t        es_sttl; /* SCFG TTL in seconds */
473
474    uint32_t        es_pdmd; /* One fixed value X509 */
475    uint32_t        es_aead; /* One fixed value AESG */
476    uint32_t        es_kexs; /* One fixed value C255 */
477
478    /* Maximum number of incoming connections in inchoate state.  This is
479     * only applicable in server mode.
480     */
481    unsigned        es_max_inchoate;
482
483    /**
484     * Setting this value to 0 means that
485     *
486     * For client:
487     *  a) we send a SETTINGS frame to indicate that we do not support server
488     *     push; and
489     *  b) All incoming pushed streams get reset immediately.
490     * (For maximum effect, set es_max_streams_in to 0.)
491     *
492     * For server:
493     *  lsquic_conn_push_stream() will return -1.
494     */
495    int             es_support_push;
496
497    /**
498     * If set to true value, the server will not include connection ID in
499     * outgoing packets if client's CHLO specifies TCID=0.
500     *
501     * For client, this means including TCID=0 into CHLO message.  Note that
502     * in this case, the engine tracks connections by the
503     * (source-addr, dest-addr) tuple, thereby making it necessary to create
504     * a socket for each connection.
505     *
506     * This option has no effect in Q046, as the server never includes
507     * CIDs in the short packets.
508     *
509     * The default is @ref LSQUIC_DF_SUPPORT_TCID0.
510     */
511    int             es_support_tcid0;
512
513    /**
514     * Q037 and higher support "No STOP_WAITING frame" mode.  When set, the
515     * client will send NSTP option in its Client Hello message and will not
516     * sent STOP_WAITING frames, while ignoring incoming STOP_WAITING frames,
517     * if any.  Note that if the version negotiation happens to downgrade the
518     * client below Q037, this mode will *not* be used.
519     *
520     * This option does not affect the server, as it must support NSTP mode
521     * if it was specified by the client.
522     */
523    int             es_support_nstp;
524
525    /**
526     * If set to true value, the library will drop connections when it
527     * receives corresponding Public Reset packet.  The default is to
528     * ignore these packets.
529     */
530    int             es_honor_prst;
531
532    /**
533     * If set to true value, the library will send Public Reset packets
534     * in response to incoming packets with unknown Connection IDs.
535     * The default is @ref LSQUIC_DF_SEND_PRST.
536     */
537    int             es_send_prst;
538
539    /**
540     * A non-zero value enables internal checks that identify suspected
541     * infinite loops in user @ref on_read and @ref on_write callbacks
542     * and break them.  An infinite loop may occur if user code keeps
543     * on performing the same operation without checking status, e.g.
544     * reading from a closed stream etc.
545     *
546     * The value of this parameter is as follows: should a callback return
547     * this number of times in a row without making progress (that is,
548     * reading, writing, or changing stream state), loop break will occur.
549     *
550     * The defaut value is @ref LSQUIC_DF_PROGRESS_CHECK.
551     */
552    unsigned        es_progress_check;
553
554    /**
555     * A non-zero value make stream dispatch its read-write events once
556     * per call.
557     *
558     * When zero, read and write events are dispatched until the stream
559     * is no longer readable or writeable, respectively, or until the
560     * user signals unwillingness to read or write using
561     * @ref lsquic_stream_wantread() or @ref lsquic_stream_wantwrite()
562     * or shuts down the stream.
563     *
564     * The default value is @ref LSQUIC_DF_RW_ONCE.
565     */
566    int             es_rw_once;
567
568    /**
569     * If set, this value specifies that number of microseconds that
570     * @ref lsquic_engine_process_conns() and
571     * @ref lsquic_engine_send_unsent_packets() are allowed to spend
572     * before returning.
573     *
574     * This is not an exact science and the connections must make
575     * progress, so the deadline is checked after all connections get
576     * a chance to tick (in the case of @ref lsquic_engine_process_conns())
577     * and at least one batch of packets is sent out.
578     *
579     * When processing function runs out of its time slice, immediate
580     * calls to @ref lsquic_engine_has_unsent_packets() return false.
581     *
582     * The default value is @ref LSQUIC_DF_PROC_TIME_THRESH.
583     */
584    unsigned        es_proc_time_thresh;
585
586    /**
587     * If set to true, packet pacing is implemented per connection.
588     *
589     * The default value is @ref LSQUIC_DF_PACE_PACKETS.
590     */
591    int             es_pace_packets;
592
593    /**
594     * Clock granularity information is used by the pacer.  The value
595     * is in microseconds; default is @ref LSQUIC_DF_CLOCK_GRANULARITY.
596     */
597    unsigned        es_clock_granularity;
598
599    /* The following settings are specific to IETF QUIC. */
600    /* vvvvvvvvvvv */
601
602    /**
603     * Initial max data.
604     *
605     * This is a transport parameter.
606     *
607     * Depending on the engine mode, the default value is either
608     * @ref LSQUIC_DF_INIT_MAX_DATA_CLIENT or
609     * @ref LSQUIC_DF_INIT_MAX_DATA_SERVER.
610     */
611    unsigned        es_init_max_data;
612
613    /**
614     * Initial max stream data.
615     *
616     * This is a transport parameter.
617     *
618     * Depending on the engine mode, the default value is either
619     * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_CLIENT or
620     * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_SERVER.
621     */
622    unsigned        es_init_max_stream_data_bidi_remote;
623    unsigned        es_init_max_stream_data_bidi_local;
624
625    /**
626     * Initial max stream data for unidirectional streams initiated
627     * by remote endpoint.
628     *
629     * This is a transport parameter.
630     *
631     * Depending on the engine mode, the default value is either
632     * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_CLIENT or
633     * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER.
634     */
635    unsigned        es_init_max_stream_data_uni;
636
637    /**
638     * Maximum initial number of bidirectional stream.
639     *
640     * This is a transport parameter.
641     *
642     * Default value is @ref LSQUIC_DF_INIT_MAX_STREAMS_BIDI.
643     */
644    unsigned        es_init_max_streams_bidi;
645
646    /**
647     * Maximum initial number of unidirectional stream.
648     *
649     * This is a transport parameter.
650     *
651     * Default value is @ref LSQUIC_DF_INIT_MAX_STREAMS_UNI_CLIENT or
652     * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER.
653     */
654    unsigned        es_init_max_streams_uni;
655
656    /**
657     * Idle connection timeout.
658     *
659     * This is a transport parameter.
660     *
661     * (Note: es_idle_conn_to is not reused because it is in microseconds,
662     * which, I now realize, was not a good choice.  Since it will be
663     * obsoleted some time after the switchover to IETF QUIC, we do not
664     * have to keep on using strange units.)
665     *
666     * Default value is @ref LSQUIC_DF_IDLE_TIMEOUT.
667     *
668     * Maximum value is 600 seconds.
669     */
670    unsigned        es_idle_timeout;
671
672    /**
673     * Ping period.  If set to non-zero value, the connection will generate and
674     * send PING frames in the absence of other activity.
675     *
676     * By default, the server does not send PINGs and the period is set to zero.
677     * The client's defaut value is @ref LSQUIC_DF_PING_PERIOD.
678     */
679    unsigned        es_ping_period;
680
681    /**
682     * Source Connection ID length.  Only applicable to the IETF QUIC
683     * versions.  Valid values are 0 through 20, inclusive.
684     *
685     * Default value is @ref LSQUIC_DF_SCID_LEN.
686     */
687    unsigned        es_scid_len;
688
689    /**
690     * Source Connection ID issuance rate.  Only applicable to the IETF QUIC
691     * versions.  This field is measured in CIDs per minute.  Using value 0
692     * indicates that there is no rate limit for CID issuance.
693     *
694     * Default value is @ref LSQUIC_DF_SCID_ISS_RATE.
695     */
696    unsigned        es_scid_iss_rate;
697
698    /**
699     * Maximum size of the QPACK dynamic table that the QPACK decoder will
700     * use.
701     *
702     * The default is @ref LSQUIC_DF_QPACK_DEC_MAX_SIZE.
703     */
704    unsigned        es_qpack_dec_max_size;
705
706    /**
707     * Maximum number of blocked streams that the QPACK decoder is willing
708     * to tolerate.
709     *
710     * The default is @ref LSQUIC_DF_QPACK_DEC_MAX_BLOCKED.
711     */
712    unsigned        es_qpack_dec_max_blocked;
713
714    /**
715     * Maximum size of the dynamic table that the encoder is willing to use.
716     * The actual size of the dynamic table will not exceed the minimum of
717     * this value and the value advertized by peer.
718     *
719     * The default is @ref LSQUIC_DF_QPACK_ENC_MAX_SIZE.
720     */
721    unsigned        es_qpack_enc_max_size;
722
723    /**
724     * Maximum number of blocked streams that the QPACK encoder is willing
725     * to risk.  The actual number of blocked streams will not exceed the
726     * minimum of this value and the value advertized by peer.
727     *
728     * The default is @ref LSQUIC_DF_QPACK_ENC_MAX_BLOCKED.
729     */
730    unsigned        es_qpack_enc_max_blocked;
731
732    /**
733     * Enable ECN support.
734     *
735     * The default is @ref LSQUIC_DF_ECN
736     */
737    int             es_ecn;
738
739    /**
740     * Allow peer to migrate connection.
741     *
742     * The default is @ref LSQUIC_DF_ALLOW_MIGRATION
743     */
744    int             es_allow_migration;
745
746    /**
747     * Congestion control algorithm to use.
748     *
749     *  0:  Use default (@ref LSQUIC_DF_CC_ALGO)
750     *  1:  Cubic
751     *  2:  BBR
752     */
753    unsigned        es_cc_algo;
754
755    /**
756     * Use QL loss bits.  Allowed values are:
757     *  0:  Do not use loss bits
758     *  1:  Allow loss bits
759     *  2:  Allow and send loss bits
760     *
761     * Default value is @ref LSQUIC_DF_QL_BITS
762     */
763    int             es_ql_bits;
764
765    /**
766     * Enable spin bit.  Allowed values are 0 and 1.
767     *
768     * Default value is @ref LSQUIC_DF_SPIN
769     */
770    int             es_spin;
771};
772
773/* Initialize `settings' to default values */
774void
775lsquic_engine_init_settings (struct lsquic_engine_settings *,
776                             unsigned lsquic_engine_flags);
777
778/**
779 * Check settings for errors.
780 *
781 * @param   settings    Settings struct.
782 *
783 * @param   flags       Engine flags.
784 *
785 * @param   err_buf     Optional pointer to buffer into which error string
786 *                      is written.
787
788 * @param   err_buf_sz  Size of err_buf.  No more than this number of bytes
789 *                      will be written to err_buf, including the NUL byte.
790 *
791 * @retval  0   Settings have no errors.
792 * @retval -1   There are errors in settings.
793 */
794int
795lsquic_engine_check_settings (const struct lsquic_engine_settings *settings,
796                              unsigned lsquic_engine_flags,
797                              char *err_buf, size_t err_buf_sz);
798
799struct lsquic_out_spec
800{
801    struct iovec          *iov;
802    size_t                 iovlen;
803    const struct sockaddr *local_sa;
804    const struct sockaddr *dest_sa;
805    void                  *peer_ctx;
806    int                    ecn; /* Valid values are 0 - 3.  See RFC 3168 */
807};
808
809/**
810 * Returns number of packets successfully sent out or -1 on error.  -1 should
811 * only be returned if no packets were sent out.  If -1 is returned or if the
812 * return value is smaller than `n_packets_out', this indicates that sending
813 * of packets is not possible.
814 *
815 * If not all packets could be sent out, errno is examined.  If it is not
816 * EAGAIN or EWOULDBLOCK, the connection whose packet cause the error is
817 * closed forthwith.
818 *
819 * No packets will be attempted to be sent out until
820 * @ref lsquic_engine_send_unsent_packets() is called.
821 */
822typedef int (*lsquic_packets_out_f)(
823    void                          *packets_out_ctx,
824    const struct lsquic_out_spec  *out_spec,
825    unsigned                       n_packets_out
826);
827
828/**
829 * The shared hash interface is used to share data between multiple LSQUIC
830 * instances.
831 */
832struct lsquic_shared_hash_if
833{
834    /**
835     * If you want your item to never expire, set `expiry' to zero.
836     * Returns 0 on success, -1 on failure.
837     *
838     * If inserted successfully, `free()' will be called on `data' and 'key'
839     * pointer when the element is deleted, whether due to expiration
840     * or explicit deletion.
841     */
842    int (*shi_insert)(void *shi_ctx, void *key, unsigned key_sz,
843                      void *data, unsigned data_sz, time_t expiry);
844    /**
845     * Returns 0 on success, -1 on failure.
846     */
847    int (*shi_delete)(void *shi_ctx, const void *key, unsigned key_sz);
848
849    /**
850     * `data' is pointed to the result and `data_sz' is set to the
851     * object size.  The implementation may choose to copy the object
852     * into buffer pointed to by `data', so you should have it ready.
853     *
854     * @retval  1   found.
855     * @retval  0   not found.
856     * @retval -1   error (perhaps not enough room in `data' if copy was
857     *                attempted).
858     */
859    int (*shi_lookup)(void *shi_ctx, const void *key, unsigned key_sz,
860                                     void **data, unsigned *data_sz);
861};
862
863/**
864 * The packet out memory interface is used by LSQUIC to get buffers to
865 * which outgoing packets will be written before they are passed to
866 * ea_packets_out callback.
867 *
868 * If not specified, malloc() and free() are used.
869 */
870struct lsquic_packout_mem_if
871{
872    /**
873     * Allocate buffer for sending.
874     */
875    void *  (*pmi_allocate) (void *pmi_ctx, void *conn_ctx, unsigned short sz,
876                                                                char is_ipv6);
877    /**
878     * This function is used to release the allocated buffer after it is
879     * sent via @ref ea_packets_out.
880     */
881    void    (*pmi_release)  (void *pmi_ctx, void *conn_ctx, void *buf,
882                                                                char is_ipv6);
883    /**
884     * If allocated buffer is not going to be sent, return it to the caller
885     * using this function.
886     */
887    void    (*pmi_return)  (void *pmi_ctx, void *conn_ctx, void *buf,
888                                                                char is_ipv6);
889};
890
891typedef void (*lsquic_cids_update_f)(void *ctx, void **peer_ctx,
892                                const lsquic_cid_t *cids, unsigned n_cids);
893
894struct stack_st_X509;
895
896/**
897 * When headers are processed, various errors may occur.  They are listed
898 * in this enum.
899 */
900enum lsquic_header_status
901{
902    LSQUIC_HDR_OK,
903    /** Duplicate pseudo-header */
904    LSQUIC_HDR_ERR_DUPLICATE_PSDO_HDR,
905    /** Not all request pseudo-headers are present */
906    LSQUIC_HDR_ERR_INCOMPL_REQ_PSDO_HDR,
907    /** Unnecessary request pseudo-header present in the response */
908    LSQUIC_HDR_ERR_UNNEC_REQ_PSDO_HDR,
909    /** Prohibited header in request */
910    LSQUIC_HDR_ERR_BAD_REQ_HEADER,
911    /** Not all response pseudo-headers are present */
912    LSQUIC_HDR_ERR_INCOMPL_RESP_PSDO_HDR,
913    /** Unnecessary response pseudo-header present in the response. */
914    LSQUIC_HDR_ERR_UNNEC_RESP_PSDO_HDR,
915    /** Unknown pseudo-header */
916    LSQUIC_HDR_ERR_UNKNOWN_PSDO_HDR,
917    /** Uppercase letter in header */
918    LSQUIC_HDR_ERR_UPPERCASE_HEADER,
919    /** Misplaced pseudo-header */
920    LSQUIC_HDR_ERR_MISPLACED_PSDO_HDR,
921    /** Missing pseudo-header */
922    LSQUIC_HDR_ERR_MISSING_PSDO_HDR,
923    /** Header or headers are too large */
924    LSQUIC_HDR_ERR_HEADERS_TOO_LARGE,
925    /** Cannot allocate any more memory. */
926    LSQUIC_HDR_ERR_NOMEM,
927};
928
929struct lsquic_hset_if
930{
931    /**
932     * Create a new header set.  This object is (and must be) fetched from a
933     * stream by calling @ref lsquic_stream_get_hset() before the stream can
934     * be read.
935     */
936    void *              (*hsi_create_header_set)(void *hsi_ctx,
937                                                        int is_push_promise);
938    /**
939     * Process new header.  Return 0 on success, -1 if there is a problem with
940     * the header.  -1 is treated as a stream error: the associated stream is
941     * reset.
942     *
943     * `hdr_set' is the header set object returned by
944     * @ref hsi_create_header_set().
945     *
946     * `name_idx' is set to the index in either the HPACK or QPACK static table
947     * whose entry's name element matches `name'.  The values are as follows:
948     *      - if there is no such match, `name_idx' is set to zero;
949     *      - if HPACK is used, the value is between 1 and 61; and
950     *      - if QPACK is used, the value is 62+ (subtract 62 to get the QPACK
951     *        static table index).
952     *
953     * If `name' is NULL, this means that no more header are going to be
954     * added to the set.
955     */
956    enum lsquic_header_status (*hsi_process_header)(void *hdr_set,
957                                    unsigned name_idx,
958                                    const char *name, unsigned name_len,
959                                    const char *value, unsigned value_len);
960    /**
961     * Discard header set.  This is called for unclaimed header sets and
962     * header sets that had an error.
963     */
964    void                (*hsi_discard_header_set)(void *hdr_set);
965};
966
967/**
968 * SSL keylog interface.
969 */
970struct lsquic_keylog_if
971{
972    /** Return keylog handle or NULL if no key logging is desired */
973    void *    (*kli_open) (void *keylog_ctx, lsquic_conn_t *);
974
975    /**
976     * Log line.  The first argument is the pointer returned by
977     * @ref kli_open.
978     */
979    void      (*kli_log_line) (void *handle, const char *line);
980
981    /**
982     * Close handle.
983     */
984    void      (*kli_close) (void *handle);
985};
986
987/* TODO: describe this important data structure */
988typedef struct lsquic_engine_api
989{
990    const struct lsquic_engine_settings *ea_settings;   /* Optional */
991    const struct lsquic_stream_if       *ea_stream_if;
992    void                                *ea_stream_if_ctx;
993    lsquic_packets_out_f                 ea_packets_out;
994    void                                *ea_packets_out_ctx;
995    lsquic_lookup_cert_f                 ea_lookup_cert;
996    void                                *ea_cert_lu_ctx;
997    struct ssl_ctx_st *                (*ea_get_ssl_ctx)(void *peer_ctx);
998    /**
999     * Shared hash interface is optional.  If set to zero, performance of
1000     * multiple LSQUIC instances will be degraded.
1001     */
1002    const struct lsquic_shared_hash_if  *ea_shi;
1003    void                                *ea_shi_ctx;
1004    /**
1005     * Memory interface is optional.
1006     */
1007    const struct lsquic_packout_mem_if  *ea_pmi;
1008    void                                *ea_pmi_ctx;
1009    /**
1010     * Optional interface to report new and old source connection IDs.
1011     */
1012    lsquic_cids_update_f                 ea_new_scids;
1013    lsquic_cids_update_f                 ea_live_scids;
1014    lsquic_cids_update_f                 ea_old_scids;
1015    void                                *ea_cids_update_ctx;
1016    /**
1017     * Function to verify server certificate.  The chain contains at least
1018     * one element.  The first element in the chain is the server
1019     * certificate.  The chain belongs to the library.  If you want to
1020     * retain it, call sk_X509_up_ref().
1021     *
1022     * 0 is returned on success, -1 on error.
1023     *
1024     * If the function pointer is not set, no verification is performed
1025     * (the connection is allowed to proceed).
1026     */
1027    int                                (*ea_verify_cert)(void *verify_ctx,
1028                                                struct stack_st_X509 *chain);
1029    void                                *ea_verify_ctx;
1030
1031    /**
1032     * Optional header set interface.  If not specified, the incoming headers
1033     * are converted to HTTP/1.x format and are read from stream and have to
1034     * be parsed again.
1035     */
1036    const struct lsquic_hset_if         *ea_hsi_if;
1037    void                                *ea_hsi_ctx;
1038#if LSQUIC_CONN_STATS
1039    /**
1040     * If set, engine will print cumulative connection statistics to this
1041     * file just before it is destroyed.
1042     */
1043    void /* FILE, really */             *ea_stats_fh;
1044#endif
1045
1046    /**
1047     * Optional SSL key logging interface.
1048     */
1049    const struct lsquic_keylog_if       *ea_keylog_if;
1050    void                                *ea_keylog_ctx;
1051} lsquic_engine_api_t;
1052
1053/**
1054 * Create new engine.
1055 *
1056 * @param   lsquic_engine_flags     A bitmask of @ref LSENG_SERVER and
1057 *                                  @ref LSENG_HTTP
1058 */
1059lsquic_engine_t *
1060lsquic_engine_new (unsigned lsquic_engine_flags,
1061                   const struct lsquic_engine_api *);
1062
1063/**
1064 * Create a client connection to peer identified by `peer_ctx'.
1065 *
1066 * To let the engine specify QUIC version, use N_LSQVER.  If zero-rtt info
1067 * is supplied, version is picked from there instead.
1068 *
1069 * If `max_packet_size' is set to zero, it is inferred based on `peer_sa':
1070 * 1350 for IPv6 and 1370 for IPv4.
1071 */
1072lsquic_conn_t *
1073lsquic_engine_connect (lsquic_engine_t *, enum lsquic_version,
1074                       const struct sockaddr *local_sa,
1075                       const struct sockaddr *peer_sa,
1076                       void *peer_ctx, lsquic_conn_ctx_t *conn_ctx,
1077                       const char *hostname, unsigned short max_packet_size,
1078                       const unsigned char *zero_rtt, size_t zero_rtt_len,
1079                       /** Resumption token: optional */
1080                       const unsigned char *token, size_t token_sz);
1081
1082/**
1083 * Pass incoming packet to the QUIC engine.  This function can be called
1084 * more than once in a row.  After you add one or more packets, call
1085 * lsquic_engine_process_conns() to schedule output, if any.
1086 *
1087 * @retval  0   Packet was processed by a real connection.
1088 *
1089 * @retval  1   Packet was handled successfully, but not by a connection.
1090 *              This may happen with version negotiation and public reset
1091 *              packets as well as some packets that may be ignored.
1092 *
1093 * @retval -1   Some error occurred.  Possible reasons are invalid packet
1094 *              size or failure to allocate memory.
1095 */
1096int
1097lsquic_engine_packet_in (lsquic_engine_t *,
1098        const unsigned char *packet_in_data, size_t packet_in_size,
1099        const struct sockaddr *sa_local, const struct sockaddr *sa_peer,
1100        void *peer_ctx, int ecn);
1101
1102/**
1103 * Process tickable connections.  This function must be called often enough so
1104 * that packets and connections do not expire.
1105 */
1106void
1107lsquic_engine_process_conns (lsquic_engine_t *engine);
1108
1109/**
1110 * Returns true if engine has some unsent packets.  This happens if
1111 * @ref ea_packets_out() could not send everything out.
1112 */
1113int
1114lsquic_engine_has_unsent_packets (lsquic_engine_t *engine);
1115
1116/**
1117 * Send out as many unsent packets as possibe: until we are out of unsent
1118 * packets or until @ref ea_packets_out() fails.
1119 *
1120 * If @ref ea_packets_out() does fail (that is, it returns an error), this
1121 * function must be called to signify that sending of packets is possible
1122 * again.
1123 */
1124void
1125lsquic_engine_send_unsent_packets (lsquic_engine_t *engine);
1126
1127void
1128lsquic_engine_destroy (lsquic_engine_t *);
1129
1130/** Return max allowed outbound streams less current outbound streams. */
1131unsigned
1132lsquic_conn_n_avail_streams (const lsquic_conn_t *);
1133
1134void
1135lsquic_conn_make_stream (lsquic_conn_t *);
1136
1137/** Return number of delayed streams currently pending */
1138unsigned
1139lsquic_conn_n_pending_streams (const lsquic_conn_t *);
1140
1141/** Cancel `n' pending streams.  Returns new number of pending streams. */
1142unsigned
1143lsquic_conn_cancel_pending_streams (lsquic_conn_t *, unsigned n);
1144
1145/**
1146 * Mark connection as going away: send GOAWAY frame and do not accept
1147 * any more incoming streams, nor generate streams of our own.
1148 *
1149 * In the server mode, of course, we can call this function just fine in both
1150 * Google and IETF QUIC.
1151 *
1152 * In client mode, calling this function in for an IETF QUIC connection does
1153 * not do anything, as the client MUST NOT send GOAWAY frames.
1154 * See [draft-ietf-quic-http-17] Section 4.2.7.
1155 */
1156void
1157lsquic_conn_going_away (lsquic_conn_t *);
1158
1159/**
1160 * This forces connection close.  on_conn_closed and on_close callbacks
1161 * will be called.
1162 */
1163void
1164lsquic_conn_close (lsquic_conn_t *);
1165
1166int lsquic_stream_wantread(lsquic_stream_t *s, int is_want);
1167ssize_t lsquic_stream_read(lsquic_stream_t *s, void *buf, size_t len);
1168ssize_t lsquic_stream_readv(lsquic_stream_t *s, const struct iovec *,
1169                                                            int iovcnt);
1170
1171/**
1172 * This function allows user-supplied callback to read the stream contents.
1173 * It is meant to be used for zero-copy stream processing.
1174 */
1175ssize_t
1176lsquic_stream_readf (lsquic_stream_t *s,
1177    /**
1178     * The callback takes four parameters:
1179     *  - Pointer to user-supplied context;
1180     *  - Pointer to the data;
1181     *  - Data size (can be zero); and
1182     *  - Indicator whether the FIN follows the data.
1183     *
1184     * The callback returns number of bytes processed.  If this number is zero
1185     * or is smaller than `len', reading from stream stops.
1186     */
1187    size_t (*readf)(void *ctx, const unsigned char *buf, size_t len, int fin),
1188    void *ctx);
1189
1190int lsquic_stream_wantwrite(lsquic_stream_t *s, int is_want);
1191
1192/**
1193 * Write `len' bytes to the stream.  Returns number of bytes written, which
1194 * may be smaller that `len'.
1195 */
1196ssize_t lsquic_stream_write(lsquic_stream_t *s, const void *buf, size_t len);
1197
1198ssize_t lsquic_stream_writev(lsquic_stream_t *s, const struct iovec *vec, int count);
1199
1200/**
1201 * Used as argument to @ref lsquic_stream_writef()
1202 */
1203struct lsquic_reader
1204{
1205    /**
1206     * Not a ssize_t because the read function is not supposed to return
1207     * an error.  If an error occurs in the read function (for example, when
1208     * reading from a file fails), it is supposed to deal with the error
1209     * itself.
1210     */
1211    size_t (*lsqr_read) (void *lsqr_ctx, void *buf, size_t count);
1212    /**
1213     * Return number of bytes remaining in the reader.
1214     */
1215    size_t (*lsqr_size) (void *lsqr_ctx);
1216    void    *lsqr_ctx;
1217};
1218
1219/**
1220 * Write to stream using @ref lsquic_reader.  This is the most generic of
1221 * the write functions -- @ref lsquic_stream_write() and
1222 * @ref lsquic_stream_writev() utilize the same mechanism.
1223 *
1224 * @retval Number of bytes written or -1 on error.
1225 */
1226ssize_t
1227lsquic_stream_writef (lsquic_stream_t *, struct lsquic_reader *);
1228
1229/**
1230 * Flush any buffered data.  This triggers packetizing even a single byte
1231 * into a separate frame.  Flushing a closed stream is an error.
1232 *
1233 * @retval  0   Success
1234 * @retval -1   Failure
1235 */
1236int
1237lsquic_stream_flush (lsquic_stream_t *s);
1238
1239/**
1240 * @typedef lsquic_http_header_t
1241 * @brief HTTP header structure. Contains header name and value.
1242 *
1243 */
1244typedef struct lsquic_http_header
1245{
1246   struct iovec name;
1247   struct iovec value;
1248} lsquic_http_header_t;
1249
1250/**
1251 * @typedef lsquic_http_headers_t
1252 * @brief HTTP header list structure. Contains a list of HTTP headers in key/value pairs.
1253 * used in API functions to pass headers.
1254 */
1255struct lsquic_http_headers
1256{
1257    int                     count;
1258    lsquic_http_header_t   *headers;
1259};
1260
1261int lsquic_stream_send_headers(lsquic_stream_t *s,
1262                               const lsquic_http_headers_t *h, int eos);
1263
1264/**
1265 * Get header set associated with the stream.  The header set is created by
1266 * @ref hsi_create_header_set() callback.  After this call, the ownership of
1267 * the header set is trasnferred to the caller.
1268 *
1269 * This call must precede calls to @ref lsquic_stream_read() and
1270 * @ref lsquic_stream_readv().
1271 *
1272 * If the optional header set interface (@ref ea_hsi_if) is not specified,
1273 * this function returns NULL.
1274 */
1275void *
1276lsquic_stream_get_hset (lsquic_stream_t *);
1277
1278/**
1279 * A server may push a stream.  This call creates a new stream in reference
1280 * to stream `s'.  It will behave as if the client made a request: it will
1281 * trigger on_new_stream() event and it can be used as a regular client-
1282 * initiated stream.
1283 *
1284 * If `hdr_set' is not set, it is generated by using `ea_hsi_if' callbacks.
1285 * In either case, the header set object belongs to the connection.  The
1286 * user is not to free this object until (@ref hsi_discard_header_set) is
1287 * called.
1288 *
1289 * @retval  0   Stream pushed successfully.
1290 * @retval  1   Stream push failed because it is disabled or because we hit
1291 *                stream limit or connection is going away.
1292 * @retval -1   Stream push failed because of an internal error.
1293 */
1294int
1295lsquic_conn_push_stream (lsquic_conn_t *c, void *hdr_set, lsquic_stream_t *s,
1296    const  struct iovec* url, const struct iovec* authority,
1297    const lsquic_http_headers_t *headers);
1298
1299/**
1300 * Only makes sense in server mode: the client cannot push a stream and this
1301 * function always returns false in client mode.
1302 */
1303int
1304lsquic_conn_is_push_enabled (lsquic_conn_t *);
1305
1306/** Possible values for how are 0, 1, and 2.  See shutdown(2). */
1307int lsquic_stream_shutdown(lsquic_stream_t *s, int how);
1308
1309int lsquic_stream_close(lsquic_stream_t *s);
1310
1311/**
1312 * Get certificate chain returned by the server.  This can be used for
1313 * server certificate verification.
1314 *
1315 * If server certificate cannot be verified, the connection can be closed
1316 * using lsquic_conn_cert_verification_failed().
1317 *
1318 * The caller releases the stack using sk_X509_free().
1319 */
1320struct stack_st_X509 *
1321lsquic_conn_get_server_cert_chain (lsquic_conn_t *);
1322
1323/** Returns ID of the stream */
1324lsquic_stream_id_t
1325lsquic_stream_id (const lsquic_stream_t *s);
1326
1327/**
1328 * Returns stream ctx associated with the stream.  (The context is what
1329 * is returned by @ref on_new_stream callback).
1330 */
1331lsquic_stream_ctx_t *
1332lsquic_stream_get_ctx (const lsquic_stream_t *s);
1333
1334/** Returns true if this is a pushed stream */
1335int
1336lsquic_stream_is_pushed (const lsquic_stream_t *s);
1337
1338/**
1339 * Returns true if this stream was rejected, false otherwise.  Use this as
1340 * an aid to distinguish between errors.
1341 */
1342int
1343lsquic_stream_is_rejected (const lsquic_stream_t *s);
1344
1345/**
1346 * Refuse pushed stream.  Call it from @ref on_new_stream.
1347 *
1348 * No need to call lsquic_stream_close() after this.  on_close will be called.
1349 *
1350 * @see lsquic_stream_is_pushed
1351 */
1352int
1353lsquic_stream_refuse_push (lsquic_stream_t *s);
1354
1355/**
1356 * Get information associated with pushed stream:
1357 *
1358 * @param ref_stream_id   Stream ID in response to which push promise was
1359 *                            sent.
1360 * @param hdr_set         Header set.  This object was passed to or generated
1361 *                            by @ref lsquic_conn_push_stream().
1362 *
1363 * @retval   0  Success.
1364 * @retval  -1  This is not a pushed stream.
1365 */
1366int
1367lsquic_stream_push_info (const lsquic_stream_t *,
1368                         lsquic_stream_id_t *ref_stream_id, void **hdr_set);
1369
1370/** Return current priority of the stream */
1371unsigned lsquic_stream_priority (const lsquic_stream_t *s);
1372
1373/**
1374 * Set stream priority.  Valid priority values are 1 through 256, inclusive.
1375 *
1376 * @retval   0  Success.
1377 * @retval  -1  Priority value is invalid.
1378 */
1379int lsquic_stream_set_priority (lsquic_stream_t *s, unsigned priority);
1380
1381/**
1382 * Get a pointer to the connection object.  Use it with lsquic_conn_*
1383 * functions.
1384 */
1385lsquic_conn_t * lsquic_stream_conn(const lsquic_stream_t *s);
1386
1387lsquic_stream_t *
1388lsquic_conn_get_stream_by_id (lsquic_conn_t *c, lsquic_stream_id_t stream_id);
1389
1390/** Get connection ID */
1391const lsquic_cid_t *
1392lsquic_conn_id (const lsquic_conn_t *c);
1393
1394/** Get pointer to the engine */
1395lsquic_engine_t *
1396lsquic_conn_get_engine (lsquic_conn_t *c);
1397
1398int
1399lsquic_conn_get_sockaddr(lsquic_conn_t *c,
1400                const struct sockaddr **local, const struct sockaddr **peer);
1401
1402struct lsquic_logger_if {
1403    int     (*log_buf)(void *logger_ctx, const char *buf, size_t len);
1404};
1405
1406/**
1407 * Enumerate timestamp styles supported by LSQUIC logger mechanism.
1408 */
1409enum lsquic_logger_timestamp_style {
1410    /**
1411     * No timestamp is generated.
1412     */
1413    LLTS_NONE,
1414
1415    /**
1416     * The timestamp consists of 24 hours, minutes, seconds, and
1417     * milliseconds.  Example: 13:43:46.671
1418     */
1419    LLTS_HHMMSSMS,
1420
1421    /**
1422     * Like above, plus date, e.g: 2017-03-21 13:43:46.671
1423     */
1424    LLTS_YYYYMMDD_HHMMSSMS,
1425
1426    /**
1427     * This is Chrome-like timestamp used by proto-quic.  The timestamp
1428     * includes month, date, hours, minutes, seconds, and microseconds.
1429     *
1430     * Example: 1223/104613.946956 (instead of 12/23 10:46:13.946956).
1431     *
1432     * This is to facilitate reading two logs side-by-side.
1433     */
1434    LLTS_CHROMELIKE,
1435
1436    /**
1437     * The timestamp consists of 24 hours, minutes, seconds, and
1438     * microseconds.  Example: 13:43:46.671123
1439     */
1440    LLTS_HHMMSSUS,
1441
1442    /**
1443     * Date and time using microsecond resolution,
1444     * e.g: 2017-03-21 13:43:46.671123
1445     */
1446    LLTS_YYYYMMDD_HHMMSSUS,
1447
1448    N_LLTS
1449};
1450
1451/**
1452 * Call this if you want to do something with LSQUIC log messages, as they
1453 * are thrown out by default.
1454 */
1455void lsquic_logger_init(const struct lsquic_logger_if *, void *logger_ctx,
1456                        enum lsquic_logger_timestamp_style);
1457
1458/**
1459 * Set log level for all LSQUIC modules.  Acceptable values are debug, info,
1460 * notice, warning, error, alert, emerg, crit (case-insensitive).
1461 *
1462 * @retval  0   Success.
1463 * @retval -1   Failure: log_level is not valid.
1464 */
1465int
1466lsquic_set_log_level (const char *log_level);
1467
1468/**
1469 * E.g. "event=debug"
1470 */
1471int
1472lsquic_logger_lopt (const char *optarg);
1473
1474/**
1475 * Return the list of QUIC versions (as bitmask) this engine instance
1476 * supports.
1477 */
1478unsigned lsquic_engine_quic_versions (const lsquic_engine_t *);
1479
1480/**
1481 * This is one of the flags that can be passed to @ref lsquic_global_init.
1482 * Use it to initialize LSQUIC for use in client mode.
1483 */
1484#define LSQUIC_GLOBAL_CLIENT (1 << 0)
1485
1486/**
1487 * This is one of the flags that can be passed to @ref lsquic_global_init.
1488 * Use it to initialize LSQUIC for use in server mode.
1489 */
1490#define LSQUIC_GLOBAL_SERVER (1 << 1)
1491
1492/**
1493 * Initialize LSQUIC.  This must be called before any other LSQUIC function
1494 * is called.  Returns 0 on success and -1 on failure.
1495 *
1496 * @param flags     This a bitmask of @ref LSQUIC_GLOBAL_CLIENT and
1497 *                    @ref LSQUIC_GLOBAL_SERVER.  At least one of these
1498 *                    flags should be specified.
1499 *
1500 * @retval  0   Success.
1501 * @retval -1   Initialization failed.
1502 *
1503 * @see LSQUIC_GLOBAL_CLIENT
1504 * @see LSQUIC_GLOBAL_SERVER
1505 */
1506int
1507lsquic_global_init (int flags);
1508
1509/**
1510 * Clean up global state created by @ref lsquic_global_init.  Should be
1511 * called after all LSQUIC engine instances are gone.
1512 */
1513void
1514lsquic_global_cleanup (void);
1515
1516/**
1517 * Get QUIC version used by the connection.
1518 *
1519 * @see lsquic_version
1520 */
1521enum lsquic_version
1522lsquic_conn_quic_version (const lsquic_conn_t *c);
1523
1524/* Return keysize or -1 on error */
1525int
1526lsquic_conn_crypto_keysize (const lsquic_conn_t *c);
1527
1528/* Return algorithm keysize or -1 on error */
1529int
1530lsquic_conn_crypto_alg_keysize (const lsquic_conn_t *c);
1531
1532enum lsquic_crypto_ver
1533{
1534    LSQ_CRY_QUIC,
1535    LSQ_CRY_TLSv13,
1536};
1537
1538enum lsquic_crypto_ver
1539lsquic_conn_crypto_ver (const lsquic_conn_t *c);
1540
1541/* Return cipher or NULL on error */
1542const char *
1543lsquic_conn_crypto_cipher (const lsquic_conn_t *c);
1544
1545/** Translate string QUIC version to LSQUIC QUIC version representation */
1546enum lsquic_version
1547lsquic_str2ver (const char *str, size_t len);
1548
1549/** Translate ALPN (e.g. "h3", "h3-23", "h3-Q046") to LSQUIC enum */
1550enum lsquic_version
1551lsquic_alpn2ver (const char *alpn, size_t len);
1552
1553/**
1554 * This function closes all mini connections and marks all full connections
1555 * as going away.  In server mode, this also causes the engine to stop
1556 * creating new connections.
1557 */
1558void
1559lsquic_engine_cooldown (lsquic_engine_t *);
1560
1561struct ssl_st *
1562lsquic_hsk_getssl(lsquic_conn_t *conn);
1563
1564/**
1565 * Get user-supplied context associated with the connection.
1566 */
1567lsquic_conn_ctx_t *
1568lsquic_conn_get_ctx (const lsquic_conn_t *);
1569
1570/**
1571 * Set user-supplied context associated with the connection.
1572 */
1573void
1574lsquic_conn_set_ctx (lsquic_conn_t *, lsquic_conn_ctx_t *);
1575
1576/**
1577 * Get peer context associated with the connection.
1578 */
1579void *
1580lsquic_conn_get_peer_ctx (lsquic_conn_t *, const struct sockaddr *local_sa);
1581
1582/**
1583 * Abort connection.
1584 */
1585void
1586lsquic_conn_abort (lsquic_conn_t *);
1587
1588/**
1589 * Helper function: convert list of versions as specified in the argument
1590 * bitmask to string that can be included as argument to "v=" part of the
1591 * Alt-Svc header.
1592 *
1593 * For example (1<<LSQVER_037)|(1<<LSQVER_038) => "37,38"
1594 *
1595 * This is only applicable to Google QUIC versions.
1596 */
1597const char *
1598lsquic_get_alt_svc_versions (unsigned versions);
1599
1600/**
1601 * Return a NULL-terminated list of HTTP/3 ALPNs, e.g "h3-17", "h3-18", "h3".
1602 */
1603const char *const *
1604lsquic_get_h3_alpns (unsigned versions);
1605
1606/**
1607 * Returns true if provided buffer could be a valid handshake-stage packet,
1608 * false otherwise.  Do not call this function if a connection has already
1609 * been established: it will return incorrect result.
1610 */
1611int
1612lsquic_is_valid_hs_packet (lsquic_engine_t *, const unsigned char *, size_t);
1613
1614/**
1615 * Parse cid from packet stored in `buf' and store it to `cid'.  Returns 0
1616 * on success and -1 on failure.
1617 */
1618int
1619lsquic_cid_from_packet (const unsigned char *, size_t bufsz, lsquic_cid_t *cid);
1620
1621/**
1622 * Returns true if there are connections to be processed, false otherwise.
1623 * If true, `diff' is set to the difference between the earliest advisory
1624 * tick time and now.  If the former is in the past, the value of `diff'
1625 * is negative.
1626 */
1627int
1628lsquic_engine_earliest_adv_tick (lsquic_engine_t *engine, int *diff);
1629
1630/**
1631 * Return number of connections whose advisory tick time is before current
1632 * time plus `from_now' microseconds from now.  `from_now' can be negative.
1633 */
1634unsigned
1635lsquic_engine_count_attq (lsquic_engine_t *engine, int from_now);
1636
1637enum LSQUIC_CONN_STATUS
1638{
1639    LSCONN_ST_HSK_IN_PROGRESS,
1640    LSCONN_ST_CONNECTED,
1641    LSCONN_ST_HSK_FAILURE,
1642    LSCONN_ST_GOING_AWAY,
1643    LSCONN_ST_TIMED_OUT,
1644    /* If es_honor_prst is not set, the connection will never get public
1645     * reset packets and this flag will not be set.
1646     */
1647    LSCONN_ST_RESET,
1648    LSCONN_ST_USER_ABORTED,
1649    LSCONN_ST_ERROR,
1650    LSCONN_ST_CLOSED,
1651    LSCONN_ST_PEER_GOING_AWAY,
1652};
1653
1654enum LSQUIC_CONN_STATUS
1655lsquic_conn_status (lsquic_conn_t *, char *errbuf, size_t bufsz);
1656
1657extern const char *const
1658lsquic_ver2str[N_LSQVER];
1659
1660#ifdef __cplusplus
1661}
1662#endif
1663
1664#endif //__LSQUIC_H__
1665
1666