nat

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 18, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

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

View Source
const DefaultRefreshInterval = 60 * time.Second

DefaultRefreshInterval is the default interval between STUN binding refreshes.

View Source
const DefaultTimeout = 5 * time.Second

DefaultTimeout is the default per-server STUN request timeout.

Variables

View Source
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.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks that configuration values are within acceptable ranges.

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

type DiscoveryResult struct {
	Endpoint string // "ip:port" format
	NATType  NATType
}

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

type MappedAddress struct {
	IP   net.IP
	Port int
}

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 NATType

type NATType string

NATType represents the classified NAT behavior.

const (
	NATNone      NATType = "none"
	NATFullCone  NATType = "full_cone"
	NATSymmetric NATType = "symmetric"
	NATUnknown   NATType = "unknown"
)

type PeerUpdater

type PeerUpdater interface {
	UpdatePeer(peer api.Peer) error
}

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

type UDPSTUNClient struct {
	Timeout time.Duration
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL