network

type Backend string

type ConfigSink interface {
	// ApplyMesh sends cfg to nodeID and returns that node's reported
	// identity. An error means this one node did not get its config;
	// Distribute treats that as this node's problem, never the fleet's.
	ApplyMesh(ctx context.Context, nodeID string, cfg DeviceConfig) (NodeIdentity, error)
}

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

type CoordinatorOption func(*Coordinator)

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

type DetectResult struct {
	Backend Backend
	Reason  string
}

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

type DeviceConfig struct {
	NodeID     string
	PrivateKey Key

	// Address is this node's own mesh address with the mesh CIDR's
	// prefix length (e.g. 10.181.0.3/16, not /32), because that prefix
	// is what tells the host routing table to send the whole mesh range
	// out the WireGuard interface.
	Address    netip.Prefix
	ListenPort int
	Peers      []PeerConfig
}

type DeviceOption func(*deviceOptions)

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

type DistributeResult struct {
	// Nodes is one entry per node in the inventory, in node ID order.
	Nodes []NodeResult

	// Updated lists the nodes whose reported identity differed from what
	// the inventory held going in. A non-empty Updated means the caller
	// must persist those identities and that the next pass will produce a
	// different plan; an empty one means the mesh has converged.
	Updated []string
}

type Key [KeyLen]byte

type LinkConfigurator interface {
	// SetAddress assigns addr to the interface named iface and brings the
	// interface up.
	SetAddress(ctx context.Context, iface string, addr netip.Prefix) error
}

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

type Mesh interface {
	// Apply converges this node's WireGuard device on cfg. Peers present
	// on the device but absent from cfg are removed; peers in cfg that
	// the device does not have are added; a peer whose endpoint or
	// allowed IPs changed is updated in place, not torn down and
	// recreated (tearing down would drop the session key and force a new
	// handshake for no reason).
	Apply(ctx context.Context, cfg DeviceConfig) error

	// Status reports what the device currently looks like, including
	// per-peer last-handshake times. This is what makes "peer
	// unreachable" observable rather than silent: a peer configured
	// minutes ago with a zero LastHandshake has never completed a
	// handshake, which is the mesh's equivalent of a failing health
	// check.
	Status(ctx context.Context) (Status, error)

	// Close tears the device down. Safe to call more than once.
	Close() error
}

type NodeIdentity struct {
	// PublicKey is derived from the private key the node generated and
	// keeps locally. This is the only key material that ever moves.
	PublicKey Key

	// ListenPort is the UDP port the node's device actually bound, which
	// can differ from the one it was asked for if that port was taken.
	ListenPort int

	// Endpoint is the node's own view of how it can be reached
	// ("host:port"), which may be empty. It is a hint, not an authority:
	// a node behind NAT genuinely does not know its own public address,
	// and the control plane's observation of where the node's gRPC
	// session dialed from is a better source. Coordinator prefers the
	// observed value when it has one; see Distribute.
	Endpoint string
}

type NodeInfo struct {
	// ID is store.Node.ID. The empty string is not valid here, unlike in
	// desired_services.node_id where "" means "the control plane's own
	// local node" (migrations/0009_node_placement.sql): a mesh has no
	// implicit node, every participant including the control plane's own
	// has a real row and a real key.
	ID   string
	Name string

	// PublicKey is this node's WireGuard public key. Zero until the node
	// has reported one, which is a normal transient state for a node
	// that enrolled but has not yet come up on the mesh, not an error:
	// Plan skips such a node as a peer rather than failing the whole
	// plan, so one not-yet-ready node cannot stop the rest of the fleet
	// from meshing.
	PublicKey Key

	// Endpoint is "host:port", the UDP address other nodes dial to reach
	// this one. May be empty for a node behind NAT that has never been
	// observed dialing out: WireGuard learns a peer's endpoint from its
	// first inbound handshake, so a NATted node is reachable as soon as
	// it initiates, which (ADR 003's reverse-dial design) it always
	// does. An empty endpoint therefore means "wait for it to talk to
	// us," not "unreachable."
	Endpoint string

	// Address is this node's mesh IP, assigned by AllocateAddress and
	// persisted by the control plane. Invalid (the zero netip.Addr)
	// until assigned, same "not ready yet" meaning as a zero PublicKey.
	Address netip.Addr
}

