{"id":13461743,"url":"https://github.com/cloudflare/quiche","last_synced_at":"2025-05-13T10:52:06.906Z","repository":{"id":37270084,"uuid":"150891532","full_name":"cloudflare/quiche","owner":"cloudflare","description":"🥧 Savoury implementation of the QUIC transport protocol and HTTP/3","archived":false,"fork":false,"pushed_at":"2025-05-12T21:02:16.000Z","size":22626,"stargazers_count":10140,"open_issues_count":235,"forks_count":810,"subscribers_count":161,"default_branch":"master","last_synced_at":"2025-05-12T21:39:11.497Z","etag":null,"topics":["http3","network-programming","protocol","quic","rust"],"latest_commit_sha":null,"homepage":"https://docs.quic.tech/quiche/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-09-29T18:22:05.000Z","updated_at":"2025-05-12T17:03:21.000Z","dependencies_parsed_at":"2023-12-20T17:25:53.213Z","dependency_job_id":"64c5986a-3ce1-41e4-9bc2-11e16c2cc79f","html_url":"https://github.com/cloudflare/quiche","commit_stats":{"total_commits":1699,"total_committers":88,"mean_commits":"19.306818181818183","dds":0.2978222483814008,"last_synced_commit":"0b37da1cc564e40749ba650febd40586a4355be4"},"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fquiche","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fquiche/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fquiche/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fquiche/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/quiche/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253829856,"owners_count":21970988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http3","network-programming","protocol","quic","rust"],"created_at":"2024-07-31T11:00:56.058Z","updated_at":"2025-05-13T10:52:06.872Z","avatar_url":"https://github.com/cloudflare.png","language":"Rust","readme":"![quiche](quiche.svg)\n\n[![crates.io](https://img.shields.io/crates/v/quiche.svg)](https://crates.io/crates/quiche)\n[![docs.rs](https://docs.rs/quiche/badge.svg)](https://docs.rs/quiche)\n[![license](https://img.shields.io/github/license/cloudflare/quiche.svg)](https://opensource.org/licenses/BSD-2-Clause)\n![build](https://img.shields.io/github/actions/workflow/status/cloudflare/quiche/stable.yml?branch=master)\n\n[quiche] is an implementation of the QUIC transport protocol and HTTP/3 as\nspecified by the [IETF]. It provides a low level API for processing QUIC packets\nand handling connection state. The application is responsible for providing I/O\n(e.g. sockets handling) as well as an event loop with support for timers.\n\nFor more information on how quiche came about and some insights into its design\nyou can read a [post] on Cloudflare's blog that goes into some more detail.\n\n[quiche]: https://docs.quic.tech/quiche/\n[ietf]: https://quicwg.org/\n[post]: https://blog.cloudflare.com/enjoy-a-slice-of-quic-and-rust/\n\nWho uses quiche?\n----------------\n\n### Cloudflare\n\nquiche powers Cloudflare edge network's [HTTP/3 support][cloudflare-http3]. The\n[cloudflare-quic.com](https://cloudflare-quic.com) website can be used for\ntesting and experimentation.\n\n### Android\n\nAndroid's DNS resolver uses quiche to [implement DNS over HTTP/3][android-http3].\n\n### curl\n\nquiche can be [integrated into curl][curl-http3] to provide support for HTTP/3.\n\n[cloudflare-http3]: https://blog.cloudflare.com/http3-the-past-present-and-future/\n[android-http3]: https://security.googleblog.com/2022/07/dns-over-http3-in-android.html\n[curl-http3]: https://github.com/curl/curl/blob/master/docs/HTTP3.md#quiche-version\n\nGetting Started\n---------------\n\n### Command-line apps\n\nBefore diving into the quiche API, here are a few examples on how to use the\nquiche tools provided as part of the [quiche-apps](apps/) crate.\n\nAfter cloning the project according to the command mentioned in the [building](#building) section, the client can be run as follows:\n\n```bash\n $ cargo run --bin quiche-client -- https://cloudflare-quic.com/\n```\n\nwhile the server can be run as follows:\n\n```bash\n $ cargo run --bin quiche-server -- --cert apps/src/bin/cert.crt --key apps/src/bin/cert.key\n```\n\n(note that the certificate provided is self-signed and should not be used in\nproduction)\n\nUse the `--help` command-line flag to get a more detailed description of each\ntool's options.\n\n### Configuring connections\n\nThe first step in establishing a QUIC connection using quiche is creating a\n[`Config`] object:\n\n```rust\nlet mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;\nconfig.set_application_protos(\u0026[b\"example-proto\"]);\n\n// Additional configuration specific to application and use case...\n```\n\nThe [`Config`] object controls important aspects of the QUIC connection such\nas QUIC version, ALPN IDs, flow control, congestion control, idle timeout\nand other properties or features.\n\nQUIC is a general-purpose transport protocol and there are several\nconfiguration properties where there is no reasonable default value. For\nexample, the permitted number of concurrent streams of any particular type\nis dependent on the application running over QUIC, and other use-case\nspecific concerns.\n\nquiche defaults several properties to zero, applications most likely need\nto set these to something else to satisfy their needs using the following:\n\n- [`set_initial_max_streams_bidi()`]\n- [`set_initial_max_streams_uni()`]\n- [`set_initial_max_data()`]\n- [`set_initial_max_stream_data_bidi_local()`]\n- [`set_initial_max_stream_data_bidi_remote()`]\n- [`set_initial_max_stream_data_uni()`]\n\n[`Config`] also holds TLS configuration. This can be changed by mutators on\nthe an existing object, or by constructing a TLS context manually and\ncreating a configuration using [`with_boring_ssl_ctx_builder()`].\n\nA configuration object can be shared among multiple connections.\n\n### Connection setup\n\nOn the client-side the [`connect()`] utility function can be used to create\na new connection, while [`accept()`] is for servers:\n\n```rust\n// Client connection.\nlet conn = quiche::connect(Some(\u0026server_name), \u0026scid, local, peer, \u0026mut config)?;\n\n// Server connection.\nlet conn = quiche::accept(\u0026scid, None, local, peer, \u0026mut config)?;\n```\n\n### Handling incoming packets\n\nUsing the connection's [`recv()`] method the application can process\nincoming packets that belong to that connection from the network:\n\n```rust\nlet to = socket.local_addr().unwrap();\n\nloop {\n    let (read, from) = socket.recv_from(\u0026mut buf).unwrap();\n\n    let recv_info = quiche::RecvInfo { from, to };\n\n    let read = match conn.recv(\u0026mut buf[..read], recv_info) {\n        Ok(v) =\u003e v,\n\n        Err(e) =\u003e {\n            // An error occurred, handle it.\n            break;\n        },\n    };\n}\n```\n\n### Generating outgoing packets\n\nOutgoing packet are generated using the connection's [`send()`] method\ninstead:\n\n```rust\nloop {\n    let (write, send_info) = match conn.send(\u0026mut out) {\n        Ok(v) =\u003e v,\n\n        Err(quiche::Error::Done) =\u003e {\n            // Done writing.\n            break;\n        },\n\n        Err(e) =\u003e {\n            // An error occurred, handle it.\n            break;\n        },\n    };\n\n    socket.send_to(\u0026out[..write], \u0026send_info.to).unwrap();\n}\n```\n\nWhen packets are sent, the application is responsible for maintaining a\ntimer to react to time-based connection events. The timer expiration can be\nobtained using the connection's [`timeout()`] method.\n\n```rust\nlet timeout = conn.timeout();\n```\n\nThe application is responsible for providing a timer implementation, which\ncan be specific to the operating system or networking framework used. When\na timer expires, the connection's [`on_timeout()`] method should be called,\nafter which additional packets might need to be sent on the network:\n\n```rust\n// Timeout expired, handle it.\nconn.on_timeout();\n\n// Send more packets as needed after timeout.\nloop {\n    let (write, send_info) = match conn.send(\u0026mut out) {\n        Ok(v) =\u003e v,\n\n        Err(quiche::Error::Done) =\u003e {\n            // Done writing.\n            break;\n        },\n\n        Err(e) =\u003e {\n            // An error occurred, handle it.\n            break;\n        },\n    };\n\n    socket.send_to(\u0026out[..write], \u0026send_info.to).unwrap();\n}\n```\n\n#### Pacing\n\nIt is recommended that applications [pace] sending of outgoing packets to\navoid creating packet bursts that could cause short-term congestion and\nlosses in the network.\n\nquiche exposes pacing hints for outgoing packets through the [`at`] field\nof the [`SendInfo`] structure that is returned by the [`send()`] method.\nThis field represents the time when a specific packet should be sent into\nthe network.\n\nApplications can use these hints by artificially delaying the sending of\npackets through platform-specific mechanisms (such as the [`SO_TXTIME`]\nsocket option on Linux), or custom methods (for example by using user-space\ntimers).\n\n[pace]: https://datatracker.ietf.org/doc/html/rfc9002#section-7.7\n[`SO_TXTIME`]: https://man7.org/linux/man-pages/man8/tc-etf.8.html\n\n### Sending and receiving stream data\n\nAfter some back and forth, the connection will complete its handshake and\nwill be ready for sending or receiving application data.\n\nData can be sent on a stream by using the [`stream_send()`] method:\n\n```rust\nif conn.is_established() {\n    // Handshake completed, send some data on stream 0.\n    conn.stream_send(0, b\"hello\", true)?;\n}\n```\n\nThe application can check whether there are any readable streams by using\nthe connection's [`readable()`] method, which returns an iterator over all\nthe streams that have outstanding data to read.\n\nThe [`stream_recv()`] method can then be used to retrieve the application\ndata from the readable stream:\n\n```rust\nif conn.is_established() {\n    // Iterate over readable streams.\n    for stream_id in conn.readable() {\n        // Stream is readable, read until there's no more data.\n        while let Ok((read, fin)) = conn.stream_recv(stream_id, \u0026mut buf) {\n            println!(\"Got {} bytes on stream {}\", read, stream_id);\n        }\n    }\n}\n```\n\n### HTTP/3\n\nThe quiche [HTTP/3 module] provides a high level API for sending and\nreceiving HTTP requests and responses on top of the QUIC transport protocol.\n\n[`Config`]: https://docs.quic.tech/quiche/struct.Config.html\n[`set_initial_max_streams_bidi()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_streams_bidi\n[`set_initial_max_streams_uni()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_streams_uni\n[`set_initial_max_data()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_data\n[`set_initial_max_stream_data_bidi_local()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_bidi_local\n[`set_initial_max_stream_data_bidi_remote()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_bidi_remote\n[`set_initial_max_stream_data_uni()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_uni\n[`with_boring_ssl_ctx_builder()`]: https://docs.quic.tech/quiche/struct.Config.html#method.with_boring_ssl_ctx_builder\n[`connect()`]: https://docs.quic.tech/quiche/fn.connect.html\n[`accept()`]: https://docs.quic.tech/quiche/fn.accept.html\n[`recv()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.recv\n[`send()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.send\n[`timeout()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.timeout\n[`on_timeout()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.on_timeout\n[`stream_send()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.stream_send\n[`readable()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.readable\n[`stream_recv()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.stream_recv\n[HTTP/3 module]: https://docs.quic.tech/quiche/h3/index.html\n\nHave a look at the [quiche/examples/] directory for more complete examples on\nhow to use the quiche API, including examples on how to use quiche in C/C++\napplications (see below for more information).\n\n[examples/]: quiche/examples/\n\nCalling quiche from C/C++\n-------------------------\n\nquiche exposes a [thin C API] on top of the Rust API that can be used to more\neasily integrate quiche into C/C++ applications (as well as in other languages\nthat allow calling C APIs via some form of FFI). The C API follows the same\ndesign of the Rust one, modulo the constraints imposed by the C language itself.\n\nWhen running ``cargo build``, a static library called ``libquiche.a`` will be\nbuilt automatically alongside the Rust one. This is fully stand-alone and can\nbe linked directly into C/C++ applications.\n\nNote that in order to enable the FFI API, the ``ffi`` feature must be enabled (it\nis disabled by default), by passing ``--features ffi`` to ``cargo``.\n\n[thin C API]: https://github.com/cloudflare/quiche/blob/master/quiche/include/quiche.h\n\nBuilding\n--------\n\nquiche requires Rust 1.82 or later to build. The latest stable Rust release can\nbe installed using [rustup](https://rustup.rs/).\n\nOnce the Rust build environment is setup, the quiche source code can be fetched\nusing git:\n\n```bash\n $ git clone --recursive https://github.com/cloudflare/quiche\n```\n\nand then built using cargo:\n\n```bash\n $ cargo build --examples\n```\n\ncargo can also be used to run the testsuite:\n\n```bash\n $ cargo test\n```\n\nNote that [BoringSSL], which is used to implement QUIC's cryptographic handshake\nbased on TLS, needs to be built and linked to quiche. This is done automatically\nwhen building quiche using cargo, but requires the `cmake` command to be\navailable during the build process. On Windows you also need\n[NASM](https://www.nasm.us/). The [official BoringSSL\ndocumentation](https://github.com/google/boringssl/blob/master/BUILDING.md) has\nmore details.\n\nIn alternative you can use your own custom build of BoringSSL by configuring\nthe BoringSSL directory with the ``QUICHE_BSSL_PATH`` environment variable:\n\n```bash\n $ QUICHE_BSSL_PATH=\"/path/to/boringssl\" cargo build --examples\n```\n\nAlternatively you can use [OpenSSL/quictls]. To enable quiche to use this vendor\nthe ``openssl`` feature can be added to the ``--feature`` list. Be aware that\n``0-RTT`` is not supported if this vendor is used.\n\n[BoringSSL]: https://boringssl.googlesource.com/boringssl/\n\n[OpenSSL/quictls]: https://github.com/quictls/openssl\n\n### Building for Android\n\nBuilding quiche for Android (NDK version 19 or higher, 21 recommended), can be\ndone using [cargo-ndk] (v2.0 or later).\n\nFirst the [Android NDK] needs to be installed, either using Android Studio or\ndirectly, and the `ANDROID_NDK_HOME` environment variable needs to be set to the\nNDK installation path, e.g.:\n\n```bash\n $ export ANDROID_NDK_HOME=/usr/local/share/android-ndk\n```\n\nThen the Rust toolchain for the Android architectures needed can be installed as\nfollows:\n\n```bash\n $ rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android\n```\n\nNote that the minimum API level is 21 for all target architectures.\n\n[cargo-ndk] (v2.0 or later) also needs to be installed:\n\n```bash\n $ cargo install cargo-ndk\n```\n\nFinally the quiche library can be built using the following procedure. Note that\nthe `-t \u003carchitecture\u003e` and `-p \u003cNDK version\u003e` options are mandatory.\n\n```bash\n $ cargo ndk -t arm64-v8a -p 21 -- build --features ffi\n```\n\nSee [build_android_ndk19.sh] for more information.\n\n[Android NDK]: https://developer.android.com/ndk\n[cargo-ndk]: https://docs.rs/crate/cargo-ndk\n[build_android_ndk19.sh]: https://github.com/cloudflare/quiche/blob/master/tools/android/build_android_ndk19.sh\n\n### Building for iOS\n\nTo build quiche for iOS, you need the following:\n\n- Install Xcode command-line tools. You can install them with Xcode or with the\n  following command:\n\n```bash\n $ xcode-select --install\n```\n\n- Install the Rust toolchain for iOS architectures:\n\n```bash\n $ rustup target add aarch64-apple-ios x86_64-apple-ios\n```\n\n- Install `cargo-lipo`:\n\n```bash\n $ cargo install cargo-lipo\n```\n\nTo build libquiche, run the following command:\n\n```bash\n $ cargo lipo --features ffi\n```\n\nor\n\n```bash\n $ cargo lipo --features ffi --release\n```\n\niOS build is tested in Xcode 10.1 and Xcode 11.2.\n\n### Building Docker images\n\nIn order to build the Docker images, simply run the following command:\n\n```bash\n $ make docker-build\n```\n\nYou can find the quiche Docker images on the following Docker Hub repositories:\n\n- [cloudflare/quiche](https://hub.docker.com/repository/docker/cloudflare/quiche)\n- [cloudflare/quiche-qns](https://hub.docker.com/repository/docker/cloudflare/quiche-qns)\n\nThe `latest` tag will be updated whenever quiche master branch updates.\n\n**cloudflare/quiche**\n\nProvides a server and client installed in /usr/local/bin.\n\n**cloudflare/quiche-qns**\n\nProvides the script to test quiche within the [quic-interop-runner](https://github.com/marten-seemann/quic-interop-runner).\n\nCopyright\n---------\n\nCopyright (C) 2018-2019, Cloudflare, Inc.\n\nSee [COPYING] for the license.\n\n[COPYING]: https://github.com/cloudflare/quiche/tree/master/COPYING\n","funding_links":[],"categories":["Rust","Libraries","库 Libraries","语言资源库","网络服务","Network","Quic \u0026\u0026 KCP \u0026\u0026 KTP \u0026\u0026 PCC \u0026\u0026 SRT 学习资料快速链接","框架和开源实现","Networking \u0026 Performance","Implementations"],"sub_categories":["Network programming","网络编程 Network programming","rust","网络服务_其他","Network Troubleshooting","Rust","Protocol Implementations"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fquiche","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fquiche","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fquiche/lists"}