peer

Documentation

Index

• Variables
• type Channel
  • func (c *Channel) Close() error
  • func (c *Channel) Label() string
  • func (c *Channel) NetConn() net.Conn
  • func (c *Channel) Protocol() string
  • func (c *Channel) Read(bytes []byte) (int, error)
  • func (c *Channel) Write(bytes []byte) (n int, err error)
• type ChannelOptions
• type Conn
  • func Client(servers []webrtc.ICEServer, opts *ConnOptions) (*Conn, error)
  • func Server(servers []webrtc.ICEServer, opts *ConnOptions) (*Conn, error)
  • func (c *Conn) Accept(ctx context.Context) (*Channel, error)
  • func (c *Conn) AddRemoteCandidate(i webrtc.ICECandidateInit)
  • func (c *Conn) Close() error
  • func (c *Conn) CloseWithError(err error) error
  • func (c *Conn) Closed() <-chan struct{}
  • func (c *Conn) Dial(ctx context.Context, label string, opts *ChannelOptions) (*Channel, error)
  • func (c *Conn) LocalCandidate() <-chan webrtc.ICECandidateInit
  • func (c *Conn) LocalSessionDescription() <-chan webrtc.SessionDescription
  • func (c *Conn) Ping() (time.Duration, error)
  • func (c *Conn) SetConfiguration(configuration webrtc.Configuration) error
  • func (c *Conn) SetRemoteSessionDescription(sessionDescription webrtc.SessionDescription)
• type ConnOptions

Variables

var (
	// ErrDisconnected occurs when the connection has disconnected.
	// The connection will be attempting to reconnect at this point.
	ErrDisconnected = xerrors.New("connection is disconnected")
	// ErrFailed occurs when the connection has failed.
	// The connection will not retry after this point.
	ErrFailed = xerrors.New("connection has failed")
	// ErrClosed occurs when the connection was closed. It wraps io.EOF
	// to fulfill expected read errors from closed pipes.
	ErrClosed = xerrors.Errorf("connection was closed: %w", io.EOF)
)

Types

type Channel

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

Channel represents a WebRTC DataChannel.

This struct wraps webrtc.DataChannel to add concurrent-safe usage, data bufferring, and standardized errors for connection state.

It modifies the default behavior of a DataChannel by closing on WebRTC PeerConnection failure. This is done to emulate TCP connections. This option can be changed in the options when creating a Channel.

func (*Channel) Close

func (c *Channel) Close() error

Close gracefully closes the DataChannel.

func (*Channel) Label

func (c *Channel) Label() string

Label returns the label of the underlying DataChannel.

func (*Channel) NetConn

func (c *Channel) NetConn() net.Conn

NetConn wraps the DataChannel in a struct fulfilling net.Conn. Read, Write, and Close operations can still be used on the *Channel struct.

func (*Channel) Protocol

func (c *Channel) Protocol() string

Protocol returns the protocol of the underlying DataChannel.

func (*Channel) Read

func (c *Channel) Read(bytes []byte) (int, error)

Read blocks until data is received.

This will block until the underlying DataChannel has been opened.

func (*Channel) Write

func (c *Channel) Write(bytes []byte) (n int, err error)

Write sends data to the underlying DataChannel.

This function will block if too much data is being sent. Data will buffer if the connection is temporarily disconnected, and will be flushed upon reconnection.

If the Channel is setup to close on disconnect, any buffered data will be lost.

type ChannelOptions

type ChannelOptions struct {
	// ID is a channel ID that should be used when `Negotiated`
	// is true.
	ID uint16

	// Negotiated returns whether the data channel will already
	// be active on the other end. Defaults to false.
	Negotiated bool

	// Arbitrary string that can be parsed on `Accept`.
	Protocol string

	// Ordered determines whether the channel acts like
	// a TCP connection. Defaults to false.
	Unordered bool

	// Whether the channel will be left open on disconnect or not.
	// If true, data will be buffered on either end to be sent
	// once reconnected. Defaults to false.
	OpenOnDisconnect bool
}

type Conn

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

Conn represents a WebRTC peer connection.

This struct wraps webrtc.PeerConnection to add bidirectional pings, concurrent-safe webrtc.DataChannel, and standardized errors for connection state.

func Client

func Client(servers []webrtc.ICEServer, opts *ConnOptions) (*Conn, error)

Client creates a new client connection.

func Server

func Server(servers []webrtc.ICEServer, opts *ConnOptions) (*Conn, error)

Server creates a new server connection.

func (*Conn) Accept

func (c *Conn) Accept(ctx context.Context) (*Channel, error)

Accept blocks waiting for a channel to be opened.

func (*Conn) AddRemoteCandidate

func (c *Conn) AddRemoteCandidate(i webrtc.ICECandidateInit)

AddRemoteCandidate adds a remote candidate to the RTC connection.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection and frees all associated resources.

func (*Conn) CloseWithError

func (c *Conn) CloseWithError(err error) error

CloseWithError closes the connection; subsequent reads/writes will return the error err.

func (*Conn) Closed

func (c *Conn) Closed() <-chan struct{}

func (*Conn) Dial

func (c *Conn) Dial(ctx context.Context, label string, opts *ChannelOptions) (*Channel, error)

Dial creates a new DataChannel.

func (*Conn) LocalCandidate

func (c *Conn) LocalCandidate() <-chan webrtc.ICECandidateInit

LocalCandidate returns a channel that emits when a local candidate needs to be exchanged with a remote connection.

func (*Conn) LocalSessionDescription

func (c *Conn) LocalSessionDescription() <-chan webrtc.SessionDescription

LocalSessionDescription returns a channel that emits a session description when one is required to be exchanged.

func (*Conn) Ping

func (c *Conn) Ping() (time.Duration, error)

Ping returns the duration it took to round-trip data. Multiple pings cannot occur at the same time, so this function will block.

func (*Conn) SetConfiguration

func (c *Conn) SetConfiguration(configuration webrtc.Configuration) error

SetConfiguration applies options to the WebRTC connection. Generally used for updating transport options, like ICE servers.

func (*Conn) SetRemoteSessionDescription

func (c *Conn) SetRemoteSessionDescription(sessionDescription webrtc.SessionDescription)

SetRemoteSessionDescription sets the remote description for the WebRTC connection.

type ConnOptions

type ConnOptions struct {
	Logger slog.Logger

	// Enables customization on the underlying WebRTC connection.
	SettingEngine webrtc.SettingEngine
}