carte 0.6.0

Runs your apps' processes on demand behind *.localhost hostnames, one stack per git worktree
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

//! Connections to loopback ports.

use std::io;
use std::net::SocketAddr;
use std::os::fd::AsFd;

use nix::sys::socket::{setsockopt, sockopt};

/// Whether a connection is to itself. On Linux, connecting to a loopback port
/// nobody listens on can succeed when the kernel picks that same port as the
/// source port; that isn't a listener. Such a socket is set to close with a
/// reset, so it doesn't leave the port in TIME_WAIT for the app that binds it.
pub fn connected_to_itself(
    socket: &impl AsFd,
    local: io::Result<SocketAddr>,
    peer: io::Result<SocketAddr>,
) -> bool {
    let (Ok(local), Ok(peer)) = (local, peer) else {
        return false;
    };
    if local != peer {
        return false;
    }
    let reset = nix::libc::linger {
        l_onoff: 1,
        l_linger: 0,
    };
    let _ = setsockopt(socket, sockopt::Linger, &reset);
    true
}

#[cfg(test)]
mod tests {
    use std::net::{Ipv4Addr, TcpListener};
    use std::time::Duration;

    use super::*;

    /// Connects a socket bound to a free port to that same port. Linux allows it;
    /// macOS refuses, and then there is nothing to test.
    async fn self_connection() -> Option<(u16, tokio::net::TcpStream)> {
        let socket = tokio::net::TcpSocket::new_v4().unwrap();
        socket
            .bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
            .unwrap();
        let addr = socket.local_addr().unwrap();
        let port = addr.port();
        let stream = socket.connect(addr).await;
        if cfg!(not(target_os = "linux")) && stream.is_err() {
            return None;
        }
        Some((port, stream.unwrap()))
    }

    #[tokio::test]
    async fn a_connection_to_itself_isnt_a_listener() {
        let Some((_, stream)) = self_connection().await else {
            return;
        };
        assert!(connected_to_itself(
            &stream,
            stream.local_addr(),
            stream.peer_addr()
        ));
    }

    #[tokio::test]
    async fn the_port_is_free_again_once_a_connection_to_itself_is_dropped() {
        let Some((port, stream)) = self_connection().await else {
            return;
        };
        assert!(connected_to_itself(
            &stream,
            stream.local_addr(),
            stream.peer_addr()
        ));
        drop(stream);
        // A child forked by a parallel test can hold the socket for a few
        // milliseconds; a port left in TIME_WAIT would stay taken for a minute.
        let started = std::time::Instant::now();
        loop {
            let socket = tokio::net::TcpSocket::new_v4().unwrap();
            socket.set_reuseaddr(true).unwrap();
            let bound = socket
                .bind(SocketAddr::from((Ipv4Addr::LOCALHOST, port)))
                .and_then(|()| socket.listen(1));
            match bound {
                Ok(_) => break,
                Err(err) if started.elapsed() < Duration::from_secs(2) => {
                    assert_eq!(err.kind(), std::io::ErrorKind::AddrInUse, "{err}");
                    tokio::time::sleep(Duration::from_millis(10)).await;
                }
                Err(err) => panic!("port {port} still taken: {err}"),
            }
        }
    }

    #[test]
    fn other_connections_are_left_alone() {
        let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, 0)).unwrap();
        let stream = std::net::TcpStream::connect(listener.local_addr().unwrap()).unwrap();
        assert!(!connected_to_itself(
            &stream,
            stream.local_addr(),
            stream.peer_addr()
        ));
    }
}