derphttp

Documentation

Overview

Package derphttp implements DERP-over-HTTP.

This makes DERP look exactly like WebSockets. A server can implement DERP over HTTPS and even if the TLS connection intercepted using a fake root CA, unless the interceptor knows how to detect DERP packets, it will look like a web socket.

Index

• Variables
• func Handler(s *derp.Server) http.Handler
• type Client
  • func NewClient(privateKey key.Private, serverURL string, logf logger.Logf) (*Client, error)
  • func NewNetcheckClient(logf logger.Logf) *Client
  • func NewRegionClient(privateKey key.Private, logf logger.Logf, getRegion func() *tailcfg.DERPRegion) *Client
  • func (c *Client) Close() error
  • func (c *Client) ClosePeer(target key.Public) error
  • func (c *Client) Connect(ctx context.Context) error
  • func (c *Client) DialRegionTLS(ctx context.Context, reg *tailcfg.DERPRegion) (tlsConn *tls.Conn, connClose io.Closer, err error)
  • func (c *Client) ForwardPacket(from, to key.Public, b []byte) error
  • func (c *Client) NotePreferred(v bool)
  • func (c *Client) Recv() (derp.ReceivedMessage, error)
  • func (c *Client) RecvDetail() (m derp.ReceivedMessage, connGen int, err error)
  • func (c *Client) RunWatchConnectionLoop(ctx context.Context, ignoreServerKey key.Public, infoLogf logger.Logf, ...)
  • func (c *Client) SelfPublicKey() key.Public
  • func (c *Client) Send(dstKey key.Public, b []byte) error
  • func (c *Client) SendPong(data [8]byte) error
  • func (c *Client) ServerPublicKey() key.Public
  • func (c *Client) SetCanAckPings(v bool)
  • func (c *Client) SetURLDialer(dialer func(ctx context.Context, network, addr string) (net.Conn, error))
  • func (c *Client) WatchConnectionChanges() error

Variables

var ErrClientClosed = errors.New("derphttp.Client closed")

Functions

func Handler

func Handler(s *derp.Server) http.Handler

Types

type Client

type Client struct {
	TLSConfig *tls.Config        // optional; nil means default
	DNSCache  *dnscache.Resolver // optional; nil means no caching
	MeshKey   string             // optional; for trusted clients
	IsProber  bool               // optional; for probers to optional declare themselves as such
	// contains filtered or unexported fields
}

Client is a DERP-over-HTTP client.

It automatically reconnects on error retry. That is, a failed Send or Recv will report the error and not retry, but subsequent calls to Send/Recv will completely re-establish the connection (unless Close has been called).

func NewClient

func NewClient(privateKey key.Private, serverURL string, logf logger.Logf) (*Client, error)

NewClient returns a new DERP-over-HTTP client. It connects lazily. To trigger a connection, use Connect.

func NewNetcheckClient

func NewNetcheckClient(logf logger.Logf) *Client

NewNetcheckClient returns a Client that's only able to have its DialRegion method called. It's used by the netcheck package.

func NewRegionClient

func NewRegionClient(privateKey key.Private, logf logger.Logf, getRegion func() *tailcfg.DERPRegion) *Client

NewRegionClient returns a new DERP-over-HTTP client. It connects lazily. To trigger a connection, use Connect.

func (*Client) Close

func (c *Client) Close() error

Close closes the client. It will not automatically reconnect after being closed.

func (*Client) ClosePeer

func (c *Client) ClosePeer(target key.Public) error

ClosePeer asks the server to close target's TCP connection.

Only trusted connections (using MeshKey) are allowed to use this.

func (*Client) Connect

func (c *Client) Connect(ctx context.Context) error

Connect connects or reconnects to the server, unless already connected. It returns nil if there was already a good connection, or if one was made.

func (*Client) DialRegionTLS

func (c *Client) DialRegionTLS(ctx context.Context, reg *tailcfg.DERPRegion) (tlsConn *tls.Conn, connClose io.Closer, err error)

func (*Client) ForwardPacket

func (c *Client) ForwardPacket(from, to key.Public, b []byte) error

func (*Client) NotePreferred

func (c *Client) NotePreferred(v bool)

NotePreferred notes whether this Client is the caller's preferred (home) DERP node. It's only used for stats.

func (*Client) Recv

func (c *Client) Recv() (derp.ReceivedMessage, error)

Recv reads a message from c. The returned message may alias memory from Client. The message should only be used until the next Client call.

func (*Client) RecvDetail

func (c *Client) RecvDetail() (m derp.ReceivedMessage, connGen int, err error)

RecvDetail is like Recv, but additional returns the connection generation on each message. The connGen value is incremented every time the derphttp.Client reconnects to the server.

func (*Client) RunWatchConnectionLoop

func (c *Client) RunWatchConnectionLoop(ctx context.Context, ignoreServerKey key.Public, infoLogf logger.Logf, add, remove func(key.Public))

RunWatchConnectionLoop loops until ctx is done, sending WatchConnectionChanges and subscribing to connection changes.

If the server's public key is ignoreServerKey, RunWatchConnectionLoop returns.

Otherwise, the add and remove funcs are called as clients come & go.

infoLogf, if non-nil, is the logger to write periodic status updates about how many peers are on the server. Error log output is set to the c's logger, regardless of infoLogf's value.

To force RunWatchConnectionLoop to return quickly, its ctx needs to be closed, and c itself needs to be closed.

func (*Client) SelfPublicKey

func (c *Client) SelfPublicKey() key.Public

SelfPublicKey returns our own public key.

func (*Client) Send

func (c *Client) Send(dstKey key.Public, b []byte) error

func (*Client) SendPong

func (c *Client) SendPong(data [8]byte) error

SendPong sends a reply to a ping, with the ping's provided challenge/identifier data.

Unlike other send methods, SendPong makes no attempt to connect or reconnect to the peer. It's best effort. If there's a connection problem, the server will choose to hang up on us if we're not replying.

func (*Client) ServerPublicKey

func (c *Client) ServerPublicKey() key.Public

ServerPublicKey returns the server's public key.

It only returns a non-zero value once a connection has succeeded from an earlier call.

func (*Client) SetCanAckPings

func (c *Client) SetCanAckPings(v bool)

SetCanAckPings sets whether this client will reply to ping requests from the server.

This only affects future connections.

func (*Client) SetURLDialer

func (c *Client) SetURLDialer(dialer func(ctx context.Context, network, addr string) (net.Conn, error))

SetURLDialer sets the dialer to use for dialing URLs. This dialer is only use for clients created with NewClient, not NewRegionClient. If unset or nil, the default dialer is used.

The primary use for this is the derper mesh mode to connect to each other over a VPC network.

func (*Client) WatchConnectionChanges

func (c *Client) WatchConnectionChanges() error

WatchConnectionChanges sends a request to subscribe to notifications about clients connecting & disconnecting.

Only trusted connections (using MeshKey) are allowed to use this.