Documentation
¶
Overview ¶
Package wss is the beacon-side WSS listener for compat-mode daemons. See docs/SPEC-compat-mode.md.
Architecture:
- Accept incoming WebSocket upgrades on a bind address (typically 127.0.0.1:8443, behind a Caddy reverse proxy that terminates TLS on port 443). The binary does not handle TLS itself — Caddy does — but plain WS is also supported for in-process tests via httptest.NewServer.
- After upgrade, complete an Ed25519 challenge: send a random nonce, receive the daemon's signed reply, verify against the daemon's known pubkey (looked up via PubKeyLookupFn).
- On success, store the conn in the wssPeers map keyed by node ID. The conn is owned by a per-peer goroutine that reads binary frames and dispatches them via OnFrame.
- Outbound writes: WriteFrame(destID, frame) finds the conn and writes one binary WS frame. Returns false if destID is not currently connected — caller falls back to UDP.
This package is transport-only. It does not know what's inside a frame; it just shuttles bytes both directions. The beacon's existing relay router calls WriteFrame first and falls back to UDP if the destination is a UDP-only peer.
Index ¶
Constants ¶
const DefaultAuthTimeout = 10 * time.Second
DefaultAuthTimeout caps the time a peer has to complete the auth challenge after WS upgrade. Bots that don't sign correctly drop off after this.
const DefaultIdleTimeout = 90 * time.Second
DefaultIdleTimeout disconnects peers that don't send or pong within this window. Pings from the WS library run automatically; this is the outer ceiling.
const MaxFrameSize = 64 * 1024
MaxFrameSize bounds the size of an inbound binary frame. Matches the Pilot wire MTU cap (16 KB on data frames + 34-byte header) with margin for future fields. Larger frames are rejected and the peer is disconnected.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// BindAddr is the host:port to listen on. Typically
// "127.0.0.1:8443" with Caddy fronting TLS on :443, or ":8443"
// for direct exposure.
BindAddr string
// PubKeyLookup returns the Ed25519 pubkey registered for nodeID.
// In production this is plumbed to the registry-shared pubkey
// cache. Returns (nil, false) if nodeID is unknown.
PubKeyLookup PubKeyLookupFn
// OnFrame is invoked when a connected WSS peer sends a binary
// frame. senderID is the verified node ID (from the auth phase);
// the caller must not retain the frame slice past the callback.
OnFrame OnFrameFn
// AuthTimeout overrides DefaultAuthTimeout.
AuthTimeout time.Duration
// IdleTimeout overrides DefaultIdleTimeout.
IdleTimeout time.Duration
// MaxPeers caps the number of concurrent WSS peer connections.
// New upgrades beyond this are rejected with 503. 0 = unlimited.
MaxPeers int
}
Config configures a Server.
type Metrics ¶
type Metrics struct {
UpgradeOK, UpgradeFail uint64
AuthOK, AuthFail uint64
FramesIn, FramesOut uint64
IdleDisconns uint64
ActivePeers uint64
}
Metrics is the structured counter snapshot returned by Server.Metrics. Field semantics:
- UpgradeOK / UpgradeFail: HTTP upgrade outcomes (before auth).
- AuthOK / AuthFail: post-upgrade Ed25519 challenge outcomes.
- FramesIn / FramesOut: binary frame counts. One per Pilot packet.
- IdleDisconns: peers dropped for inactivity.
- ActivePeers: gauge — live WSS connections.
type OnFrameFn ¶
OnFrameFn handles an inbound binary frame from a connected WSS peer. senderID is the authenticated node ID. frame is owned by the caller of OnFrame — must not be retained past the call.
type PubKeyLookupFn ¶
PubKeyLookupFn fetches the Ed25519 pubkey for a node ID. Returns ok=false if the node ID is not registered.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server accepts WSS upgrades and maintains the peer connection map. Safe for concurrent use after Start.
func New ¶
New constructs a Server with the given configuration. Returns an error for missing required fields.
func (*Server) Addr ¶
Addr returns the actual listen address after Start (useful for tests that bind to :0). Returns the configured BindAddr if Start has not yet been called.
func (*Server) Close ¶
Close stops the server, drops all peer connections, and waits for the accept goroutine to exit. Idempotent.
func (*Server) IsConnected ¶
IsConnected returns whether nodeID has an active WSS peer connection. Used by the relay router's "WSS first, UDP fallback" decision. O(1) sharded map read.
func (*Server) Metrics ¶
Metrics returns a snapshot of the counter set for Prometheus scraping or logs.
func (*Server) PeerCount ¶
PeerCount returns the number of currently connected WSS peers. Useful for capacity monitoring + Prometheus gauge.
func (*Server) Start ¶
Start binds the listener and starts accepting upgrades. Non-blocking; returns after the listener is bound. Use Close() to shut down.
func (*Server) WriteFrame ¶
WriteFrame sends a binary frame to the connected WSS peer with the given node ID. Returns false if destID is not currently connected — the caller (relay router) should fall back to UDP. Returns false + logs on write error (peer is then dropped).
Source Files