rwebtransport 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/Cargo.lock +666 -666
  2. package/Cargo.toml +31 -31
  3. package/LICENSE +202 -202
  4. package/NOTICE +41 -41
  5. package/README.md +550 -550
  6. package/crates/echo-server/Cargo.toml +20 -20
  7. package/crates/echo-server/src/main.rs +666 -666
  8. package/crates/native/Cargo.toml +23 -23
  9. package/crates/native/src/config.rs +129 -129
  10. package/crates/native/src/driver.rs +463 -463
  11. package/crates/native/src/lib.rs +821 -821
  12. package/crates/native/src/server.rs +718 -718
  13. package/crates/native/src/session.rs +1191 -1191
  14. package/crates/native/src/tls.rs +96 -96
  15. package/crates/wtcore/Cargo.toml +15 -15
  16. package/crates/wtcore/src/h3.rs +226 -226
  17. package/crates/wtcore/src/lib.rs +9 -9
  18. package/dist/index.js.map +1 -1
  19. package/dist/index.mjs.map +1 -1
  20. package/package.json +80 -79
  21. package/prebuilds/darwin-arm64/rwebtransport.node +0 -0
  22. package/prebuilds/linux-arm64/rwebtransport.node +0 -0
  23. package/prebuilds/linux-x64/rwebtransport.node +0 -0
  24. package/prebuilds/win32-x64/rwebtransport.node +0 -0
  25. package/scripts/bench.mjs +180 -180
  26. package/scripts/build.js +67 -67
  27. package/scripts/postinstall.js +67 -67
  28. package/scripts/setup-unix.sh +129 -129
  29. package/scripts/setup-windows.ps1 +229 -229
  30. package/vendor/quiche/AGENTS.md +75 -75
  31. package/vendor/quiche/COPYING +23 -23
  32. package/vendor/quiche/Cargo.lock +1212 -1212
  33. package/vendor/quiche/Cargo.toml +215 -215
  34. package/vendor/quiche/README.md +466 -466
  35. package/vendor/quiche/examples/Makefile +46 -46
  36. package/vendor/quiche/examples/README.md +20 -20
  37. package/vendor/quiche/examples/cert-big.crt +90 -90
  38. package/vendor/quiche/examples/cert.crt +18 -18
  39. package/vendor/quiche/examples/cert.key +28 -28
  40. package/vendor/quiche/examples/client.c +343 -343
  41. package/vendor/quiche/examples/client.rs +281 -281
  42. package/vendor/quiche/examples/gen-certs.sh +15 -15
  43. package/vendor/quiche/examples/http3-client.c +473 -473
  44. package/vendor/quiche/examples/http3-client.rs +349 -349
  45. package/vendor/quiche/examples/http3-server.c +614 -614
  46. package/vendor/quiche/examples/http3-server.rs +680 -680
  47. package/vendor/quiche/examples/qpack-decode.rs +87 -87
  48. package/vendor/quiche/examples/qpack-encode.rs +88 -88
  49. package/vendor/quiche/examples/rootca.crt +21 -21
  50. package/vendor/quiche/examples/server.c +529 -529
  51. package/vendor/quiche/examples/server.rs +529 -529
  52. package/vendor/quiche/include/quiche.h +1282 -1282
  53. package/vendor/quiche/src/buffers.rs +105 -105
  54. package/vendor/quiche/src/build.rs +66 -66
  55. package/vendor/quiche/src/cid.rs +1079 -1079
  56. package/vendor/quiche/src/crypto/boringssl.rs +373 -373
  57. package/vendor/quiche/src/crypto/mod.rs +671 -671
  58. package/vendor/quiche/src/dgram.rs +118 -118
  59. package/vendor/quiche/src/error.rs +263 -263
  60. package/vendor/quiche/src/ffi.rs +2290 -2290
  61. package/vendor/quiche/src/flowcontrol.rs +246 -246
  62. package/vendor/quiche/src/frame.rs +2172 -2172
  63. package/vendor/quiche/src/h3/AGENTS.md +54 -54
  64. package/vendor/quiche/src/h3/ffi.rs +442 -442
  65. package/vendor/quiche/src/h3/frame.rs +1404 -1404
  66. package/vendor/quiche/src/h3/mod.rs +8223 -8223
  67. package/vendor/quiche/src/h3/qpack/decoder.rs +288 -288
  68. package/vendor/quiche/src/h3/qpack/encoder.rs +235 -235
  69. package/vendor/quiche/src/h3/qpack/mod.rs +202 -202
  70. package/vendor/quiche/src/h3/qpack/static_table.rs +323 -323
  71. package/vendor/quiche/src/h3/stream.rs +1595 -1595
  72. package/vendor/quiche/src/lib.rs +9556 -9556
  73. package/vendor/quiche/src/minmax.rs +446 -446
  74. package/vendor/quiche/src/packet.rs +2334 -2334
  75. package/vendor/quiche/src/path.rs +1374 -1374
  76. package/vendor/quiche/src/pmtud.rs +652 -652
  77. package/vendor/quiche/src/rand.rs +64 -64
  78. package/vendor/quiche/src/range_buf.rs +186 -186
  79. package/vendor/quiche/src/ranges.rs +755 -755
  80. package/vendor/quiche/src/recovery/AGENTS.md +80 -80
  81. package/vendor/quiche/src/recovery/bandwidth.rs +565 -565
  82. package/vendor/quiche/src/recovery/bytes_in_flight.rs +179 -179
  83. package/vendor/quiche/src/recovery/congestion/cubic.rs +1038 -1038
  84. package/vendor/quiche/src/recovery/congestion/delivery_rate.rs +514 -514
  85. package/vendor/quiche/src/recovery/congestion/hystart.rs +241 -241
  86. package/vendor/quiche/src/recovery/congestion/mod.rs +361 -361
  87. package/vendor/quiche/src/recovery/congestion/prr.rs +238 -238
  88. package/vendor/quiche/src/recovery/congestion/recovery.rs +1170 -1170
  89. package/vendor/quiche/src/recovery/congestion/reno.rs +291 -291
  90. package/vendor/quiche/src/recovery/congestion/test_sender.rs +201 -201
  91. package/vendor/quiche/src/recovery/gcongestion/bbr/bandwidth_sampler.rs +1947 -1947
  92. package/vendor/quiche/src/recovery/gcongestion/bbr/windowed_filter.rs +158 -158
  93. package/vendor/quiche/src/recovery/gcongestion/bbr.rs +37 -37
  94. package/vendor/quiche/src/recovery/gcongestion/bbr2/drain.rs +120 -120
  95. package/vendor/quiche/src/recovery/gcongestion/bbr2/mode.rs +318 -318
  96. package/vendor/quiche/src/recovery/gcongestion/bbr2/network_model.rs +784 -784
  97. package/vendor/quiche/src/recovery/gcongestion/bbr2/probe_bw.rs +729 -729
  98. package/vendor/quiche/src/recovery/gcongestion/bbr2/probe_rtt.rs +175 -175
  99. package/vendor/quiche/src/recovery/gcongestion/bbr2/startup.rs +190 -190
  100. package/vendor/quiche/src/recovery/gcongestion/bbr2.rs +855 -855
  101. package/vendor/quiche/src/recovery/gcongestion/mod.rs +275 -275
  102. package/vendor/quiche/src/recovery/gcongestion/pacer.rs +294 -294
  103. package/vendor/quiche/src/recovery/gcongestion/recovery.rs +1384 -1384
  104. package/vendor/quiche/src/recovery/mod.rs +3086 -3086
  105. package/vendor/quiche/src/recovery/rtt.rs +152 -152
  106. package/vendor/quiche/src/stream/mod.rs +2210 -2210
  107. package/vendor/quiche/src/stream/recv_buf.rs +1236 -1236
  108. package/vendor/quiche/src/stream/send_buf.rs +849 -849
  109. package/vendor/quiche/src/test_utils.rs +681 -681
  110. package/vendor/quiche/src/tests.rs +12922 -12922
  111. package/vendor/quiche/src/tls/boringssl.rs +375 -375
  112. package/vendor/quiche/src/tls/mod.rs +1245 -1245
  113. package/vendor/quiche/src/transport_params.rs +628 -628
@@ -1,466 +1,466 @@
1
- ![quiche](quiche.svg)
2
-
3
- [![crates.io](https://img.shields.io/crates/v/quiche.svg)](https://crates.io/crates/quiche)
4
- [![docs.rs](https://docs.rs/quiche/badge.svg)](https://docs.rs/quiche)
5
- [![license](https://img.shields.io/github/license/cloudflare/quiche.svg)](https://opensource.org/licenses/BSD-2-Clause)
6
- ![build](https://img.shields.io/github/actions/workflow/status/cloudflare/quiche/stable.yml?branch=master)
7
-
8
- [quiche] is an implementation of the QUIC transport protocol and HTTP/3 as
9
- specified by the [IETF]. It provides a low level API for processing QUIC packets
10
- and handling connection state. The application is responsible for providing I/O
11
- (e.g. sockets handling) as well as an event loop with support for timers.
12
-
13
- For more information on how quiche came about and some insights into its design
14
- you can read a [post] on Cloudflare's blog that goes into some more detail.
15
-
16
- [quiche]: https://docs.quic.tech/quiche/
17
- [ietf]: https://quicwg.org/
18
- [post]: https://blog.cloudflare.com/enjoy-a-slice-of-quic-and-rust/
19
-
20
- Who uses quiche?
21
- ----------------
22
-
23
- ### Cloudflare
24
-
25
- quiche powers Cloudflare edge network's [HTTP/3 support][cloudflare-http3]. The
26
- [cloudflare-quic.com](https://cloudflare-quic.com) website can be used for
27
- testing and experimentation.
28
-
29
- ### Android
30
-
31
- Android's DNS resolver uses quiche to [implement DNS over HTTP/3][android-http3].
32
-
33
- ### curl
34
-
35
- quiche can be [integrated into curl][curl-http3] to provide support for HTTP/3.
36
-
37
- [cloudflare-http3]: https://blog.cloudflare.com/http3-the-past-present-and-future/
38
- [android-http3]: https://security.googleblog.com/2022/07/dns-over-http3-in-android.html
39
- [curl-http3]: https://github.com/curl/curl/blob/master/docs/HTTP3.md#quiche-version
40
-
41
- Getting Started
42
- ---------------
43
-
44
- ### Command-line apps
45
-
46
- Before diving into the quiche API, here are a few examples on how to use the
47
- quiche tools provided as part of the [quiche-apps](apps/) crate. These are not
48
- suitable for production environments; see [disclaimers and
49
- notes](#disclaimers-and-notes).
50
-
51
- After cloning the project according to the command mentioned in the [building](#building) section, the client can be run as follows:
52
-
53
- ```bash
54
- $ cargo run --bin quiche-client -- https://cloudflare-quic.com/
55
- ```
56
-
57
- while the server can be run as follows:
58
-
59
- ```bash
60
- $ cargo run --bin quiche-server -- --cert apps/src/bin/cert.crt --key apps/src/bin/cert.key
61
- ```
62
-
63
- (note that the certificate provided is self-signed and should not be used in
64
- production)
65
-
66
- Use the `--help` command-line flag to get a more detailed description of each
67
- tool's options.
68
-
69
- ### Configuring connections
70
-
71
- The first step in establishing a QUIC connection using quiche is creating a
72
- [`Config`] object:
73
-
74
- ```rust
75
- let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
76
- config.set_application_protos(&[b"example-proto"]);
77
-
78
- // Additional configuration specific to application and use case...
79
- ```
80
-
81
- The [`Config`] object controls important aspects of the QUIC connection such
82
- as QUIC version, ALPN IDs, flow control, congestion control, idle timeout
83
- and other properties or features.
84
-
85
- QUIC is a general-purpose transport protocol and there are several
86
- configuration properties where there is no reasonable default value. For
87
- example, the permitted number of concurrent streams of any particular type
88
- is dependent on the application running over QUIC, and other use-case
89
- specific concerns.
90
-
91
- quiche defaults several properties to zero, applications most likely need
92
- to set these to something else to satisfy their needs using the following:
93
-
94
- - [`set_initial_max_streams_bidi()`]
95
- - [`set_initial_max_streams_uni()`]
96
- - [`set_initial_max_data()`]
97
- - [`set_initial_max_stream_data_bidi_local()`]
98
- - [`set_initial_max_stream_data_bidi_remote()`]
99
- - [`set_initial_max_stream_data_uni()`]
100
-
101
- [`Config`] also holds TLS configuration. This can be changed by mutators on
102
- the an existing object, or by constructing a TLS context manually and
103
- creating a configuration using [`with_boring_ssl_ctx_builder()`].
104
-
105
- A configuration object can be shared among multiple connections.
106
-
107
- ### Connection setup
108
-
109
- On the client-side the [`connect()`] utility function can be used to create
110
- a new connection, while [`accept()`] is for servers:
111
-
112
- ```rust
113
- // Client connection.
114
- let conn = quiche::connect(Some(&server_name), &scid, local, peer, &mut config)?;
115
-
116
- // Server connection.
117
- let conn = quiche::accept(&scid, None, local, peer, &mut config)?;
118
- ```
119
-
120
- ### Handling incoming packets
121
-
122
- Using the connection's [`recv()`] method the application can process
123
- incoming packets that belong to that connection from the network:
124
-
125
- ```rust
126
- let to = socket.local_addr().unwrap();
127
-
128
- loop {
129
- let (read, from) = socket.recv_from(&mut buf).unwrap();
130
-
131
- let recv_info = quiche::RecvInfo { from, to };
132
-
133
- let read = match conn.recv(&mut buf[..read], recv_info) {
134
- Ok(v) => v,
135
-
136
- Err(e) => {
137
- // An error occurred, handle it.
138
- break;
139
- },
140
- };
141
- }
142
- ```
143
-
144
- ### Generating outgoing packets
145
-
146
- Outgoing packet are generated using the connection's [`send()`] method
147
- instead:
148
-
149
- ```rust
150
- loop {
151
- let (write, send_info) = match conn.send(&mut out) {
152
- Ok(v) => v,
153
-
154
- Err(quiche::Error::Done) => {
155
- // Done writing.
156
- break;
157
- },
158
-
159
- Err(e) => {
160
- // An error occurred, handle it.
161
- break;
162
- },
163
- };
164
-
165
- socket.send_to(&out[..write], &send_info.to).unwrap();
166
- }
167
- ```
168
-
169
- When packets are sent, the application is responsible for maintaining a
170
- timer to react to time-based connection events. The timer expiration can be
171
- obtained using the connection's [`timeout()`] method.
172
-
173
- ```rust
174
- let timeout = conn.timeout();
175
- ```
176
-
177
- The application is responsible for providing a timer implementation, which
178
- can be specific to the operating system or networking framework used. When
179
- a timer expires, the connection's [`on_timeout()`] method should be called,
180
- after which additional packets might need to be sent on the network:
181
-
182
- ```rust
183
- // Timeout expired, handle it.
184
- conn.on_timeout();
185
-
186
- // Send more packets as needed after timeout.
187
- loop {
188
- let (write, send_info) = match conn.send(&mut out) {
189
- Ok(v) => v,
190
-
191
- Err(quiche::Error::Done) => {
192
- // Done writing.
193
- break;
194
- },
195
-
196
- Err(e) => {
197
- // An error occurred, handle it.
198
- break;
199
- },
200
- };
201
-
202
- socket.send_to(&out[..write], &send_info.to).unwrap();
203
- }
204
- ```
205
-
206
- #### Pacing
207
-
208
- It is recommended that applications [pace] sending of outgoing packets to
209
- avoid creating packet bursts that could cause short-term congestion and
210
- losses in the network.
211
-
212
- quiche exposes pacing hints for outgoing packets through the [`at`] field
213
- of the [`SendInfo`] structure that is returned by the [`send()`] method.
214
- This field represents the time when a specific packet should be sent into
215
- the network.
216
-
217
- Applications can use these hints by artificially delaying the sending of
218
- packets through platform-specific mechanisms (such as the [`SO_TXTIME`]
219
- socket option on Linux), or custom methods (for example by using user-space
220
- timers).
221
-
222
- [pace]: https://datatracker.ietf.org/doc/html/rfc9002#section-7.7
223
- [`SO_TXTIME`]: https://man7.org/linux/man-pages/man8/tc-etf.8.html
224
-
225
- ### Sending and receiving stream data
226
-
227
- After some back and forth, the connection will complete its handshake and
228
- will be ready for sending or receiving application data.
229
-
230
- Data can be sent on a stream by using the [`stream_send()`] method:
231
-
232
- ```rust
233
- if conn.is_established() {
234
- // Handshake completed, send some data on stream 0.
235
- conn.stream_send(0, b"hello", true)?;
236
- }
237
- ```
238
-
239
- The application can check whether there are any readable streams by using
240
- the connection's [`readable()`] method, which returns an iterator over all
241
- the streams that have outstanding data to read.
242
-
243
- The [`stream_recv()`] method can then be used to retrieve the application
244
- data from the readable stream:
245
-
246
- ```rust
247
- if conn.is_established() {
248
- // Iterate over readable streams.
249
- for stream_id in conn.readable() {
250
- // Stream is readable, read until there's no more data.
251
- while let Ok((read, fin)) = conn.stream_recv(stream_id, &mut buf) {
252
- println!("Got {} bytes on stream {}", read, stream_id);
253
- }
254
- }
255
- }
256
- ```
257
-
258
- ### HTTP/3
259
-
260
- The quiche [HTTP/3 module] provides a high level API for sending and
261
- receiving HTTP requests and responses on top of the QUIC transport protocol.
262
-
263
- [`Config`]: https://docs.quic.tech/quiche/struct.Config.html
264
- [`set_initial_max_streams_bidi()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_streams_bidi
265
- [`set_initial_max_streams_uni()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_streams_uni
266
- [`set_initial_max_data()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_data
267
- [`set_initial_max_stream_data_bidi_local()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_bidi_local
268
- [`set_initial_max_stream_data_bidi_remote()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_bidi_remote
269
- [`set_initial_max_stream_data_uni()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_uni
270
- [`with_boring_ssl_ctx_builder()`]: https://docs.quic.tech/quiche/struct.Config.html#method.with_boring_ssl_ctx_builder
271
- [`connect()`]: https://docs.quic.tech/quiche/fn.connect.html
272
- [`accept()`]: https://docs.quic.tech/quiche/fn.accept.html
273
- [`recv()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.recv
274
- [`send()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.send
275
- [`timeout()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.timeout
276
- [`on_timeout()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.on_timeout
277
- [`stream_send()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.stream_send
278
- [`readable()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.readable
279
- [`stream_recv()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.stream_recv
280
- [HTTP/3 module]: https://docs.quic.tech/quiche/h3/index.html
281
-
282
- Have a look at the [quiche/examples/] directory for more complete examples on
283
- how to use the quiche API, including examples on how to use quiche in C/C++
284
- applications (see below for more information).
285
-
286
- [examples/]: quiche/examples/
287
-
288
- Calling quiche from C/C++
289
- -------------------------
290
-
291
- quiche exposes a [thin C API] on top of the Rust API that can be used to more
292
- easily integrate quiche into C/C++ applications (as well as in other languages
293
- that allow calling C APIs via some form of FFI). The C API follows the same
294
- design of the Rust one, modulo the constraints imposed by the C language itself.
295
-
296
- When running ``cargo build``, a static library called ``libquiche.a`` will be
297
- built automatically alongside the Rust one. This is fully stand-alone and can
298
- be linked directly into C/C++ applications.
299
-
300
- Note that in order to enable the FFI API, the ``ffi`` feature must be enabled (it
301
- is disabled by default), by passing ``--features ffi`` to ``cargo``.
302
-
303
- [thin C API]: https://github.com/cloudflare/quiche/blob/master/quiche/include/quiche.h
304
-
305
- Building
306
- --------
307
-
308
- quiche requires Rust 1.88 or later to build. The latest stable Rust release can
309
- be installed using [rustup](https://rustup.rs/).
310
-
311
- Once the Rust build environment is setup, the quiche source code can be fetched
312
- using git:
313
-
314
- ```bash
315
- $ git clone https://github.com/cloudflare/quiche
316
- ```
317
-
318
- and then built using cargo:
319
-
320
- ```bash
321
- $ cargo build --examples
322
- ```
323
-
324
- cargo can also be used to run the testsuite:
325
-
326
- ```bash
327
- $ cargo test
328
- ```
329
-
330
- Note that [BoringSSL], which is used to implement QUIC's cryptographic handshake
331
- based on TLS, needs to be built and linked to quiche. This is done automatically
332
- by the [boring-sys] crate when building with cargo, but requires the `cmake`
333
- command to be available during the build process.
334
-
335
- On Windows [NASM](https://www.nasm.us/) is also required. The [official BoringSSL
336
- documentation](https://github.com/google/boringssl/blob/master/BUILDING.md) has
337
- more details.
338
-
339
- In alternative you can use your own custom build of BoringSSL by configuring
340
- the BoringSSL directory with the ``BORING_BSSL_PATH`` environment variable:
341
-
342
- ```bash
343
- $ BORING_BSSL_PATH="/path/to/boringssl" cargo build --examples
344
- ```
345
-
346
- [BoringSSL]: https://boringssl.googlesource.com/boringssl/
347
- [boring-sys]: https://crates.io/crates/boring-sys
348
-
349
- ### Building for Android
350
-
351
- Building quiche for Android (NDK version 19 or higher, 21 recommended), can be
352
- done using [cargo-ndk] (v2.0 or later).
353
-
354
- First the [Android NDK] needs to be installed, either using Android Studio or
355
- directly, and the `ANDROID_NDK_HOME` environment variable needs to be set to the
356
- NDK installation path, e.g.:
357
-
358
- ```bash
359
- $ export ANDROID_NDK_HOME=/usr/local/share/android-ndk
360
- ```
361
-
362
- Then the Rust toolchain for the Android architectures needed can be installed as
363
- follows:
364
-
365
- ```bash
366
- $ rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
367
- ```
368
-
369
- Note that the minimum API level is 21 for all target architectures.
370
-
371
- [cargo-ndk] (v2.0 or later) also needs to be installed:
372
-
373
- ```bash
374
- $ cargo install cargo-ndk
375
- ```
376
-
377
- Finally the quiche library can be built using the following procedure. Note that
378
- the `-t <architecture>` and `-p <NDK version>` options are mandatory.
379
-
380
- ```bash
381
- $ cargo ndk -t arm64-v8a -p 21 -- build --features ffi
382
- ```
383
-
384
- See [build_android_ndk19.sh] for more information.
385
-
386
- [Android NDK]: https://developer.android.com/ndk
387
- [cargo-ndk]: https://docs.rs/crate/cargo-ndk
388
- [build_android_ndk19.sh]: https://github.com/cloudflare/quiche/blob/master/tools/android/build_android_ndk19.sh
389
-
390
- ### Building for iOS
391
-
392
- To build quiche for iOS, you need the following:
393
-
394
- - Install Xcode command-line tools. You can install them with Xcode or with the
395
- following command:
396
-
397
- ```bash
398
- $ xcode-select --install
399
- ```
400
-
401
- - Install the Rust toolchain for iOS architectures:
402
-
403
- ```bash
404
- $ rustup target add aarch64-apple-ios x86_64-apple-ios
405
- ```
406
-
407
- - Install `cargo-lipo`:
408
-
409
- ```bash
410
- $ cargo install cargo-lipo
411
- ```
412
-
413
- To build libquiche, run the following command:
414
-
415
- ```bash
416
- $ cargo lipo --features ffi
417
- ```
418
-
419
- or
420
-
421
- ```bash
422
- $ cargo lipo --features ffi --release
423
- ```
424
-
425
- iOS build is tested in Xcode 10.1 and Xcode 11.2.
426
-
427
- ### Building Docker images
428
-
429
- In order to build the Docker images, simply run the following command:
430
-
431
- ```bash
432
- $ make docker-build
433
- ```
434
-
435
- You can find the quiche Docker images on the following Docker Hub repositories:
436
-
437
- - [cloudflare/quiche](https://hub.docker.com/repository/docker/cloudflare/quiche)
438
- - [cloudflare/quiche-qns](https://hub.docker.com/repository/docker/cloudflare/quiche-qns)
439
-
440
- The `latest` tag will be updated whenever quiche master branch updates.
441
-
442
- **cloudflare/quiche**
443
-
444
- Provides a server and client installed in /usr/local/bin.
445
-
446
- **cloudflare/quiche-qns**
447
-
448
- Provides the script to test quiche within the [quic-interop-runner](https://github.com/marten-seemann/quic-interop-runner).
449
-
450
- Disclaimers and Notes
451
- ---------
452
-
453
- ⚠️ This repository includes a number of client and server example
454
- applications that are provided to demonstrate simple usage of the quiche library
455
- API. They are not intended to be used in production environments; no
456
- performance, security or reliability guarantees are provided.
457
-
458
-
459
- Copyright
460
- ---------
461
-
462
- Copyright (C) 2018-2019, Cloudflare, Inc.
463
-
464
- See [COPYING] for the license.
465
-
466
- [COPYING]: https://github.com/cloudflare/quiche/tree/master/COPYING
1
+ ![quiche](quiche.svg)
2
+
3
+ [![crates.io](https://img.shields.io/crates/v/quiche.svg)](https://crates.io/crates/quiche)
4
+ [![docs.rs](https://docs.rs/quiche/badge.svg)](https://docs.rs/quiche)
5
+ [![license](https://img.shields.io/github/license/cloudflare/quiche.svg)](https://opensource.org/licenses/BSD-2-Clause)
6
+ ![build](https://img.shields.io/github/actions/workflow/status/cloudflare/quiche/stable.yml?branch=master)
7
+
8
+ [quiche] is an implementation of the QUIC transport protocol and HTTP/3 as
9
+ specified by the [IETF]. It provides a low level API for processing QUIC packets
10
+ and handling connection state. The application is responsible for providing I/O
11
+ (e.g. sockets handling) as well as an event loop with support for timers.
12
+
13
+ For more information on how quiche came about and some insights into its design
14
+ you can read a [post] on Cloudflare's blog that goes into some more detail.
15
+
16
+ [quiche]: https://docs.quic.tech/quiche/
17
+ [ietf]: https://quicwg.org/
18
+ [post]: https://blog.cloudflare.com/enjoy-a-slice-of-quic-and-rust/
19
+
20
+ Who uses quiche?
21
+ ----------------
22
+
23
+ ### Cloudflare
24
+
25
+ quiche powers Cloudflare edge network's [HTTP/3 support][cloudflare-http3]. The
26
+ [cloudflare-quic.com](https://cloudflare-quic.com) website can be used for
27
+ testing and experimentation.
28
+
29
+ ### Android
30
+
31
+ Android's DNS resolver uses quiche to [implement DNS over HTTP/3][android-http3].
32
+
33
+ ### curl
34
+
35
+ quiche can be [integrated into curl][curl-http3] to provide support for HTTP/3.
36
+
37
+ [cloudflare-http3]: https://blog.cloudflare.com/http3-the-past-present-and-future/
38
+ [android-http3]: https://security.googleblog.com/2022/07/dns-over-http3-in-android.html
39
+ [curl-http3]: https://github.com/curl/curl/blob/master/docs/HTTP3.md#quiche-version
40
+
41
+ Getting Started
42
+ ---------------
43
+
44
+ ### Command-line apps
45
+
46
+ Before diving into the quiche API, here are a few examples on how to use the
47
+ quiche tools provided as part of the [quiche-apps](apps/) crate. These are not
48
+ suitable for production environments; see [disclaimers and
49
+ notes](#disclaimers-and-notes).
50
+
51
+ After cloning the project according to the command mentioned in the [building](#building) section, the client can be run as follows:
52
+
53
+ ```bash
54
+ $ cargo run --bin quiche-client -- https://cloudflare-quic.com/
55
+ ```
56
+
57
+ while the server can be run as follows:
58
+
59
+ ```bash
60
+ $ cargo run --bin quiche-server -- --cert apps/src/bin/cert.crt --key apps/src/bin/cert.key
61
+ ```
62
+
63
+ (note that the certificate provided is self-signed and should not be used in
64
+ production)
65
+
66
+ Use the `--help` command-line flag to get a more detailed description of each
67
+ tool's options.
68
+
69
+ ### Configuring connections
70
+
71
+ The first step in establishing a QUIC connection using quiche is creating a
72
+ [`Config`] object:
73
+
74
+ ```rust
75
+ let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
76
+ config.set_application_protos(&[b"example-proto"]);
77
+
78
+ // Additional configuration specific to application and use case...
79
+ ```
80
+
81
+ The [`Config`] object controls important aspects of the QUIC connection such
82
+ as QUIC version, ALPN IDs, flow control, congestion control, idle timeout
83
+ and other properties or features.
84
+
85
+ QUIC is a general-purpose transport protocol and there are several
86
+ configuration properties where there is no reasonable default value. For
87
+ example, the permitted number of concurrent streams of any particular type
88
+ is dependent on the application running over QUIC, and other use-case
89
+ specific concerns.
90
+
91
+ quiche defaults several properties to zero, applications most likely need
92
+ to set these to something else to satisfy their needs using the following:
93
+
94
+ - [`set_initial_max_streams_bidi()`]
95
+ - [`set_initial_max_streams_uni()`]
96
+ - [`set_initial_max_data()`]
97
+ - [`set_initial_max_stream_data_bidi_local()`]
98
+ - [`set_initial_max_stream_data_bidi_remote()`]
99
+ - [`set_initial_max_stream_data_uni()`]
100
+
101
+ [`Config`] also holds TLS configuration. This can be changed by mutators on
102
+ the an existing object, or by constructing a TLS context manually and
103
+ creating a configuration using [`with_boring_ssl_ctx_builder()`].
104
+
105
+ A configuration object can be shared among multiple connections.
106
+
107
+ ### Connection setup
108
+
109
+ On the client-side the [`connect()`] utility function can be used to create
110
+ a new connection, while [`accept()`] is for servers:
111
+
112
+ ```rust
113
+ // Client connection.
114
+ let conn = quiche::connect(Some(&server_name), &scid, local, peer, &mut config)?;
115
+
116
+ // Server connection.
117
+ let conn = quiche::accept(&scid, None, local, peer, &mut config)?;
118
+ ```
119
+
120
+ ### Handling incoming packets
121
+
122
+ Using the connection's [`recv()`] method the application can process
123
+ incoming packets that belong to that connection from the network:
124
+
125
+ ```rust
126
+ let to = socket.local_addr().unwrap();
127
+
128
+ loop {
129
+ let (read, from) = socket.recv_from(&mut buf).unwrap();
130
+
131
+ let recv_info = quiche::RecvInfo { from, to };
132
+
133
+ let read = match conn.recv(&mut buf[..read], recv_info) {
134
+ Ok(v) => v,
135
+
136
+ Err(e) => {
137
+ // An error occurred, handle it.
138
+ break;
139
+ },
140
+ };
141
+ }
142
+ ```
143
+
144
+ ### Generating outgoing packets
145
+
146
+ Outgoing packet are generated using the connection's [`send()`] method
147
+ instead:
148
+
149
+ ```rust
150
+ loop {
151
+ let (write, send_info) = match conn.send(&mut out) {
152
+ Ok(v) => v,
153
+
154
+ Err(quiche::Error::Done) => {
155
+ // Done writing.
156
+ break;
157
+ },
158
+
159
+ Err(e) => {
160
+ // An error occurred, handle it.
161
+ break;
162
+ },
163
+ };
164
+
165
+ socket.send_to(&out[..write], &send_info.to).unwrap();
166
+ }
167
+ ```
168
+
169
+ When packets are sent, the application is responsible for maintaining a
170
+ timer to react to time-based connection events. The timer expiration can be
171
+ obtained using the connection's [`timeout()`] method.
172
+
173
+ ```rust
174
+ let timeout = conn.timeout();
175
+ ```
176
+
177
+ The application is responsible for providing a timer implementation, which
178
+ can be specific to the operating system or networking framework used. When
179
+ a timer expires, the connection's [`on_timeout()`] method should be called,
180
+ after which additional packets might need to be sent on the network:
181
+
182
+ ```rust
183
+ // Timeout expired, handle it.
184
+ conn.on_timeout();
185
+
186
+ // Send more packets as needed after timeout.
187
+ loop {
188
+ let (write, send_info) = match conn.send(&mut out) {
189
+ Ok(v) => v,
190
+
191
+ Err(quiche::Error::Done) => {
192
+ // Done writing.
193
+ break;
194
+ },
195
+
196
+ Err(e) => {
197
+ // An error occurred, handle it.
198
+ break;
199
+ },
200
+ };
201
+
202
+ socket.send_to(&out[..write], &send_info.to).unwrap();
203
+ }
204
+ ```
205
+
206
+ #### Pacing
207
+
208
+ It is recommended that applications [pace] sending of outgoing packets to
209
+ avoid creating packet bursts that could cause short-term congestion and
210
+ losses in the network.
211
+
212
+ quiche exposes pacing hints for outgoing packets through the [`at`] field
213
+ of the [`SendInfo`] structure that is returned by the [`send()`] method.
214
+ This field represents the time when a specific packet should be sent into
215
+ the network.
216
+
217
+ Applications can use these hints by artificially delaying the sending of
218
+ packets through platform-specific mechanisms (such as the [`SO_TXTIME`]
219
+ socket option on Linux), or custom methods (for example by using user-space
220
+ timers).
221
+
222
+ [pace]: https://datatracker.ietf.org/doc/html/rfc9002#section-7.7
223
+ [`SO_TXTIME`]: https://man7.org/linux/man-pages/man8/tc-etf.8.html
224
+
225
+ ### Sending and receiving stream data
226
+
227
+ After some back and forth, the connection will complete its handshake and
228
+ will be ready for sending or receiving application data.
229
+
230
+ Data can be sent on a stream by using the [`stream_send()`] method:
231
+
232
+ ```rust
233
+ if conn.is_established() {
234
+ // Handshake completed, send some data on stream 0.
235
+ conn.stream_send(0, b"hello", true)?;
236
+ }
237
+ ```
238
+
239
+ The application can check whether there are any readable streams by using
240
+ the connection's [`readable()`] method, which returns an iterator over all
241
+ the streams that have outstanding data to read.
242
+
243
+ The [`stream_recv()`] method can then be used to retrieve the application
244
+ data from the readable stream:
245
+
246
+ ```rust
247
+ if conn.is_established() {
248
+ // Iterate over readable streams.
249
+ for stream_id in conn.readable() {
250
+ // Stream is readable, read until there's no more data.
251
+ while let Ok((read, fin)) = conn.stream_recv(stream_id, &mut buf) {
252
+ println!("Got {} bytes on stream {}", read, stream_id);
253
+ }
254
+ }
255
+ }
256
+ ```
257
+
258
+ ### HTTP/3
259
+
260
+ The quiche [HTTP/3 module] provides a high level API for sending and
261
+ receiving HTTP requests and responses on top of the QUIC transport protocol.
262
+
263
+ [`Config`]: https://docs.quic.tech/quiche/struct.Config.html
264
+ [`set_initial_max_streams_bidi()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_streams_bidi
265
+ [`set_initial_max_streams_uni()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_streams_uni
266
+ [`set_initial_max_data()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_data
267
+ [`set_initial_max_stream_data_bidi_local()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_bidi_local
268
+ [`set_initial_max_stream_data_bidi_remote()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_bidi_remote
269
+ [`set_initial_max_stream_data_uni()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_uni
270
+ [`with_boring_ssl_ctx_builder()`]: https://docs.quic.tech/quiche/struct.Config.html#method.with_boring_ssl_ctx_builder
271
+ [`connect()`]: https://docs.quic.tech/quiche/fn.connect.html
272
+ [`accept()`]: https://docs.quic.tech/quiche/fn.accept.html
273
+ [`recv()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.recv
274
+ [`send()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.send
275
+ [`timeout()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.timeout
276
+ [`on_timeout()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.on_timeout
277
+ [`stream_send()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.stream_send
278
+ [`readable()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.readable
279
+ [`stream_recv()`]: https://docs.quic.tech/quiche/struct.Connection.html#method.stream_recv
280
+ [HTTP/3 module]: https://docs.quic.tech/quiche/h3/index.html
281
+
282
+ Have a look at the [quiche/examples/] directory for more complete examples on
283
+ how to use the quiche API, including examples on how to use quiche in C/C++
284
+ applications (see below for more information).
285
+
286
+ [examples/]: quiche/examples/
287
+
288
+ Calling quiche from C/C++
289
+ -------------------------
290
+
291
+ quiche exposes a [thin C API] on top of the Rust API that can be used to more
292
+ easily integrate quiche into C/C++ applications (as well as in other languages
293
+ that allow calling C APIs via some form of FFI). The C API follows the same
294
+ design of the Rust one, modulo the constraints imposed by the C language itself.
295
+
296
+ When running ``cargo build``, a static library called ``libquiche.a`` will be
297
+ built automatically alongside the Rust one. This is fully stand-alone and can
298
+ be linked directly into C/C++ applications.
299
+
300
+ Note that in order to enable the FFI API, the ``ffi`` feature must be enabled (it
301
+ is disabled by default), by passing ``--features ffi`` to ``cargo``.
302
+
303
+ [thin C API]: https://github.com/cloudflare/quiche/blob/master/quiche/include/quiche.h
304
+
305
+ Building
306
+ --------
307
+
308
+ quiche requires Rust 1.88 or later to build. The latest stable Rust release can
309
+ be installed using [rustup](https://rustup.rs/).
310
+
311
+ Once the Rust build environment is setup, the quiche source code can be fetched
312
+ using git:
313
+
314
+ ```bash
315
+ $ git clone https://github.com/cloudflare/quiche
316
+ ```
317
+
318
+ and then built using cargo:
319
+
320
+ ```bash
321
+ $ cargo build --examples
322
+ ```
323
+
324
+ cargo can also be used to run the testsuite:
325
+
326
+ ```bash
327
+ $ cargo test
328
+ ```
329
+
330
+ Note that [BoringSSL], which is used to implement QUIC's cryptographic handshake
331
+ based on TLS, needs to be built and linked to quiche. This is done automatically
332
+ by the [boring-sys] crate when building with cargo, but requires the `cmake`
333
+ command to be available during the build process.
334
+
335
+ On Windows [NASM](https://www.nasm.us/) is also required. The [official BoringSSL
336
+ documentation](https://github.com/google/boringssl/blob/master/BUILDING.md) has
337
+ more details.
338
+
339
+ In alternative you can use your own custom build of BoringSSL by configuring
340
+ the BoringSSL directory with the ``BORING_BSSL_PATH`` environment variable:
341
+
342
+ ```bash
343
+ $ BORING_BSSL_PATH="/path/to/boringssl" cargo build --examples
344
+ ```
345
+
346
+ [BoringSSL]: https://boringssl.googlesource.com/boringssl/
347
+ [boring-sys]: https://crates.io/crates/boring-sys
348
+
349
+ ### Building for Android
350
+
351
+ Building quiche for Android (NDK version 19 or higher, 21 recommended), can be
352
+ done using [cargo-ndk] (v2.0 or later).
353
+
354
+ First the [Android NDK] needs to be installed, either using Android Studio or
355
+ directly, and the `ANDROID_NDK_HOME` environment variable needs to be set to the
356
+ NDK installation path, e.g.:
357
+
358
+ ```bash
359
+ $ export ANDROID_NDK_HOME=/usr/local/share/android-ndk
360
+ ```
361
+
362
+ Then the Rust toolchain for the Android architectures needed can be installed as
363
+ follows:
364
+
365
+ ```bash
366
+ $ rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
367
+ ```
368
+
369
+ Note that the minimum API level is 21 for all target architectures.
370
+
371
+ [cargo-ndk] (v2.0 or later) also needs to be installed:
372
+
373
+ ```bash
374
+ $ cargo install cargo-ndk
375
+ ```
376
+
377
+ Finally the quiche library can be built using the following procedure. Note that
378
+ the `-t <architecture>` and `-p <NDK version>` options are mandatory.
379
+
380
+ ```bash
381
+ $ cargo ndk -t arm64-v8a -p 21 -- build --features ffi
382
+ ```
383
+
384
+ See [build_android_ndk19.sh] for more information.
385
+
386
+ [Android NDK]: https://developer.android.com/ndk
387
+ [cargo-ndk]: https://docs.rs/crate/cargo-ndk
388
+ [build_android_ndk19.sh]: https://github.com/cloudflare/quiche/blob/master/tools/android/build_android_ndk19.sh
389
+
390
+ ### Building for iOS
391
+
392
+ To build quiche for iOS, you need the following:
393
+
394
+ - Install Xcode command-line tools. You can install them with Xcode or with the
395
+ following command:
396
+
397
+ ```bash
398
+ $ xcode-select --install
399
+ ```
400
+
401
+ - Install the Rust toolchain for iOS architectures:
402
+
403
+ ```bash
404
+ $ rustup target add aarch64-apple-ios x86_64-apple-ios
405
+ ```
406
+
407
+ - Install `cargo-lipo`:
408
+
409
+ ```bash
410
+ $ cargo install cargo-lipo
411
+ ```
412
+
413
+ To build libquiche, run the following command:
414
+
415
+ ```bash
416
+ $ cargo lipo --features ffi
417
+ ```
418
+
419
+ or
420
+
421
+ ```bash
422
+ $ cargo lipo --features ffi --release
423
+ ```
424
+
425
+ iOS build is tested in Xcode 10.1 and Xcode 11.2.
426
+
427
+ ### Building Docker images
428
+
429
+ In order to build the Docker images, simply run the following command:
430
+
431
+ ```bash
432
+ $ make docker-build
433
+ ```
434
+
435
+ You can find the quiche Docker images on the following Docker Hub repositories:
436
+
437
+ - [cloudflare/quiche](https://hub.docker.com/repository/docker/cloudflare/quiche)
438
+ - [cloudflare/quiche-qns](https://hub.docker.com/repository/docker/cloudflare/quiche-qns)
439
+
440
+ The `latest` tag will be updated whenever quiche master branch updates.
441
+
442
+ **cloudflare/quiche**
443
+
444
+ Provides a server and client installed in /usr/local/bin.
445
+
446
+ **cloudflare/quiche-qns**
447
+
448
+ Provides the script to test quiche within the [quic-interop-runner](https://github.com/marten-seemann/quic-interop-runner).
449
+
450
+ Disclaimers and Notes
451
+ ---------
452
+
453
+ ⚠️ This repository includes a number of client and server example
454
+ applications that are provided to demonstrate simple usage of the quiche library
455
+ API. They are not intended to be used in production environments; no
456
+ performance, security or reliability guarantees are provided.
457
+
458
+
459
+ Copyright
460
+ ---------
461
+
462
+ Copyright (C) 2018-2019, Cloudflare, Inc.
463
+
464
+ See [COPYING] for the license.
465
+
466
+ [COPYING]: https://github.com/cloudflare/quiche/tree/master/COPYING