Debian Codegraph @

third_party/rust/neqo-http3/src/lib.rs

raw
1 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
2 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
3 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
4 // option. This file may not be copied, modified, or distributed
5 // except according to those terms.
6
7 /*!
8
9 # The HTTP/3 protocol
10
11 This crate implements [RFC9114](https://datatracker.ietf.org/doc/html/rfc9114).
12
13 The implementation depends on:
14 - [neqo-transport](../neqo_transport/index.html) --- implements the QUIC protocol
15 ([RFC9000](https://www.rfc-editor.org/info/rfc9000)) and
16 - [neqo-qpack](../neqo_qpack/index.html) --- implements QPACK
17 ([RFC9204](https://www.rfc-editor.org/info/rfc9204));
18
19 ## Features
20
21 Both client and server-side HTTP/3 protocols are implemented, although the server-side
22 implementation is not meant to be used in production and its only purpose is to facilitate testing
23 of the client-side code.
24
25 __`WebTransport`__
26 ([draft version 2](https://datatracker.ietf.org/doc/html/draft-vvv-webtransport-http3-02)) is
27 supported and can be enabled using [`Http3Parameters`](struct.Http3Parameters.html).
28
29 ## Interaction with an application
30
31 ### Driving HTTP/3 session
32
33 The crate does not create an OS level UDP socket, it produces, i.e. encodes, data that should be
34 sent as a payload in a UDP packet and consumes data received on the UDP socket. For example,
35 [`std::net::UdpSocket`] or [`mio::net::UdpSocket`](https://crates.io/crates/mio)
36 could be used for creating UDP sockets.
37
38 The application is responsible for creating a socket, polling the socket, and sending and receiving
39 data from the socket.
40
41 In addition to receiving data HTTP/3 session’s actions may be triggered when a certain amount of
42 time passes, e.g. after a certain amount of time data may be considered lost and should be
43 retransmitted, packet pacing requires a timer, etc. The implementation does not use timers, but
44 instead informs the application when processing needs to be triggered.
45
46
47 The core functions for driving HTTP/3 sessions are:
48 - __On the client-side__ :
49 - [`process_output`](struct.Http3Client.html#method.process_output) used for producing UDP
50 payload. If a payload is not produced this function returns a callback time, e.g. the time when
51 [`process_output`](struct.Http3Client.html#method.process_output) should be called again.
52 - [`process_input`](struct.Http3Client.html#method.process_input) used consuming UDP payload.
53 - [`process`](struct.Http3Client.html#method.process) combines the 2 functions into one, i.e. it
54 consumes UDP payload if available and produces some UDP payload to be sent or returns a
55 callback time.
56 - __On the server-side__ only [`process`](struct.Http3Server.html#method.process) is
57 available.
58
59 An example interaction with a socket:
60
61 ```ignore
62 let socket = match UdpSocket::bind(local_addr) {
63 Err(e) => {
64 eprintln!("Unable to bind UDP socket: {}", e);
65 }
66 Ok(s) => s,
67 };
68 let mut client = Http3Client::new(...);
69
70 ...
71
72 // process_output can return 3 values, data to be sent, time duration when process_output should
73 // be called, and None when Http3Client is done.
74 match client.process_output(Instant::now()) {
75 Output::Datagram(dgram) => {
76 // Send dgram on a socket.
77 socket.send_to(&dgram[..], dgram.destination())
78
79 }
80 Output::Callback(duration) => {
81 // the client is idle for “duration”, set read timeout on the socket to this value and
82 // poll the socket for reading in the meantime.
83 socket.set_read_timeout(Some(duration)).unwrap();
84 }
85 Output::None => {
86 // client is done.
87 }
88 };
89
90 ...
91
92 // Reading new data coming for the network.
93 match socket.recv_from(&mut buf[..]) {
94 Ok((sz, remote)) => {
95 let d = Datagram::new(remote, *local_addr, &buf[..sz]);
96 client.process_input(d, Instant::now());
97 }
98 Err(err) => {
99 eprintln!("UDP error: {}", err);
100 }
101 }
102 ```
103
104 ### HTTP/3 session events
105
106 [`Http3Client`](struct.Http3Client.html) and [`Http3Server`](struct.Http3Server.html) produce
107 events that can be obtain by calling
108 [`next_event`](neqo_common/event/trait.Provider.html#tymethod.next_event). The events are of type
109 [`Http3ClientEvent`](enum.Http3ClientEvent.html) and
110 [`Http3ServerEvent`](enum.Http3ServerEvent.html) respectively. They are informing the application
111 when the connection changes state, when new data is received on a stream, etc.
112
113 ```ignore
114 ...
115
116 while let Some(event) = client.next_event() {
117 match event {
118 Http3ClientEvent::DataReadable { stream_id } => {
119 println!("New data available on stream {}", stream_id);
120 }
121 Http3ClientEvent::StateChange(Http3State::Connected) => {
122 println!("Http3 session is in state Connected now");
123 }
124 _ => {
125 println!("Unhandled event {:?}", event);
126 }
127 }
128 }
129 ```
130
131
132
133 */
134
135 mod buffered_send_stream;
136 mod client_events;
137 mod conn_params;
138 mod connection;
139 mod connection_client;
140 mod connection_server;
141 mod control_stream_local;
142 mod control_stream_remote;
143 pub mod features;
144 mod frames;
145 mod headers_checks;
146 mod priority;
147 mod push_controller;
148 mod push_id;
149 mod qlog;
150 mod qpack_decoder_receiver;
151 mod qpack_encoder_receiver;
152 mod recv_message;
153 mod request_target;
154 mod send_message;
155 mod server;
156 mod server_connection_events;
157 mod server_events;
158 mod settings;
159 mod stream_type_reader;
160
161 use std::{
162 cell::RefCell,
163 fmt::{self, Debug, Display, Formatter},
164 rc::Rc,
165 };
166
167 use buffered_send_stream::BufferedStream;
168 pub use client_events::{Http3ClientEvent, WebTransportEvent};
169 pub use conn_params::Http3Parameters;
170 pub use connection::{Http3State, WebTransportSessionAcceptAction};
171 pub use connection_client::Http3Client;
172 use features::extended_connect::WebTransportSession;
173 use frames::HFrame;
174 pub use neqo_common::Header;
175 use neqo_common::MessageType;
176 use neqo_qpack::Error as QpackError;
177 pub use neqo_transport::{streams::SendOrder, Output, StreamId};
178 use neqo_transport::{
179 AppError, Connection, Error as TransportError, RecvStreamStats, SendStreamStats,
180 };
181 pub use priority::Priority;
182 pub use push_id::PushId;
183 pub use server::Http3Server;
184 pub use server_events::{
185 Http3OrWebTransportStream, Http3ServerEvent, WebTransportRequest, WebTransportServerEvent,
186 };
187 use stream_type_reader::NewStreamType;
188
189 use crate::priority::PriorityHandler;
190
191 type Res<T> = Result<T, Error>;
192
193 #[derive(Clone, Debug, PartialEq, Eq)]
194 pub enum Error {
195 HttpNoError,
196 HttpGeneralProtocol,
197 HttpGeneralProtocolStream, /* this is the same as the above but it should only close a
198 * stream not a connection. */
199 // When using this error, you need to provide a value that is unique, which
200 // will allow the specific error to be identified. This will be validated in CI.
201 HttpInternal(u16),
202 HttpStreamCreation,
203 HttpClosedCriticalStream,
204 HttpFrameUnexpected,
205 HttpFrame,
206 HttpExcessiveLoad,
207 HttpId,
208 HttpSettings,
209 HttpMissingSettings,
210 HttpRequestRejected,
211 HttpRequestCancelled,
212 HttpRequestIncomplete,
213 HttpConnect,
214 HttpVersionFallback,
215 HttpMessageError,
216 QpackError(neqo_qpack::Error),
217
218 // Internal errors from here.
219 AlreadyClosed,
220 AlreadyInitialized,
221 FatalError,
222 HttpGoaway,
223 Internal,
224 InvalidHeader,
225 InvalidInput,
226 InvalidRequestTarget,
227 InvalidResumptionToken,
228 InvalidState,
229 InvalidStreamId,
230 NoMoreData,
231 NotEnoughData,
232 StreamLimitError,
233 TransportError(TransportError),
234 TransportStreamDoesNotExist,
235 Unavailable,
236 Unexpected,
237 }
238
239 impl Error {
240 #[must_use]
241 pub const fn code(&self) -> AppError {
242 match self {
243 Self::HttpNoError => 0x100,
244 Self::HttpGeneralProtocol | Self::HttpGeneralProtocolStream | Self::InvalidHeader => {
245 0x101
246 }
247 Self::HttpInternal(..) => 0x102,
248 Self::HttpStreamCreation => 0x103,
249 Self::HttpClosedCriticalStream => 0x104,
250 Self::HttpFrameUnexpected => 0x105,
251 Self::HttpFrame => 0x106,
252 Self::HttpExcessiveLoad => 0x107,
253 Self::HttpId => 0x108,
254 Self::HttpSettings => 0x109,
255 Self::HttpMissingSettings => 0x10a,
256 Self::HttpRequestRejected => 0x10b,
257 Self::HttpRequestCancelled => 0x10c,
258 Self::HttpRequestIncomplete => 0x10d,
259 Self::HttpMessageError => 0x10e,
260 Self::HttpConnect => 0x10f,
261 Self::HttpVersionFallback => 0x110,
262 Self::QpackError(e) => e.code(),
263 // These are all internal errors.
264 _ => 3,
265 }
266 }
267
268 #[must_use]
269 pub const fn connection_error(&self) -> bool {
270 matches!(
271 self,
272 Self::HttpGeneralProtocol
273 | Self::HttpInternal(..)
274 | Self::HttpStreamCreation
275 | Self::HttpClosedCriticalStream
276 | Self::HttpFrameUnexpected
277 | Self::HttpFrame
278 | Self::HttpExcessiveLoad
279 | Self::HttpId
280 | Self::HttpSettings
281 | Self::HttpMissingSettings
282 | Self::QpackError(QpackError::EncoderStream | QpackError::DecoderStream)
283 )
284 }
285
286 #[must_use]
287 pub const fn stream_reset_error(&self) -> bool {
288 matches!(self, Self::HttpGeneralProtocolStream | Self::InvalidHeader)
289 }
290
291 /// # Panics
292 ///
293 /// On unexpected errors, in debug mode.
294 #[must_use]
295 pub fn map_stream_send_errors(err: &Self) -> Self {
296 match err {
297 Self::TransportError(
298 TransportError::InvalidStreamId | TransportError::FinalSizeError,
299 ) => Self::TransportStreamDoesNotExist,
300 Self::TransportError(TransportError::InvalidInput) => Self::InvalidInput,
301 _ => {
302 debug_assert!(false, "Unexpected error");
303 Self::TransportStreamDoesNotExist
304 }
305 }
306 }
307
308 /// # Panics
309 ///
310 /// On unexpected errors, in debug mode.
311 #[must_use]
312 pub fn map_stream_create_errors(err: &TransportError) -> Self {
313 match err {
314 TransportError::ConnectionState => Self::Unavailable,
315 TransportError::StreamLimitError => Self::StreamLimitError,
316 _ => {
317 debug_assert!(false, "Unexpected error");
318 Self::TransportStreamDoesNotExist
319 }
320 }
321 }
322
323 /// # Panics
324 ///
325 /// On unexpected errors, in debug mode.
326 #[must_use]
327 pub fn map_stream_recv_errors(err: &Self) -> Self {
328 match err {
329 Self::TransportError(TransportError::NoMoreData) => {
330 debug_assert!(
331 false,
332 "Do not call stream_recv if FIN has been previously read"
333 );
334 }
335 Self::TransportError(TransportError::InvalidStreamId) => {}
336 _ => {
337 debug_assert!(false, "Unexpected error");
338 }
339 }
340 Self::TransportStreamDoesNotExist
341 }
342
343 #[must_use]
344 pub const fn map_set_resumption_errors(err: &TransportError) -> Self {
345 match err {
346 TransportError::ConnectionState => Self::InvalidState,
347 _ => Self::InvalidResumptionToken,
348 }
349 }
350
351 /// # Errors
352 ///
353 /// Any error is mapped to the indicated type.
354 ///
355 /// # Panics
356 ///
357 /// On internal errors, in debug mode.
358 fn map_error<R>(r: Result<R, impl Into<Self>>, err: Self) -> Result<R, Self> {
359 r.map_err(|e| {
360 debug_assert!(!matches!(e.into(), Self::HttpInternal(..)));
361 debug_assert!(!matches!(err, Self::HttpInternal(..)));
362 err
363 })
364 }
365 }
366
367 impl From<TransportError> for Error {
368 fn from(err: TransportError) -> Self {
369 Self::TransportError(err)
370 }
371 }
372
373 impl From<QpackError> for Error {
374 fn from(err: QpackError) -> Self {
375 match err {
376 QpackError::ClosedCriticalStream => Self::HttpClosedCriticalStream,
377 e => Self::QpackError(e),
378 }
379 }
380 }
381
382 impl From<AppError> for Error {
383 fn from(error: AppError) -> Self {
384 match error {
385 0x100 => Self::HttpNoError,
386 0x101 => Self::HttpGeneralProtocol,
387 0x103 => Self::HttpStreamCreation,
388 0x104 => Self::HttpClosedCriticalStream,
389 0x105 => Self::HttpFrameUnexpected,
390 0x106 => Self::HttpFrame,
391 0x107 => Self::HttpExcessiveLoad,
392 0x108 => Self::HttpId,
393 0x109 => Self::HttpSettings,
394 0x10a => Self::HttpMissingSettings,
395 0x10b => Self::HttpRequestRejected,
396 0x10c => Self::HttpRequestCancelled,
397 0x10d => Self::HttpRequestIncomplete,
398 0x10f => Self::HttpConnect,
399 0x110 => Self::HttpVersionFallback,
400 0x200 => Self::QpackError(QpackError::DecompressionFailed),
401 0x201 => Self::QpackError(QpackError::EncoderStream),
402 0x202 => Self::QpackError(QpackError::DecoderStream),
403 _ => Self::HttpInternal(0),
404 }
405 }
406 }
407
408 impl ::std::error::Error for Error {
409 fn source(&self) -> Option<&(dyn ::std::error::Error + 'static)> {
410 match self {
411 Self::TransportError(e) => Some(e),
412 Self::QpackError(e) => Some(e),
413 _ => None,
414 }
415 }
416 }
417
418 impl Display for Error {
419 fn fmt(&self, f: &mut Formatter) -> fmt::Result {
420 write!(f, "HTTP/3 error: {self:?}")
421 }
422 }
423
424 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
425 pub enum Http3StreamType {
426 Control,
427 Decoder,
428 Encoder,
429 NewStream,
430 Http,
431 Push,
432 ExtendedConnect,
433 WebTransport(StreamId),
434 Unknown,
435 }
436
437 #[must_use]
438 #[derive(Default, PartialEq, Eq, Debug)]
439 enum ReceiveOutput {
440 #[default]
441 NoOutput,
442 ControlFrames(Vec<HFrame>),
443 UnblockedStreams(Vec<StreamId>),
444 NewStream(NewStreamType),
445 }
446
447 trait Stream: Debug {
448 fn stream_type(&self) -> Http3StreamType;
449 }
450
451 trait RecvStream: Stream {
452 /// The stream reads data from the corresponding quic stream and returns `ReceiveOutput`.
453 /// The function also returns true as the second parameter if the stream is done and
454 /// could be forgotten, i.e. removed from all records.
455 ///
456 /// # Errors
457 ///
458 /// An error may happen while reading a stream, e.g. early close, protocol error, etc.
459 fn receive(&mut self, conn: &mut Connection) -> Res<(ReceiveOutput, bool)>;
460
461 /// # Errors
462 ///
463 /// An error may happen while reading a stream, e.g. early close, etc.
464 fn reset(&mut self, close_type: CloseType) -> Res<()>;
465
466 /// The function allows an app to read directly from the quic stream. The function
467 /// returns the number of bytes written into `buf` and true/false if the stream is
468 /// completely done and can be forgotten, i.e. removed from all records.
469 ///
470 /// # Errors
471 ///
472 /// An error may happen while reading a stream, e.g. early close, protocol error, etc.
473 fn read_data(&mut self, _conn: &mut Connection, _buf: &mut [u8]) -> Res<(usize, bool)> {
474 Err(Error::InvalidStreamId)
475 }
476
477 fn http_stream(&mut self) -> Option<&mut dyn HttpRecvStream> {
478 None
479 }
480
481 fn webtransport(&self) -> Option<Rc<RefCell<WebTransportSession>>> {
482 None
483 }
484
485 /// This function is only implemented by `WebTransportRecvStream`.
486 fn stats(&mut self, _conn: &mut Connection) -> Res<RecvStreamStats> {
487 Err(Error::Unavailable)
488 }
489 }
490
491 trait HttpRecvStream: RecvStream {
492 /// This function is similar to the receive function and has the same output, i.e.
493 /// a `ReceiveOutput` enum and bool. The bool is true if the stream is completely done
494 /// and can be forgotten, i.e. removed from all records.
495 ///
496 /// # Errors
497 ///
498 /// An error may happen while reading a stream, e.g. early close, protocol error, etc.
499 fn header_unblocked(&mut self, conn: &mut Connection) -> Res<(ReceiveOutput, bool)>;
500
501 fn maybe_update_priority(&mut self, priority: Priority) -> Res<bool>;
502 fn priority_update_frame(&mut self) -> Option<HFrame>;
503 fn priority_update_sent(&mut self) -> Res<()>;
504
505 fn set_new_listener(&mut self, _conn_events: Box<dyn HttpRecvStreamEvents>) {}
506 fn extended_connect_wait_for_response(&self) -> bool {
507 false
508 }
509 }
510
511 #[derive(Debug, PartialEq, Eq, Copy, Clone)]
512 pub struct Http3StreamInfo {
513 stream_id: StreamId,
514 stream_type: Http3StreamType,
515 }
516
517 impl Http3StreamInfo {
518 #[must_use]
519 pub const fn new(stream_id: StreamId, stream_type: Http3StreamType) -> Self {
520 Self {
521 stream_id,
522 stream_type,
523 }
524 }
525
526 #[must_use]
527 pub const fn stream_id(&self) -> StreamId {
528 self.stream_id
529 }
530
531 #[must_use]
532 pub const fn session_id(&self) -> Option<StreamId> {
533 if let Http3StreamType::WebTransport(session) = self.stream_type {
534 Some(session)
535 } else {
536 None
537 }
538 }
539
540 #[must_use]
541 pub fn is_http(&self) -> bool {
542 self.stream_type == Http3StreamType::Http
543 }
544 }
545
546 trait RecvStreamEvents: Debug {
547 fn data_readable(&self, _stream_info: Http3StreamInfo) {}
548 fn recv_closed(&self, _stream_info: Http3StreamInfo, _close_type: CloseType) {}
549 }
550
551 trait HttpRecvStreamEvents: RecvStreamEvents {
552 fn header_ready(
553 &self,
554 stream_info: Http3StreamInfo,
555 headers: Vec<Header>,
556 interim: bool,
557 fin: bool,
558 );
559 fn extended_connect_new_session(&self, _stream_id: StreamId, _headers: Vec<Header>) {}
560 }
561
562 trait SendStream: Stream {
563 /// # Errors
564 ///
565 /// Error may occur during sending data, e.g. protocol error, etc.
566 fn send(&mut self, conn: &mut Connection) -> Res<()>;
567 fn has_data_to_send(&self) -> bool;
568 fn stream_writable(&self);
569 fn done(&self) -> bool;
570
571 /// # Errors
572 ///
573 /// Error may occur during sending data, e.g. protocol error, etc.
574 fn send_data(&mut self, _conn: &mut Connection, _buf: &[u8]) -> Res<usize>;
575
576 /// # Errors
577 ///
578 /// It may happen that the transport stream is already closed. This is unlikely.
579 fn close(&mut self, conn: &mut Connection) -> Res<()>;
580
581 /// # Errors
582 ///
583 /// It may happen that the transport stream is already closed. This is unlikely.
584 fn close_with_message(
585 &mut self,
586 _conn: &mut Connection,
587 _error: u32,
588 _message: &str,
589 ) -> Res<()> {
590 Err(Error::InvalidStreamId)
591 }
592
593 /// This function is called when sending side is closed abruptly by the peer or
594 /// the application.
595 fn handle_stop_sending(&mut self, close_type: CloseType);
596 fn http_stream(&mut self) -> Option<&mut dyn HttpSendStream> {
597 None
598 }
599
600 /// # Errors
601 ///
602 /// It may happen that the transport stream is already closed. This is unlikely.
603 fn send_data_atomic(&mut self, _conn: &mut Connection, _buf: &[u8]) -> Res<()> {
604 Err(Error::InvalidStreamId)
605 }
606
607 /// This function is only implemented by `WebTransportSendStream`.
608 fn stats(&mut self, _conn: &mut Connection) -> Res<SendStreamStats> {
609 Err(Error::Unavailable)
610 }
611 }
612
613 trait HttpSendStream: SendStream {
614 /// This function is used to supply headers to a http message. The
615 /// function is used for request headers, response headers, 1xx response and
616 /// trailers.
617 ///
618 /// # Errors
619 ///
620 /// This can also return an error if the underlying stream is closed.
621 fn send_headers(&mut self, headers: &[Header], conn: &mut Connection) -> Res<()>;
622 fn set_new_listener(&mut self, _conn_events: Box<dyn SendStreamEvents>) {}
623 }
624
625 trait SendStreamEvents: Debug {
626 fn send_closed(&self, _stream_info: Http3StreamInfo, _close_type: CloseType) {}
627 fn data_writable(&self, _stream_info: Http3StreamInfo) {}
628 }
629
630 /// This enum is used to mark a different type of closing a stream:
631 /// `ResetApp` - the application has closed the stream.
632 /// `ResetRemote` - the stream was closed by the peer.
633 /// `LocalError` - There was a stream error on the stream. The stream errors are errors
634 /// that do not close the complete connection, e.g. unallowed headers.
635 /// `Done` - the stream was closed without an error.
636 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
637 enum CloseType {
638 ResetApp(AppError),
639 ResetRemote(AppError),
640 LocalError(AppError),
641 Done,
642 }
643
644 impl CloseType {
645 #[must_use]
646 pub const fn error(&self) -> Option<AppError> {
647 match self {
648 Self::ResetApp(error) | Self::ResetRemote(error) | Self::LocalError(error) => {
649 Some(*error)
650 }
651 Self::Done => None,
652 }
653 }
654
655 #[must_use]
656 pub const fn locally_initiated(&self) -> bool {
657 matches!(self, Self::ResetApp(_))
658 }
659 }