Documentation
¶
Overview ¶
Package nat provides NAT traversal via STUN for plexd mesh nodes.
Package nat implements STUN-based NAT traversal and endpoint discovery.
Index ¶
Constants ¶
const DefaultRefreshInterval = 60 * time.Second
DefaultRefreshInterval is the default interval between STUN binding refreshes.
const DefaultTimeout = 5 * time.Second
DefaultTimeout is the default per-server STUN request timeout.
Variables ¶
var DefaultSTUNServers = []string{
"stun.l.google.com:19302",
"stun.cloudflare.com:3478",
}
DefaultSTUNServers is the default list of STUN servers used for NAT traversal.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Enabled controls whether NAT traversal is active.
// Default: true (set by ApplyDefaults).
Enabled bool `yaml:"enabled"`
// STUNServers is the list of STUN server addresses (host:port).
STUNServers []string `yaml:"stun_servers"`
// RefreshInterval is the interval between STUN binding refreshes.
// Must be at least 10s.
RefreshInterval time.Duration `yaml:"refresh_interval"`
// Timeout is the per-server STUN request timeout.
// Must be positive.
Timeout time.Duration `yaml:"timeout"`
}
Config holds the configuration for NAT traversal.
func (*Config) ApplyDefaults ¶
func (c *Config) ApplyDefaults()
ApplyDefaults sets default values for zero-valued fields. On a zero-valued Config, Enabled defaults to true. To disable NAT traversal, set Enabled=false before or after calling ApplyDefaults.
type Discoverer ¶
type Discoverer struct {
// contains filtered or unexported fields
}
Discoverer performs STUN-based NAT traversal to discover the node's public endpoint.
func NewDiscoverer ¶
func NewDiscoverer(client STUNClient, cfg Config, localPort int, logger *slog.Logger) *Discoverer
NewDiscoverer creates a new Discoverer.
func (*Discoverer) Discover ¶
func (d *Discoverer) Discover(ctx context.Context) (*DiscoveryResult, error)
Discover performs STUN binding requests to discover the public endpoint and classify NAT type.
func (*Discoverer) LastResult ¶
func (d *Discoverer) LastResult() *api.NATInfo
LastResult returns the most recently discovered NAT info, or nil if no discovery has succeeded.
func (*Discoverer) Run ¶
func (d *Discoverer) Run(ctx context.Context, reporter EndpointReporter, updater PeerUpdater, nodeID string) error
Run performs initial STUN discovery, reports the endpoint, then enters a refresh loop. It blocks until ctx is cancelled or an unrecoverable error occurs.
type DiscoveryResult ¶
DiscoveryResult holds the outcome of a STUN discovery cycle.
type EndpointReporter ¶
type EndpointReporter interface {
ReportEndpoint(ctx context.Context, nodeID string, req api.EndpointReport) (*api.EndpointResponse, error)
}
EndpointReporter abstracts the control plane endpoint reporting API.
type MappedAddress ¶
MappedAddress represents a STUN XOR-MAPPED-ADDRESS result.
func (MappedAddress) String ¶
func (m MappedAddress) String() string
String returns the address in "ip:port" format.
type PeerUpdater ¶
PeerUpdater abstracts WireGuard peer endpoint updates.
type STUNClient ¶
type STUNClient interface {
Bind(ctx context.Context, serverAddr string, localPort int) (MappedAddress, error)
}
STUNClient abstracts STUN binding operations for testability.
type UDPSTUNClient ¶
UDPSTUNClient performs STUN binding requests over UDP.
func (*UDPSTUNClient) Bind ¶
func (c *UDPSTUNClient) Bind(ctx context.Context, serverAddr string, localPort int) (MappedAddress, error)
Bind sends a STUN Binding Request to serverAddr from localPort and returns the mapped address from the response.