wgengine

type Bird interface {
	// Reconfig recomputes from the given self node whether this node is
	// a primary subnet router. It is called near the top of every
	// [Engine.Reconfig], before its ErrNoChanges early return. It
	// reports whether the primary subnet router state changed, which
	// suppresses the engine's ErrNoChanges early return.
	Reconfig(self tailcfg.NodeView) (changed bool)

	// ReconfigDone is called at the end of [Engine.Reconfig], after the
	// router is configured, and applies any protocol state change
	// computed by the preceding Reconfig call.
	ReconfigDone()

	// Close disables the protocol and closes the connection to BIRD.
	Close()
}

type Config struct {
	// Tun is the device used by the Engine to exchange packets with
	// the OS.
	// If nil, a fake Device that does nothing is used.
	Tun tun.Device

	// IsTAP is whether Tun is actually a TAP (Layer 2) device that'll
	// require ethernet headers.
	IsTAP bool

	// Router interfaces the Engine to the OS network stack.
	// If nil, a fake Router that does nothing is used.
	Router router.Router

	// DNS interfaces the Engine to the OS DNS resolver configuration.
	// If nil, a fake OSConfigurator that does nothing is used.
	DNS dns.OSConfigurator

	// ReconfigureVPN provides an optional hook for platforms like Android to
	// know when it's time to reconfigure their VPN implementation. Such
	// platforms can only set their entire VPN configuration (routes, DNS, etc)
	// at all once and can't make piecemeal incremental changes, so this
	// provides a hook to "flush" a batch of Router and/or DNS changes.
	ReconfigureVPN func() error

	// NetMon optionally provides an existing network monitor to re-use.
	// If nil, a new network monitor is created.
	NetMon *netmon.Monitor

	// HealthTracker, if non-nil, is the health tracker to use.
	HealthTracker *health.Tracker

	// Metrics is the usermetrics registry to use.
	// Mandatory, if not set, an error is returned.
	Metrics *usermetric.Registry

	// Dialer is the dialer to use for outbound connections.
	// If nil, a new Dialer is created.
	Dialer *tsdial.Dialer

	// ExtraRootCAs, if non-nil, specifies additional trusted root CAs for TLS
	// connections (e.g. DERP). Passed through to magicsock.
	ExtraRootCAs *x509.CertPool

	// DERPAppName, if non-empty, is an opaque app name string to
	// advertise to DERP servers for stats purposes. It is passed
	// through to magicsock.
	DERPAppName string

	// ControlKnobs is the set of control plane-provied knobs
	// to use.
	// If nil, defaults are used.
	ControlKnobs *controlknobs.Knobs

	// ListenPort is the port on which the engine will listen.
	// If zero, a port is automatically selected.
	ListenPort uint16

	// RespondToPing determines whether this engine should internally
	// reply to ICMP pings, without involving the OS.
	// Used in "fake" mode for development.
	RespondToPing bool

	// BIRDSocket, if non-empty, is the path of the BIRD unix socket to
	// configure whenever this node is a primary subnet router. It
	// requires the feature/bird package to be linked in.
	BIRDSocket string

	// SetSubsystem, if non-nil, is called for each new subsystem created, just before a successful return.
	SetSubsystem func(any)

	// DriveForLocal, if populated, will cause the engine to expose a Taildrive
	// listener at 100.100.100.100:8080.
	DriveForLocal drive.FileSystemForLocal

	// EventBus, if non-nil, is used for event publication and subscription by
	// the Engine and its subsystems.
	//
	// TODO(creachadair): As of 2025-03-19 this is optional, but is intended to
	// become required non-nil.
	EventBus *eventbus.Bus

	// ForceDiscoKey, if non-zero, forces the use of a specific disco
	// private key. This should only be used for special cases and
	// experiments, not for production. The recommended normal path is to
	// leave it zero, in which case a new disco key is generated per
	// Tailscale start and kept only in memory.
	ForceDiscoKey key.DiscoPrivate

	// OnDERPRecv, if non-nil, is called for every non-disco packet
	// received from DERP before the peer map lookup. If it returns
	// true, the packet is considered handled and is not passed to
	// WireGuard. The pkt slice is borrowed and must be copied if
	// the callee needs to retain it.
	OnDERPRecv func(regionID int, src key.NodePublic, pkt []byte) (handled bool)
}

type Engine interface {
	// Reconfig reconfigures WireGuard and makes sure it's running.
	// This also handles setting up any kernel routes.
	//
	// This is called whenever tailcontrol (the control plane)
	// sends an updated network map.
	//
	// The returned error is ErrNoChanges if no changes were made.
	Reconfig(*wgcfg.Config, *router.Config, *dns.Config) error

	// ResetAndStop resets the engine to a clean state (like calling Reconfig
	// with all pointers to zero values) and waits for it to be fully stopped,
	// with no live peers or DERPs.
	//
	// Unlike Reconfig, it does not return ErrNoChanges.
	ResetAndStop() (*Status, error)

	// SetPeerForIPFunc installs the IP-to-node lookup used by the
	// engine's internal cold paths (Ping, TSMP, pendopen diagnostics).
	// It parallels [Engine.SetPeerByIPPacketFunc] but returns richer
	// data (a full NodeView, the matched route prefix, and the IsSelf
	// flag).
	//
	// If fn is nil, those lookups fail for every IP.
	//
	// LocalBackend installs a func backed by the live nodeBackend for
	// exact-match and self addresses, with the RouteManager's outbound
	// table supplying the subnet-route / exit-node fallback; the engine
	// itself holds no peer-lookup state on this path.
	SetPeerForIPFunc(fn func(netip.Addr) (_ PeerForIP, ok bool))

	// GetFilter returns the current packet filter, if any.
	GetFilter() *filter.Filter

	// SetFilter updates the packet filter.
	SetFilter(*filter.Filter)

	// GetJailedFilter returns the current packet filter for jailed nodes,
	// if any.
	GetJailedFilter() *filter.Filter

	// SetJailedFilter updates the packet filter for jailed nodes.
	SetJailedFilter(*filter.Filter)

	// SetPeerRoutes updates the per-peer route attributes used by the
	// tun-layer data plane for per-packet NAT rewrites and
	// jailed-filter selection. native4 and native6 are this node's own
	// Tailscale addresses, and routes maps each peer's addresses and
	// routed prefixes to its attributes; it is a shared immutable
	// snapshot from [routemanager.RouteManager.Outbound].
	//
	// A nil routes table disables all per-packet peer processing;
	// callers pass nil when no current peer has any such attributes.
	SetPeerRoutes(native4, native6 netip.Addr, routes *bart.Table[*routemanager.PeerRoute])

	// SetStatusCallback sets the function to call when the
	// WireGuard status changes.
	SetStatusCallback(StatusCallback)

	// RequestStatus requests a WireGuard status update right
	// away, sent to the callback registered via SetStatusCallback.
	RequestStatus()

	// PeerByKey returns the WireGuard status of the provided peer.
	// If the peer is not found, ok is false.
	PeerByKey(key.NodePublic) (_ wgint.Peer, ok bool)

	// Close shuts down this wireguard instance, remove any routes
	// it added, etc. To bring it up again later, you'll need a
	// new Engine.
	Close()

	// Done returns a channel that is closed when the Engine's
	// Close method is called, the engine aborts with an error,
	// or it shuts down due to the closure of the underlying device.
	// You don't have to call this.
	Done() <-chan struct{}

	// SetSelfNode informs the engine of the current self node.
	// The zero (invalid) NodeView indicates no self node.
	SetSelfNode(tailcfg.NodeView)

	// UpdateStatus populates the network state using the provided
	// status builder.
	UpdateStatus(*ipnstate.StatusBuilder)

	// Ping is a request to start a ping of the given message size to the peer
	// handling the given IP, then call cb with its ping latency & method.
	//
	// If size is zero too small, it is ignored. See tailscale.PingOpts for details.
	Ping(ip netip.Addr, pingType tailcfg.PingType, size int, cb func(*ipnstate.PingResult))

	// InstallCaptureHook registers a function to be called to capture
	// packets traversing the data path. The hook can be uninstalled by
	// calling this function with a nil value.
	InstallCaptureHook(packet.CaptureCallback)

	// SetPeerByIPPacketFunc installs a callback used by wireguard-go to
	// look up which peer should handle an outbound packet by destination IP.
	SetPeerByIPPacketFunc(func(netip.Addr) (_ key.NodePublic, ok bool))

	// SetPeerConfigFunc installs the live source of per-peer WireGuard
	// configuration: given a peer's public key, fn returns the prefixes
	// the peer is currently allowed to originate traffic from, or
	// ok=false if the peer is unknown (in which case it must not exist
	// in the WireGuard device). The engine installs a single
	// [device.PeerLookupFunc] wrapping fn, so lazily-created peers
	// always see current state and the lookup func never needs to be
	// reinstalled as peers come and go.
	//
	// It is expected to be called once during LocalBackend construction,
	// before the first [Engine.Reconfig]. fn is called rarely (when
	// wireguard-go first hears from a peer it doesn't have) and may
	// acquire locks.
	SetPeerConfigFunc(fn func(key.NodePublic) (allowedIPs []netip.Prefix, ok bool))

	// SyncDevicePeer synchronizes the WireGuard device's state for a
	// single peer with the config source installed via
	// [Engine.SetPeerConfigFunc]: if the source no longer knows the
	// peer, it is removed from the device; if the peer is active in the
	// device, its allowed IPs are updated. It does O(1) work (plus the
	// config source lookup) and is intended to be called for each peer
	// added, updated, or removed by an incremental netmap delta,
	// avoiding a full [Engine.Reconfig].
	//
	// It is a no-op if no config source is installed.
	SyncDevicePeer(key.NodePublic)

	// ResetDevicePeer removes the peer from the WireGuard device,
	// discarding any session key material and in-flight handshake
	// state. If the peer is still known to the config source installed
	// via [Engine.SetPeerConfigFunc], it is lazily re-created on demand
	// with fresh state.
	//
	// LocalBackend calls it when a peer's disco key changes, which
	// means the peer restarted and its old sessions are dead.
	ResetDevicePeer(key.NodePublic)

	// SetNetLogSource installs the [NetLogSource] consulted by the
	// engine's network flow logger for node lookups and the current
	// audit logging identity.
	//
	// It is expected to be called once during LocalBackend construction,
	// before any [Engine.Reconfig] call that starts up the network logger.
	SetNetLogSource(NetLogSource)

	// SetWGPeerLookup installs the function used by the engine's
	// wireguard-go log wrapper to rewrite peer references in log lines
	// (mapping wireguard-go's "peer(XXXX…YYYY)" form to the
	// Tailscale-conventional short string form).
	//
	// It is expected to be called once during LocalBackend construction.
	// The function is called concurrently and must be safe to call with
	// no Engine locks held.
	SetWGPeerLookup(func(wgString string) (tsString string, ok bool))

	// SetPeerSessionStateFunc installs a callback used to observe WireGuard
	// peer session state transitions.
	//
	// Calls are serialized per Engine and delivered in transition order from
	// wireguard-go, while wireguard-go is holding locks. The callback must be
	// cheap and must not call back into wireguard-go.
	//
	// It does not replay current state. Callers that need a complete view should
	// set it before peers are started or lazily created, and maintain any
	// snapshots, sequence numbers, and pubsub state outside wireguard-go.
	//
	// In Tailscale, the usual implementation is
	// ipnlocal.LocalBackend.onPeerWireGuardState, installed early in
	// LocalBackend construction.
	SetPeerSessionStateFunc(func(key.NodePublic, PeerWireGuardState))

	// ProbeLocks acquires and releases the engine's internal locks so
	// that [ipnlocal.LocalBackend]'s watchdog can detect deadlocks in
	// the engine. It is otherwise a no-op.
	ProbeLocks()
}

