Documentation
¶
Overview ¶
Package engine computes the UI's model from the cache, the collected values 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
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
// HooksFor returns the hooks of the pack that claimed an install. Nil gives every install Scope,
// RulesFor, Verifier, Process, ProxyMode and kgateway's settings, version, reported version and experimental kinds.
HooksFor func(install.Install) Hooks
// ClassOnly adds a class-only install per GatewayClass controllerName no
// detected install lists (install.ClassOnly); set HooksFor with it.
ClassOnly bool
// 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
// Limits counts and logs compute-bound hits; nil means a recorder on Logger and Now.
Limits *limits.Recorder
// 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, controller metrics
// included; 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 pack collectors read 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 Hooks ¶ added in v0.6.0
type Hooks struct {
Scope install.ScopeProvider
Settings func(install.Install) install.Settings
RulesFor func(version string) computed.Selection
Version func(install.Install) string
// Reported reads the version the controller reports from the collected
// values; false keeps the last one, so the rule set does not flip.
Reported func(install.Install, collect.Snapshot) (string, bool)
ExperimentalOnly func(kinds.Served, install.Install) bool
// Checks run on the install, in registration order: the core's and its pack's.
Checks []health.Check
// Conditions are the install's condition types beyond Gateway API's.
Conditions health.ConditionTypes
// Verifier checks the install's scope against its controller.
Verifier scopeverify.Verifier
// Process reports the install's controller and proxy processes.
Process process.Source
// ProxyMode decides whether one of the install's Gateways is self-managed.
ProxyMode proxymode.Resolver
}
Hooks are one install's pack hooks (extension.Impl). A nil Scope assumes all namespaces, nil Settings reads none, nil Version is "", nil Reported reports none, nil ExperimentalOnly marks no kind, nil RulesFor is Config.RulesFor and nil Checks is Config.Checks. A nil Verifier runs no verification, nil Process reports no processes and nil ProxyMode treats every proxy as managed. A RulesFor that returns no Rules gives the install no rule set: no computed views. One without a computed.Delegator gives it no delegation (install.Resolved.NoDelegation). A class-only install never has a rule set.
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 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,
// a check's wake time, such as metrics staleness, or a scope mismatch maturing.
Next Deadline
// Collected are the collector values this computation read; the API shows
// the same evidence as the checks from them.
Collected collect.Snapshot
}
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
// Stale is the collected values' StalePrint at the source's instant, so
// metrics turning stale are never confirmed as current.
Stale 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 served-kinds change it saw and the collector values it read, controller metrics included, with which of their parts were stale.