README
¶
beacon
The Pilot Protocol beacon. The NAT-traversal sidecar that runs alongside the rendezvous server at the network edge:
- STUN — daemons hit it to learn their public
host:port. - Hole punch — coordinates simultaneous opens for restricted-cone NATs (
MsgPunchRequest→MsgPunchCommandto both peers). - Relay — fallback path for symmetric NATs that can't punch (
MsgRelaywrapping; daemons auto-detect onRelayDeliver). - Gossip — sharded peer-state propagation between multiple beacons in multi-beacon deployments.
This repository is published for source-code transparency and auditability. It is not a self-hosting guide. The canonical Pilot Protocol beacon is operated by Vulture Labs at
34.71.57.205:9001(alongside the rendezvous at34.71.57.205:9000); production daemons connect there by default. If you want to read the code that produced the binary your daemon's relay path is routing through, you're in the right place.
Architecture
The beacon runs a single UDP listener (default port 9001) plus an optional WSS TCP/443 fallback for UDP-blocked egress. It is a fixed-public-endpoint service: daemons send it MsgRegister, MsgPunchRequest, MsgRelay, and MsgStun packets, and the beacon dispatches based on a sharded in-memory map of node ID → last-seen UDP endpoint.
State is fully ephemeral — the beacon is restart-tolerant because daemons re-register on a short keepalive interval. In multi-beacon deployments, peer-state is propagated via gossip across the configured peers.
SO_REUSEPORT is used on Linux to scale across multiple accept goroutines on the same UDP port.
Layout
| File | What it does |
|---|---|
server.go |
UDP server: accept/dispatch + shard routing + gossip. |
nodes_shard.go |
Per-shard endpoint+last-seen map; SO_REUSEPORT-aware. |
reuseport_{linux,other}.go |
Platform-specific SO_REUSEPORT socket opts. |
wss/ |
WSS (TCP/443) tunnel — fallback for UDP-blocked egress. |
cmd/beacon/ |
Standalone binary entrypoint. |
Build locally
If you want to compile the source locally — for example to read the exact binary that produced your daemon's relay traffic, or to step through it under a debugger:
go build ./cmd/beacon
The build is hermetic Go with no cgo; any Go toolchain at the version pinned in go.mod will reproduce the binary.
License
AGPL-3.0-or-later. See LICENSE.
Documentation
¶
Index ¶
- Constants
- type Server
- func (s *Server) Addr() net.Addr
- func (s *Server) Close() error
- func (s *Server) CloseCompatWSS() error
- func (s *Server) EnableCompatWSS(bindAddr string, pubKeyLookup bwss.PubKeyLookupFn) error
- func (s *Server) ListenAndServe(addr string) error
- func (s *Server) LocalNodeCount() int
- func (s *Server) PeerNodeCount() int
- func (s *Server) Ready() <-chan struct{}
- func (s *Server) RelayDropped() uint64
- func (s *Server) RelayForwarded() uint64
- func (s *Server) RelayNotFound() uint64
- func (s *Server) SendPunchCommand(nodeID uint32, targetIP net.IP, targetPort uint16) error
- func (s *Server) ServeHealth(addr string) error
- func (s *Server) SetAdvertiseAddr(addr string)
- func (s *Server) SetHealthy(ok bool)
- func (s *Server) SetRegistry(addr string)
- func (s *Server) SetRegistryAdminToken(token string)
- func (s *Server) WSSAddr() string
- func (s *Server) WSSIsConnected(nodeID uint32) bool
- func (s *Server) WSSMetrics() bwss.Metrics
Constants ¶
const MaxReusePortShards = 0
MaxReusePortShards is unlimited on Linux — the kernel flow-hashes across all open SO_REUSEPORT sockets. 0 means "use the configured 2× NumCPU default in ListenAndServe."
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func NewWithPeers ¶
NewWithPeers creates a beacon server with gossip peer support. beaconID uniquely identifies this beacon instance (0 = standalone). peers is a list of peer beacon addresses for gossip exchange.
func (*Server) Close ¶
Close shuts down the server's UDP sockets and signals goroutines to exit. Safe to call multiple times: the teardown runs exactly once, and any subsequent call returns the first-error observed during that single teardown without re-closing already-closed sockets.
func (*Server) CloseCompatWSS ¶
CloseCompatWSS shuts down the WSS bridge. Idempotent. Used by graceful shutdown paths and tests.
func (*Server) EnableCompatWSS ¶
func (s *Server) EnableCompatWSS(bindAddr string, pubKeyLookup bwss.PubKeyLookupFn) error
EnableCompatWSS attaches a WSS-bridge listener for compat-mode daemons. After Start, the beacon's relay worker checks the WSS peer map BEFORE the UDP tier-1/2 lookups: relay packets destined for a WSS-connected daemon are written over WSS instead of UDP. Inbound WSS frames feed into handlePacket the same way UDP datagrams do, so the existing dispatch logic (BeaconMsgRelay, BeaconMsgDiscover, etc.) handles them without changes.
pubKeyLookup must return the Ed25519 pubkey registered for nodeID. In the rendezvous binary this is plumbed to the in-process registry's pubkey index.
Call this BEFORE ListenAndServe so the wssServer is in place when the first UDP datagram arrives.
func (*Server) ListenAndServe ¶
func (*Server) LocalNodeCount ¶
LocalNodeCount returns the number of locally registered nodes.
func (*Server) PeerNodeCount ¶
PeerNodeCount returns the number of nodes known via gossip from peer beacons.
func (*Server) Ready ¶
func (s *Server) Ready() <-chan struct{}
Ready returns a channel that is closed when the server has bound its port.
func (*Server) RelayDropped ¶
RelayDropped returns the count of relay packets dropped (capacity / errors).
func (*Server) RelayForwarded ¶
RelayForwarded returns the count of relay packets the beacon has forwarded since startup. Used by /api/stats to surface observable evidence that the relay path is live.
func (*Server) RelayNotFound ¶
RelayNotFound returns the count of relay packets dropped because the destination node was not registered with the beacon.
func (*Server) SendPunchCommand ¶
SendPunchCommand tells a node to send UDP to a target endpoint.
func (*Server) ServeHealth ¶
ServeHealth starts a simple HTTP server with a /healthz endpoint for load balancer health checks.
func (*Server) SetAdvertiseAddr ¶
SetAdvertiseAddr sets the address this beacon registers with the registry. When empty (default), the beacon auto-detects from its TCP local addr to the registry — which on a GCP MIG deployment yields the INTERNAL VPC address (10.128.0.x), unreachable from external daemons. MIG-deployed beacons must set this to the public DNAT entrypoint (e.g. the rendezvous reserved IP on UDP 9001) so external clients receive a routable address from beacon_list.
func (*Server) SetHealthy ¶
SetHealthy sets the health status (for graceful drain on scale-down).
func (*Server) SetRegistry ¶
SetRegistry sets the registry address for dynamic peer discovery. Safe to call at any time — protected by mu so the discovery loop does not race against a post-startup SetRegistry call.
func (*Server) SetRegistryAdminToken ¶
SetRegistryAdminToken sets the admin token sent with beacon_register. Required when the registry enforces SEC-002 beacon registration auth.
func (*Server) WSSAddr ¶
WSSAddr returns the actual listen address of the compat WSS bridge. Empty string if EnableCompatWSS was never called. Used by tests that bind to :0 and need to discover the real port.
func (*Server) WSSIsConnected ¶
WSSIsConnected reports whether a compat-mode daemon is currently connected via the WSS bridge for the given nodeID. False if the bridge isn't enabled. Used by tests that need to wait for the post-handshake registration to land.
func (*Server) WSSMetrics ¶
WSSMetrics returns the live WSS-bridge metrics, or zero values if EnableCompatWSS was never called. Used by the dashboard / Prom scrape to expose compat-mode visibility.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
beacon
command
|
|
|
Package wss is the beacon-side WSS listener for compat-mode daemons.
|
Package wss is the beacon-side WSS listener for compat-mode daemons. |
|
internal/daemonwss
Package wss implements pkg/daemon/transport.Transport over a WebSocket Secure connection to a Pilot beacon.
|
Package wss implements pkg/daemon/transport.Transport over a WebSocket Secure connection to a Pilot beacon. |