heldport

package
v0.20.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

README

internal/testutil/heldport

Overview

Test helper that keeps a test server's TCP port reserved while the server is down, on Linux only. A test can then close a server's listener (its dials are refused, a transient failure for the sync worker) and listen on the same address again. In between, no other server can take the port and answer in its place, except a process of the same user that also sets SO_REUSEPORT and binds that exact port [heldport.go:Listen] [heldport_linux.go:hold]. Off Linux, Listen and Relisten are plain listeners and hold nothing: on macOS a bound socket that does not listen can receive the port's connections, so a held port would stop the server [heldport_other.go:hold].

Interface

  • Listen — listens on a fresh IPv4 loopback port; on Linux it also holds the port until the test ends [heldport.go:Listen]
  • Relisten — listens again on an address that Listen returned [heldport.go:Relisten]

Invariants

  • On Linux, both listeners set SO_REUSEPORT, and a second socket with SO_REUSEPORT stays bound to the port without listening until the test's cleanup [heldport_linux.go:listenControl] [heldport_linux.go:hold]
  • The held socket is close-on-exec, so no child process started after the mark inherits it [heldport_linux.go:hold] [heldport_linux_test.go:TestHeldSocketIsCloseOnExec]
  • ForkLock is held from the socket's creation to that mark, so no child process started in between inherits it either. No test covers this race [heldport_linux.go:hold]
  • On Linux, while no listener is open, a dial to the port is refused, and a socket without SO_REUSEPORT cannot bind it [heldport_linux_test.go:TestRelistenAfterClose]
  • Off Linux, listeners set no socket option and no port is held [heldport_other.go:listenControl] [heldport_other.go:hold]
  • Every setup error fails the test [heldport.go:listen] [heldport_linux.go:hold]

Side Effects

  • On Linux, opens one bound socket per Listen call; the test's cleanup closes it [heldport_linux.go:hold]

Verification

  • Run: go test ./internal/testutil/heldport/... -count=1 -race (the tests run on Linux only)

Documentation

Overview

Package heldport keeps a test server's TCP port reserved while the server is down, on Linux only, so a test can stop a server and start it again on the same address. In between, only a socket that also sets SO_REUSEPORT and binds that exact port, from a process of the same user, can take the port. Elsewhere Listen and Relisten are plain listeners and hold nothing: on macOS a bound socket that does not listen can receive the port's connections (XNU hands a SYN to the first bound socket that matches), so a held port would stop the server.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Listen

func Listen(t testing.TB) net.Listener

Listen listens on a fresh IPv4 loopback port. On Linux it also holds the port until the test ends: after the listener closes, a dial to the port is refused, no socket without SO_REUSEPORT can bind it, and Relisten serves on it again.

func Relisten

func Relisten(t testing.TB, addr string) net.Listener

Relisten listens again on addr, a port that Listen returned.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL