tunables

Documentation

Overview

Package tunables holds the agent's hot-reloadable operational knobs behind one atomic snapshot, swapped whole on each SIGHUP. Pull, not push: consumers read the current snapshot at their own use site, so a cadence change takes effect at the next tick and no consumer needs reload plumbing.

What belongs here: cadences, grace windows, bounded-buffer thresholds — anything whose change rebinds no resource. What never does: addresses, paths, credentials, map sizes, or a required contract.

The Store is a REQUIRED dependency, never nil, with no per-package fallback values. Defaults live in config.Defaults and hotness is declared in config.Config.Tunables — both exactly once.

Index

• type Change
  • func Diff(oldV, newV Values) []Change
• type Store
  • func New(initial Values) *Store
  • func (s *Store) Get() Values
  • func (s *Store) Replace(v Values)
• type Values

Types

type Change

type Change struct {
	Knob     string
	From, To any
}

Change is one knob transition a reload produced, named by the field's `knob` struct tag (the YAML path).

func Diff

func Diff(oldV, newV Values) []Change

Diff returns every field that differs between two snapshots, in declaration order. Reflection-driven off the `knob` tags so a field added to Values can never be forgotten in reload logging — there is no per-field list to maintain (the guard test in config asserts every field carries a tag).

type Store

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

Store is the shared holder. One owner (the runtime Manager) replaces the snapshot; any number of readers Get it lock-free.

func New

func New(initial Values) *Store

New returns a Store seeded with initial.

func (*Store) Get

func (s *Store) Get() Values

Get returns the current snapshot by value.

func (*Store) Replace

func (s *Store) Replace(v Values)

Replace swaps the whole snapshot in. Values are assumed pre-validated (config.Config.Validate runs before any reload apply).

type Values

type Values struct {
	// GhostGrace is the Lingering-Ghost TTL: how long a deleted port's
	// metadata survives so dying FIN/RST packets still attribute.
	// Applies to ghosts marked AFTER a change; in-flight ghosts keep
	// the deadline they were marked with.
	//
	// Map lifecycle: docs/architecture/data-structures.md#map-lifecycle-invariants
	GhostGrace time.Duration `knob:"gc.ghost_grace"`
	// GhostSweepInterval is the ghost-sweep cadence.
	GhostSweepInterval time.Duration `knob:"gc.ghost_sweep_interval"`
	// ReconcileInterval is the periodic full-reconcile cadence — the
	// metadata-freshness ceiling when Kafka is down. The /debug
	// sync-stale badge derives from it.
	ReconcileInterval time.Duration `knob:"reconcile.interval"`
	// ScrapeInterval is the kernel-drain cadence. Safe to retune live:
	// the delta math is interval-agnostic by design.
	ScrapeInterval time.Duration `knob:"scrape.interval"`
	// WALFlushInterval bounds the crash-loss window.
	//
	// Userspace structures: docs/architecture/data-structures.md#userspace-structures
	WALFlushInterval time.Duration `knob:"wal.flush_interval"`
	// UnresolvedTTL is the late-binding window before buffered
	// unknown-MAC flows fold to the "unknown" tenant.
	UnresolvedTTL time.Duration `knob:"unresolved.ttl"`
	// UnresolvedCap bounds the UnresolvedBuffer (Contract 1 —
	// the cap's existence is a contract; only its value is tunable).
	UnresolvedCap int `knob:"unresolved.cap"`
	// Pressure* are the pressure-relief GC thresholds.
	//
	// Kernel maps: docs/architecture/data-structures.md#kernel-side-bpf-maps
	PressureHighWatermark float64 `knob:"gc.pressure_high_watermark"`
	PressureLowWatermark  float64 `knob:"gc.pressure_low_watermark"`
	PressureMaxPerPass    int     `knob:"gc.pressure_max_per_pass"`
	// MaxStaticRouteHops bounds the static-route resolver's multi-hop
	// trace. Read where the trie is rebuilt — cold-start and each
	// reconcile — so a change applies to the next resolve, never
	// mid-traversal; the rebuilt trie is swapped atomically as always.
	//
	// Static-route resolver: docs/architecture/trie-construction.md#the-static-route-resolver
	MaxStaticRouteHops int `knob:"neutron.max_static_route_hops"`
}

Values is one immutable snapshot of every hot-reloadable knob. The zero value is NOT usable — construct from config (config.Config.Tunables) so validated defaults always apply.