spf

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

type Config struct {
	Source    Source
	Resolver  NextHopResolver
	Root      types.SystemID
	Levels    []Level
	Debounce  time.Duration
	Installer *Installer
	// ResolverV6 / InstallerV6 enable the IPv6 install pass (isis-12). Both nil
	// (an IPv4-only node) skips IPv6 entirely. The SPF tree is shared; the IPv6
	// pass only adds TLV 236 leaf extraction + IPv6-family Loc-RIB insertion.
	ResolverV6  NextHopResolverV6
	InstallerV6 *Installer
}

type Edge struct {
	// To is the neighbor Source ID (a router with pseudonode 0, or a LAN
	// pseudo-node with pseudonode != 0).
	To types.SourceID
	// Metric is the 24-bit IS-reachability edge metric (RFC 5305 sec 3). A
	// pseudo-node edge is 0.
	Metric uint32
}

type Graph struct {
	// Nodes is every vertex keyed by its Source ID. A router and its
	// pseudo-nodes are distinct entries.
	Nodes map[types.SourceID]*Node
}

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

type LSPRecord struct {
	// Source is the LSP originator's Source ID (System ID + pseudonode). A
	// pseudo-node LSP has a non-zero pseudonode number.
	Source types.SourceID
	// Overload is the OL bit from the LSP type block (fragment 0; RFC 3787). The
	// builder ORs it across fragments so any fragment carrying it marks the node.
	Overload bool
	// LSP is the decoded LSP whose TLV 22 / 132 / 135 the builder reads. The TLV
	// value slices may alias the LSDB's stable raw bytes (lazy decode).
	LSP packet.LSP
}

type LeakResult struct {
	// IntoL1 are the prefixes leaked DOWN from L2 into L1 (RFC 2966: up/down bit
	// set). IPv4 (TLV 135).
	IntoL1 []LeakedPrefix
	// IntoL2 are the prefixes leaked UP from L1 into L2 (up/down bit clear). IPv4.
	IntoL2 []LeakedPrefix
	// IntoL1V6 / IntoL2V6 are the IPv6 (TLV 236) equivalents over the SHARED SPF
	// tree (RFC 5308 sec 5): identical leak rules, IPv6 prefixes.
	IntoL1V6 []LeakedPrefix
	// IntoL2V6 are the IPv6 prefixes leaked UP from L1 into L2.
	IntoL2V6 []LeakedPrefix
}

type LeakedPrefix struct {
	// Prefix is the leaked destination prefix (IPv4 for TLV 135, IPv6 for TLV 236).
	Prefix netip.Prefix
	// Metric is the full path cost to the prefix in the SOURCE level (node distance
	// + prefix metric), clamped at MaxPathMetric so a wide-metric sum never wraps.
	// It fits in 32 bits because MaxPathMetric (0xFE000000) is below 2^32.
	Metric uint32
	// UpDown is the RFC 2966 up/down bit to stamp on the re-originated entry: set
	// for an L2->L1 (down) leak, clear for an L1->L2 (up) leak.
	UpDown bool
}

type Level uint8

type NextHop struct {
	// Addr is the next-hop IP address (the adjacent neighbor's interface address,
	// TLV 132). Invalid means the next-hop could not be resolved and the entry is
	// dropped.
	Addr netip.Addr
	// Interface is the outgoing interface name the adjacency is on. Empty when
	// unknown (the kernel then resolves the egress from the route table).
	Interface string
}

type NextHopResolver interface {
	ResolveNextHop(level Level, neighbor types.SystemID) (NextHop, bool)
}

type NextHopResolverV6 interface {
	ResolveNextHopV6(level Level, neighbor types.SystemID) (NextHop, bool)
}

type Node struct {
	// ID is the node Source ID (System ID + pseudonode number).
	ID types.SourceID
	// Edges are the outgoing adjacencies (TLV 22 entries, pseudo-node edges 0).
	Edges []Edge
	// Prefixes are the IP reachabilities the node originates (TLV 135).
	Prefixes []Prefix
	// PrefixesV6 are the IPv6 reachabilities the node originates (TLV 236,
	// RFC 5308 sec 2). Populated only when IPv6 is in use; the IPv6 route builder
	// (ipv6.go) attaches them over the same shared SPF tree.
	PrefixesV6 []Prefix
	// Addrs are the node's own IPv4 interface addresses (TLV 132). Used only as a
	// fallback next-hop source; the primary next-hop comes from the local
	// adjacency table (Shared Contracts "Next-hop derivation for SPF").
	Addrs []netip.Addr
	// AddrsV6 are the node's own IPv6 interface addresses (TLV 232, RFC 5308
	// sec 3). The LSP carries only non-link-local addresses; the link-local
	// next-hop comes from the local adjacency table (neighbor IIH TLV 232).
	AddrsV6 []netip.Addr
	// Overload is the LSP-database-overload (OL) bit (RFC 3787): the node is a
	// valid destination but excluded as a transit node in SPF.
	Overload bool
}

