agent

type Config struct {
	Agent            string            // agent identifier
	Network          string            // VPC network name
	Token            string            // tunnel auth token
	Labels           map[string]string // agent-declared labels for VPCService selection
	AdvertisedRoutes []string          // CIDRs reachable behind this agent, advertised to the relay
	Instance         string            // stable per-process instance UUID

	// SeedRelayAddr is the relay dialed for the bootstrap session (host:port).
	// Empty means Run picks one at random from SeedRelays; set it only for the
	// static single-relay case.
	SeedRelayAddr string
	// SeedRelays is the initial relay pool. Empty means just SeedRelayAddr.
	SeedRelays sets.Set[string]
	// RelayLister, when set, is polled to keep the relay pool current; relays
	// coming and going are picked up without a restart. Nil = static pool.
	RelayLister func(context.Context) (sets.Set[string], error)
	// MinConns is the number of concurrent relay connection slots. Values
	// below 1 are treated as 1. Ignored when ConnectAll is set.
	MinConns int
	// ConnectionTracker receives live-session changes from this agent. Run
	// creates one when it is nil. Callers that expose readiness must provide a
	// tracker and use the same value in their admin handlers.
	ConnectionTracker *ConnectionTracker
	// ConnectAll maintains one session per relay in the pool instead of
	// MinConns slots, tracking pool refreshes. Relay consumers (backplane
	// VTEP sessions) need this: relays do not federate routes, so reaching
	// agents homed on any relay requires a session to every relay.
	ConnectAll bool
	// ConnectionObserver receives lifecycle and traffic snapshots for each
	// MinConns slot. It is intended for interactive clients and is unused by
	// ConnectAll consumers. The callback must return promptly.
	ConnectionObserver func(ConnectionStatus)
	// SessionObserver receives the same snapshots keyed by relay instead of
	// slot. It fires for every session under every connection policy. This
	// includes ConnectAll, where ConnectionObserver never fires. Embedding
	// consumers such as backplane VTEP sessions use it to track per-relay
	// RTT and installed prefixes. The callback must return promptly. Run
	// waits for every session goroutine before it returns, so the observer
	// never fires after Run returns. Consumers rely on this contract to
	// order callbacks across successive runs.
	SessionObserver func(ConnectionStatus)

	// TLSConfig is used for the QUIC control sessions. Nil means defaults.
	TLSConfig *tls.Config

	// SocksListenAddr is the SOCKS5 listen address for the netstack datapath.
	// Ignored in TUN mode.
	SocksListenAddr string
	// PcapPath writes a packet capture of the netstack datapath. Not
	// supported in TUN mode.
	PcapPath string
	// TunMode selects the kernel TUN datapath over the in-process netstack:
	// the agent creates a TUN device (TunIfaceName) and programs overlay
	// addresses/routes on it, so any process in the netns reaches the overlay
	// by kernel route. Linux only; requires NET_ADMIN and /dev/net/tun.
	TunMode bool
	// TunIfaceName names the TUN device created in TUN mode.
	TunIfaceName string
	// TunNetns, when non-empty, places the TUN device inside this named
	// network namespace (created and bind-mounted under /var/run/netns if
	// missing). Only sockets created in that namespace reach the overlay,
	// giving kernel-level isolation between tenants sharing the process.
	// Requires CAP_SYS_ADMIN. Ignored outside TUN mode.
	TunNetns string
	// AdminPort is denied to traffic that enters through the overlay. This
	// keeps an underlay admin listener private even when it binds a wildcard
	// address. Zero means that no admin port is reserved.
	AdminPort uint16
}

type ConnectionState string

type ConnectionStatus struct {
	Slot        int
	Relay       string
	State       ConnectionState
	Latency     time.Duration
	ConnectedAt time.Time
	RXBytes     uint64
	TXBytes     uint64
	Prefixes    []netip.Prefix
	Err         error
}

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