discovery

package
v0.115.0-nightly Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 20, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const PeerExchangeProtocol = "/orama/peer-exchange/1.0.0"

Protocol ID for peer exchange

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	DiscoveryInterval time.Duration
	MaxConnections    int
}

Config contains discovery configuration

type Manager

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

Manager handles peer discovery operations without a DHT dependency. Note: The constructor intentionally accepts a second parameter of type interface{} to remain source-compatible with previous call sites that passed a DHT instance. The value is ignored.

func NewManager

func NewManager(h host.Host, _ interface{}, logger *zap.Logger) *Manager

NewManager creates a new discovery manager.

The second parameter is intentionally typed as interface{} so callers that previously passed a DHT instance can continue to do so; the value is ignored.

func NewManagerSimple

func NewManagerSimple(h host.Host, logger *zap.Logger) *Manager

NewManagerSimple creates a manager with a cleaner signature (host + logger).

func (*Manager) Start

func (d *Manager) Start(config Config) error

Start begins periodic peer discovery

func (*Manager) StartProtocolHandler added in v0.51.1

func (d *Manager) StartProtocolHandler()

StartProtocolHandler registers the peer exchange protocol handler on the host

func (*Manager) Stop

func (d *Manager) Stop()

Stop stops peer discovery

func (*Manager) TriggerPeerExchange added in v0.53.2

func (d *Manager) TriggerPeerExchange(ctx context.Context) int

TriggerPeerExchange manually triggers peer exchange with all connected peers This is useful for pre-startup cluster discovery to populate the peerstore with RQLite metadata

type MetadataProvider

type MetadataProvider interface {
	ProvideMetadata() *RQLiteNodeMetadata
}

MetadataProvider is implemented by subsystems that can supply node metadata. The publisher calls Provide() every cycle and stores the result in the peerstore.

type MetadataPublisher

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

MetadataPublisher periodically writes local node metadata to the peerstore so it is included in every peer exchange response. This decouples metadata production (lifecycle, RQLite status, service health) from the exchange protocol itself.

func NewMetadataPublisher

func NewMetadataPublisher(h host.Host, provider MetadataProvider, interval time.Duration, logger *zap.Logger) *MetadataPublisher

NewMetadataPublisher creates a publisher that writes metadata every interval.

func (*MetadataPublisher) PublishNow

func (p *MetadataPublisher) PublishNow()

PublishNow performs a single immediate metadata publish. Useful after lifecycle transitions or other state changes.

func (*MetadataPublisher) Start

func (p *MetadataPublisher) Start(ctx context.Context)

Start begins the periodic publish loop. It blocks until ctx is cancelled.

type NamespaceStatus

type NamespaceStatus struct {
	Name   string `json:"name"`
	Status string `json:"status"` // "healthy", "degraded", "recovering"
}

NamespaceStatus represents a namespace's status on a node.

type PeerExchangeRequest added in v0.51.1

type PeerExchangeRequest struct {
	Limit int `json:"limit"`
}

PeerExchangeRequest represents a request for peer information

type PeerExchangeResponse added in v0.51.1

type PeerExchangeResponse struct {
	Peers          []PeerInfo          `json:"peers"`
	RQLiteMetadata *RQLiteNodeMetadata `json:"rqlite_metadata,omitempty"`
}

PeerExchangeResponse represents a list of peers to exchange

type PeerExchangeResponseV2 added in v0.53.2

type PeerExchangeResponseV2 struct {
	Peers          []PeerInfo          `json:"peers"`
	RQLiteMetadata *RQLiteNodeMetadata `json:"rqlite_metadata,omitempty"`
}

PeerExchangeResponseV2 extends the original response with RQLite metadata. Kept for backward compatibility — the V1 PeerExchangeResponse in discovery.go already includes the same RQLiteMetadata field, so this is effectively unused.

type PeerInfo added in v0.51.1

type PeerInfo struct {
	ID    string   `json:"id"`
	Addrs []string `json:"addrs"`
}

PeerInfo contains peer identity and addresses

type RQLiteNodeMetadata added in v0.53.2

type RQLiteNodeMetadata struct {
	NodeID         string    `json:"node_id"`         // RQLite node ID (raft address)
	RaftAddress    string    `json:"raft_address"`    // Raft port address (e.g., "10.0.0.1:7001")
	HTTPAddress    string    `json:"http_address"`    // HTTP API address (e.g., "10.0.0.1:5001")
	NodeType       string    `json:"node_type"`       // Node type identifier
	RaftLogIndex   uint64    `json:"raft_log_index"`  // Current Raft log index (for data comparison)
	LastSeen       time.Time `json:"last_seen"`       // Updated on every announcement
	ClusterVersion string    `json:"cluster_version"` // For compatibility checking

	// PeerID is the LibP2P peer ID of the node. Used for metadata authentication:
	// on receipt, the receiver verifies PeerID == stream sender to prevent spoofing.
	PeerID string `json:"peer_id,omitempty"`

	// WireGuardIP is the node's WireGuard VPN address (e.g., "10.0.0.1").
	WireGuardIP string `json:"wireguard_ip,omitempty"`

	// LifecycleState is the node's current lifecycle state:
	// "joining", "active", "draining", or "maintenance".
	// Zero value (empty string) from old nodes is treated as "active".
	LifecycleState string `json:"lifecycle_state,omitempty"`

	// MaintenanceTTL is the time at which maintenance mode expires.
	// Only meaningful when LifecycleState == "maintenance".
	MaintenanceTTL time.Time `json:"maintenance_ttl,omitempty"`

	// Services reports the status of each service running on the node.
	Services map[string]*ServiceStatus `json:"services,omitempty"`

	// Namespaces reports the status of each namespace on the node.
	Namespaces map[string]*NamespaceStatus `json:"namespaces,omitempty"`

	// BinaryVersion is the node's binary version string (e.g., "1.2.3").
	BinaryVersion string `json:"binary_version,omitempty"`
}

RQLiteNodeMetadata contains node information announced via LibP2P peer exchange. This struct is the single source of truth for node metadata propagated through the cluster. Go's json.Unmarshal silently ignores unknown fields, so old nodes reading metadata from new nodes simply skip the new fields — no protocol version change is needed.

func (*RQLiteNodeMetadata) EffectiveLifecycleState

func (m *RQLiteNodeMetadata) EffectiveLifecycleState() string

EffectiveLifecycleState returns the lifecycle state, defaulting to "active" for old nodes that don't populate the field.

func (*RQLiteNodeMetadata) IsAvailable

func (m *RQLiteNodeMetadata) IsAvailable() bool

IsAvailable returns true if the node is in a state that can serve requests.

func (*RQLiteNodeMetadata) IsInMaintenance

func (m *RQLiteNodeMetadata) IsInMaintenance() bool

IsInMaintenance returns true if the node has announced maintenance mode.

func (*RQLiteNodeMetadata) IsMaintenanceExpired

func (m *RQLiteNodeMetadata) IsMaintenanceExpired() bool

IsMaintenanceExpired returns true if the node is in maintenance and the TTL has passed. Used by the leader's health monitor to enforce expiry.

type ServiceStatus

type ServiceStatus struct {
	Name    string `json:"name"`              // e.g. "rqlite", "gateway", "olric"
	Running bool   `json:"running"`           // whether the process is up
	Healthy bool   `json:"healthy"`           // whether it passed its health check
	Message string `json:"message,omitempty"` // optional detail ("leader", "follower", etc.)
}

ServiceStatus represents the health of an individual service on a node.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL