porttrack

Documentation

Overview

Package porttrack provides race-free ephemeral port assignment for subprocess tests. The parent test process creates a Collector that listens on a TCP port; the child process uses Listen which, when given a magic address, binds to localhost:0 and reports the actual port back to the collector.

The magic address format is:

testport-report-LABEL:PORT

where localhost:PORT is the collector's TCP address and LABEL identifies which listener this is (e.g. "main", "plaintext").

When Listen is called with a non-magic address, it falls through to net.Listen with zero overhead beyond a single strings.HasPrefix check.

Index

• func Listen(network, address string) (net.Listener, error)
• type Collector
  • func NewCollector(t testenv.TB) *Collector
  • func (c *Collector) Addr(label string) string
  • func (c *Collector) Port(ctx context.Context, label string) (int, error)

Functions

func Listen

func Listen(network, address string) (net.Listener, error)

Listen is the child/production side of the porttrack protocol.

If address has the magic prefix (as returned by Collector.Addr), Listen binds to localhost:0 on the given network, then TCP-connects to the collector and writes "LABEL\tPORT\n" to report the actual port. The collector connection is closed before returning.

If address does not have the magic prefix, Listen is simply net.Listen(network, address).

Types

type Collector

type Collector struct {
	// contains filtered or unexported fields
}

Collector is the parent/test side of the porttrack protocol. It listens for port reports from child processes that used Listen with a magic address obtained from Collector.Addr.

func NewCollector

func NewCollector(t testenv.TB) *Collector

NewCollector creates a new Collector. The collector's TCP listener is closed when t finishes.

func (*Collector) Addr

func (c *Collector) Addr(label string) string

Addr returns a magic address string that, when passed to Listen, causes the child to bind to localhost:0 and report its actual port back to this collector under the given label.

func (*Collector) Port

func (c *Collector) Port(ctx context.Context, label string) (int, error)

Port blocks until the child process has reported the port for the given label, then returns it. If ctx is cancelled before a port is reported, Port returns the context's cause as an error.