engine

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

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

View Source
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).

View Source
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

func Earliest(ds ...Deadline) Deadline

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.

func (Deadline) Due

func (d Deadline) Due(now time.Time) bool

Due reports whether d is due at now: after At when Strict, else at or after At.

func (Deadline) IsZero

func (d Deadline) IsZero() bool

IsZero reports whether d is unset.

type Engine

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

Engine computes Models.

func New

func New(cfg Config) *Engine

New returns an Engine.

func (*Engine) Compute

func (e *Engine) Compute() *Model

Compute builds a new Model and publishes it. Once Run has started, only Run's loop computes and publishes.

func (*Engine) Current

func (e *Engine) Current() *Published

Current returns the latest publication, or nil before the first.

func (*Engine) Installs

func (e *Engine) Installs() []install.Install

Installs returns the installs of the current model; the metrics collector scrapes these.

func (*Engine) Platform

func (e *Engine) Platform() platform.Info

Platform returns the platform the engine computes models for.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, safety time.Duration)

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

type Published struct {
	Model       *Model
	Source      Source
	ConfirmedAt time.Time
}

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.

func (Source) Equal

func (s Source) Equal(o Source) bool

Equal reports whether s and o describe the same source data.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL