From 2d63a8ba18e253a3957338f2c4b667b4cd885c32 Mon Sep 17 00:00:00 2001 From: Virgil Date: Mon, 30 Mar 2026 19:32:26 +0000 Subject: [PATCH] refactor(node): add AX-native aliases for component and path APIs Co-Authored-By: Virgil --- docs/discovery.md | 2 +- docs/identity.md | 2 +- logging/logger.go | 11 +++++++++-- logging/logger_test.go | 11 ++++++++--- node/identity.go | 14 +++++++++----- node/peer.go | 14 +++++++++----- node/worker.go | 11 +++++++++-- specs/logging.md | 3 ++- specs/node.md | 9 ++++++--- 9 files changed, 54 insertions(+), 23 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index a01f322..3423165 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -146,7 +146,7 @@ This also updates `LastSeen` and triggers a KD-tree rebuild. ```go // Create registry, err := node.NewPeerRegistry() // XDG paths -registry, err := node.NewPeerRegistryWithPath(path) // Custom path (testing) +registry, err := node.NewPeerRegistryFromPath(path) // Custom path (testing) // CRUD err := registry.AddPeer(peer) diff --git a/docs/identity.md b/docs/identity.md index c16a559..b102683 100644 --- a/docs/identity.md +++ b/docs/identity.md @@ -53,7 +53,7 @@ Internally this calls `stmf.GenerateKeyPair()` from the Borg library to produce ### Custom Paths (Testing) ```go -nm, err := node.NewNodeManagerWithPaths( +nm, err := node.NewNodeManagerFromPaths( "/tmp/test/private.key", "/tmp/test/node.json", ) diff --git a/logging/logger.go b/logging/logger.go index d162458..739b54d 100644 --- a/logging/logger.go +++ b/logging/logger.go @@ -87,8 +87,10 @@ func New(cfg Config) *Logger { } } -// WithComponent returns a new Logger with the specified component name. -func (l *Logger) WithComponent(component string) *Logger { +// ComponentLogger returns a new Logger scoped to one component. +// +// transportLogger := logger.ComponentLogger("transport") +func (l *Logger) ComponentLogger(component string) *Logger { return &Logger{ output: l.output, level: l.level, @@ -96,6 +98,11 @@ func (l *Logger) WithComponent(component string) *Logger { } } +// Deprecated: use ComponentLogger. +func (l *Logger) WithComponent(component string) *Logger { + return l.ComponentLogger(component) +} + // SetLevel sets the minimum log level. func (l *Logger) SetLevel(level Level) { l.mu.Lock() diff --git a/logging/logger_test.go b/logging/logger_test.go index 38f8cb9..0850cde 100644 --- a/logging/logger_test.go +++ b/logging/logger_test.go @@ -75,7 +75,7 @@ func TestLogger_WithFields_Good(t *testing.T) { } } -func TestLogger_WithComponent_Good(t *testing.T) { +func TestLogger_ConfigComponent_Good(t *testing.T) { var buf bytes.Buffer logger := New(Config{ Output: &buf, @@ -91,20 +91,25 @@ func TestLogger_WithComponent_Good(t *testing.T) { } } -func TestLogger_DerivedComponent_Good(t *testing.T) { +func TestLogger_ComponentLogger_Good(t *testing.T) { var buf bytes.Buffer parent := New(Config{ Output: &buf, Level: LevelInfo, }) - child := parent.WithComponent("ChildComponent") + child := parent.ComponentLogger("ChildComponent") child.Info("child message") + alias := parent.WithComponent("AliasComponent") + alias.Info("alias message") output := buf.String() if !core.Contains(output, "[ChildComponent]") { t.Error("Derived component name should appear") } + if !core.Contains(output, "[AliasComponent]") { + t.Error("Compatibility alias should preserve the component name") + } } func TestLogger_Formatted_Good(t *testing.T) { diff --git a/node/identity.go b/node/identity.go index 5ec6a88..a6cb702 100644 --- a/node/identity.go +++ b/node/identity.go @@ -99,14 +99,13 @@ func NewNodeManager() (*NodeManager, error) { return nil, core.E("NodeManager.New", "failed to get config path", err) } - return NewNodeManagerWithPaths(keyPath, configPath) + return NewNodeManagerFromPaths(keyPath, configPath) } -// NewNodeManagerWithPaths creates a NodeManager with custom paths. -// This is primarily useful for testing to avoid xdg path caching issues. +// NewNodeManagerFromPaths creates a NodeManager using explicit key and config paths. // -// nodeManager, err := NewNodeManagerWithPaths("/srv/p2p/private.key", "/srv/p2p/node.json") -func NewNodeManagerWithPaths(keyPath, configPath string) (*NodeManager, error) { +// nodeManager, err := NewNodeManagerFromPaths("/srv/p2p/private.key", "/srv/p2p/node.json") +func NewNodeManagerFromPaths(keyPath, configPath string) (*NodeManager, error) { nm := &NodeManager{ keyPath: keyPath, configPath: configPath, @@ -121,6 +120,11 @@ func NewNodeManagerWithPaths(keyPath, configPath string) (*NodeManager, error) { return nm, nil } +// Deprecated: use NewNodeManagerFromPaths. +func NewNodeManagerWithPaths(keyPath, configPath string) (*NodeManager, error) { + return NewNodeManagerFromPaths(keyPath, configPath) +} + // HasIdentity returns true if a node identity has been initialized. func (n *NodeManager) HasIdentity() bool { n.mu.RLock() diff --git a/node/peer.go b/node/peer.go index 19ce7a9..ea96695 100644 --- a/node/peer.go +++ b/node/peer.go @@ -131,14 +131,13 @@ func NewPeerRegistry() (*PeerRegistry, error) { return nil, core.E("PeerRegistry.New", "failed to get peers path", err) } - return NewPeerRegistryWithPath(peersPath) + return NewPeerRegistryFromPath(peersPath) } -// NewPeerRegistryWithPath creates a new PeerRegistry with a custom path. -// This is primarily useful for testing to avoid xdg path caching issues. +// NewPeerRegistryFromPath creates a PeerRegistry using an explicit peers file path. // -// peerRegistry, err := NewPeerRegistryWithPath("/srv/p2p/peers.json") -func NewPeerRegistryWithPath(peersPath string) (*PeerRegistry, error) { +// peerRegistry, err := NewPeerRegistryFromPath("/srv/p2p/peers.json") +func NewPeerRegistryFromPath(peersPath string) (*PeerRegistry, error) { pr := &PeerRegistry{ peers: make(map[string]*Peer), path: peersPath, @@ -158,6 +157,11 @@ func NewPeerRegistryWithPath(peersPath string) (*PeerRegistry, error) { return pr, nil } +// Deprecated: use NewPeerRegistryFromPath. +func NewPeerRegistryWithPath(peersPath string) (*PeerRegistry, error) { + return NewPeerRegistryFromPath(peersPath) +} + // SetAuthMode sets the authentication mode for peer connections. func (r *PeerRegistry) SetAuthMode(mode PeerAuthMode) { r.allowedPublicKeyMu.Lock() diff --git a/node/worker.go b/node/worker.go index 0f97063..23d3178 100644 --- a/node/worker.go +++ b/node/worker.go @@ -407,7 +407,14 @@ func (w *Worker) handleDeploy(conn *PeerConnection, msg *Message) (*Message, err } } -// RegisterWithTransport registers the worker's message handler with the transport. -func (w *Worker) RegisterWithTransport() { +// RegisterOnTransport installs the worker message handler on the transport. +// +// worker.RegisterOnTransport() +func (w *Worker) RegisterOnTransport() { w.transport.OnMessage(w.HandleMessage) } + +// Deprecated: use RegisterOnTransport. +func (w *Worker) RegisterWithTransport() { + w.RegisterOnTransport() +} diff --git a/specs/logging.md b/specs/logging.md index 67c4fde..31de890 100644 --- a/specs/logging.md +++ b/specs/logging.md @@ -67,7 +67,8 @@ Structured logger with configurable output, severity filtering, and component sc | Name | Signature | Description | | --- | --- | --- | -| `WithComponent` | `func (l *Logger) WithComponent(component string) *Logger` | Returns a new logger that uses the same output and current level but replaces the component label. | +| `ComponentLogger` | `func (l *Logger) ComponentLogger(component string) *Logger` | Returns a new logger scoped to `component`. Preferred over `WithComponent`. | +| `WithComponent` | `func (l *Logger) WithComponent(component string) *Logger` | Deprecated compatibility alias for `ComponentLogger`. | | `SetLevel` | `func (l *Logger) SetLevel(level Level)` | Sets the minimum severity that the logger will emit. | | `GetLevel` | `func (l *Logger) GetLevel() Level` | Returns the current minimum severity. | | `Debug` | `func (l *Logger) Debug(msg string, fields ...Fields)` | Logs `msg` at debug level after merging any supplied field maps. | diff --git a/specs/node.md b/specs/node.md index d78cb03..87324b3 100644 --- a/specs/node.md +++ b/specs/node.md @@ -93,10 +93,12 @@ | `NewDispatcher` | `func NewDispatcher() *Dispatcher` | Creates an empty dispatcher with a debug-level component logger named `dispatcher`. | | `NewMessageDeduplicator` | `func NewMessageDeduplicator(ttl time.Duration) *MessageDeduplicator` | Creates a deduplicator that retains message IDs for the supplied TTL. | | `NewNodeManager` | `func NewNodeManager() (*NodeManager, error)` | Resolves XDG key and config paths, then loads an existing identity if present. | -| `NewNodeManagerWithPaths` | `func NewNodeManagerWithPaths(keyPath, configPath string) (*NodeManager, error)` | Creates a node manager using explicit key and config paths, primarily for tests. | +| `NewNodeManagerFromPaths` | `func NewNodeManagerFromPaths(keyPath, configPath string) (*NodeManager, error)` | Creates a node manager from explicit key and config paths. | +| `NewNodeManagerWithPaths` | `func NewNodeManagerWithPaths(keyPath, configPath string) (*NodeManager, error)` | Deprecated compatibility alias for `NewNodeManagerFromPaths`. | | `NewPeerRateLimiter` | `func NewPeerRateLimiter(maxTokens, refillRate int) *PeerRateLimiter` | Creates a token bucket seeded with `maxTokens` and refilled at `refillRate` tokens per second. | | `NewPeerRegistry` | `func NewPeerRegistry() (*PeerRegistry, error)` | Resolves the XDG peers path, loads any persisted peers, and builds the selection KD-tree. | -| `NewPeerRegistryWithPath` | `func NewPeerRegistryWithPath(peersPath string) (*PeerRegistry, error)` | Creates a peer registry bound to `peersPath` with open authentication mode and an empty public-key allowlist. | +| `NewPeerRegistryFromPath` | `func NewPeerRegistryFromPath(peersPath string) (*PeerRegistry, error)` | Creates a peer registry bound to `peersPath` with open authentication mode and an empty public-key allowlist. | +| `NewPeerRegistryWithPath` | `func NewPeerRegistryWithPath(peersPath string) (*PeerRegistry, error)` | Deprecated compatibility alias for `NewPeerRegistryFromPath`. | | `NewTransport` | `func NewTransport(node *NodeManager, registry *PeerRegistry, config TransportConfig) *Transport` | Creates a transport with lifecycle context, a 5-minute message deduplicator, and a WebSocket upgrader that only accepts local origins. | | `NewWorker` | `func NewWorker(node *NodeManager, transport *Transport) *Worker` | Creates a worker, records its start time for uptime reporting, and defaults `DataDir` to `xdg.DataHome`. | @@ -228,7 +230,8 @@ | `SetMinerManager` | `func (w *Worker) SetMinerManager(manager MinerManager)` | Installs the miner manager used for start, stop, stats, and log requests. | | `SetProfileManager` | `func (w *Worker) SetProfileManager(manager ProfileManager)` | Installs the profile manager used during deployment handling. | | `HandleMessage` | `func (w *Worker) HandleMessage(conn *PeerConnection, msg *Message)` | Dispatches supported message types, sends normal replies on success, and emits `MsgError` responses when a handled command fails. | -| `RegisterWithTransport` | `func (w *Worker) RegisterWithTransport()` | Registers `HandleMessage` as the transport's inbound message callback. | +| `RegisterOnTransport` | `func (w *Worker) RegisterOnTransport()` | Registers `HandleMessage` as the transport's inbound message callback. | +| `RegisterWithTransport` | `func (w *Worker) RegisterWithTransport()` | Deprecated compatibility alias for `RegisterOnTransport`. | ### `*ProtocolError` methods