Skip to main content

karyon_net/transports/
quic.rs

1use std::{
2    io,
3    net::SocketAddr,
4    pin::Pin,
5    sync::Arc,
6    task::{Context, Poll},
7    time::Duration,
8};
9
10use quinn::{Incoming, VarInt};
11use rustls_pki_types::{CertificateDer, PrivateKeyDer};
12
13use crate::async_rustls::rustls;
14
15use karyon_core::{
16    async_runtime::io::{AsyncRead, AsyncWrite},
17    async_util::timeout,
18};
19
20#[cfg(feature = "tokio")]
21use tokio::io::{AsyncWrite as TokioAsyncWrite, ReadBuf};
22
23#[cfg(feature = "smol")]
24use futures_util::io::{AsyncRead as FutAsyncRead, AsyncWrite as FutAsyncWrite};
25
26use crate::{
27    ACCEPT_HANDSHAKE_TIMEOUT, Bytes, Endpoint, Error, Result, endpoint::resolve_endpoint,
28    stream::ByteStream, stream_mux::StreamMux,
29};
30
31/// Default max unacked bytes a peer may send on one stream.
32const DEFAULT_STREAM_RECEIVE_WINDOW: u32 = 1024 * 1024; // 1MB
33
34/// Default max unacked bytes a peer may send on all streams of one
35/// connection. quinn's default is unbounded.
36const DEFAULT_RECEIVE_WINDOW: u32 = 8 * 1024 * 1024; // 8MB
37
38/// A QUIC send stream. Re-exported from quinn for use by higher layers.
39pub type QuicSendStream = quinn::SendStream;
40
41/// A QUIC receive stream. Re-exported from quinn for use by higher layers.
42pub type QuicRecvStream = quinn::RecvStream;
43
44/// QUIC configuration.
45#[derive(Clone)]
46pub struct QuicConfig {
47    /// Maximum concurrent bidirectional streams.
48    pub max_bi_streams: u64,
49    /// Maximum concurrent unidirectional streams.
50    pub max_uni_streams: u64,
51    /// Keep-alive interval. None to disable.
52    pub keep_alive_interval: Option<Duration>,
53    /// Idle timeout.
54    pub idle_timeout: Option<Duration>,
55    /// Enable datagrams.
56    pub enable_datagrams: bool,
57    /// Max unacked bytes a peer may send on one stream.
58    pub stream_receive_window: u64,
59    /// Max unacked bytes a peer may send on all streams of one connection.
60    pub receive_window: u64,
61}
62
63impl Default for QuicConfig {
64    fn default() -> Self {
65        Self {
66            max_bi_streams: 100,
67            max_uni_streams: 100,
68            keep_alive_interval: Some(Duration::from_secs(5)),
69            idle_timeout: Some(Duration::from_secs(30)),
70            enable_datagrams: false,
71            stream_receive_window: DEFAULT_STREAM_RECEIVE_WINDOW.into(),
72            receive_window: DEFAULT_RECEIVE_WINDOW.into(),
73        }
74    }
75}
76
77/// Server-side QUIC configuration. Build from either a cert chain +
78/// private key (`new`) or a pre-built rustls config (`from_rustls`).
79#[derive(Clone)]
80pub struct ServerQuicConfig {
81    source: ServerSource,
82    config: QuicConfig,
83    /// Max time `QuicEndpoint::accept` waits for a handshake.
84    handshake_timeout: Duration,
85}
86
87#[derive(Clone)]
88enum ServerSource {
89    Certs {
90        cert_chain: Vec<CertificateDer<'static>>,
91        private_key: Arc<PrivateKeyDer<'static>>,
92    },
93    Rustls(Box<rustls::ServerConfig>),
94}
95
96impl ServerQuicConfig {
97    /// Create a config from a cert chain + private key.
98    pub fn new(
99        cert_chain: Vec<CertificateDer<'static>>,
100        private_key: Arc<PrivateKeyDer<'static>>,
101    ) -> Self {
102        Self {
103            source: ServerSource::Certs {
104                cert_chain,
105                private_key,
106            },
107            config: QuicConfig::default(),
108            handshake_timeout: ACCEPT_HANDSHAKE_TIMEOUT,
109        }
110    }
111
112    /// Create a config from a pre-built rustls `ServerConfig` (for
113    /// custom verifiers, client-auth, etc).
114    pub fn from_rustls(rustls_config: rustls::ServerConfig) -> Self {
115        Self {
116            source: ServerSource::Rustls(Box::new(rustls_config)),
117            config: QuicConfig::default(),
118            handshake_timeout: ACCEPT_HANDSHAKE_TIMEOUT,
119        }
120    }
121
122    /// Override the QUIC transport parameters.
123    pub fn with_config(mut self, config: QuicConfig) -> Self {
124        self.config = config;
125        self
126    }
127
128    /// Set the max time `QuicEndpoint::accept` waits for a handshake.
129    /// Defaults to 10s.
130    pub fn with_handshake_timeout(mut self, timeout: Duration) -> Self {
131        self.handshake_timeout = timeout;
132        self
133    }
134
135    pub(crate) fn build(self) -> Result<quinn::ServerConfig> {
136        let mut server_config = match self.source {
137            ServerSource::Certs {
138                cert_chain,
139                private_key,
140            } => quinn::ServerConfig::with_single_cert(cert_chain, private_key.clone_key())
141                .map_err(|e| Error::TlsConfig(e.to_string()))?,
142            ServerSource::Rustls(rustls_config) => {
143                let quic_config = quinn::crypto::rustls::QuicServerConfig::try_from(*rustls_config)
144                    .map_err(|e| Error::QuicConfigError(e.to_string()))?;
145                quinn::ServerConfig::with_crypto(Arc::new(quic_config))
146            }
147        };
148        server_config.transport_config(Arc::new(build_transport_config(&self.config)));
149        Ok(server_config)
150    }
151}
152
153/// Client-side QUIC configuration. Build from either a root cert list
154/// (`new`) or a pre-built rustls config (`from_rustls`).
155#[derive(Clone)]
156pub struct ClientQuicConfig {
157    source: ClientSource,
158    server_name: String,
159    config: QuicConfig,
160}
161
162#[derive(Clone)]
163enum ClientSource {
164    Roots(Vec<CertificateDer<'static>>),
165    Rustls(Box<rustls::ClientConfig>),
166}
167
168impl ClientQuicConfig {
169    /// Create a config from a list of trusted root certs + server name.
170    pub fn new(root_certs: Vec<CertificateDer<'static>>, server_name: impl Into<String>) -> Self {
171        Self {
172            source: ClientSource::Roots(root_certs),
173            server_name: server_name.into(),
174            config: QuicConfig::default(),
175        }
176    }
177
178    /// Create a config from a pre-built rustls `ClientConfig` + server name
179    /// (for custom verifiers, client-auth certs, etc).
180    pub fn from_rustls(
181        rustls_config: rustls::ClientConfig,
182        server_name: impl Into<String>,
183    ) -> Self {
184        Self {
185            source: ClientSource::Rustls(Box::new(rustls_config)),
186            server_name: server_name.into(),
187            config: QuicConfig::default(),
188        }
189    }
190
191    /// Override the QUIC transport parameters.
192    pub fn with_config(mut self, config: QuicConfig) -> Self {
193        self.config = config;
194        self
195    }
196
197    pub fn server_name(&self) -> &str {
198        &self.server_name
199    }
200
201    pub(crate) fn build(self) -> Result<quinn::ClientConfig> {
202        let mut client_config = match self.source {
203            ClientSource::Roots(root_certs) => {
204                let mut root_store = rustls::RootCertStore::empty();
205                for cert in root_certs {
206                    root_store
207                        .add(cert)
208                        .map_err(|e| Error::TlsConfig(e.to_string()))?;
209                }
210                quinn::ClientConfig::with_root_certificates(Arc::new(root_store))
211                    .map_err(|e| Error::TlsConfig(e.to_string()))?
212            }
213            ClientSource::Rustls(rustls_config) => {
214                let quic_config = quinn::crypto::rustls::QuicClientConfig::try_from(*rustls_config)
215                    .map_err(|e| Error::QuicConfigError(e.to_string()))?;
216                quinn::ClientConfig::new(Arc::new(quic_config))
217            }
218        };
219        client_config.transport_config(Arc::new(build_transport_config(&self.config)));
220        Ok(client_config)
221    }
222}
223
224fn build_transport_config(config: &QuicConfig) -> quinn::TransportConfig {
225    let mut transport = quinn::TransportConfig::default();
226    transport.max_concurrent_bidi_streams(
227        quinn::VarInt::from_u64(config.max_bi_streams).unwrap_or(quinn::VarInt::from_u32(100u32)),
228    );
229    transport.max_concurrent_uni_streams(
230        VarInt::from_u64(config.max_uni_streams).unwrap_or(VarInt::from_u32(100u32)),
231    );
232    // Bound the memory a peer can make us buffer per connection.
233    // Values above 2^62 do not fit a VarInt, use the defaults then.
234    transport.stream_receive_window(
235        VarInt::from_u64(config.stream_receive_window)
236            .unwrap_or(VarInt::from_u32(DEFAULT_STREAM_RECEIVE_WINDOW)),
237    );
238    transport.receive_window(
239        VarInt::from_u64(config.receive_window).unwrap_or(VarInt::from_u32(DEFAULT_RECEIVE_WINDOW)),
240    );
241    if let Some(interval) = config.keep_alive_interval {
242        transport.keep_alive_interval(Some(interval));
243    }
244    if let Some(timeout) = config.idle_timeout
245        && let Ok(idle) = quinn::IdleTimeout::try_from(timeout)
246    {
247        transport.max_idle_timeout(Some(idle));
248    }
249    // Disable datagrams explicitly when the caller opts out.
250    if !config.enable_datagrams {
251        transport.datagram_receive_buffer_size(None);
252    }
253    transport
254}
255
256/// A QUIC endpoint that can listen for and initiate connections.
257pub struct QuicEndpoint {
258    inner: quinn::Endpoint,
259    local_endpoint: Endpoint,
260    handshake_timeout: Duration,
261}
262
263impl QuicEndpoint {
264    /// Bind to a local address and start listening with the given server config.
265    pub async fn listen(endpoint: &Endpoint, config: ServerQuicConfig) -> Result<Self> {
266        let addr = SocketAddr::try_from(endpoint.clone())?;
267        let handshake_timeout = config.handshake_timeout;
268        let server_config = config.build()?;
269        let inner = quinn::Endpoint::server(server_config, addr)?;
270        let local_addr = inner.local_addr()?;
271        let local_endpoint = Endpoint::new_quic_addr(local_addr);
272        Ok(Self {
273            inner,
274            local_endpoint,
275            handshake_timeout,
276        })
277    }
278
279    /// Connect to a remote QUIC endpoint.
280    pub async fn dial(endpoint: &Endpoint, config: ClientQuicConfig) -> Result<QuicConn> {
281        let addr = resolve_endpoint(endpoint).await?;
282        let server_name = config.server_name.clone();
283        let client_config = config.build()?;
284        // Bind the client socket in the same address family as the target.
285        let bind_addr: SocketAddr = if addr.is_ipv6() {
286            "[::]:0".parse().unwrap()
287        } else {
288            "0.0.0.0:0".parse().unwrap()
289        };
290        let mut quinn_endpoint = quinn::Endpoint::client(bind_addr)?;
291        quinn_endpoint.set_default_client_config(client_config);
292
293        let connection = quinn_endpoint.connect(addr, &server_name)?.await?;
294        let peer_endpoint = Endpoint::new_quic_addr(connection.remote_address());
295        let local_addr = quinn_endpoint.local_addr()?;
296        let local_endpoint = Endpoint::new_quic_addr(local_addr);
297
298        Ok(QuicConn {
299            inner: connection,
300            peer_endpoint,
301            local_endpoint,
302        })
303    }
304
305    /// Accept an incoming QUIC connection without running its handshake.
306    ///
307    /// Servers should use this and drive [`QuicIncoming::handshake`] in a
308    /// separate task, so a slow peer cannot stall the accept loop.
309    pub async fn accept_incoming(&self) -> Result<QuicIncoming> {
310        let inner = self.inner.accept().await.ok_or(Error::ConnectionClosed)?;
311        Ok(QuicIncoming {
312            inner,
313            local_endpoint: self.local_endpoint.clone(),
314        })
315    }
316
317    /// Accept an incoming QUIC connection and run its handshake. The
318    /// handshake runs inline and fails after the handshake timeout (10s by
319    /// default, see [`ServerQuicConfig::with_handshake_timeout`]), so a slow
320    /// peer stalls a plain accept loop for up to that long. Servers should
321    /// use [`Self::accept_incoming`] instead.
322    pub async fn accept(&self) -> Result<QuicConn> {
323        let incoming = self.accept_incoming().await?;
324        timeout(self.handshake_timeout, incoming.handshake()).await?
325    }
326
327    /// Returns the local endpoint.
328    pub fn local_endpoint(&self) -> Result<Endpoint> {
329        Ok(self.local_endpoint.clone())
330    }
331
332    /// Close the endpoint.
333    pub fn close(&self, code: u32, reason: &[u8]) {
334        self.inner.close(quinn::VarInt::from_u32(code), reason);
335    }
336}
337
338/// An accepted QUIC connection whose handshake has not run yet.
339pub struct QuicIncoming {
340    inner: Incoming,
341    local_endpoint: Endpoint,
342}
343
344impl QuicIncoming {
345    /// Runs the QUIC/TLS handshake.
346    pub async fn handshake(self) -> Result<QuicConn> {
347        let connection = self.inner.await?;
348        let peer_endpoint = Endpoint::new_quic_addr(connection.remote_address());
349        Ok(QuicConn {
350            inner: connection,
351            peer_endpoint,
352            local_endpoint: self.local_endpoint,
353        })
354    }
355
356    /// Remote address of the peer. Known before the handshake runs.
357    pub fn peer_endpoint(&self) -> Endpoint {
358        Endpoint::new_quic_addr(self.inner.remote_address())
359    }
360}
361
362/// A QUIC connection. Manages streams and datagrams.
363/// This is NOT a single read/write channel — it is a stream factory.
364pub struct QuicConn {
365    inner: quinn::Connection,
366    peer_endpoint: Endpoint,
367    local_endpoint: Endpoint,
368}
369
370impl QuicConn {
371    /// Open a new bidirectional stream.
372    pub async fn open_bi(&self) -> Result<(QuicSendStream, QuicRecvStream)> {
373        let (send, recv) = self.inner.open_bi().await?;
374        Ok((send, recv))
375    }
376
377    /// Open a new unidirectional (send-only) stream.
378    pub async fn open_uni(&self) -> Result<QuicSendStream> {
379        let send = self.inner.open_uni().await?;
380        Ok(send)
381    }
382
383    /// Accept a bidirectional stream opened by the peer.
384    pub async fn accept_bi(&self) -> Result<(QuicSendStream, QuicRecvStream)> {
385        let (send, recv) = self.inner.accept_bi().await?;
386        Ok((send, recv))
387    }
388
389    /// Accept a unidirectional (receive-only) stream from the peer.
390    pub async fn accept_uni(&self) -> Result<QuicRecvStream> {
391        let recv = self.inner.accept_uni().await?;
392        Ok(recv)
393    }
394
395    /// Send an unreliable datagram over the connection. Zero-copy —
396    /// ownership of the `Bytes` allocation is passed to quinn.
397    pub fn send_datagram(&self, data: Bytes) -> Result<()> {
398        self.inner
399            .send_datagram(data.into_inner())
400            .map_err(|e| Error::QuicConfigError(e.to_string()))?;
401        Ok(())
402    }
403
404    /// Receive an unreliable datagram. Zero-copy — wraps the allocation
405    /// returned by quinn.
406    pub async fn recv_datagram(&self) -> Result<Bytes> {
407        let data = self.inner.read_datagram().await?;
408        Ok(Bytes::from_inner(data))
409    }
410
411    /// Maximum datagram size the peer supports, or None if unsupported.
412    pub fn max_datagram_size(&self) -> Option<usize> {
413        self.inner.max_datagram_size()
414    }
415
416    /// Remote peer's address.
417    pub fn peer_endpoint(&self) -> Result<Endpoint> {
418        Ok(self.peer_endpoint.clone())
419    }
420
421    /// Local address.
422    pub fn local_endpoint(&self) -> Result<Endpoint> {
423        Ok(self.local_endpoint.clone())
424    }
425
426    /// Current round-trip time estimate.
427    pub fn rtt(&self) -> Duration {
428        self.inner.rtt()
429    }
430
431    /// Close the connection gracefully.
432    pub fn close(&self, code: u32, reason: &[u8]) {
433        self.inner.close(quinn::VarInt::from_u32(code), reason);
434    }
435
436    /// Wait for the connection to be closed (by us or the peer).
437    pub async fn closed(&self) -> quinn::ConnectionError {
438        self.inner.closed().await
439    }
440
441    /// Returns a reference to the inner quinn connection.
442    pub fn inner(&self) -> &quinn::Connection {
443        &self.inner
444    }
445
446    /// Peer certificate chain from the QUIC TLS handshake. Quinn returns
447    /// a type-erased `Box<dyn Any>`; for rustls-based QUIC (which is what
448    /// karyon uses) it downcasts to `Vec<CertificateDer<'static>>`.
449    pub fn peer_certificates(&self) -> Option<Vec<CertificateDer<'static>>> {
450        let any = self.inner.peer_identity()?;
451        any.downcast::<Vec<CertificateDer<'static>>>()
452            .ok()
453            .map(|b| *b)
454    }
455}
456
457// -- StreamMux impl --
458
459impl StreamMux for QuicConn {
460    async fn open_stream(&self) -> Result<Box<dyn ByteStream>> {
461        let (send, recv) = self.open_bi().await?;
462        Ok(Box::new(QuicBiStream {
463            send,
464            recv,
465            peer_endpoint: self.peer_endpoint.clone(),
466            local_endpoint: self.local_endpoint.clone(),
467        }))
468    }
469
470    async fn accept_stream(&self) -> Result<Box<dyn ByteStream>> {
471        let (send, recv) = self.accept_bi().await?;
472        Ok(Box::new(QuicBiStream {
473            send,
474            recv,
475            peer_endpoint: self.peer_endpoint.clone(),
476            local_endpoint: self.local_endpoint.clone(),
477        }))
478    }
479
480    fn peer_endpoint(&self) -> Option<Endpoint> {
481        Some(self.peer_endpoint.clone())
482    }
483
484    fn local_endpoint(&self) -> Option<Endpoint> {
485        Some(self.local_endpoint.clone())
486    }
487}
488
489/// Single QUIC bidirectional stream as a ByteStream.
490pub struct QuicBiStream {
491    send: QuicSendStream,
492    recv: QuicRecvStream,
493    peer_endpoint: Endpoint,
494    local_endpoint: Endpoint,
495}
496
497impl ByteStream for QuicBiStream {
498    fn peer_endpoint(&self) -> Option<Endpoint> {
499        Some(self.peer_endpoint.clone())
500    }
501    fn local_endpoint(&self) -> Option<Endpoint> {
502        Some(self.local_endpoint.clone())
503    }
504}
505
506// Quinn streams use tokio IO traits natively.
507// For smol builds, delegate manually via poll methods.
508
509#[cfg(feature = "tokio")]
510impl AsyncRead for QuicBiStream {
511    fn poll_read(
512        mut self: Pin<&mut Self>,
513        cx: &mut Context<'_>,
514        buf: &mut ReadBuf<'_>,
515    ) -> Poll<io::Result<()>> {
516        Pin::new(&mut self.recv).poll_read(cx, buf)
517    }
518}
519
520#[cfg(feature = "smol")]
521impl AsyncRead for QuicBiStream {
522    fn poll_read(
523        mut self: Pin<&mut Self>,
524        cx: &mut Context<'_>,
525        buf: &mut [u8],
526    ) -> Poll<io::Result<usize>> {
527        FutAsyncRead::poll_read(Pin::new(&mut self.recv), cx, buf)
528    }
529}
530
531#[cfg(feature = "tokio")]
532impl AsyncWrite for QuicBiStream {
533    fn poll_write(
534        mut self: Pin<&mut Self>,
535        cx: &mut Context<'_>,
536        buf: &[u8],
537    ) -> Poll<io::Result<usize>> {
538        TokioAsyncWrite::poll_write(Pin::new(&mut self.send), cx, buf)
539    }
540
541    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
542        TokioAsyncWrite::poll_flush(Pin::new(&mut self.send), cx)
543    }
544
545    fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
546        TokioAsyncWrite::poll_shutdown(Pin::new(&mut self.send), cx)
547    }
548}
549
550#[cfg(feature = "smol")]
551impl AsyncWrite for QuicBiStream {
552    fn poll_write(
553        mut self: Pin<&mut Self>,
554        cx: &mut Context<'_>,
555        buf: &[u8],
556    ) -> Poll<io::Result<usize>> {
557        FutAsyncWrite::poll_write(Pin::new(&mut self.send), cx, buf)
558    }
559
560    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
561        FutAsyncWrite::poll_flush(Pin::new(&mut self.send), cx)
562    }
563
564    fn poll_close(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
565        FutAsyncWrite::poll_close(Pin::new(&mut self.send), cx)
566    }
567}