webrtc

Documentation

Overview

Package webrtc manages Pion RTCPeerConnection, DataChannel, and signaling.

Index

• Constants
• type MessageHandler
• type MessageSender
• type Peer
  • func (p *Peer) Close()
  • func (p *Peer) SendMessage(msg protocol.Message) error
  • func (p *Peer) SendRaw(data []byte) error
• type PeerManager
  • func NewPeerManager(logger *slog.Logger, signaling MessageSender, serverURL string, ...) *PeerManager
  • func (pm *PeerManager) AllowedDeviceID() string
  • func (pm *PeerManager) CloseAll()
  • func (pm *PeerManager) ClosePeer(deviceID string)
  • func (pm *PeerManager) HandleSignalingMessage(msg SignalingMessage)
  • func (pm *PeerManager) PeerCount() int
  • func (pm *PeerManager) PeerStates() map[string]string
  • func (pm *PeerManager) SendTo(deviceID string, msg protocol.Message) error
  • func (pm *PeerManager) SetAllowedDeviceID(id string)
• type ProtocolHandler
• type SignalingClient
  • func NewSignalingClient(identity *auth.Identity, serverURL string, hostName string, ...) *SignalingClient
  • func (sc *SignalingClient) Close()
  • func (sc *SignalingClient) JWT() string
  • func (sc *SignalingClient) Run(ctx context.Context) error
  • func (sc *SignalingClient) Send(msg SignalingMessage) error
  • func (sc *SignalingClient) SignalActivity()
• type SignalingMessage
• type TurnCredentials

Constants

const (
	// DefaultPresenceInterval is how often the agent sends presence heartbeats.
	DefaultPresenceInterval = 30 * time.Second

	// DefaultReadDeadlineGrace is the fixed grace period added on top of
	// 2×PresenceInterval when computing the WebSocket read deadline.
	DefaultReadDeadlineGrace = 10 * time.Second

	// TokenRefreshMargin is how early before expiry to refresh the JWT.
	TokenRefreshMargin = 5 * time.Minute

	// JWTLifetime is the expected JWT lifetime (matching server-issued 1hr tokens).
	JWTLifetime = 1 * time.Hour

	// DormancyTimeout is how long continuous reconnection failures must persist
	// before the signaling client enters dormancy (stops retrying).
	DormancyTimeout = 5 * time.Minute
)

const DataChannelLabel = "terminal"

DataChannelLabel is the name of the WebRTC DataChannel used for terminal protocol.

Types

type MessageHandler

type MessageHandler func(msg SignalingMessage)

MessageHandler is called when the signaling client receives a message. Only called for authenticated, non-error messages.

type MessageSender

type MessageSender interface {
	Send(msg SignalingMessage) error
}

MessageSender sends signaling messages (SDP/ICE) via the signaling client.

type Peer

type Peer struct {
	DeviceID string
	// contains filtered or unexported fields
}

Peer represents a single WebRTC peer connection to a mobile device.

func (*Peer) Close

func (p *Peer) Close()

Close cleanly shuts down the peer connection. Closing the done channel unblocks any goroutine waiting in waitForSendReady so it returns immediately instead of waiting for the full sendReadyTimeout.

func (*Peer) SendMessage

func (p *Peer) SendMessage(msg protocol.Message) error

SendMessage encodes and sends a protocol message over the DataChannel. Blocks if the send buffer is full, waiting for backpressure to clear.

func (*Peer) SendRaw

func (p *Peer) SendRaw(data []byte) error

SendRaw sends pre-encoded bytes directly over the DataChannel. Blocks if the send buffer is full, waiting for backpressure to clear.

type PeerManager

type PeerManager struct {

	// API is the Pion WebRTC API used to create peer connections.
	// If nil, the default API is used. Set this for testing with custom settings.
	API *webrtc.API

	// MaxPeers is the maximum number of simultaneous peer connections allowed.
	// Defaults to 1 (single-pairing mode). Set after construction to override.
	MaxPeers int

	// OnPeerDisconnect is called when a peer connection enters a terminal state
	// (Failed or Closed). Set by agent.go to point at Handler.PeerDisconnected,
	// which triggers bridge teardown and pane size restore.
	OnPeerDisconnect func(deviceID string)
	// contains filtered or unexported fields
}

PeerManager manages multiple WebRTC peer connections, one per mobile device.

func NewPeerManager

func NewPeerManager(logger *slog.Logger, signaling MessageSender, serverURL string, jwtFn func() string, handler ProtocolHandler, hmacSecret string) *PeerManager

NewPeerManager creates a manager for WebRTC peer connections.

func (*PeerManager) AllowedDeviceID

func (pm *PeerManager) AllowedDeviceID() string

