ice

package module
v0.6.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 22, 2018 License: BSD-3-Clause Imports: 10 Imported by: 0

README

Build Status Master status GoDoc codecov Go Report stability-wip FOSSA Status

ICE

Package ice implements Interactive Connectivity Establishment (ICE) [RFC8445]: A Protocol for Network Address Translator (NAT) Traversal. Complies to gortc principles as core package.

Currently in active development, so no guarantees for API backward compatibility.

Supported RFCs

License

FOSSA Status

Documentation

Overview

Package ice implements RFC 8445 Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Foundation added in v0.6.0 

func Foundation(c *Candidate, serverAddr Addr) []byte

Foundation computes foundation value for candidate. The serverAddr parameter is for STUN or TURN server address, zero value is valid. Will return nil if candidate is nil.

Value is an arbitrary string used in the freezing algorithm to group similar candidates. It is the same for two candidates that have the same type, base IP address, protocol (UDP, TCP, etc.), and STUN or TURN server. If any of these are different, then the foundation will be different.

func Gather added in v0.1.0 

func Gather() ([]gather.Addr, error)

Gather via DefaultGatherer.

func IsHostIPValid added in v0.6.0 

func IsHostIPValid(ip net.IP, ipv6Only bool) bool

IsHostIPValid reports whether ip is valid as host address ip.

func PairPriority added in v0.6.3 

func PairPriority(controlling, controlled int) int64

PairPriority computes Pair Priority as in RFC 8445 Section 6.1.2.3.

func Priority added in v0.5.0 

func Priority(typePref, localPref, componentID int) int

Priority calculates the priority value by RFC 8445 Section 5.1.2.1 formulae.

The typePref value MUST be an integer from 0 (lowest preference) to 126 (highest preference) inclusive, MUST be identical for all candidates of the same type, and MUST be different for candidates of different types.

The localPref value MUST be an integer from 0 (lowest preference) to 65535 (highest preference) inclusive. When there is only a single IP address, this value SHOULD be set to 65535. If there are multiple candidates for a particular component for a particular data stream that have the same type, the local preference MUST be unique for each one. If an ICE agent is dual stack, the local preference SHOULD be set according to the current best practice described in [RFC8421].

The component ID MUST be an integer between 1 and 256 inclusive.

func TypePreference added in v0.6.1 

func TypePreference(t ct.Type) int

TypePreference returns recommended type preference for candidate type.

Types

type Addr 

type Addr struct {
	IP    net.IP
	Port  int
	Proto ct.Protocol
}

Addr represents transport address, the combination of an IP address and the transport protocol (such as UDP or TCP) port.

func (Addr) Equal added in v0.6.0 

func (a Addr) Equal(b Addr) bool

Equal returns true of b equals to a.

func (Addr) String 

func (a Addr) String() string

type AttrControlled added in v0.6.3 

type AttrControlled uint64

AttrControlled represents ICE-CONTROLLED attribute.

func (AttrControlled) AddTo added in v0.6.3 

func (c AttrControlled) AddTo(m *stun.Message) error

AddTo adds ICE-CONTROLLED to message.

func (*AttrControlled) GetFrom added in v0.6.3 

func (c *AttrControlled) GetFrom(m *stun.Message) error

GetFrom decodes ICE-CONTROLLED from message.

type AttrControlling added in v0.6.3 

type AttrControlling uint64

AttrControlling represents ICE-CONTROLLING attribute.

func (AttrControlling) AddTo added in v0.6.3 

func (c AttrControlling) AddTo(m *stun.Message) error

AddTo adds ICE-CONTROLLING to message.

func (*AttrControlling) GetFrom added in v0.6.3 

func (c *AttrControlling) GetFrom(m *stun.Message) error

GetFrom decodes ICE-CONTROLLING from message.

type Candidate 

type Candidate struct {
	Addr        Addr
	Type        ct.Type
	Priority    int
	Foundation  []byte
	Base        Addr
	Related     Addr
	ComponentID int
}

The Candidate is a transport address that is a potential point of contact for receipt of data. Candidates also have properties — their type (server reflexive, relayed, or host), priority, foundation, and base.

func (Candidate) Equal 

func (c Candidate) Equal(b Candidate) bool

Equal reports whether c equals to b.

type Candidates added in v0.6.3 

type Candidates []Candidate

Candidates is list of candidates ordered by priority descending.

func (Candidates) Len added in v0.6.3 

func (c Candidates) Len() int

func (Candidates) Less added in v0.6.3 

func (c Candidates) Less(i, j int) bool

func (Candidates) Swap added in v0.6.3 

func (c Candidates) Swap(i, j int)

type Checklist added in v0.6.3 

type Checklist struct {
	Pairs Pairs
	State ChecklistState
}

Checklist is set of pairs.

From RFC 8455 Section 6.1.2: 

There is one checklist for each data stream.  To form a checklist,
initiating and responding ICE agents form candidate pairs, compute
pair priorities, order pairs by priority, prune pairs, remove lower-
priority pairs, and set checklist states.  If candidates are added to
a checklist (e.g., due to detection of peer-reflexive candidates),
the agent will re-perform these steps for the updated checklist.

func (*Checklist) ComputePriorities added in v0.6.3 

func (c *Checklist) ComputePriorities(role Role)

ComputePriorities computes priorities for all pairs based on agent role.

The role determines whether local candidate is from controlling or from controlled agent.

func (*Checklist) Len added in v0.6.3 

func (c *Checklist) Len() int

Len returns pairs count.

func (*Checklist) Limit added in v0.6.3 

func (c *Checklist) Limit(max int)

Limit ensures maximum length of pairs, removing the pairs with least priority if needed.

func (*Checklist) Order added in v0.6.3 

func (c *Checklist) Order()

