probe

Documentation

Overview

Package probe runs STUN Binding requests against one or more servers and captures mapping behavior (mapped endpoint, RTT, errors).

Index

• Variables
• type FilteringResult
  • func ProbeFiltering(ctx context.Context, server Server, timeout time.Duration) FilteringResult
• type Prober
  • func NewSTUN() Prober
• type Result
• type Server

Variables

var ErrFilteringNotSupported = errors.New("server did not advertise OTHER-ADDRESS")

ErrFilteringNotSupported is returned in FilteringResult.Err when the target server's BindingResponse does not include an OTHER-ADDRESS attribute, so the §4.4 sequence cannot be attempted.

var ErrTest1Failed = errors.New("initial probe failed; cannot run §4.4 sequence")

ErrTest1Failed wraps the underlying transport / parse error from the initial Binding probe. The §4.4 sequence is skipped when this error is returned.

Types

type FilteringResult

type FilteringResult struct {
	Server        Server
	Test1Mapped   netip.AddrPort
	Test1Other    netip.AddrPort
	Test2Received bool
	Test3Received bool
	Err           error
}

FilteringResult captures the outcome of an RFC 5780 §4.4 three-step filtering classification. Test1Other.IsValid() == false means the server did not advertise OTHER-ADDRESS; in that case Test2Received and Test3Received are both false and Err wraps ErrFilteringNotSupported.

Server is the target of the §4.4 sequence (echoed from the ProbeFiltering argument so consumers can attribute the result without re-threading state).

func ProbeFiltering

func ProbeFiltering(ctx context.Context, server Server, timeout time.Duration) FilteringResult

ProbeFiltering runs RFC 5780 §4.4 against server. Uses one unconnected UDP socket for all three tests so (a) the NAT mapping stays stable across tests and (b) the socket can receive responses from the server's alt-IP/alt-port sources (a connected UDP socket would filter those out). Tests 2/3 are one-shot; "no response within timeout/2" is the verdict, not an error.

ctx governs the initial address resolution only; once resolution completes, per-test SetReadDeadline timers (timeout/2 each) drive the rest. Cancelling ctx mid-call has no effect on in-flight reads.

type Prober

type Prober interface {
	Probe(ctx context.Context, s Server) Result
}

Prober performs one STUN Binding probe per call. Implementations must not panic on bad input and must respect context cancellation.

func NewSTUN

func NewSTUN() Prober

NewSTUN returns a Prober backed by pion/stun over UDP. A fresh UDP socket is opened per probe.

type Result

type Result struct {
	Server Server
	Mapped netip.AddrPort
	Other  netip.AddrPort
	RTT    time.Duration
	Err    error
}

Result captures the outcome of a single probe. On success, Mapped and RTT are set and Err is nil. On failure, Err is non-nil and Mapped/RTT are zero.

Other carries the OTHER-ADDRESS attribute (RFC 5780 §7.4) when the server advertised one. Zero-value (Other.IsValid() == false) means the server's response did not include OTHER-ADDRESS, so it does not support the §4.4 filtering classification sequence.

type Server

type Server struct {
	Host string
	Port int
}

Server identifies a STUN server to probe.