transportc

README

TranspoRTC

A ready-to-go pluggable transport utilizing WebRTC datachannel written in Go.

Design

Config

A Config defines the behavior of the transport. A Config could be used to configure:

• Automatic signalling when establishing the PeerConnection
• IP addresses to be used for ICE candidates
• Port range for ICE candidates
• UDP Mux for serving multiple connections over one UDP socket

Dialer

A Dialer is created from a Config and is used to dial one or more Conn backed by WebRTC DataChannel.

On its first call to Dial, the Dialer will create a new PeerConnection and DataChannel. On subsequent calls, the Dialer will reuse the existing PeerConnection and DataChannel.

Listener

A Listener is created from a Config and is used to listen for incoming Conn backed by WebRTC DataChannel. It looks for incoming SDP offers to establish new PeerConnections and also looks for incoming DataChannels on existing PeerConnections.

One Listener can maintain multiple PeerConnections and on each PeerConnection multiple DataChannels may co-exist.

A Listener requires a valid SignalMethod to function.

Conn

A Conn is created from a Dialer and is used to send and receive messages. Each Conn is backed by a single WebRTC DataChannel.

Documentation

Index

• Constants
• type Config
  • func (c *Config) BuildSettingEngine() (webrtc.SettingEngine, error)
  • func (c *Config) NewDialer(pConf *webrtc.Configuration) (*Dialer, error)
  • func (c *Config) NewListener(pConf *webrtc.Configuration) (*Listener, error)
