wtransport/
lib.rs

1//! WebTransport protocol implementation in *pure* Rust, *async-friendly*, and *API-simple*.
2//!
3//! For a quick start with this library, refer to [`Endpoint`].
4//!
5//! ## About WebTransport
6//! WebTransport is a modern protocol built on [QUIC](https://en.wikipedia.org/wiki/QUIC)
7//! and [HTTP/3](https://en.wikipedia.org/wiki/HTTP/3), providing an alternative to
8//! HTTP and WebSocket.
9//!
10//! It's designed for efficient client-server communication with *low latency* and
11//! bi-directional *multistream* data exchange capabilities, making it suitable for a wide range of
12//! applications.
13//!
14//! WebTransport guarantees *secure* and *reliable* communication by leveraging encryption
15//! and authentication to protect your data during transmission.
16//!
17//! WebTransport offers two key communication channels: *streams* and *datagrams*.
18//!
19//! ### Streams
20//! WebTransport streams are communication channels that provide *ordered* and
21//! *reliable* data transfer.
22//!
23//! WebTransport streams allow sending multiple sets of data at once within a single session.
24//! Each stream operates independently, ensuring that the order and reliability
25//! of one stream do not affect the others.
26//!
27//! Streams can be: *uni-directional* or *bi-directional*.
28//!
29//! *Order Preserved, Guaranteed Delivery, Flow-Controlled, Secure (All Traffic Encrypted),
30//! and Multiple Independent Streams*.
31//!
32//! ## Datagrams
33//! WebTransport datagrams are lightweight and *unordered* communication channels,
34//! prioritizing quick data exchange without guarantees of reliability or sequence.
35//!
36//! *Unordered, No Guaranteed Delivery, No Flow-Controlled, Secure (All Traffic Encrypted),
37//! Independent Messages*.
38//!
39//!
40//! # Examples
41//! Explore operational server and client examples below. The elegantly simple yet potent
42//! API empowers you to get started with minimal code.
43//!
44//! ## Server
45//! ```no_run
46//! # use anyhow::Result;
47//! use wtransport::Endpoint;
48//! use wtransport::Identity;
49//! use wtransport::ServerConfig;
50//!
51//! #[tokio::main]
52//! async fn main() -> Result<()> {
53//!     let config = ServerConfig::builder()
54//!         .with_bind_default(4433)
55//!         .with_identity(Identity::load_pemfiles("cert.pem", "key.pem").await?)
56//!         .build();
57//!
58//!     let server = Endpoint::server(config)?;
59//!
60//!     loop {
61//!         let incoming_session = server.accept().await;
62//!         let incoming_request = incoming_session.await?;
63//!         let connection = incoming_request.accept().await?;
64//!         // ...
65//!     }
66//! }
67//! ```
68//! See [repository server example](https://github.com/BiagioFesta/wtransport/blob/master/wtransport/examples/server.rs)
69//! for the complete code.
70//!
71//! ## Client
72//! ```no_run
73//! # use anyhow::Result;
74//! use wtransport::ClientConfig;
75//! use wtransport::Endpoint;
76//!
77//! #[tokio::main]
78//! async fn main() -> Result<()> {
79//!     let connection = Endpoint::client(ClientConfig::default())?
80//!         .connect("https://localhost:4433")
81//!         .await?;
82//!     // ...
83//!   # Ok(())
84//! }
85//! ```
86//! See [repository client example](https://github.com/BiagioFesta/wtransport/blob/master/wtransport/examples/client.rs)
87//! for the complete code.
88#![cfg_attr(docsrs, feature(doc_cfg))]
89#![warn(missing_docs, clippy::doc_markdown)]
90
91/// Client and server configurations.
92pub mod config;
93
94/// WebTransport connection.
95pub mod connection;
96
97/// Endpoint module.
98pub mod endpoint;
99
100/// Errors definitions module.
101pub mod error;
102
103/// Interfaces for sending and receiving data.
104pub mod stream;
105
106/// TLS specific configurations.
107pub mod tls;
108
109/// Datagrams module.
110pub mod datagram;
111
112#[doc(inline)]
113pub use config::ClientConfig;
114
115#[doc(inline)]
116pub use config::ServerConfig;
117
118#[doc(inline)]
119pub use tls::Identity;
120
121#[doc(inline)]
122pub use endpoint::Endpoint;
123
124#[doc(inline)]
125pub use connection::Connection;
126
127#[doc(inline)]
128pub use stream::RecvStream;
129
130#[doc(inline)]
131pub use stream::SendStream;
132
133#[doc(inline)]
134pub use wtransport_proto::varint::VarInt;
135
136#[doc(inline)]
137pub use wtransport_proto::ids::StreamId;
138
139#[doc(inline)]
140pub use wtransport_proto::ids::SessionId;
141
142pub use wtransport_proto as proto;
143
144#[cfg(feature = "quinn")]
145#[cfg_attr(docsrs, doc(cfg(feature = "quinn")))]
146pub use quinn;
147
148mod driver;
wtransport/lib.rs

wtransport/
lib.rs
