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