Skip to main content

eggfetch_core/
network_stream.rs

1//! Network stream types for connection metadata and upgraded connections.
2//!
3//! This module provides:
4//!
5//! - [`ConnectionMetadata`]: read-only metadata about an established
6//!   connection (addresses, TLS info, transport kind).
7//! - [`UpgradedStream`]: an owned post-HTTP IO handle for 101/CONNECT
8//!   upgrade handoff.
9//! - [`NetworkStream`]: a compatibility object exposed on responses for
10//!   metadata access and, where safe, low-level IO.
11
12use std::net::SocketAddr;
13use std::pin::Pin;
14use std::sync::Arc;
15use std::task::{Context, Poll};
16
17use bytes::Bytes;
18use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
19
20use crate::error::{Error, Result};
21
22/// The kind of transport used for a connection.
23#[derive(Debug, Clone, Copy, PartialEq, Eq)]
24pub enum TransportKind {
25    /// Plain TCP.
26    Tcp,
27    /// Unix domain socket (no IP addresses; local/peer remain `None`).
28    Unix,
29    /// TLS-wrapped TCP (rustls).
30    Tls,
31    /// TLS-wrapped Unix domain socket.
32    TlsUnix,
33    /// QUIC (HTTP/3) via Quinn.
34    ///
35    /// Reserved for H3 endpoint information where Quinn exposes it
36    /// (remote address). Per-response H3 metadata is currently
37    /// explicitly unavailable (`Response::network_stream()` is `None`
38    /// for ordinary H3 responses); this variant documents the transport
39    /// kind for future connector-derived metadata without inventing
40    /// values today.
41    Quic,
42}
43
44/// Read-only TLS session metadata captured after handshake.
45///
46/// This is an EggFetch-specific type; it does **not** masquerade as
47/// `ssl.SSLObject` or any Python SSL type.
48#[derive(Debug, Clone)]
49pub struct TlsInfo {
50    /// Negotiated ALPN protocol (e.g. `"http/1.1"`, `"h2"`).
51    pub alpn_protocol: Option<String>,
52    /// TLS version string (e.g. `"TLSv1.3"`).
53    pub tls_version: Option<String>,
54    /// Cipher suite identifier.
55    pub cipher_suite: Option<String>,
56    /// Server name used for SNI.
57    pub server_name: Option<String>,
58}
59
60/// Read-only metadata about an established connection.
61///
62/// All fields are captured at connection time and never mutated.
63/// Shared through `Arc` so multiple responses (H2) can reference the
64/// same connection metadata.
65#[derive(Debug, Clone)]
66pub struct ConnectionMetadata {
67    /// Local (client) socket address, if available.
68    pub local_addr: Option<SocketAddr>,
69    /// Remote (peer/server) socket address, if available.
70    pub peer_addr: Option<SocketAddr>,
71    /// Transport kind.
72    pub transport_kind: TransportKind,
73    /// TLS session info, if the connection is TLS.
74    pub tls_info: Option<TlsInfo>,
75}
76
77impl Default for ConnectionMetadata {
78    fn default() -> Self {
79        Self {
80            local_addr: None,
81            peer_addr: None,
82            transport_kind: TransportKind::Tcp,
83            tls_info: None,
84        }
85    }
86}
87
88/// Build [`TlsInfo`] from a rustls client connection.
89///
90/// Extracts ALPN, TLS version, and cipher suite where rustls exposes them
91/// safely. `server_name` is the SNI hostname when known (direct-connector
92/// TLS host); `None` explicitly marks unavailable rather than inventing a
93/// value. No secret-bearing material is included.
94pub(crate) fn tls_info_from_rustls(
95    conn: &rustls::ClientConnection,
96    server_name: Option<String>,
97) -> TlsInfo {
98    TlsInfo {
99        alpn_protocol: conn
100            .alpn_protocol()
101            .map(|p| String::from_utf8_lossy(p).into_owned()),
102        tls_version: conn.protocol_version().map(|v| format!("{v:?}")),
103        cipher_suite: conn.negotiated_cipher_suite().map(|c| format!("{c:?}")),
104        server_name,
105    }
106}
107
108/// An owned post-HTTP IO handle for upgraded connections (101, CONNECT).
109///
110/// After Hyper transfers ownership of the underlying IO through its
111/// upgrade mechanism, this type owns the raw stream and provides
112/// async read/write, TLS upgrade, and metadata access.
113///
114/// # Ownership rules
115///
116/// - Once created, the connection is removed from the HTTP pool and
117///   must never be reused.
118/// - `close()` is idempotent.
119/// - Cancellation during `start_tls()` closes or leaves the stream
120///   in a deterministic state.
121pub struct UpgradedStream {
122    inner: UpgradedStreamInner,
123    metadata: Arc<ConnectionMetadata>,
124    /// Leading bytes already read from the connection before the
125    /// upgrade completed (e.g. data sent by the server in the same
126    /// write as the 101/CONNECT response headers).
127    leading_data: Bytes,
128}
129
130/// Classification of the concrete IO inside an [`UpgradedStream`].
131///
132/// Used by the Python bindings to refuse `start_tls` on streams where
133/// the underlying socket cannot be recovered (Hyper's opaque adapter).
134#[derive(Debug, Clone, Copy, PartialEq, Eq)]
135pub enum UpgradedStreamVariant {
136    /// Plain TCP.
137    Tcp,
138    /// Already TLS-wrapped.
139    Tls,
140    /// Opaque adapter (Hyper's `Upgraded` wrapper).
141    Adapter,
142}
143
144/// The concrete IO inside an upgraded stream.
145enum UpgradedStreamInner {
146    /// Plain TCP stream.
147    Tcp(tokio::net::TcpStream),
148    /// TLS stream already established before upgrade.
149    Tls(Box<tokio_rustls::client::TlsStream<tokio::net::TcpStream>>),
150    /// Opaque adapter (e.g. Hyper's Upgraded wrapper).
151    Adapter(Pin<Box<dyn TokioIoBox>>),
152}
153
154/// Trait alias for `AsyncRead + AsyncWrite + Send` objects that can
155/// be stored in a trait object.
156pub(crate) trait TokioIoBox:
157    tokio::io::AsyncRead + tokio::io::AsyncWrite + Send + Unpin
158{
159}
160impl<T: tokio::io::AsyncRead + tokio::io::AsyncWrite + Send + Unpin> TokioIoBox for T {}
161
162impl AsyncRead for UpgradedStreamInner {
163    fn poll_read(
164        mut self: Pin<&mut Self>,
165        cx: &mut Context<'_>,
166        buf: &mut ReadBuf<'_>,
167    ) -> Poll<std::io::Result<()>> {
168        match &mut *self {
169            UpgradedStreamInner::Tcp(s) => Pin::new(s).poll_read(cx, buf),
170            UpgradedStreamInner::Tls(s) => Pin::new(s).poll_read(cx, buf),
171            UpgradedStreamInner::Adapter(a) => a.as_mut().poll_read(cx, buf),
172        }
173    }
174}
175
176impl AsyncWrite for UpgradedStreamInner {
177    fn poll_write(
178        mut self: Pin<&mut Self>,
179        cx: &mut Context<'_>,
180        buf: &[u8],
181    ) -> Poll<std::io::Result<usize>> {
182        match &mut *self {
183            UpgradedStreamInner::Tcp(s) => Pin::new(s).poll_write(cx, buf),
184            UpgradedStreamInner::Tls(s) => Pin::new(s).poll_write(cx, buf),
185            UpgradedStreamInner::Adapter(a) => a.as_mut().poll_write(cx, buf),
186        }
187    }
188
189    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
190        match &mut *self {
191            UpgradedStreamInner::Tcp(s) => Pin::new(s).poll_flush(cx),
192            UpgradedStreamInner::Tls(s) => Pin::new(s).poll_flush(cx),
193            UpgradedStreamInner::Adapter(a) => a.as_mut().poll_flush(cx),
194        }
195    }
196
197    fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
198        match &mut *self {
199            UpgradedStreamInner::Tcp(s) => Pin::new(s).poll_shutdown(cx),
200            UpgradedStreamInner::Tls(s) => Pin::new(s).poll_shutdown(cx),
201            UpgradedStreamInner::Adapter(a) => a.as_mut().poll_shutdown(cx),
202        }
203    }
204}
205
206impl UpgradedStream {
207    /// Wrap a tokio TCP stream into an upgraded stream.
208    ///
209    /// Leading data is bytes already read from the connection before
210    /// the upgrade handshake completed (preserved by Hyper in its
211    /// `Upgraded::read_buf`).
212    pub fn from_tcp(stream: tokio::net::TcpStream, leading_data: Bytes) -> Self {
213        let metadata = Arc::new(ConnectionMetadata {
214            local_addr: stream.local_addr().ok(),
215            peer_addr: stream.peer_addr().ok(),
216            transport_kind: TransportKind::Tcp,
217            tls_info: None,
218        });
219        Self {
220            inner: UpgradedStreamInner::Tcp(stream),
221            metadata,
222            leading_data,
223        }
224    }
225
226    /// Wrap an adapter implementing `AsyncRead + AsyncWrite` into an
227    /// upgraded stream.
228    ///
229    /// Used when the underlying IO type is opaque (e.g. Hyper's
230    /// `Upgraded` wrapper) and cannot be downcast to a concrete type.
231    /// The metadata must be provided by the caller.
232    pub(crate) fn from_adapter(
233        adapter: impl TokioIoBox + 'static,
234        leading_data: Bytes,
235        metadata: Arc<ConnectionMetadata>,
236    ) -> Self {
237        let pinned: Pin<Box<dyn TokioIoBox>> = Box::pin(adapter);
238        Self {
239            inner: UpgradedStreamInner::Adapter(pinned),
240            metadata,
241            leading_data,
242        }
243    }
244
245    /// Wrap a TLS stream into an upgraded stream.
246    pub fn from_tls(
247        stream: tokio_rustls::client::TlsStream<tokio::net::TcpStream>,
248        leading_data: Bytes,
249        tls_info: TlsInfo,
250    ) -> Self {
251        // Extract peer/local addr from the underlying TcpStream through
252        // the TLS stream's `get_ref()` which returns (&TcpStream, &ClientConnection).
253        let (inner_tcp, _) = stream.get_ref();
254        let local_addr = inner_tcp.local_addr().ok();
255        let peer_addr = inner_tcp.peer_addr().ok();
256        let metadata = Arc::new(ConnectionMetadata {
257            local_addr,
258            peer_addr,
259            transport_kind: TransportKind::Tls,
260            tls_info: Some(tls_info),
261        });
262        Self {
263            inner: UpgradedStreamInner::Tls(Box::new(stream)),
264            metadata,
265            leading_data,
266        }
267    }
268
269    /// Returns a reference to the connection metadata.
270    #[must_use]
271    pub fn metadata(&self) -> &Arc<ConnectionMetadata> {
272        &self.metadata
273    }
274
275    /// Returns the concrete variant of the inner stream.
276    ///
277    /// The Python bindings use this to refuse `start_tls` on streams
278    /// backed by Hyper's opaque adapter (where the underlying TCP socket
279    /// is not recoverable).
280    #[must_use]
281    pub fn variant(&self) -> UpgradedStreamVariant {
282        match &self.inner {
283            UpgradedStreamInner::Tcp(_) => UpgradedStreamVariant::Tcp,
284            UpgradedStreamInner::Tls(_) => UpgradedStreamVariant::Tls,
285            UpgradedStreamInner::Adapter(_) => UpgradedStreamVariant::Adapter,
286        }
287    }
288
289    /// Returns the leading data that was buffered before the upgrade.
290    ///
291    /// These are bytes already read from the connection after the
292    /// HTTP response headers but before the caller consumed the
293    /// upgrade. They must be returned before any new socket reads.
294    #[must_use]
295    pub fn leading_data(&self) -> &Bytes {
296        &self.leading_data
297    }
298
299    /// Consume leading data, returning it.
300    pub fn take_leading_data(&mut self) -> Bytes {
301        std::mem::take(&mut self.leading_data)
302    }
303
304    /// Read up to `max_bytes` from the stream.
305    ///
306    /// Returns the bytes read. Returns empty bytes on EOF.
307    ///
308    /// # Errors
309    ///
310    /// Returns `Error::Io` if the underlying read fails.
311    pub async fn read(&mut self, max_bytes: usize) -> Result<Bytes> {
312        // First drain leading data.
313        if !self.leading_data.is_empty() {
314            let available = self.leading_data.len().min(max_bytes);
315            return Ok(self.leading_data.split_to(available));
316        }
317        let mut buf = vec![0u8; max_bytes];
318        let n = tokio::io::AsyncReadExt::read(self, &mut buf)
319            .await
320            .map_err(|e| Error::Io(std::sync::Arc::new(e)))?;
321        if n == 0 {
322            Ok(Bytes::new())
323        } else {
324            Ok(Bytes::copy_from_slice(&buf[..n]))
325        }
326    }
327
328    /// Write all supplied bytes to the stream.
329    ///
330    /// # Errors
331    ///
332    /// Returns `Error::Io` if the underlying write fails.
333    pub async fn write_all(&mut self, buf: &[u8]) -> Result<()> {
334        tokio::io::AsyncWriteExt::write_all(self, buf)
335            .await
336            .map_err(|e| Error::Io(std::sync::Arc::new(e)))
337    }
338
339    /// Flush the stream.
340    ///
341    /// # Errors
342    ///
343    /// Returns `Error::Io` if the underlying flush fails.
344    pub async fn flush(&mut self) -> Result<()> {
345        tokio::io::AsyncWriteExt::flush(self)
346            .await
347            .map_err(|e| Error::Io(std::sync::Arc::new(e)))
348    }
349
350    /// Shut down the stream (idempotent).
351    ///
352    /// # Errors
353    ///
354    /// This method currently always succeeds; errors are silently
355    /// discarded to maintain idempotent close semantics.
356    pub async fn close(&mut self) -> Result<()> {
357        let _ = tokio::io::AsyncWriteExt::shutdown(self).await;
358        Ok(())
359    }
360
361    /// Upgrade this TCP stream to TLS.
362    ///
363    /// Wraps the inner TCP stream with a new TLS layer using the
364    /// provided connector and server name. On success, returns a new
365    /// `UpgradedStream` with TLS metadata. The stream is consumed whether
366    /// the handshake succeeds or fails; callers that need a fallback must
367    /// retain their own connection before calling this method.
368    ///
369    /// Only works for streams backed by a concrete `TcpStream`.
370    /// Adapter-based streams (from Hyper's Upgraded) return an error
371    /// because the concrete type cannot be recovered.
372    ///
373    /// # Errors
374    ///
375    /// Returns `Error::Tls` if the handshake fails or the stream type
376    /// does not support TLS upgrade.
377    pub async fn start_tls(
378        mut self,
379        tls_connector: &tokio_rustls::TlsConnector,
380        server_name: &str,
381    ) -> Result<Self> {
382        let tcp = match std::mem::replace(
383            &mut self.inner,
384            // Placeholder that we'll immediately replace.
385            // A zero-capacity in-memory stream avoids allocating a real
386            // socket solely to move the enum value out.
387            UpgradedStreamInner::Adapter(Box::pin(tokio::io::duplex(0).0)),
388        ) {
389            UpgradedStreamInner::Tcp(s) => s,
390            UpgradedStreamInner::Tls(_) => {
391                return Err(Error::Tls("stream is already TLS-wrapped".into()));
392            }
393            UpgradedStreamInner::Adapter(_) => {
394                return Err(Error::Tls(
395                    "cannot start TLS on an opaque adapter stream; \
396                     use a concrete TcpStream-backed UpgradedStream"
397                        .into(),
398                ));
399            }
400        };
401
402        let sn = crate::transport::direct_connector::tls_server_name(server_name)
403            .map_err(|e| Error::Tls(format!("invalid server name '{server_name}': {e}")))?;
404
405        let tls_stream = tls_connector
406            .connect(sn, tcp)
407            .await
408            .map_err(|e| Error::Tls(format!("TLS handshake failed: {e}")))?;
409
410        // Extract TLS info from the negotiated parameters.
411        let (inner_tcp, connection_info) = tls_stream.get_ref();
412        let tls_info = tls_info_from_rustls(connection_info, Some(server_name.to_owned()));
413
414        let local_addr = inner_tcp.local_addr().ok();
415        let peer_addr = inner_tcp.peer_addr().ok();
416
417        let metadata = Arc::new(ConnectionMetadata {
418            local_addr,
419            peer_addr,
420            transport_kind: TransportKind::Tls,
421            tls_info: Some(tls_info),
422        });
423
424        Ok(UpgradedStream {
425            inner: UpgradedStreamInner::Tls(Box::new(tls_stream)),
426            metadata,
427            // Carry any leading data buffered before the TLS handshake so
428            // pipelined bytes from the 101 upgrade are not dropped.
429            leading_data: std::mem::take(&mut self.leading_data),
430        })
431    }
432}
433
434impl AsyncRead for UpgradedStream {
435    fn poll_read(
436        mut self: Pin<&mut Self>,
437        cx: &mut Context<'_>,
438        buf: &mut ReadBuf<'_>,
439    ) -> Poll<std::io::Result<()>> {
440        // Drain leading data first.
441        if !self.leading_data.is_empty() {
442            let available = self.leading_data.len().min(buf.remaining());
443            let chunk = self.leading_data.split_to(available);
444            buf.put_slice(&chunk);
445            return Poll::Ready(Ok(()));
446        }
447        Pin::new(&mut self.inner).poll_read(cx, buf)
448    }
449}
450
451impl AsyncWrite for UpgradedStream {
452    fn poll_write(
453        mut self: Pin<&mut Self>,
454        cx: &mut Context<'_>,
455        buf: &[u8],
456    ) -> Poll<std::io::Result<usize>> {
457        Pin::new(&mut self.inner).poll_write(cx, buf)
458    }
459
460    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
461        Pin::new(&mut self.inner).poll_flush(cx)
462    }
463
464    fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
465        Pin::new(&mut self.inner).poll_shutdown(cx)
466    }
467}
468
469/// A network stream handle exposed on responses for metadata access.
470///
471/// For upgraded connections (101/CONNECT), this provides full
472/// read/write/close/TLS access. For ordinary pooled connections,
473/// this provides read-only metadata — raw IO operations are not
474/// exposed while Hyper still owns the connection.
475///
476/// # Ordinal response limitation
477///
478/// Hyper's legacy client pool retains ownership of socket connections
479/// for ordinary HTTP/1.1 and HTTP/2 responses. The pool does not expose
480/// per-response socket metadata, and raw IO operations would corrupt
481/// pool state. Therefore, `NetworkStream::Metadata` is currently only
482/// constructed for responses where socket metadata can be safely
483/// captured without interfering with the pool. For ordinary responses,
484/// `network_stream` on `Response` is `None`.
485///
486/// This is a documented bounded difference from httpcore, which owns
487/// its connections directly and can expose metadata on every response.
488pub enum NetworkStream {
489    /// An upgraded stream with full IO access.
490    Upgraded(UpgradedStream),
491    /// Read-only metadata for an ordinary pooled connection.
492    ///
493    /// Currently reserved for future use when socket metadata can be
494    /// safely captured from Hyper's connection pool. For ordinary
495    /// responses, `Response::network_stream()` returns `None`.
496    Metadata(Arc<ConnectionMetadata>),
497}
498
499impl NetworkStream {
500    /// Returns the connection metadata.
501    #[must_use]
502    pub fn metadata(&self) -> &Arc<ConnectionMetadata> {
503        match self {
504            NetworkStream::Upgraded(s) => s.metadata(),
505            NetworkStream::Metadata(m) => m,
506        }
507    }
508
509    /// Returns `true` if this is an upgraded stream with IO access.
510    #[must_use]
511    pub fn is_upgraded(&self) -> bool {
512        matches!(self, NetworkStream::Upgraded(_))
513    }
514
515    /// If this is an upgraded stream, returns a reference to it.
516    #[must_use]
517    pub fn as_upgraded(&self) -> Option<&UpgradedStream> {
518        match self {
519            NetworkStream::Upgraded(s) => Some(s),
520            NetworkStream::Metadata(_) => None,
521        }
522    }
523
524    /// If this is an upgraded stream, returns a mutable reference.
525    pub fn as_upgraded_mut(&mut self) -> Option<&mut UpgradedStream> {
526        match self {
527            NetworkStream::Upgraded(s) => Some(s),
528            NetworkStream::Metadata(_) => None,
529        }
530    }
531
532    /// If this is an upgraded stream, consume and return it.
533    pub fn into_upgraded(self) -> Option<UpgradedStream> {
534        match self {
535            NetworkStream::Upgraded(s) => Some(s),
536            NetworkStream::Metadata(_) => None,
537        }
538    }
539}
540
541/// Read-only metadata accessible through `get_extra_info()`.
542#[derive(Debug, Clone)]
543pub struct ExtraInfo {
544    /// Local address (`client_addr`).
545    pub client_addr: Option<SocketAddr>,
546    /// Remote address (`server_addr`).
547    pub server_addr: Option<SocketAddr>,
548    /// TLS info, if available.
549    pub tls_info: Option<TlsInfo>,
550}
551
552impl ExtraInfo {
553    /// Create from connection metadata.
554    #[must_use]
555    pub fn from_metadata(meta: &ConnectionMetadata) -> Self {
556        Self {
557            client_addr: meta.local_addr,
558            server_addr: meta.peer_addr,
559            tls_info: meta.tls_info.clone(),
560        }
561    }
562}
563
564#[cfg(test)]
565mod tests {
566    use super::*;
567
568    #[test]
569    fn connection_metadata_default() {
570        let meta = ConnectionMetadata::default();
571        assert!(meta.local_addr.is_none());
572        assert!(meta.peer_addr.is_none());
573        assert_eq!(meta.transport_kind, TransportKind::Tcp);
574        assert!(meta.tls_info.is_none());
575    }
576
577    #[test]
578    fn network_stream_metadata_only() {
579        let meta = Arc::new(ConnectionMetadata {
580            local_addr: Some("127.0.0.1:12345".parse().unwrap()),
581            peer_addr: Some("93.184.216.34:443".parse().unwrap()),
582            transport_kind: TransportKind::Tls,
583            tls_info: Some(TlsInfo {
584                alpn_protocol: Some("h2".into()),
585                tls_version: Some("TLSv1.3".into()),
586                cipher_suite: Some("TLS_AES_256_GCM_SHA384".into()),
587                server_name: Some("example.com".into()),
588            }),
589        });
590        let ns = NetworkStream::Metadata(meta.clone());
591        assert!(!ns.is_upgraded());
592        assert!(ns.as_upgraded().is_none());
593        let info = ns.metadata();
594        assert_eq!(info.local_addr.unwrap().port(), 12345);
595        assert_eq!(info.peer_addr.unwrap().port(), 443);
596    }
597
598    #[test]
599    fn extra_info_from_metadata() {
600        let meta = ConnectionMetadata {
601            local_addr: Some("127.0.0.1:1000".parse().unwrap()),
602            peer_addr: Some("10.0.0.1:443".parse().unwrap()),
603            transport_kind: TransportKind::Tcp,
604            tls_info: None,
605        };
606        let info = ExtraInfo::from_metadata(&meta);
607        assert_eq!(info.client_addr.unwrap().port(), 1000);
608        assert_eq!(info.server_addr.unwrap().port(), 443);
609        assert!(info.tls_info.is_none());
610    }
611}