engine

package
v0.8.0 Latest Latest
Warning

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

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

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

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

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 pack collectors read 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 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

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
	// 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.

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