turn

package module
v2.0.12 Latest Latest
Warning

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

 Go to latest Published: Feb 4, 2022 License: MIT Imports: 21 Imported by: 1

README

Pion TURN
Pion TURN

A toolkit for building TURN clients and servers in Go

Pion TURN Slack Widget
Build Status GoDoc Coverage Status Go Report Card Codacy Badge


Pion TURN is a Go toolkit for building TURN servers and clients. We wrote it to solve problems we had when building RTC projects.

  • Deployable - Use modern tooling of the Go ecosystem. Stop generating config files.
  • Embeddable - Include pion/turn in your existing applications. No need to manage another service.
  • Extendable - TURN as an API so you can easily integrate with your existing monitoring and metrics.
  • Maintainable - pion/turn is simple and well documented. Designed for learning and easy debugging.
  • Portable - Quickly deploy to multiple architectures/platforms just by setting an environment variable.
  • Safe - Stability and safety is important for network services. Go provides everything we need.
  • Scalable - Create allocations and mutate state at runtime. Designed to make scaling easy.

Using

pion/turn is an API for building STUN/TURN clients and servers, not a binary you deploy then configure. It may require copying our examples and making minor modifications to fit your need, no knowledge of Go is required however. You may be able to download the pre-made binaries of our examples if you wish to get started quickly.

The advantage of this is that you don't need to deal with complicated config files, or custom APIs to modify the state of Pion TURN. After you instantiate an instance of a Pion TURN server or client you interact with it like any library. The quickest way to get started is to look at the examples or GoDoc

Examples

We try to cover most common use cases in examples. If more examples could be helpful please file an issue, we are always looking to expand and improve pion/turn to make it easier for developers.

To build any example you just need to run go build in the directory of the example you care about. It is also very easy to cross compile Go programs.

You can also see pion/turn usage in pion/ice

FAQ

RFCs
Implemented
Planned
Community

Pion has an active community on the Golang Slack. Sign up and join the #pion channel for discussions and support.

We are always looking to support your projects. Please reach out if you have something to build!

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible:

License

MIT License - see LICENSE.md for full text

Documentation

Overview

Package turn contains the public API for pion/turn, a toolkit for building TURN clients and servers

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateAuthKey 

func GenerateAuthKey(username, realm, password string) []byte

GenerateAuthKey is a convince function to easily generate keys in the format used by AuthHandler

func GenerateLongTermCredentials 

func GenerateLongTermCredentials(sharedSecret string, duration time.Duration) (string, string, error)

GenerateLongTermCredentials can be used to create credentials valid for [duration] time

Types

type AuthHandler 

type AuthHandler func(username, realm string, srcAddr net.Addr) (key []byte, ok bool)

AuthHandler is a callback used to handle incoming auth requests, allowing users to customize Pion TURN with custom behavior

func NewLongTermAuthHandler 

func NewLongTermAuthHandler(sharedSecret string, l logging.LeveledLogger) AuthHandler

NewLongTermAuthHandler returns a turn.AuthAuthHandler used with Long Term (or Time Windowed) Credentials. https://tools.ietf.org/search/rfc5389#section-10.2

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a STUN server client

func NewClient 

func NewClient(config *ClientConfig) (*Client, error)

NewClient returns a new Client instance. listeningAddress is the address and port to listen on, default "0.0.0.0:0"

func (*Client) Allocate 

func (c *Client) Allocate() (net.PacketConn, error)

Allocate sends a TURN allocation request to the given transport address

func (*Client) Close 

func (c *Client) Close()

Close closes this client

func (*Client) HandleInbound 

func (c *Client) HandleInbound(data []byte, from net.Addr) (bool, error)

HandleInbound handles data received. This method handles incoming packet demultiplex it by the source address and the types of the message. This return a booleen (handled or not) and if there was an error. Caller should check if the packet was handled by this client or not. If not handled, it is assumed that the packet is application data. If an error is returned, the caller should discard the packet regardless.

func (*Client) Listen 

func (c *Client) Listen() error

Listen will have this client start listening on the conn provided via the config. This is optional. If not used, you will need to call HandleInbound method to supply incoming data, instead.

func (*Client) OnDeallocated 

func (c *Client) OnDeallocated(relayedAddr net.Addr)

OnDeallocated is called when deallocation of relay address has been complete. (Called by UDPConn)

func (*Client) PerformTransaction 

func (c *Client) PerformTransaction(msg *stun.Message, to net.Addr, ignoreResult bool) (client.TransactionResult,
	error)

PerformTransaction performs STUN transaction

func (*Client) Realm 

