Agent Options - Pion ICE

Overview

Agent options provide a flexible, forward-compatible way to configure ICE agents using the functional options pattern. Each option is a function that modifies agent configuration.

Type Definition

type AgentOption func(*Agent) error

Network Configuration

WithUrls

func WithUrls(urls []*stun.URI) AgentOption

Sets the STUN/TURN server URLs. Can be updated at runtime via UpdateOptions.

stunURL, _ := stun.ParseURI("stun:stun.l.google.com:19302")
agent, _ := ice.NewAgentWithOptions(
    ice.WithUrls([]*stun.URI{stunURL}),
)

turnURL, _ := stun.ParseURI("turn:turn.example.com:3478?transport=udp")
agent, _ := ice.NewAgentWithOptions(
    ice.WithUrls([]*stun.URI{turnURL}),
)

WithPortRange

func WithPortRange(portMin, portMax uint16) AgentOption

Sets the UDP port range for host candidates. Use 0 for both to let the OS choose ports.

agent, _ := ice.NewAgentWithOptions(
    ice.WithPortRange(10000, 20000),
)

WithNetworkTypes

func WithNetworkTypes(networkTypes []NetworkType) AgentOption

Enables specific network types. See NetworkType.

agent, _ := ice.NewAgentWithOptions(
    ice.WithNetworkTypes([]ice.NetworkType{
        ice.NetworkTypeUDP4,
        ice.NetworkTypeUDP6,
    }),
)

WithCandidateTypes

func WithCandidateTypes(candidateTypes []CandidateType) AgentOption

Enables specific candidate types. See CandidateType.

// Only gather host candidates
agent, _ := ice.NewAgentWithOptions(
    ice.WithCandidateTypes([]ice.CandidateType{
        ice.CandidateTypeHost,
    }),
)

Timeout Configuration

WithDisconnectedTimeout

func WithDisconnectedTimeout(timeout time.Duration) AgentOption

Sets duration before transitioning to disconnected state. Use 0 to disable.

agent, _ := ice.NewAgentWithOptions(
    ice.WithDisconnectedTimeout(10 * time.Second),
)

WithFailedTimeout

func WithFailedTimeout(timeout time.Duration) AgentOption

Sets duration after disconnected before transitioning to failed. Use 0 to disable.

WithKeepaliveInterval

func WithKeepaliveInterval(interval time.Duration) AgentOption

Sets how often to send keepalive packets. Use 0 to disable.

WithCheckInterval

func WithCheckInterval(interval time.Duration) AgentOption

Sets how often to run connectivity checks while connecting.

WithSTUNGatherTimeout

func WithSTUNGatherTimeout(timeout time.Duration) AgentOption

Sets STUN server response timeout during gathering.

Candidate Acceptance Timing

WithHostAcceptanceMinWait

func WithHostAcceptanceMinWait(wait time.Duration) AgentOption

Minimum wait before selecting host candidates (default: 0).

WithSrflxAcceptanceMinWait

func WithSrflxAcceptanceMinWait(wait time.Duration) AgentOption

Minimum wait before selecting server reflexive candidates (default: 500ms).

WithPrflxAcceptanceMinWait

func WithPrflxAcceptanceMinWait(wait time.Duration) AgentOption

Minimum wait before selecting peer reflexive candidates (default: 1s).

WithRelayAcceptanceMinWait

func WithRelayAcceptanceMinWait(wait time.Duration) AgentOption

Minimum wait before selecting relay candidates (default: 2s).

Address Rewriting

WithAddressRewriteRules

func WithAddressRewriteRules(rules ...AddressRewriteRule) AgentOption

Adds address rewrite rules for 1:1 NAT mapping. See AddressRewriteRule.

// Replace local address with public IP
agent, _ := ice.NewAgentWithOptions(
    ice.WithAddressRewriteRules(
        ice.AddressRewriteRule{
            External: []string{"203.0.113.10"},
            Local:    "192.168.1.100",
        },
    ),
)

// Different mappings per interface
agent, _ := ice.NewAgentWithOptions(
    ice.WithAddressRewriteRules(
        ice.AddressRewriteRule{
            External: []string{"203.0.113.10"},
            Iface:    "eth0",
        },
        ice.AddressRewriteRule{
            External: []string{"203.0.113.20"},
            Iface:    "eth1",
        },
    ),
)

ICE Configuration

WithICELite

func WithICELite(lite bool) AgentOption

Enables ICE-lite mode. Lite agents only gather host candidates.

agent, _ := ice.NewAgentWithOptions(
    ice.WithICELite(true),
)

WithMaxBindingRequests

func WithMaxBindingRequests(limit uint16) AgentOption

Sets maximum binding requests before marking a pair as failed (default: 7).

WithEnableUseCandidateCheckPriority

func WithEnableUseCandidateCheckPriority() AgentOption

For lite agents, checks priority before switching pairs on USE-CANDIDATE.

Multicast DNS

WithMulticastDNSMode

func WithMulticastDNSMode(mode MulticastDNSMode) AgentOption

Configures mDNS behavior.

agent, _ := ice.NewAgentWithOptions(
    ice.WithMulticastDNSMode(ice.MulticastDNSModeQueryAndGather),
)

WithMulticastDNSHostName

func WithMulticastDNSHostName(hostName string) AgentOption

Sets mDNS hostname (must end with “.local”).

Credentials

WithLocalCredentials

func WithLocalCredentials(ufrag, pwd string) AgentOption

Sets local ICE credentials. Empty strings trigger auto-generation.

Credentials must meet minimum entropy: ufrag >= 24 bits, pwd >= 128 bits.

Renomination

WithRenomination

func WithRenomination(generator NominationValueGenerator) AgentOption

Enables ICE renomination (draft-thatcher-ice-renomination-01).

agent, _ := ice.NewAgentWithOptions(
    ice.WithRenomination(ice.DefaultNominationValueGenerator()),
)

WithNominationAttribute

func WithNominationAttribute(attrType uint16) AgentOption

Sets the STUN attribute type for renomination (default: 0x0030).

WithAutomaticRenomination

func WithAutomaticRenomination(interval time.Duration) AgentOption

Enables automatic renomination when better pairs become available.

agent, _ := ice.NewAgentWithOptions(
    ice.WithRenomination(ice.DefaultNominationValueGenerator()),
    ice.WithAutomaticRenomination(3 * time.Second),
)

Continual Gathering

WithContinualGatheringPolicy

func WithContinualGatheringPolicy(policy ContinualGatheringPolicy) AgentOption

Sets continual gathering behavior.

agent, _ := ice.NewAgentWithOptions(
    ice.WithContinualGatheringPolicy(ice.GatherContinually),
)

WithNetworkMonitorInterval

func WithNetworkMonitorInterval(interval time.Duration) AgentOption

Sets network interface monitoring interval (requires GatherContinually).

TCP Configuration

WithTCPPriorityOffset

func WithTCPPriorityOffset(offset uint16) AgentOption

Value subtracted from TCP candidate priorities (default: 27).

WithDisableActiveTCP

func WithDisableActiveTCP() AgentOption

Disables active TCP candidate creation.

Multiplexing

WithTCPMux

func WithTCPMux(tcpMux TCPMux) AgentOption

Sets TCP multiplexer for ICE-TCP.

WithUDPMux

func WithUDPMux(udpMux UDPMux) AgentOption

Sets UDP multiplexer for host candidates.

WithUDPMuxSrflx

func WithUDPMuxSrflx(udpMuxSrflx UniversalUDPMux) AgentOption

Sets UDP multiplexer for server reflexive candidates.

Filtering

WithInterfaceFilter

func WithInterfaceFilter(filter func(string) bool) AgentOption

Filters network interfaces by name.

// Only use "eth" interfaces
agent, _ := ice.NewAgentWithOptions(
    ice.WithInterfaceFilter(func(name string) bool {
        return strings.HasPrefix(name, "eth")
    }),
)

WithIPFilter

func WithIPFilter(filter func(net.IP) bool) AgentOption

