discovery

Documentation

Overview

Package discovery is STABLE — configured-node fan-out and optional UDP beacon discovery. It is part of the stable operator path.

Index

• func BuildFreshness(source string, expected, observed time.Duration, seededCount, beaconCount int, ...) *models.DiscoveryFreshness
• func Discover(ctx context.Context, cfg *config.Config) []models.NodeFacts
• func DiscoverSeeded(ctx context.Context, cfg *config.Config, seeded []config.NodeConfig) []models.NodeFacts
• func DiscoverWithWarnings(ctx context.Context, cfg *config.Config) ([]models.NodeFacts, []models.Warning)
• func WatchBeaconChanges(ctx context.Context, cfg *config.Config, registry *BeaconRegistry, ...)
• type Beacon
• type BeaconRegistry
  • func NewBeaconRegistry() *BeaconRegistry
  • func (r *BeaconRegistry) Freshness(cfg *config.Config, seededCount int) *models.DiscoveryFreshness
  • func (r *BeaconRegistry) PruneExpired(now time.Time) bool
  • func (r *BeaconRegistry) Reset() bool
  • func (r *BeaconRegistry) Snapshot() []config.NodeConfig
  • func (r *BeaconRegistry) UpdateFromBeacon(b Beacon) bool
• type Result
  • func DiscoverResult(ctx context.Context, cfg *config.Config) Result
  • func DiscoverSeededResult(ctx context.Context, cfg *config.Config, seeded []config.NodeConfig) Result

Functions

func BuildFreshness

func BuildFreshness(source string, expected, observed time.Duration, seededCount, beaconCount int, completed bool) *models.DiscoveryFreshness

BuildFreshness applies the shared discovery freshness policy used by both live UDP discovery windows and long-lived daemon beacon watchers.

func Discover

func Discover(ctx context.Context, cfg *config.Config) []models.NodeFacts

func DiscoverSeeded

func DiscoverSeeded(ctx context.Context, cfg *config.Config, seeded []config.NodeConfig) []models.NodeFacts

DiscoverSeeded probes configured nodes plus long-lived beacon-discovered nodes supplied by the caller. Unlike Discover, it does not reopen the UDP listener or wait for a fresh beacon accumulation window.

func DiscoverWithWarnings

func DiscoverWithWarnings(ctx context.Context, cfg *config.Config) ([]models.NodeFacts, []models.Warning)

DiscoverWithWarnings probes all configured nodes and returns any discovery warnings that should be surfaced to operators.

func WatchBeaconChanges

func WatchBeaconChanges(ctx context.Context, cfg *config.Config, registry *BeaconRegistry, onChange func())

WatchBeaconChanges runs a long-lived beacon broadcaster/listener pair and updates the provided registry as beacon-derived nodes appear, change, or age out. onChange is called only when the observed registry meaningfully changes.

Types

type Beacon

type Beacon struct {
	Type      string    `json:"t"`
	Name      string    `json:"n"`
	Hostname  string    `json:"h"`
	StableID  string    `json:"id,omitempty"`
	IP        string    `json:"ip"`
	SSHPort   int       `json:"p"`
	Role      string    `json:"r"`
	Version   string    `json:"v"`
	Timestamp time.Time `json:"ts"`
	// Sig is HMAC-SHA256(secret, canonical-beacon-JSON) hex-encoded.
	// Empty when no secret is configured (open/unsecured beacons).
	Sig string `json:"sig,omitempty"`
}

type BeaconRegistry

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

BeaconRegistry tracks UDP-discovered nodes from live beacons so a long-lived daemon can merge them into later refreshes without reopening the beacon listener on every snapshot build.

func NewBeaconRegistry

func NewBeaconRegistry() *BeaconRegistry

func (*BeaconRegistry) Freshness

func (r *BeaconRegistry) Freshness(cfg *config.Config, seededCount int) *models.DiscoveryFreshness

func (*BeaconRegistry) PruneExpired

func (r *BeaconRegistry) PruneExpired(now time.Time) bool

func (*BeaconRegistry) Reset

func (r *BeaconRegistry) Reset() bool

func (*BeaconRegistry) Snapshot

func (r *BeaconRegistry) Snapshot() []config.NodeConfig

func (*BeaconRegistry) UpdateFromBeacon

func (r *BeaconRegistry) UpdateFromBeacon(b Beacon) bool

type Result

type Result struct {
	Nodes     []models.NodeFacts
	Warnings  []models.Warning
	Freshness *models.DiscoveryFreshness
}

func DiscoverResult

func DiscoverResult(ctx context.Context, cfg *config.Config) Result

DiscoverResult probes configured nodes and returns the additive structured discovery metadata alongside the observed node set.

func DiscoverSeededResult

func DiscoverSeededResult(ctx context.Context, cfg *config.Config, seeded []config.NodeConfig) Result

DiscoverSeededResult probes configured nodes plus long-lived beacon-derived nodes supplied by the caller without opening a new UDP accumulation window.