type NodeResult struct {
	NodeID   string
	Config   DeviceConfig
	Identity NodeIdentity

	// Err is non-nil when this node could not be reached or refused the
	// config. Recorded per node rather than aborting the pass: this is
	// the same principle dynamicSource already applies when a node's
	// transport is unavailable ("one broken resource must never block the
	// rest"), and it matters more here, because the node most likely to
	// be unreachable is the one that just went down, and that is exactly
	// when the *other* nodes most need an updated peer list.
	Err error
}

type PeerConfig struct {
	// NodeID is not part of WireGuard's own model at all. It is carried
	// so every log line about a peer can name the resource by the ID the
	// rest of this codebase uses, matching the convention that every log
	// line describing a resource includes its ID, rather than by a
	// base64 key that matches nothing else in the database.
	NodeID    string
	PublicKey Key
	Endpoint  string

	// AllowedIPs is what traffic this peer is permitted to send and
	// what destinations route to it. For a full mesh of single-address
	// nodes this is exactly one /32 per peer, never 0.0.0.0/0: a
	// default route through a peer would make every node a potential
	// exit node for every other, which is a materially different
	// security posture than "these machines can reach each other" and
	// not something ADR 006 asks for.
	AllowedIPs []netip.Prefix

	PersistentKeepalive time.Duration
}

type PeerStatus struct {
	// NodeID is carried through from the PeerConfig that created this
	// peer so a caller can log a peer by the ID everything else in this
	// codebase logs resources by, rather than by a base64 public key.
	// WireGuard itself has no concept of a node ID, so this is empty for
	// any peer the device has that no current DeviceConfig named.
	NodeID    string
	PublicKey Key
	Endpoint  string

	// LastHandshake is zero when no handshake has ever completed with
	// this peer, which is exactly the "configured but unreachable" case:
	// a peer entry can exist indefinitely without the other end ever
	// answering.
	LastHandshake time.Time
	TransferRx    int64
	TransferTx    int64
}

type Placement struct {
	// Service is the name the service is addressed by. This is the
	// user-facing name from app.yaml, which is what makes it usable in a
	// connection string.
	Service string

	// NodeID is the node the service currently runs on. The empty string
	// means the control plane's own node, exactly as 0009's schema
	// defines it, which is why BuildRecords needs to be told which node
	// ID that is rather than being able to infer it.
	NodeID string
}

type PlanOptions struct {
	// MeshCIDR is the private range every node's address comes from. It
	// determines both the prefix length on DeviceConfig.Address (so the
	// host routes the whole mesh out the WireGuard interface) and the
	// bound ValidateInventory checks every node address against.
	MeshCIDR netip.Prefix

	// ListenPort is the UDP port each node's device listens on. Zero
	// means DefaultListenPort.
	ListenPort int

	// Keepalive is the persistent-keepalive interval set on every peer.
	// Zero means DefaultKeepalive; explicitly disabling it requires a
	// negative value, so "I did not set this field" and "I want no
	// keepalive" are distinguishable. See DefaultKeepalive for why the
	// default is non-zero.
	Keepalive time.Duration
}

type Probe interface {
	// OS is the GOOS this node is running. WireGuard's kernel module is
	// a Linux thing; nothing else has one to detect.
	OS() string

	// KernelModuleLoaded reports whether the wireguard kernel module is
	// present and loaded. On Linux this is the existence of
	// /sys/module/wireguard.
	KernelModuleLoaded() bool

	// Privileged reports whether this process can create and configure a
	// network interface at all. A loaded kernel module is useless to an
	// unprivileged process, which is exactly the "restricted kernels,
	// some container-based VPS hosts" case ADR 006 cites as the reason
	// the userspace path exists.
	Privileged() bool
}

type Record struct {
	// Name is the fully qualified name, lowercase, with no trailing dot.
	Name    string
	Address netip.Addr

	// Service and NodeID are carried for logging and for the API surface
	// that will show an operator where a name currently points. They are
	// not part of resolution.
	Service string
	NodeID  string
}

type RecordSet struct {
	Zone       string
	Records    []Record
	Unresolved []Unresolved
}

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

type Status struct {
	Backend    Backend
	Interface  string
	PublicKey  Key
	ListenPort int
	Address    netip.Prefix
	Peers      []PeerStatus
}

type SystemProbe struct{}

type Unresolved struct {
	Service string
	NodeID  string
	Reason  string
}