port_check

port_check is a small, focused Rust library for two common networking chores: finding a free local port to bind to, and checking whether a remote or local port is reachable. It supports both IPv4 and IPv6, lets you constrain the search to a port range, and offers timeout-controlled reachability checks.

Because a port that looks free at check time may be taken by the time you use it, port_check also ships a retry-based with_free_port helper that repeatedly acquires a candidate port and hands it to your closure until binding succeeds, mitigating time-of-check to time-of-use races.

What You Get

• Functions to find a free local port, optionally within a bounded range
• IPv4 and IPv6 support across all port checks
• Reachability checks for remote and local ports, with optional timeouts
• A with_free_port retry helper that mitigates time-of-check to time-of-use races
• A tiny, dependency-light API that drops into any Rust project

Common Use Cases

• Picking a free port to bind a test server or spawned service to
• Waiting for a dependent service’s port to become reachable in integration tests
• Allocating ephemeral ports in a constrained range for local tooling
• Reliably binding to a port using retry logic to avoid race conditions

Under The Hood

Architecture - The entire library lives in a single src/lib.rs (~760 lines including tests) that wraps Rust’s standard std::net primitives. Free-port discovery binds a TcpListener to port 0 and reads back the OS-assigned port; reachability checks attempt a TcpStream connection, optionally with a timeout. A Port type distinguishes IPv4 and IPv6 targets, and with_free_port wraps the discovery-plus-bind cycle in a retry loop.

Tech Stack - Pure Rust on the 2024 edition with zero runtime dependencies, relying entirely on the standard library’s networking types. The only dev-dependency is serial_test, used to serialize port-binding tests.

Code Quality - The crate is well-tested with an inline test module and CI running build, test, and coverage (codecov) badges. Documentation is thorough, including runnable examples in the README and an explicit note about TOCTOU semantics, showing care for correctness despite the library’s small size.

API Design - The public API is deliberately minimal and self-descriptive: free_local_port(), free_local_port_in_range(), is_port_reachable(), and IPv6 variants read naturally at the call site. The retry-based with_free_port closure form is the main abstraction requiring a moment to learn, keeping the overall learning curve very low.