wsnet

Documentation

Overview

Package wsnet handles client and server ends of Workspace networking negotiations and protocol.

Index

• Variables
• func ConnectEndpoint(baseURL *url.URL, workspace, token string) string
• func DialICE(server webrtc.ICEServer, options *DialICEOptions) error
• func Listen(ctx context.Context, broker string) (io.Closer, error)
• func ListenEndpoint(baseURL *url.URL, token string) string
• func TURNCredentials(token string) (username, password string, err error)
• func TURNEndpoint(baseURL *url.URL) string
• type DialICEOptions
• type Dialer
  • func Dial(conn net.Conn, iceServers []webrtc.ICEServer) (*Dialer, error)
  • func DialWebsocket(ctx context.Context, broker string, iceServers []webrtc.ICEServer) (*Dialer, error)
  • func (d *Dialer) Close() error
  • func (d *Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)
  • func (d *Dialer) Ping(ctx context.Context) error

Examples

• Dial (Basic)

Variables

var (
	// ErrMismatchedProtocol occurs when a TURN is requested to a STUN server,
	// or a TURN server is requested instead of TURNS.
	ErrMismatchedProtocol = errors.New("mismatched protocols")
	// ErrInvalidCredentials occurs when invalid credentials are passed to a
	// TURN server. This error cannot occur for STUN servers, as they don't accept
	// credentials.
	ErrInvalidCredentials = errors.New("invalid credentials")
)

Functions

func ConnectEndpoint

func ConnectEndpoint(baseURL *url.URL, workspace, token string) string

ConnectEndpoint returns the Coder endpoint to dial a connection for a workspace.

func DialICE

func DialICE(server webrtc.ICEServer, options *DialICEOptions) error

DialICE confirms ICE servers are dialable. Timeout defaults to 200ms.

func Listen

func Listen(ctx context.Context, broker string) (io.Closer, error)

Listen connects to the broker proxies connections to the local net. Close will end all RTC connections.

func ListenEndpoint

func ListenEndpoint(baseURL *url.URL, token string) string

ListenEndpoint returns the Coder endpoint to listen for workspace connections.

func TURNCredentials

func TURNCredentials(token string) (username, password string, err error)

TURNCredentials returns a username and password pair for a Coder token.

func TURNEndpoint

func TURNEndpoint(baseURL *url.URL) string

TURNEndpoint returns the TURN address for a Coder baseURL.

Types

type DialICEOptions

type DialICEOptions struct {
	Timeout time.Duration
	// Whether to ignore TLS errors.
	InsecureSkipVerify bool
}

DialICEOptions provides options for dialing an ICE server.

type Dialer

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

Dialer enables arbitrary dialing to any network and address inside a workspace. The opposing end of the WebSocket messages should be proxied with a Listener.

func Dial

func Dial(conn net.Conn, iceServers []webrtc.ICEServer) (*Dialer, error)

Dial negotiates a connection to a listener.

Example (Basic)

servers := []webrtc.ICEServer{{
	URLs:           []string{"turns:master.cdr.dev"},
	Username:       "kyle",
	Credential:     "pass",
	CredentialType: webrtc.ICECredentialTypePassword,
}}

for _, server := range servers {
	err := DialICE(server, nil)
	if errors.Is(err, ErrInvalidCredentials) {
		// You could do something...
	}
	if errors.Is(err, ErrMismatchedProtocol) {
		// Likely they used TURNS when they should have used TURN.
		// Or they could have used TURN instead of TURNS.
	}
}

dialer, err := DialWebsocket(context.Background(), "wss://master.cdr.dev/agent/workspace/connect", servers)
if err != nil {
	// Do something...
}
conn, err := dialer.DialContext(context.Background(), "tcp", "localhost:13337")
if err != nil {
	// Something...
}
defer conn.Close()
// You now have access to the proxied remote port in `conn`.

func DialWebsocket

func DialWebsocket(ctx context.Context, broker string, iceServers []webrtc.ICEServer) (*Dialer, error)

DialWebsocket dials the broker with a WebSocket and negotiates a connection.

func (*Dialer) Close

func (d *Dialer) Close() error

Close closes the RTC connection. All data channels dialed will be closed.

func (*Dialer) DialContext

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

DialContext dials the network and address on the remote listener.

func (*Dialer) Ping

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

Ping sends a ping through the control channel.