Documentation ¶
Overview ¶
Package turn implements RFC 5766 Traversal Using Relays around NAT.
Index ¶
- Constants
- Variables
- func IsChannelData(buf []byte) bool
- func ZapChannelNumber(key string, v ChannelNumber) zap.Field
- type Addr
- type Allocation
- type ChannelData
- type ChannelNumber
- type Client
- type ClientOptions
- type Data
- type DontFragmentAttr
- type EvenPort
- type FiveTuple
- type Lifetime
- type PeerAddress
- type Permission
- func (p *Permission) Bind() error
- func (p *Permission) Binding() ChannelNumber
- func (p *Permission) Bound() bool
- func (p *Permission) Close() error
- func (p *Permission) LocalAddr() net.Addr
- func (p *Permission) Read(b []byte) (n int, err error)
- func (p *Permission) RemoteAddr() net.Addr
- func (p *Permission) SetDeadline(t time.Time) error
- func (p *Permission) SetReadDeadline(t time.Time) error
- func (p *Permission) SetWriteDeadline(t time.Time) error
- func (p *Permission) Write(b []byte) (n int, err error)
- type Protocol
- type RelayedAddress
- type RequestedAddressFamily
- type RequestedTransport
- type ReservationToken
- type STUNClient
- type URI
Examples ¶
Constants ¶
const ( // DefaultPort for TURN is same as STUN. DefaultPort = stun.DefaultPort // DefaultTLSPort is for TURN over TLS and is same as STUN. DefaultTLSPort = stun.DefaultTLSPort )
Default ports for TURN from RFC 5766 Section 4.
const ( Scheme = "turn" SchemeSecure = "turns" )
Scheme definitions from RFC 7065 Section 3.2.
const ( TransportTCP = "tcp" TransportUDP = "udp" )
Transport definitions as in RFC 7065.
const DefaultLifetime = time.Minute * 10
DefaultLifetime in RFC 5766 is 10 minutes.
Variables ¶
var ( // ErrAlreadyBound means that selected permission already has bound channel number. ErrAlreadyBound = errors.New("channel already bound") // ErrNotBound means that selected permission already has no channel number. ErrNotBound = errors.New("channel is not bound") )
var ( // AllocateRequest is shorthand for allocation request message type. AllocateRequest = stun.NewType(stun.MethodAllocate, stun.ClassRequest) // CreatePermissionRequest is shorthand for create permission request type. CreatePermissionRequest = stun.NewType(stun.MethodCreatePermission, stun.ClassRequest) // SendIndication is shorthand for send indication message type. SendIndication = stun.NewType(stun.MethodSend, stun.ClassIndication) // RefreshRequest is shorthand for refresh request message type. RefreshRequest = stun.NewType(stun.MethodRefresh, stun.ClassRequest) )
var ErrBadChannelDataLength = errors.New("channelData length != len(Data)")
ErrBadChannelDataLength means that channel data length is not equal to actual data length.
var ErrInvalidChannelNumber = errors.New("channel number not in [0x4000, 0x7FFF]")
ErrInvalidChannelNumber means that channel number is not valid as by RFC 5766 Section 11.
var ErrNotImplemented = errors.New("functionality not implemented")
ErrNotImplemented means that functionality is not currently implemented, but it will be (eventually).
var RequestedTransportUDP stun.Setter = RequestedTransport{ Protocol: ProtoUDP, }
RequestedTransportUDP is setter for requested transport attribute with value ProtoUDP (17).
var ZeroLifetime stun.Setter = Lifetime{}
ZeroLifetime is shorthand for setting zero lifetime that indicates to close allocation.
Functions ¶
func IsChannelData ¶ added in v0.2.1
IsChannelData returns true if buf looks like the ChannelData Message.
func ZapChannelNumber ¶ added in v0.4.6
func ZapChannelNumber(key string, v ChannelNumber) zap.Field
ZapChannelNumber returns zap.Field for ChannelNumber.
Types ¶
type Addr ¶ added in v0.4.0
Addr is ip:port.
func (*Addr) FromUDPAddr ¶ added in v0.4.0
FromUDPAddr sets addr to UDPAddr.
type Allocation ¶ added in v0.4.0
type Allocation struct {
// contains filtered or unexported fields
}
Allocation reflects TURN Allocation.
func (*Allocation) Create ¶ added in v0.4.1
func (a *Allocation) Create(peer net.Addr) (*Permission, error)
Create creates new permission to peer.
func (*Allocation) CreateUDP ¶ added in v0.4.0
func (a *Allocation) CreateUDP(addr *net.UDPAddr) (*Permission, error)
CreateUDP creates new UDP Permission to peer with provided addr.
type ChannelData ¶ added in v0.2.1
type ChannelData struct { Data []byte // can be subslice of Raw Length int // ignored while encoding, len(Data) is used Padding bool // use padding Number ChannelNumber Raw []byte }
ChannelData represents The ChannelData Message.
func (*ChannelData) Decode ¶ added in v0.2.1
func (c *ChannelData) Decode() error
Decode decodes The ChannelData Message from Raw.
func (*ChannelData) Encode ¶ added in v0.2.1
func (c *ChannelData) Encode()
Encode encodes ChannelData Message to Raw.
func (*ChannelData) Equal ¶ added in v0.2.1
func (c *ChannelData) Equal(b *ChannelData) bool
Equal returns true if b == c.
func (*ChannelData) Reset ¶ added in v0.2.1
func (c *ChannelData) Reset()
Reset resets Length, Data and Raw length.
func (*ChannelData) WriteHeader ¶ added in v0.2.1
func (c *ChannelData) WriteHeader()
WriteHeader writes channel number and length.
type ChannelNumber ¶
type ChannelNumber int // encoded as uint16
ChannelNumber represents CHANNEL-NUMBER attribute.
The CHANNEL-NUMBER attribute contains the number of the channel.
func (ChannelNumber) AddTo ¶
func (n ChannelNumber) AddTo(m *stun.Message) error
AddTo adds CHANNEL-NUMBER to message.
func (*ChannelNumber) GetFrom ¶
func (n *ChannelNumber) GetFrom(m *stun.Message) error
GetFrom decodes CHANNEL-NUMBER from message.
func (ChannelNumber) String ¶
func (n ChannelNumber) String() string
func (ChannelNumber) Valid ¶ added in v0.2.3
func (n ChannelNumber) Valid() bool
Valid returns true if channel number has correct value that complies RFC 5766 Section 11 range.
type Client ¶ added in v0.4.0
type Client struct {
// contains filtered or unexported fields
}
Client for TURN server.
Provides transparent net.Conn interfaces to remote peers.
func NewClient ¶ added in v0.4.0
func NewClient(o ClientOptions) (*Client, error)
NewClient creates and initializes new TURN client.
func (*Client) Allocate ¶ added in v0.4.0
func (c *Client) Allocate() (*Allocation, error)
Allocate creates an allocation for current 5-tuple. Currently there can be only one allocation per client, because client wraps one net.Conn.
func (*Client) RefreshRate ¶ added in v0.6.2
RefreshRate returns current rate of refresh requests.
type ClientOptions ¶ added in v0.4.0
type ClientOptions struct { Conn net.Conn STUN STUNClient // optional STUN client Log *zap.Logger // defaults to Nop // Long-term integrity. Username string Password string // STUN client options. RTO time.Duration NoRetransmit bool // TURN options. RefreshRate time.Duration RefreshDisabled bool }
ClientOptions contains available config for TURN client.
type Data ¶
type Data []byte
Data represents DATA attribute.
The DATA attribute is present in all Send and Data indications. The value portion of this attribute is variable length and consists of the application data (that is, the data that would immediately follow the UDP header if the data was been sent directly between the client and the peer).
type DontFragmentAttr ¶
type DontFragmentAttr struct{}
DontFragmentAttr represents DONT-FRAGMENT attribute.
var DontFragment DontFragmentAttr
DontFragment is shorthand for DontFragmentAttr.
type EvenPort ¶
type EvenPort struct { // ReservePort means that the server is requested to reserve // the next-higher port number (on the same IP address) // for a subsequent allocation. ReservePort bool }
EvenPort represents EVEN-PORT attribute.
This attribute allows the client to request that the port in the relayed transport address be even, and (optionally) that the server reserve the next-higher port number.
type FiveTuple ¶ added in v0.4.0
FiveTuple represents 5-TUPLE value.
type Lifetime ¶
Lifetime represents LIFETIME attribute.
The LIFETIME attribute represents the duration for which the server will maintain an allocation in the absence of a refresh. The value portion of this attribute is 4-bytes long and consists of a 32-bit unsigned integral value representing the number of seconds remaining until expiration.
Example ¶
// Encoding lifetime to message. m := new(stun.Message) Lifetime{time.Minute}.AddTo(m) m.WriteHeader() // Decoding message. mDec := new(stun.Message) if _, err := m.WriteTo(mDec); err != nil { panic(err) } // Decoding lifetime from message. l := Lifetime{} l.GetFrom(m) fmt.Println("Decoded:", l)
Output: Decoded: 1m0s
type PeerAddress ¶
PeerAddress implements XOR-PEER-ADDRESS attribute.
The XOR-PEER-ADDRESS specifies the address and port of the peer as seen from the TURN server. (For example, the peer's server-reflexive transport address if the peer is behind a NAT.)
func (PeerAddress) AddTo ¶
func (a PeerAddress) AddTo(m *stun.Message) error
AddTo adds XOR-PEER-ADDRESS to message.
func (*PeerAddress) GetFrom ¶
func (a *PeerAddress) GetFrom(m *stun.Message) error
GetFrom decodes XOR-PEER-ADDRESS from message.
func (PeerAddress) String ¶
func (a PeerAddress) String() string
type Permission ¶ added in v0.4.0
type Permission struct {
// contains filtered or unexported fields
}
Permission implements net.PacketConn.
func (*Permission) Bind ¶ added in v0.4.0
func (p *Permission) Bind() error
Bind performs binding transaction, allocating channel binding for the permission.
func (*Permission) Binding ¶ added in v0.4.0
func (p *Permission) Binding() ChannelNumber
Binding returns current channel number or 0 if not bound.
func (*Permission) Bound ¶ added in v0.4.0
func (p *Permission) Bound() bool
Bound returns true if channel number is bound for current permission.
func (*Permission) Close ¶ added in v0.4.0
func (p *Permission) Close() error
Close stops all refreshing loops for permission and removes it from allocation.
func (*Permission) LocalAddr ¶ added in v0.4.0
func (p *Permission) LocalAddr() net.Addr
LocalAddr is relayed address from TURN server.
func (*Permission) Read ¶ added in v0.4.0
func (p *Permission) Read(b []byte) (n int, err error)
Read data from peer.
func (*Permission) RemoteAddr ¶ added in v0.4.0
func (p *Permission) RemoteAddr() net.Addr
RemoteAddr is peer address.
func (*Permission) SetDeadline ¶ added in v0.4.0
func (p *Permission) SetDeadline(t time.Time) error
SetDeadline implements net.Conn.
func (*Permission) SetReadDeadline ¶ added in v0.4.0
func (p *Permission) SetReadDeadline(t time.Time) error
SetReadDeadline implements net.Conn.
func (*Permission) SetWriteDeadline ¶ added in v0.4.0
func (p *Permission) SetWriteDeadline(t time.Time) error
SetWriteDeadline implements net.Conn.
type Protocol ¶
type Protocol byte
Protocol is IANA assigned protocol number.
const ( // ProtoUDP is IANA assigned protocol number for UDP. ProtoUDP Protocol = 17 )
type RelayedAddress ¶
RelayedAddress implements XOR-RELAYED-ADDRESS attribute.
The XOR-PEER-ADDRESS specifies the address and port of the peer as seen from the TURN server. (For example, the peer's server-reflexive transport address if the peer is behind a NAT.)
func (RelayedAddress) AddTo ¶
func (a RelayedAddress) AddTo(m *stun.Message) error
AddTo adds XOR-PEER-ADDRESS to message.
func (*RelayedAddress) GetFrom ¶
func (a *RelayedAddress) GetFrom(m *stun.Message) error
GetFrom decodes XOR-PEER-ADDRESS from message.
func (RelayedAddress) String ¶
func (a RelayedAddress) String() string
type RequestedAddressFamily ¶ added in v0.5.3
type RequestedAddressFamily byte
RequestedAddressFamily represents the REQUESTED-ADDRESS-FAMILY Attribute as defined in RFC 6156 Section 4.1.1.
const ( RequestedFamilyIPv4 RequestedAddressFamily = 0x01 RequestedFamilyIPv6 RequestedAddressFamily = 0x02 )
Values for RequestedAddressFamily as defined in RFC 6156 Section 4.1.1.
func (RequestedAddressFamily) AddTo ¶ added in v0.5.3
func (f RequestedAddressFamily) AddTo(m *stun.Message) error
AddTo adds REQUESTED-ADDRESS-FAMILY to message.
func (*RequestedAddressFamily) GetFrom ¶ added in v0.5.3
func (f *RequestedAddressFamily) GetFrom(m *stun.Message) error
GetFrom decodes REQUESTED-ADDRESS-FAMILY from message.
func (RequestedAddressFamily) String ¶ added in v0.5.3
func (f RequestedAddressFamily) String() string
type RequestedTransport ¶
type RequestedTransport struct {
Protocol Protocol
}
RequestedTransport represents REQUESTED-TRANSPORT attribute.
This attribute is used by the client to request a specific transport protocol for the allocated transport address. RFC 5766 only allows the use of codepoint 17 (User Datagram Protocol).
func (RequestedTransport) AddTo ¶
func (t RequestedTransport) AddTo(m *stun.Message) error
AddTo adds REQUESTED-TRANSPORT to message.
func (*RequestedTransport) GetFrom ¶
func (t *RequestedTransport) GetFrom(m *stun.Message) error
GetFrom decodes REQUESTED-TRANSPORT from message.
func (RequestedTransport) String ¶
func (t RequestedTransport) String() string
type ReservationToken ¶
type ReservationToken []byte
ReservationToken represents RESERVATION-TOKEN attribute.
The RESERVATION-TOKEN attribute contains a token that uniquely identifies a relayed transport address being held in reserve by the server. The server includes this attribute in a success response to tell the client about the token, and the client includes this attribute in a subsequent Allocate request to request the server use that relayed transport address for the allocation.