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(ignoreServerKey key.Public, add, remove func(key.Public))
  • func (c *Client) Send(dstKey key.Public, b []byte) error
  • func (c *Client) ServerPublicKey() key.Public
  • 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
	// 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(ignoreServerKey key.Public, add, remove func(key.Public))

RunWatchConnectionLoop loops forever, 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.

func (*Client) Send

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

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) 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.