mesh

Documentation

Overview

Package mesh is SCAFFOLDED — gossip-based peer discovery scaffolding. Not wired into the stable operator path.

Index

• type Config
  • func DefaultConfig() Config
• type Mesh
  • func New(self Peer, cfg Config, logger *slog.Logger) *Mesh
  • func (m *Mesh) ActivePeers() []Peer
  • func (m *Mesh) AddSeed(p Peer)
  • func (m *Mesh) Peers() []Peer
  • func (m *Mesh) Start(ctx context.Context) error
  • func (m *Mesh) Stop()
  • func (m *Mesh) Trust(id string) error
• type Peer
• type PeerState
  • func (s PeerState) String() string

Types

type Config

type Config struct {
	// ListenAddr is the UDP address for gossip (default ":42426").
	ListenAddr string `yaml:"listen_addr" json:"listen_addr"`
	// GossipInterval is how often we broadcast our peer list.
	GossipInterval time.Duration `yaml:"gossip_interval" json:"gossip_interval"`
	// SuspectTimeout is how long before a silent peer becomes suspect.
	SuspectTimeout time.Duration `yaml:"suspect_timeout" json:"suspect_timeout"`
	// DeadTimeout is how long a suspect peer stays before eviction.
	DeadTimeout time.Duration `yaml:"dead_timeout" json:"dead_timeout"`
	// MaxPeers caps the mesh to prevent unbounded growth.
	MaxPeers int `yaml:"max_peers" json:"max_peers"`
	// SharedSecret is the HMAC key for gossip authentication.
	SharedSecret string `yaml:"shared_secret" json:"shared_secret"`
	// FanOut is how many random peers receive each gossip round.
	FanOut int `yaml:"fan_out" json:"fan_out"`
}

Config controls mesh behavior.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns production defaults.

type Mesh

type Mesh struct {

	// Callbacks for integration with daemon cache.
	OnPeerJoin    func(Peer)
	OnPeerLeave   func(Peer)
	OnPeerSuspect func(Peer)
	// contains filtered or unexported fields
}

Mesh manages peer discovery and gossip protocol.

func New

func New(self Peer, cfg Config, logger *slog.Logger) *Mesh

New creates a mesh instance. Call Start() to begin gossip.

func (*Mesh) ActivePeers

func (m *Mesh) ActivePeers() []Peer

ActivePeers returns only peers that are verified or trusted.

func (*Mesh) AddSeed

func (m *Mesh) AddSeed(p Peer)

AddSeed injects a known seed peer (from nodes.yaml). Seed peers start as Trusted.

func (*Mesh) Peers

func (m *Mesh) Peers() []Peer

Peers returns a snapshot of all known peers sorted by name.

func (*Mesh) Start

func (m *Mesh) Start(ctx context.Context) error

Start begins listening for gossip and broadcasting our peer list.

func (*Mesh) Stop

func (m *Mesh) Stop()

Stop gracefully shuts down the mesh.

func (*Mesh) Trust

func (m *Mesh) Trust(id string) error

Trust promotes a discovered/verified peer to trusted status.

type Peer

type Peer struct {
	Name        string    `json:"name"`
	Hostname    string    `json:"hostname"`
	Port        int       `json:"port"`
	StableID    string    `json:"stable_id"`
	State       PeerState `json:"state"`
	Source      string    `json:"source"` // "config", "gossip", "mdns", "peer-exchange"
	FirstSeen   time.Time `json:"first_seen"`
	LastSeen    time.Time `json:"last_seen"`
	MissedPings int       `json:"missed_pings"`
	Generation  uint64    `json:"generation"` // Lamport-style monotonic counter
}

Peer represents a node in the mesh.

type PeerState

type PeerState int

PeerState tracks a discovered peer's lifecycle.

const (
	// PeerDiscovered means we heard about this node but haven't verified it.
	PeerDiscovered PeerState = iota
	// PeerVerified means SSH probe succeeded at least once.
	PeerVerified
	// PeerTrusted means the operator explicitly promoted this node.
	PeerTrusted
	// PeerSuspect means the node missed consecutive heartbeats.
	PeerSuspect
	// PeerDead means the node has been unreachable beyond the eviction window.
	PeerDead
)

func (PeerState) String

func (s PeerState) String() string