Documentation
¶
Overview ¶
Package engine computes the UI's model from the cache, the controller metrics and the registered checks, when triggers or deadlines call for it (D-019).
Index ¶
Constants ¶
const ( // Quiet is the trailing debounce window after the last trigger. Quiet = 250 * time.Millisecond // MaxDelay bounds the debounce from the first trigger of a burst. MaxDelay = time.Second // ConfirmEvery is the confirm tick interval. ConfirmEvery = time.Second )
Scheduler timing (D-019).
const Window = 30 * time.Second
Window is how long a computed disagreement must hold unchanged before it raises KGWUI-012 (computed-rules §9.3).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Snapshots cache.Snapshotter
// Served is the one served-kind list given to assignment, checks, the
// scope verifier and the overview.
Served []kinds.Served
// KindsChange, if set, reports how the kinds served now differ from Served.
KindsChange func() kinds.Change
// Catalog, if set, returns every kind the API server serves.
Catalog func() kinds.Catalog
Detectors []install.Detector
Scope install.ScopeProvider
// Verifier checks scope against the controller; its persistence should be
// 2 × the metrics interval (design §4.4).
Verifier scopeverify.Verifier
Metrics ctrlmetrics.Source
Checks []health.Check
// Pinned restricts the UI to one install ID; empty shows all.
Pinned string
// Platform is the platform the snapshots come from; zero means platform.Kubernetes().
Platform platform.Info
// ProxyMode decides whether a Gateway is self-managed; nil means proxymode.GatewayParameters{}.
ProxyMode proxymode.Resolver
// Process reports each install's processes; nil means process.Kube{}.
Process process.Source
// RulesFor selects each install's computed rule set from its kgateway version; nil means rulesets.Select.
RulesFor func(controllerVersion string) computed.Selection
// DelegationBounds caps views B and C per install; zero means computed.DefaultBounds.
DelegationBounds computed.Bounds
// Logger receives install rejections; nil means slog.Default().
Logger *slog.Logger
// MetricsMaxAge is the age beyond which a metrics result is stale
// (3 × the metrics interval). Zero disables staleness: never use it in production.
MetricsMaxAge time.Duration
// Now stamps computations; nil means Clock.Now. It must agree with Clock,
// or Run sees deadlines due that Compute does not.
Now func() time.Time
// OnCompute, if set, receives each model Run publishes, on Run's goroutine.
// Confirmations do not call it.
OnCompute func(*Model)
// Triggers starts recomputes; nil means only deadlines, the safety timer
// and the confirm tick do.
Triggers *trigger.Signal
// Clock drives Run's timers; nil means clock.RealClock{}.
Clock clock.WithTicker
// ConfirmEvery is the confirm tick interval; zero means ConfirmEvery.
ConfirmEvery time.Duration
// OnLoop, if set, is called on Run's goroutine after each loop transition (tests).
OnLoop func(LoopEvent)
// Collected, if set, returns the collector values; checks read them and
// the confirm tick compares their print (D-019).
Collected func() collect.Snapshot
// NoMemo turns per-check memoization off, so every check runs on every
// recompute (tests compare against it).
NoMemo bool
}
Config wires the engine.
type Deadline ¶
type Deadline struct {
// At is the boundary instant.
At time.Time
// Strict marks a predicate of the form "now > At": the deadline is due at
// the first clock reading after At, not at At itself.
Strict bool
}
Deadline is a time-driven instant at which the model must be recomputed, with no debounce. The zero Deadline is unset and never due.
func Earliest ¶
Earliest returns the set deadline that falls due first, or the zero Deadline when none is set. At equal At a non-strict deadline wins, since it is due at At itself; so a deadline due at now is never dropped.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine computes Models.
func (*Engine) Compute ¶
Compute builds a new Model and publishes it. Once Run has started, only Run's loop computes and publishes.
func (*Engine) Installs ¶
Installs returns the installs of the current model; the metrics collector scrapes these.
func (*Engine) Run ¶
Run is the scheduler goroutine (D-019 §3). It computes once at start, then whenever triggers, deadlines or the safety timer call for it, and runs the confirm tick every Config.ConfirmEvery until ctx is done. safety is the longest time between recomputes; zero or less disables it. Each recompute runs in its own goroutine, so triggers keep arriving during it; the loop publishes its result, and a result that arrives after ctx is done is dropped.
type InstallModel ¶
type InstallModel struct {
Resolved install.Resolved
Owned *install.Owned
Overview overview.Overview
Health health.Report
// Diagnosis groups and ranks Health's findings; Build set each finding's Group.
Diagnosis *diagnose.Diagnosis
// Index is the explorer's immutable index; handlers never decode objects.
Index *explore.Index
// Rules is the computed rule set selected for this install's controller (D-020).
Rules computed.Selection
// Computed are the install's computed views with their check states.
Computed *computed.Views
// Process is the install's controller and proxy processes.
Process *health.ProcessData
}
InstallModel is everything the API serves about one install.
type LoopEvent ¶
type LoopEvent struct {
Kind LoopEventKind
At time.Time
Published *Published
}
LoopEvent is one loop transition, at the loop clock's time.
type LoopEventKind ¶
type LoopEventKind int
LoopEventKind names a transition of Run's loop.
const ( // EvTriggered: a trigger was recorded. EvTriggered LoopEventKind = iota // EvArmed: the loop armed its timer for the next due instant and is about to wait. EvArmed // EvRunStarted: a recompute started. EvRunStarted // EvPublished: a recompute published; Published is its value. EvPublished // EvConfirmed: a confirm tick renewed ConfirmedAt; Published is the new value. EvConfirmed // EvConfirmRefused: a confirm tick did not confirm, because a run was // pending or running, the live source differed, or something newer was published. EvConfirmRefused )
Loop transitions reported to Config.OnLoop.
type MetricsRead ¶
type MetricsRead struct {
ID string
Result ctrlmetrics.Result
Present bool
}
MetricsRead is one metrics result as Compute read it.
type Model ¶
type Model struct {
Snapshot *cache.Snapshot
Served []kinds.Served
Installs []InstallModel
Pinned string
ComputedAt time.Time
// Rejected are this computation's install rejections (invalid IDs); /readyz reports them.
Rejected []string
// Seq orders computations; it strictly increases.
Seq uint64
// Next is the earliest deadline not yet due at ComputedAt: a grace expiry,
// metrics staleness or a scope mismatch maturing.
Next Deadline
// MetricsRead are the metrics results this computation used, one per install, in install order.
MetricsRead []MetricsRead
}
Model is one consistent computation over a snapshot.
type Published ¶
Published is one publication: a Model, the Source it was computed from and when that source was last confirmed live. It is never mutated after publication; a confirmation publishes a new value.
type Source ¶
type Source struct {
Cache cache.Fingerprint
// Metrics is encodeMetrics of the results read.
Metrics uint64
// Kinds is the served-kinds change as kinds.Change.String().
Kinds string
// Collected is the collector store's print; zero without collectors.
Collected uint64
// Catalog is the served-kind catalog's kinds.Catalog.Key().
Catalog string
}
Source is the source fingerprint of a model (D-019 §2): the cache data it was computed from, the identity of the metrics results it read, the served-kinds change it saw and the collector values it read.