type NodeResult struct {
	// ID is the reached node's Source ID.
	ID types.SourceID
	// Metric is the total path cost from the root (clamped at MaxPathMetric).
	Metric uint64
	// FirstHops are the System IDs of the directly-adjacent neighbors on the
	// equal-cost shortest paths to ID. The root itself has an empty set (it is
	// directly connected, no next-hop). One entry for a single path; multiple for
	// ECMP. A reachable node always has at least one first-hop unless it is the
	// root.
	FirstHops []types.SystemID
}

type Prefix struct {
	// Prefix is the advertised IPv4 prefix.
	Prefix netip.Prefix
	// Metric is the 32-bit prefix metric (RFC 5305 sec 4); read in full, never
	// capped at 24-bit.
	Metric uint32
	// UpDown is the up/down bit from the TLV 135 control octet (RFC 5305 sec 4.1
	// / RFC 2966): set means the prefix was leaked DOWN a level (L2 -> L1). A
	// prefix with this bit set MUST NOT be re-leaked UP into L2 (loop prevention).
	UpDown bool
}

type Result struct {
	// Root is the System ID SPF was rooted at.
	Root types.SystemID
	// Level is the level this result covers.
	Level Level
	// Nodes maps each reachable node's Source ID to its result.
	Nodes map[types.SourceID]*NodeResult
}

type RouteDelta struct {
	// Added are prefixes new since the previous run.
	Added []RouteEntry
	// Changed are prefixes present in both runs whose metric / next-hop set /
	// level differs.
	Changed []RouteEntry
	// Removed are prefixes present in the previous run but gone now.
	Removed []netip.Prefix
}

type RouteEntry struct {
	// Prefix is the destination IPv4 prefix (masked to its length).
	Prefix netip.Prefix
	// Metric is the total IS-IS path cost (node distance + prefix metric),
	// clamped at MaxPathMetric.
	Metric uint64
	// Level is the level the winning route came from (1 or 2).
	Level Level
	// UpDown is the up/down bit of the winning advertisement (RFC 2966): set when
	// the prefix was leaked down a level. Carried for the snapshot / diagnostics;
	// it does not change the installed next-hop.
	UpDown bool
	// NextHops are the resolved equal-cost next-hops (ECMP). At least one for a
	// route that is published; sorted by address for a stable diff.
	NextHops []NextHop
}

type RouteSink interface {
	InsertForward(fam family.Family, prefix netip.Prefix, p locrib.Path)
	Remove(fam family.Family, prefix netip.Prefix, source redistevents.ProtocolID, instance uint32)
	// Flush sends buffered ops to the engine; the installer calls it once per
	// Apply/RemoveAll so a whole delta travels in one RPC batch (R-1).
	Flush()
}

type RouteSnapshotEntry struct {
	Prefix   string             `json:"prefix"`
	Metric   uint64             `json:"metric"`
	Level    string             `json:"level"`
	UpDown   bool               `json:"up-down,omitempty"`
	NextHops []RouteSnapshotHop `json:"next-hops"`
}

type RouteSnapshotHop struct {
	NextHop   string `json:"next-hop"`
	Interface string `json:"interface,omitempty"`
}

type SPFLogEntry struct {
	// Time is the run start time as a Unix timestamp (seconds). The renderer
	// formats it; the engine keeps it numeric so the value is locale-free.
	TimeUnix int64 `json:"time-unix"`
	// Level is the routing level computed ("l1" | "l2").
	Level string `json:"level"`
	// Trigger names why SPF ran (e.g. "lsdb-change", "manual"). The debounced
	// engine path records "lsdb-change"; a direct Run records "manual".
	Trigger string `json:"trigger"`
	// DurationSeconds is how long the Dijkstra pass took for this level.
	DurationSeconds float64 `json:"duration-seconds"`
	// Nodes is the number of nodes in the level graph this run built.
	Nodes int `json:"nodes"`
}

type Source interface {
	// Records returns every LSP held at the level. A purged (zero-lifetime) LSP
	// is omitted by the implementation; a malformed LSP excludes that one node,
	// not the whole run (security review: error isolation).
	Records(level Level) []LSPRecord
}