Documentation
¶
Index ¶
Constants ¶
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 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 ¶
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 ¶
NewManagerSimple creates a manager with a cleaner signature (host + logger).
func (*Manager) StartProtocolHandler ¶ added in v0.51.1
func (d *Manager) StartProtocolHandler()
StartProtocolHandler registers the peer exchange protocol handler on the host
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 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.