confium_net_quic/lib.rs
1//! QUIC transport for Confium.
2//!
3//! `quic://host:port` URLs address a peer reachable over QUIC. A
4//! [`QuicListener`] bound via `quic://0.0.0.0:port` accepts inbound
5//! connections and yields [`QuicTransport`] handles on
6//! [`confium_net::Listener::accept`].
7//!
8//! QUIC streams are reliable, ordered, and per-stream — but Confium's
9//! [`confium_net::Transport`] contract is "one `send` == one `recv`
10//! payload." Each transport handle opens a single bidirectional QUIC
11//! stream and frames every message with a 4-byte big-endian length
12//! prefix, mirroring the TCP transport so cross-transport semantics
13//! are identical. (Future work could use one stream per message for
14//! head-of-line-blocking freedom; the framing stays the same.)
15//!
16//! ## TLS / authentication
17//!
18//! QUIC mandates TLS 1.3. Confium's TC protocol signs each round
19//! message at the application layer (see `TODO.roadmap/05-networking-
20//! primitives.md`), so the transport itself uses an in-memory
21//! self-signed certificate that the client accepts unconditionally
22//! (`ServerConfig` peer verification disabled). This is the third
23//! authentication option listed in the roadmap: "application-layer
24//! signatures — TC session itself signs each round message; transport
25//! is unauthenticated but the protocol is safe."
26//!
27//! ## Runtime
28//!
29//! Quinn is async. The [`confium_net::Transport`] / [`confium_net::Listener`]
30//! traits are blocking. Each transport/listener handle drives its async
31//! work via the shared runtime's `block_on`, presenting a synchronous
32//! facade to callers.
33//!
34//! # Schemes
35//!
36//! - `quic` — accept either IPv4 or IPv6 addresses.
37//! - `quic4` — restrict to IPv4.
38//! - `quic6` — restrict to IPv6.
39
40pub mod listener;
41pub mod runtime;
42pub mod tls;
43pub mod transport;
44
45pub use listener::QuicListener;
46pub use transport::QuicTransport;
47pub use transport::QuicTransportKind;
48
49use confium_net::register_transport;
50
51// One kind owns all three schemes. `register_transport!` submits it to
52// the link-time inventory so `confium_net::connect` /
53// `confium_net::listen` can dispatch to it by scheme.
54register_transport!(QuicTransportKind);