stunserver

Documentation

Overview

Package stunserver implements a stateless STUN responder for natcheck.

The package exposes two consumption modes built on the same Handle function: pure byte-in/byte-out for in-process tests, and a PacketConn dispatch loop for use as a long-running responder. Supports BindingRequest with optional OTHER-ADDRESS responses (RFC 5780 §7.4). CHANGE-REQUEST routing is a caller concern — use ParseChangeRequest to extract flags from incoming requests.

Index

• func BuildChangeRequest(changeIP, changePort bool) stun.RawAttribute
• func ParseChangeRequest(req []byte) (changeIP, changePort, ok bool)
• type Options
• type Server
  • func New(opts Options) *Server
  • func (s *Server) Handle(req []byte, src netip.AddrPort) []byte
  • func (s *Server) Serve(ctx context.Context, conn net.PacketConn) error

Functions

func BuildChangeRequest

func BuildChangeRequest(changeIP, changePort bool) stun.RawAttribute

BuildChangeRequest returns a CHANGE-REQUEST attribute (RFC 5780 §7.2) suitable for passing to stun.Build alongside other setters. Bit A (0x04) requests CHANGE-IP; bit B (0x02) requests CHANGE-PORT.

func ParseChangeRequest

func ParseChangeRequest(req []byte) (changeIP, changePort, ok bool)

ParseChangeRequest extracts CHANGE-REQUEST flags from a STUN BindingRequest. Returns ok=false for messages other than BindingRequest, malformed STUN, missing CHANGE-REQUEST attribute, or attribute payloads not exactly 4 bytes.

Types

type Options

type Options struct {
	// Other is the address of the diagonal peer in an RFC 5780 §3 four-corner
	// topology. When set, Handle includes an OTHER-ADDRESS attribute pointing
	// to it. Zero-value disables the attribute.
	Other netip.AddrPort
}

Options configures a Server.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is a stateless STUN responder. Construct via New. Handle is pure and safe for concurrent use across goroutines. Serve owns its PacketConn — do not call Serve concurrently with the same conn.

func New

func New(opts Options) *Server

New returns a Server configured with opts.

func (*Server) Handle

func (s *Server) Handle(req []byte, src netip.AddrPort) []byte

Handle processes a single STUN request and returns the wire bytes of the response, or nil to indicate no reply (drop). The src argument is the observed source endpoint and is echoed in XOR-MAPPED-ADDRESS.

Handle never panics. Malformed input, unsupported message types, and any build failure are silently dropped (return nil) per the diagnostic-responder posture. Response size is comparable to request size; no meaningful amplification factor.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, conn net.PacketConn) error

Serve runs a read-decode-Handle-write loop on conn until ctx is cancelled or conn returns net.ErrClosed. On ctx cancellation, Serve forces any in-flight ReadFrom to return immediately by setting a deadline in the past (matching the cancellation idiom in internal/probe/stun.go).

Per-packet decode failures and non-UDP source addresses are swallowed; the loop continues. WriteTo errors (e.g., destination unreachable) are silently dropped — diagnostic-responder posture, not a delivery-guaranteed service.

Returns ctx.Err() on cancellation or the underlying conn error (typically net.ErrClosed) on shutdown.