client

package
v0.59.2 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2025 License: BSD-3-Clause Imports: 18 Imported by: 0

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

Constants

View Source 
const (
	OpenConnectionTimeout = 30 * time.Second
)

Variables

View Source 
var (
	ErrConnAlreadyExists = fmt.Errorf("connection already exists")
)
View Source 
var (
	ErrRelayClientNotConnected = fmt.Errorf("relay client not connected")
)

Functions

This section is empty.

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(serverURL string, authTokenStore *auth.TokenStore, peerID string, mtu uint16) *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(ctx context.Context) 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(ctx context.Context, 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. It block until the server confirm the peer is online. 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) 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 messages.PeerID, 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 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 manager about a new relay client instance.
	OnNewRelayClient chan *Client
	OnReconnected    chan struct{}
	// 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, mtu uint16) *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(ctx context.Context, 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 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 PeersStateSubscription 

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

PeersStateSubscription manages subscriptions to peer state changes (online/offline) over a relay connection. It allows tracking peers' availability and handling offline events via a callback. We get online notification from the server only once.

func NewPeersStateSubscription 

func NewPeersStateSubscription(log *log.Entry, relayConn relayedConnWriter, offlineCallback func(peerIDs []messages.PeerID)) *PeersStateSubscription

func (*PeersStateSubscription) Cleanup 

func (s *PeersStateSubscription) Cleanup()

func (*PeersStateSubscription) OnPeersOnline 

func (s *PeersStateSubscription) OnPeersOnline(peersID []messages.PeerID)

OnPeersOnline should be called when a notification is received that certain peers have come online. It checks if any of the peers are being waited on and signals their availability.

func (*PeersStateSubscription) OnPeersWentOffline 

func (s *PeersStateSubscription) OnPeersWentOffline(peersID []messages.PeerID)

func (*PeersStateSubscription) UnsubscribeStateChange 

func (s *PeersStateSubscription) UnsubscribeStateChange(peerIDs []messages.PeerID) error

func (*PeersStateSubscription) WaitToBeOnlineAndSubscribe 

func (s *PeersStateSubscription) WaitToBeOnlineAndSubscribe(ctx context.Context, peerID messages.PeerID) error

WaitToBeOnlineAndSubscribe waits for a specific peer to come online and subscribes to its state changes.

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
	MTU               uint16
	ConnectionTimeout time.Duration
}

func (*ServerPicker) PickServer 

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

Source Files

View all Source files

Directories

Path Synopsis
net
quic
ws

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.