registry

package
v1.5.0-rc1 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client talks to a registry server over TCP (optionally TLS). It automatically reconnects if the connection drops.

func Dial 

func Dial(addr string) (*Client, error)

func DialTLS 

func DialTLS(addr string, tlsConfig *tls.Config) (*Client, error)

DialTLS connects to a registry server over TLS. A non-nil tlsConfig is required. For certificate pinning, use DialTLSPinned.

func DialTLSPinned 

func DialTLSPinned(addr, fingerprint string) (*Client, error)

DialTLSPinned connects to a registry server over TLS with certificate pinning. The fingerprint is a hex-encoded SHA-256 hash of the server's DER-encoded certificate.

func (*Client) CheckTrust added in v1.4.0 

func (c *Client) CheckTrust(nodeA, nodeB uint32) (bool, error)

CheckTrust checks if a trust pair or shared network exists between two nodes.

func (*Client) Close 

func (c *Client) Close() error

func (*Client) CreateNetwork 

func (c *Client) CreateNetwork(nodeID uint32, name, joinRule, token, adminToken string, networkAdminToken ...string) (map[string]interface{}, error)

func (*Client) DeleteNetwork added in v1.5.1 

func (c *Client) DeleteNetwork(networkID uint16, adminToken string, nodeID ...uint32) (map[string]interface{}, error)

func (*Client) DemoteMember added in v1.5.1 

func (c *Client) DemoteMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

DemoteMember demotes an admin to member. Only the owner can demote.

func (*Client) Deregister 

func (c *Client) Deregister(nodeID uint32) (map[string]interface{}, error)

func (*Client) GetKeyInfo added in v1.5.1 

func (c *Client) GetKeyInfo(nodeID uint32) (map[string]interface{}, error)

GetKeyInfo returns key lifecycle metadata for a node.

func (*Client) GetMemberRole added in v1.5.1 

func (c *Client) GetMemberRole(networkID uint16, targetNodeID uint32) (map[string]interface{}, error)

GetMemberRole returns the RBAC role of a node in a network.

func (*Client) GetNetworkPolicy added in v1.5.1 

func (c *Client) GetNetworkPolicy(networkID uint16) (map[string]interface{}, error)

GetNetworkPolicy returns the policy for a given network.

func (*Client) GetPoloScore added in v1.3.0 

func (c *Client) GetPoloScore(nodeID uint32) (int, error)

GetPoloScore retrieves the current polo score for a node.

func (*Client) Heartbeat 

func (c *Client) Heartbeat(nodeID uint32) (map[string]interface{}, error)

func (*Client) InviteToNetwork added in v1.5.1 

