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 AddressFamilySelector
• type Client
  • func NewClient(privateKey key.NodePrivate, serverURL string, logf logger.Logf) (*Client, error)
  • func NewNetcheckClient(logf logger.Logf) *Client
  • func NewRegionClient(privateKey key.NodePrivate, logf logger.Logf, ...) *Client
  • func (c *Client) Close() error
  • func (c *Client) ClosePeer(target key.NodePublic) 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, node *tailcfg.DERPNode, err error)
  • func (c *Client) ForwardPacket(from, to key.NodePublic, b []byte) error
  • func (c *Client) LocalAddr() (netip.AddrPort, error)
  • func (c *Client) NotePreferred(v bool)
  • func (c *Client) Ping(ctx context.Context) error
  • 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.NodePublic, infoLogf logger.Logf, ...)
  • func (c *Client) SelfPublicKey() key.NodePublic
  • func (c *Client) Send(dstKey key.NodePublic, b []byte) error
  • func (c *Client) SendPing(data [8]byte) error
  • func (c *Client) SendPong(data [8]byte) error
  • func (c *Client) ServerPublicKey() key.NodePublic
  • func (c *Client) SetAddressFamilySelector(s AddressFamilySelector)
  • func (c *Client) SetCanAckPings(v bool)
  • func (c *Client) SetURLDialer(dialer func(ctx context.Context, network, addr string) (net.Conn, error))
  • func (c *Client) TLSConnectionState() (_ *tls.ConnectionState, ok bool)
  • 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 AddressFamilySelector

type AddressFamilySelector interface {
	// PreferIPv6 reports whether IPv4 dials should be slightly
	// delayed to give IPv6 a better chance of winning dial races.
	// Implementations should only return true if IPv6 is expected
	// to succeed. (otherwise delaying IPv4 will delay the
	// connection overall)
	PreferIPv6() bool
}

AddressFamilySelector decides whethers IPv6 is preferred for outbound dials.

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.NodePrivate, 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.NodePrivate, 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.NodePublic) 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, node *tailcfg.DERPNode, err error)

DialRegionTLS returns a TLS connection to a DERP node in the given region.

DERP nodes for a region are tried in sequence according to their order in the DERP map. TLS is initiated on the first node where a socket is established.

func (*Client) ForwardPacket

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

func (*Client) LocalAddr

func (c *Client) LocalAddr() (netip.AddrPort, error)

LocalAddr reports c's local TCP address, without any implicit connect or reconnect.

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

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

Ping sends a ping to the peer and waits for it either to be acknowledged (in which case Ping returns nil) or waits for ctx to be over and returns an error. It will wait at most 5 seconds before returning an error.

Another goroutine must be in a loop calling Recv or RecvDetail or ping responses won't be handled.

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.NodePublic, infoLogf logger.Logf, add, remove func(key.NodePublic))

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

SelfPublicKey returns our own public key.

func (*Client) Send

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

func (*Client) SendPing

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

SendPing writes a ping message, without any implicit connect or reconnect. This is a lower-level interface that writes a frame without any implicit handling of the response pong, if any. For a higher-level interface, use Ping.

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

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

func (c *Client) SetAddressFamilySelector(s AddressFamilySelector)

SetAddressFamilySelector sets the AddressFamilySelector that this connection will use. It should be called before any dials. The value must not be nil. If called more than once, s must be the same concrete type as any prior calls.

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

func (c *Client) TLSConnectionState() (_ *tls.ConnectionState, ok bool)

TLSConnectionState returns the last TLS connection state, if any. The client must already be connected.

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.