Skip to main content

hyprstream_rpc/transport/
lazy_quinn.rs

1//! Lazy-connecting quinn RPC transport.
2//!
3//! The [`dial`](crate::dial::dial) factory is synchronous and does no I/O, but a
4//! networked QUIC peer must be connected before the first request. This wrapper
5//! bridges that: it holds the dial target (`addr` + `server_name` + the
6//! [`QuicServerAuth`](crate::transport::QuicServerAuth) policy) and connects on
7//! the **first `send()`**, caching the established session for subsequent calls
8//! — exactly the lazy-connect model `ZmqConnection` uses, so sync construction +
9//! zero I/O at dial time is preserved (A1 spike). The connect path (WebPKI vs
10//! cert-hash pin) is selected by the auth policy.
11//!
12//! # Re-dial / self-heal
13//!
14//! On a `send()` error the cached session is dropped, so the next call re-dials
15//! — like `ZmqConnection`, which a dead cached session would otherwise not
16//! recover from. This is deliberately **coarse**: it re-dials on *any* failure,
17//! including a per-request timeout on an otherwise-live connection. Refined,
18//! liveness-based re-dial with backoff is the connection-manager's job (#156);
19//! this wrapper only needs to not strand a dead session.
20//!
21//! Concurrent first-sends are **single-flighted**: the dial happens under the
22//! cache lock, so N racing callers dial once and the rest reuse the session.
23//! The connected handle is cloned out from under the lock (both `QuinnTransport`
24//! and its `Session` are cheap `Clone`), so `send()` itself never holds the
25//! lock — only the dial does.
26
27use std::net::SocketAddr;
28use std::time::Duration;
29
30use anyhow::{anyhow, bail, Result};
31use async_trait::async_trait;
32use tokio::sync::Mutex;
33
34use crate::transport::backoff::LazyState;
35use crate::transport::quinn_transport::{
36    connect_pinned_hashes, connect_webpki, verify_peer_cert_pinned, QuinnPendingStream,
37    QuinnPublishStub, QuinnTransport,
38};
39use crate::transport::QuicServerAuth;
40use crate::transport_traits::Transport;
41
42/// Default per-request deadline when the caller passes `None`, mirroring
43/// `SessionRpcTransport`.
44const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
45
46/// Ceiling on the lazy connect itself (TLS handshake + dial). The per-request
47/// deadline wraps only the *request*; without this a dead/misrouted address (or
48/// a stalled handshake) would hang the first `send()` indefinitely.
49const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
50
51/// A quinn RPC transport that connects on first use and caches the session.
52pub struct LazyQuinnTransport {
53    addr: SocketAddr,
54    server_name: String,
55    auth: QuicServerAuth,
56    /// Cached session + reconnect backoff state (#156). `None` until the first
57    /// successful dial; reset to `None` (with backoff recorded) after any
58    /// transport-fatal `send()` error or failed dial.
59    state: Mutex<LazyState<QuinnTransport>>,
60}
61
62impl LazyQuinnTransport {
63    /// Create a lazy transport for a QUIC peer, authenticated per `auth`
64    /// (WebPKI, cert-hash pin, or — later — RFC 7250 raw key). No connection is
65    /// made until the first `send()`.
66    pub fn new(addr: SocketAddr, server_name: impl Into<String>, auth: QuicServerAuth) -> Self {
67        Self {
68            addr,
69            server_name: server_name.into(),
70            auth,
71            state: Mutex::new(LazyState::default()),
72        }
73    }
74
75    /// Return the cached connected transport, dialing once (under the lock —
76    /// single-flight) if not yet connected. Backs off after consecutive failures
77    /// so a downed peer is not tight-looped (#156).
78    async fn connected(&self) -> Result<QuinnTransport> {
79        let mut guard = self.state.lock().await;
80        if let Some(transport) = guard.cached.as_ref() {
81            return Ok(transport.clone());
82        }
83        if let Some(remaining) = guard.backoff.cooldown_remaining() {
84            return Err(anyhow!(
85                "quinn peer is in reconnect backoff — retry in {remaining:.1?}"
86            ));
87        }
88        let connect = async {
89            let hashes = self.auth.accept_cert_hashes();
90            match (self.auth.require_web_pki(), hashes.is_empty()) {
91                (true, true) => connect_webpki(&self.server_name, self.addr.port()).await,
92                (false, false) => connect_pinned_hashes(self.addr, hashes).await,
93                (true, false) => {
94                    let session = connect_webpki(&self.server_name, self.addr.port()).await?;
95                    verify_peer_cert_pinned(&session, hashes)?;
96                    Ok(session)
97                }
98                (false, true) => bail!("QUIC endpoint has no server-auth requirement"),
99            }
100        };
101        match tokio::time::timeout(CONNECT_TIMEOUT, connect).await {
102            Err(_) => {
103                guard.backoff.record_failure();
104                Err(anyhow!("quinn connect timed out after {CONNECT_TIMEOUT:?}"))
105            }
106            Ok(Err(e)) => {
107                guard.backoff.record_failure();
108                Err(e)
109            }
110            Ok(Ok(session)) => {
111                guard.backoff.record_success();
112                let transport = QuinnTransport::new(session);
113                guard.cached = Some(transport.clone());
114                Ok(transport)
115            }
116        }
117    }
118
119    /// Drop the cached session and record a failure so the next `send()`
120    /// re-dials after the backoff cooldown (#156).
121    async fn invalidate(&self) {
122        let mut guard = self.state.lock().await;
123        guard.cached = None;
124        guard.backoff.record_failure();
125    }
126}
127
128#[async_trait]
129impl Transport for LazyQuinnTransport {
130    type Sub = QuinnPendingStream;
131    type Pub = QuinnPublishStub;
132
133    async fn send(&self, payload: Vec<u8>, timeout_ms: Option<i32>) -> Result<Vec<u8>> {
134        let transport = self
135            .connected()
136            .await
137            .map_err(crate::transport_traits::PreDispatchTransportError::new)?;
138
139        // Make *our* deadline authoritative so we can tell a per-request timeout
140        // (the connection is probably fine — keep it) apart from a transport-fatal
141        // error (re-dial). The inner transport gets a generous ceiling that fires
142        // only if ours somehow doesn't.
143        let deadline = timeout_ms
144            .map(|ms| Duration::from_millis(ms.max(0) as u64))
145            .unwrap_or(DEFAULT_TIMEOUT);
146        let inner_ceiling_ms = deadline.as_millis().saturating_mul(2).min(i32::MAX as u128) as i32;
147
148        match tokio::time::timeout(deadline, transport.send(payload, Some(inner_ceiling_ms))).await
149        {
150            // Our deadline fired: a slow/stalled request, not necessarily a dead
151            // connection. Keep the cached session — re-dialing on every timeout
152            // would thrash a merely-busy peer. (#156 owns liveness-based re-dial.)
153            Err(_elapsed) => Err(anyhow!("quinn RPC timeout after {deadline:?}")),
154            Ok(Ok(resp)) => Ok(resp),
155            // Transport-fatal (open_bi/write/read failed): the session is likely
156            // dead — drop it so the next call re-dials, like ZmqConnection.
157            Ok(Err(e)) => {
158                self.invalidate().await;
159                Err(e)
160            }
161        }
162    }
163
164    /// QUIC is an untrusted carrier for envelope confidentiality — cleartext
165    /// forbidden unconditionally, matching the concrete
166    /// [`QuinnTransport`](super::quinn_transport) and
167    /// [`EndpointType::Quic`](super::EndpointType). A loopback address is not
168    /// evidence the bytes stay inside the trust boundary (it can terminate at a
169    /// proxy/tunnel), so it earns no exemption; local trusted RPC uses UDS/inproc.
170    fn forbids_cleartext_envelope(&self) -> bool {
171        true
172    }
173
174    async fn subscribe(&self, _topic: &[u8]) -> Result<Self::Sub> {
175        bail!("lazy quinn RPC transport does not support SUB — streaming is on the moq plane")
176    }
177
178    async fn publish(&self, _topic: &[u8]) -> Result<Self::Pub> {
179        bail!("lazy quinn RPC transport does not support PUB — streaming is on the moq plane")
180    }
181}
182
183#[cfg(test)]
184#[allow(clippy::unwrap_used, clippy::expect_used)]
185mod tests {
186    use super::*;
187    use crate::transport::quinn_transport::QuinnRpcServer;
188    use bytes::Bytes;
189    use ed25519_dalek::SigningKey;
190    use rand::RngCore;
191    use std::time::Duration;
192    use tokio_util::sync::CancellationToken;
193
194    fn fresh_signing_key() -> SigningKey {
195        let mut k = [0u8; 32];
196        rand::thread_rng().fill_bytes(&mut k);
197        SigningKey::from_bytes(&k)
198    }
199
200    fn sha256_32(bytes: &[u8]) -> [u8; 32] {
201        use sha2::{Digest, Sha256};
202        let mut h = [0u8; 32];
203        h.copy_from_slice(&Sha256::digest(bytes));
204        h
205    }
206
207    /// Hermetic loopback WebTransport echo server. Returns the bound addr, the
208    /// server cert's SHA-256 pin, and a shutdown token. (Mirrors the harness in
209    /// `quinn_transport::tests`; `build_server` there is test-private.)
210    fn spawn_echo_server() -> (SocketAddr, [u8; 32], CancellationToken) {
211        crate::transport::pq_provider::install_pq_crypto_provider().expect("install PQ provider");
212
213        let cert_key = rcgen::generate_simple_self_signed(vec!["localhost".to_owned()]).unwrap();
214        let cert_der = cert_key.cert.der().to_vec();
215        let key_der = cert_key.key_pair.serialize_der();
216        let chain = vec![rustls::pki_types::CertificateDer::from(cert_der.clone())];
217        let key = rustls::pki_types::PrivateKeyDer::Pkcs8(
218            rustls::pki_types::PrivatePkcs8KeyDer::from(key_der),
219        );
220        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
221        let server = web_transport_quinn::ServerBuilder::new()
222            .with_addr(addr)
223            .with_certificate(chain, key)
224            .unwrap();
225        let bound = server.local_addr().unwrap();
226
227        let processor = crate::transport::rpc_session::from_fn(|req: Bytes| async move { Ok(req) });
228        let rpc_server =
229            QuinnRpcServer::new(server, processor, fresh_signing_key()).with_test_trusted_carrier();
230        let shutdown = rpc_server.shutdown_token();
231        tokio::spawn(rpc_server.run());
232
233        (bound, sha256_32(&cert_der), shutdown)
234    }
235
236    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
237    async fn lazy_connects_on_first_send_and_caches() {
238        let (addr, pin, shutdown) = spawn_echo_server();
239        let t = LazyQuinnTransport::new(
240            addr,
241            "localhost",
242            QuicServerAuth::pinned(vec![pin]).unwrap(),
243        );
244
245        assert!(
246            t.state.lock().await.cached.is_none(),
247            "no connection before first send"
248        );
249
250        let resp = t.send(b"hello".to_vec(), Some(5_000)).await.unwrap();
251        assert_eq!(resp, b"hello");
252        assert!(
253            t.state.lock().await.cached.is_some(),
254            "session cached after first send"
255        );
256
257        let resp2 = t.send(b"again".to_vec(), Some(5_000)).await.unwrap();
258        assert_eq!(resp2, b"again");
259
260        shutdown.cancel();
261    }
262
263    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
264    async fn wrong_cert_pin_does_not_connect() {
265        let (addr, _pin, shutdown) = spawn_echo_server();
266        let t = LazyQuinnTransport::new(
267            addr,
268            "localhost",
269            QuicServerAuth::pinned(vec![[0u8; 32]]).unwrap(),
270        ); // wrong fingerprint
271           // The TLS handshake must *promptly reject* a wrong pin: the send must
272           // COMPLETE with an error well within the hang-guard. If the guard fires
273           // (i.e. send hung), the test fails — so a hang can't masquerade as a pass.
274        let res = tokio::time::timeout(Duration::from_secs(8), t.send(b"x".to_vec(), Some(3_000)))
275            .await
276            .expect("send must complete (with an error) — a wrong pin should reject, not hang");
277        assert!(res.is_err(), "a wrong cert pin must make send fail");
278        assert!(
279            t.state.lock().await.cached.is_none(),
280            "failed dial leaves nothing cached"
281        );
282        shutdown.cancel();
283    }
284
285    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
286    async fn dead_address_send_fails_fast_not_hang() {
287        // No server at 127.0.0.1:1 → the lazy connect must fail (or hit
288        // CONNECT_TIMEOUT) so `send()` returns an error rather than hanging
289        // forever. The guard (> CONNECT_TIMEOUT) fails the test if it hangs.
290        let t = LazyQuinnTransport::new(
291            "127.0.0.1:1".parse().unwrap(),
292            "localhost",
293            QuicServerAuth::pinned(vec![[0u8; 32]]).unwrap(),
294        );
295        let res = tokio::time::timeout(Duration::from_secs(13), t.send(b"x".to_vec(), Some(2_000)))
296            .await
297            .expect("send must complete (with an error) within the connect timeout, not hang");
298        assert!(
299            res.is_err(),
300            "a dead address must yield an error, not a connection"
301        );
302        assert!(
303            t.state.lock().await.cached.is_none(),
304            "a failed connect caches nothing"
305        );
306    }
307
308    #[tokio::test]
309    async fn subscribe_publish_bail() {
310        let t = LazyQuinnTransport::new(
311            "127.0.0.1:1".parse().unwrap(),
312            "localhost",
313            QuicServerAuth::pinned(vec![[0u8; 32]]).unwrap(),
314        );
315        assert!(t.subscribe(b"topic").await.is_err());
316        assert!(t.publish(b"topic").await.is_err());
317    }
318}