Skip to main content

qualia_core_db/p2p/connectivity/
h2_capsule.rs

1//! Loopback TLS HTTP/2 Extended CONNECT carrying RFC 9297 DATAGRAM capsules.
2//!
3//! Two peers complete RFC 8441 Extended CONNECT with `:protocol` = `capsule`.
4//! CSCP (and QSession) bytes then travel as DATAGRAM capsule **values** on
5//! HTTP/2 DATA. This is **not UDP** and **not MASQUE Internet**. Nested
6//! recovery over a reliable stream is degraded (head-of-line blocking).
7
8#![cfg(not(target_arch = "wasm32"))]
9
10use std::sync::Arc;
11use std::time::Duration;
12
13use bytes::Bytes;
14use h2::ext::Protocol;
15use http::{Method, Request, Response, StatusCode, Version};
16use rustls::pki_types::ServerName;
17use tokio::net::{TcpListener, TcpStream};
18use tokio_rustls::{TlsAcceptor, TlsConnector};
19
20use crate::net::peer::fabric::capsule::{
21    encode_datagram_capsule, CapsuleError, CAPSULE_DATAGRAM, MAX_CAPSULE_VALUE,
22};
23use crate::p2p::connectivity::wss_tls::{client_config, mint_server, server_config, LocalCa};
24
25/// RFC 9297 Capsule Protocol token for `:protocol`.
26pub const CAPSULE_PROTOCOL: &str = "capsule";
27
28/// QSession fragments are MIN_QDNF_MTU (1280). CSCP control still uses the
29/// fabric encoder (`MAX_CAPSULE_VALUE` = 1024). Not a MASQUE/HTTP/3 claim.
30const STREAM_VALUE_MAX: usize = 2048;
31const VARINT_1: u64 = 1 << 6;
32const VARINT_2: u64 = 1 << 14;
33const VARINT_4: u64 = 1 << 30;
34const MAX_VARINT: u64 = (1 << 62) - 1;
35
36enum Outgoing {
37    Datagram(Vec<u8>),
38    Raw(Vec<u8>),
39}
40
41struct Drive {
42    rt: Option<tokio::runtime::Runtime>,
43    // Keep the local port reserved until both endpoints and their I/O are gone.
44    _listener: TcpListener,
45}
46
47impl Drop for Drive {
48    fn drop(&mut self) {
49        if let Some(rt) = self.rt.take() {
50            // Runtime drop joins workers and destroys their socket-owning tasks.
51            // A synchronous endpoint may itself be dropped from an async caller;
52            // move that blocking teardown off the caller's runtime in that case.
53            if tokio::runtime::Handle::try_current().is_ok() {
54                std::thread::spawn(move || drop(rt))
55                    .join()
56                    .expect("capsule runtime shutdown worker panicked");
57            } else {
58                drop(rt);
59            }
60        }
61    }
62}
63
64struct Half {
65    tx: tokio::sync::mpsc::Sender<Outgoing>,
66    rx: std::sync::mpsc::Receiver<Result<Vec<u8>, String>>,
67}
68
69/// One end of a capsule-protocol HTTP/2 CONNECT stream (loopback TLS).
70pub struct CapsuleEndpoint {
71    tx: tokio::sync::mpsc::Sender<Outgoing>,
72    rx: std::sync::mpsc::Receiver<Result<Vec<u8>, String>>,
73    _drive: Arc<Drive>,
74}
75
76impl CapsuleEndpoint {
77    /// Send `payload` as a DATAGRAM capsule value (`encode_datagram_capsule` when ≤ 1024).
78    pub fn send_payload(&self, payload: &[u8]) -> Result<(), String> {
79        self.tx
80            .blocking_send(Outgoing::Datagram(payload.to_vec()))
81            .map_err(|_| "h2 capsule send closed".to_string())
82    }
83
84    /// Send an already-framed capsule (used to inject unknown-critical types).
85    pub fn send_raw_capsule(&self, framed: &[u8]) -> Result<(), String> {
86        self.tx
87            .blocking_send(Outgoing::Raw(framed.to_vec()))
88            .map_err(|_| "h2 capsule send closed".to_string())
89    }
90
91    /// Receive the next DATAGRAM capsule value. Unknown critical / truncated fail closed.
92    pub fn recv_payload(&self) -> Result<Vec<u8>, String> {
93        match self.rx.recv_timeout(Duration::from_secs(30)) {
94            Ok(Ok(v)) => Ok(v),
95            Ok(Err(e)) => Err(e),
96            Err(_) => Err("h2 capsule recv timeout or closed".into()),
97        }
98    }
99}
100
101fn h2_tls_cfgs(
102    ca: &LocalCa,
103) -> Result<(Arc<rustls::ServerConfig>, Arc<rustls::ClientConfig>), String> {
104    let (cert, key) = mint_server(ca)?;
105    let mut server = (*server_config(&cert, &key)?).clone();
106    server.alpn_protocols = vec![b"h2".to_vec()];
107    let mut client = (*client_config(ca)?).clone();
108    client.alpn_protocols = vec![b"h2".to_vec()];
109    Ok((Arc::new(server), Arc::new(client)))
110}
111
112/// Two loopback TLS HTTP/2 peers with `:protocol` = `capsule`.
113pub fn loopback_tls_h2_capsule(ca: &LocalCa) -> Result<(CapsuleEndpoint, CapsuleEndpoint), String> {
114    loopback_tls_h2_connect(ca, CAPSULE_PROTOCOL)
115}
116
117/// Same CONNECT path; `protocol` is the client `:protocol` pseudo-header.
118pub fn loopback_tls_h2_connect(
119    ca: &LocalCa,
120    protocol: &'static str,
121) -> Result<(CapsuleEndpoint, CapsuleEndpoint), String> {
122    let rt = tokio::runtime::Builder::new_multi_thread()
123        .worker_threads(2)
124        .enable_all()
125        .build()
126        .map_err(|e| format!("rt: {e}"))?;
127    let (halves, listener) = rt.block_on(async {
128        tokio::time::timeout(Duration::from_secs(10), establish(ca, protocol))
129            .await
130            .map_err(|_| "TLS HTTP/2 CONNECT setup deadline exceeded".to_string())?
131    })?;
132    let drive = Arc::new(Drive {
133        rt: Some(rt),
134        _listener: listener,
135    });
136    Ok((
137        CapsuleEndpoint {
138            tx: halves.0.tx,
139            rx: halves.0.rx,
140            _drive: drive.clone(),
141        },
142        CapsuleEndpoint {
143            tx: halves.1.tx,
144            rx: halves.1.rx,
145            _drive: drive,
146        },
147    ))
148}
149
150async fn establish(
151    ca: &LocalCa,
152    protocol: &'static str,
153) -> Result<((Half, Half), TcpListener), String> {
154    let (srv_cfg, cli_cfg) = h2_tls_cfgs(ca)?;
155    let listener = TcpListener::bind("127.0.0.1:0")
156        .await
157        .map_err(|e| format!("tcp listener bind: {e}"))?;
158    let addr = listener
159        .local_addr()
160        .map_err(|e| format!("tcp listener address: {e}"))?;
161
162    let listener_ref = &listener;
163    let server_fut = async move {
164        let (tcp, _) = listener_ref
165            .accept()
166            .await
167            .map_err(|e| format!("tcp accept: {e}"))?;
168        let tls = TlsAcceptor::from(srv_cfg)
169            .accept(tcp)
170            .await
171            .map_err(|e| format!("tls-s: {e}"))?;
172        let mut h2 = h2::server::Builder::new()
173            .enable_connect_protocol()
174            .handshake(tls)
175            .await
176            .map_err(|e| format!("h2-s: {e}"))?;
177        let (req, mut respond) = h2
178            .accept()
179            .await
180            .ok_or_else(|| "h2 server closed before CONNECT".to_string())?
181            .map_err(|e| format!("accept: {e}"))?;
182        tokio::spawn(async move {
183            let _ = std::future::poll_fn(|cx| h2.poll_closed(cx)).await;
184        });
185        let proto = req.extensions().get::<Protocol>().map(|p| p.as_str());
186        if req.method() != Method::CONNECT || proto != Some(CAPSULE_PROTOCOL) {
187            let _ = respond.send_response(
188                Response::builder()
189                    .status(StatusCode::BAD_REQUEST)
190                    .body(())
191                    .unwrap(),
192                true,
193            );
194            return Err(format!(
195                "CONNECT requires method CONNECT and :protocol=capsule (got {:?} {:?})",
196                req.method(),
197                proto
198            ));
199        }
200        let send = respond
201            .send_response(
202                Response::builder().status(StatusCode::OK).body(()).unwrap(),
203                false,
204            )
205            .map_err(|e| format!("respond: {e}"))?;
206        Ok(pump(send, req.into_body()))
207    };
208
209    let client_fut = async move {
210        let tcp = TcpStream::connect(addr)
211            .await
212            .map_err(|e| format!("tcp connect to {addr}: {e}"))?;
213        let name = ServerName::try_from("localhost").map_err(|e| e.to_string())?;
214        let tls = TlsConnector::from(cli_cfg)
215            .connect(name, tcp)
216            .await
217            .map_err(|e| format!("tls-c: {e}"))?;
218        let (sender, conn) = h2::client::Builder::new()
219            .handshake::<_, Bytes>(tls)
220            .await
221            .map_err(|e| format!("h2-c: {e}"))?;
222        tokio::spawn(async move {
223            let _ = conn.await;
224        });
225        let mut sender = sender.ready().await.map_err(|e| format!("ready: {e}"))?;
226        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
227        while !sender.is_extended_connect_protocol_enabled() {
228            if tokio::time::Instant::now() > deadline {
229                return Err("client did not receive SETTINGS_ENABLE_CONNECT_PROTOCOL".into());
230            }
231            tokio::time::sleep(Duration::from_millis(5)).await;
232            sender = sender.ready().await.map_err(|e| format!("ready: {e}"))?;
233        }
234        let req = Request::builder()
235            .method(Method::CONNECT)
236            .uri("https://localhost/")
237            .version(Version::HTTP_2)
238            .extension(Protocol::from_static(protocol))
239            .body(())
240            .map_err(|e| format!("req: {e}"))?;
241        let (resp_fut, send) = sender
242            .send_request(req, false)
243            .map_err(|e| format!("connect: {e}"))?;
244        let resp = resp_fut.await.map_err(|e| format!("resp: {e}"))?;
245        if !resp.status().is_success() {
246            return Err(format!("CONNECT rejected: {}", resp.status()));
247        }
248        Ok(pump(send, resp.into_body()))
249    };
250
251    let halves = tokio::try_join!(client_fut, server_fut)?;
252    Ok((halves, listener))
253}
254
255fn pump(mut send: h2::SendStream<Bytes>, mut recv: h2::RecvStream) -> Half {
256    let (tx, mut rx_out) = tokio::sync::mpsc::channel::<Outgoing>(32);
257    let (tx_in, rx_in) = std::sync::mpsc::sync_channel(32);
258    tokio::spawn(async move {
259        let mut acc = Vec::new();
260        loop {
261            tokio::select! {
262                out = rx_out.recv() => {
263                    match out {
264                        None => break,
265                        Some(Outgoing::Datagram(p)) => {
266                            let mut buf = [0u8; 2064];
267                            match encode_stream_datagram(&p, &mut buf) {
268                                Ok(n) => {
269                                    if send.send_data(Bytes::copy_from_slice(&buf[..n]), false).is_err() {
270                                        let _ = tx_in.send(Err("send_data".into()));
271                                        break;
272                                    }
273                                }
274                                Err(e) => {
275                                    let _ = tx_in.send(Err(e));
276                                    break;
277                                }
278                            }
279                        }
280                        Some(Outgoing::Raw(p)) => {
281                            if send.send_data(Bytes::from(p), false).is_err() {
282                                let _ = tx_in.send(Err("send_data".into()));
283                                break;
284                            }
285                        }
286                    }
287                }
288                chunk = recv.data() => {
289                    match chunk {
290                        None => {
291                            if !acc.is_empty() {
292                                let _ = tx_in.send(Err("truncated capsule".into()));
293                            }
294                            break;
295                        }
296                        Some(Err(e)) => {
297                            let _ = tx_in.send(Err(format!("h2 data: {e}")));
298                            break;
299                        }
300                        Some(Ok(bytes)) => {
301                            let n = bytes.len();
302                            acc.extend_from_slice(&bytes);
303                            let _ = recv.flow_control().release_capacity(n);
304                            match drain_capsules(&mut acc) {
305                                Ok(vals) => {
306                                    for v in vals {
307                                        if tx_in.send(Ok(v)).is_err() {
308                                            return;
309                                        }
310                                    }
311                                }
312                                Err(e) => {
313                                    let _ = tx_in.send(Err(e));
314                                    break;
315                                }
316                            }
317                        }
318                    }
319                }
320            }
321        }
322    });
323    Half { tx, rx: rx_in }
324}
325
326fn encode_stream_datagram(payload: &[u8], out: &mut [u8]) -> Result<usize, String> {
327    if payload.len() <= MAX_CAPSULE_VALUE {
328        encode_datagram_capsule(payload, out).map_err(|e| format!("{e:?}"))
329    } else if payload.len() <= STREAM_VALUE_MAX {
330        encode_local(CAPSULE_DATAGRAM, payload, out)
331    } else {
332        Err("stream capsule capacity".into())
333    }
334}
335
336fn encode_local(ty: u64, payload: &[u8], out: &mut [u8]) -> Result<usize, String> {
337    let n_ty = encode_varint(ty, out).map_err(|e| format!("{e:?}"))?;
338    let n_len =
339        encode_varint(payload.len() as u64, &mut out[n_ty..]).map_err(|e| format!("{e:?}"))?;
340    let start = n_ty + n_len;
341    let end = start + payload.len();
342    if out.len() < end {
343        return Err("capacity".into());
344    }
345    out[start..end].copy_from_slice(payload);
346    Ok(end)
347}
348
349fn drain_capsules(acc: &mut Vec<u8>) -> Result<Vec<Vec<u8>>, String> {
350    let mut out = Vec::new();
351    loop {
352        match take_capsule(acc)? {
353            None => break,
354            Some(None) => {}
355            Some(Some(v)) => out.push(v),
356        }
357    }
358    Ok(out)
359}
360
361/// `None` = need more bytes. `Some(None)` = skipped non-critical. `Some(Some(v))` = DATAGRAM.
362fn take_capsule(acc: &mut Vec<u8>) -> Result<Option<Option<Vec<u8>>>, String> {
363    if acc.is_empty() {
364        return Ok(None);
365    }
366    let (ty, tlen) = match decode_varint(acc) {
367        Ok(v) => v,
368        Err(CapsuleError::Truncated) => return Ok(None),
369        Err(e) => return Err(format!("{e:?}")),
370    };
371    let rest = match acc.get(tlen..) {
372        Some(r) => r,
373        None => return Ok(None),
374    };
375    let (vlen, llen) = match decode_varint(rest) {
376        Ok(v) => v,
377        Err(CapsuleError::Truncated) => return Ok(None),
378        Err(e) => return Err(format!("{e:?}")),
379    };
380    if vlen > STREAM_VALUE_MAX as u64 {
381        return Err("capsule capacity".into());
382    }
383    let header = tlen + llen;
384    let end = header.saturating_add(vlen as usize);
385    if acc.len() < end {
386        return Ok(None);
387    }
388    let value = acc[header..end].to_vec();
389    acc.drain(..end);
390    if ty == CAPSULE_DATAGRAM {
391        Ok(Some(Some(value)))
392    } else if ty <= 0x3f {
393        Ok(Some(None))
394    } else {
395        Err("unknown critical capsule".into())
396    }
397}
398
399fn varint_len(value: u64) -> usize {
400    if value < VARINT_1 {
401        1
402    } else if value < VARINT_2 {
403        2
404    } else if value < VARINT_4 {
405        4
406    } else {
407        8
408    }
409}
410
411fn encode_varint(value: u64, out: &mut [u8]) -> Result<usize, CapsuleError> {
412    if value > MAX_VARINT {
413        return Err(CapsuleError::Malformed);
414    }
415    let len = varint_len(value);
416    if out.len() < len {
417        return Err(CapsuleError::Capacity);
418    }
419    match len {
420        1 => out[0] = value as u8,
421        2 => {
422            let n = (value as u16) | 0x4000;
423            out[..2].copy_from_slice(&n.to_be_bytes());
424        }
425        4 => {
426            let n = (value as u32) | 0x8000_0000;
427            out[..4].copy_from_slice(&n.to_be_bytes());
428        }
429        _ => {
430            let n = value | 0xC000_0000_0000_0000;
431            out[..8].copy_from_slice(&n.to_be_bytes());
432        }
433    }
434    Ok(len)
435}
436
437fn decode_varint(src: &[u8]) -> Result<(u64, usize), CapsuleError> {
438    let first = *src.first().ok_or(CapsuleError::Truncated)?;
439    let len = 1usize << (first >> 6);
440    if src.len() < len {
441        return Err(CapsuleError::Truncated);
442    }
443    let value = match len {
444        1 => first as u64,
445        2 => u16::from_be_bytes([src[0], src[1]]) as u64 & 0x3fff,
446        4 => u32::from_be_bytes([src[0], src[1], src[2], src[3]]) as u64 & 0x3fff_ffff,
447        8 => {
448            u64::from_be_bytes([
449                src[0], src[1], src[2], src[3], src[4], src[5], src[6], src[7],
450            ]) & MAX_VARINT
451        }
452        _ => return Err(CapsuleError::Malformed),
453    };
454    if varint_len(value) != len {
455        return Err(CapsuleError::Malformed);
456    }
457    Ok((value, len))
458}
459
460#[cfg(test)]
461#[path = "h2_capsule_tests.rs"]
462mod tests;