Candidate Gathering

Understanding the ICE candidate gathering process

ICE candidate gathering is the process of discovering and collecting local network addresses that can be used for peer-to-peer communication. This guide covers how gathering works, the different gathering modes, and how to handle candidates.

Starting Candidate Gathering

To begin gathering candidates, call GatherCandidates() after creating an agent:

agent, err := ice.NewAgentWithOptions(
    ice.WithNetworkTypes([]ice.NetworkType{ice.NetworkTypeUDP4}),
)
if err != nil {
    panic(err)
}

// Set candidate handler first
err = agent.OnCandidate(func(c ice.Candidate) {
    if c == nil {
        fmt.Println("Gathering complete")
        return
    }
    fmt.Printf("New candidate: %s\n", c)
})

// Start gathering
err = agent.GatherCandidates()
if err != nil {
    panic(err)
}

You must set the OnCandidate handler before calling GatherCandidates(), otherwise the agent will return ErrNoOnCandidateHandler.

Candidate Types

The ICE agent can gather three types of candidates:

1. Host Candidates

   Local network addresses discovered from your network interfaces. These are gathered by enumerating network interfaces and binding to local ports.

   ice.WithCandidateTypes([]ice.CandidateType{
       ice.CandidateTypeHost,
   })
   
2. Server Reflexive Candidates

   Public addresses discovered by sending STUN binding requests to STUN servers. The server returns your public IP and port as seen from the internet.

   ice.WithCandidateTypes([]ice.CandidateType{
       ice.CandidateTypeServerReflexive,
   })
   
3. Relay Candidates

   Relayed addresses obtained from TURN servers. All traffic flows through the TURN server, ensuring connectivity even through restrictive NATs.

   ice.WithCandidateTypes([]ice.CandidateType{
       ice.CandidateTypeRelay,
   })
   

Gathering Process

The gathering process runs concurrently for all candidate types:

// From gather.go:196
func (a *Agent) gatherCandidatesInternal(ctx context.Context) {
    var wg sync.WaitGroup
    for _, t := range a.candidateTypes {
        switch t {
        case CandidateTypeHost:
            wg.Add(1)
            go func() {
                a.gatherCandidatesLocal(ctx, a.networkTypes)
                wg.Done()
            }()
        case CandidateTypeServerReflexive:
            a.gatherServerReflexiveCandidates(ctx, &wg)
        case CandidateTypeRelay:
            wg.Add(1)
            go func() {
                a.gatherCandidatesRelay(ctx, a.urls)
                wg.Done()
            }()
        }
    }
    wg.Wait()
}

Host Candidate Gathering

Host candidates are gathered by:

1. Enumerating network interfaces
2. Filtering based on interface and IP filters
3. Binding UDP/TCP sockets to local ports
4. Creating candidate objects with priority calculations

// Gather only from specific interfaces
agent, err := ice.NewAgentWithOptions(
    ice.WithInterfaceFilter(func(name string) bool {
        return strings.HasPrefix(name, "eth")
    }),
)

Server Reflexive Gathering

Server reflexive candidates are discovered by:

1. Binding local UDP sockets
2. Sending STUN binding requests to configured STUN servers
3. Receiving XOR-MAPPED-ADDRESS responses
4. Creating srflx candidates with the public address

urls := []*stun.URI{
    {Scheme: stun.SchemeTypeSTUN, Host: "stun.l.google.com", Port: 19302},
}

agent, err := ice.NewAgentWithOptions(
    ice.WithUrls(urls),
    ice.WithSTUNGatherTimeout(5 * time.Second),
)

Relay Candidate Gathering

Relay candidates are obtained by:

1. Connecting to TURN servers via UDP, TCP, TLS, or DTLS
2. Performing TURN allocation
3. Receiving relayed transport address
4. Creating relay candidates

urnURLs := []*stun.URI{
    {Scheme: stun.SchemeTypeTURN, Host: "turn.example.com", Port: 3478,
     Username: "user", Password: "pass"},
}

agent, err := ice.NewAgentWithOptions(
    ice.WithUrls(turnURLs),
)

Gathering States

The gathering process transitions through three states:

1. New - Initial state before gathering starts
2. Gathering - Actively gathering candidates
3. Complete - All gathering finished (in GatherOnce mode)

state, err := agent.GetGatheringState()
fmt.Printf("Gathering state: %s\n", state)

Continual vs Single Gathering

Pion ICE supports two gathering policies:

GatherOnce (Default)

Gathering completes after the initial collection:

agent, err := ice.NewAgentWithOptions(
    ice.WithContinualGatheringPolicy(ice.GatherOnce),
)

The OnCandidate handler receives a nil candidate when gathering completes.

GatherContinually

Continuously monitors network interfaces and gathers new candidates as they appear:

