Documentation
¶
Overview ¶
Package testport publishes test containers on host ports below the kernel's ephemeral range, so that rootless Docker under pasta, which forwards only non-ephemeral ports, can reach them. It builds on Linux only, because the reservation depends on how Linux shares a bound port.
Reserve picks such a port and holds it, so that no other test process picks it too. Bind publishes a container on one.
Index ¶
Constants ¶
const ( // ErrCodeNoFreePort is the code reported when no port below the ephemeral range is free. ErrCodeNoFreePort = iota + 1 // ErrCodeReserve is the code reported when a port cannot be reserved for a reason other than // being in use. ErrCodeReserve )
const ErrLayer = "testport"
ErrLayer is the layer that testport errors are reported from.
Variables ¶
var ( // ErrNoFreePort is returned by [Reserve] when every port between 10000 and the start of the // ephemeral range is in use or reserved. ErrNoFreePort = errors.New("no free port below the ephemeral range", ErrLayer, ErrCodeNoFreePort) // ErrReserve is returned by [Reserve], joined with the underlying error, when it cannot draw // the random start of its walk, or when a socket fails for a reason other than the port being // in use, in which case the port is its data. ErrReserve = errors.New("cannot reserve a port", ErrLayer, ErrCodeReserve) )
Functions ¶
func Bind ¶
func Bind(containerPort string) testcontainers.CustomizeRequestOption
Bind publishes containerPort, such as "5432/tcp", on a port from Reserve and releases the reservation once the container terminates. A container that fails to create or start is never terminated, so its reservation stays held until the process exits. The container must expose containerPort, or testcontainers drops the binding. Bind sets a host config modifier, after which testcontainers no longer copies the deprecated host fields of ContainerRequest, such as Binds and NetworkMode, so set those through their options instead. Read the port back with MappedPort.
Types ¶
type Reservation ¶
type Reservation struct {
// contains filtered or unexported fields
}
Reservation holds a host port until Reservation.Release. While held, a bind with SO_REUSEADDR that then listens, as the Docker daemon does when it publishes a port, takes the port, and a bind without SO_REUSEADDR, as Reserve in another process does, fails.
func Reserve ¶
func Reserve() (*Reservation, error)
Reserve holds a TCP port between 10000 and the start of the kernel's ephemeral range, or 32768 when the range cannot be read. It walks the range once from a random port and returns ErrNoFreePort when every port in it is bound or reserved, and ErrReserve when a socket fails for another reason. The reservation holds the port in the caller's network namespace, which is the host's only when the caller shares it, and child processes do not inherit it.
func (*Reservation) Port ¶
func (r *Reservation) Port() string
Port returns the reserved port as a decimal string, the form Docker port bindings and connection strings take.
func (*Reservation) Release ¶
func (r *Reservation) Release() error
Release frees the port for any process to bind. Calls after the first do nothing and return nil.
Source Files