type NetLogSource interface {
	// SelfNode returns the current self node and its owning user profile.
	// The views are invalid if there is no current node.
	SelfNode() (tailcfg.NodeView, tailcfg.UserProfileView)

	// NodeByAddr returns the node assigned the given address along with
	// its owning user profile.
	// ok is false if no node is known to own addr.
	NodeByAddr(addr netip.Addr) (node tailcfg.NodeView, user tailcfg.UserProfileView, ok bool)

	// NetLogIDs returns the audit logging IDs from the current netmap,
	// along with whether exit node flows should be logged.
	// ok is false if network flow logging should not run.
	NetLogIDs() (nodeID, domainID logid.PrivateID, logExitFlows bool, ok bool)
}

type NetLogger interface {
	// Reconfig is called near the top of every [Engine.Reconfig],
	// before its ErrNoChanges early return (so identity-only changes
	// still take effect) and before the router is configured (so a
	// starting logger captures initial packets). It reports whether
	// network logging state changed, which suppresses the engine's
	// ErrNoChanges early return.
	Reconfig(routerCfg *router.Config, routerChanged bool) (changed bool)

	// ReconfigDone is called at the end of [Engine.Reconfig], after
	// the router is configured, so that a logger stopping as a result
	// of the preceding Reconfig call captures final packets. It may
	// block to flush pending messages.
	ReconfigDone()

	// Shutdown stops the logger. It may block to flush pending
	// messages, bounded by an internal upload timeout.
	Shutdown()
}

type NetLoggerDeps struct {
	Logf   logger.Logf
	Tun    *tstun.Wrapper
	Sock   *magicsock.Conn
	NetMon *netmon.Monitor
	Health *health.Tracker
	Bus    *eventbus.Bus

	// Source returns the [NetLogSource] installed via
	// [Engine.SetNetLogSource], or nil if none has been installed yet.
	// It is a func because the source is installed after the engine
	// (and thus the NetLogger) is constructed.
	Source func() NetLogSource
}

type NetworkMapCallback func(*netmap.NetworkMap)

type PeerForIP struct {
	// Node is the matched node. It's always a valid value when
	// Engine.PeerForIP returns ok==true.
	Node tailcfg.NodeView

	// IsSelf is whether the Node is the local process.
	IsSelf bool

	// Route is the route that matched the IP provided
	// to Engine.PeerForIP.
	Route netip.Prefix
}

type PeerWireGuardState uint8

type Status struct {
	AsOf       time.Time // the time at which the status was calculated
	Peers      []ipnstate.PeerStatusLite
	LocalAddrs []tailcfg.Endpoint // the set of possible endpoints for the magic conn
	DERPs      int                // number of active DERP connections
}

type StatusCallback func(*Status, error)