func (c *Client) InviteToNetwork(networkID uint16, inviterID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

InviteToNetwork stores a pending invite for a target node to join an invite-only network.

func (*Client) JoinNetwork 

func (c *Client) JoinNetwork(nodeID uint32, networkID uint16, token string, inviterID uint32, adminToken string) (map[string]interface{}, error)

func (*Client) KickMember added in v1.5.1 

func (c *Client) KickMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

KickMember removes a member from a network. Requires owner or admin role.

func (*Client) LeaveNetwork 

func (c *Client) LeaveNetwork(nodeID uint32, networkID uint16, adminToken string) (map[string]interface{}, error)

func (*Client) ListNetworks 

func (c *Client) ListNetworks() (map[string]interface{}, error)

func (*Client) ListNodes 

func (c *Client) ListNodes(networkID uint16, adminToken ...string) (map[string]interface{}, error)

func (*Client) Lookup 

func (c *Client) Lookup(nodeID uint32) (map[string]interface{}, error)

func (*Client) PollHandshakes 

func (c *Client) PollHandshakes(nodeID uint32) (map[string]interface{}, error)

PollHandshakes retrieves and clears pending handshake requests for a node. H3 fix: includes a signature to prove node identity.

func (*Client) PollInvites added in v1.5.1 

func (c *Client) PollInvites(nodeID uint32) (map[string]interface{}, error)

PollInvites returns and clears pending network invites for a node. Signed.

func (*Client) PromoteMember added in v1.5.1 

func (c *Client) PromoteMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

PromoteMember promotes a network member to admin. Only the owner can promote.

func (*Client) Punch 

func (c *Client) Punch(requesterID, nodeA, nodeB uint32) (map[string]interface{}, error)

func (*Client) Register 

func (c *Client) Register(listenAddr string) (map[string]interface{}, error)

func (*Client) RegisterWithKey 

func (c *Client) RegisterWithKey(listenAddr, publicKeyB64, owner string, lanAddrs []string) (map[string]interface{}, error)

RegisterWithKey re-registers using an existing Ed25519 public key. The registry returns the same node_id if the key is known. lanAddrs are the node's LAN addresses for same-network peer detection.

func (*Client) RegisterWithOwner 

func (c *Client) RegisterWithOwner(listenAddr, owner string) (map[string]interface{}, error)

RegisterWithOwner registers a new node with an owner identifier (email/name) for key rotation recovery.

func (*Client) RenameNetwork added in v1.5.1 

func (c *Client) RenameNetwork(networkID uint16, name, adminToken string, nodeID ...uint32) (map[string]interface{}, error)

func (*Client) ReportTrust 

func (c *Client) ReportTrust(nodeID, peerID uint32) (map[string]interface{}, error)

func (*Client) RequestHandshake 

func (c *Client) RequestHandshake(fromNodeID, toNodeID uint32, justification, signatureB64 string) (map[string]interface{}, error)

RequestHandshake relays a handshake request through the registry to a target node. This works even for private nodes — no IP exposure needed. M12 fix: includes a signature to prove sender identity.

func (*Client) Resolve 

func (c *Client) Resolve(nodeID, requesterID uint32) (map[string]interface{}, error)

func (*Client) ResolveHostname 

func (c *Client) ResolveHostname(hostname string) (map[string]interface{}, error)

ResolveHostname resolves a hostname to node info (node_id, address, public flag).

func (*Client) ResolveHostnameAs added in v1.4.0 

func (c *Client) ResolveHostnameAs(requesterID uint32, hostname string) (map[string]interface{}, error)

ResolveHostnameAs resolves a hostname with a requester_id for privacy checks. Private nodes require the requester to have a trust pair or shared network.

func (*Client) RespondHandshake 

func (c *Client) RespondHandshake(nodeID, peerID uint32, accept bool, signatureB64 string) (map[string]interface{}, error)

RespondHandshake approves or rejects a relayed handshake request. If accepted, the registry creates a mutual trust pair. M12 fix: includes a signature to prove responder identity.

func (*Client) RespondInvite added in v1.5.1 

func (c *Client) RespondInvite(nodeID uint32, networkID uint16, accept bool) (map[string]interface{}, error)

RespondInvite accepts or rejects a pending network invite. Signed.

func (*Client) RevokeTrust 

func (c *Client) RevokeTrust(nodeID, peerID uint32) (map[string]interface{}, error)

func (*Client) RotateKey 

func (c *Client) RotateKey(nodeID uint32, signatureB64, newPubKeyB64 string) (map[string]interface{}, error)

RotateKey requests a key rotation for a node. Requires a signature proving ownership of the current key and the new public key.

func (*Client) Send 

func (c *Client) Send(msg map[string]interface{}) (map[string]interface{}, error)

func (*Client) SetHostname 

func (c *Client) SetHostname(nodeID uint32, hostname string) (map[string]interface{}, error)

SetHostname sets or clears the hostname for a node. An empty hostname clears the current hostname.

func (*Client) SetKeyExpiry added in v1.5.1 

func (c *Client) SetKeyExpiry(nodeID uint32, expiresAt time.Time) (map[string]interface{}, error)

SetKeyExpiry sets the key expiry time for a node. Requires signature.

func (*Client) SetNetworkPolicy added in v1.5.1 

func (c *Client) SetNetworkPolicy(networkID uint16, policy map[string]interface{}, adminToken string) (map[string]interface{}, error)

SetNetworkPolicy sets or updates a network's policy. Requires owner/admin role or admin token.

func (*Client) SetPoloScore added in v1.3.0 

func (c *Client) SetPoloScore(nodeID uint32, poloScore int) (map[string]interface{}, error)

SetPoloScore sets the polo score of a node to a specific value.

func (*Client) SetSigner 

func (c *Client) SetSigner(fn func(challenge string) string)

SetSigner sets a signing function for authenticated registry operations (H3 fix). The signer receives a challenge string and returns a base64-encoded Ed25519 signature.

func (*Client) SetTags 

func (c *Client) SetTags(nodeID uint32, tags []string) (map[string]interface{}, error)

SetTags sets the capability tags for a node.

func (*Client) SetTaskExec 

func (c *Client) SetTaskExec(nodeID uint32, enabled bool) (map[string]interface{}, error)

func (*Client) SetVisibility 

func (c *Client) SetVisibility(nodeID uint32, public bool) (map[string]interface{}, error)

func (*Client) UpdatePoloScore added in v1.3.0 

func (c *Client) UpdatePoloScore(nodeID uint32, delta int) (map[string]interface{}, error)

UpdatePoloScore adjusts the polo score of a node by the given delta. Delta can be positive (increase polo score) or negative (decrease polo score).

type DashboardEdge 

type DashboardEdge struct {
	Source string `json:"source"`
	Target string `json:"target"`
}

DashboardEdge represents a trust relationship between two nodes.

type DashboardNetwork 

type DashboardNetwork struct {
	ID            uint16 `json:"id"`
	Members       int    `json:"members"`
	OnlineMembers int    `json:"online_members"`
}

DashboardNetwork is a public-safe view of a network for the dashboard.

type DashboardNode 

type DashboardNode struct {
	Address    string   `json:"address"`
	Tags       []string `json:"tags"`
	Online     bool     `json:"online"`
	TrustLinks int      `json:"trust_links"`
	TaskExec   bool     `json:"task_exec"`
	PoloScore  int      `json:"polo_score"`
}

DashboardNode is a public-safe view of a node for the dashboard.

type DashboardStats 

type DashboardStats struct {
	TotalNodes      int                `json:"total_nodes"`
	ActiveNodes     int                `json:"active_nodes"`
	TotalTrustLinks int                `json:"total_trust_links"`
	TotalRequests   int64              `json:"total_requests"`
	UniqueTags      int                `json:"unique_tags"`
	TaskExecutors   int                `json:"task_executors"`
	Networks        []DashboardNetwork `json:"networks"`
	Nodes           []DashboardNode    `json:"nodes"`
	Edges           []DashboardEdge    `json:"edges"`
	UptimeSecs      int64              `json:"uptime_secs"`
}

DashboardStats is the public-safe data returned by the dashboard API.

type HandshakeRelayMsg 

type HandshakeRelayMsg struct {
	FromNodeID    uint32    `json:"from_node_id"`
	Justification string    `json:"justification"`
	Timestamp     time.Time `json:"timestamp"`
}

HandshakeRelayMsg is a handshake request stored in the registry's relay inbox.

type HandshakeResponseMsg 

type HandshakeResponseMsg struct {
	FromNodeID uint32    `json:"from_node_id"` // the node that approved/rejected
	Accept     bool      `json:"accept"`
	Timestamp  time.Time `json:"timestamp"`
}

HandshakeResponseMsg is a handshake approval/rejection stored for the original requester.

type KeyInfo added in v1.5.1 

type KeyInfo struct {
	CreatedAt   time.Time `json:"created_at"`
	RotatedAt   time.Time `json:"rotated_at,omitempty"` // zero if never rotated
	RotateCount int       `json:"rotate_count"`
	ExpiresAt   time.Time `json:"expires_at,omitempty"` // zero = no expiry
}

KeyInfo tracks key lifecycle metadata for compliance and trust decisions.

type NetworkInfo 

type NetworkInfo struct {
	ID          uint16
	Name        string
	JoinRule    string
	Token       string // for token-gated networks
	Members     []uint32
	MemberRoles map[uint32]Role // per-member RBAC roles
	AdminToken  string          // per-network admin token (optional)
	Policy      NetworkPolicy   // network policy (membership limits, port restrictions)
	Created     time.Time
}

type NetworkInvite added in v1.5.1 

type NetworkInvite struct {
	NetworkID uint16    `json:"network_id"`
	InviterID uint32    `json:"inviter_id"`
	Timestamp time.Time `json:"timestamp"`
}

NetworkInvite is a pending network invitation stored in the registry's invite inbox.

type NetworkPolicy added in v1.5.1 

type NetworkPolicy struct {
	MaxMembers   int      `json:"max_members"`   // 0 = unlimited
	AllowedPorts []uint16 `json:"allowed_ports"` // empty = all ports allowed
	Description  string   `json:"description"`   // human-readable network description
}

NetworkPolicy defines constraints and metadata for a network.

type NodeInfo 

type NodeInfo struct {
	ID        uint32
	Owner     string // email or identifier (for key rotation)
	PublicKey []byte
	RealAddr  string
	Networks  []uint16
	LastSeen  time.Time
	Public    bool     // if true, endpoint is visible in lookup/list_nodes
	Hostname  string   // unique hostname for discovery (empty = none)
	Tags      []string // capability tags (e.g., "webserver", "assistant")
	PoloScore int      // polo score for reputation system (default: 0)
	TaskExec  bool     // if true, node advertises task execution capability
	LANAddrs  []string // LAN addresses for same-network peer detection
	KeyMeta   KeyInfo  // key lifecycle metadata
}

type OperationRateLimiter added in v1.5.1 

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

OperationRateLimiter provides per-operation rate limiting using separate token buckets for each operation category. Each category has its own rate.

func NewOperationRateLimiter added in v1.5.1 

func NewOperationRateLimiter() *OperationRateLimiter

NewOperationRateLimiter creates a rate limiter with per-operation categories.

func (*OperationRateLimiter) AddCategory added in v1.5.1 

func (orl *OperationRateLimiter) AddCategory(name string, rate int, window time.Duration)

AddCategory registers a rate limit for an operation category.

func (*OperationRateLimiter) Allow added in v1.5.1 

func (orl *OperationRateLimiter) Allow(category, ip string) bool

Allow checks if a request from the given IP is allowed for the given category. Returns true if the category is not registered (no limit configured).

func (*OperationRateLimiter) Cleanup added in v1.5.1 

func (orl *OperationRateLimiter) Cleanup()

Cleanup removes stale buckets from all categories.

func (*OperationRateLimiter) SetClock added in v1.5.1 

func (orl *OperationRateLimiter) SetClock(fn func() time.Time)

SetClock overrides the time source for all categories (for testing).

type RateLimiter 

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

RateLimiter tracks per-IP registration attempts using a token bucket.

func NewRateLimiter 

func NewRateLimiter(rate int, window time.Duration) *RateLimiter

NewRateLimiter creates a rate limiter allowing rate requests per window per IP.

func (*RateLimiter) Allow 

func (rl *RateLimiter) Allow(ip string) bool

Allow checks if a request from the given IP is allowed. Uses a sliding window: tokens refill proportionally to elapsed time.

func (*RateLimiter) BucketCount 

func (rl *RateLimiter) BucketCount() int

BucketCount returns the number of tracked IPs (for testing).

func (*RateLimiter) Cleanup 

func (rl *RateLimiter) Cleanup()

Cleanup removes stale buckets. Called periodically.

func (*RateLimiter) HasBucket 

func (rl *RateLimiter) HasBucket(ip string) bool

HasBucket returns whether a given IP has an active bucket (for testing).

func (*RateLimiter) SetClock 

func (rl *RateLimiter) SetClock(fn func() time.Time)

SetClock overrides the time source (for testing).

type Role added in v1.5.1 

type Role string

Role represents a member's permission level within a network. 

const (
	RoleOwner  Role = "owner"  // created the network, full control
	RoleAdmin  Role = "admin"  // can invite, remove members, change settings
	RoleMember Role = "member" // can communicate, cannot manage
)

type Server 

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

func New 

func New(beaconAddr string) *Server

func NewWithStore 

func NewWithStore(beaconAddr, storePath string) *Server

func (*Server) Addr 

func (s *Server) Addr() net.Addr

Addr returns the server's bound address. Only valid after Ready() fires.

func (*Server) Close 

func (s *Server) Close() error

func (*Server) ConnCount added in v1.5.1 

func (s *Server) ConnCount() int64

ConnCount returns the current number of active connections (for testing).

func (*Server) GetDashboardStats 

func (s *Server) GetDashboardStats() DashboardStats

GetDashboardStats returns public-safe statistics for the dashboard. No IPs, keys, or endpoints are exposed.

func (*Server) IsStandby 

func (s *Server) IsStandby() bool

IsStandby returns true if this server is running in standby mode.

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe(addr string) error

func (*Server) Ready 

func (s *Server) Ready() <-chan struct{}

Ready returns a channel that is closed when the server has bound its port.

func (*Server) Reap added in v1.4.0 

func (s *Server) Reap()

Reap triggers stale node and beacon cleanup (for testing).

func (*Server) RunStandby 

func (s *Server) RunStandby(primaryAddr string)

RunStandby connects to a primary registry and receives replicated snapshots. On each snapshot, the standby updates its own state and persists to storePath. This blocks until the connection is lost, then retries with backoff.

func (*Server) ServeDashboard 

func (s *Server) ServeDashboard(addr string) error

ServeDashboard starts an HTTP server serving the dashboard UI and stats API.

func (*Server) SetAdminToken 

func (s *Server) SetAdminToken(token string)

SetAdminToken sets the admin token required for network creation. If empty, network creation is disabled entirely (secure by default).

func (*Server) SetClock added in v1.4.0 

func (s *Server) SetClock(fn func() time.Time)

SetClock overrides the time source for testing.

func (*Server) SetMaxConnections added in v1.5.1 

func (s *Server) SetMaxConnections(max int64)

SetMaxConnections overrides the default connection limit (for testing).

func (*Server) SetOperationRateLimiterClock added in v1.5.1 

func (s *Server) SetOperationRateLimiterClock(fn func() time.Time)

SetOperationRateLimiterClock overrides the time source for per-operation rate limits (for testing).

func (*Server) SetReplicationToken 

func (s *Server) SetReplicationToken(token string)

SetReplicationToken sets the token required for subscribe_replication (H4 fix). If empty, replication subscription is disabled.

func (*Server) SetStandby 

func (s *Server) SetStandby(primary string)

SetStandby configures this server as a standby that receives replicated state from a primary. In standby mode, write operations are rejected.

func (*Server) SetTLS 

func (s *Server) SetTLS(certFile, keyFile string) error

SetTLS configures the registry to use TLS with the given cert and key files. If certFile is empty, a self-signed certificate is generated automatically.

func (*Server) TriggerSnapshot added in v1.3.0 

func (s *Server) TriggerSnapshot() error

TriggerSnapshot manually triggers a snapshot save. This is useful for testing and for ensuring data is persisted before shutdown. Returns an error if the save fails, or nil if there's no storePath configured.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.