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}