fips_core/transport/
mod.rs

1//! Transport Layer Abstractions
2//!
3//! Traits and types for FIPS transport drivers. Transports provide the
4//! underlying communication mechanisms (UDP, Ethernet, Tor, etc.) over
5//! which FIPS links are established.
6
7pub mod tcp;
8pub mod tor;
9pub mod udp;
10#[cfg(feature = "webrtc-transport")]
11pub mod webrtc;
12
13#[cfg(feature = "sim-transport")]
14pub mod sim;
15
16#[cfg(any(target_os = "linux", target_os = "macos"))]
17pub mod ethernet;
18
19#[cfg(target_os = "linux")]
20pub mod ble;
21
22mod handle;
23mod packet_channel;
24
25#[cfg(test)]
26mod tests;
27
28pub use handle::TransportHandle;
29pub(crate) use packet_channel::received_timestamp_ms;
30pub use packet_channel::{PacketRx, PacketTx, ReceivedPacket, packet_channel};
31
32use secp256k1::XOnlyPublicKey;
33use std::fmt;
34use std::net::SocketAddr;
35use std::sync::Arc;
36use std::time::Duration;
37use thiserror::Error;
38
39// ============================================================================
40// Transport Identifiers
41// ============================================================================
42
43/// Unique identifier for a transport instance.
44#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
45pub struct TransportId(u32);
46
47impl TransportId {
48    /// Create a new transport ID.
49    pub fn new(id: u32) -> Self {
50        Self(id)
51    }
52
53    /// Get the raw ID value.
54    pub fn as_u32(&self) -> u32 {
55        self.0
56    }
57}
58
59impl fmt::Display for TransportId {
60    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
61        write!(f, "transport:{}", self.0)
62    }
63}
64
65/// Unique identifier for a link instance.
66#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
67pub struct LinkId(u64);
68
69impl LinkId {
70    /// Create a new link ID.
71    pub fn new(id: u64) -> Self {
72        Self(id)
73    }
74
75    /// Get the raw ID value.
76    pub fn as_u64(&self) -> u64 {
77        self.0
78    }
79}
80
81impl fmt::Display for LinkId {
82    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
83        write!(f, "link:{}", self.0)
84    }
85}
86
87// ============================================================================
88// Errors
89// ============================================================================
90
91/// Errors related to transport operations.
92#[derive(Debug, Error)]
93pub enum TransportError {
94    #[error("transport not started")]
95    NotStarted,
96
97    #[error("transport already started")]
98    AlreadyStarted,
99
100    #[error("transport failed to start: {0}")]
101    StartFailed(String),
102
103    #[error("transport shutdown failed: {0}")]
104    ShutdownFailed(String),
105
106    #[error("link failed: {0}")]
107    LinkFailed(String),
108
109    #[error("send failed: {0}")]
110    SendFailed(String),
111
112    #[error("receive failed: {0}")]
113    RecvFailed(String),
114
115    #[error("invalid transport address: {0}")]
116    InvalidAddress(String),
117
118    #[error("mtu exceeded: packet {packet_size} > mtu {mtu}")]
119    MtuExceeded { packet_size: usize, mtu: u16 },
120
121    #[error("transport timeout")]
122    Timeout,
123
124    #[error("connection refused")]
125    ConnectionRefused,
126
127    #[error("transport not supported: {0}")]
128    NotSupported(String),
129
130    #[error("io error: {0}")]
131    Io(#[from] std::io::Error),
132}
133
134impl TransportError {
135    /// True when the local OS says the outbound underlay path is temporarily
136    /// unsendable, rather than the peer or protocol being bad.
137    pub fn is_local_route_unavailable(&self) -> bool {
138        match self {
139            TransportError::Io(error) => is_local_route_error_kind(error.kind()),
140            TransportError::SendFailed(message) => is_local_route_error_text(message),
141            _ => false,
142        }
143    }
144}
145
146fn is_local_route_error_kind(kind: std::io::ErrorKind) -> bool {
147    matches!(
148        kind,
149        std::io::ErrorKind::NetworkUnreachable
150            | std::io::ErrorKind::HostUnreachable
151            | std::io::ErrorKind::AddrNotAvailable
152    )
153}
154
155fn is_local_route_error_text(message: &str) -> bool {
156    let lower = message.to_ascii_lowercase();
157    lower.contains("network is unreachable")
158        || lower.contains("no route to host")
159        || lower.contains("host is unreachable")
160        || lower.contains("can't assign requested address")
161        || lower.contains("cannot assign requested address")
162        || lower.contains("os error 51")
163        || lower.contains("os error 65")
164        || lower.contains("os error 49")
165}
166
167// ============================================================================
168// Transport Type Metadata
169// ============================================================================
170
171/// Static metadata about a transport type.
172#[derive(Clone, Debug, PartialEq, Eq)]
173pub struct TransportType {
174    /// Human-readable name (e.g., "udp", "ethernet", "tor").
175    pub name: &'static str,
176    /// Whether this transport requires connection establishment.
177    pub connection_oriented: bool,
178    /// Whether the transport guarantees delivery.
179    pub reliable: bool,
180}
181
182impl TransportType {
183    /// UDP/IP transport.
184    pub const UDP: TransportType = TransportType {
185        name: "udp",
186        connection_oriented: false,
187        reliable: false,
188    };
189
190    /// TCP/IP transport.
191    pub const TCP: TransportType = TransportType {
192        name: "tcp",
193        connection_oriented: true,
194        reliable: true,
195    };
196
197    /// Raw Ethernet transport.
198    pub const ETHERNET: TransportType = TransportType {
199        name: "ethernet",
200        connection_oriented: false,
201        reliable: false,
202    };
203
204    /// WiFi (same characteristics as Ethernet).
205    pub const WIFI: TransportType = TransportType {
206        name: "wifi",
207        connection_oriented: false,
208        reliable: false,
209    };
210
211    /// Tor onion transport.
212    pub const TOR: TransportType = TransportType {
213        name: "tor",
214        connection_oriented: true,
215        reliable: true,
216    };
217
218    /// Serial/UART transport.
219    pub const SERIAL: TransportType = TransportType {
220        name: "serial",
221        connection_oriented: false,
222        reliable: true, // typically uses framing with checksums
223    };
224
225    /// BLE L2CAP CoC transport.
226    pub const BLE: TransportType = TransportType {
227        name: "ble",
228        connection_oriented: true,
229        reliable: true, // L2CAP SeqPacket guarantees delivery
230    };
231
232    /// WebRTC DataChannel transport.
233    pub const WEBRTC: TransportType = TransportType {
234        name: "webrtc",
235        connection_oriented: true,
236        reliable: false,
237    };
238
239    /// In-memory simulated packet transport.
240    #[cfg(feature = "sim-transport")]
241    pub const SIM: TransportType = TransportType {
242        name: "sim",
243        connection_oriented: false,
244        reliable: false,
245    };
246
247    /// Check if the transport is connectionless.
248    pub fn is_connectionless(&self) -> bool {
249        !self.connection_oriented
250    }
251}
252
253impl fmt::Display for TransportType {
254    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
255        write!(f, "{}", self.name)
256    }
257}
258
259// ============================================================================
260// Transport State
261// ============================================================================
262
263/// Transport lifecycle state.
264#[derive(Clone, Copy, Debug, PartialEq, Eq)]
265pub enum TransportState {
266    /// Configured but not started.
267    Configured,
268    /// Initialization in progress.
269    Starting,
270    /// Ready for links.
271    Up,
272    /// Was up, now unavailable.
273    Down,
274    /// Failed to start.
275    Failed,
276}
277
278impl TransportState {
279    /// Check if the transport is operational.
280    pub fn is_operational(&self) -> bool {
281        matches!(self, TransportState::Up)
282    }
283
284    /// Check if the transport can be started.
285    pub fn can_start(&self) -> bool {
286        matches!(
287            self,
288            TransportState::Configured | TransportState::Down | TransportState::Failed
289        )
290    }
291
292    /// Check if the transport is in a terminal state.
293    pub fn is_terminal(&self) -> bool {
294        matches!(self, TransportState::Failed)
295    }
296}
297
298impl fmt::Display for TransportState {
299    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
300        let s = match self {
301            TransportState::Configured => "configured",
302            TransportState::Starting => "starting",
303            TransportState::Up => "up",
304            TransportState::Down => "down",
305            TransportState::Failed => "failed",
306        };
307        write!(f, "{}", s)
308    }
309}
310
311// ============================================================================
312// Link State
313// ============================================================================
314
315/// Link lifecycle state.
316#[derive(Clone, Copy, Debug, PartialEq, Eq)]
317pub enum LinkState {
318    /// Connection in progress (connection-oriented only).
319    Connecting,
320    /// Ready for traffic.
321    Connected,
322    /// Was connected, now gone.
323    Disconnected,
324    /// Connection attempt failed.
325    Failed,
326}
327
328impl LinkState {
329    /// Check if the link is operational.
330    pub fn is_operational(&self) -> bool {
331        matches!(self, LinkState::Connected)
332    }
333
334    /// Check if the link is in a terminal state.
335    pub fn is_terminal(&self) -> bool {
336        matches!(self, LinkState::Disconnected | LinkState::Failed)
337    }
338}
339
340impl fmt::Display for LinkState {
341    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
342        let s = match self {
343            LinkState::Connecting => "connecting",
344            LinkState::Connected => "connected",
345            LinkState::Disconnected => "disconnected",
346            LinkState::Failed => "failed",
347        };
348        write!(f, "{}", s)
349    }
350}
351
352/// Direction of link establishment.
353#[derive(Clone, Copy, Debug, PartialEq, Eq)]
354pub enum LinkDirection {
355    /// We initiated the connection.
356    Outbound,
357    /// They initiated the connection.
358    Inbound,
359}
360
361impl fmt::Display for LinkDirection {
362    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
363        let s = match self {
364            LinkDirection::Outbound => "outbound",
365            LinkDirection::Inbound => "inbound",
366        };
367        write!(f, "{}", s)
368    }
369}
370
371// ============================================================================
372// Transport Address
373// ============================================================================
374
375/// Opaque transport-specific address.
376///
377/// Each transport type interprets this differently:
378/// - UDP/TCP: "host:port" (IP address or DNS hostname)
379/// - Ethernet: MAC address (6 bytes)
380///
381/// The bytes are immutable and shared so hot-path clones can carry path
382/// evidence through receive/session bookkeeping without copying address bytes.
383#[derive(Clone, PartialEq, Eq, Hash)]
384pub struct TransportAddr(Arc<[u8]>);
385
386impl TransportAddr {
387    /// Create a transport address from raw bytes.
388    pub fn new(bytes: Vec<u8>) -> Self {
389        Self(bytes.into())
390    }
391
392    /// Create a transport address from a byte slice.
393    pub fn from_bytes(bytes: &[u8]) -> Self {
394        Self(Arc::from(bytes))
395    }
396
397    /// Create a transport address from a string.
398    pub fn from_string(s: &str) -> Self {
399        Self(Arc::from(s.as_bytes()))
400    }
401
402    /// Create a transport address from a `SocketAddr` without going
403    /// through `to_string()`.
404    ///
405    /// The standard path is `from_string(&addr.to_string())`, which
406    /// allocates a `String` for the formatted address and then copies
407    /// its bytes into a fresh `Vec<u8>` — two heap allocations per
408    /// inbound packet on the UDP receive hot path. At line rate that's
409    /// a few percent of one core in malloc/free. This variant writes
410    /// the `SocketAddr::Display` representation directly into a
411    /// `Vec<u8>` via `std::io::Write`, halving the alloc count and
412    /// skipping the intermediate `String` materialisation entirely.
413    pub fn from_socket_addr(addr: std::net::SocketAddr) -> Self {
414        use std::io::Write;
415        // Pre-size to fit `[ipv6_lit]:65535` (47 + brackets + colon +
416        // port digits ≈ 56 bytes worst case) so we don't re-grow the
417        // buffer mid-format on common addresses.
418        let mut buf = Vec::with_capacity(56);
419        // The `write!` macro on `&mut Vec<u8>` cannot fail (Vec's
420        // `Write` impl is infallible for in-memory buffers), so the
421        // expect is for shape only.
422        write!(&mut buf, "{addr}").expect("Vec<u8>::write_fmt is infallible");
423        Self(buf.into())
424    }
425
426    /// Get the raw bytes.
427    pub fn as_bytes(&self) -> &[u8] {
428        &self.0
429    }
430
431    /// Try to interpret as a UTF-8 string.
432    pub fn as_str(&self) -> Option<&str> {
433        std::str::from_utf8(&self.0).ok()
434    }
435
436    /// Get the length in bytes.
437    pub fn len(&self) -> usize {
438        self.0.len()
439    }
440
441    /// Check if empty.
442    pub fn is_empty(&self) -> bool {
443        self.0.is_empty()
444    }
445}
446
447impl fmt::Debug for TransportAddr {
448    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
449        match self.as_str() {
450            Some(s) => write!(f, "TransportAddr(\"{}\")", s),
451            None => write!(f, "TransportAddr({:?})", self.0),
452        }
453    }
454}
455
456impl fmt::Display for TransportAddr {
457    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
458        // Best-effort display as string if valid UTF-8, else hex
459        match self.as_str() {
460            Some(s) => write!(f, "{}", s),
461            None => {
462                for byte in self.0.iter() {
463                    write!(f, "{:02x}", byte)?;
464                }
465                Ok(())
466            }
467        }
468    }
469}
470
471impl From<&str> for TransportAddr {
472    fn from(s: &str) -> Self {
473        Self::from_string(s)
474    }
475}
476
477impl From<String> for TransportAddr {
478    fn from(s: String) -> Self {
479        Self(s.into_bytes().into())
480    }
481}
482
483// ============================================================================
484// Link Statistics
485// ============================================================================
486
487/// Statistics for a link.
488#[derive(Clone, Debug, Default)]
489pub struct LinkStats {
490    /// Total packets sent.
491    pub packets_sent: u64,
492    /// Total packets received.
493    pub packets_recv: u64,
494    /// Total bytes sent.
495    pub bytes_sent: u64,
496    /// Total bytes received.
497    pub bytes_recv: u64,
498    /// Timestamp of last received packet (Unix milliseconds).
499    pub last_recv_ms: u64,
500    /// Estimated round-trip time.
501    rtt_estimate: Option<Duration>,
502    /// Observed packet loss rate (0.0-1.0).
503    pub loss_rate: f32,
504    /// Estimated throughput in bytes/second.
505    pub throughput_estimate: u64,
506}
507
508impl LinkStats {
509    /// Create new link statistics.
510    pub fn new() -> Self {
511        Self::default()
512    }
513
514    /// Record a sent packet.
515    pub fn record_sent(&mut self, bytes: usize) {
516        self.packets_sent += 1;
517        self.bytes_sent += bytes as u64;
518    }
519
520    /// Record a received packet.
521    pub fn record_recv(&mut self, bytes: usize, timestamp_ms: u64) {
522        self.packets_recv += 1;
523        self.bytes_recv += bytes as u64;
524        self.last_recv_ms = timestamp_ms;
525    }
526
527    /// Get the RTT estimate, if available.
528    pub fn rtt_estimate(&self) -> Option<Duration> {
529        self.rtt_estimate
530    }
531
532    /// Update RTT estimate from a probe response.
533    ///
534    /// Uses exponential moving average with alpha=0.2.
535    pub fn update_rtt(&mut self, rtt: Duration) {
536        match self.rtt_estimate {
537            Some(old_rtt) => {
538                let alpha = 0.2;
539                let new_rtt_nanos = (alpha * rtt.as_nanos() as f64
540                    + (1.0 - alpha) * old_rtt.as_nanos() as f64)
541                    as u64;
542                self.rtt_estimate = Some(Duration::from_nanos(new_rtt_nanos));
543            }
544            None => {
545                self.rtt_estimate = Some(rtt);
546            }
547        }
548    }
549
550    /// Time since last receive (for keepalive/timeout).
551    pub fn time_since_recv(&self, current_time_ms: u64) -> u64 {
552        if self.last_recv_ms == 0 {
553            return u64::MAX;
554        }
555        current_time_ms.saturating_sub(self.last_recv_ms)
556    }
557
558    /// Reset all statistics.
559    pub fn reset(&mut self) {
560        *self = Self::default();
561    }
562}
563
564// ============================================================================
565// Link
566// ============================================================================
567
568/// A link to a remote endpoint over a transport.
569#[derive(Clone, Debug)]
570pub struct Link {
571    /// Unique link identifier.
572    link_id: LinkId,
573    /// Which transport this link uses.
574    transport_id: TransportId,
575    /// Transport-specific remote address.
576    remote_addr: TransportAddr,
577    /// Whether we initiated or they initiated.
578    direction: LinkDirection,
579    /// Current link state.
580    state: LinkState,
581    /// Base RTT hint from transport type.
582    base_rtt: Duration,
583    /// Measured statistics.
584    stats: LinkStats,
585    /// When this link was created (Unix milliseconds).
586    created_at: u64,
587}
588
589impl Link {
590    /// Create a new link in Connecting state.
591    pub fn new(
592        link_id: LinkId,
593        transport_id: TransportId,
594        remote_addr: TransportAddr,
595        direction: LinkDirection,
596        base_rtt: Duration,
597    ) -> Self {
598        Self {
599            link_id,
600            transport_id,
601            remote_addr,
602            direction,
603            state: LinkState::Connecting,
604            base_rtt,
605            stats: LinkStats::new(),
606            created_at: 0,
607        }
608    }
609
610    /// Create a link with a creation timestamp.
611    pub fn new_with_timestamp(
612        link_id: LinkId,
613        transport_id: TransportId,
614        remote_addr: TransportAddr,
615        direction: LinkDirection,
616        base_rtt: Duration,
617        created_at: u64,
618    ) -> Self {
619        let mut link = Self::new(link_id, transport_id, remote_addr, direction, base_rtt);
620        link.created_at = created_at;
621        link
622    }
623
624    /// Create a connectionless link (immediately connected).
625    ///
626    /// For connectionless transports (UDP, Ethernet), links are immediately
627    /// in the Connected state.
628    pub fn connectionless(
629        link_id: LinkId,
630        transport_id: TransportId,
631        remote_addr: TransportAddr,
632        direction: LinkDirection,
633        base_rtt: Duration,
634    ) -> Self {
635        let mut link = Self::new(link_id, transport_id, remote_addr, direction, base_rtt);
636        link.state = LinkState::Connected;
637        link
638    }
639
640    /// Get the link ID.
641    pub fn link_id(&self) -> LinkId {
642        self.link_id
643    }
644
645    /// Get the transport ID.
646    pub fn transport_id(&self) -> TransportId {
647        self.transport_id
648    }
649
650    /// Get the remote address.
651    pub fn remote_addr(&self) -> &TransportAddr {
652        &self.remote_addr
653    }
654
655    /// Get the link direction.
656    pub fn direction(&self) -> LinkDirection {
657        self.direction
658    }
659
660    /// Get the current state.
661    pub fn state(&self) -> LinkState {
662        self.state
663    }
664
665    /// Get the base RTT hint.
666    pub fn base_rtt(&self) -> Duration {
667        self.base_rtt
668    }
669
670    /// Get the link statistics.
671    pub fn stats(&self) -> &LinkStats {
672        &self.stats
673    }
674
675    /// Get mutable access to link statistics.
676    pub fn stats_mut(&mut self) -> &mut LinkStats {
677        &mut self.stats
678    }
679
680    /// Get the creation timestamp.
681    pub fn created_at(&self) -> u64 {
682        self.created_at
683    }
684
685    /// Set the creation timestamp.
686    pub fn set_created_at(&mut self, timestamp: u64) {
687        self.created_at = timestamp;
688    }
689
690    /// Mark the link as connected.
691    pub fn set_connected(&mut self) {
692        self.state = LinkState::Connected;
693    }
694
695    /// Mark the link as disconnected.
696    pub fn set_disconnected(&mut self) {
697        self.state = LinkState::Disconnected;
698    }
699
700    /// Mark the link as failed.
701    pub fn set_failed(&mut self) {
702        self.state = LinkState::Failed;
703    }
704
705    /// Check if this link is operational.
706    pub fn is_operational(&self) -> bool {
707        self.state.is_operational()
708    }
709
710    /// Check if this link is in a terminal state.
711    pub fn is_terminal(&self) -> bool {
712        self.state.is_terminal()
713    }
714
715    /// Get effective RTT (measured if available, else base hint).
716    pub fn effective_rtt(&self) -> Duration {
717        self.stats.rtt_estimate().unwrap_or(self.base_rtt)
718    }
719
720    /// Age of the link in milliseconds.
721    pub fn age(&self, current_time_ms: u64) -> u64 {
722        if self.created_at == 0 {
723            return 0;
724        }
725        current_time_ms.saturating_sub(self.created_at)
726    }
727}
728
729// ============================================================================
730// Discovered Peer
731// ============================================================================
732
733/// A peer discovered via transport-layer discovery.
734#[derive(Clone, Debug)]
735pub struct DiscoveredPeer {
736    /// Transport that discovered this peer.
737    pub transport_id: TransportId,
738    /// Transport address where the peer was found.
739    pub addr: TransportAddr,
740    /// Optional hint about the peer's identity (if known from discovery).
741    pub pubkey_hint: Option<XOnlyPublicKey>,
742}
743
744impl DiscoveredPeer {
745    /// Create a discovered peer without identity hint.
746    pub fn new(transport_id: TransportId, addr: TransportAddr) -> Self {
747        Self {
748            transport_id,
749            addr,
750            pubkey_hint: None,
751        }
752    }
753
754    /// Create a discovered peer with identity hint.
755    pub fn with_hint(
756        transport_id: TransportId,
757        addr: TransportAddr,
758        pubkey: XOnlyPublicKey,
759    ) -> Self {
760        Self {
761            transport_id,
762            addr,
763            pubkey_hint: Some(pubkey),
764        }
765    }
766}
767
768// ============================================================================
769// Transport Trait
770// ============================================================================
771
772/// Transport trait defining the interface for transport drivers.
773///
774/// This is a simplified synchronous trait. Actual implementations would
775/// be async and use channels for event delivery.
776pub trait Transport {
777    /// Get the transport identifier.
778    fn transport_id(&self) -> TransportId;
779
780    /// Get the transport type metadata.
781    fn transport_type(&self) -> &TransportType;
782
783    /// Get the current state.
784    fn state(&self) -> TransportState;
785
786    /// Get the MTU for this transport.
787    fn mtu(&self) -> u16;
788
789    /// Get the MTU for a specific link.
790    ///
791    /// Returns the MTU negotiated for the given transport address, or
792    /// falls back to the transport-wide default if the address is unknown
793    /// or the transport doesn't support per-link MTU negotiation.
794    fn link_mtu(&self, addr: &TransportAddr) -> u16 {
795        let _ = addr;
796        self.mtu()
797    }
798
799    /// Start the transport.
800    fn start(&mut self) -> Result<(), TransportError>;
801
802    /// Stop the transport.
803    fn stop(&mut self) -> Result<(), TransportError>;
804
805    /// Send data to a transport address.
806    fn send(&self, addr: &TransportAddr, data: &[u8]) -> Result<(), TransportError>;
807
808    /// Discover potential peers (if supported).
809    fn discover(&self) -> Result<Vec<DiscoveredPeer>, TransportError>;
810
811    /// Whether to auto-connect to peers returned by discover().
812    /// Default: false. Concrete transports read from their own config.
813    fn auto_connect(&self) -> bool {
814        false
815    }
816
817    /// Whether to accept inbound handshake initiations on this transport.
818    /// Default: true (preserves UDP's current implicit behavior).
819    fn accept_connections(&self) -> bool {
820        true
821    }
822
823    /// Close a specific connection (connection-oriented transports only).
824    ///
825    /// For connectionless transports (UDP, Ethernet), this is a no-op.
826    /// Connection-oriented transports (TCP, Tor) remove the connection
827    /// from their pool and drop the underlying stream.
828    fn close_connection(&self, _addr: &TransportAddr) {
829        // Default no-op for connectionless transports
830    }
831}
832
833// ============================================================================
834// Connection State (for non-blocking connect)
835// ============================================================================
836
837/// State of a transport-level connection attempt.
838///
839/// Used by connection-oriented transports (TCP, Tor) to report the progress
840/// of a background connection attempt initiated by `connect()`.
841#[derive(Clone, Debug, PartialEq, Eq)]
842pub enum ConnectionState {
843    /// No connection attempt in progress for this address.
844    None,
845    /// Connection attempt is in progress (background task running).
846    Connecting,
847    /// Connection is established and ready for send().
848    Connected,
849    /// Connection attempt failed with the given error message.
850    Failed(String),
851}
852
853// ============================================================================
854// Transport Congestion
855// ============================================================================
856
857/// Transport-local congestion indicators.
858///
859/// All fields are optional — transports report what they can.
860/// Consumers compute deltas from cumulative counters.
861#[derive(Clone, Debug, Default)]
862pub struct TransportCongestion {
863    /// Cumulative packets dropped by kernel/OS before reaching the application.
864    /// Monotonically increasing since transport start.
865    pub recv_drops: Option<u64>,
866}
867
868// ============================================================================
869// DNS Resolution
870// ============================================================================
871
872/// Resolve a TransportAddr to a SocketAddr.
873///
874/// Fast path: if the address parses as a numeric IP:port, returns
875/// immediately with no DNS lookup. Otherwise, treats the address as
876/// `hostname:port` and performs async DNS resolution via the system
877/// resolver.
878pub(crate) async fn resolve_socket_addr(
879    addr: &TransportAddr,
880) -> Result<SocketAddr, TransportError> {
881    resolve_socket_addrs(addr)
882        .await?
883        .into_iter()
884        .next()
885        .ok_or_else(|| {
886            TransportError::InvalidAddress(format!(
887                "DNS resolution returned no addresses for {}",
888                addr.as_str().unwrap_or("<non-utf8>")
889            ))
890        })
891}
892
893/// Resolve a TransportAddr to every SocketAddr returned by the resolver.
894///
895/// Numeric IP addresses still bypass DNS. Hostnames keep the resolver's
896/// address order, and callers that establish connections should try more than
897/// one address so dual-stack hosts still work when one address family is
898/// temporarily broken.
899pub(crate) async fn resolve_socket_addrs(
900    addr: &TransportAddr,
901) -> Result<Vec<SocketAddr>, TransportError> {
902    let s = addr
903        .as_str()
904        .ok_or_else(|| TransportError::InvalidAddress("not valid UTF-8".into()))?;
905
906    // Fast path: numeric IP address — no DNS lookup
907    if let Ok(sock_addr) = s.parse::<SocketAddr>() {
908        return Ok(vec![sock_addr]);
909    }
910
911    // Slow path: DNS resolution
912    let addrs = tokio::net::lookup_host(s)
913        .await
914        .map_err(|e| {
915            TransportError::InvalidAddress(format!("DNS resolution failed for {}: {}", s, e))
916        })?
917        .collect::<Vec<_>>();
918    if addrs.is_empty() {
919        return Err(TransportError::InvalidAddress(format!(
920            "DNS resolution returned no addresses for {}",
921            s
922        )));
923    }
924    Ok(addrs)
925}
fips_core/transport/mod.rs

fips_core/transport/
mod.rs
