litespeed-quic/docs/index.rst

LSQUIC Documentation
====================

This is the documentation for LSQUIC_ |release|, last updated |today|.

LiteSpeed QUIC (LSQUIC) Library is an open-source implementation of QUIC
and HTTP/3 functionality for servers and clients.  LSQUIC is:

- fast;

- flexible; and

- production-ready.

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 v1, Internet-Draft versions 29, and 27;
and the older "Google" QUIC versions Q043, Q046, an Q050.

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:

 - :ref:`extensible-http-priorities`
 - :ref:`apiref-datagrams`
 - 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/
.. _`LiteSpeed Web ADC`: https://www.litespeedtech.com/products/litespeed-web-adc/
.. _OpenLiteSpeed: https://openlitespeed.org/

Contents
--------

.. toctree::
   :maxdepth: 2

   gettingstarted
   tutorial
   apiref
   devel
   internals
   faq

Indices and tables
==================

* :ref:`genindex`
* :ref:`search`
Switch to readthedocs.org for hosting documentation Add API reference. 2020-02-20 21:56:57 +00:00			`LSQUIC Documentation`
			`====================`

			`This is the documentation for LSQUIC_ \|release\|, last updated \|today\|.`

			`LiteSpeed QUIC (LSQUIC) Library is an open-source implementation of QUIC`
			`and HTTP/3 functionality for servers and clients. LSQUIC is:`

			`- fast;`

			`- flexible; and`

			`- production-ready.`

			`Most of the code in this distribution has been used in our own products`
			-- `LiteSpeed Web Server`_, `LiteSpeed Web ADC`_, and OpenLiteSpeed_ --
			`since 2017.`

Update index.rst 2021-06-05 23:20:53 +00:00			`Currently supported QUIC versions are v1, Internet-Draft versions 29, and 27;`
Release 2.29.0 - [FEATURE] QUIC and HTTP/3 Internet Draft 34 support and v1 support. The latter is turned off by default. - Drop support for ID-28 and ID-32. - [BUGFIX] IETF QUIC mini conn receive history (trechist): allow unlimited inserts by dropping smallest elements. - [BUGFIX] gQUIC: set STTL to correct value, issue #226. - [BUGFIX] Account for poison packet gap when MTU probe was too large. 2021-02-10 13:51:11 +00:00			`and the older "Google" QUIC versions Q043, Q046, an Q050.`
Switch to readthedocs.org for hosting documentation Add API reference. 2020-02-20 21:56:57 +00:00
			LSQUIC is licensed under the `MIT License`_; see LICENSE in the source
			`distribution for details.`

Finish LSQUIC Tutorial 2020-08-21 15:06:45 +00:00			`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:`

Release 2.22.0 - [FEATURE] Extensible HTTP Priorities (HTTP/3 only). - [FEATURE] Add conn context to packet-out memory interface (PR #175). - [BUGFIX] gQUIC proof generation: allocate buffer big enough for signature (issue #173). - [BUGFIX] Make library thread-safe: drop use of global variables (issue #133, issue #167). - [BUGFIX] Deactivate only recent HQ frame, not any HQ frame. - [BUGFIX] gQUIC server: associate compressed cert with SSL_CTX, instead of keeping them in a separate hash, potentially leading to mismatches. - [BUGFIX] Stream data discard infinite loop: break on FIN. - cmake: add install target via -DCMAKE_INSTALL_PREFIX (PR #171). - Support randomized packet number to begin a connection. - Mini and full IETF connection size optimization. - http_client: specify HTTP priorities based on stream conditions. 2020-10-07 13:41:26 +00:00			- :ref:`extensible-http-priorities`
Release 2.20.0 - [FEATURE] QUIC and HTTP/3 Internet Draft 30 support. - [FEATURE] Unreliable Datagram Extension support. - [FEATURE] Adaptive congestion controller. - [BUGFIX] Do not send MAX_STREAM_DATA frames on crypto streams. - [BUGFIX] Fail with CRYPTO_BUFFER_EXCEEDED when too much CRYPTO data comes in. - [BUFFIX] Spin bit is now strictly per path; value is reset on DCID change. - [BUGFIX] Check that max value of max_streams_uni and max_streams_bidi TPs is 2^60. - [BUGFIX] Close IETF mini conn immediately if crypto session cannot be initialized. - Deprecate ID-28 (no browser uses it): it's no longer in the default versions list. - New programs duck_server and duck_client that implement the experimental siduck-00 protocol. They quack! - IETF crypto streams: don't limit ourselves from sending. - Command-line programs: turn off QL loss bits if -G is used, as Wireshark cannot decrypt QUIC packets when this extension is used. - Turn all h3 framing unit tests back on. - Fix malo initialization when compiled in no-pool mode. 2020-09-15 20:42:13 +00:00			- :ref:`apiref-datagrams`
Finish LSQUIC Tutorial 2020-08-21 15:06:45 +00:00			`- 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.`

Switch to readthedocs.org for hosting documentation Add API reference. 2020-02-20 21:56:57 +00:00			`.. _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/
			.. _`LiteSpeed Web ADC`: https://www.litespeedtech.com/products/litespeed-web-adc/
			`.. _OpenLiteSpeed: https://openlitespeed.org/`

			`Contents`
			`--------`

			`.. toctree::`
			`:maxdepth: 2`

			`gettingstarted`
Release 2.12.0 - [FEATURE] QUIC timestamps extension. - [API] New: ea_alpn that is used when not in HTTP mode. - [BUGFIX] SNI is mandatory only for HTTP/3 and gQUIC. - [BUGFIX] Benign double-free -- issue #110. - [BUGFIX] Printing of transport parameters. 2020-03-02 13:53:41 +00:00			`tutorial`
Switch to readthedocs.org for hosting documentation Add API reference. 2020-02-20 21:56:57 +00:00			`apiref`
Release 2.29.3 - [BUGFIX] Do not send RESET_STREAM if writing to stream is already finished. - perf_client: wait for all ACKs before exiting. - Improve how generated RESET_STREAM is logged. - Fix compilation in different combos of adv_tick/conn_stats flags. - Move qpack warning disablement into src/liblsquic/CMakeLists.txt. 2021-03-03 14:41:42 +00:00			`devel`
Release 2.29.6 - Documentation: describe lsquic internals ("guts"). - Two more fixes to compliance issues found by h3spec. - Truncate, don't abort, SCIDs larger than 16 bytes (PR #244). - Several small internal improvements and space optimizations. 2021-03-31 13:38:32 +00:00			`internals`
Add FAQ to the docs 2020-10-11 20:53:34 +00:00			`faq`
Switch to readthedocs.org for hosting documentation Add API reference. 2020-02-20 21:56:57 +00:00
			`Indices and tables`
			`==================`

			* :ref:`genindex`
			* :ref:`search`