From a79b35abafbad664f85270508441d7fe96e45597 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Sat, 4 Apr 2026 21:58:37 +0000
Subject: [PATCH] Improve public API usage examples

---
 core_impl.go  |  9 +++++++++
 events.go     |  2 +-
 state_impl.go | 11 ++++++++++-
 stats.go      |  6 +++---
 worker.go     |  2 +-
 5 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/core_impl.go b/core_impl.go
index 8821d89..b56055e 100644
--- a/core_impl.go
+++ b/core_impl.go
@@ -108,6 +108,9 @@ func isValidWorkersMode(mode WorkersMode) bool {
 }
 
 // NewEventBus creates an empty synchronous event dispatcher.
+//
+//	bus := proxy.NewEventBus()
+//	bus.Subscribe(proxy.EventLogin, func(e proxy.Event) { _ = e.Miner })
 func NewEventBus() *EventBus {
 	return &EventBus{listeners: make(map[EventType][]EventHandler)}
 }
@@ -190,6 +193,9 @@ func targetFromDifficulty(diff uint64) string {
 }
 
 // NewCustomDiff creates a login-time custom difficulty resolver.
+//
+//	resolver := proxy.NewCustomDiff(50000)
+//	resolver.OnLogin(proxy.Event{Miner: miner})
 func NewCustomDiff(globalDiff uint64) *CustomDiff {
 	return &CustomDiff{globalDiff: globalDiff}
 }
@@ -207,6 +213,9 @@ func (cd *CustomDiff) OnLogin(e Event) {
 }
 
 // NewRateLimiter creates a per-IP token bucket limiter.
+//
+//	limiter := proxy.NewRateLimiter(proxy.RateLimit{MaxConnectionsPerMinute: 30, BanDurationSeconds: 300})
+//	if limiter.Allow("203.0.113.42:3333") { /* accept */ }
 func NewRateLimiter(cfg RateLimit) *RateLimiter {
 	return &RateLimiter{
 		cfg:     cfg,
diff --git a/events.go b/events.go
index ad0008c..e519d46 100644
--- a/events.go
+++ b/events.go
@@ -6,7 +6,7 @@ import "sync"
 // Dispatch is synchronous on the calling goroutine. Listeners must not block.
 //
 //	bus := proxy.NewEventBus()
-//	bus.Subscribe(proxy.EventLogin, customDiff.OnLogin)
+//	bus.Subscribe(proxy.EventLogin, func(e proxy.Event) { fmt.Println(e.Miner.User()) })
 //	bus.Subscribe(proxy.EventAccept, stats.OnAccept)
 type EventBus struct {
 	listeners map[EventType][]EventHandler
diff --git a/state_impl.go b/state_impl.go
index 8b4f0af..2ccada3 100644
--- a/state_impl.go
+++ b/state_impl.go
@@ -1189,6 +1189,9 @@ func (m *Miner) Close() {
 }
 
 // NewStats creates zeroed global metrics.
+//
+//	stats := proxy.NewStats()
+//	bus.Subscribe(proxy.EventAccept, stats.OnAccept)
 func NewStats() *Stats {
 	stats := &Stats{startTime: time.Now().UTC(), latency: make([]uint16, 0, 1024)}
 	stats.windows[HashrateWindow60s] = newTickWindow(60)
@@ -1340,6 +1343,9 @@ func insertTopDiff(top *[10]uint64, diff uint64) {
 }
 
 // NewWorkers creates a worker aggregate tracker.
+//
+//	workers := proxy.NewWorkers(proxy.WorkersByRigID, bus)
+//	workers.OnLogin(proxy.Event{Miner: miner})
 func NewWorkers(mode WorkersMode, bus *EventBus) *Workers {
 	workers := &Workers{
 		mode:      mode,
@@ -1571,7 +1577,10 @@ func (cd *CustomDiff) Apply(miner *Miner) {
 
 // NewServer constructs a server instance.
 //
-//	server, result := proxy.NewServer(bind, tlsCfg, limiter, onAccept)
+//	server, result := proxy.NewServer(bind, tlsCfg, limiter, func(conn net.Conn, port uint16) {
+//	    _ = conn
+//	    _ = port
+//	})
 func NewServer(bind BindAddr, tlsCfg *tls.Config, limiter *RateLimiter, onAccept func(net.Conn, uint16)) (*Server, Result) {
 	if onAccept == nil {
 		onAccept = func(net.Conn, uint16) {}
diff --git a/stats.go b/stats.go
index 3d2c60c..aa9d649 100644
--- a/stats.go
+++ b/stats.go
@@ -9,9 +9,9 @@ import (
 // Stats tracks global proxy metrics. Hot-path counters are atomic. Hashrate windows
 // use a ring buffer per window size, advanced by Tick().
 //
-//	s := proxy.NewStats()
-//	bus.Subscribe(proxy.EventAccept, s.OnAccept)
-//	bus.Subscribe(proxy.EventReject, s.OnReject)
+//	stats := proxy.NewStats()
+//	bus.Subscribe(proxy.EventAccept, stats.OnAccept)
+//	bus.Subscribe(proxy.EventReject, stats.OnReject)
 type Stats struct {
 	accepted    atomic.Uint64
 	rejected    atomic.Uint64
diff --git a/worker.go b/worker.go
index 7592712..e14585b 100644
--- a/worker.go
+++ b/worker.go
@@ -8,7 +8,7 @@ import (
 // Workers maintains per-worker aggregate stats. Workers are identified by name,
 // derived from the miner's login fields per WorkersMode.
 //
-//	w := proxy.NewWorkers(proxy.WorkersByRigID, bus)
+//	workers := proxy.NewWorkers(proxy.WorkersByRigID, bus)
 type Workers struct {
 	mode       WorkersMode
 	entries    []WorkerRecord // ordered by first-seen (stable)