client

Documentation

Overview

Package client contains the implementation of the Relay client.

The Relay client is responsible for establishing a connection with the Relay server and sending and receiving messages, Keep persistent connection with the Relay server and handle the connection issues. It uses the WebSocket protocol for communication and optionally supports TLS (Transport Layer Security).

If a peer wants to communicate with a peer on a different relay server, the manager will establish a new connection to the relay server. The connection with these relay servers will be closed if there is no active connection. The peers negotiate the common relay instance via signaling service.

Index

• Variables
• type Client
  • func NewClient(ctx context.Context, serverURL string, authTokenStore *auth.TokenStore, ...) *Client
  • func (c *Client) Close() error
  • func (c *Client) Connect() error
  • func (c *Client) HasConns() bool
  • func (c *Client) OpenConn(dstPeerID string) (net.Conn, error)
  • func (c *Client) Ready() bool
  • func (c *Client) ServerInstanceURL() (string, error)
  • func (c *Client) SetOnConnectedListener(fn func())
  • func (c *Client) SetOnDisconnectListener(fn func(string))
• type Conn
  • func NewConn(client *Client, dstID []byte, dstStringID string, messageChan chan Msg, ...) *Conn
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(b []byte) (n int, err error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(p []byte) (n int, err error)
• type Guard
  • func NewGuard(sp *ServerPicker) *Guard
  • func (g *Guard) StartReconnectTrys(ctx context.Context, relayClient *Client)
• type Manager
  • func NewManager(ctx context.Context, serverURLs []string, peerID string) *Manager
  • func (m *Manager) AddCloseListener(serverAddress string, onClosedListener OnServerCloseListener) error
  • func (m *Manager) HasRelayAddress() bool
  • func (m *Manager) OpenConn(serverAddress, peerKey string) (net.Conn, error)
  • func (m *Manager) Ready() bool
  • func (m *Manager) RelayInstanceAddress() (string, error)
  • func (m *Manager) Serve() error
  • func (m *Manager) ServerURLs() []string
  • func (m *Manager) SetOnReconnectedListener(f func())
  • func (m *Manager) UpdateServerURLs(serverURLs []string)
  • func (m *Manager) UpdateToken(token *relayAuth.Token) error
• type ManagerService
• type Msg
  • func (m *Msg) Free()
• type OnServerCloseListener
• type RelayAddr
  • func (a RelayAddr) Network() string
  • func (a RelayAddr) String() string
• type RelayTrack
  • func NewRelayTrack() *RelayTrack
• type ServerPicker
  • func (sp *ServerPicker) PickServer(parentCtx context.Context) (*Client, error)

Variables

var (
	ErrConnAlreadyExists = fmt.Errorf("connection already exists")
)

var (
	ErrRelayClientNotConnected = fmt.Errorf("relay client not connected")
)

Types

type Client

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

Client is a client for the relay server. It is responsible for establishing a connection to the relay server and managing connections to other peers. All exported functions are safe to call concurrently. After close the connection, the client can be reused by calling Connect again. When the client is closed, all connections are closed too. While the Connect is in progress, the OpenConn function will block until the connection is established with relay server.

func NewClient

func NewClient(ctx context.Context, serverURL string, authTokenStore *auth.TokenStore, peerID string) *Client

NewClient creates a new client for the relay server. The client is not connected to the server until the Connect

func (*Client) Close

func (c *Client) Close() error

Close closes the connection to the relay server and all connections to other peers.

func (*Client) Connect

func (c *Client) Connect() error

Connect establishes a connection to the relay server. It blocks until the connection is established or an error occurs.

func (*Client) HasConns

func (c *Client) HasConns() bool

HasConns returns true if there are connections.

func (*Client) OpenConn

func (c *Client) OpenConn(dstPeerID string) (net.Conn, error)

OpenConn create a new net.Conn for the destination peer ID. In case if the connection is in progress to the relay server, the function will block until the connection is established or timed out. Otherwise, it will return immediately. todo: what should happen if call with the same peerID with multiple times?

func (*Client) Ready

func (c *Client) Ready() bool

func (*Client) ServerInstanceURL

func (c *Client) ServerInstanceURL() (string, error)

ServerInstanceURL returns the address of the relay server. It could change after the close and reopen the connection.

func (*Client) SetOnConnectedListener

func (c *Client) SetOnConnectedListener(fn func())

func (*Client) SetOnDisconnectListener

func (c *Client) SetOnDisconnectListener(fn func(string))

SetOnDisconnectListener sets a function that will be called when the connection to the relay server is closed.

type Conn

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

Conn represent a connection to a relayed remote peer.

func NewConn

func NewConn(client *Client, dstID []byte, dstStringID string, messageChan chan Msg, instanceURL *RelayAddr) *Conn

NewConn creates a new connection to a relayed remote peer. client: the client instance, it used to send messages to the destination peer dstID: the destination peer ID dstStringID: the destination peer ID in string format messageChan: the channel where the messages will be received instanceURL: the relay instance URL, it used to get the proper server instance address for the remote peer

func (*Conn) Close

func (c *Conn) Close() error

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

func (*Conn) Read

func (c *Conn) Read(b []byte) (n int, err error)

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) SetDeadline

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