Order is ordering pairs by priority descending. First element will have highest priority.

func (*Checklist) Prune added in v0.6.3 

func (c *Checklist) Prune()

Prune removes redundant candidates.

Two candidate pairs are redundant if their local candidates have the same base and their remote candidates are identical

type ChecklistState added in v0.6.3 

type ChecklistState byte

ChecklistState represents the Checklist State.

See RFC 8445 Section 6.1.2.1 

const (
	// ChecklistRunning is neither Completed nor Failed yet. Checklists are
	// initially set to the Running state.
	ChecklistRunning ChecklistState = iota
	// ChecklistCompleted contains a nominated pair for each component of the
	// data stream.
	ChecklistCompleted
	// ChecklistFailed does not have a valid pair for each component of the data
	// stream, and all of the candidate pairs in the checklist are in either the
	// Failed or the Succeeded state. In other words, at least one component of
	// the checklist has candidate pairs that are all in the Failed state, which
	// means the component has failed, which means the checklist has failed.
	ChecklistFailed
)

func (ChecklistState) String added in v0.6.3 

func (s ChecklistState) String() string

type HostAddr added in v0.6.1 

type HostAddr struct {
	IP              net.IP
	LocalPreference int
}

HostAddr wraps IP of host interface and local preference.

func HostAddresses added in v0.6.1 

func HostAddresses(gathered []gather.Addr) ([]HostAddr, error)

HostAddresses returns valid host addresses from gathered addresses with calculated local preference.

When gathered addresses are only IPv6, the host is considered ipv6-only. When there are both IPv6 and IPv4 addresses, the RFC 8421 is used to calculate local preferences.

type Pair added in v0.6.3 

type Pair struct {
	Local    Candidate
	Remote   Candidate
	Priority int64
	State    PairState
}

Pair wraps two candidates, one is local, other is remote.

func (Pair) Foundation added in v0.6.3 

func (p Pair) Foundation() []byte

Foundation is combination of candidates foundations.

type PairState added in v0.6.3 

type PairState byte

PairState as defined in RFC 8445 Section 6.1.2.6. 

const (
	// PairFrozen state: A check for this pair has not been sent, and it cannot
	// be sent until the pair is unfrozen and moved into the Waiting state.
	PairFrozen PairState = iota
	// PairInProgress state: A check has been sent for this pair, but the
	// transaction is in progress.
	PairInProgress
	// PairSucceeded state: A check has been sent for this pair, and it produced
	// a successful result.
	PairSucceeded
	// PairFailed state: A check has been sent for this pair, and it failed (a
	// response to the check was never received, or a failure response was
	// received).
	PairFailed
	// PairWaiting state: A check has not been sent for this pair, but the pair
	// is not Frozen.
	PairWaiting
)

func (PairState) String added in v0.6.3 

func (s PairState) String() string

type Pairs added in v0.6.3 

type Pairs []Pair

Pairs is ordered slice of Pair elements.

func NewPairs added in v0.6.3 

func NewPairs(local, remote Candidates) Pairs

NewPairs pairs each local candidate with each remote candidate for the same component of the same data stream with the same IP address family. Candidates should be sorted by priority in descending order, which is default order for the Candidates type. Populates only Local and Remote fields of Pair.

See RFC 8445 Section 6.1.2.2.

func (Pairs) Len added in v0.6.3 

func (p Pairs) Len() int

func (Pairs) Less added in v0.6.3 

func (p Pairs) Less(i, j int) bool

func (Pairs) Swap added in v0.6.3 

func (p Pairs) Swap(i, j int)

type PriorityAttr added in v0.6.0 

type PriorityAttr uint32

PriorityAttr represents PRIORITY attribute.

func (PriorityAttr) AddTo added in v0.6.0 

func (p PriorityAttr) AddTo(m *stun.Message) error

AddTo adds PRIORITY attribute to message.

func (*PriorityAttr) GetFrom added in v0.6.0 

func (p *PriorityAttr) GetFrom(m *stun.Message) error

GetFrom decodes PRIORITY attribute from message.

type Role added in v0.6.3 

type Role byte

Role represents ICE agent role, which can be controlling or controlled. 

const (
	Controlling Role = iota
	Controlled
)

Possible ICE agent roles.

type State added in v0.6.3 

type State byte

State represents the ICE agent state.

As per RFC 8445 Section 6.1.3, the ICE agent has a state determined by the state of the checklists. The state is Completed if all checklists are Completed, Failed if all checklists are Failed, or Running otherwise. 

const (
	// Running if all checklists are nor completed not failed.
	Running State = iota
	// Completed if all checklists are completed.
	Completed
	// Failed if all checklists are failed.
	Failed
)

func (State) String added in v0.6.3 

func (s State) String() string

type UseCandidateAttr added in v0.5.0 

type UseCandidateAttr struct{}

UseCandidateAttr represents USE-CANDIDATE attribute. 

var UseCandidate UseCandidateAttr

UseCandidate is shorthand for UseCandidateAttr.

func (UseCandidateAttr) AddTo added in v0.5.0 

func (UseCandidateAttr) AddTo(m *stun.Message) error

AddTo adds USE-CANDIDATE attribute to message.

func (UseCandidateAttr) IsSet added in v0.5.0 

func (UseCandidateAttr) IsSet(m *stun.Message) bool

IsSet returns true if USE-CANDIDATE attribute is set.

Source Files

View all Source files

Directories

Path Synopsis
Package candidate contains common types for ice candidate.
 Package candidate contains common types for ice candidate.
cmd
ice-gather
Package sdp implements Session Description Protocol (SDP) Offer/Answer procedures for Interactive Connectivity Establishment (ICE).
 Package sdp implements Session Description Protocol (SDP) Offer/Answer procedures for Interactive Connectivity Establishment (ICE).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.