func (c *Client) Realm() stun.Realm

Realm return realm

func (*Client) STUNServerAddr 

func (c *Client) STUNServerAddr() net.Addr

STUNServerAddr return the STUN server address

func (*Client) SendBindingRequest 

func (c *Client) SendBindingRequest() (net.Addr, error)

SendBindingRequest sends a new STUN request to the STUN server

func (*Client) SendBindingRequestTo 

func (c *Client) SendBindingRequestTo(to net.Addr) (net.Addr, error)

SendBindingRequestTo sends a new STUN request to the given transport address

func (*Client) TURNServerAddr 

func (c *Client) TURNServerAddr() net.Addr

TURNServerAddr return the TURN server address

func (*Client) Username 

func (c *Client) Username() stun.Username

Username returns username

func (*Client) WriteTo 

func (c *Client) WriteTo(data []byte, to net.Addr) (int, error)

WriteTo sends data to the specified destination using the base socket.

type ClientConfig 

type ClientConfig struct {
	STUNServerAddr string // STUN server address (e.g. "stun.abc.com:3478")
	TURNServerAddr string // TURN server addrees (e.g. "turn.abc.com:3478")
	Username       string
	Password       string
	Realm          string
	Software       string
	RTO            time.Duration
	Conn           net.PacketConn // Listening socket (net.PacketConn)
	LoggerFactory  logging.LoggerFactory
	Net            *vnet.Net
}

ClientConfig is a bag of config parameters for Client.

type ListenerConfig 

type ListenerConfig struct {
	Listener net.Listener

	// When an allocation is generated the RelayAddressGenerator
	// creates the net.PacketConn and returns the IP/Port it is available at
	RelayAddressGenerator RelayAddressGenerator
}

ListenerConfig is a single net.Listener to accept connections on. This will be used for TCP, TLS and DTLS listeners

type PacketConnConfig 

type PacketConnConfig struct {
	PacketConn net.PacketConn

	// When an allocation is generated the RelayAddressGenerator
	// creates the net.PacketConn and returns the IP/Port it is available at
	RelayAddressGenerator RelayAddressGenerator
}

PacketConnConfig is a single net.PacketConn to listen/write on. This will be used for UDP listeners

type RelayAddressGenerator 

type RelayAddressGenerator interface {
	// Validate confirms that the RelayAddressGenerator is properly initialized
	Validate() error

	// Allocate a PacketConn (UDP) RelayAddress
	AllocatePacketConn(network string, requestedPort int) (net.PacketConn, net.Addr, error)

	// Allocate a Conn (TCP) RelayAddress
	AllocateConn(network string, requestedPort int) (net.Conn, net.Addr, error)
}

RelayAddressGenerator is used to generate a RelayAddress when creating an allocation. You can use one of the provided ones or provide your own.

type RelayAddressGeneratorNone 

type RelayAddressGeneratorNone struct {
	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net *vnet.Net
}

RelayAddressGeneratorNone returns the listener with no modifications

func (*RelayAddressGeneratorNone) AllocateConn 

func (r *RelayAddressGeneratorNone) AllocateConn(network string, requestedPort int) (net.Conn, net.Addr, error)

AllocateConn generates a new Conn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorNone) AllocatePacketConn 

func (r *RelayAddressGeneratorNone) AllocatePacketConn(network string, requestedPort int) (net.PacketConn, net.Addr, error)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorNone) Validate 

func (r *RelayAddressGeneratorNone) Validate() error

Validate is caled on server startup and confirms the RelayAddressGenerator is properly configured

type RelayAddressGeneratorPortRange 

type RelayAddressGeneratorPortRange struct {
	// RelayAddress is the IP returned to the user when the relay is created
	RelayAddress net.IP

	// MinPort the minimum port to allocate
	MinPort uint16
	// MaxPort the maximum (inclusive) port to allocate
	MaxPort uint16

	// MaxRetries the amount of tries to allocate a random port in the defined range
	MaxRetries int

	// Rand the random source of numbers
	Rand randutil.MathRandomGenerator

	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net *vnet.Net
}

RelayAddressGeneratorPortRange can be used to only allocate connections inside a defined port range. Similar to the RelayAddressGeneratorStatic a static ip address can be set.

func (*RelayAddressGeneratorPortRange) AllocateConn 

func (r *RelayAddressGeneratorPortRange) AllocateConn(network string, requestedPort int) (net.Conn, net.Addr, error)

AllocateConn generates a new Conn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorPortRange) AllocatePacketConn 

func (r *RelayAddressGeneratorPortRange) AllocatePacketConn(network string, requestedPort int) (net.PacketConn, net.Addr, error)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorPortRange) Validate 

