ice

Documentation

Overview

Package ice implements RFC 8445 ICE candidate gathering, prioritization, and connectivity-check scaffolding for the HelixCluster NAT-traversal subsystem.

CLAUDE-2 boundary: candidate gathering from REAL local network interfaces is fully exercisable in-process without any STUN or relay server. Functions that require a real STUN or relay server return ErrUnsupported instead of fabricating candidates — per the CLAUDE-2 "no-fake-success" mandate.

Index

• Variables
• func ComputePriority(typePref uint8, localPref uint16, componentID uint16) uint32
• func ConnectivityCheck(_ interface{}, pair CandidatePair) error
• func PairPriority(controlling, controlled uint32) uint64
• func SortPairs(pairs []CandidatePair, localIsControlling bool)
• type Candidate
  • func GatherHostCandidates(port uint16) ([]Candidate, error)
  • func GatherServerReflexive(_ interface{}, stunServer netip.AddrPort) ([]Candidate, error)
• type CandidatePair
• type CandidateType
  • func (ct CandidateType) String() string
  • func (ct CandidateType) TypePreference() uint8

Variables

var ErrUnsupported = errors.New("ice: operation unsupported in this environment (no real STUN/relay available)")

ErrUnsupported is returned by GatherServerReflexive and ConnectivityCheck to signal that the operation cannot be performed without a real STUN server or real network path. It is a distinct sentinel defined in this package; callers MUST test with errors.Is.

Functions

func ComputePriority

func ComputePriority(typePref uint8, localPref uint16, componentID uint16) uint32

ComputePriority computes the RFC 8445 §5.1.2.1 candidate priority:

priority = (2^24) * typePref  +  (2^8) * localPref  +  (256 - componentID)

typePref: 0–126 (candidate type preference, from CandidateType.TypePreference) localPref: 0–65535 (local interface preference; 65535 = highest) componentID: 1–256 (1 = RTP)

func ConnectivityCheck

func ConnectivityCheck(_ interface{}, pair CandidatePair) error

ConnectivityCheck returns ErrUnsupported unconditionally.

RFC 8445 §7 connectivity checks require a live bidirectional network path between peers. No such path is guaranteed to exist in this environment, so fabricating a successful check is FORBIDDEN per CLAUDE-2.

func PairPriority

func PairPriority(controlling, controlled uint32) uint64

PairPriority computes the RFC 8445 §6.1.2.3 pair priority from the controlling and controlled agent's individual candidate priorities:

G = controlling priority, D = controlled priority
pair priority = 2^32 * min(G,D) + 2 * max(G,D) + (G > D ? 1 : 0)

func SortPairs

func SortPairs(pairs []CandidatePair, localIsControlling bool)

SortPairs sorts pairs in-place by descending pair priority (highest first). localIsControlling specifies which candidate priority to pass as the "controlling" argument to PairPriority.

Ties are broken deterministically by Foundation strings (Local then Remote) and finally by address strings to ensure a stable, reproducible order.

Types

type Candidate

type Candidate struct {
	// Type is the candidate category.
	Type CandidateType
	// Addr is the transport address (IP + port) of the candidate.
	Addr netip.AddrPort
	// ComponentID is the RTP/RTCP component identifier (1 for RTP, 2 for RTCP).
	ComponentID uint16
	// Priority is the RFC 8445 §5.1.2.1 candidate priority.
	Priority uint32
	// Foundation is a string identifier shared by candidates gathered from the
	// same base address and via the same gathering technique (RFC 8445 §5.1.1.3).
	Foundation string
}

Candidate is a single ICE candidate as defined by RFC 8445 §5.

func GatherHostCandidates

func GatherHostCandidates(port uint16) ([]Candidate, error)

GatherHostCandidates enumerates REAL local network interface addresses using net.InterfaceAddrs and returns one host Candidate per usable unicast IP.

A usable address is:

• a unicast IP (not multicast, not unspecified, not loopback)
• both IPv4 and IPv6 global-scope addresses are included

Each candidate has ComponentID 1 and a Priority computed with ComputePriority using the host type preference (126) and localPref 65535. The Foundation is derived from the IP address string and candidate type so that candidates from the same interface share a stable foundation.

port is embedded in the Addr field; pass 0 if the port is not yet known.

func GatherServerReflexive

func GatherServerReflexive(_ interface{}, stunServer netip.AddrPort) ([]Candidate, error)

GatherServerReflexive returns ErrUnsupported unconditionally.

Gathering server-reflexive candidates requires a real STUN server reachable over the real network. Because no such server is guaranteed to be present in this environment, fabricating a candidate is FORBIDDEN per CLAUDE-2. Callers that have a real STUN server available should implement this operation themselves using the nattraversal package.

stunServer is accepted for API symmetry but is NOT contacted.

type CandidatePair

type CandidatePair struct {
	// Local is the local candidate contributed by this agent.
	Local Candidate
	// Remote is the remote candidate contributed by the peer.
	Remote Candidate
}

CandidatePair groups a local and a remote Candidate for connectivity checking (RFC 8445 §6.1.2).

type CandidateType

type CandidateType uint8

CandidateType identifies an ICE candidate category as defined by RFC 8445 §5.

const (
	// CandidateHost is a host candidate (address is a local interface address).
	CandidateHost CandidateType = iota
	// CandidateServerReflexive is a server-reflexive candidate (address mapped
	// by a STUN server).
	CandidateServerReflexive
	// CandidatePeerReflexive is a peer-reflexive candidate (address observed in
	// a peer's STUN Binding Request during connectivity checks).
	CandidatePeerReflexive
	// CandidateRelay is a relay candidate (address allocated on a TURN relay).
	CandidateRelay
)

func (CandidateType) String

func (ct CandidateType) String() string

String returns a human-readable label for the CandidateType.

func (CandidateType) TypePreference

func (ct CandidateType) TypePreference() uint8

TypePreference returns the RFC 8445 §5.1.2.1 type preference value for the candidate type. The values are:

host  = 126, prflx = 110, srflx = 100, relay = 0