Skip to main content

tpt_port_scout/
lib.rs

1//! RAII TCP/UDP port reservation for parallel integration tests.
2//!
3//! Finding a free port with the classic "bind to `:0`, read the port, drop the
4//! listener, then hand the number to your server" pattern has a
5//! [TOCTOU](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use) race:
6//! between dropping the probe listener and your server binding, another process
7//! (or another parallel test) can grab the same port.
8//!
9//! `tpt-port-scout` closes that window by **keeping the reservation sockets open**
10//! until you are ready to hand them off. A [`PortSet`] binds `N` listeners on
11//! `127.0.0.1:0`, exposes each assigned [`SocketAddr`], and only releases the
12//! kernel reservations when it is dropped — or when you explicitly convert a
13//! listener into a raw handle for your server to reuse.
14//!
15//! # Quick start
16//!
17//! ```
18//! use tpt_port_scout::PortSet;
19//!
20//! // Reserve two free ports; both remain held until `ports` is dropped.
21//! let ports = PortSet::reserve(2).unwrap();
22//! let addr_a = ports.addr(0);
23//! let addr_b = ports.addr(1);
24//! assert_ne!(addr_a.port(), addr_b.port());
25//! ```
26//!
27//! # Handing a port off to a server
28//!
29//! There are two supported patterns:
30//!
31//! 1. **Rebind-before-drop** (portable, works everywhere). Read [`addr`](PortSet::addr),
32//!    then drop the [`PortSet`] immediately before your server binds. The race
33//!    window is as small as possible, but not zero.
34//!
35//! 2. **Zero-race hand-off** (recommended). Convert the reservation listener into
36//!    a raw OS handle with [`PortSet::into_std_listener`] / [`PortSet::take_listener`]
37//!    and let your server adopt the already-bound socket, so the port is *never*
38//!    released. See [`PortSet::take_listener`].
39//!
40//! This crate has **zero runtime dependencies** — pure [`std::net`].
41
42use std::io;
43use std::net::{Ipv4Addr, SocketAddr, TcpListener, UdpSocket};
44
45/// Loopback address used for all reservations.
46const LOOPBACK: Ipv4Addr = Ipv4Addr::LOCALHOST;
47
48/// A set of reserved TCP ports on `127.0.0.1`.
49///
50/// Each reservation is a live [`TcpListener`] bound to an ephemeral port. The
51/// kernel will not reassign those ports to anyone else while the `PortSet` is
52/// alive, so parallel tests can each hold their own non-colliding ports.
53///
54/// Dropping the `PortSet` closes every listener and releases the ports.
55pub struct PortSet {
56    listeners: Vec<Option<TcpListener>>,
57    addrs: Vec<SocketAddr>,
58}
59
60impl PortSet {
61    /// Reserve `n` free TCP ports on `127.0.0.1`.
62    ///
63    /// Returns an error if `n` is `0` or if binding any listener fails.
64    ///
65    /// # Examples
66    ///
67    /// ```
68    /// # use tpt_port_scout::PortSet;
69    /// let ports = PortSet::reserve(3).unwrap();
70    /// assert_eq!(ports.len(), 3);
71    /// ```
72    pub fn reserve(n: usize) -> io::Result<Self> {
73        if n == 0 {
74            return Err(io::Error::new(
75                io::ErrorKind::InvalidInput,
76                "PortSet::reserve requires n >= 1",
77            ));
78        }
79        let mut listeners = Vec::with_capacity(n);
80        let mut addrs = Vec::with_capacity(n);
81        for _ in 0..n {
82            let listener = TcpListener::bind((LOOPBACK, 0))?;
83            let addr = listener.local_addr()?;
84            listeners.push(Some(listener));
85            addrs.push(addr);
86        }
87        Ok(Self { listeners, addrs })
88    }
89
90    /// Reserve a single free TCP port on `127.0.0.1`.
91    ///
92    /// Convenience wrapper around [`PortSet::reserve(1)`](PortSet::reserve).
93    ///
94    /// # Examples
95    ///
96    /// ```
97    /// # use tpt_port_scout::PortSet;
98    /// let port = PortSet::reserve_one().unwrap();
99    /// assert_eq!(port.len(), 1);
100    /// let _addr = port.addr(0);
101    /// ```
102    pub fn reserve_one() -> io::Result<Self> {
103        Self::reserve(1)
104    }
105
106    /// Number of ports held by this set.
107    pub fn len(&self) -> usize {
108        self.addrs.len()
109    }
110
111    /// Returns `true` if this set holds no (live) reservations.
112    ///
113    /// A `PortSet` is only empty after all of its listeners have been taken via
114    /// [`take_listener`](PortSet::take_listener); it is never empty on construction.
115    pub fn is_empty(&self) -> bool {
116        self.listeners.iter().all(|l| l.is_none())
117    }
118
119    /// The [`SocketAddr`] assigned to reservation `i`.
120    ///
121    /// # Panics
122    ///
123    /// Panics if `i` is out of range.
124    ///
125    /// # Examples
126    ///
127    /// ```
128    /// # use tpt_port_scout::PortSet;
129    /// let ports = PortSet::reserve_one().unwrap();
130    /// let addr = ports.addr(0);
131    /// assert!(addr.ip().is_loopback());
132    /// assert_ne!(addr.port(), 0);
133    /// ```
134    pub fn addr(&self, i: usize) -> SocketAddr {
135        self.addrs[i]
136    }
137
138    /// The [`SocketAddr`] assigned to reservation `i`, or `None` if out of range.
139    pub fn try_addr(&self, i: usize) -> Option<SocketAddr> {
140        self.addrs.get(i).copied()
141    }
142
143    /// The port number assigned to reservation `i`.
144    ///
145    /// # Panics
146    ///
147    /// Panics if `i` is out of range.
148    pub fn port(&self, i: usize) -> u16 {
149        self.addrs[i].port()
150    }
151
152    /// All reserved [`SocketAddr`]s, in reservation order.
153    ///
154    /// # Examples
155    ///
156    /// ```
157    /// # use tpt_port_scout::PortSet;
158    /// let ports = PortSet::reserve(2).unwrap();
159    /// let addrs = ports.addrs();
160    /// assert_eq!(addrs.len(), 2);
161    /// ```
162    pub fn addrs(&self) -> &[SocketAddr] {
163        &self.addrs
164    }
165
166    /// Borrow the live [`TcpListener`] for reservation `i`.
167    ///
168    /// Returns `None` if `i` is out of range or the listener has already been
169    /// taken via [`take_listener`](PortSet::take_listener).
170    pub fn listener(&self, i: usize) -> Option<&TcpListener> {
171        self.listeners.get(i).and_then(|l| l.as_ref())
172    }
173
174    /// Take ownership of the reservation listener for index `i` for a **zero-race
175    /// hand-off** to a server.
176    ///
177    /// The returned [`TcpListener`] is the *same* already-bound socket that was
178    /// holding the reservation, so the port is never released between reservation
179    /// and server start-up. Most server frameworks accept a pre-bound
180    /// `std::net::TcpListener` (e.g. `hyper`, `axum::Server::from_tcp`,
181    /// `actix_web::HttpServer::listen`), which makes this completely race-free.
182    ///
183    /// After the listener is taken, [`addr`](PortSet::addr) still returns the
184    /// address, but the reservation for index `i` is no longer held by this set.
185    ///
186    /// Returns `None` if `i` is out of range or the listener was already taken.
187    ///
188    /// # Examples
189    ///
190    /// ```
191    /// # use tpt_port_scout::PortSet;
192    /// let mut ports = PortSet::reserve_one().unwrap();
193    /// let addr = ports.addr(0);
194    /// let listener = ports.take_listener(0).unwrap();
195    /// assert_eq!(listener.local_addr().unwrap(), addr);
196    /// // hand `listener` to your server here — the port was never released.
197    /// ```
198    pub fn take_listener(&mut self, i: usize) -> Option<TcpListener> {
199        self.listeners.get_mut(i).and_then(|slot| slot.take())
200    }
201
202    /// Consume a single-port set and return its underlying [`TcpListener`].
203    ///
204    /// Convenience for the common `reserve_one()` → hand-off flow.
205    ///
206    /// # Errors
207    ///
208    /// Returns an error if the set does not hold exactly one live reservation.
209    ///
210    /// # Examples
211    ///
212    /// ```
213    /// # use tpt_port_scout::PortSet;
214    /// let ports = PortSet::reserve_one().unwrap();
215    /// let listener = ports.into_std_listener().unwrap();
216    /// assert!(listener.local_addr().unwrap().ip().is_loopback());
217    /// ```
218    pub fn into_std_listener(mut self) -> io::Result<TcpListener> {
219        let live: Vec<usize> = self
220            .listeners
221            .iter()
222            .enumerate()
223            .filter_map(|(i, l)| l.as_ref().map(|_| i))
224            .collect();
225        match live.as_slice() {
226            [i] => Ok(self.listeners[*i].take().expect("checked as Some above")),
227            _ => Err(io::Error::new(
228                io::ErrorKind::InvalidInput,
229                format!(
230                    "into_std_listener requires exactly one live reservation, found {}",
231                    live.len()
232                ),
233            )),
234        }
235    }
236}
237
238impl Drop for PortSet {
239    fn drop(&mut self) {
240        // Explicitly release every remaining reservation. Dropping each
241        // `TcpListener` closes its socket and frees the port. Listeners that
242        // were taken via `take_listener` / `into_std_listener` are `None` and
243        // are owned by the caller instead.
244        for slot in self.listeners.iter_mut() {
245            drop(slot.take());
246        }
247    }
248}
249
250impl std::fmt::Debug for PortSet {
251    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
252        f.debug_struct("PortSet")
253            .field("addrs", &self.addrs)
254            .field(
255                "held",
256                &self.listeners.iter().filter(|l| l.is_some()).count(),
257            )
258            .finish()
259    }
260}
261
262/// Reserve a set of free UDP ports on `127.0.0.1`.
263///
264/// UDP counterpart to [`PortSet`]. Each reservation is a bound [`UdpSocket`];
265/// the ports are released on drop.
266pub struct UdpPortSet {
267    sockets: Vec<Option<UdpSocket>>,
268    addrs: Vec<SocketAddr>,
269}
270
271impl UdpPortSet {
272    /// Reserve `n` free UDP ports on `127.0.0.1`.
273    ///
274    /// Returns an error if `n` is `0` or if binding any socket fails.
275    pub fn reserve(n: usize) -> io::Result<Self> {
276        if n == 0 {
277            return Err(io::Error::new(
278                io::ErrorKind::InvalidInput,
279                "UdpPortSet::reserve requires n >= 1",
280            ));
281        }
282        let mut sockets = Vec::with_capacity(n);
283        let mut addrs = Vec::with_capacity(n);
284        for _ in 0..n {
285            let socket = UdpSocket::bind((LOOPBACK, 0))?;
286            let addr = socket.local_addr()?;
287            sockets.push(Some(socket));
288            addrs.push(addr);
289        }
290        Ok(Self { sockets, addrs })
291    }
292
293    /// Reserve a single free UDP port on `127.0.0.1`.
294    pub fn reserve_one() -> io::Result<Self> {
295        Self::reserve(1)
296    }
297
298    /// Number of ports held by this set.
299    pub fn len(&self) -> usize {
300        self.addrs.len()
301    }
302
303    /// Returns `true` if this set holds no live reservations.
304    pub fn is_empty(&self) -> bool {
305        self.sockets.iter().all(|s| s.is_none())
306    }
307
308    /// The [`SocketAddr`] assigned to reservation `i`.
309    ///
310    /// # Panics
311    ///
312    /// Panics if `i` is out of range.
313    pub fn addr(&self, i: usize) -> SocketAddr {
314        self.addrs[i]
315    }
316
317    /// The port number assigned to reservation `i`.
318    ///
319    /// # Panics
320    ///
321    /// Panics if `i` is out of range.
322    pub fn port(&self, i: usize) -> u16 {
323        self.addrs[i].port()
324    }
325
326    /// All reserved [`SocketAddr`]s, in reservation order.
327    pub fn addrs(&self) -> &[SocketAddr] {
328        &self.addrs
329    }
330
331    /// Take ownership of the reservation [`UdpSocket`] for index `i` for a
332    /// zero-race hand-off.
333    pub fn take_socket(&mut self, i: usize) -> Option<UdpSocket> {
334        self.sockets.get_mut(i).and_then(|slot| slot.take())
335    }
336}
337
338impl Drop for UdpPortSet {
339    fn drop(&mut self) {
340        for slot in self.sockets.iter_mut() {
341            drop(slot.take());
342        }
343    }
344}
345
346impl std::fmt::Debug for UdpPortSet {
347    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
348        f.debug_struct("UdpPortSet")
349            .field("addrs", &self.addrs)
350            .field("held", &self.sockets.iter().filter(|s| s.is_some()).count())
351            .finish()
352    }
353}
354
355#[cfg(test)]
356mod tests {
357    use super::*;
358    use std::collections::HashSet;
359    use std::net::TcpStream;
360
361    #[test]
362    fn reserve_one_binds_a_loopback_port() {
363        let ports = PortSet::reserve_one().unwrap();
364        assert_eq!(ports.len(), 1);
365        assert!(!ports.is_empty());
366        let addr = ports.addr(0);
367        assert!(addr.ip().is_loopback());
368        assert_ne!(addr.port(), 0);
369    }
370
371    #[test]
372    fn reserve_zero_is_an_error() {
373        assert!(PortSet::reserve(0).is_err());
374        assert!(UdpPortSet::reserve(0).is_err());
375    }
376
377    #[test]
378    fn reserve_many_yields_distinct_ports() {
379        let ports = PortSet::reserve(16).unwrap();
380        assert_eq!(ports.len(), 16);
381        let unique: HashSet<u16> = ports.addrs().iter().map(|a| a.port()).collect();
382        assert_eq!(unique.len(), 16, "all reserved ports must be distinct");
383    }
384
385    #[test]
386    fn parallel_reservations_do_not_collide() {
387        use std::sync::mpsc;
388        use std::thread;
389
390        let (tx, rx) = mpsc::channel();
391        let mut handles = Vec::new();
392        for _ in 0..8 {
393            let tx = tx.clone();
394            handles.push(thread::spawn(move || {
395                // Hold the reservation while we report it, so the kernel can't
396                // hand the same port to another thread mid-test.
397                let ports = PortSet::reserve(4).unwrap();
398                let assigned: Vec<u16> = ports.addrs().iter().map(|a| a.port()).collect();
399                tx.send((ports, assigned)).unwrap();
400            }));
401        }
402        drop(tx);
403        for h in handles {
404            h.join().unwrap();
405        }
406
407        // Collect while all guards are still alive → no two ports may match.
408        let mut held = Vec::new();
409        let mut all_ports = HashSet::new();
410        while let Ok((guard, assigned)) = rx.recv() {
411            for p in assigned {
412                assert!(
413                    all_ports.insert(p),
414                    "port {p} was reserved twice in parallel"
415                );
416            }
417            held.push(guard);
418        }
419        assert_eq!(all_ports.len(), 8 * 4);
420    }
421
422    #[test]
423    fn reserved_port_actually_accepts_connections() {
424        // The reservation listener is live, so a client can connect to it.
425        let ports = PortSet::reserve_one().unwrap();
426        let addr = ports.addr(0);
427        let listener = ports.listener(0).unwrap();
428        let _client = TcpStream::connect(addr).unwrap();
429        let (accepted, _peer) = listener.accept().unwrap();
430        assert_eq!(accepted.local_addr().unwrap(), addr);
431    }
432
433    #[test]
434    fn take_listener_hands_off_same_socket() {
435        let mut ports = PortSet::reserve_one().unwrap();
436        let addr = ports.addr(0);
437        let listener = ports.take_listener(0).unwrap();
438        assert_eq!(listener.local_addr().unwrap(), addr);
439        // Taken index is now empty; taking again yields None.
440        assert!(ports.take_listener(0).is_none());
441        assert!(ports.is_empty());
442        // The handed-off listener still works.
443        let _client = TcpStream::connect(addr).unwrap();
444        let (_accepted, _peer) = listener.accept().unwrap();
445    }
446
447    #[test]
448    fn into_std_listener_requires_exactly_one() {
449        let single = PortSet::reserve_one().unwrap();
450        assert!(single.into_std_listener().is_ok());
451
452        let many = PortSet::reserve(2).unwrap();
453        assert!(many.into_std_listener().is_err());
454    }
455
456    #[test]
457    fn try_addr_and_out_of_range() {
458        let ports = PortSet::reserve(2).unwrap();
459        assert!(ports.try_addr(0).is_some());
460        assert!(ports.try_addr(2).is_none());
461        assert!(ports.listener(5).is_none());
462    }
463
464    #[test]
465    fn drop_releases_ports_for_reuse() {
466        let addr = {
467            let ports = PortSet::reserve_one().unwrap();
468            ports.addr(0)
469        }; // dropped here → port released
470           // We should now be able to bind that exact port ourselves.
471        let rebound = TcpListener::bind(addr).unwrap();
472        assert_eq!(rebound.local_addr().unwrap().port(), addr.port());
473    }
474
475    #[test]
476    fn udp_reserve_yields_distinct_ports() {
477        let ports = UdpPortSet::reserve(8).unwrap();
478        assert_eq!(ports.len(), 8);
479        let unique: HashSet<u16> = ports.addrs().iter().map(|a| a.port()).collect();
480        assert_eq!(unique.len(), 8);
481        assert!(ports.addr(0).ip().is_loopback());
482    }
483
484    #[test]
485    fn udp_take_socket_hands_off() {
486        let mut ports = UdpPortSet::reserve_one().unwrap();
487        let addr = ports.addr(0);
488        let socket = ports.take_socket(0).unwrap();
489        assert_eq!(socket.local_addr().unwrap(), addr);
490        assert!(ports.is_empty());
491    }
492
493    #[test]
494    fn debug_impl_reports_held_count() {
495        let mut ports = PortSet::reserve(2).unwrap();
496        let dbg = format!("{ports:?}");
497        assert!(dbg.contains("held: 2"));
498        ports.take_listener(0);
499        let dbg = format!("{ports:?}");
500        assert!(dbg.contains("held: 1"));
501    }
502}