func (r *RelayAddressGeneratorPortRange) Validate() error

Validate is called on server startup and confirms the RelayAddressGenerator is properly configured

type RelayAddressGeneratorStatic 

type RelayAddressGeneratorStatic struct {
	// RelayAddress is the IP returned to the user when the relay is created
	RelayAddress net.IP

	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net *vnet.Net
}

RelayAddressGeneratorStatic can be used to return static IP address each time a relay is created. This can be used when you have a single static IP address that you want to use

func (*RelayAddressGeneratorStatic) AllocateConn 

func (r *RelayAddressGeneratorStatic) AllocateConn(network string, requestedPort int) (net.Conn, net.Addr, error)

AllocateConn generates a new Conn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorStatic) AllocatePacketConn 

func (r *RelayAddressGeneratorStatic) AllocatePacketConn(network string, requestedPort int) (net.PacketConn, net.Addr, error)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorStatic) Validate 

func (r *RelayAddressGeneratorStatic) Validate() error

Validate is caled on server startup and confirms the RelayAddressGenerator is properly configured

type STUNConn 

type STUNConn struct {
	// contains filtered or unexported fields
}

STUNConn wraps a net.Conn and implements net.PacketConn by being STUN aware and packetizing the stream

func NewSTUNConn 

func NewSTUNConn(nextConn net.Conn) *STUNConn

NewSTUNConn creates a STUNConn

func (*STUNConn) Close 

func (s *STUNConn) Close() error

Close implements Close from net.PacketConn

func (*STUNConn) LocalAddr 

func (s *STUNConn) LocalAddr() net.Addr

LocalAddr implements LocalAddr from net.PacketConn

func (*STUNConn) ReadFrom 

func (s *STUNConn) ReadFrom(p []byte) (n int, addr net.Addr, err error)

ReadFrom implements ReadFrom from net.PacketConn

func (*STUNConn) SetDeadline 

func (s *STUNConn) SetDeadline(t time.Time) error

SetDeadline implements SetDeadline from net.PacketConn

func (*STUNConn) SetReadDeadline 

func (s *STUNConn) SetReadDeadline(t time.Time) error

SetReadDeadline implements SetReadDeadline from net.PacketConn

func (*STUNConn) SetWriteDeadline 

func (s *STUNConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements SetWriteDeadline from net.PacketConn

func (*STUNConn) WriteTo 

func (s *STUNConn) WriteTo(p []byte, addr net.Addr) (n int, err error)

WriteTo implements WriteTo from net.PacketConn

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server is an instance of the Pion TURN Server

func NewServer 

func NewServer(config ServerConfig) (*Server, error)

NewServer creates the Pion TURN server

func (*Server) Close 

func (s *Server) Close() error

Close stops the TURN Server. It cleans up any associated state and closes all connections it is managing

type ServerConfig 

type ServerConfig struct {
	// PacketConnConfigs and ListenerConfigs are a list of all the turn listeners
	// Each listener can have custom behavior around the creation of Relays
	PacketConnConfigs []PacketConnConfig
	ListenerConfigs   []ListenerConfig

	// LoggerFactory must be set for logging from this server.
	LoggerFactory logging.LoggerFactory

	// Realm sets the realm for this server
	Realm string

	// AuthHandler is a callback used to handle incoming auth requests, allowing users to customize Pion TURN with custom behavior
	AuthHandler AuthHandler

	// ChannelBindTimeout sets the lifetime of channel binding. Defaults to 10 minutes.
	ChannelBindTimeout time.Duration

	// Sets the server inbound MTU(Maximum transmition unit). Defaults to 1600 bytes.
	InboundMTU int
}

ServerConfig configures the Pion TURN Server

Source Files

View all Source files

Directories

Path Synopsis
examples
lt-cred-generator
turn-client/tcp
turn-client/udp
turn-server/add-software-attribute
turn-server/log
turn-server/lt-cred
turn-server/port-range
turn-server/simple
turn-server/tcp
turn-server/tls
internal
allocation
Package allocation contains all CRUD operations for allocations
 Package allocation contains all CRUD operations for allocations
client
Package client implements the API for a TURN client
 Package client implements the API for a TURN client
ipnet
Package ipnet contains helper functions around net and IP
 Package ipnet contains helper functions around net and IP
proto
Package proto implements RFC 5766 Traversal Using Relays around NAT.
 Package proto implements RFC 5766 Traversal Using Relays around NAT.
server
Package server implements the private API to implement a TURN server
 Package server implements the private API to implement a TURN server

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.