discovery

type Link struct {
	Name  string
	Index int
	MAC   net.HardwareAddr
	MTU   int

	// Up is the administrative state; Carrier is whether the link is
	// operationally up (a cable is plugged in and negotiated).
	Up      bool
	Carrier bool

	Loopback bool
	Driver   string

	// Addrs holds the interface's addresses, IPv4 and IPv6 alike, so the
	// wizard can show what the user expects to see.
	Addrs []netip.Prefix

	// VLANID and ParentIndex are set for an 802.1Q sub-interface; VLANID is 0
	// on any other kind of device.
	VLANID      int
	ParentIndex int

	// RxQueues is how many receive queues the device exposes. AF_XDP binds one
	// socket per queue, so a device with none cannot be used.
	RxQueues int

	// SpeedMbps is the negotiated link speed, or 0 when the device does not
	// report one (a veth, or a physical port with no carrier). Backends that
	// size themselves against line rate need it; nothing else does.
	SpeedMbps int
}

type MACSource string

type NeedsDstMACError struct {
	Reason string
	// Suggestion, when set, is a command the user could run to fix things.
	Suggestion string
}

type Neighbor struct {
	IP        netip.Addr
	MAC       net.HardwareAddr
	LinkIndex int
	// Reachable is true for entries the kernel considers usable (REACHABLE,
	// STALE, PERMANENT and friends) rather than incomplete or failed.
	Reachable bool
}

type Options struct {
	// ProbeTimeout bounds the active ARP probe. Zero uses DefaultProbeTimeout;
	// negative disables probing so only the existing neighbour table is used.
	ProbeTimeout time.Duration
}

type Resolved struct {
	// Link is the interface AF_XDP binds to — always a physical NIC.
	Link Link
	// L3Link is where addressing lives. It is the VLAN sub-interface when
	// --vlan names one, and Link otherwise.
	L3Link Link

	SrcMAC net.HardwareAddr
	SrcIP  netip.Addr
	Dst    netip.Prefix

	DstMAC    net.HardwareAddr
	MACSource MACSource
	// NextHop is the address the MAC belongs to: the destination itself when
	// it is on-link, or the gateway when it is not.
	NextHop netip.Addr
	OnLink  bool

	// Notes are informational lines for the review screen.
	Notes []string
}

type Route struct {
	// Dst is the destination prefix. The zero Prefix means the default route.
	Dst netip.Prefix
	// Gateway is the next hop, or the zero Addr for a directly connected
	// ("on-link") route.
	Gateway   netip.Addr
	LinkIndex int
	Priority  int
	Src       netip.Addr
}

type Source interface {
	Links() ([]Link, error)
	Routes() ([]Route, error)
	Neighbors(linkIndex int) ([]Neighbor, error)
	// Probe provokes IPv4 neighbour resolution for dst out of the given link
	// and waits up to timeout for the kernel to answer. Returning an error is
	// not fatal — the caller checks the neighbour table afterwards either way.
	Probe(link Link, dst netip.Addr, timeout time.Duration) error
}