agent, err := ice.NewAgentWithOptions(
    ice.WithContinualGatheringPolicy(ice.GatherContinually),
    ice.WithNetworkMonitorInterval(2 * time.Second),
)

Continual gathering is useful for mobile applications where network interfaces change frequently (switching between WiFi and cellular).

Network Monitoring

With continual gathering, the agent periodically checks for network changes:

// From gather.go:1206
func (a *Agent) startNetworkMonitoring(ctx context.Context) {
    ticker := time.NewTicker(a.networkMonitorInterval)
    defer ticker.Stop()
    
    for {
        select {
        case <-ctx.Done():
            return
        case <-ticker.C:
            if a.detectNetworkChanges() {
                a.gatherCandidatesInternal(ctx)
            }
        }
    }
}

mDNS Candidates

For local network privacy, ICE can use mDNS hostnames instead of IP addresses:

agent, err := ice.NewAgentWithOptions(
    ice.WithMulticastDNSMode(ice.MulticastDNSModeQueryAndGather),
    ice.WithMulticastDNSHostName("device.local"),
)

Multicast DNS Modes

• MulticastDNSModeDisabled - No mDNS support (default)
• MulticastDNSModeQueryOnly - Resolve mDNS candidates from remote peer
• MulticastDNSModeQueryAndGather - Gather and resolve mDNS candidates

When using MulticastDNSModeQueryAndGather, host candidates will advertise .local hostnames instead of IP addresses, hiding location-tracking information.

Handling Candidates

The OnCandidate handler is called for each discovered candidate:

var candidates []ice.Candidate

err = agent.OnCandidate(func(c ice.Candidate) {
    if c == nil {
        // Gathering complete (in GatherOnce mode)
        fmt.Printf("Gathered %d candidates\n", len(candidates))
        return
    }
    
    // New candidate discovered
    candidates = append(candidates, c)
    
    // Send to remote peer via signaling
    sendToRemote(c.Marshal())
})

Location Tracking Prevention

ICE automatically filters certain candidates to prevent location tracking:

// From gather.go:432
func shouldFilterLocationTrackedIP(candidateIP netip.Addr) bool {
    // IPv6 link-local addresses are filtered when using privacy-preserving
    // address generation (RFC 8445 Section 5.1.1.1)
    return candidateIP.Is6() && 
           (candidateIP.IsLinkLocalUnicast() || candidateIP.IsLinkLocalMulticast())
}

Link-local IPv6 addresses are filtered when gathering candidates that use privacy mechanisms.

Example: Continual Gathering

Here’s a complete example demonstrating continual gathering:

import (
    "context"
    "fmt"
    "time"
    "github.com/pion/ice/v4"
)

func main() {
    agent, err := ice.NewAgentWithOptions(
        ice.WithNetworkTypes([]ice.NetworkType{
            ice.NetworkTypeUDP4,
            ice.NetworkTypeUDP6,
        }),
        ice.WithCandidateTypes([]ice.CandidateType{
            ice.CandidateTypeHost,
        }),
        ice.WithContinualGatheringPolicy(ice.GatherContinually),
        ice.WithNetworkMonitorInterval(2 * time.Second),
    )
    if err != nil {
        panic(err)
    }
    defer agent.Close()
    
    // Track candidates
    candidateCount := 0
    err = agent.OnCandidate(func(c ice.Candidate) {
        if c == nil {
            return // No completion signal in continual mode
        }
        candidateCount++
        fmt.Printf("[%d] %s\n", candidateCount, c)
    })
    if err != nil {
        panic(err)
    }
    
    // Start gathering
    err = agent.GatherCandidates()
    if err != nil {
        panic(err)
    }
    
    // Monitor gathering state
    ticker := time.NewTicker(5 * time.Second)
    defer ticker.Stop()
    
    for {
        <-ticker.C
        state, _ := agent.GetGatheringState()
        candidates, _ := agent.GetLocalCandidates()
        fmt.Printf("State: %s, Candidates: %d\n", state, len(candidates))
    }
}

Troubleshooting

No Candidates Gathered

• Verify network types are enabled: WithNetworkTypes()
• Check interface filters aren’t too restrictive
• Enable debug logging to see why interfaces are skipped

STUN/TURN Failures

• Verify server URLs are correct
• Check firewall allows UDP/TCP to STUN/TURN ports
• Increase STUN gather timeout: WithSTUNGatherTimeout(10 * time.Second)
• Check TURN credentials are valid

Gathering Never Completes

• Ensure OnCandidate handler is set before GatherCandidates()
• Check for network connectivity issues
• Review logs for errors during gathering

Next Steps

Connectivity Checks

Learn how ICE performs connectivity checks between candidates

NAT Traversal

Configure address rewriting for NAT traversal

Multiplexing

Share UDP/TCP ports across multiple ICE sessions

Examples

See gathering examples in action