From b9b3c47b4c3b52d3e351fbe940cd8a49e69c8587 Mon Sep 17 00:00:00 2001 From: Virgil Date: Sun, 5 Apr 2026 01:30:08 +0000 Subject: [PATCH] docs(proxy): align public comments with AX Co-Authored-By: Virgil --- api/router.go | 5 +++-- core_impl.go | 9 +++++++-- pool/client.go | 15 ++++++++++----- pool/impl.go | 15 ++++++++++----- pool/strategy.go | 9 ++++----- proxy.go | 13 +++++-------- 6 files changed, 39 insertions(+), 27 deletions(-) diff --git a/api/router.go b/api/router.go index 7434e71..98317dd 100644 --- a/api/router.go +++ b/api/router.go @@ -1,4 +1,4 @@ -// Package api mounts the three monitoring endpoints on an HTTP mux. +// Package api mounts the monitoring endpoints on an HTTP mux. // // mux := http.NewServeMux() // api.RegisterRoutes(mux, p) @@ -20,7 +20,8 @@ type RouteRegistrar interface { } // mux := http.NewServeMux() -// api.RegisterRoutes(mux, p) // GET /1/summary, /1/workers, /1/miners +// api.RegisterRoutes(mux, p) +// GET /1/summary, /1/workers, and /1/miners func RegisterRoutes(router RouteRegistrar, p *proxy.Proxy) { if router == nil || p == nil { return diff --git a/core_impl.go b/core_impl.go index 7233498..f6ce517 100644 --- a/core_impl.go +++ b/core_impl.go @@ -17,7 +17,12 @@ import ( "time" ) -// Result is a small success/error carrier used by constructors and loaders. +// Result is the success/error carrier used by constructors and loaders. +// +// cfg, result := proxy.LoadConfig("config.json") +// if !result.OK { +// return result.Error +// } type Result struct { OK bool Error error @@ -34,7 +39,7 @@ func newErrorResult(err error) Result { var splitterFactoriesMu sync.RWMutex var splitterFactoriesByMode = map[string]func(*Config, *EventBus) Splitter{} -// Register a mode-specific splitter constructor. +// RegisterSplitterFactory installs the constructor used for one proxy mode. // // proxy.RegisterSplitterFactory("simple", func(cfg *proxy.Config, bus *proxy.EventBus) proxy.Splitter { // return simple.NewSimpleSplitter(cfg, bus, nil) diff --git a/pool/client.go b/pool/client.go index 568b89f..52827a4 100644 --- a/pool/client.go +++ b/pool/client.go @@ -1,7 +1,9 @@ -// Package pool implements the outbound stratum pool client and failover strategy. +// Package pool implements the outbound pool client and failover strategy. // -// client := pool.NewStratumClient(poolCfg, listener) -// client.Connect() +// client := pool.NewStratumClient(proxy.PoolConfig{URL: "pool.example:3333", User: "WALLET", Pass: "x"}, listener) +// if result := client.Connect(); result.OK { +// client.Login() +// } package pool import ( @@ -12,8 +14,11 @@ import ( "dappco.re/go/proxy" ) -// client := NewStratumClient(poolCfg, listener) -// client.Connect() +// client := pool.NewStratumClient(poolCfg, listener) +// +// if result := client.Connect(); result.OK { +// client.Login() +// } type StratumClient struct { config proxy.PoolConfig listener StratumListener diff --git a/pool/impl.go b/pool/impl.go index 13648fd..a5c62af 100644 --- a/pool/impl.go +++ b/pool/impl.go @@ -19,7 +19,7 @@ import ( // NewStrategyFactory creates a StrategyFactory for the supplied config. // -// factory := pool.NewStrategyFactory(cfg) +// factory := pool.NewStrategyFactory(&proxy.Config{Pools: []proxy.PoolConfig{{URL: "pool.example:3333", Enabled: true}}}) // strategy := factory(listener) func NewStrategyFactory(config *proxy.Config) StrategyFactory { return func(listener StratumListener) Strategy { @@ -27,8 +27,11 @@ func NewStrategyFactory(config *proxy.Config) StrategyFactory { } } -// client := pool.NewStratumClient(poolCfg, listener) -// client.Connect() +// client := pool.NewStratumClient(proxy.PoolConfig{URL: "pool.example:3333", User: "WALLET", Pass: "x"}, listener) +// +// if result := client.Connect(); result.OK { +// client.Login() +// } func NewStratumClient(poolConfig proxy.PoolConfig, listener StratumListener) *StratumClient { return &StratumClient{ config: poolConfig, @@ -47,7 +50,7 @@ func (c *StratumClient) IsActive() bool { return c.active } -// client.Connect() +// result := client.Connect() func (c *StratumClient) Connect() proxy.Result { if c == nil { return proxy.Result{OK: false, Error: errors.New("client is nil")} @@ -93,6 +96,8 @@ func (c *StratumClient) Connect() proxy.Result { } // client.Login() +// +// A login reply with a job triggers `OnJob` immediately. func (c *StratumClient) Login() { if c == nil || c.conn == nil { return @@ -116,7 +121,7 @@ func (c *StratumClient) Login() { _ = c.writeJSON(req) } -// seq := client.Submit(jobID, "deadbeef", "HASH64HEX", "cn/r") +// seq := client.Submit("job-1", "deadbeef", "HASH64HEX", "cn/r") func (c *StratumClient) Submit(jobID, nonce, result, algo string) int64 { if c == nil { return 0 diff --git a/pool/strategy.go b/pool/strategy.go index 4cd39d0..2d89b15 100644 --- a/pool/strategy.go +++ b/pool/strategy.go @@ -7,10 +7,11 @@ import ( ) // FailoverStrategy wraps an ordered slice of PoolConfig entries. -// It connects to the first enabled pool and fails over in order on error. -// On reconnect it always retries from the primary first. // -// strategy := pool.NewFailoverStrategy(cfg.Pools, listener, cfg) +// strategy := pool.NewFailoverStrategy([]proxy.PoolConfig{ +// {URL: "primary.example:3333", Enabled: true}, +// {URL: "backup.example:3333", Enabled: true}, +// }, listener, cfg) // strategy.Connect() type FailoverStrategy struct { pools []proxy.PoolConfig @@ -23,8 +24,6 @@ type FailoverStrategy struct { } // StrategyFactory creates a FailoverStrategy for a given StratumListener. -// Splitters use it to create one upstream strategy per mapper without importing -// the pool wiring directly. // // factory := pool.NewStrategyFactory(cfg) // strategy := factory(listener) diff --git a/proxy.go b/proxy.go index 73bdb3c..960c7b8 100644 --- a/proxy.go +++ b/proxy.go @@ -1,13 +1,10 @@ -// Package proxy is a CryptoNote stratum mining proxy library. -// -// It accepts miner connections over TCP (optionally TLS), splits the 32-bit nonce -// space across up to 256 simultaneous miners per upstream pool connection (NiceHash -// mode), and presents a small monitoring API. -// -// Full specification: docs/RFC.md +// Package proxy is the mining proxy library. // +// cfg := &proxy.Config{Mode: "nicehash", Bind: []proxy.BindAddr{{Host: "0.0.0.0", Port: 3333}}, Pools: []proxy.PoolConfig{{URL: "pool.example:3333", Enabled: true}}, Workers: proxy.WorkersByRigID} // p, result := proxy.New(cfg) -// if result.OK { p.Start() } +// if result.OK { +// p.Start() +// } package proxy import (