AllowedDeviceID returns the allowed device ID. Thread-safe.

func (*PeerManager) CloseAll

func (pm *PeerManager) CloseAll()

CloseAll closes all peer connections and waits for background cleanup goroutines (from state change handlers) to finish.

func (*PeerManager) ClosePeer

func (pm *PeerManager) ClosePeer(deviceID string)

ClosePeer closes a specific peer connection.

func (*PeerManager) HandleSignalingMessage

func (pm *PeerManager) HandleSignalingMessage(msg SignalingMessage)

HandleSignalingMessage processes an incoming signaling message (connect_request, sdp_answer, ice_candidate).

func (*PeerManager) PeerCount

func (pm *PeerManager) PeerCount() int

PeerCount returns the number of active peer connections.

func (*PeerManager) PeerStates

func (pm *PeerManager) PeerStates() map[string]string

PeerStates returns a map of device ID to PeerConnection state string for all tracked peers. Used by ConnectionCleaner as a safety net to detect peers in failed/closed state that weren't cleaned up by state handlers.

func (*PeerManager) SendTo

func (pm *PeerManager) SendTo(deviceID string, msg protocol.Message) error

SendTo sends a protocol message to a specific peer via their DataChannel.

func (*PeerManager) SetAllowedDeviceID

func (pm *PeerManager) SetAllowedDeviceID(id string)

SetAllowedDeviceID updates the allowed device ID under the mutex. Safe to call from any goroutine (e.g., SIGUSR2 handler).

type ProtocolHandler

type ProtocolHandler func(peerID string, msg protocol.Message)

ProtocolHandler is called when a decoded protocol message arrives on the DataChannel.

type SignalingClient

type SignalingClient struct {

	// PresenceInterval controls how often heartbeats are sent. Defaults to 30s.
	PresenceInterval time.Duration

	// InitialBackoff controls the starting reconnection backoff delay.
	// Defaults to 1s if zero.
	InitialBackoff time.Duration

	// ReadDeadlineGrace is the fixed grace added to 2×PresenceInterval for
	// the rolling WebSocket read deadline. Defaults to 10s.
	ReadDeadlineGrace time.Duration

	// HTTPClient used for token exchange. Defaults to a 10s-timeout client.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

SignalingClient manages a persistent WebSocket connection to the signaling server.

func NewSignalingClient

func NewSignalingClient(identity *auth.Identity, serverURL string, hostName string, handler MessageHandler, logger *slog.Logger, hmacSecret string) *SignalingClient

NewSignalingClient creates a signaling client for the given identity and server.

func (*SignalingClient) Close

func (sc *SignalingClient) Close()

Close shuts down the signaling client.

func (*SignalingClient) JWT

func (sc *SignalingClient) JWT() string

JWT returns the current JWT token. Thread-safe.

func (*SignalingClient) Run

func (sc *SignalingClient) Run(ctx context.Context) error

Run connects to the signaling server and maintains the connection with automatic reconnection and token refresh. Blocks until ctx is canceled.

After DormancyTimeout of continuous reconnection failures, the client enters dormancy and stops retrying. It resumes when SignalActivity() is called (e.g., when a new tmux command triggers supervisor activity).

func (*SignalingClient) Send

func (sc *SignalingClient) Send(msg SignalingMessage) error

Send sends a signaling message to the server. Thread-safe.

func (*SignalingClient) SignalActivity

func (sc *SignalingClient) SignalActivity()

SignalActivity wakes the signaling client from dormancy, causing it to resume reconnection attempts. Safe to call from any goroutine. Used by the supervisor when it detects tmux command activity.

type SignalingMessage

type SignalingMessage struct {
	Type           string `json:"type"`
	Token          string `json:"token,omitempty"`
	Name           string `json:"name,omitempty"`
	Status         string `json:"status,omitempty"`
	Error          string `json:"error,omitempty"`
	Reason         string `json:"reason,omitempty"`
	TargetDeviceID string `json:"targetDeviceId,omitempty"`
	DeviceID       string `json:"deviceId,omitempty"`

	// SDP fields
	SDP string `json:"sdp,omitempty"`

	// ICE candidate fields
	Candidate     string `json:"candidate,omitempty"`
	SDPMid        string `json:"sdpMid,omitempty"`
	SDPMLineIndex *int   `json:"sdpMLineIndex,omitempty"`
}

SignalingMessage represents a JSON message to/from the signaling server.

type TurnCredentials

type TurnCredentials struct {
	URLs       []string `json:"urls"`
	Username   string   `json:"username"`
	Credential string   `json:"credential"`
}

TurnCredentials holds STUN/TURN server credentials from the signaling server.