classify

Documentation

Overview

Package classify turns probe results into a NAT-type verdict.

Classification follows RFC 5780 mapping-behavior categories (Endpoint-Independent, Address-Dependent, Address and Port-Dependent) and emits legacy RFC 3489 terms ("cone", "symmetric") for human readers. See docs/design.md for the v0.1 scope and limits.

Index

• Constants
• type Forecast
• type NATType
  • func (t NATType) String() string
• type Verdict
  • func Classify(results []probe.Result) Verdict

Constants

const (
	WarnAllProbesFailed            = "all_probes_failed"
	WarnADMOrStricter              = "adm_or_stricter"
	WarnCGNATDetected              = "cgnat_detected"
	WarnInsufficientProbes         = "insufficient_probes"
	WarnFilteringBehaviorNotTested = "filtering_behavior_not_tested"
)

Stable warning vocabulary for the JSON API.

Types

type Forecast

type Forecast struct {
	DirectP2P    string // "likely" | "possible" | "unlikely" | "unknown"
	TURNRequired bool
}

Forecast is the WebRTC direct-P2P prediction.

type NATType

type NATType int

NATType is the RFC 5780 mapping-behavior category.

const (
	// Unknown indicates classification could not be determined from the
	// available probes (typically only one successful probe — no comparison
	// point for mapping behavior).
	Unknown NATType = iota

	// EndpointIndependentMapping: same mapped endpoint across servers.
	// RFC 5780. Legacy term "cone".
	EndpointIndependentMapping

	// AddressDependentMapping: mapped endpoint varies by destination address.
	// RFC 5780. v0.1 reports this for any case where mapped endpoints differ
	// across servers; ADM vs APDM cannot be distinguished without
	// CHANGE-REQUEST.
	AddressDependentMapping

	// AddressPortDependentMapping: mapped endpoint varies by destination
	// address and port. RFC 5780. Legacy term "symmetric". v0.1 does not
	// emit this category directly (see AddressDependentMapping note).
	AddressPortDependentMapping

	// Blocked: no probe succeeded. Network rejects outbound STUN, all target
	// servers are unreachable, or the caller's timeout fired too early.
	Blocked
)

func (NATType) String

func (t NATType) String() string

String returns the canonical RFC 5780 name.

type Verdict

type Verdict struct {
	Type            NATType
	LegacyName      string // "cone", "symmetric", "" when unknown/blocked
	PublicEndpoint  netip.AddrPort
	CGNAT           bool
	FilteringTested bool // always false in v0.1
	Warnings        []string
	Forecast        Forecast
}

Verdict is the final classification output.

func Classify

func Classify(results []probe.Result) Verdict

Classify turns probe results into a Verdict. Pure function: no I/O, no goroutines, deterministic for a given input.

A probe.Result is treated as successful only when Err == nil AND Mapped.IsValid(). This guards against buggy Prober implementations that might report nil-error with a zero mapped endpoint.