const (NonceLen       = 24FrameHeaderLen = 1 + 4// frameType byte + 4 byte lengthKeyLen         = 32MaxInfoLen     = 1 << 20)

const (FrameServerKey     =FrameType(0x01)// 8B magic + 32B public key + (0+ bytes future use)FrameClientInfo    =FrameType(0x02)// 32B pub key + 24B nonce + naclbox(json)FrameServerInfo    =FrameType(0x03)// 24B nonce + naclbox(json)FrameSendPacket    =FrameType(0x04)// 32B dest pub key + packet bytesFrameForwardPacket =FrameType(0x0a)// 32B src pub key + 32B dst pub key + packet bytesFrameRecvPacket    =FrameType(0x05)// v0/1: packet bytes, v2: 32B src pub key + packet bytesFrameKeepAlive     =FrameType(0x06)// no payload, no-op (to be replaced with ping/pong)FrameNotePreferred =FrameType(0x07)// 1 byte payload: 0x01 or 0x00 for whether this is client's home node// framePeerGone is sent from server to client to signal that// a previous sender is no longer connected. That is, if A// sent to B, and then if A disconnects, the server sends// framePeerGone to B so B can forget that a reverse path// exists on that connection to get back to A. It is also sent// if A tries to send a CallMeMaybe to B and the server has no// record of BFramePeerGone =FrameType(0x08)// 32B pub key of peer that's gone + 1 byte reason// framePeerPresent is like framePeerGone, but for other members of the DERP// region when they're meshed up together.//// The message is at least 32 bytes (the public key of the peer that's// connected). If there are at least 18 bytes remaining after that, it's the// 16 byte IP + 2 byte BE uint16 port of the client. If there's another byte// remaining after that, it's a PeerPresentFlags byte.// While current servers send 41 bytes, old servers will send fewer, and newer// servers might send more.FramePeerPresent =FrameType(0x09)// frameWatchConns is how one DERP node in a regional mesh// subscribes to the others in the region.// There's no payload. If the sender doesn't have permission, the connection// is closed. Otherwise, the client is initially flooded with// framePeerPresent for all connected nodes, and then a stream of// framePeerPresent & framePeerGone has peers connect and disconnect.FrameWatchConns =FrameType(0x10)// frameClosePeer is a privileged frame type (requires the// mesh key for now) that closes the provided peer's// connection. (To be used for cluster load balancing// purposes, when clients end up on a non-ideal node)FrameClosePeer =FrameType(0x11)// 32B pub key of peer to close.FramePing =FrameType(0x12)// 8 byte ping payload, to be echoed back in framePongFramePong =FrameType(0x13)// 8 byte payload, the contents of the ping being replied to// frameHealth is sent from server to client to tell the client// if their connection is unhealthy somehow. Currently the only unhealthy state// is whether the connection is detected as a duplicate.// The entire frame body is the text of the error message. An empty message// clears the error state.FrameHealth =FrameType(0x14)// frameRestarting is sent from server to client for the// server to declare that it's restarting. Payload is two big// endian uint32 durations in milliseconds: when to reconnect,// and how long to try total. See ServerRestartingMessage docs for// more details on how the client should interpret them.FrameRestarting =FrameType(0x15))

const (PeerGoneReasonDisconnected  =PeerGoneReasonType(0x00)// is only sent when a peer disconnects from this serverPeerGoneReasonNotHere       =PeerGoneReasonType(0x01)// server doesn't know about this peerPeerGoneReasonMeshConnBroke =PeerGoneReasonType(0xf0)// invented by Client.RunWatchConnectionLoop on disconnect; not sent on the wire)

const (PeerPresentIsRegular  = 1 << 0PeerPresentIsMeshPeer = 1 << 1PeerPresentIsProber   = 1 << 2PeerPresentNotIdeal   = 1 << 3// client said derp server is not its Region.Nodes[0] ideal node)

const FastStartHeader = "Derp-Fast-Start"

const IdealNodeHeader = "Ideal-Node"

const KeepAlive = 60 *time.Second

const Magic = "DERP🔑"// 8 bytes: 0x44 45 52 50 f0 9f 94 91

const MaxPacketSize = 64 << 10

const ProtocolVersion = 2

funcReadFrameTypeHeader¶added inv1.90.0

func ReadFrameTypeHeader(br *bufio.Reader, wantTypeFrameType) (frameLenuint32, errerror)

ReadFrameTypeHeader reads a frame header from br andverifies that the frame type matches wantType.

If it does, it returns the frame length (not includingthe 5 byte header) and a nil error.

If it doesn't, it returns an error and a zero length.

funcWriteFrame¶added inv1.90.0

func WriteFrame(bw *bufio.Writer, tFrameType, b []byte)error

WriteFrame writes a complete frame & flushes it.

funcWriteFrameHeader¶added inv1.90.0

func WriteFrameHeader(bw *bufio.Writer, tFrameType, frameLenuint32)error

WriteFrameHeader writes a frame header to bw.

The frame header is 5 bytes: a one byte frame typefollowed by a big-endian uint32 length of theremaining frame (not including the 5 byte header).

It does not flush bw.

typeClient¶

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

Client is a DERP client.

func NewClient(privateKeykey.NodePrivate, ncConn, brw *bufio.ReadWriter, logflogger.Logf, opts ...ClientOpt) (*Client,error)

func (c *Client) ClosePeer(targetkey.NodePublic)error

func (c *Client) ForwardPacket(srcKey, dstKeykey.NodePublic, pkt []byte) (errerror)

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

func (c *Client) NotePreferred(preferredbool) (errerror)

func (c *Client) PublicKey()key.NodePublic

func (c *Client) Recv() (mReceivedMessage, errerror)

func (c *Client) Send(dstKeykey.NodePublic, pkt []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) WatchConnectionChanges()error

typeClientInfo¶added inv1.90.0

type ClientInfo struct {// MeshKey optionally specifies a pre-shared key used by// trusted clients.  It's required to subscribe to the// connection list & forward packets. It's empty for regular// users.MeshKeykey.DERPMesh `json:"meshKey,omitempty,omitzero"`// Version is the DERP protocol version that the client was built with.// See the ProtocolVersion const.Versionint `json:"version,omitempty"`// CanAckPings is whether the client declares it's able to ack// pings.CanAckPingsbool// IsProber is whether this client is a prober.IsProberbool `json:",omitempty"`}

ClientInfo is the information a DERP client sends to the serverabout itself when it connects.

func (c *ClientInfo) Equal(other *ClientInfo)bool

typeClientOpt¶added inv0.100.0

type ClientOpt interface {// contains filtered or unexported methods}

ClientOpt is an option passed to NewClient.

func CanAckPings(vbool)ClientOpt

func IsProber(vbool)ClientOpt

func MeshKey(kkey.DERPMesh)ClientOpt

func ServerPublicKey(keykey.NodePublic)ClientOpt

typeConn¶

type Conn interface {io.WriteCloserLocalAddr()net.Addr// The *Deadline methods follow the semantics of net.Conn.SetDeadline(time.Time)errorSetReadDeadline(time.Time)errorSetWriteDeadline(time.Time)error}

Conn is the subset of the underlying net.Conn the DERP Server needs.It is a defined type so that non-net connections can be used.

typeFrameType¶added inv1.90.0

type FrameTypebyte

FrameType is the one byte frame type at the beginning of the frameheader. The second field is a big-endian uint32 describing thelength of the remaining frame (not including the initial 5 bytes).

func ReadFrameHeader(br *bufio.Reader) (tFrameType, frameLenuint32, errerror)

typeHealthMessage¶added inv1.16.0

type HealthMessage struct {// Problem, if non-empty, is a description of why the connection// is unhealthy.//// The empty string means the connection is healthy again.//// The default condition is healthy, so the server doesn't// broadcast a HealthMessage until a problem exists.Problemstring}

HealthMessage is a one-way message from server to client, declaring theconnection health state.

typeKeepAliveMessage¶added inv1.6.0

type KeepAliveMessage struct{}

KeepAliveMessage is a one-way empty message from server to client, just tokeep the connection alive. It's like a PingMessage, but doesn't solicita reply from the client.

typePeerGoneMessage¶added inv0.98.0

type PeerGoneMessage struct {Peerkey.NodePublicReasonPeerGoneReasonType}

PeerGoneMessage is a ReceivedMessage that indicates that the clientidentified by the underlying public key is not connected to thisserver.

It has only historically been sent by the server when the clientconnection count decremented from 1 to 0 and not from e.g. 2 to 1.Seehttps://github.com/tailscale/tailscale/issues/13566 for details.

typePeerGoneReasonType¶added inv1.40.0

type PeerGoneReasonTypebyte

PeerGoneReasonType is a one byte reason code explaining why aserver does not have a path to the requested destination.

typePeerPresentFlags¶added inv1.70.0

type PeerPresentFlagsbyte

PeerPresentFlags is an optional byte of bit flags sent after a framePeerPresent message.

For a modern server, the value should always be non-zero. If the value is zero,that means the server doesn't support this field.

typePeerPresentMessage¶added inv0.99.1

type PeerPresentMessage struct {// Key is the public key of the client.Keykey.NodePublic// IPPort is the remote IP and port of the client.IPPortnetip.AddrPort// Flags is a bitmask of info about the client.FlagsPeerPresentFlags}

PeerPresentMessage is a ReceivedMessage that indicates that the client isconnected to the server. (Only used by trusted mesh clients)

It will be sent to client watchers for every new connection from a client,even if the client's already connected with that public key.Seehttps://github.com/tailscale/tailscale/issues/13566 for PeerPresentMessageand PeerGoneMessage not being 1:1.

typePingMessage¶added inv1.6.0

type PingMessage [8]byte

PingMessage is a request from a client or server to reply to theother side with a PongMessage with the given payload.

typePongMessage¶added inv1.20.0

type PongMessage [8]byte

PongMessage is a reply to a PingMessage from a client or serverwith the payload sent previously in a PingMessage.

typeReceivedMessage¶

type ReceivedMessage interface {// contains filtered or unexported methods}

ReceivedMessage represents a type returned by Client.Recv. Unlessotherwise documented, the returned message aliases the byte sliceprovided to Recv and thus the message is only as good as thatbuffer, which is up to the caller.

typeReceivedPacket¶

type ReceivedPacket struct {Sourcekey.NodePublic// Data is the received packet bytes. It aliases the memory// passed to Client.Recv.Data []byte}

ReceivedPacket is a ReceivedMessage representing an incoming packet.

typeServerInfo¶added inv1.90.0

type ServerInfo struct {Versionint `json:"version,omitempty"`TokenBucketBytesPerSecondint `json:",omitempty"`TokenBucketBytesBurstint `json:",omitempty"`}

ServerInfo is the message sent from the server to clients duringthe connection setup.

typeServerInfoMessage¶added inv1.2.0

type ServerInfoMessage struct {// TokenBucketBytesPerSecond is how many bytes per second the// server says it will accept, including all framing bytes.//// Zero means unspecified. There might be a limit, but the// client need not try to respect it.TokenBucketBytesPerSecondint// TokenBucketBytesBurst is how many bytes the server will// allow to burst, temporarily violating// TokenBucketBytesPerSecond.//// Zero means unspecified. There might be a limit, but the// client need not try to respect it.TokenBucketBytesBurstint}

ServerInfoMessage is sent by the server upon first connect.

typeServerRestartingMessage¶added inv1.16.0

type ServerRestartingMessage struct {// ReconnectIn is an advisory duration that the client should wait// before attempting to reconnect. It might be zero.// It exists for the server to smear out the reconnects.ReconnectIntime.Duration// TryFor is an advisory duration for how long the client// should attempt to reconnect before giving up and proceeding// with its normal connection failure logic. The interval// between retries is undefined for now.// A server should not send a TryFor duration more than a few// seconds.TryFortime.Duration}

ServerRestartingMessage is a one-way message from server to client,advertising that the server is restarting.