Snider/Mining
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

ax(node): replace prose comments with usage examples in PeerRegistry

Browse source 
AX Principle 2: comments that restate the type signature add zero
information. Replaced all prose-description comments on PeerRegistry
methods with concrete call-site examples that show real usage.

Co-Authored-By: Charon <charon@lethean.io>
This commit is contained in:
Claude 2026-04-02 09:18:29 +01:00
parent c39c9b9ff8
commit 35c178ce05
No known key found for this signature in database
GPG key ID: AF404715446AEB41
1 changed files with 19 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
pkg/node/peer.go
View file

@ -121,7 +121,8 @@ const (
scoreWeight = 1.2
)
// NewPeerRegistry creates a new PeerRegistry, loading existing peers if available.
// registry, err := node.NewPeerRegistry()
// if err != nil { return err }
func NewPeerRegistry() (*PeerRegistry, error) {
peersPath, err := xdg.ConfigFile("lethean-desktop/peers.json")
if err != nil {
@ -131,8 +132,8 @@ func NewPeerRegistry() (*PeerRegistry, error) {
return NewPeerRegistryWithPath(peersPath)
}
// NewPeerRegistryWithPath creates a new PeerRegistry with a custom path.
// This is primarily useful for testing to avoid xdg path caching issues.
// registry, err := node.NewPeerRegistryWithPath("/tmp/test-peers.json")
// used in tests to avoid xdg path caching
func NewPeerRegistryWithPath(peersPath string) (*PeerRegistry, error) {
pr := &PeerRegistry{
peers: make(map[string]*Peer),
@ -192,10 +193,8 @@ func (r *PeerRegistry) IsPublicKeyAllowed(publicKey string) bool {
return r.allowedPublicKeys[publicKey]
}
// IsPeerAllowed checks if a peer is allowed to connect based on auth mode.
// Returns true if:
// - AuthMode is Open (allow all)
// - AuthMode is Allowlist AND (peer is pre-registered OR public key is allowlisted)
// if !registry.IsPeerAllowed(payload.Identity.ID, payload.Identity.PublicKey) { conn.Close(); return }
// true when Open mode, or Allowlist mode with pre-registered peer or allowlisted key
func (r *PeerRegistry) IsPeerAllowed(peerID string, publicKey string) bool {
r.allowedPublicKeyMutex.RLock()
authMode := r.authMode
@ -220,7 +219,7 @@ func (r *PeerRegistry) IsPeerAllowed(peerID string, publicKey string) bool {
return keyAllowed
}
// ListAllowedPublicKeys returns all allowlisted public keys.
// keys := registry.ListAllowedPublicKeys() // for display or export
func (r *PeerRegistry) ListAllowedPublicKeys() []string {
r.allowedPublicKeyMutex.RLock()
defer r.allowedPublicKeyMutex.RUnlock()
@ -268,7 +267,7 @@ func (r *PeerRegistry) AddPeer(peer *Peer) error {
return r.save()
}
// UpdatePeer updates an existing peer's information.
// registry.UpdatePeer(peer) // after handshake completes and real ID is known
// Note: Persistence is debounced. Call Close() to flush before shutdown.
func (r *PeerRegistry) UpdatePeer(peer *Peer) error {
r.mu.Lock()
@ -285,7 +284,7 @@ func (r *PeerRegistry) UpdatePeer(peer *Peer) error {
return r.save()
}
// RemovePeer removes a peer from the registry.
// registry.RemovePeer(peer.ID) // on manual disconnect or ban
// Note: Persistence is debounced. Call Close() to flush before shutdown.
func (r *PeerRegistry) RemovePeer(id string) error {
r.mu.Lock()
@ -318,7 +317,7 @@ func (r *PeerRegistry) GetPeer(id string) *Peer {
return &peerCopy
}
// ListPeers returns all registered peers.
// for _, peer := range registry.ListPeers() { log(peer.ID, peer.Role) }
func (r *PeerRegistry) ListPeers() []*Peer {
r.mu.RLock()
defer r.mu.RUnlock()
@ -331,7 +330,7 @@ func (r *PeerRegistry) ListPeers() []*Peer {
return peers
}
// UpdateMetrics updates a peer's performance metrics.
// registry.UpdateMetrics(peer.ID, rtt, peer.GeoKM, peer.Hops) // after PingPeer
// Note: Persistence is debounced. Call Close() to flush before shutdown.
func (r *PeerRegistry) UpdateMetrics(id string, pingMS, geoKM float64, hops int) error {
r.mu.Lock()
@ -353,7 +352,7 @@ func (r *PeerRegistry) UpdateMetrics(id string, pingMS, geoKM float64, hops int)
return r.save()
}
// UpdateScore updates a peer's reliability score.
// registry.UpdateScore(peer.ID, 75.0) // clamps to 0-100
// Note: Persistence is debounced. Call Close() to flush before shutdown.
func (r *PeerRegistry) UpdateScore(id string, score float64) error {
r.mu.Lock()
@ -378,7 +377,8 @@ func (r *PeerRegistry) UpdateScore(id string, score float64) error {
return r.save()
}
// SetConnected updates a peer's connection state.
// registry.SetConnected(peer.ID, true) // on connect
// registry.SetConnected(peer.ID, false) // on disconnect or error
func (r *PeerRegistry) SetConnected(id string, connected bool) {
r.mu.Lock()
defer r.mu.Unlock()
@ -401,7 +401,7 @@ const (
ScoreDefault = 50.0 // Default score for new peers
)
// RecordSuccess records a successful interaction with a peer, improving their score.
// registry.RecordSuccess(peer.ID) // after a successful response
func (r *PeerRegistry) RecordSuccess(id string) {
r.mu.Lock()
peer, exists := r.peers[id]
@ -416,7 +416,7 @@ func (r *PeerRegistry) RecordSuccess(id string) {
r.save()
}
// RecordFailure records a failed interaction with a peer, reducing their score.
// registry.RecordFailure(peer.ID) // after a failed send or error response
func (r *PeerRegistry) RecordFailure(id string) {
r.mu.Lock()
peer, exists := r.peers[id]
@ -437,7 +437,7 @@ func (r *PeerRegistry) RecordFailure(id string) {
})
}
// RecordTimeout records a timeout when communicating with a peer.
// registry.RecordTimeout(peer.ID) // after a request deadline exceeded
func (r *PeerRegistry) RecordTimeout(id string) {
r.mu.Lock()
peer, exists := r.peers[id]
@ -458,7 +458,7 @@ func (r *PeerRegistry) RecordTimeout(id string) {
})
}
// GetPeersByScore returns peers sorted by score (highest first).
// for _, peer := range registry.GetPeersByScore() { log(peer.ID, peer.Score) }
func (r *PeerRegistry) GetPeersByScore() []*Peer {
r.mu.RLock()
defer r.mu.RUnlock()
@ -533,7 +533,7 @@ func (r *PeerRegistry) SelectNearestPeers(n int) []*Peer {
return peers
}
// GetConnectedPeers returns all currently connected peers.
// for _, peer := range registry.GetConnectedPeers() { ctrl.GetRemoteStats(peer.ID) }
func (r *PeerRegistry) GetConnectedPeers() []*Peer {
r.mu.RLock()
defer r.mu.RUnlock()