config

Documentation

Overview

Package config loads and validates runtime configuration for retry-endpoint. Parameters are accepted from CLI flags first; environment variables serve as fallbacks; hard-coded defaults apply when neither is present.

Index

• Variables
• type Config
  • func Load() (*Config, error)

Variables

var Scopes = map[string]uint16{
	"link":   0xFF02,
	"site":   0xFF05,
	"org":    0xFF08,
	"global": 0xFF0E,
}

Scopes maps a human-readable scope name to the two-byte big-endian IPv6 multicast prefix. See RFC 4291 §2.7.

Types

type Config

type Config struct {
	// Ingress (multicast receive)
	MCIface    string // NIC for multicast ingress
	ListenPort int    // Multicast listen port
	ShardBits  uint   // Number of txid prefix bits used as the group key (1–15)
	NumGroups  uint32 // Derived: 1 << ShardBits
	MCScope    string // "site" | "global" — also accepts legacy "link"/"org" in ASM mode
	MCPrefix   uint16 // Derived from (SourceMode, MCScope) — upper 16 bits of the IPv6 group address
	MCGroupID  uint16 // IANA group-id occupying bytes 12–13 (default 0x000B)

	// SSM (RFC 4607)
	// SourceMode: "asm" (default) | "ssm"
	// BindSource: optional IPv6 literal for beacon emit; required when
	//   listeners pre-declare this retry-endpoint in sources.bootstrap.beacon
	// PublishersManifest: optional URL or local path for static manifest
	//   source-set bootstrap; defer to operator-supplied static list for now
	// SSMBootstrap{Beacon,Manifest,SubtreeGroupAnnounce}: per-control-group
	//   bootstrap source lists (IPv6 literals or DNS names; resolved via
	//   the shared bootstrap.Resolver at startup and refreshed periodically).
	//   Used to (S,G)-join the matching control group.
	// PublishersStatic: lab/CI escape hatch — pre-declared data-plane
	//   publisher source list. Production must learn the data-plane source
	//   set from manifest discovery.
	SourceMode             string
	BindSource             string
	SSMBootstrapManifest   []string
	SSMBootstrapBeacon     []string
	SSMBootstrapSubtreeAnn []string
	SSMPublishersStatic    []string
	SSMBootstrapRefresh    time.Duration

	// Cache (modular shard-common backend)
	CacheBackend     string // "memory" | "redis" | "aerospike"
	RedisAddr        string // Redis-protocol address (Redis/Valkey/Dragonfly); also enables cross-instance dedup when CacheBackend=memory
	AeroHosts        []string
	AeroNamespace    string
	AeroSet          string
	CacheDialTimeout time.Duration
	CacheOpTimeout   time.Duration
	CacheTTL         time.Duration
	CacheMaxKeys     int // Maximum number of keys in cache (0 = no limit)

	// Per-FrameVer TTLs. Resolution order applied in Load():
	//   1. explicit semantic flag/env (e.g. CACHE_TTL_TX) — wins
	//   2. else, explicit CACHE_TTL — overrides differentiated default
	//   3. else, differentiated default below
	CacheTTLTx      time.Duration // FrameVer V2 (BRC-124/128 regular tx)
	CacheTTLBlock   time.Duration // FrameVer V4 (BRC-131 block control)
	CacheTTLSubtree time.Duration // FrameVer V5 (BRC-132 subtree data)
	CacheTTLAnchor  time.Duration // FrameVer V6 (BRC-134 anchor tx)

	// Server (NACK receive)
	NACKPort    int // NACK listen port (default 9300)
	NACKWorkers int // Worker goroutines for NACK processing

	// Retransmit
	EgressIfaces []string      // NIC names for multicast egress
	EgressPort   int           // Destination UDP port for retransmitted frames
	DedupWindow  time.Duration // Deduplication window (default 60s)

	// NACK proxying (cross-domain recovery). When enabled, a cache miss
	// triggers an asynchronous recovery from an upstream retry-endpoint.
	ProxyEnabled           bool
	UpstreamRetryEndpoints []string      // upstream NACK targets (host:port)
	ProxyTimeout           time.Duration // per-upstream response wait
	ProxyMaxEndpoints      int           // upstream endpoints tried per gap (0 = all)
	ProxyDedupWindow       time.Duration // in-flight SETNX claim TTL
	ProxyWorkers           int           // recovery worker goroutines
	ProxyQueue             int           // recovery job queue depth

	// Rate limiting
	RLIPRate         float64       // IP rate limit (tokens per second)
	RLIPBurst        int           // IP burst size
	RLSenderRate     float64       // Alias for RLChainRate (backward-compat)
	RLSenderWindow   time.Duration // Alias for RLChainWindow (backward-compat)
	RLChainRate      float64       // Max NACKs per window per (srcIP, HashKey)
	RLChainWindow    time.Duration // Sliding window for per-HashKey limiter
	RLSequenceMax    int           // Max requests per SeqNum per SequenceWindow
	RLSequenceWindow time.Duration // SeqNum sliding window duration
	RLGroupRate      float64       // Retransmits per second per (srcIP, groupIdx)
	RLGroupBurst     int           // Burst size per (srcIP, groupIdx)

	// Runtime
	NumWorkers   int           // Worker goroutines for multicast ingress (always 1)
	Debug        bool          // Enable per-packet debug logging
	DrainTimeout time.Duration // Pre-drain delay before closing sockets

	// Observability
	MetricsAddr   string        // HTTP bind address for /metrics, /healthz, /readyz
	InstanceID    string        // OTel service.instance.id
	OTLPEndpoint  string        // gRPC OTLP endpoint (empty = disabled)
	OTLPInterval  time.Duration // OTLP push interval
	LogFormat     string        // "text" (default) | "json"
	LogLevel      string        // debug|info|warn|error
	TraceSampling float64       // 0..1 head sampling ratio; 0 disables tracing

	// Beacon (BRC-126 endpoint discovery)
	BeaconEnabled        bool
	BeaconTier           uint          // 0 = closest to source
	BeaconPreference     uint          // weighting within tier; higher = preferred
	BeaconInterval       time.Duration // ADVERT cadence
	BeaconScope          string        // "site" | "org" | "global" | "both" | "all"
	BeaconScopeByte      byte          // derived: 0x05 | 0x08 | 0x0E | 0xFF
	BeaconFlagsUnicast   bool
	BeaconFlagsMulticast bool
	BeaconFlagsDraining  bool
	BeaconNACKAddr       string // explicit IPv6 unicast NACK address for ADVERT; auto-detected if empty

	// BRC-132 subtree data
	SubtreeDataEnabled bool // join GroupSubtreeDataAnnounce (0xFFFB) for subtree data caching

	// Response suppression (BRC-126)
	SuppressACK  bool // do not emit ACK responses
	SuppressMISS bool // do not emit MISS responses

	// ThrottleResponse emits a THROTTLED hint on honest-congestion throttles
	// (sequence/chain/group tiers) so listeners hold instead of timing out;
	// the IP flood tier stays silent.
	ThrottleResponse bool
}

Config holds all runtime parameters for the retry endpoint.

func Load

func Load() (*Config, error)

Load parses flags and environment variables, validates all values, and returns a populated Config. It calls flag.Parse internally; callers must not call flag.Parse separately.