Skip to main content

net_io/
tcp.rs

1//! TCP listeners and connections.
2
3use std::io::{self, IoSlice, IoSliceMut, Read, Write};
4use std::net::{Shutdown, SocketAddr, ToSocketAddrs};
5use std::sync::{Arc, Mutex, PoisonError};
6use std::time::{Duration, Instant};
7
8use crate::accept::{Accepted, Acceptor};
9use crate::driver::DriverKind;
10use crate::error::{CloseReason, ConfigReason, LimitKind, NetError, RefusalCause, TimeoutKind};
11use crate::gate::{AdmitStage, Gate, GateCell, KillHandle, guarded};
12use crate::id::{ConnectionId, ListenerId, WorkerId};
13use crate::info::{ConnectionInfo, Endpoint, Origin, Transport};
14use crate::limits::{Effective, Limits};
15use crate::link::{ClockRef, Got, Link, WakeSource};
16use crate::opts::{ListenOptions, SocketOptions, TcpOptions};
17use crate::proxy::ProxyMode;
18use crate::retry::Backoff;
19use crate::session::Phase;
20use crate::sys::{self, AddrFailure, AsSock, Interest, KillSlot, Ready};
21
22/// Facts about one bound listener.
23///
24/// ```
25/// let listener = net_io::listen("127.0.0.1:0")?;
26/// assert!(listener.info().local.socket_addr().is_some());
27/// # Ok::<(), net_io::NetError>(())
28/// ```
29#[non_exhaustive]
30#[derive(Clone, Debug)]
31pub struct ListenerInfo {
32    /// The listener's index in its server (0 for a plain listener).
33    pub id: ListenerId,
34    /// Its name, if one was given.
35    pub name: Option<String>,
36    /// The bound address.
37    pub local: Endpoint,
38    /// The effective backlog; `None` when it cannot be read (macOS, adopted sockets).
39    pub backlog: Option<u32>,
40    /// The kind of socket.
41    pub transport: Transport,
42    /// Whether it expects a PROXY header.
43    pub proxy: ProxyMode,
44    /// Whether it serves TLS.
45    pub tls: bool,
46}
47
48/// Linux silently caps the backlog at `net.core.somaxconn`; read it once.
49pub(crate) fn effective_backlog(requested: u32) -> Option<u32> {
50    if cfg!(target_os = "linux") {
51        let cap = std::fs::read_to_string("/proc/sys/net/core/somaxconn")
52            .ok()
53            .and_then(|s| s.trim().parse::<u32>().ok());
54        Some(cap.map_or(requested, |c| requested.min(c)))
55    } else if cfg!(windows) {
56        // Asked for as `SOMAXCONN_HINT` past 200, which Windows holds to 65,535.
57        Some(requested.min(65_535))
58    } else {
59        None
60    }
61}
62
63/// Whether accepted sockets inherit the listener's options (spike S-4, decision D-055).
64const OPTIONS_INHERITED: bool = cfg!(any(target_os = "linux", windows));
65
66pub(crate) fn bind_error(addr: SocketAddr, e: io::Error) -> NetError {
67    match sys::classify_addr_error(&e) {
68        AddrFailure::InUse => NetError::AddrInUse { addr },
69        AddrFailure::NotAvailable => NetError::AddrNotAvailable { addr },
70        AddrFailure::Permission => NetError::PermissionDenied { what: "bind" },
71        _ if e.kind() == io::ErrorKind::Unsupported => NetError::Unsupported {
72            feature: "a listen option this OS does not have",
73            platform: std::env::consts::OS,
74        },
75        _ => NetError::Bind { addr, source: e },
76    }
77}
78
79fn connect_error(addr: SocketAddr, after: Duration, e: io::Error) -> NetError {
80    // A reset during the handshake (a server refusing at its cap after the accept,
81    // a listen queue that overflowed) is a reset, as `NetError::from_os` maps it.
82    if matches!(
83        e.kind(),
84        io::ErrorKind::ConnectionReset | io::ErrorKind::ConnectionAborted
85    ) {
86        return NetError::ConnectionReset;
87    }
88    match sys::classify_addr_error(&e) {
89        AddrFailure::Refused => NetError::ConnectionRefused { addr },
90        AddrFailure::HostUnreachable => NetError::HostUnreachable { addr },
91        AddrFailure::NetworkUnreachable => NetError::NetworkUnreachable { addr },
92        AddrFailure::TimedOut => NetError::ConnectTimeout { addr, after },
93        AddrFailure::NotAvailable => NetError::AddrNotAvailable { addr },
94        AddrFailure::Permission => NetError::PermissionDenied { what: "connect" },
95        _ => NetError::Os {
96            op: "connect",
97            source: e,
98        },
99    }
100}
101
102/// Whether a connect error is one a restarting or failing-over server produces, or
103/// a shortage of local ports that passes (the backoff bounds the wait either way).
104/// A `local` address the host does not have is a configuration error: its bind
105/// fails with the same `AddrNotAvailable`, but names the local address.
106fn reconnectable(e: &NetError, local: Option<SocketAddr>) -> bool {
107    if matches!(e, NetError::AddrNotAvailable { addr } if Some(*addr) == local) {
108        return false;
109    }
110    e.is_retryable()
111        || matches!(
112            e,
113            NetError::ConnectionRefused { .. }
114                | NetError::HostUnreachable { .. }
115                | NetError::NetworkUnreachable { .. }
116                | NetError::ConnectionReset
117                | NetError::NoAddresses
118                | NetError::AddrNotAvailable { .. }
119                | NetError::Os { op: "resolve", .. }
120        )
121        || matches!(e, NetError::Os { op: "connect", source } if sys::out_of_ports(source))
122}
123
124fn resolve<A: ToSocketAddrs>(addr: A) -> Result<Vec<SocketAddr>, NetError> {
125    let addrs: Vec<SocketAddr> = addr
126        .to_socket_addrs()
127        .map_err(|e| NetError::Os {
128            op: "resolve",
129            source: e,
130        })?
131        .collect();
132    if addrs.is_empty() {
133        return Err(NetError::NoAddresses);
134    }
135    Ok(addrs)
136}
137
138/// A listening TCP socket created by net-io, so options that must precede `bind` can be set.
139///
140/// # Examples
141///
142/// ```no_run
143/// let listener = net_io::listen("0.0.0.0:7000")?;
144/// loop {
145///     let (mut conn, info) = listener.accept()?;
146///     println!("connection {} from {:?}", info.id, info.client_addr());
147///     conn.send_all(b"hello\n")?;
148///     conn.close()?;
149/// }
150/// # Ok::<(), net_io::NetError>(())
151/// ```
152#[derive(Debug)]
153pub struct TcpListener {
154    inner: std::net::TcpListener,
155    info: ListenerInfo,
156    tcp: TcpOptions,
157    acceptor: Mutex<Acceptor>,
158}
159
160impl TcpListener {
161    /// Binds with safe defaults (see [`crate::listen`]).
162    ///
163    /// # Errors
164    ///
165    /// `AddrInUse`, `PermissionDenied`, `AddrNotAvailable`, `NoAddresses`, `Bind`.
166    pub fn bind<A: ToSocketAddrs>(addr: A) -> Result<TcpListener, NetError> {
167        TcpListener::bind_with(addr, ListenOptions::new())
168    }
169
170    /// Binds with `options`, applied in the order `docs/API.md` gives.
171    ///
172    /// # Errors
173    ///
174    /// As [`TcpListener::bind`]; `Unsupported` for an option the platform lacks.
175    pub fn bind_with<A: ToSocketAddrs>(
176        addr: A,
177        options: ListenOptions,
178    ) -> Result<TcpListener, NetError> {
179        let mut last = NetError::NoAddresses;
180        for a in resolve(addr)? {
181            match sys::tcp_listener(a, &options.params()) {
182                Ok(l) => return TcpListener::finish(l, options, ListenerId(0), None),
183                Err(e) => last = bind_error(a, e),
184            }
185        }
186        Err(last)
187    }
188
189    pub(crate) fn finish(
190        inner: std::net::TcpListener,
191        options: ListenOptions,
192        id: ListenerId,
193        name: Option<String>,
194    ) -> Result<TcpListener, NetError> {
195        let local = inner
196            .local_addr()
197            .map_err(|e| NetError::from_os("getsockname", e))?;
198        if OPTIONS_INHERITED && !options.tcp.is_empty() {
199            options.tcp.apply(&inner, local.is_ipv6())?;
200        }
201        Ok(TcpListener {
202            info: ListenerInfo {
203                id,
204                name,
205                local: Endpoint::Ip(local),
206                backlog: effective_backlog(options.backlog),
207                transport: Transport::Tcp,
208                proxy: ProxyMode::Off,
209                tls: false,
210            },
211            inner,
212            tcp: options.tcp,
213            acceptor: Mutex::new(Acceptor::new()),
214        })
215    }
216
217    /// Blocks until a connection arrives; applies per-connection options, normalizes
218    /// the peer, issues a `ConnectionId`. No admission: a plain listener has no gate.
219    ///
220    /// # Errors
221    ///
222    /// `Limit { which: Descriptors }` when exhaustion persists past one backoff step; `Os`.
223    pub fn accept(&self) -> Result<(TcpConnection, ConnectionInfo), NetError> {
224        match self.accept_until(None)? {
225            Some(pair) => Ok(pair),
226            None => Err(NetError::TimedOut {
227                kind: TimeoutKind::Read,
228            }),
229        }
230    }
231
232    /// As [`TcpListener::accept`], but `Ok(None)` when nothing arrived within `timeout`.
233    ///
234    /// # Errors
235    ///
236    /// As [`TcpListener::accept`].
237    ///
238    /// ```
239    /// let listener = net_io::listen("127.0.0.1:0")?;
240    /// let got = listener.accept_timeout(std::time::Duration::from_millis(10))?;
241    /// assert!(got.is_none());
242    /// # Ok::<(), net_io::NetError>(())
243    /// ```
244    pub fn accept_timeout(
245        &self,
246        timeout: Duration,
247    ) -> Result<Option<(TcpConnection, ConnectionInfo)>, NetError> {
248        self.accept_until(Some(Instant::now() + crate::time::bounded(timeout)))
249    }
250
251    fn accept_until(
252        &self,
253        deadline: Option<Instant>,
254    ) -> Result<Option<(TcpConnection, ConnectionInfo)>, NetError> {
255        let mut paused_once = false;
256        loop {
257            let outcome = self
258                .acceptor
259                .lock()
260                .unwrap_or_else(PoisonError::into_inner)
261                .accept(&self.inner);
262            match outcome {
263                Accepted::Conn((stream, peer)) => {
264                    let conn = TcpConnection::accepted(stream, peer, &self.tcp, self.info.id)?;
265                    let info = conn.info().clone();
266                    return Ok(Some((conn, info)));
267                }
268                Accepted::Skipped(_) => continue,
269                Accepted::Again => {
270                    let timeout = match deadline {
271                        None => None,
272                        Some(d) => {
273                            let left = d.saturating_duration_since(Instant::now());
274                            if left.is_zero() {
275                                return Ok(None);
276                            }
277                            Some(left)
278                        }
279                    };
280                    match sys::wait(self.inner.sock(), Interest::Read, None, timeout) {
281                        Ok(Ready::TimedOut) => return Ok(None),
282                        Ok(_) => continue,
283                        Err(e) => return Err(NetError::from_os("poll", e)),
284                    }
285                }
286                Accepted::Pause(backoff) => {
287                    if paused_once {
288                        return Err(NetError::Limit {
289                            which: LimitKind::Descriptors,
290                        });
291                    }
292                    paused_once = true;
293                    std::thread::sleep(backoff);
294                }
295                Accepted::Failed(e) => return Err(NetError::from_os("accept", e)),
296            }
297        }
298    }
299
300    pub(crate) fn std(&self) -> &std::net::TcpListener {
301        &self.inner
302    }
303
304    /// Records the listener's id and name in its facts (adopted listeners).
305    pub(crate) fn set_identity(&mut self, id: ListenerId, name: Option<String>) {
306        self.info.id = id;
307        self.info.name = name;
308    }
309
310    /// Records whether the listener serves TLS in its facts.
311    pub(crate) fn set_tls(&mut self, on: bool) {
312        self.info.tls = on;
313    }
314
315    /// Records the listener's PROXY requirement in its facts.
316    pub(crate) fn set_proxy_mode(&mut self, mode: crate::proxy::ProxyMode) {
317        self.info.proxy = mode;
318    }
319
320    pub(crate) fn tcp_options(&self) -> &TcpOptions {
321        &self.tcp
322    }
323
324    /// Facts about this listener.
325    #[must_use]
326    pub fn info(&self) -> &ListenerInfo {
327        &self.info
328    }
329
330    /// The bound address.
331    ///
332    /// # Errors
333    ///
334    /// `Os` when `getsockname` fails.
335    pub fn local_addr(&self) -> Result<SocketAddr, NetError> {
336        self.inner
337            .local_addr()
338            .map_err(|e| NetError::from_os("getsockname", e))
339    }
340
341    /// Adopts an existing listening socket (checked with `SO_ACCEPTCONN` and `SO_TYPE`).
342    ///
343    /// # Errors
344    ///
345    /// `InvalidConfig { field: "socket", reason: NotListening }`.
346    ///
347    /// ```
348    /// let std_listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
349    /// let listener = net_io::TcpListener::from_std(std_listener)?;
350    /// assert!(listener.local_addr().is_ok());
351    /// # Ok::<(), net_io::NetError>(())
352    /// ```
353    pub fn from_std(listener: std::net::TcpListener) -> Result<TcpListener, NetError> {
354        match sys::is_listening_stream(listener.sock()) {
355            Ok(true) => {}
356            Ok(false) => {
357                return Err(NetError::InvalidConfig {
358                    field: "socket",
359                    reason: ConfigReason::NotListening,
360                });
361            }
362            Err(e) => return Err(NetError::from_os("getsockopt", e)),
363        }
364        listener
365            .set_nonblocking(true)
366            .map_err(|e| NetError::from_os("ioctl", e))?;
367        TcpListener::finish(
368            listener,
369            ListenOptions::new().tcp_options(TcpOptions::new()),
370            ListenerId(0),
371            None,
372        )
373        .map(|mut l| {
374            l.info.backlog = None;
375            l
376        })
377    }
378
379    /// Gives the socket up (it stays non-blocking).
380    #[must_use]
381    pub fn into_std(self) -> std::net::TcpListener {
382        self.inner
383    }
384
385    /// A second handle to the same listening socket.
386    ///
387    /// # Errors
388    ///
389    /// `Os` when duplication fails.
390    pub fn try_clone(&self) -> Result<TcpListener, NetError> {
391        let inner = self
392            .inner
393            .try_clone()
394            .map_err(|e| NetError::from_os("dup", e))?;
395        Ok(TcpListener {
396            inner,
397            info: self.info.clone(),
398            tcp: self.tcp,
399            acceptor: Mutex::new(Acceptor::new()),
400        })
401    }
402}
403
404#[cfg(unix)]
405impl std::os::fd::AsFd for TcpListener {
406    fn as_fd(&self) -> std::os::fd::BorrowedFd<'_> {
407        self.inner.as_fd()
408    }
409}
410
411#[cfg(unix)]
412impl From<TcpListener> for std::os::fd::OwnedFd {
413    fn from(l: TcpListener) -> std::os::fd::OwnedFd {
414        l.inner.into()
415    }
416}
417
418#[cfg(unix)]
419impl TryFrom<std::os::fd::OwnedFd> for TcpListener {
420    type Error = NetError;
421    fn try_from(fd: std::os::fd::OwnedFd) -> Result<TcpListener, NetError> {
422        TcpListener::from_std(std::net::TcpListener::from(fd))
423    }
424}
425
426#[cfg(windows)]
427impl std::os::windows::io::AsSocket for TcpListener {
428    fn as_socket(&self) -> std::os::windows::io::BorrowedSocket<'_> {
429        self.inner.as_socket()
430    }
431}
432
433#[cfg(windows)]
434impl From<TcpListener> for std::os::windows::io::OwnedSocket {
435    fn from(l: TcpListener) -> std::os::windows::io::OwnedSocket {
436        l.inner.into()
437    }
438}
439
440#[cfg(windows)]
441impl TryFrom<std::os::windows::io::OwnedSocket> for TcpListener {
442    type Error = NetError;
443    fn try_from(s: std::os::windows::io::OwnedSocket) -> Result<TcpListener, NetError> {
444        TcpListener::from_std(std::net::TcpListener::from(s))
445    }
446}
447
448/// Options for an outbound connection.
449///
450/// ```no_run
451/// use net_io::{ConnectOptions, TcpConnection};
452/// use std::time::Duration;
453/// let options = ConnectOptions::new().timeout(Duration::from_secs(3));
454/// let conn = TcpConnection::connect_host("example.com", 443, options)?;
455/// println!("connected to {}", conn.peer_addr());
456/// # Ok::<(), net_io::NetError>(())
457/// ```
458#[must_use]
459#[derive(Clone, Debug)]
460pub struct ConnectOptions {
461    timeout: Duration,
462    local_addr: Option<SocketAddr>,
463    tcp: TcpOptions,
464    limits: Limits,
465    happy_eyeballs: bool,
466    attempt_delay: Duration,
467}
468
469impl Default for ConnectOptions {
470    fn default() -> ConnectOptions {
471        ConnectOptions {
472            timeout: Duration::from_secs(10),
473            local_addr: None,
474            tcp: TcpOptions::new().nodelay(true),
475            limits: Limits::default(),
476            happy_eyeballs: false,
477            attempt_delay: Duration::from_millis(250),
478        }
479    }
480}
481
482impl ConnectOptions {
483    /// Timeout 10 s, `TCP_NODELAY` on, no local bind.
484    pub fn new() -> ConnectOptions {
485        ConnectOptions::default()
486    }
487
488    /// The total time for all attempts (held to at most 365 days).
489    pub fn timeout(mut self, total: Duration) -> ConnectOptions {
490        self.timeout = crate::time::bounded(total);
491        self
492    }
493
494    /// Binds to this address before connecting.
495    pub fn local_addr(mut self, addr: SocketAddr) -> ConnectOptions {
496        self.local_addr = Some(addr);
497        self
498    }
499
500    /// Options applied before the connect.
501    pub fn tcp_options(mut self, options: TcpOptions) -> ConnectOptions {
502        self.tcp = options;
503        self
504    }
505
506    /// Limits for the connection.
507    pub fn limits(mut self, limits: Limits) -> ConnectOptions {
508        self.limits = limits;
509        self
510    }
511
512    /// Happy Eyeballs (RFC 8305, simplified because `std` resolution returns both
513    /// families at once): attempts overlap instead of waiting for each other, IPv6
514    /// first and the families interleaved, and the first established connection wins.
515    /// The total timeout still bounds everything; the others are reset.
516    pub fn happy_eyeballs(mut self, on: bool) -> ConnectOptions {
517        self.happy_eyeballs = on;
518        self
519    }
520
521    /// How long an attempt runs alone before the next one starts (250 ms; held to
522    /// 100 ms through 2 s). An attempt that fails starts the next at once.
523    pub fn attempt_delay(mut self, d: Duration) -> ConnectOptions {
524        self.attempt_delay = d.clamp(Duration::from_millis(100), Duration::from_secs(2));
525        self
526    }
527}
528
529/// What [`TcpConnection::probe`] found, without waiting or consuming anything.
530///
531/// ```
532/// assert_ne!(net_io::Health::Open, net_io::Health::PeerClosed);
533/// ```
534#[non_exhaustive]
535#[derive(Clone, Copy, Debug, PartialEq, Eq)]
536pub enum Health {
537    /// Connected, nothing waiting: safe to send a request on.
538    Open,
539    /// Bytes are waiting (on a TLS connection, possibly only records), or, on a
540    /// stream other than TCP, bytes or the end of the stream.
541    Readable,
542    /// The peer sent FIN: the next read returns 0. A pooled connection in this state
543    /// should be closed, not reused.
544    PeerClosed,
545}
546
547/// What [`TcpConnection::drain`] saw before closing.
548///
549/// ```
550/// let d = net_io::Drained::default();
551/// assert!(!d.peer_closed && d.discarded == 0);
552/// ```
553#[non_exhaustive]
554#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
555pub struct Drained {
556    /// The peer's FIN arrived in time: both sides finished, nothing was reset.
557    pub peer_closed: bool,
558    /// Bytes read and dropped while waiting for it.
559    pub discarded: u64,
560}
561
562/// A connected TCP socket that carries its own limits.
563///
564/// Every read honours the current phase's deadline (a connection from `accept`
565/// starts `Idle` under the idle timeout; one from `connect` starts `Receiving`
566/// under the read timeout), the exchange deadline, and the inbound minimum
567/// rate; every write honours the write deadline and the outbound minimum rate.
568/// One owner: other threads act on it only through its [`KillHandle`].
569///
570/// # Examples
571///
572/// ```no_run
573/// use net_io::{Limits, Phase};
574/// use std::time::{Duration, Instant};
575///
576/// let mut conn = net_io::connect("127.0.0.1:7000")?;
577/// conn.set_limits(Limits::builder().read_timeout(Duration::from_secs(5)).build()?);
578/// conn.set_phase(Phase::Receiving);
579/// conn.set_exchange_deadline(Some(Instant::now() + Duration::from_secs(20)));
580/// let mut buf = [0u8; 1024];
581/// let n = conn.recv(&mut buf)?;
582/// # let _ = n;
583/// # Ok::<(), net_io::NetError>(())
584/// ```
585pub struct TcpConnection {
586    link: Option<Link>,
587}
588
589impl TcpConnection {
590    /// Connects with a 10 s timeout across every resolved address (see [`crate::connect`]).
591    ///
592    /// # Errors
593    ///
594    /// `ConnectTimeout`, `ConnectionRefused`, `HostUnreachable`, `NetworkUnreachable`, `NoAddresses`.
595    pub fn connect<A: ToSocketAddrs>(addr: A) -> Result<TcpConnection, NetError> {
596        TcpConnection::connect_with(addr, ConnectOptions::new())
597    }
598
599    /// Connects with `options`.
600    ///
601    /// # Errors
602    ///
603    /// As [`TcpConnection::connect`].
604    pub fn connect_with<A: ToSocketAddrs>(
605        addr: A,
606        options: ConnectOptions,
607    ) -> Result<TcpConnection, NetError> {
608        let addrs = resolve(addr)?;
609        TcpConnection::connect_addrs(&addrs, &options)
610    }
611
612    /// Connects, and after a failure a restarting or failing-over server produces
613    /// (refused, timed out, unreachable, reset, no addresses, resolution failed), or
614    /// a shortage of local ports (every ephemeral port in use or in TIME_WAIT),
615    /// sleeps for [`Backoff::next_delay`] and tries again, resolving `addr` again
616    /// each time. Any other error returns at once.
617    ///
618    /// ```no_run
619    /// use net_io::{Backoff, ConnectOptions, TcpConnection};
620    /// use std::time::Duration;
621    ///
622    /// let mut backoff = Backoff::new().give_up_after(Duration::from_secs(60));
623    /// let conn = TcpConnection::connect_retry("db.internal:5433", ConnectOptions::new(), &mut backoff)?;
624    /// backoff.reset();
625    /// # let _ = conn;
626    /// # Ok::<(), net_io::NetError>(())
627    /// ```
628    ///
629    /// # Errors
630    ///
631    /// The last connect error once `backoff` is spent; a non-transient error at once.
632    pub fn connect_retry<A: ToSocketAddrs>(
633        addr: A,
634        options: ConnectOptions,
635        backoff: &mut Backoff,
636    ) -> Result<TcpConnection, NetError> {
637        loop {
638            let err = match TcpConnection::connect_with(&addr, options.clone()) {
639                Ok(conn) => return Ok(conn),
640                Err(e) => e,
641            };
642            if !reconnectable(&err, options.local_addr) {
643                return Err(err);
644            }
645            match backoff.next_delay() {
646                Some(d) => std::thread::sleep(d),
647                None => return Err(err),
648            }
649        }
650    }
651
652    /// Resolves `host` with the standard library and connects to the addresses in
653    /// order; each attempt gets the remaining time divided by the remaining
654    /// addresses (at least 1 s).
655    ///
656    /// # Errors
657    ///
658    /// `NoAddresses`, or the last connect error.
659    pub fn connect_host(
660        host: &str,
661        port: u16,
662        options: ConnectOptions,
663    ) -> Result<TcpConnection, NetError> {
664        let addrs = resolve((host, port))?;
665        TcpConnection::connect_addrs(&addrs, &options)
666    }
667
668    fn connect_addrs(
669        addrs: &[SocketAddr],
670        options: &ConnectOptions,
671    ) -> Result<TcpConnection, NetError> {
672        if options.happy_eyeballs && addrs.len() > 1 {
673            return connect_racing(addrs, options);
674        }
675        let start = Instant::now();
676        let deadline = start + options.timeout;
677        let mut last = NetError::NoAddresses;
678        for (i, addr) in addrs.iter().enumerate() {
679            let left = deadline.saturating_duration_since(Instant::now());
680            if left.is_zero() {
681                break;
682            }
683            let remaining = (addrs.len() - i) as u32;
684            let attempt = (left / remaining).max(Duration::from_secs(1)).min(left);
685            match connect_one(*addr, options, attempt) {
686                Ok(conn) => return Ok(conn),
687                Err(e) => last = e,
688            }
689        }
690        if matches!(last, NetError::NoAddresses) {
691            if let Some(addr) = addrs.first() {
692                last = NetError::ConnectTimeout {
693                    addr: *addr,
694                    after: options.timeout,
695                };
696            }
697        }
698        Err(last)
699    }
700
701    pub(crate) fn accepted(
702        stream: std::net::TcpStream,
703        peer: SocketAddr,
704        tcp: &TcpOptions,
705        listener: ListenerId,
706    ) -> Result<TcpConnection, NetError> {
707        let local = stream
708            .local_addr()
709            .map_err(|e| NetError::from_os("getsockname", e))?;
710        if !OPTIONS_INHERITED && !tcp.is_empty() {
711            tcp.apply(&stream, local.is_ipv6())?;
712        }
713        let info = ConnectionInfo::new_tcp(
714            crate::id::issue_single(),
715            Some(listener),
716            WorkerId(0),
717            Origin::Accepted,
718            local,
719            peer,
720            Instant::now(),
721        );
722        let limits = Arc::new(Limits::default().effective(DriverKind::Blocking));
723        Ok(TcpConnection::from_link(Link::new(
724            sys::Stream::Tcp(stream),
725            info,
726            limits,
727            ClockRef::Monotonic,
728            Arc::new(KillSlot::new()),
729            WakeSource::Thread,
730            Phase::Idle,
731        )))
732    }
733
734    pub(crate) fn from_link(link: Link) -> TcpConnection {
735        TcpConnection { link: Some(link) }
736    }
737
738    /// The process at an end of a named pipe.
739    #[cfg(all(windows, feature = "local"))]
740    pub(crate) fn pipe_pid(&self, server: bool) -> Result<u32, NetError> {
741        match &self.link_ref().stream {
742            sys::Stream::Pipe(p) => if server {
743                p.server_pid()
744            } else {
745                p.client_pid()
746            }
747            .map_err(|e| NetError::from_os("GetNamedPipeClientProcessId", e)),
748            _ => Err(NetError::Unsupported {
749                feature: "client_pid on a socket",
750                platform: std::env::consts::OS,
751            }),
752        }
753    }
754
755    pub(crate) fn take_link(&mut self) -> Option<Link> {
756        self.link.take()
757    }
758
759    pub(crate) fn link(&mut self) -> Result<&mut Link, NetError> {
760        self.link.as_mut().ok_or(NetError::Closed)
761    }
762
763    pub(crate) fn link_ref(&self) -> &Link {
764        match &self.link {
765            Some(l) => l,
766            // Only `take_link` (crate-internal, at the end of a handler) empties it.
767            None => unreachable_link(),
768        }
769    }
770
771    /// One receive; `Ok(0)` means the peer closed its side. A zero-length `buf`
772    /// returns `Ok(0)` without a system call (check `buf.len()`).
773    ///
774    /// # Errors
775    ///
776    /// `TimedOut { kind }`, `SlowPeer { In }`, `ConnectionReset`, `Killed`, `Closed`.
777    pub fn recv(&mut self, buf: &mut [u8]) -> Result<usize, NetError> {
778        let link = self.link()?;
779        loop {
780            match link.read(buf)? {
781                Got::Data(n) => return Ok(n),
782                Got::Eof => return Ok(0),
783                Got::Woken => continue,
784            }
785        }
786    }
787
788    /// Receives until `buf` is full.
789    ///
790    /// # Errors
791    ///
792    /// As [`TcpConnection::recv`]; `Closed` when the peer closes first.
793    pub fn recv_exact(&mut self, buf: &mut [u8]) -> Result<(), NetError> {
794        let mut filled = 0;
795        while filled < buf.len() {
796            match self.recv(&mut buf[filled..])? {
797                0 => return Err(NetError::Closed),
798                n => filled += n,
799            }
800        }
801        Ok(())
802    }
803
804    /// One receive into the first non-empty slice.
805    ///
806    /// # Errors
807    ///
808    /// As [`TcpConnection::recv`].
809    pub fn recv_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, NetError> {
810        match bufs.iter_mut().find(|b| !b.is_empty()) {
811            Some(first) => self.recv(first),
812            None => Ok(0),
813        }
814    }
815
816    /// Reads without consuming (`MSG_PEEK`), within the read timeout.
817    ///
818    /// # Errors
819    ///
820    /// As [`TcpConnection::recv`]; `Unsupported` on a TLS connection.
821    pub fn peek(&self, buf: &mut [u8]) -> Result<usize, NetError> {
822        let link = self.link_ref();
823        if buf.is_empty() {
824            return Ok(0);
825        }
826        if link.has_tls() {
827            // The socket holds ciphertext; peeking at it would mean nothing here.
828            return Err(NetError::Unsupported {
829                feature: "peek on a TLS connection",
830                platform: std::env::consts::OS,
831            });
832        }
833        let timeout = link.limits.read_timeout;
834        match link.stream.wait(Interest::Read, None, Some(timeout)) {
835            Ok(Ready::TimedOut) => {
836                return Err(NetError::TimedOut {
837                    kind: TimeoutKind::Read,
838                });
839            }
840            Ok(_) => {}
841            Err(e) => return Err(NetError::from_os("poll", e)),
842        }
843        link.stream
844            .peek(buf)
845            .map_err(|e| NetError::from_os("recv", e))
846    }
847
848    /// One send after the gate check; may be partial.
849    ///
850    /// # Errors
851    ///
852    /// `TimedOut`, `SlowPeer { Out }`, `BrokenPipe`, `ConnectionReset`, `EgressDenied`, `Killed`.
853    pub fn send(&mut self, buf: &[u8]) -> Result<usize, NetError> {
854        self.link()?.write(buf)
855    }
856
857    /// Sends all of `buf`, continuing from the exact offset; the gate check runs
858    /// before every system call.
859    ///
860    /// # Errors
861    ///
862    /// As [`TcpConnection::send`].
863    pub fn send_all(&mut self, buf: &[u8]) -> Result<(), NetError> {
864        self.link()?.write_all(buf)
865    }
866
867    /// One vectored send (up to 64 slices) after the gate check; may be partial.
868    ///
869    /// # Errors
870    ///
871    /// As [`TcpConnection::send`].
872    pub fn send_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, NetError> {
873        self.link()?.write_vectored(bufs)
874    }
875
876    /// Sends `len` bytes of `file` from `offset`: zero copy where the OS can (`sendfile`
877    /// on Unix), by reading and writing otherwise (TLS; Windows outside the reactor). A
878    /// gate check runs before each 1 MiB. The file's position does not matter, and on
879    /// Unix it does not move.
880    ///
881    /// # Errors
882    ///
883    /// As [`TcpConnection::send`]; `FileTruncated { sent }` when the file ends early,
884    /// and the connection is then reset. Send files that do not change while in flight.
885    pub fn send_file(
886        &mut self,
887        file: &std::fs::File,
888        offset: u64,
889        len: u64,
890    ) -> Result<u64, NetError> {
891        self.link()?.send_file(file, offset, len)
892    }
893
894    /// Receives up to `len` bytes into `file` at `offset`, for snapshot and log
895    /// shipping; returns the count, which is short of `len` only when the peer
896    /// closed. On Linux the bytes go socket to pipe to file by `splice`, without a
897    /// copy through user space; with TLS, on other systems, and for a file `splice`
898    /// turns down, they are copied through a 64 KiB buffer. The read deadlines, the
899    /// minimum rate, kills, and drains apply as for [`TcpConnection::recv`]. The
900    /// file's position does not matter, and on Unix it does not move; a file opened
901    /// for appending is written at its end whatever `offset` says.
902    ///
903    /// ```no_run
904    /// let mut conn = net_io::connect("127.0.0.1:7000")?;
905    /// let file = std::fs::File::create("snapshot.bin")?;
906    /// let got = conn.recv_file(&file, 0, 1 << 30)?;
907    /// println!("received {got} bytes");
908    /// # Ok::<(), Box<dyn std::error::Error>>(())
909    /// ```
910    ///
911    /// # Errors
912    ///
913    /// As [`TcpConnection::recv`]; `Os` when the file cannot be written, and the
914    /// connection is then closed.
915    pub fn recv_file(
916        &mut self,
917        file: &std::fs::File,
918        offset: u64,
919        len: u64,
920    ) -> Result<u64, NetError> {
921        self.link()?.recv_file(file, offset, len)
922    }
923
924    /// Sends every slice, advancing them in place (no copy).
925    ///
926    /// # Errors
927    ///
928    /// As [`TcpConnection::send`].
929    pub fn send_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), NetError> {
930        self.link()?.write_all_vectored(bufs)
931    }
932
933    /// What the next read would find, without waiting and without consuming: one
934    /// zero-timeout wait, and a one-byte peek when the socket is readable. Use it
935    /// before reusing an idle pooled connection; a request sent on a connection
936    /// whose peer already closed is lost.
937    ///
938    /// ```no_run
939    /// use net_io::Health;
940    /// let mut conn = net_io::connect("127.0.0.1:7000")?;
941    /// if conn.probe()? != Health::Open {
942    ///     conn = net_io::connect("127.0.0.1:7000")?;
943    /// }
944    /// # let _ = conn;
945    /// # Ok::<(), net_io::NetError>(())
946    /// ```
947    ///
948    /// # Errors
949    ///
950    /// `ConnectionReset` when the peer reset it, `Killed`, `Closed` after a fatal
951    /// error, `Os`.
952    pub fn probe(&mut self) -> Result<Health, NetError> {
953        self.link()?.probe()
954    }
955
956    /// Client-side drain: FIN, then reads and discards until the peer's FIN arrives
957    /// or `within` passes, then closes. Closing after the peer's FIN leaves nothing
958    /// unread, so neither side sees a reset.
959    ///
960    /// ```no_run
961    /// use std::time::Duration;
962    /// let conn = net_io::connect("127.0.0.1:7000")?;
963    /// let drained = conn.drain(Duration::from_secs(2));
964    /// println!("clean: {}, discarded {} bytes", drained.peer_closed, drained.discarded);
965    /// # Ok::<(), net_io::NetError>(())
966    /// ```
967    pub fn drain(mut self, within: Duration) -> Drained {
968        let Some(mut link) = self.link.take() else {
969            return Drained::default();
970        };
971        let (peer_closed, discarded) = link.drain_for(within);
972        let reason = link.reason_or(CloseReason::SessionClosed);
973        link.finish_quick(reason);
974        Drained {
975            peer_closed,
976            discarded,
977        }
978    }
979
980    /// Half-close: `Write` sends FIN and keeps reading; `Read` stops reading.
981    ///
982    /// # Errors
983    ///
984    /// `Closed`, `Os`.
985    pub fn shutdown(&mut self, how: Shutdown) -> Result<(), NetError> {
986        self.link()?.shutdown(how)
987    }
988
989    /// Graceful close: FIN, then reads and discards up to 64 KiB for up to 2 s so
990    /// unread input does not cause an RST that destroys the last response.
991    ///
992    /// # Errors
993    ///
994    /// None in this version; the signature leaves room for a flush error.
995    pub fn close(mut self) -> Result<(), NetError> {
996        if let Some(link) = self.link.take() {
997            let reason = link.reason_or(CloseReason::SessionClosed);
998            link.finish(reason);
999        }
1000        Ok(())
1001    }
1002
1003    /// Abortive close: RST, kernel resources freed at once.
1004    pub fn abort(mut self) {
1005        if let Some(link) = self.link.take() {
1006            let reason = link.reason_or(CloseReason::SessionError);
1007            let reason = if reason.is_abortive() {
1008                reason
1009            } else {
1010                CloseReason::SessionError
1011            };
1012            link.finish(reason);
1013        }
1014    }
1015
1016    /// What net-io knows about this connection.
1017    #[must_use]
1018    pub fn info(&self) -> &ConnectionInfo {
1019        &self.link_ref().info
1020    }
1021
1022    /// The connection's id.
1023    #[must_use]
1024    pub fn id(&self) -> ConnectionId {
1025        self.link_ref().info.id
1026    }
1027
1028    /// The socket peer.
1029    #[must_use]
1030    pub fn peer_addr(&self) -> SocketAddr {
1031        self.link_ref()
1032            .info
1033            .peer
1034            .socket_addr()
1035            .unwrap_or_else(|| SocketAddr::from(([0, 0, 0, 0], 0)))
1036    }
1037
1038    /// Our end.
1039    #[must_use]
1040    pub fn local_addr(&self) -> SocketAddr {
1041        self.link_ref()
1042            .info
1043            .local
1044            .socket_addr()
1045            .unwrap_or_else(|| SocketAddr::from(([0, 0, 0, 0], 0)))
1046    }
1047
1048    /// A handle other threads can use to abort this connection.
1049    #[must_use]
1050    pub fn kill_handle(&self) -> KillHandle {
1051        let link = self.link_ref();
1052        KillHandle {
1053            slot: link.slot.clone(),
1054            generation: link.generation(),
1055            id: link.info.id,
1056        }
1057    }
1058
1059    /// Replaces the limits from the next operation on (unset values: blocking-driver defaults).
1060    pub fn set_limits(&mut self, limits: Limits) {
1061        if let Ok(link) = self.link() {
1062            let e: Effective = limits.effective(DriverKind::Blocking);
1063            link.set_limits(e);
1064        }
1065    }
1066
1067    /// Chooses which deadlines apply.
1068    pub fn set_phase(&mut self, phase: Phase) {
1069        if let Ok(link) = self.link() {
1070            link.set_phase(phase);
1071        }
1072    }
1073
1074    /// The deadline for the current exchange (`None` clears it).
1075    pub fn set_exchange_deadline(&mut self, at: Option<Instant>) {
1076        if let Ok(link) = self.link() {
1077            link.set_exchange_deadline(at);
1078        }
1079    }
1080
1081    /// Registers this dialed connection with `gate` (`Gate::admit` with
1082    /// `AdmitStage::Dialed`): from then on `Gate::check` runs before every write
1083    /// and `Gate::closed` runs once at close, so a back-channel or outbound
1084    /// connection can be revoked like an accepted one.
1085    ///
1086    /// # Errors
1087    ///
1088    /// `Refused { cause: Gate(code) }` when the gate refuses (the connection is
1089    /// then aborted and later calls return `Closed`); `InvalidConfig { field:
1090    /// "gate" }` when a gate is already set; `Closed`.
1091    ///
1092    /// ```no_run
1093    /// use std::sync::Arc;
1094    /// let mut upstream = net_io::connect("10.0.0.9:9000")?;
1095    /// upstream.set_gate(Arc::new(net_io::AllowAll))?;
1096    /// upstream.send_all(b"PING\r\n")?;
1097    /// # Ok::<(), net_io::NetError>(())
1098    /// ```
1099    pub fn set_gate<G: Gate>(&mut self, gate: Arc<G>) -> Result<(), NetError> {
1100        let link = self.link()?;
1101        if link.gate.is_some() {
1102            return Err(NetError::InvalidConfig {
1103                field: "gate",
1104                reason: ConfigReason::Inconsistent,
1105            });
1106        }
1107        let code = match guarded(|| gate.admit(&link.info, AdmitStage::Dialed)) {
1108            Some(Ok(admitted)) => {
1109                link.info.lane = admitted.lane;
1110                link.info.gate = admitted.tag;
1111                link.gate = Some(Box::new(GateCell {
1112                    gate,
1113                    ticket: Some(admitted.ticket),
1114                }));
1115                return Ok(());
1116            }
1117            Some(Err(refusal)) => refusal.code(),
1118            None => 0,
1119        };
1120        let cause = RefusalCause::Gate(code);
1121        if let Some(link) = self.link.take() {
1122            link.finish(CloseReason::Refused(cause));
1123        }
1124        Err(NetError::Refused { cause })
1125    }
1126
1127    /// Live socket options.
1128    #[must_use]
1129    pub fn options(&self) -> SocketOptions<'_> {
1130        let link = self.link_ref();
1131        SocketOptions {
1132            sock: link.stream.sock(),
1133            v6: link.info.local.socket_addr().is_some_and(|a| a.is_ipv6()),
1134        }
1135    }
1136
1137    /// The socket's pending error (`SO_ERROR`).
1138    ///
1139    /// # Errors
1140    ///
1141    /// `Os` when the OS call fails.
1142    pub fn take_error(&self) -> Result<Option<io::Error>, NetError> {
1143        sys::take_error(self.link_ref().stream.sock())
1144            .map_err(|e| NetError::from_os("getsockopt", e))
1145    }
1146}
1147
1148#[cold]
1149fn unreachable_link() -> ! {
1150    // A TcpConnection is emptied only by the server after its handler returned,
1151    // when no code can reach it any more.
1152    std::process::abort()
1153}
1154
1155/// A non-blocking socket ready to connect to `addr`.
1156fn dial_socket(
1157    addr: SocketAddr,
1158    options: &ConnectOptions,
1159) -> Result<std::net::TcpStream, NetError> {
1160    let owned = sys::tcp_socket(addr.is_ipv6()).map_err(|e| NetError::from_os("socket", e))?;
1161    let stream = std::net::TcpStream::from(owned);
1162    stream
1163        .set_nonblocking(true)
1164        .map_err(|e| NetError::from_os("ioctl", e))?;
1165    options.tcp.apply(&stream, addr.is_ipv6())?;
1166    if let Some(local) = options.local_addr {
1167        sys::bind_to(stream.sock(), local).map_err(|e| bind_error(local, e))?;
1168    }
1169    Ok(stream)
1170}
1171
1172/// IPv6 first, then the families take turns.
1173fn interleaved(addrs: &[SocketAddr]) -> Vec<SocketAddr> {
1174    let (v6, v4): (Vec<_>, Vec<_>) = addrs.iter().copied().partition(SocketAddr::is_ipv6);
1175    let (mut v6, mut v4) = (v6.into_iter(), v4.into_iter());
1176    let mut out = Vec::with_capacity(addrs.len());
1177    loop {
1178        match (v6.next(), v4.next()) {
1179            (None, None) => return out,
1180            (a, b) => out.extend(a.into_iter().chain(b)),
1181        }
1182    }
1183}
1184
1185/// At most this many attempts run at once, and never two start closer than this.
1186const MAX_RACING: usize = 16;
1187const RACE_SPACING: Duration = Duration::from_millis(10);
1188
1189/// Happy Eyeballs: see [`ConnectOptions::happy_eyeballs`]. Dropping a losing attempt
1190/// resets it, so nothing lingers half open at the far end.
1191fn connect_racing(
1192    addrs: &[SocketAddr],
1193    options: &ConnectOptions,
1194) -> Result<TcpConnection, NetError> {
1195    let ordered = interleaved(addrs);
1196    let start = Instant::now();
1197    let deadline = start + options.timeout;
1198    let mut racing: Vec<(std::net::TcpStream, SocketAddr, Instant)> = Vec::new();
1199    let mut queue = ordered.iter().copied();
1200    let mut waiting = queue.next();
1201    let mut next_at = start;
1202    let mut last_start: Option<Instant> = None;
1203    let mut last = NetError::NoAddresses;
1204    loop {
1205        let now = Instant::now();
1206        if now >= deadline {
1207            break;
1208        }
1209        let spaced = last_start.map_or(now, |t| t + RACE_SPACING);
1210        if let Some(addr) = waiting.filter(|_| {
1211            racing.len() < MAX_RACING && now >= spaced && (now >= next_at || racing.is_empty())
1212        }) {
1213            waiting = queue.next();
1214            last_start = Some(now);
1215            next_at = now + options.attempt_delay;
1216            let stream = match dial_socket(addr, options) {
1217                Ok(s) => s,
1218                Err(e) => {
1219                    last = e;
1220                    next_at = now;
1221                    continue;
1222                }
1223            };
1224            match sys::connect_start(stream.sock(), addr) {
1225                Ok(false) => return dialed(stream, addr, options),
1226                Ok(true) => racing.push((stream, addr, now)),
1227                Err(e) => {
1228                    last = connect_error(addr, Duration::ZERO, e);
1229                    next_at = now;
1230                }
1231            }
1232            continue;
1233        }
1234        if racing.is_empty() && waiting.is_none() {
1235            break;
1236        }
1237        let mut until = deadline;
1238        if waiting.is_some() {
1239            until = until.min(next_at.max(spaced).max(now + Duration::from_millis(1)));
1240        }
1241        let wait = until.saturating_duration_since(now);
1242        if racing.is_empty() {
1243            std::thread::sleep(wait);
1244            continue;
1245        }
1246        let socks: Vec<_> = racing.iter().map(|(s, ..)| s.sock()).collect();
1247        let ready = sys::wait_writable(&socks, wait).map_err(|e| NetError::from_os("poll", e))?;
1248        drop(socks);
1249        for i in (0..racing.len()).rev() {
1250            if ready & (1 << i) == 0 {
1251                continue;
1252            }
1253            let (stream, addr, began) = racing.swap_remove(i);
1254            match sys::take_error(stream.sock()) {
1255                Ok(None) => {
1256                    for (loser, ..) in &racing {
1257                        let _ = sys::set_linger(loser.sock(), Some(Duration::ZERO));
1258                    }
1259                    return dialed(stream, addr, options);
1260                }
1261                Ok(Some(e)) => {
1262                    last = connect_error(addr, began.elapsed(), e);
1263                    next_at = Instant::now();
1264                }
1265                Err(e) => last = NetError::from_os("getsockopt", e),
1266            }
1267        }
1268    }
1269    for (loser, ..) in &racing {
1270        let _ = sys::set_linger(loser.sock(), Some(Duration::ZERO));
1271    }
1272    if matches!(last, NetError::NoAddresses) {
1273        if let Some(addr) = ordered.first() {
1274            last = NetError::ConnectTimeout {
1275                addr: *addr,
1276                after: options.timeout,
1277            };
1278        }
1279    }
1280    Err(last)
1281}
1282
1283fn connect_one(
1284    addr: SocketAddr,
1285    options: &ConnectOptions,
1286    attempt: Duration,
1287) -> Result<TcpConnection, NetError> {
1288    let stream = dial_socket(addr, options)?;
1289    let started = Instant::now();
1290    match sys::connect_start(stream.sock(), addr) {
1291        Ok(false) => {}
1292        Ok(true) => {
1293            match sys::wait(stream.sock(), Interest::Write, None, Some(attempt)) {
1294                Ok(Ready::TimedOut) => {
1295                    return Err(NetError::ConnectTimeout {
1296                        addr,
1297                        after: attempt,
1298                    });
1299                }
1300                Ok(_) => {}
1301                Err(e) => return Err(NetError::from_os("poll", e)),
1302            }
1303            match sys::take_error(stream.sock()) {
1304                Ok(None) => {}
1305                Ok(Some(e)) => return Err(connect_error(addr, started.elapsed(), e)),
1306                Err(e) => return Err(NetError::from_os("getsockopt", e)),
1307            }
1308        }
1309        Err(e) => return Err(connect_error(addr, started.elapsed(), e)),
1310    }
1311    dialed(stream, addr, options)
1312}
1313
1314/// A connection from a socket that just connected to `addr`.
1315fn dialed(
1316    stream: std::net::TcpStream,
1317    addr: SocketAddr,
1318    options: &ConnectOptions,
1319) -> Result<TcpConnection, NetError> {
1320    sys::prepare_dialed(&stream).map_err(|e| NetError::from_os("ioctl", e))?;
1321    let local = stream
1322        .local_addr()
1323        .map_err(|e| NetError::from_os("getsockname", e))?;
1324    let info = ConnectionInfo::new_tcp(
1325        crate::id::issue_single(),
1326        None,
1327        WorkerId(0),
1328        Origin::Dialed,
1329        local,
1330        crate::addr::normalize_socket(addr),
1331        Instant::now(),
1332    );
1333    Ok(TcpConnection::from_link(Link::new(
1334        sys::Stream::Tcp(stream),
1335        info,
1336        Arc::new(options.limits.effective(DriverKind::Blocking)),
1337        ClockRef::Monotonic,
1338        Arc::new(KillSlot::new()),
1339        WakeSource::Thread,
1340        Phase::Receiving,
1341    )))
1342}
1343
1344impl Read for TcpConnection {
1345    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
1346        self.recv(buf).map_err(io::Error::from)
1347    }
1348}
1349
1350impl Write for TcpConnection {
1351    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1352        self.send(buf).map_err(io::Error::from)
1353    }
1354
1355    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
1356        self.send_vectored(bufs).map_err(io::Error::from)
1357    }
1358
1359    fn flush(&mut self) -> io::Result<()> {
1360        Ok(())
1361    }
1362}
1363
1364impl Drop for TcpConnection {
1365    /// Never blocks: FIN, then close without the linger; use `close()` for the full graceful close.
1366    fn drop(&mut self) {
1367        if let Some(link) = self.link.take() {
1368            let reason = link.reason_or(CloseReason::SessionClosed);
1369            link.finish_quick(reason);
1370        }
1371    }
1372}
1373
1374impl std::fmt::Debug for TcpConnection {
1375    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1376        match &self.link {
1377            Some(l) => f
1378                .debug_struct("TcpConnection")
1379                .field("info", &l.info)
1380                .finish(),
1381            None => f.write_str("TcpConnection(closed)"),
1382        }
1383    }
1384}
1385
1386#[cfg(unix)]
1387impl std::os::fd::AsFd for TcpConnection {
1388    fn as_fd(&self) -> std::os::fd::BorrowedFd<'_> {
1389        std::os::fd::AsFd::as_fd(&self.link_ref().stream)
1390    }
1391}
1392
1393#[cfg(windows)]
1394impl std::os::windows::io::AsSocket for TcpConnection {
1395    fn as_socket(&self) -> std::os::windows::io::BorrowedSocket<'_> {
1396        std::os::windows::io::AsSocket::as_socket(&self.link_ref().stream)
1397    }
1398}
1399
1400#[cfg(test)]
1401mod tests {
1402    use super::*;
1403
1404    /// The soak's pooled client gave up at once on a reset during connect (a server
1405    /// refusing at its cap) and on Windows port exhaustion: both pass, so a reconnect
1406    /// waits for them under its backoff.
1407    #[test]
1408    fn test_connect_resets_and_port_shortage_are_reconnectable() {
1409        let addr: SocketAddr = "127.0.0.1:9".parse().unwrap();
1410        let reset = connect_error(
1411            addr,
1412            Duration::ZERO,
1413            io::Error::from(io::ErrorKind::ConnectionReset),
1414        );
1415        assert!(matches!(reset, NetError::ConnectionReset));
1416        assert!(reconnectable(&reset, None));
1417        #[cfg(windows)]
1418        let shortages = [10055, 10048, 10049];
1419        #[cfg(unix)]
1420        let shortages = [sys::errno::EADDRNOTAVAIL, sys::errno::EADDRINUSE];
1421        for code in shortages {
1422            let short = connect_error(addr, Duration::ZERO, io::Error::from_raw_os_error(code));
1423            assert!(reconnectable(&short, None), "{code}: {short:?}");
1424        }
1425        let denied = connect_error(
1426            addr,
1427            Duration::ZERO,
1428            io::Error::from(io::ErrorKind::PermissionDenied),
1429        );
1430        assert!(!reconnectable(&denied, None), "{denied:?}");
1431        // A bind to a local address this host does not have names that address.
1432        let local: SocketAddr = "192.0.2.1:0".parse().unwrap();
1433        #[cfg(unix)]
1434        let not_available = sys::errno::EADDRNOTAVAIL;
1435        #[cfg(windows)]
1436        let not_available = sys::errno::WSAEADDRNOTAVAIL;
1437        let missing = bind_error(local, io::Error::from_raw_os_error(not_available));
1438        assert!(!reconnectable(&missing, Some(local)), "{missing:?}");
1439    }
1440
1441    #[test]
1442    fn test_listen_accept_echo_round_trip() {
1443        let l = TcpListener::bind("127.0.0.1:0").unwrap();
1444        let addr = l.local_addr().unwrap();
1445        let t = std::thread::spawn(move || {
1446            let (mut c, info) = l.accept().unwrap();
1447            assert_eq!(info.origin, Origin::Accepted);
1448            let mut buf = [0u8; 4];
1449            c.recv_exact(&mut buf).unwrap();
1450            c.send_all(&buf).unwrap();
1451            c.close().unwrap();
1452        });
1453        let mut c = TcpConnection::connect(addr).unwrap();
1454        c.send_all(b"ping").unwrap();
1455        let mut buf = [0u8; 4];
1456        c.recv_exact(&mut buf).unwrap();
1457        assert_eq!(&buf, b"ping");
1458        assert_eq!(c.recv(&mut buf).unwrap(), 0);
1459        t.join().unwrap();
1460    }
1461
1462    #[test]
1463    fn test_connect_refused_maps_to_connection_refused() {
1464        // Bind then drop to get a free port with nothing listening.
1465        let port = std::net::TcpListener::bind("127.0.0.1:0")
1466            .unwrap()
1467            .local_addr()
1468            .unwrap()
1469            .port();
1470        let err = TcpConnection::connect_with(
1471            ("127.0.0.1", port),
1472            ConnectOptions::new().timeout(Duration::from_secs(5)),
1473        )
1474        .unwrap_err();
1475        assert!(
1476            matches!(
1477                err,
1478                NetError::ConnectionRefused { .. } | NetError::ConnectTimeout { .. }
1479            ),
1480            "{err:?}"
1481        );
1482    }
1483
1484    #[test]
1485    fn test_bind_in_use_maps_to_addr_in_use() {
1486        let a = TcpListener::bind("127.0.0.1:0").unwrap();
1487        let err = TcpListener::bind(a.local_addr().unwrap()).unwrap_err();
1488        assert!(matches!(err, NetError::AddrInUse { .. }), "{err:?}");
1489    }
1490
1491    /// Edge cases 127 and 128: bind errors map by class, whatever the OS's number.
1492    #[test]
1493    fn test_bind_errors_map_by_class() {
1494        #[cfg(unix)]
1495        use crate::sys::errno::{EACCES as ACCESS, EADDRNOTAVAIL as NOT_AVAILABLE};
1496        #[cfg(windows)]
1497        use crate::sys::errno::{WSAEACCES as ACCESS, WSAEADDRNOTAVAIL as NOT_AVAILABLE};
1498        let addr: SocketAddr = "[::1]:80".parse().unwrap();
1499        let e = bind_error(addr, io::Error::from_raw_os_error(NOT_AVAILABLE));
1500        assert!(matches!(e, NetError::AddrNotAvailable { .. }), "{e:?}");
1501        let e = bind_error(addr, io::Error::from_raw_os_error(ACCESS));
1502        assert!(matches!(e, NetError::PermissionDenied { .. }), "{e:?}");
1503    }
1504
1505    #[test]
1506    fn test_read_timeout_fires() {
1507        let l = TcpListener::bind("127.0.0.1:0").unwrap();
1508        let addr = l.local_addr().unwrap();
1509        let _server = std::thread::spawn(move || {
1510            let (c, _) = l.accept().unwrap();
1511            std::thread::sleep(Duration::from_secs(2));
1512            drop(c);
1513        });
1514        let limits = Limits::builder()
1515            .read_timeout(Duration::from_millis(200))
1516            .min_rate(crate::limits::MinRate::off())
1517            .build()
1518            .unwrap();
1519        let mut c =
1520            TcpConnection::connect_with(addr, ConnectOptions::new().limits(limits)).unwrap();
1521        let mut buf = [0u8; 8];
1522        let start = Instant::now();
1523        let err = c.recv(&mut buf).unwrap_err();
1524        assert!(
1525            matches!(
1526                err,
1527                NetError::TimedOut {
1528                    kind: TimeoutKind::Read
1529                }
1530            ),
1531            "{err:?}"
1532        );
1533        assert!(start.elapsed() < Duration::from_secs(2));
1534    }
1535
1536    #[test]
1537    fn test_kill_wakes_blocked_recv() {
1538        let l = TcpListener::bind("127.0.0.1:0").unwrap();
1539        let addr = l.local_addr().unwrap();
1540        let _server = std::thread::spawn(move || {
1541            let (c, _) = l.accept().unwrap();
1542            std::thread::sleep(Duration::from_secs(3));
1543            drop(c);
1544        });
1545        let mut c = TcpConnection::connect(addr).unwrap();
1546        let kill = c.kill_handle();
1547        std::thread::spawn(move || {
1548            std::thread::sleep(Duration::from_millis(100));
1549            assert!(kill.kill(crate::error::KillReason(4)));
1550        });
1551        let mut buf = [0u8; 8];
1552        let start = Instant::now();
1553        let err = c.recv(&mut buf).unwrap_err();
1554        assert!(matches!(err, NetError::Killed { .. }), "{err:?}");
1555        assert!(start.elapsed() < Duration::from_secs(2));
1556    }
1557
1558    #[test]
1559    fn test_interleaved_starts_with_v6_and_takes_turns() {
1560        let a = |t: &str| t.parse::<SocketAddr>().unwrap();
1561        let (v4a, v4b, v4c) = (a("1.1.1.1:1"), a("2.2.2.2:1"), a("3.3.3.3:1"));
1562        let (v6a, v6b) = (a("[::1]:1"), a("[::2]:1"));
1563        assert_eq!(
1564            interleaved(&[v4a, v4b, v4c, v6a, v6b]),
1565            [v6a, v4a, v6b, v4b, v4c]
1566        );
1567        assert_eq!(interleaved(&[v4a, v4b]), [v4a, v4b]);
1568        assert!(interleaved(&[]).is_empty());
1569    }
1570
1571    #[test]
1572    fn test_attempt_delay_is_held_to_its_range() {
1573        let low = ConnectOptions::new().attempt_delay(Duration::from_millis(1));
1574        assert_eq!(low.attempt_delay, Duration::from_millis(100));
1575        let high = ConnectOptions::new().attempt_delay(Duration::from_secs(9));
1576        assert_eq!(high.attempt_delay, Duration::from_secs(2));
1577    }
1578
1579    #[test]
1580    fn test_racing_a_refused_address_moves_on_at_once() {
1581        let closed = {
1582            let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
1583            l.local_addr().unwrap()
1584        };
1585        let live = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
1586        let options = ConnectOptions::new()
1587            .happy_eyeballs(true)
1588            .attempt_delay(Duration::from_secs(2));
1589        let started = Instant::now();
1590        let c = TcpConnection::connect_addrs(&[closed, live.local_addr().unwrap()], &options);
1591        assert_eq!(c.unwrap().peer_addr(), live.local_addr().unwrap());
1592        // Windows retries a refused connect for about 2 s before it reports it.
1593        if cfg!(unix) {
1594            assert!(
1595                started.elapsed() < Duration::from_secs(2),
1596                "no attempt delay"
1597            );
1598        }
1599    }
1600
1601    #[test]
1602    fn test_racing_every_address_refused_reports_the_last() {
1603        let closed: Vec<SocketAddr> = (0..2)
1604            .map(|_| {
1605                let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
1606                l.local_addr().unwrap()
1607            })
1608            .collect();
1609        let options = ConnectOptions::new()
1610            .timeout(Duration::from_secs(5))
1611            .happy_eyeballs(true);
1612        let e = TcpConnection::connect_addrs(&closed, &options).err();
1613        assert!(
1614            matches!(e, Some(NetError::ConnectionRefused { .. })),
1615            "{e:?}"
1616        );
1617    }
1618
1619    /// A silent address (documentation range: nothing answers it) cannot hold the
1620    /// connection up longer than the attempt delay.
1621    #[test]
1622    fn test_racing_a_silent_address_starts_the_next_after_the_delay() {
1623        let silent: SocketAddr = "192.0.2.1:9".parse().unwrap();
1624        let live = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
1625        let options = ConnectOptions::new()
1626            .timeout(Duration::from_secs(5))
1627            .happy_eyeballs(true)
1628            .attempt_delay(Duration::from_millis(100));
1629        let started = Instant::now();
1630        let c = TcpConnection::connect_addrs(&[silent, live.local_addr().unwrap()], &options);
1631        assert_eq!(c.unwrap().peer_addr(), live.local_addr().unwrap());
1632        assert!(started.elapsed() < Duration::from_secs(2));
1633    }
1634
1635    #[test]
1636    fn test_listen_options_that_an_os_lacks_are_refused() {
1637        let bind = |o: ListenOptions| TcpListener::bind_with("127.0.0.1:0", o);
1638        let defer = ListenOptions::new().defer_accept(Some(Duration::from_secs(1)));
1639        let cpu = ListenOptions::new().incoming_cpu(Some(0));
1640        if cfg!(target_os = "linux") {
1641            assert!(bind(defer).is_ok());
1642            assert!(bind(cpu).is_ok());
1643        } else {
1644            assert!(matches!(bind(defer), Err(NetError::Unsupported { .. })));
1645            assert!(matches!(bind(cpu), Err(NetError::Unsupported { .. })));
1646        }
1647    }
1648
1649    /// Fast open is off by default on some hosts, and off means refused or ignored,
1650    /// never a broken listener.
1651    #[test]
1652    fn test_fast_open_listener_still_accepts() {
1653        let options = ListenOptions::new().fast_open(Some(16));
1654        if let Ok(l) = TcpListener::bind_with("127.0.0.1:0", options) {
1655            let addr = l.local_addr().unwrap();
1656            let _c = TcpConnection::connect(addr).unwrap();
1657            assert!(l.accept().is_ok());
1658        }
1659    }
1660
1661    #[test]
1662    fn test_user_timeout_where_the_os_has_it() {
1663        let l = TcpListener::bind("127.0.0.1:0").unwrap();
1664        let options = ConnectOptions::new()
1665            .tcp_options(TcpOptions::new().user_timeout(Duration::from_secs(5)));
1666        let c = TcpConnection::connect_with(l.local_addr().unwrap(), options);
1667        if cfg!(any(target_os = "linux", windows)) {
1668            assert!(c.is_ok());
1669        } else {
1670            assert!(matches!(c, Err(NetError::Unsupported { .. })));
1671        }
1672    }
1673
1674    /// A connection whose link is dropped by a panic unwinding past it (no close
1675    /// ran) can no longer be killed: its kill slot ended before its socket closed,
1676    /// so a kill handle kept elsewhere cannot shut down whatever socket the OS gives
1677    /// that descriptor number next.
1678    #[test]
1679    fn test_kill_after_an_unwound_link_is_refused() {
1680        let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
1681        let mut c = TcpConnection::connect(l.local_addr().unwrap()).unwrap();
1682        let (_peer, _) = l.accept().unwrap();
1683        let kill = c.kill_handle();
1684        assert!(kill.is_open());
1685        let link = c.take_link().unwrap();
1686        let unwound = std::panic::catch_unwind(std::panic::AssertUnwindSafe(move || {
1687            let _held = link;
1688            panic!("a bug past every boundary");
1689        }));
1690        assert!(unwound.is_err());
1691        drop(c);
1692        assert!(
1693            !kill.is_open(),
1694            "the slot still holds the closed connection"
1695        );
1696        assert!(
1697            !kill.kill(crate::error::KillReason(9)),
1698            "a kill went through for a closed socket"
1699        );
1700        // Where descriptor numbers are reused lowest first (Unix), the next socket
1701        // may take that number: a stale kill must leave it alone.
1702        let l2 = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
1703        let mut next = std::net::TcpStream::connect(l2.local_addr().unwrap()).unwrap();
1704        let (mut next_peer, _) = l2.accept().unwrap();
1705        assert!(!kill.kill(crate::error::KillReason(9)));
1706        std::io::Write::write_all(&mut next_peer, b"x").unwrap();
1707        next.set_read_timeout(Some(Duration::from_secs(5))).unwrap();
1708        let mut b = [0u8; 1];
1709        assert_eq!(std::io::Read::read(&mut next, &mut b).unwrap(), 1);
1710    }
1711}