func (*Conn) SetReadDeadline

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

func (*Conn) SetWriteDeadline

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

func (*Conn) Write

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

type Guard

type Guard struct {
	// OnNewRelayClient is a channel that is used to notify the relay client about a new relay client instance.
	OnNewRelayClient chan *Client
	// contains filtered or unexported fields
}

Guard manage the reconnection tries to the Relay server in case of disconnection event.

func NewGuard

func NewGuard(sp *ServerPicker) *Guard

NewGuard creates a new guard for the relay client.

func (*Guard) StartReconnectTrys

func (g *Guard) StartReconnectTrys(ctx context.Context, relayClient *Client)

StartReconnectTrys is called when the relay client is disconnected from the relay server. It attempts to reconnect to the relay server. The function first tries a quick reconnect to the same server that was used before, if the server URL is still valid. If the quick reconnect fails, it starts a ticker to periodically attempt server picking until it succeeds or the context is done.

Parameters: - ctx: The context to control the lifecycle of the reconnection attempts. - relayClient: The relay client instance that was disconnected. todo prevent multiple reconnection instances. In the current usage it should not happen, but it is better to prevent

type Manager

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

Manager is a manager for the relay client instances. It establishes one persistent connection to the given relay URL and automatically reconnect to them in case disconnection. The manager also manage temporary relay connection. If a client wants to communicate with a client on a different relay server, the manager will establish a new connection to the relay server. The connection with these relay servers will be closed if there is no active connection. Periodically the manager will check if there is any unused relay connection and close it.

func NewManager

func NewManager(ctx context.Context, serverURLs []string, peerID string) *Manager

NewManager creates a new manager instance. The serverURL address can be empty. In this case, the manager will not serve.

func (*Manager) AddCloseListener

func (m *Manager) AddCloseListener(serverAddress string, onClosedListener OnServerCloseListener) error

AddCloseListener adds a listener to the given server instance address. The listener will be called if the connection closed.

func (*Manager) HasRelayAddress

func (m *Manager) HasRelayAddress() bool

HasRelayAddress returns true if the manager is serving. With this method can check if the peer can communicate with Relay service.

func (*Manager) OpenConn

func (m *Manager) OpenConn(serverAddress, peerKey string) (net.Conn, error)

OpenConn opens a connection to the given peer key. If the peer is on the same relay server, the connection will be established via the relay server. If the peer is on a different relay server, the manager will establish a new connection to the relay server. It returns back with a net.Conn what represent the remote peer connection.

func (*Manager) Ready

func (m *Manager) Ready() bool

Ready returns true if the home Relay client is connected to the relay server.

func (*Manager) RelayInstanceAddress

func (m *Manager) RelayInstanceAddress() (string, error)

RelayInstanceAddress returns the address of the permanent relay server. It could change if the network connection is lost. This address will be sent to the target peer to choose the common relay server for the communication.

func (*Manager) Serve

func (m *Manager) Serve() error

Serve starts the manager, attempting to establish a connection with the relay server. If the connection fails, it will keep trying to reconnect in the background. Additionally, it starts a cleanup loop to remove unused relay connections. The manager will automatically reconnect to the relay server in case of disconnection.

func (*Manager) ServerURLs

func (m *Manager) ServerURLs() []string

ServerURLs returns the addresses of the relay servers.

func (*Manager) SetOnReconnectedListener

func (m *Manager) SetOnReconnectedListener(f func())

func (*Manager) UpdateServerURLs

func (m *Manager) UpdateServerURLs(serverURLs []string)

func (*Manager) UpdateToken

func (m *Manager) UpdateToken(token *relayAuth.Token) error

UpdateToken updates the token in the token store.

type ManagerService

type ManagerService interface {
	Serve() error
	OpenConn(serverAddress, peerKey string) (net.Conn, error)
	AddCloseListener(serverAddress string, onClosedListener OnServerCloseListener) error
	RelayInstanceAddress() (string, error)
	ServerURLs() []string
	HasRelayAddress() bool
	UpdateToken(token *relayAuth.Token) error
}

ManagerService is the interface for the relay manager.

type Msg

type Msg struct {
	Payload []byte
	// contains filtered or unexported fields
}

Msg carry the payload from the server to the client. With this struct, the net.Conn can free the buffer.

func (*Msg) Free

func (m *Msg) Free()

type OnServerCloseListener

type OnServerCloseListener func()

type RelayAddr

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

func (RelayAddr) Network

func (a RelayAddr) Network() string

func (RelayAddr) String

func (a RelayAddr) String() string

type RelayTrack

type RelayTrack struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

RelayTrack hold the relay clients for the foreign relay servers. With the mutex can ensure we can open new connection in case the relay connection has been established with the relay server.

func NewRelayTrack

func NewRelayTrack() *RelayTrack

type ServerPicker

type ServerPicker struct {
	TokenStore *auth.TokenStore
	ServerURLs atomic.Value
	PeerID     string
}

func (*ServerPicker) PickServer

func (sp *ServerPicker) PickServer(parentCtx context.Context) (*Client, error)