• type Conn
  • func (c *Conn) Close() error
  • func (*Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(p []byte) (int, error)
  • func (*Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(deadline time.Time) error
  • func (c *Conn) SetReadDeadline(deadline time.Time) error
  • func (c *Conn) SetWriteDeadline(deadline time.Time) error
  • func (c *Conn) Write(p []byte) (int, error)
• type DTLSRole
• type DebugSignal
  • func NewDebugSignal(bufferSize int) *DebugSignal
  • func (ds *DebugSignal) Answer(answer []byte) error
  • func (ds *DebugSignal) GetAnswer() ([]byte, error)
  • func (ds *DebugSignal) GetOffer() ([]byte, error)
  • func (ds *DebugSignal) MakeOffer(offer []byte) error
• type Dialer
  • func (d *Dialer) Close() error
  • func (d *Dialer) CreateOffer(ctx context.Context) error
  • func (d *Dialer) Dial(label string) (net.Conn, error)
  • func (d *Dialer) DialContext(ctx context.Context, label string) (net.Conn, error)
  • func (d *Dialer) GetOffer() ([]byte, error)
  • func (d *Dialer) SetAnswer(answer []byte) error
• type Listener
  • func (l *Listener) Accept() (net.Conn, error)
  • func (l *Listener) Start() error
  • func (l *Listener) Stop() error
  • func (l *Listener) Suspend() error
• type ListenerRunningStatus
• type NAT1To1IPs
• type PortRange
• type SignalMethod

Constants

const (
	MTU_DEFAULT              = 1024
	MAX_RECV_TIMEOUT_DEFAULT = time.Second * 10
)

Types

type Config

type Config struct {
	// ListenerDTLSRole defines the DTLS role when Listening.
	// MUST be either DTLSRoleClient or DTLSRoleServer, as defined in RFC4347
	// DTLSRoleClient will send the ClientHello and start the handshake.
	// DTLSRoleServer will wait for the ClientHello.
	ListenerDTLSRole DTLSRole

	/**** OPTIONAL FIELDS ****/
	// SignalMethod offers the automatic signaling when establishing the DataChannel.
	SignalMethod SignalMethod

	// IPs includes a slice of IP addresses and one single ICE Candidate Type.
	// If set, will add these IPs as ICE Candidates
	IPs *NAT1To1IPs

	// PortRange is the range of ports to use for the DataChannel.
	PortRange *PortRange

	// UDPMux allows serving multiple DataChannels over the one or more pre-established UDP socket.
	UDPMux ice.UDPMux

	// CandidateNetworkTypes restricts ICE agent to gather
	// on only selected types of networks.
	CandidateNetworkTypes []webrtc.NetworkType

	// InterfaceFilter restricts ICE agent to gather ICE candidates
	// on only selected interfaces.
	InterfaceFilter func(interfaceName string) (allowed bool)
}

Config is the configuration for the Dialer and Listener.

func (*Config) BuildSettingEngine

func (c *Config) BuildSettingEngine() (webrtc.SettingEngine, error)

BuildSettingEngine builds a SettingEngine from the configuration.

func (*Config) NewDialer

func (c *Config) NewDialer(pConf *webrtc.Configuration) (*Dialer, error)

NewDialer creates a new Dialer from the given configuration.

func (*Config) NewListener

func (c *Config) NewListener(pConf *webrtc.Configuration) (*Listener, error)

NewListener creates a new Listener from the given configuration.

type Conn

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

Conn is a net.Conn implementation for WebRTC DataChannels.

func (*Conn) Close

func (c *Conn) Close() error

Close implements the net.Conn Close method.

func (*Conn) LocalAddr

func (*Conn) LocalAddr() net.Addr

LocalAddr implements the net.Conn LocalAddr method.

It is hardcoded to return nil since WebRTC DataChannels are P2P and Local addresses are therefore trivial.

func (*Conn) Read

func (c *Conn) Read(p []byte) (int, error)

Read implements the net.Conn Read method.

func (*Conn) RemoteAddr

func (*Conn) RemoteAddr() net.Addr

RemoteAddr implements the net.Conn RemoteAddr method.

It is hardcoded to return nil since WebRTC DataChannels are P2P and Remote addresses are therefore trivial.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(deadline time.Time) error

SetDeadline implements the net.Conn SetDeadline method. It sets both read and write deadlines in a single call.

See SetReadDeadline and SetWriteDeadline for the behavior of the deadlines.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(deadline time.Time) error

SetReadDeadline sets the deadline for future Read calls.

A Read call will fail and return os.ErrDeadlineExceeded before attempting to read from the buffer if the deadline has passed. And a Read call will block till no later than the set read deadline.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(deadline time.Time) error

SetWriteDeadline sets the deadline for future Write calls.

A Write call will fail and return os.ErrDeadlineExceeded before attempting to write to the buffer if the deadline has passed. Otherwise the set write deadline will not affect the WriteTo call.

func (*Conn) Write

func (c *Conn) Write(p []byte) (int, error)

Write implements the net.Conn Write method. If the size of the buffer is greater than the MTU, the data could still be sent but will be fragmented (not recommended).

type DTLSRole

type DTLSRole = webrtc.DTLSRole

RFC 4347

const (
	// DTLSRoleAuto defines the DTLS role is determined based on
	// the resolved ICE role: the ICE controlled role acts as the DTLS
	// client and the ICE controlling role acts as the DTLS server.
	DTLSRoleAuto DTLSRole = iota + 1

	// DTLSRoleClient defines the DTLS client role.
	DTLSRoleClient

	// DTLSRoleServer defines the DTLS server role.
	DTLSRoleServer
)

From pion/webrtc

type DebugSignal

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

IOSignal implements a minimalistic signaling method. Offerer's writer should write to the answerer's reader and vice versa.

func NewDebugSignal

func NewDebugSignal(bufferSize int) *DebugSignal

NewDebugSignal creates a new DebugSignal.

func (*DebugSignal) Answer

func (ds *DebugSignal) Answer(answer []byte) error

Answer implements SignalMethod.Answer. It writes the SDP answer to answers channel.

func (*DebugSignal) GetAnswer

func (ds *DebugSignal) GetAnswer() ([]byte, error)

GetAnswer implements SignalMethod.GetAnswer It reads the SDP answer from answers channel.

func (*DebugSignal) GetOffer

func (ds *DebugSignal) GetOffer() ([]byte, error)

GetOffer implements SignalMethod.GetOffer It reads the SDP offer from offers channel.

func (*DebugSignal) MakeOffer

func (ds *DebugSignal) MakeOffer(offer []byte) error

MakeOffer implements SignalMethod.MakeOffer. It writes the SDP offer to offers channel.

type Dialer

type Dialer struct {
	SignalMethod SignalMethod
	MTU          int // maximum transmission unit
	// contains filtered or unexported fields
}

Dialer can dial a remote peer.

If the SignalMethod is set, the Offer/Answer exchange per new PeerConnection will be done automatically.

func (*Dialer) Close

func (d *Dialer) Close() error

Close closes the WebRTC PeerConnection and with it all the WebRTC DataChannels under it.

SHOULD be called when done using the transport.

func (*Dialer) CreateOffer

func (d *Dialer) CreateOffer(ctx context.Context) error

CreateOffer creates a local offer and sets it as the local description.

Automatically called by NewPeerConction when SignalMethod is set.

func (*Dialer) Dial

func (d *Dialer) Dial(label string) (net.Conn, error)

Dial connects to a remote peer with SDP-based negotiation.

Internally calls DialContext with context.Background().

The returned connection is backed by a DataChannel created by the caller with the SDP role as OFFERER as defined in RFC3264. If SignalMethod is set, the Offer/Answer exchange per new PeerConnection will be done automatically. Otherwise, it is recommended to call NewPeerConnection and exchange the SDP offer/answer manually before dialing.

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context, label string) (net.Conn, error)

DialContext connects to a remote peer with SDP-based negotiation using the provided context.

The provided Context must be non-nil. If the context expires before the connection is complete, an error is returned. Once successfully connected, any expiration of the context will not affect the connection.

The returned connection is backed by a DataChannel created by the caller with the SDP role as OFFERER as defined in RFC3264. If SignalMethod is set, the Offer/Answer exchange per new PeerConnection will be done automatically. Otherwise, it is recommended to call NewPeerConnection and exchange the SDP offer/answer manually before dialing.

func (*Dialer) GetOffer

func (d *Dialer) GetOffer() ([]byte, error)

GetOffer returns the local offer.

Automatically called by NewPeerConction when SignalMethod is set.

func (*Dialer) SetAnswer

func (d *Dialer) SetAnswer(answer []byte) error

SetAnswer sets the remote answer.

Automatically called by NewPeerConction when SignalMethod is set.

type Listener

type Listener struct {
	SignalMethod     SignalMethod
	MTU              int
	MaxAcceptTimeout time.Duration
	// contains filtered or unexported fields
}

Listener listens for new PeerConnections and saves all incoming datachannel from peers for later use.

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

Accept accepts a new connection from the listener.

It does not establish new connections. These connections are from the pool filled automatically by acceptLoop.

func (*Listener) Start

func (l *Listener) Start() error

func (*Listener) Stop

func (l *Listener) Stop() error

Stop the listener. Close existing PeerConnections.

The listener can be stopped when it is running or suspended.

func (*Listener) Suspend

func (l *Listener) Suspend() error

Suspend the listener. Don't close existing PeerConnections.

type ListenerRunningStatus

type ListenerRunningStatus = uint32

const (
	LISTENER_NEW ListenerRunningStatus = iota
	LISTENER_RUNNING
	LISTENER_SUSPENDED
	LISTENER_STOPPED
)

type NAT1To1IPs

type NAT1To1IPs struct {
	IPs  []string
	Type webrtc.ICECandidateType
}

NAT1To1IPs consists of a slice of IP addresses and one single ICE Candidate Type. Use this struct to set the IPs to be used as ICE Candidates.

type PortRange

type PortRange struct {
	Min uint16
	Max uint16
}

PortRange specifies the range of ports to use for ICE Transports.

type SignalMethod

type SignalMethod interface {
	// MakeOffer sends the SDP offer generated by offerer to the answerer.
	//
	// Called by OFFERER (#1)
	MakeOffer(offer []byte) error

	// GetOffer SHOULD return an error if Offer is not yet received/available.
	// However, blocking until an offer is received is also acceptable.
	//
	// Called by ANSWERER (#2)
	GetOffer() ([]byte, error)

	// Answer sends the SDP answer generated by answerer to the offerer.
	//
	// Called by ANSWERER (#3)
	Answer(answer []byte) error

	// GetAnswer blocks until the next SDP answer is available.
	//
	// Called by OFFERER (#4)
	GetAnswer() ([]byte, error)
}

var (
	// SignalMethodManual won't automatically establish a connection.
	// The connection will be established once both party have called SetRemoteDescription.
	SignalMethodManual SignalMethod = nil
)