resolver

Documentation

Overview

Package resolver orchestrates the full public IP resolution algorithm. It loads a prepared STUN server list, builds ASN-spread batches, fires parallel STUN queries, accumulates results via quorum voting, and returns a high-confidence result.

This is the primary library entry point for external consumers.

Index

• type Config
• type Resolution
  • func Resolve(ctx context.Context, cfg Config) (*Resolution, error)

Types

type Config

type Config struct {
	// ServerListPath is the path to the prepared NDJSON server list.
	ServerListPath string

	// Servers allows passing a pre-loaded server list. If non-nil,
	// ServerListPath is ignored.
	Servers []serverlist.Server

	// BatchSize is the number of STUN servers to query per batch.
	// Default: 10.
	BatchSize int

	// MinConfirmingASNs is the minimum number of distinct ASNs that must
	// agree on the IP before the exit condition is met. Default: 5.
	MinConfirmingASNs int

	// AgreementRatio is the minimum fraction of responding ASNs that must
	// agree. Default: 0.80.
	AgreementRatio float64

	// PerServerTimeout is the timeout for each individual STUN query.
	// Default: 800ms.
	PerServerTimeout time.Duration

	// DNSTimeout is the timeout for each individual DNS reflection query.
	// Default: 2s.
	DNSTimeout time.Duration

	// GlobalTimeout is the maximum wall-clock time for the entire
	// resolution. Default: 5s.
	GlobalTimeout time.Duration

	// MaxBatches is the maximum number of batches to process before
	// returning the best available result. Default: 50.
	MaxBatches int

	// Verbose is an optional writer for diagnostic output.
	// If nil, no diagnostic output is produced.
	Verbose io.Writer

	// Logger is an optional structured logger for diagnostic output.
	// If nil, a logger may still be derived from Verbose for compatibility.
	Logger *slog.Logger
}

Config controls the resolution process.

type Resolution

type Resolution struct {
	IP             netip.Addr        `json:"ip"`
	Confidence     quorum.Confidence `json:"confidence"`
	ConfirmingASNs int               `json:"confirming_asns"`
	TotalASNs      int               `json:"total_asns"`
	Ambiguous      bool              `json:"ambiguous"`
	RegionalBias   bool              `json:"regional_bias"`
	ServersQueried int               `json:"servers_queried"`
	Elapsed        time.Duration     `json:"elapsed"`
}

Resolution is the result returned by Resolve.

func Resolve

func Resolve(ctx context.Context, cfg Config) (*Resolution, error)

Resolve determines the host's public IP address by querying DNS reflection sources and any configured STUN servers, then applying quorum voting.