Replace free_port fixture with free_listener to prevent race condition in tests

[sourcery-ai]

There is a potential race condition in the current implementation of the free_port fixture, which is used in both server_runtime.rs and server_runtime_more.rs. The fixture currently binds to a free port and immediately releases it, which can allow another process to claim the port before the test or server setup code does. This can lead to flaky tests or unexpected failures.

Suggested Solution:

• Replace the free_port fixture with a free_listener fixture that returns a bound TcpListener. This keeps the port reserved until the test or server is ready to use it, preventing other processes from claiming the port in the meantime.
• Update all tests and helpers that use free_port() to use free_listener() instead. If only the address is needed, extract it with listener.local_addr().unwrap().
• Where possible, pass the TcpListener directly to the server setup code instead of just the address.

Example Implementation:

#[fixture]
/// Returns a bound TcpListener on a free port for use in tests.
/// This prevents race conditions by keeping the port reserved until the test is ready.
pub fn free_listener() -> std::net::TcpListener {
    let addr = SocketAddr::new(Ipv4Addr::LOCALHOST.into(), 0);
    std::net::TcpListener::bind(addr).expect("Failed to bind to localhost:0")
}

Action Items:

1. Implement the free_listener fixture as shown above.
2. Refactor all usages of free_port in the codebase to use free_listener.
3. Update server setup code to accept a TcpListener where possible.
4. Remove the old free_port fixture once all usages have been migrated.

Let us know if you need further guidance or code examples for the migration!

Issue: #258

---

I created this issue for @leynos from #244 (comment).

Tips and commands

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[leynos]

@coderabbitai looking at the codebase, is this issue still relevant? If the issue has been fixed in the code, does the documentation reflect this?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for free_port fixture definition and usage
echo "=== Searching for free_port fixture ==="
rg "free_port" -A 3 -B 1

echo -e "\n=== Searching for free_listener fixture ==="
rg "free_listener" -A 3 -B 1

echo -e "\n=== Checking if server_runtime.rs exists ==="
fd "server_runtime.rs$" --exec cat {}

echo -e "\n=== Checking if server_runtime_more.rs exists ==="
fd "server_runtime_more.rs$" --exec cat {}

echo -e "\n=== Looking for test fixture documentation ==="
fd "README|TESTING|TEST" -e md --exec grep -l "fixture\|free_port\|free_listener" {} \;

Length of output: 7047

---

🏁 Script executed:

#!/bin/bash
# Get the complete test_util.rs file to see the full context
echo "=== Complete src/server/test_util.rs file ==="
cat src/server/test_util.rs

echo -e "\n=== Check for any recent commits mentioning free_port or race condition ==="
git log --oneline --grep="free_port\|race\|free_listener" -n 10 2>/dev/null || echo "Could not check git history"

echo -e "\n=== Check bind_server implementation to see how free_port is used ==="
ast-grep --pattern 'fn bind_server($$$) {
  $$$
}'

Length of output: 1711

---

@leynos Yes, this issue is still very relevant. The race condition described in the issue still exists in the codebase.

Looking at the current implementation in src/server/test_util.rs:

#[fixture]
pub fn free_port() -> SocketAddr {
    let addr = SocketAddr::new(Ipv4Addr::LOCALHOST.into(), 0);
    let listener = std::net::TcpListener::bind(addr).expect("failed to bind free port listener");
    listener
        .local_addr()
        .expect("failed to read free port listener address")
}

The problem is that the TcpListener is created, its address is extracted, and then it immediately goes out of scope and is dropped. This releases the port back to the OS, creating a window where another process could claim that port before the test actually uses it.

The proposed free_listener fixture has not been implemented, and free_port is still being used extensively throughout the test suite in:

• src/server/connection.rs
• src/server/runtime.rs
• src/server/config/tests.rs

Regarding documentation: There is no documentation about this issue or these test fixtures in any README or testing documentation files.

The fix suggested in the issue would prevent the race condition by keeping the TcpListener alive (and thus the port reserved) until the test is ready to use it. This would make the tests more reliable and eliminate potential flaky test failures.