diff --git a/.dockerignore b/.dockerignore index 72f606441..1284f63d8 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,4 +1,3 @@ -website/ fuzz/ include/ target/ diff --git a/.gitignore b/.gitignore index a8928fac4..e56acb16e 100644 --- a/.gitignore +++ b/.gitignore @@ -18,16 +18,3 @@ Cargo.lock # Misc .DS_Store - -# Website -/website/node_modules -/website/build -/website/.env.local -/website/.env.development.local -/website/.env.test.local -/website/.env.production.local -/website/npm-debug.log* -/website/yarn-debug.log* -/website/yarn-error.log* -/website/.docusaurus -/website/.cache-loader diff --git a/typos.toml b/typos.toml index 8fa53dbe2..0391977ec 100644 --- a/typos.toml +++ b/typos.toml @@ -17,7 +17,6 @@ extend-exclude = [ "*.der", "*.pem", "LICENSE", - "**/website/**/*", "**/target/**/*", "**/deps/**/*", "**/corpus/**/*", diff --git a/website/.gitignore b/website/.gitignore deleted file mode 100644 index b2d6de306..000000000 --- a/website/.gitignore +++ /dev/null @@ -1,20 +0,0 @@ -# Dependencies -/node_modules - -# Production -/build - -# Generated files -.docusaurus -.cache-loader - -# Misc -.DS_Store -.env.local -.env.development.local -.env.test.local -.env.production.local - -npm-debug.log* -yarn-debug.log* -yarn-error.log* diff --git a/website/README.md b/website/README.md deleted file mode 100644 index aaba2fa1e..000000000 --- a/website/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# Website - -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. - -### Installation - -``` -$ yarn -``` - -### Local Development - -``` -$ yarn start -``` - -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. - -### Build - -``` -$ yarn build -``` - -This command generates static content into the `build` directory and can be served using any static contents hosting service. - -### Deployment - -Using SSH: - -``` -$ USE_SSH=true yarn deploy -``` - -Not using SSH: - -``` -$ GIT_USER= yarn deploy -``` - -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. diff --git a/website/babel.config.js b/website/babel.config.js deleted file mode 100644 index e00595dae..000000000 --- a/website/babel.config.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = { - presets: [require.resolve('@docusaurus/core/lib/babel/preset')], -}; diff --git a/website/blog/2023-10-26-open-source/index.md b/website/blog/2023-10-26-open-source/index.md deleted file mode 100644 index 690f7632a..000000000 --- a/website/blog/2023-10-26-open-source/index.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -slug: tquic-open-source -title: Announcing the TQUIC open source project -authors: [iyangsj] -tags: [tquic, quic, rust, open source] ---- - - -# Introduction - -TQUIC is a QUIC protocol implementation written in the Rust language, aiming to create a low-overhead, high-throughput, and high-quality transport protocol library with continuous technological influence. - - - - -# Why Open source? - -QUIC is a new general-purpose, secured, multiplexed transport-layer protocol. It offers several enhancements, aiming to eventually replace TCP, which could enable Internet transport to continue evolving and solve many of the problems plaguing the Internet. - -With QUIC being chosen as the foundation for HTTP/3, it is reasonable to expect that the protocol will carry a growing share of Internet traffic. - -Given QUIC's broad scope, long-term vision, and innovative nature, we have decided to release our TQUIC library as open-source. Our goal is to take this opportunity to collaborate with peers and further explore the emerging technologies in the transport layer. - - -# Features and Advantages - -The advantages of TQUIC are as follows. - -**High Throughput**: TQUIC provides the most comprehensive collection of congestion control algorithms in the industry, consistently meeting RFC standards and outperforming [similar open-source projects](https://tquic.net/docs/further_readings/comparison/) by 2%-30% in certain scenarios such as poor networks. - -**High performance**: The performance of TQUIC surpasses that of [similar open-source projects](https://tquic.net/docs/further_readings/benchmark) by 5% and 20% in most and certain scenarios respectively. - -**High Quality**: The QUIC protocol stack comprises over 10 core RFC standards or drafts, covering the transport layer, security layer, and application layer. It is considerably more complex compared to TCP. TQUIC has achieved an impressive unit test coverage of over 95% and has successfully passed interoperability tests with four leading QUIC implementations in the industry. Additionally, a rigorous test method based on formal specifications (SIGCOMM2019 paper) is employed to ensure strict protocol conformance. - -**Easy to Use**: TQUIC is not only easy to use, but also supports flexible configuration and detailed observability. In addition, it offers APIs for Rust/C/C++, with plans to expand its support to Kotlin/Swift, etc. - -**Powered by Rust**: TQUIC is written in a memory-safe language, making it immune to Buffer Overflow vulnerability and other memory-related bugs. - -**Rich Features**: TQUIC supports all major features as specified in the QUIC and HTTP/3 RFCs. - -[The TQUIC project website](https://tquic.net/docs/intro) offers a comprehensive introduction to TQUIC. - - -# Architecture - -The Figure shown below illustrates the architecture of TQUIC. - -![TQUIC Architecture](./tquic-arch.png) - -TQUIC was built with a focus on working across different platforms and supporting various concurrency models. Its core employs an abstraction design for network I/O and event loop. It relies on callbacks provided by users rather than sockets. Furthermore, it doesn't impose specific event loop requirements, but offers functions to assist users in scheduling events. This flexibility makes TQUIC easy to customize and integrate. - -The TQUIC API layer provides user-friendly interfaces for various programming languages on different mainstream platforms. It provides both sync and async interfaces, works well with different concurrency models, and improves user experience. - - -# Roadmap - -* Integrating open-source ecosystem projects, expanding TQUIC application scenarios, and further enhancing user experience with TQUIC -* Publishing relevant papers and gradually releasing more advanced TQUIC features and algorithms as open-source -* Tracking the evolution and innovation of the QUIC protocol, while continuously enhancing the core capabilities of TQUIC - - -# Conclusion - -The open source of TQUIC is just the beginning. We welcome suggestions from all parties and encourage involvement in the advancement of the ecology of transport technology. Interested parties are welcome to reach out and engage with us. - - diff --git a/website/blog/2023-10-26-open-source/tquic-arch.png b/website/blog/2023-10-26-open-source/tquic-arch.png deleted file mode 100644 index 0612088ab..000000000 Binary files a/website/blog/2023-10-26-open-source/tquic-arch.png and /dev/null differ diff --git a/website/blog/authors.yml b/website/blog/authors.yml deleted file mode 100644 index 25c3eb482..000000000 --- a/website/blog/authors.yml +++ /dev/null @@ -1,9 +0,0 @@ -jeffyang: - name: Sijie Yang - url: https://github.com/iyangsj - image_url: https://github.com/iyangsj.png - -iyangsj: - name: Sijie Yang - url: https://github.com/iyangsj - image_url: https://github.com/iyangsj.png diff --git a/website/docs/api_reference/_category_.json b/website/docs/api_reference/_category_.json deleted file mode 100644 index a8525dc3d..000000000 --- a/website/docs/api_reference/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "API Reference", - "position": 4, - "link": { - "type": "generated-index", - "description": "API Reference of the TQUIC library." - } -} diff --git a/website/docs/api_reference/c_h3.md b/website/docs/api_reference/c_h3.md deleted file mode 100644 index 73698fde9..000000000 --- a/website/docs/api_reference/c_h3.md +++ /dev/null @@ -1,381 +0,0 @@ ---- -title: C/C++ HTTP/3 API Reference -sidebar_position: 4 ---- - -# C/C++ HTTP/3 API Reference - -## Preliminaries - -The declarations are all in `tquic.h`, so you just need to include it in each source file: - -```c -#include -``` - -## Common types - -The TQUIC HTTP/3 library defines several types that are commonly used by its public functions. - -| Types | Description | -|-------|-------------| -| `http3_config_t` | The behavior of the HTTP/3 library can be managed through various parameters in `http3_config_t`. | -| `http3_conn_t` | HTTP/3 connection, which can manitain muliple requests simultaneously. | -| `http3_header_t` | HTTP/3 header structure. | -| `http3_headers_t` | HTTP/3 headers list. | -| `http3_methods_t` | The structure lists the callbacks used by the connection to interact with the user code. | -| `http3_context_t` | User-provided HTTP/3 context that can be used to associate information during event callbacks. | -| `http3_priority_t` | Extensible HTTP/3 priority, as described in [RFC9218](https://www.rfc-editor.org/rfc/rfc9218.html). | - - -## Configurations - - -### HTTP/3 configurations initialization - -#### http3_config_new - -```c -struct http3_config_t *http3_config_new(void); -``` -* Create an instance of `http3_config_t` and initialize it with default values. The caller is responsible for managing the memory and should free it by calling `http3_config_free`. - - -#### http3_config_free - -```c -void http3_config_free(struct http3_config_t *config); -``` -* Free HTTP/3 configuration. - - -### HTTP/3 configurations customization - -#### http3_config_set_max_field_section_size -```c -void http3_config_set_max_field_section_size(struct http3_config_t *config, uint64_t v); -``` -* Set the `max_field_section_size` setting parameter in bytes. -* The default value is set to `0`, which means there is no limit on the size of headers received from the peer. The calculation rules for headers size constraints can be found in [RFC9114 Headers Size Constraints](https://www.rfc-editor.org/rfc/rfc9114.html#name-header-size-constraints). - - -## HTTP/3 Connection - -### Instantiation and destruction - -#### http3_conn_new -```c -struct http3_conn_t *http3_conn_new(struct quic_conn_t *quic_conn, struct http3_config_t *config); -``` -* Create an HTTP/3 connection. The caller is responsible for the memory of the connection and properly free it by calling `http3_conn_free`. - - -#### http3_conn_free -```c -void http3_conn_free(struct http3_conn_t *conn); -``` -* Free an HTTP/3 connection. - - -### Event-driven and Callbacks - -#### http3_conn_set_events_handler -```c -void http3_conn_set_events_handler(struct http3_conn_t *conn, - const struct http3_methods_t *methods, - http3_context_t context); -``` -* Sets the callback and context for processing HTTP/3 connection events. - - -#### http3_conn_process_streams -```c -int http3_conn_process_streams(struct http3_conn_t *conn, struct quic_conn_t *quic_conn); -``` -* Drives the HTTP/3 connection to process internal events for all maintained streams. - - -### HTTP/3 Callbacks - -The `http3_methods_t` lists the callbacks used by the HTTP/3 connection to interact with the user code. - - -#### on_stream_headers -```c -typedef struct http3_methods_t { - void (*on_stream_headers)(void *ctx, uint64_t stream_id, const struct http3_headers_t *headers, bool fin); - /* ... */ -} http3_methods_t; -``` - * `on_stream_headers` is called when request or response headers are received from the peer. In this callback, the upper-layer application can parse the headers using `http3_for_each_header`. - - -#### on_stream_data -```c -typedef struct http3_methods_t { - void (*on_stream_data)(void *ctx, uint64_t stream_id); - /* ... */ -} http3_methods_t; -``` - * `on_stream_data` is called when DATA frames are received from the peer. Note that this event is edge-triggered. - - -#### on_stream_finished -```c -typedef struct http3_methods_t { - void (*on_stream_finished)(void *ctx, uint64_t stream_id); - /* ... */ -} http3_methods_t; -``` - * `on_stream_finished` is called when all incoming data for a stream has been read. - - -#### on_stream_reset -```c -typedef struct http3_methods_t { - void (*on_stream_reset)(void *ctx, uint64_t stream_id, uint64_t error_code); - /* ... */ -} http3_methods_t; -``` - * `on_stream_reset` is called when a RESET_STREAM frame is received from the peer. This callback is optional. - - -#### on_stream_priority_update -```c -typedef struct http3_methods_t { - void (*on_stream_priority_update)(void *ctx, uint64_t stream_id); - /* ... */ -} http3_methods_t; -``` - * `on_stream_priority_update` is called when a PRIORITY_UPDATE frame is received from the peer. This callback is optional, and the upper-layer application can use `http3_take_priority_update` to get the priority update info for the associated stream. - - -#### on_conn_goaway -```c -typedef struct http3_methods_t { - void (*on_conn_goaway)(void *ctx, uint64_t stream_id); - /* ... */ -} http3_methods_t; -``` - * `on_conn_goaway` is called when a GOAWAY frame is received from the peer. This callback is optional, and after receiving this event, the upper-layer application should not initiate new streams on the connection. - - -### Miscellaneous functions - -#### http3_for_each_setting -```c -int http3_for_each_setting(const struct http3_conn_t *conn, int (*cb)(uint64_t identifier, - uint64_t value, - void *argp), void *argp); -``` -* For each settings parameter, execute the `cb` callback. - - -#### http3_send_goaway -```c -int64_t http3_send_goaway(struct http3_conn_t *conn, struct quic_conn_t *quic_conn, uint64_t id); -``` -* Send a GOAWAY frame to the peer and disconnect gracefully. - - -## HTTP/3 request - -### Request and Response - -#### http3_stream_new -```c -int64_t http3_stream_new(struct http3_conn_t *conn, struct quic_conn_t *quic_conn); -``` -* Create a new HTTP/3 request stream. - - -#### http3_stream_new_with_priority -```c -int64_t http3_stream_new_with_priority(struct http3_conn_t *conn, - struct quic_conn_t *quic_conn, - const struct http3_priority_t *priority); -``` -* Create a new HTTP/3 request stream with a specified priority using the `priority` parameter. - - -#### http3_stream_close -```c -int http3_stream_close(struct http3_conn_t *conn, - struct quic_conn_t *quic_conn, - uint64_t stream_id); -``` -* Close HTTP/3 request stream. - - -#### http3_send_headers -```c -int http3_send_headers(struct http3_conn_t *conn, - struct quic_conn_t *quic_conn, - uint64_t stream_id, - const struct http3_header_t *headers, - size_t headers_len, - bool fin); -``` -* Send HTTP/3 request or response headers, where the `fin` indicates whether there is more data to be sent. - - -#### http3_send_body -```c -ssize_t http3_send_body(struct http3_conn_t *conn, - struct quic_conn_t *quic_conn, - uint64_t stream_id, - const uint8_t *body, - size_t body_len, - bool fin); -``` -* Send body for an HTTP/3 request or response, where the `fin` indicates whether there is more data to be sent. - - -#### http3_recv_body -```c -ssize_t http3_recv_body(struct http3_conn_t *conn, - struct quic_conn_t *quic_conn, - uint64_t stream_id, - uint8_t *out, - size_t out_len); -``` -* Receive body for an HTTP/3 request or response. - - -#### http3_for_each_header -```c -int http3_for_each_header(const struct http3_headers_t *headers, int (*cb)(const uint8_t *name, - size_t name_len, - const uint8_t *value, - size_t value_len, - void *argp), void *argp); -``` -* For each header, execute the `cb` callback. - - -#### http3_stream_read_finished -```c -bool http3_stream_read_finished(struct quic_conn_t *conn, uint64_t stream_id); -``` -* Check if all incoming data has been fully read. - - -### HTTP/3 Extensiable priority - -#### http3_stream_set_priority -```c -int http3_stream_set_priority(struct http3_conn_t *conn, - struct quic_conn_t *quic_conn, - uint64_t stream_id, - const struct http3_priority_t *priority); -``` -* Set priority for an HTTP/3 stream. - - -#### http3_send_priority_update_for_request -```c -int http3_send_priority_update_for_request(struct http3_conn_t *conn, - struct quic_conn_t *quic_conn, - uint64_t stream_id, - const struct http3_priority_t *priority); -``` -* HTTP/3 client sends a PRIORITY_UPDATE frame for the given request stream to the server. - - -#### http3_take_priority_update -```c -int http3_take_priority_update(struct http3_conn_t *conn, - uint64_t prioritized_element_id, - int (*cb)(const uint8_t *priority_field_value, - size_t priority_field_value_len, - void *argp), - void *argp); -``` -* When the application got a priority update event, it can use this api to get the priority_field value for the `prioritized_element_id` stream. - - -#### http3_parse_extensible_priority -```c -int http3_parse_extensible_priority(const uint8_t *priority, - size_t priority_len, - struct http3_priority_t *parsed); -``` -* The application uses this api to parse the structured encoded priority_field into the `http3_priority_t` structure. - - - -## Miscellaneous functions - -#### http3_methods_t -```c -typedef struct http3_methods_t { - /** - * Called when the stream got headers. - */ - void (*on_stream_headers)(void *ctx, - uint64_t stream_id, - const struct http3_headers_t *headers, - bool fin); - /** - * Called when the stream has buffered data to read. - */ - void (*on_stream_data)(void *ctx, uint64_t stream_id); - /** - * Called when the stream is finished. - */ - void (*on_stream_finished)(void *ctx, uint64_t stream_id); - /** - * Called when the stream receives a RESET_STREAM frame from the peer. - */ - void (*on_stream_reset)(void *ctx, uint64_t stream_id, uint64_t error_code); - /** - * Called when the stream priority is updated. - */ - void (*on_stream_priority_update)(void *ctx, uint64_t stream_id); - /** - * Called when the connection receives a GOAWAY frame from the peer. - */ - void (*on_conn_goaway)(void *ctx, uint64_t stream_id); -} http3_methods_t; -``` -* HTTP/3 callbacks. - - -#### http3_context_t -```c -typedef void *http3_context_t; -``` -* HTTP/3 context. - - -#### http3_header_t - -```c -typedef struct http3_header_t { - uint8_t *name; - uintptr_t name_len; - uint8_t *value; - uintptr_t value_len; -} http3_header_t; -``` -* HTTP/3 header structure. - - -#### http3_headers_t - -```c -typedef struct http3_headers_t http3_headers_t; -``` -* HTTP/3 headers list. - - -#### http3_priority_t - -```c -typedef struct http3_priority_t { - uint8_t urgency; - bool incremental; -} http3_priority_t; -``` -* HTTP/3 stream priority. - diff --git a/website/docs/api_reference/c_quic.md b/website/docs/api_reference/c_quic.md deleted file mode 100644 index d41b8fb74..000000000 --- a/website/docs/api_reference/c_quic.md +++ /dev/null @@ -1,1013 +0,0 @@ ---- -title: C/C++ QUIC API Reference -sidebar_position: 3 ---- - -# C++ QUIC API Reference - -## Preliminaries - -The declarations are all in `tquic.h`, so you just need to include it in each source file: - -```c -#include -``` - -## Common types - -The TQUIC library defines several types that are commonly used by its public functions. - -| Types | Description | -|-------|-------------| -| `quic_config_t` | The behavior of the library can be managed through various settings specified in the `quic_config_t`. | -| `quic_endpoint_t` | Endpoint is an entity that can participate in a QUIC connection by generating, receiving, and processing QUIC packets. Endpoint may maintain one or more QUIC connections. | -| `quic_connection_t` | QUIC connection. | -| `quic_transport_handler_t` | The context provided by the user's code. | -| `quic_transport_methods_t` | The structure lists the callbacks used by the endpoint for interaction with the user code. | -| `quic_packet_out_spec` | Data and metadata of a outbound packet. | - - -## Configurations - - -### QUIC configurations initialization - -#### quic_config_new - -```c -struct quic_config_t *quic_config_new(void); -``` -* Create an instance of `quic_config_t` and initialize it with default configuration. The caller is responsible for the memory of the Config and should properly -destroy it by calling `quic_config_free`. - - -#### quic_config_free - -```c -void quic_config_free(struct quic_config_t *config); -``` -* Destroy QUIC configuration - - -### QUIC configurations customization - -#### quic_config_set_max_idle_timeout -```c -void quic_config_set_max_idle_timeout(struct quic_config_t *config, - uint64_t v); -``` -* Set the `max_idle_timeout` transport parameter in milliseconds. -* The default value is set to `0`, which means that idle timeout is disabled by default. - - -#### quic_config_set_max_udp_payload_size -```c -void quic_config_set_max_udp_payload_size(struct quic_config_t *config, - uint16_t v); -``` -* Set the `max_udp_payload_size` transport parameter in bytes. It limits -the size of UDP payloads that the endpoint is willing to receive. -* The default value is `65527`. - - -#### quic_config_set_initial_max_data -```c -void quic_config_set_initial_max_data(struct quic_config_t *config, - uint64_t v); -``` -* Set the `initial_max_data` transport parameter in bytes. It means the initial - value for the maximum amount of data that can be sent on the connection. -* The default value is `10485760` (10 MB). - - -#### quic_config_set_initial_max_stream_data_bidi_local -```c -void quic_config_set_initial_max_stream_data_bidi_local(struct quic_config_t *config, - uint64_t v); -``` -* Set the `initial_max_stream_data_bidi_local` transport parameter in bytes. -* The default value is `5242880` (5 MB). - - -#### quic_config_set_initial_max_stream_data_bidi_remote -```c -void quic_config_set_initial_max_stream_data_bidi_remote(struct quic_config_t *config, - uint64_t v); -``` -* Set the `initial_max_stream_data_bidi_remote` transport parameter in bytes. -* The default value is `2097152` (2 MB). - - -#### quic_config_set_initial_max_stream_data_uni -```c -void quic_config_set_initial_max_stream_data_uni(struct quic_config_t *config, - uint64_t v); -``` -* Set the `initial_max_stream_data_uni` transport parameter in bytes. -* The default value is `1048576` (1 MB). - - -#### quic_config_set_initial_max_streams_bidi -```c -void quic_config_set_initial_max_streams_bidi(struct quic_config_t *config, - uint64_t v); -``` -* Set the `initial_max_streams_bidi` transport parameter. -* The default value is `200`. - - -#### quic_config_set_initial_max_streams_uni -```c -void quic_config_set_initial_max_streams_uni(struct quic_config_t *config, - uint64_t v); -``` -* Set the `initial_max_streams_uni` transport parameter. -* The default value is `100`. - - -#### quic_config_set_ack_delay_exponent -```c -void quic_config_set_ack_delay_exponent(struct quic_config_t *config, - uint64_t v); -``` -* Set the `ack_delay_exponent` transport parameter. -* The default value is `3`. - - -#### quic_config_set_max_ack_delay -```c -void quic_config_set_max_ack_delay(struct quic_config_t *config, - uint64_t v); -``` -* Set the `max_ack_delay` transport parameter in milliseconds. -* The default value is `25`. - - -#### quic_config_set_congestion_control_algorithm -```c -void quic_config_set_congestion_control_algorithm(struct quic_config_t *config, - enum quic_congestion_control_algorithm v); -``` -* Set congestion control algorithm that the connection would use. -* The default value is `QUIC_CONGESTION_CONTROL_ALGORITHM_CUBIC`. - - -#### quic_config_set_initial_congestion_window -```c -void quic_config_set_initial_congestion_window(struct quic_config_t *config, uint64_t v); -``` -* Set the initial congestion window in packets. -* The default value is 10. - - -#### quic_config_set_min_congestion_window -```c -void quic_config_set_min_congestion_window(struct quic_config_t *config, uint64_t v); -``` -* Set the minimal congestion window in packets. -* The default value is 2. - - -#### quic_config_set_initial_rtt -```c -void quic_config_set_initial_rtt(struct quic_config_t *config, uint64_t v); -``` -* Set the initial RTT in milliseconds. -* The default value is 333ms. - -:::note -The configuration should be changed with caution. Setting a value less than the default -will cause retransmission of handshake packets to be more aggressive. -::: - - -#### quic_config_set_pto_linear_factor -```c -void quic_config_set_pto_linear_factor(struct quic_config_t *config, uint64_t v); -``` -* Set the linear factor for calculating the probe timeout. The endpoint do not backoff the first `v` consecutive probe timeouts. -* The default value is `0`. - - -#### quic_config_set_max_pto -``` -void quic_config_set_max_pto(struct quic_config_t *config, uint64_t v); -``` -* Set the upper limit of probe timeout in milliseconds. A Probe Timeout (PTO) triggers the sending of one or two probe datagrams and enables a connection to recover from loss of tail packets or acknowledgments. See RFC 9002 Section 6.2. -* The probe timeout value has no limit by default. - - -#### quic_config_set_active_connection_id_limit -```c -void quic_config_set_active_connection_id_limit(struct quic_config_t *config, - uint64_t v); -``` -* Set the `active_connection_id_limit` transport parameter. -* The default value is `2`. Lower values will be ignored. - - -#### quic_config_enable_multipath -```c -void quic_config_enable_multipath(struct quic_config_t *config, bool enabled); -``` -* Set the `enable_multipath` transport parameter. -* The default value is false. (Experimental) - - -#### quic_config_set_multipath_algorithm -```c -void quic_config_set_multipath_algorithm(struct quic_config_t *config, enum MultipathAlgorithm v); -``` -* Set the multipath scheduling algorithm -* The default value is MultipathAlgorithm::MinRtt - - -#### quic_config_set_max_connection_window -```c -void quic_config_set_max_connection_window(struct quic_config_t *config, - uint64_t v); -``` -* Set the maximum size of the connection flow control window in bytes. -* The default value is `25165824` (24 MB). - - -#### quic_config_set_max_stream_window -```c -void quic_config_set_max_stream_window(struct quic_config_t *config, - uint64_t v); -``` -* Set the maximum size of the stream flow control window in bytes. -* The default value is `16777216` (16MB). - -#### quic_config_set_max_concurrent_conns -```c -void quic_config_set_max_concurrent_conns(struct quic_config_t *config, - uint32_t v); -``` -* Set the Maximum number of concurrent connections. -* The default value is `1000000` - - -#### quic_config_set_reset_token_key -```c -int quic_config_set_reset_token_key(struct quic_config_t *config, - const uint8_t *token_key, - size_t token_key_len); -``` -* Set the key for reset token generation. The `token_key_len` should be not less than 64. -* The default value is random bytes - - -#### quic_config_set_address_token_lifetime -```c -void quic_config_set_address_token_lifetime(struct quic_config_t *config, - uint64_t seconds); -``` -* Set the lifetime in seconds of address token. -* The default value is `86400` (1 Day) - - -#### quic_config_set_address_token_key -```c -int quic_config_set_address_token_key(struct quic_config_t *config, - const uint8_t *token_keys, - size_t token_keys_len); -``` -* Set the key for address token generation. The `token_key_len` should be a multiple of 16. -* The default value is random bytes - - -#### quic_config_enable_retry -```c -void quic_config_enable_retry(struct quic_config_t *config, - bool enabled); -``` -* Set whether stateless retry is allowed. -* Default is not allowed. - - -#### quic_config_set_cid_len -```c -void quic_config_set_cid_len(struct quic_config_t *config, - uint8_t v); -``` -* Set the length of source cid. The length should not be greater than 20. -* The default value is `8`. - - -#### quic_config_set_send_batch_size -```c -void quic_config_set_send_batch_size(struct quic_config_t *config, - uint16_t v); -``` -* Set the batch size for sending packets. -* The default value is `64`. - - -#### quic_config_set_tls_config -```c -void quic_config_set_tls_config(struct quic_config_t *config, SSL_CTX *ssl_ctx); -``` -* Set TLS config. - - -#### quic_config_set_tls_selector -```c -void quic_config_set_tls_selector(struct quic_config_t *config, - const struct quic_tls_config_select_methods_t *methods, - quic_tls_config_select_context_t context); -``` -* Set TLS config selector. - - -## Endpoint - -### Instantiation and destruction - -#### quic_endpoint_new -```c -struct quic_endpoint_t *quic_endpoint_new(struct quic_config_t *config, - bool is_server, - const struct quic_transport_methods_t *handler_methods, - quic_transport_context_t handler_ctx, - const struct quic_packet_send_methods_t *sender_methods, - quic_packet_send_context_t sender_ctx); -``` -* Create a QUIC endpoint. The caller is responsible for the memory of the Endpoint and properly destroy it by calling `quic_endpoint_free`. - -:::note -The endpoint doesn't own the underlying resources provided by the C caller. It is -the responsibility of the caller to ensure that these resources outlive the -endpoint and release them correctly. -::: - - -#### quic_endpoint_free -```c -void quic_endpoint_free(struct quic_endpoint_t *endpoint); -``` -* Destroy a QUIC endpoint. - - -### Receiving Packets - -#### quic_endpoint_recv -```c -int quic_endpoint_recv(struct quic_endpoint_t *endpoint, - uint8_t *buf, - size_t buf_len, - const struct quic_packet_info_t *info); -``` -* Incoming UDP datagrams are supplied to the endpoint using `quic_endpoint_recv()`. -The endpoint may find an existing connection for the packet and deliver it to the connection, create a new connection, -or respond with a version negotiation packet or stateless reset packet. - - -### Sending Packets - -#### on_packets_send - -```c -typedef struct quic_packet_send_methods_t { - int (*on_packets_send)(void *psctx, - struct quic_packet_out_spec_t *pkts, - unsigned int count); -} quic_packet_send_methods_t; -``` - -* The user specifies a mandatory callback, `on_packets_send`, in the `quic_packet_send_methods_t` structure that -the endpoint utilizes for sending packets. - -* The callback is called when the connection is sending packets out. - -* On success, it returns the number of packets sent. If this is less than `count`, -the connection will retry with a further `on_packets_send()` call to send the -remaining packets. - - -### Timeout events - -#### quic_endpoint_timeout -```c -uint64_t quic_endpoint_timeout(const struct quic_endpoint_t *endpoint); -``` -* Return the amount of time in milliseconds until the next timeout event. - - -#### quic_endpoint_on_timeout -```c -void quic_endpoint_on_timeout(struct quic_endpoint_t *endpoint); -``` -* Process timeout events on the endpoint. - - -### Internal events - -#### quic_endpoint_process_connections -```c -int quic_endpoint_process_connections(struct quic_endpoint_t *endpoint); -``` -* Process internal events of all tickable connections. - - -### Transport Callbacks - -The `quic_transport_methods_t` lists the callbacks used by the endpoint to communicate with the user code. - - -#### on_conn_created -```c -typedef struct quic_transport_methods_t { - void (*on_conn_created)(void *tctx, - struct quic_conn_t *conn); - /* ... */ -} quic_transport_methods_t; -``` - - * `on_conn_created` is called when a new connection has been created. This callback is called - as soon as connection object is created inside the endpoint, but - before the handshake is done. This callback is optional. - - -#### on_conn_established -```c -typedef struct quic_transport_methods_t { - void (*on_conn_established)(void *tctx, - struct quic_conn_t *conn); - /* ... */ -} quic_transport_methods_t; -``` - * `on_conn_established` is called when the handshake is completed. This callback is optional. - - -#### on_conn_closed -```c -typedef struct quic_transport_methods_t { - void (*on_conn_closed)(void *tctx, - struct quic_conn_t *conn); - /* ... */ -} quic_transport_methods_t; -``` - * `on_conn_closed` is called when the connection is closed. The connection is no longer - accessible after this callback returns. It is a good time to clean up - the connection context. This callback is optional. - - -#### on_stream_created -```c -typedef struct quic_transport_methods_t { - void (*on_stream_created)(void *tctx, - struct quic_conn_t *conn, - uint64_t stream_id); - /* ... */ -} quic_transport_methods_t; -``` - * `on_stream_created` is called when the stream is created. This callback is optional. - - -#### on_stream_readable -```c -typedef struct quic_transport_methods_t { - void (*on_stream_readable)(void *tctx, - struct quic_conn_t *conn, - uint64_t stream_id); - /* ... */ -} quic_transport_methods_t; -``` - * `on_stream_readable` is called when the stream is readable. This callback is called when either - there are bytes to be read or an error is ready to be collected. This - callback is optional. - - -#### on_stream_writable -```c -typedef struct quic_transport_methods_t { - void (*on_stream_writable)(void *tctx, - struct quic_conn_t *conn, - uint64_t stream_id); - /* ... */ -} quic_transport_methods_t; -``` - * `on_stream_writable` is called when the stream is writable. This callback is optional. - - -#### on_stream_closed -```c -typedef struct quic_transport_methods_t { - void (*on_conn_closed)(void *tctx, - struct quic_conn_t *conn); - /* ... */ -} quic_transport_methods_t; -``` - * `on_stream_closed` is called when the stream is closed. The stream is no longer accessible - after this callback returns. It is a good time to clean up the stream - context. This callback is optional. - - -#### on_new_token -```c -typedef struct quic_transport_methods_t { - void (*on_new_token)(void *tctx, - struct quic_conn_t *conn, - const uint8_t *token, - size_t token_len); - /* ... */ -} quic_transport_methods_t; -``` - * `on_new_token` is called when client receives a token in NEW_TOKEN frame. This callback - is optional. - - -### Miscellaneous functions - -#### quic_endpoint_exist_connection -```c -bool quic_endpoint_exist_connection(struct quic_endpoint_t *endpoint, - const uint8_t *cid, - size_t cid_len); -``` -* Check whether the given connection exists. - -#### quic_endpoint_get_connection -```c -struct quic_conn_t *quic_endpoint_get_connection(struct quic_endpoint_t *endpoint, uint64_t index); -``` -* Get the connection by index - -#### quic_endpoint_close -```c -void quic_endpoint_close(struct quic_endpoint_t *endpoint, bool force); -``` -* Gracefully or forcibly shutdown the endpoint. -* If `force` is false, cease creating new connections and wait for all active -connections to close. Otherwise, forcibly close all the active connections. - - -## Connection - -### Create connections - -#### quic_endpoint_connect -```c -int quic_endpoint_connect(struct quic_endpoint_t *endpoint, - const struct sockaddr *local, - socklen_t local_len, - const struct sockaddr *remote, - socklen_t remote_len, - const char *server_name, - const uint8_t *session, - size_t session_len, - const uint8_t *token, - size_t token_len, - uint64_t *index); -``` -* Create a client connection. If success, the output parameter `index` carrys the index of the connection. - - -### Closing connections - -#### quic_conn_close -```c -int quic_conn_close(struct quic_conn_t *conn, - bool app, - uint64_t err, - const uint8_t *reason, - size_t reason_len); -``` -* Close the connection. - - - -### Connection Context - -#### quic_conn_set_context -```c -void quic_conn_set_context(struct quic_conn_t *conn, - void *data); -``` -* Set user context for the connection. - - -#### quic_conn_context -```c -void *quic_conn_context(struct quic_conn_t *conn); -``` -* Get user context for the connection. - - -### Connection logging and tracing - -#### quic_conn_set_keylog_fd -```c -void quic_conn_set_keylog_fd(struct quic_conn_t *conn, - int fd); -``` -* Set keylog file - - -#### quic_conn_set_qlog_fd -```c -void quic_conn_set_qlog_fd(struct quic_conn_t *conn, - int fd, - const char *title, - const char *desc); -``` -* Set qlog file - - -#### quic_conn_trace_id -```c -void quic_conn_trace_id(struct quic_conn_t *conn, - const uint8_t **out, - size_t *out_len); -``` -* Return the trace id of the connection - - - -### Miscellaneous functions - -#### quic_conn_index -```c -uint64_t quic_conn_index(struct quic_conn_t *conn); -``` -* Get index of the connection. - - -#### quic_conn_is_server -```c -bool quic_conn_is_server(struct quic_conn_t *conn); -``` -* Check whether the connection is a server connection. - - -#### quic_conn_is_established -```c -bool quic_conn_is_established(struct quic_conn_t *conn); -``` -* Check whether the connection handshake is complete. - - -#### quic_conn_is_resumed -```c -bool quic_conn_is_resumed(struct quic_conn_t *conn); -``` -* Check whether the connection is created by a resumed handshake. - - -#### quic_conn_is_in_early_data -```c -bool quic_conn_is_in_early_data(struct quic_conn_t *conn); -``` -* Check whether the connection has a pending handshake that has progressed - enough to send or receive early data. - - -#### quic_conn_is_multipath -```c -bool quic_conn_is_multipath(struct quic_conn_t *conn); -``` - * Check whether the established connection works in multipath mode. - - -#### quic_conn_application_proto -```c -void quic_conn_application_proto(struct quic_conn_t *conn, - const uint8_t **out, - size_t *out_len); -``` -* Return the negotiated application level protocol. - - -#### quic_conn_server_name -```c -void quic_conn_server_name(struct quic_conn_t *conn, - const uint8_t **out, - size_t *out_len); -``` -* Return the server name in the TLS SNI extension. - - -#### quic_conn_session -```c -void quic_conn_session(struct quic_conn_t *conn, - const uint8_t **out, - size_t *out_len); -``` -* Return the session data used by resumption. - - -#### quic_conn_is_draining -```c -bool quic_conn_is_draining(struct quic_conn_t *conn); -``` -* Check whether the connection is draining. - - -#### quic_conn_is_closed -```c -bool quic_conn_is_closed(struct quic_conn_t *conn); -``` -* Check whether the connection is closing. - - -#### quic_conn_is_idle_timeout -```c -bool quic_conn_is_idle_timeout(struct quic_conn_t *conn); -``` -* Check whether the connection was closed due to idle timeout. - - -#### quic_conn_is_reset -```c -bool quic_conn_is_reset(struct quic_conn_t *conn); -``` -* Check whether the connection was closed due to stateless reset. - - -#### quic_conn_peer_error -```c -bool quic_conn_peer_error(struct quic_conn_t *conn, - bool *is_app, - uint64_t *error_code, - const uint8_t **reason, - size_t *reason_len); -``` -* Returns the error from the peer, if any. - - -#### quic_conn_local_error -```c -bool quic_conn_local_error(struct quic_conn_t *conn, - bool *is_app, - uint64_t *error_code, - const uint8_t **reason, - size_t *reason_len); -``` -* Returns the local error, if any. - - - -## Stream - -### Create streams - -#### quic_stream_new -```c -int quic_stream_new(struct quic_conn_t *conn, - uint64_t stream_id, - uint8_t urgency, - bool incremental); -``` -* Create a stream with specified priority. - -### Stream priorities - -#### quic_stream_set_priority -```c -int quic_stream_set_priority(struct quic_conn_t *conn, - uint64_t stream_id, - uint8_t urgency, - bool incremental); -``` -* Set the priority for a stream. - -### Stream events - -To register or unregister an interest in a read or write event, use the following functions: - -#### quic_stream_wantwrite -```c -int quic_stream_wantwrite(struct quic_conn_t *conn, - uint64_t stream_id, - bool want); -``` -* Set want write flag for a stream. - -#### quic_stream_wantread -```c -int quic_stream_wantread(struct quic_conn_t *conn, - uint64_t stream_id, - bool want); -``` -* Set want read flag for a stream. - -### Reading from streams - -#### quic_stream_read -```c -ssize_t quic_stream_read(struct quic_conn_t *conn, - uint64_t stream_id, - uint8_t *out, - size_t out_len, - bool *fin); -``` -* Read data from a stream. - - -### Writing to streams - -#### quic_stream_write -```c -ssize_t quic_stream_write(struct quic_conn_t *conn, - uint64_t stream_id, - const uint8_t *buf, - size_t buf_len, - bool fin); -``` -* Write data to a stream. - -### Closing streams - -#### quic_stream_shutdown -```c -int quic_stream_shutdown(struct quic_conn_t *conn, - uint64_t stream_id, - enum quic_shutdown direction, - uint64_t err); -``` -* Shutdown stream reading or writing. - - - -### Stream context - -#### quic_stream_set_context -```c -int quic_stream_set_context(struct quic_conn_t *conn, - uint64_t stream_id, - void *data); -``` -* Set user context for a stream. - - -#### quic_stream_context -```c -void *quic_stream_context(struct quic_conn_t *conn, - uint64_t stream_id); - -``` -* Return the stream’s user context. - - - -### Miscellaneous functions - -#### quic_stream_capacity -```c -ssize_t quic_stream_capacity(struct quic_conn_t *conn, - uint64_t stream_id); -``` -* Return the stream’s send capacity in bytes. - - -#### quic_stream_finished -```c -bool quic_stream_finished(struct quic_conn_t *conn, - uint64_t stream_id); -``` -* Return true if all the data has been read from the stream. - - - -## Path - -### Create paths - -#### quic_conn_add_path -```c -int quic_conn_add_path(struct quic_conn_t *conn, - const struct sockaddr *local, - socklen_t local_len, - const struct sockaddr *remote, - socklen_t remote_len, - uint64_t *index); -``` - * Add a new path on the client connection. - - -### Miscellaneous functions -#### quic_conn_active_path -```c -bool quic_conn_active_path(const struct quic_conn_t *conn, - struct quic_path_address_t *a); -``` -* Return the address of the active path - - -#### quic_path_address_iter_t -```c -struct quic_path_address_iter_t *quic_conn_paths(struct quic_conn_t *conn); -``` -* Return an iterator over path addresses. The caller should properly destroy it by calling `quic_four_tuple_iter_free`. - - -#### quic_conn_path_iter_next -```c -bool quic_conn_path_iter_next(struct quic_path_address_iter_t *iter, - struct quic_path_address_t *a); -``` -* Return the address of the next path. - - -#### quic_conn_path_iter_free -```c -void quic_conn_path_iter_free(struct quic_path_address_iter_t *iter); -``` -* Destroy the FourTupleIter - - -## Miscellaneous types and functions - -### Miscellaneous types - -#### quic_transport_handler_t -```c -typedef void *quic_transport_context_t; - -typedef struct quic_transport_handler_t { - const struct quic_transport_methods_t *methods; - quic_transport_context_t context; -} quic_transport_handler_t; -``` - -#### quic_packet_out_spec_t - -```c -typedef struct quic_packet_out_spec_t { - const struct iovec *iov; - size_t iovlen; - const void *src_addr; - socklen_t src_addr_len; - const void *dst_addr; - socklen_t dst_addr_len; -} quic_packet_out_spec_t; -``` -* Outgoing packets. - - -#### quic_shutdown - -```c -typedef enum quic_shutdown { - QUIC_SHUTDOWN_READ = 0, - QUIC_SHUTDOWN_WRITE = 1, -} quic_shutdown; - -``` -* The stream's side to shutdown. - - -#### quic_path_address_iter_t -```c -typedef struct quic_path_address_iter_t quic_path_address_iter_t; -``` -* An iterator over FourTuple. - - -#### quic_congestion_control_algorithm -```c -typedef enum quic_congestion_control_algorithm { - QUIC_CONGESTION_CONTROL_ALGORITHM_CUBIC, - QUIC_CONGESTION_CONTROL_ALGORITHM_BBR, - QUIC_CONGESTION_CONTROL_ALGORITHM_BBR3, - QUIC_CONGESTION_CONTROL_ALGORITHM_COPA, -} quic_congestion_control_algorithm; -``` -* Congestion control algorithms. - - -#### quic_multipath_algorithm -```c -typedef enum quic_multipath_algorithm { - QUIC_MULTIPATH_ALGORITHM_MIN_RTT, - QUIC_MULTIPATH_ALGORITHM_REDUNDANT, - QUIC_MULTIPATH_ALGORITHM_ROUND_ROBIN, -} quic_multipath_algorithm; -``` -* Multipath scheduling algorithms. - - -#### quic_log_level -```c -typedef enum quic_log_level { - QUIC_LOG_LEVEL_OFF, - QUIC_LOG_LEVEL_ERROR, - QUIC_LOG_LEVEL_WARN, - QUIC_LOG_LEVEL_INFO, - QUIC_LOG_LEVEL_DEBUG, - QUIC_LOG_LEVEL_TRACE, -} quic_log_level; -``` -* An enum representing the available verbosity level filters of the logger. - - -### Miscellaneous functions - -#### quic_set_logger -```c -void quic_set_logger(void (*cb)(const uint8_t *line, void *argp), void *argp, quic_log_level level); -``` -* Set callback for logging. -* `cb` is a callback function that will be called for each log message. `line` is a null-terminated log message and `argp` is user-defined data that will be passed to the callback. - diff --git a/website/docs/api_reference/rust_h3.md b/website/docs/api_reference/rust_h3.md deleted file mode 100644 index c2a778dad..000000000 --- a/website/docs/api_reference/rust_h3.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Rust HTTP/3 API Reference -sidebar_position: 2 ---- - -The Rust documentation of TQUIC is autogenerated by cargo and is available at the [docs.rs](https://docs.rs/tquic). diff --git a/website/docs/api_reference/rust_quic.md b/website/docs/api_reference/rust_quic.md deleted file mode 100644 index 7f6e3b9fe..000000000 --- a/website/docs/api_reference/rust_quic.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Rust QUIC API Reference -sidebar_position: 1 ---- - -The Rust documentation of TQUIC is autogenerated by cargo and is available at the [docs.rs](https://docs.rs/tquic). diff --git a/website/docs/faq/_category_.json b/website/docs/faq/_category_.json deleted file mode 100644 index 6449369e9..000000000 --- a/website/docs/faq/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Frequently Asked Questions", - "position": 7, - "link": { - "type": "generated-index", - "description": "Frequently asked questions about the TQUIC library." - } -} diff --git a/website/docs/faq/development.md b/website/docs/faq/development.md deleted file mode 100644 index 41e5d0ab0..000000000 --- a/website/docs/faq/development.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Development -sidebar_position: 5 ---- - -# Development - -## What are the regulations for code review? -Please refer to [this document](../how_to_contribute/contribute_codes#certain-regulations-about-code-review). - -## How to test the TQUIC library? -TQUIC currently includes extensive testing, including unit testing, fuzzing testing, integration testing, -performance benchmarking, interoperability testing, and protocol conformance testing. - -If you have any questions, please contact [the project maintainers](https://github.com/tencent/tquic/blob/develop/MAINTAINERS.md) -further for guidance. diff --git a/website/docs/faq/installation.md b/website/docs/faq/installation.md deleted file mode 100644 index 90e8bb10e..000000000 --- a/website/docs/faq/installation.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Installation -sidebar_position: 1 ---- - -# Installation - -## Failed to run custom build command for TQUIC? - -If you get a `not found CMakeLists.txt` error, it is likely because the submodules of tquic were not downloaded properly. - -``` -error: failed to run custom build command for `tquic` - -... - CMake Error: The source directory "third_party/boringssl" does not appear to contain CMakeLists.txt. - Specify --help for usage, or press the help button on the CMake GUI. - thread 'main' panicked at ' - command did not execute successfully, got: exit status: 1 - - build script failed, must exit now', index.crates.io/cmake-0.1.50/src/lib.rs:1098:5 - note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace -``` - -The source code of tquic should be cloned using the `--recursive` option: -``` -git clone https://github.com/tencent/tquic --recursive -``` - -If the source code has already been cloned, but you forgot to use the option `--recursive`, you can manually download the submodules like this: -``` -git submodule init && git submodule update -``` - - -## Not found example tools of TQUIC? - -If you cannot locate the example tools in the directory `./target/release`, it is likely because you forgot to include the build option `--all` or `--release`. - - -## Not found C library of TQUIC? - -If you cannot locate the static or dynamic c library of tquic in the directory `./target/release`, it is likely because you forgot to include the build option `-F ffi` or `--release`. - diff --git a/website/docs/faq/performance.md b/website/docs/faq/performance.md deleted file mode 100644 index 0e65736e9..000000000 --- a/website/docs/faq/performance.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Performance -sidebar_position: 3 ---- - -# Performance - -## How fast is TQUIC? - -[The document](../further_readings/benchmark) includes a benchmark report of different QUIC libraries, which you can refer to for more information. - -It is important to note that the performance of the QUIC library greatly depends on the specific features being used and the environment in which it is running. Therefore, we encourage users to conduct their own benchmarks using a configuration similar to what they plan on using in production. diff --git a/website/docs/faq/trouble_shooting.md b/website/docs/faq/trouble_shooting.md deleted file mode 100644 index d347d5726..000000000 --- a/website/docs/faq/trouble_shooting.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Trouble shooting -sidebar_position: 4 ---- - -# Trouble shooting - -## How to analyze encrypted QUIC traffic? - -The TLS key log can be saved by using the `--keylog-file` option in example tools or by utilizing the [keylog API](../api_reference/c_quic#connection-logging-and-tracing) for your own programs. - -This saved key log file can then be used to decrypt QUIC traffic in Wireshark. - -:::tip -In Wireshark, navigate to `Edit-> Preferences-> Protocols-> TLS`, and update the `(Pre)-Master-Secret log filename preference` with the path of the TLS key log. -::: diff --git a/website/docs/faq/usage.md b/website/docs/faq/usage.md deleted file mode 100644 index a79e4cc68..000000000 --- a/website/docs/faq/usage.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Usage -sidebar_position: 2 ---- - -# Usage - - -## Whether TQUIC supports mobile platforms? - -TQUIC is implemented in the Rust language, enabling it to be run on any platform supported by Rust. TQUIC currently supports Linux, MacOS, iOS, and Android. - - -## Which versions of the QUIC protocol are supported? - -TQUIC currently supports [QUIC v1](https://datatracker.ietf.org/doc/html/rfc9000). - diff --git a/website/docs/further_readings/_category_.json b/website/docs/further_readings/_category_.json deleted file mode 100644 index f9c6147f3..000000000 --- a/website/docs/further_readings/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Further Readings", - "position": 8, - "link": { - "type": "generated-index", - "description": "More supplemental documents about the TQUIC library." - } -} diff --git a/website/docs/further_readings/benchmark.md b/website/docs/further_readings/benchmark.md deleted file mode 100644 index 2ff7aa065..000000000 --- a/website/docs/further_readings/benchmark.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Benchmark -sidebar_position: 2 ---- - -# Performance benchmarking - -## Methods for testing - -The purpose of this document is to evaluate the performance of the TQUIC library and compare it with that of several widely used [QUIC implementations](comparison.md). -It is important to note that there are numerous QUIC implementations currently available in the industry. However, we only selected some of them for comparison. The primary reasons for our choices are detailed in [this article](./comparison.md). - -### Testbed - -The detailed parameters of the test machine are as follows. Both the client and server programs are deployed on the same machine, but assigned to different CPU cores in order to prevent interference. The deployment allows for easy automation of benchmarking. - -| Category | Description | -| -------- | ----------- | -| CPU | AMD EPYC 7K62 48-Core | -| Memory | 512G | -| Disk | SSSTC ER2-GD480 | -| OS | Linux 4.14 | - -**Server-side Setup**: The server example programs from each QUIC implementation are chosen for testing, using the most recent stable version, as described below. - -| Core Maintainers | QUIC Implementations | -| ---------------- | -------------------- | -| Google | QUICHE-G [v118.0.5983.1](https://chromium.googlesource.com/chromium/src.git/+/refs/tags/118.0.5983.1) | -| Nginx | NGINX-QUIC [v1.25.2](http://nginx.org/en/download.html) | -| Cloudflare | QUICHE-CF [v0.18.0](https://github.com/cloudflare/quiche/releases/tag/0.18.0) | -| LiteSpeed | LSQUIC [v4.0.1](https://github.com/litespeedtech/lsquic/releases/tag/v4.0.1) | - -The application logic of each server program is simplified to reflect the actual processing overhead of the QUIC stack as closely as possible. For example, the server program from LSQUIC uses regular expressions to extract the file path from the request, which introduces certain performance overhead. Therefore, we have opted to replace the regular expression matching with simple string matching. - -Each server program is compiled in release mode and configured to run in single-thread mode. For detailed configuration parameters, please refer to the [Appendix](benchmark.md#appendix). - - -**Client-side Setup**: The [TQUIC client](https://github.com/tencent/tquic/tools/src/bin/tquic_client.rs) is used as a stress testing tool due to its highly flexible parameters, and support for multiple threads, which helps increase the pressure to a test server. - - -### Scenarios tested - -The application layer protocol used for testing was HTTP/3, while various typical scenarios were tested, including web browsing, image loading, and video playback. We conducted tests in both long connection and short connection scenarios. - -- **Long connection scenario**: The purpose of the scenario is to test the protocol stack's capacity for handling requests by constantly sending multiple requests per connection. The selected sizes of page, image, and video files were 5KB, 15KB, and 2MB respectively according to the median statistics from the [HTTP Archive](https://httparchive.org/reports/page-weight#bytesHtml). - -- **Short connection scenario**: The purpose of the scenario is to test the protocol stack's capacity for handshake by sending only one request per connection. Additionally, we intentionally selected a relatively small response size of 1KB. - -The RPS (number of successful requests per second) of each implementation is compared under extreme pressure, while all implementations achieve a maximum CPU utilization rate of 100% (unless otherwise noted). - -:::note -The future work may involve the addition of more complex test scenarios. -::: - -## Results - -### Long connection scenario -As shown below, TQUIC outperforms the other implementations under various conditions. For example, TQUIC is four to five times faster than the most widely used QUICHE-G; -The performance of TQUIC consistently surpasses that of LSQUIC under various conditions, by up to 20%, despite the fact that LSQUIC is written in C and considered the best performing among these alternative implementations. - -![15K](benchmark_long_15k.png) -![50K](benchmark_long_50k.png) -![2M](benchmark_long_2m.png) - - -### Short connection scenario - -TQUIC outperforms the other implementations by at least 20% in the short connection scenario, as shown in the figure below. -Note that the CPU consumption of QUICHE-G and LSQUIC is 30% and 60%, respectively, and the CPU consumption of the other implementations is 100%. - -![1K](benchmark_short.png) - - -## Appendix - -### Server configurations - -**QUICHE-G** -``` -./quic_server --port=${port} --quic_response_cache_dir=${file_dir} \ - --certificate_file=server.crt --key_file=server.pkcs8 -``` - -**NGINX-QUIC** -``` -events { - worker_connections 100000; -} - -http { - access_log off; - server { - listen ${port} quic reuseport; - keepalive_requests 1000000; - ssl_certificate server.crt; - ssl_certificate_key server.key; - ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; - root ${file_dir}; - } -} -``` - -**QUICHE-CF** -``` -./quiche-server --listen [::]:${port} --root ${file_dir} \ - --cert server.crt --key server.key --disable-gso --no-retry -``` - - -**LSQUIC** -``` -./http_server -c example.org,server.crt,server.key -s 0.0.0.0:${port} -r ${file_dir} -``` - -**TQUIC** -``` -./server -l 0.0.0.0:${port} --log-level OFF --root ${file_dir} -c server.crt -k server.key -``` - - -### Client configurations - -The command for stress tests is as follows: -``` -./client -p --max-requests-per-thread 0 --log-level OFF --disable-stateless-reset \ - --threads ${threads} \ - --max-concurrent-conns ${max_concurrent_conns} \ - --max-requests-per-conn ${max_requests_per_conn} \ - --max-concurrent-requests ${max_concurrent_requests} \ - --send-udp-payload-size ${send_udp_payload_size} \ - --duration ${duration} \ - --handshake-timeout ${handshake_timeout} \ - --idle-timeout ${idle_timeout} \ - https://${host}:${port}/${file} -``` - -The parameters' meanings are as follows: -- **threads**: The number of threads to use. -- **max_concurrent_conns**: The number of concurrent connections maintained per thread. -- **max_requests_per_conn**: The maximum number of requests per connection. 0 means no limit. -- **max_concurrent_requests**: The number of concurrent streams per connection. -- **recv_udp_payload_size**: Specify the `max_udp_payload_size` transport parameter. The value for the tests is 1350. -- **duration**：The duration for testing. -- **handshake_timeout**: The handshake timeout. The value for the tests is 5 seconds. -- **idle_timeout**：The connection idle timeout. The value for the tests is 5 seconds. -- **host**：The listening address for the server. -- **port**：The listening port for the server. -- **file**：The requested resource by the client. - diff --git a/website/docs/further_readings/benchmark_long_15k.png b/website/docs/further_readings/benchmark_long_15k.png deleted file mode 100644 index 7d4b02eb1..000000000 Binary files a/website/docs/further_readings/benchmark_long_15k.png and /dev/null differ diff --git a/website/docs/further_readings/benchmark_long_2m.png b/website/docs/further_readings/benchmark_long_2m.png deleted file mode 100644 index 3dd6dfe03..000000000 Binary files a/website/docs/further_readings/benchmark_long_2m.png and /dev/null differ diff --git a/website/docs/further_readings/benchmark_long_50k.png b/website/docs/further_readings/benchmark_long_50k.png deleted file mode 100644 index a4f921084..000000000 Binary files a/website/docs/further_readings/benchmark_long_50k.png and /dev/null differ diff --git a/website/docs/further_readings/benchmark_short.png b/website/docs/further_readings/benchmark_short.png deleted file mode 100644 index 420051d79..000000000 Binary files a/website/docs/further_readings/benchmark_short.png and /dev/null differ diff --git a/website/docs/further_readings/comparison.md b/website/docs/further_readings/comparison.md deleted file mode 100644 index 2b10d3330..000000000 --- a/website/docs/further_readings/comparison.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Comparison -sidebar_position: 1 ---- - -# Comparison to alternatives - -The industry currently offers numerous available [QUIC implementations](https://github.com/quicwg/base-drafts/wiki/Implementations). However, we have selected only a few for comparative analysis. The main reasons behind our choice are as follows: - -- **Open source project**: This facilitates the establishment of a test environment and also enables further code analysis. For instance, we didn't choose AppleQUIC or F5 QUIC. -- **Written in a system programming language**: Some implementations may not be aimed at high performance and therefore cannot be fairly compared to those based on system programming languages. We didn't choose implementations based on Python/Haskell/Java etc. -- **Widely used**: It is used by well-known open-source projects or large-scale network service providers. - -:::tip -The following analysis may not be accurate as each project is currently under active development. The document may be updated or supplemented with new implementations at a later time. -::: - - -## Basic information - -| Category | QUICHE-G | NGINX-QUIC | QUICHE-CF | LSQUIC | TQUIC | -| ------------- | ---------- | ------ | ----- | ---- | ------------- | -| Primary maintainers | Google | NGINX Community | Cloudflare | LiteSpeed | TQUIC Community | -| Code repository | [google/quiche](https://github.com/google/quiche) | [quic](https://github.com/nginx/nginx/tree/master/src/event/quic) | [cloudflare/quiche](https://github.com/cloudflare/quiche) | [lsquic](https://github.com/litespeedtech/lsquic) | [tquic](https://github.com/tencent/tquic) | -| Programming language | C++ | C | RUST | C | RUST | -| Lines of code | About 150,000 | About 20,000 | About 40,000 | About 100,000 | About 50,000 | -| Typical Use Cases | Chromium, Envoy | Nginx | Cloudflare edge network | LiteSpeed WebServer, Web ADC | Tencent Cloud EdgeOne | - -The implementations selected for the comparison with TQUIC are shown in the table above. Two of them are used by well-known open source projects([Envoy](https://www.envoyproxy.io/)/[Nginx](https://nginx.org/)) and two are used by popular CDN vendors([Cloudflare](https://www.cloudflare.com/)/[LiteSpeed](https://www.litespeedtech.com/)). They are all written in high-performance systems programming languages. - -The NGINX-QUIC codebase, despite having the fewest lines of code, currently lacks comments, unit tests, and certain important features. In contrast, the TQUIC codebase has extensive unit tests and detailed comments that make up approximately half of its total lines of code. This makes it easier for contributors to participate. - - -## Performance and throughput - -| Category | QUICHE-G | NGINX-QUIC | QUICHE-CF | LSQUIC | TQUIC | -| ------------- | ---------- | ------ | ----- | ---- | ---- | -| Performance | Normal | Good | Good | Better | Best | -| Congestion control | CUBIC, BBR, BBRv2, Reno | Reno | CUBIC, BBR | CUBIC, BBR | CUBIC, BBR, BBRv3, COPA | -| Multipath | Not supported | Not supported | Not supported | Not supported | Support Multipath QUIC | - - -The performance of TQUIC surpasses that of the other implementations significantly. For further details on the benchmark methodology and results, please refer to the [benchmark report](benchmark.md). - -Popular congestion control algorithms are supported by all these implementations, except for NGINX-QUIC. - -TQUIC is the only one of these implementations that supports multipath QUIC, thereby enhancing both throughput and reliability. Some other libraries, including QUICHE-CF, are currently in development to provide support for multipath QUIC. - - -## Quality and stability - -| Category | QUICHE-G | NGINX-QUIC | QUICHE-CF | LSQUIC | TQUIC | -| ------------- | ---------- | ------ | ----- | ---- | ---- | -| Testing | Extensive unit tests | No unit tests; Few integration tests | Extensive unit tests | Many unit tests, but limited for high-level components | Extensive unit tests | -| Memory safety | Not supported | Not supported | Supported | Not supported | Supported | - -Most implementations have extensive unit tests, whereas NGINX-QUIC, as mentioned earlier, lacks them and only a limited number of integration tests for QUIC can be found in a [separate repository](https://hg.nginx.org/nginx-tests/file/tip). - -TQUIC and QUICHE-CF are written in a memory-safe language, making them immune to Buffer Overflow vulnerability and other memory-related bugs. In contrast, LSQUIC, a C-based library that was open-sourced in 2017, has been consistently [identifying and resolving memory-related bugs](https://github.com/litespeedtech/lsquic/blob/master/CHANGELOG) throughout the years. This is very common for implementations written in C or C++. - - -## Usability and observability - -| Category | QUICHE-G | NGINX-QUIC | QUICHE-CF | LSQUIC | TQUIC | -| ------------- | ---------- | ------ | ----- | ---- | ---- | -| Library APIs | C++ | C | Rust/C/C++ | C | Rust/C/C++ | -| API documentation | No documentation | No documentation | Detailed for RUST; Limited for C/C++ | Very detailed | Very detailed | -| SSL Keylog | Not supported | Supported | Supported | Supported | Supported | -| QLOG | Not supported | Not supported | Supported | Not supported | Supported | - -The APIs for both TQUIC and QUICHE-CF are available in multiple languages, along with detailed API documentation. The absence of comprehensive API documentation for QUICHE-G poses challenges for average users. Currently, NGINX-QUIC is not a standalone QUIC library and only works with Nginx. - -The absence of an SSL Keylog or QLOG can make certain implementations (QUICHE-G/NGINX-QUIC/LSQUIC) less convenient for troubleshooting purposes. - - -:::tip -The document is open-source. Please help improve it by filing issues or pull requests. -::: - diff --git a/website/docs/further_readings/conformance.md b/website/docs/further_readings/conformance.md deleted file mode 100644 index 7d600a324..000000000 --- a/website/docs/further_readings/conformance.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Conformance -sidebar_position: 3 ---- - -# Protocol conformance test - -We perform protocol conformance tests based on the methodology introduced in a paper titled ["Formal specification and testing of QUIC"](https://dl.acm.org/doi/10.1145/3341302.3342087) published at SIGCOMM 2019. We have upgraded the initial formal specification to incorporate support for QUIC v1 and resolved some issues in the ivy toolchain. - - -## Formal specification of QUIC - -The formal specification of the QUIC protocol is written in the [Ivy](http://microsoft.github.io/ivy/) language. It can be used to test implementations of QUIC using compositional specification-based testing methods. - -The currently targeted version is IETF QUIC v1. - - -## How it works - -The specification is written in a way that allows monitoring of packets on the wire, as well as modular testing of implementations. - -That is, from the specification we can produce an automated tester that takes one role in the protocol. The tester uses symbolic execution and an SMT solver to randomly generate protocol traffic that complies with the specification. For example, if the tester is taking the client role, it generates packets that are legal for the client to send, and these are transmitted to the server being tested. The responses sent by the server are then checked for compliance with the specification. - - -## Advantages - -This approach has certain advantages when compared to interoperability testing. - -* The specification-based tester can generate stimulus that can't be produced by any current implementation and perhaps would only be produced by attackers. Because it is randomized, it tends to generate unusual cases that specifiers may not have considered. - -* It checks for actual specification compliance and not just for correct interopation. Compliance with the specification is important for future protocol developers who need to ensure compatibility with legacy implementations. - -* The formal specification can be seen as documentation, since it gives an unambiguous interpretation of statements made in natural language in the IETF specification documents. - - -## Usage - -The formal specification of QUIC v1 will soon be made available as open source, along with detailed instructions on how to use it in its project documentation. - diff --git a/website/docs/further_readings/resources.md b/website/docs/further_readings/resources.md deleted file mode 100644 index 107f9895d..000000000 --- a/website/docs/further_readings/resources.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Resources -sidebar_position: 4 ---- - -# Resources - -## Specifications - -* IETF QUIC Working Group: -https://quicwg.org/ - - -## Tools - -* Tools for analysing, debugging and visualising QUIC: -https://github.com/quicwg/base-drafts/wiki/Tools - - -## Implementers - -* Implementations of QUIC: -https://github.com/quicwg/base-drafts/wiki/Implementations diff --git a/website/docs/getting_started/_category_.json b/website/docs/getting_started/_category_.json deleted file mode 100644 index 9c8d71c39..000000000 --- a/website/docs/getting_started/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Getting Started", - "position": 2, - "link": { - "type": "generated-index", - "description": "Quickly get started with TQUIC." - } -} diff --git a/website/docs/getting_started/demo.md b/website/docs/getting_started/demo.md deleted file mode 100644 index 0d1a5dc98..000000000 --- a/website/docs/getting_started/demo.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Example tools -sidebar_position: 2 ---- - -# Example tools - -:::tip - -The example tools are built by adding an option `--all` to the `cargo build` command. They are generated and saved in the directory `./target/release/`. -::: - - -## Server - -### Run the quic server -```bash -./tquic_server -c cert.crt -k cert.key -l 127.0.0.1:8443 -``` - -The server is configured to listen on the address `127.0.0.1:8443` and act as an HTTP/3 file server. - -The test certificate `cert.crt` and private key `cert.key` can be found in the directory `./src/tls/testdata/`. They can also be generated using the following commands: -``` -openssl genpkey -algorithm RSA -out cert.key -pkeyopt rsa_keygen_bits:2048 -openssl req -new -key cert.key -out cert.csr -subj "/C=CN/ST=beijing/L=beijing/O=tquic/CN=example.org" -openssl x509 -req -in cert.csr -signkey cert.key -out cert.crt -``` - -### More options - -You can explore different options by using the `-h` option for help information. -```bash -./tquic_server -h -``` - -The output is as follows: -``` -Usage: tquic_server [OPTIONS] - -Options: - -c, --cert - TLS certificate in PEM format [default: ./cert.crt] - -k, --key - TLS private key in PEM format [default: ./cert.key] - --log-level - Log level, support OFF/ERROR/WARN/INFO/DEBUG/TRACE [default: INFO] - -l, --listen - Address to listen [default: 0.0.0.0:4433] - --root - Document root directory [default: ./] - --ticket-key - Session ticket key [default: "tquic key"] - --address-token-key - Key for generating address token - --enable-retry - Enable stateless retry - --disable-stateless-reset - Disable stateless reset - --congestion-control-algor - Congestion control algorithm [default: CUBIC] - --initial-congestion-window - Initial congestion window in packets [default: 32] - --min-congestion-window - Minimum congestion window in packets [default: 4] - --enable-multipath - Enable multipath transport - --multipath-algor - Multipath scheduling algorithm [default: MINRTT] - --recv-udp-payload-size - Set max_udp_payload_size transport parameter [default: 65527] - --send-udp-payload-size - Set the maximum outgoing UDP payload size [default: 1200] - --handshake-timeout