Filters IP addresses during gathering.

WithIncludeLoopback

func WithIncludeLoopback() AgentOption

Includes loopback addresses in candidates.

Advanced Options

WithNet

func WithNet(net transport.Net) AgentOption

Sets custom network implementation (testing/virtual networks).

WithProxyDialer

func WithProxyDialer(dialer proxy.Dialer) AgentOption

Sets proxy dialer for TURN connections.

WithBindingRequestHandler

func WithBindingRequestHandler(
    handler func(m *stun.Message, local, remote Candidate, pair *CandidatePair) bool,
) AgentOption

Sets custom STUN binding request handler.

WithLoggerFactory

func WithLoggerFactory(loggerFactory logging.LoggerFactory) AgentOption

Sets logger factory for structured logging.

Helper Functions

DefaultNominationValueGenerator

func DefaultNominationValueGenerator() NominationValueGenerator

Returns a generator that produces incrementing nomination values starting at 1.

type NominationValueGenerator func() uint32

Agent - Main ICE Agent type
AgentConfig - Legacy configuration struct
AddressRewriteRule - NAT mapping rules

​Overview

​Type Definition

​Network Configuration

​WithUrls

​WithPortRange

​WithNetworkTypes

​WithCandidateTypes

​Timeout Configuration

​WithDisconnectedTimeout

​WithFailedTimeout

​WithKeepaliveInterval

​WithCheckInterval

​WithSTUNGatherTimeout

​Candidate Acceptance Timing

​WithHostAcceptanceMinWait

​WithSrflxAcceptanceMinWait

​WithPrflxAcceptanceMinWait

​WithRelayAcceptanceMinWait

​Address Rewriting

​WithAddressRewriteRules

​ICE Configuration

​WithICELite

​WithMaxBindingRequests

​WithEnableUseCandidateCheckPriority

​Multicast DNS

​WithMulticastDNSMode

​WithMulticastDNSHostName

​Credentials

​WithLocalCredentials

​Renomination

​WithRenomination

​WithNominationAttribute

​WithAutomaticRenomination

​Continual Gathering

​WithContinualGatheringPolicy

​WithNetworkMonitorInterval

​TCP Configuration

​WithTCPPriorityOffset

​WithDisableActiveTCP

​Multiplexing

​WithTCPMux

​WithUDPMux

​WithUDPMuxSrflx

​Filtering

​WithInterfaceFilter

​WithIPFilter

​WithIncludeLoopback

​Advanced Options

​WithNet

​WithProxyDialer

​WithBindingRequestHandler

​WithLoggerFactory

​Helper Functions

​DefaultNominationValueGenerator

​Related

Overview

Type Definition

Network Configuration

WithUrls

WithPortRange

WithNetworkTypes

WithCandidateTypes

Timeout Configuration

WithDisconnectedTimeout

WithFailedTimeout

WithKeepaliveInterval

WithCheckInterval

WithSTUNGatherTimeout

Candidate Acceptance Timing

WithHostAcceptanceMinWait

WithSrflxAcceptanceMinWait

WithPrflxAcceptanceMinWait

WithRelayAcceptanceMinWait

Address Rewriting

WithAddressRewriteRules

ICE Configuration

WithICELite

WithMaxBindingRequests

WithEnableUseCandidateCheckPriority

Multicast DNS

WithMulticastDNSMode

WithMulticastDNSHostName

Credentials

WithLocalCredentials

Renomination

WithRenomination

WithNominationAttribute

WithAutomaticRenomination

Continual Gathering

WithContinualGatheringPolicy

WithNetworkMonitorInterval

TCP Configuration

WithTCPPriorityOffset

WithDisableActiveTCP

Multiplexing

WithTCPMux

WithUDPMux

WithUDPMuxSrflx

Filtering

WithInterfaceFilter

WithIPFilter

WithIncludeLoopback

Advanced Options

WithNet

WithProxyDialer

WithBindingRequestHandler

WithLoggerFactory

Helper Functions

DefaultNominationValueGenerator

Related