computed

package
v0.6.0 Latest Latest
Warning

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

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

Documentation

Overview

Package computed is the seam for the UI's computed views (D-020): the rule interface, its inputs and results, and the states a cross-check reports. The version-specific rule sets live in subpackages; rulesets selects one.

Index

Constants

View Source
const (
	ModeDefault = "default"
	ModeInherit = "inherit"
)

Effective matcher modes (rules §6).

View Source
const (
	CapEdges    = "edges"
	CapContexts = "contexts"
	CapMatchers = "matchers"
	CapDepth    = "depth"
)

Compute caps, as DelegationResult.Cap names them (rules §5.7).

View Source
const (
	ReasonBackendNotFound = "BackendNotFound"
	ReasonRefNotPermitted = "RefNotPermitted"
)

Parent signal reasons: ResolvedRefs=False reasons a delegation failure writes on the parent (ProcessBackendError, pkg/kgateway/query/utils.go V3:37-50).

View Source
const (
	// UncertainRoot: an owned top-level route whose root eligibility is unknown.
	UncertainRoot = -1
	// UncertainPossible: a route an uncertain selection might select.
	UncertainPossible = -2
)

Uncertain point rule indexes besides a real rule index (rules §8.5).

View Source
const (
	LogClassRegex            = "regex"
	LogClassTLS              = "tls"
	LogClassDuplicate        = "duplicate"
	LogClassBind             = "bind"
	LogClassValidation       = "validation"
	LogClassUnknownExtension = "unknown-extension"
	LogClassApply            = "apply"
	LogClassParameters       = "parameters"
	LogClassRender           = "render"
	LogClassNoValidPorts     = "no-valid-ports"
	LogClassStatusUpdate     = "status-update"
	LogClassPrune            = "prune"
	LogClassPanic            = "panic"
	LogClassOther            = "other"
)

Error classes of derived log events (design §8.9): Envoy's reject reasons, the deployer's failures, a Go panic and other.

View Source
const (
	TargetFound           = "found"
	TargetNotFound        = "not-found"
	TargetSectionNotFound = "section-not-found"
	TargetMatchesNothing  = "matches-nothing"
	TargetUnknown         = "unknown"
)

Target outcomes, as TargetResult.Outcome carries them.

View Source
const MaxDisplayBytes = 256

MaxDisplayBytes bounds one value inside a display string such as a reason.

View Source
const MaxLogWindow = 8

MaxLogWindow is how many following lines a LogWindow marker may ask for.

View Source
const MaxPathBytes = 4096

MaxPathBytes bounds a generated path. A longer one is never cut: the context is unknown, too-large.

View Source
const MaxStatusBytes = 1024

MaxStatusBytes bounds a status message quoted in evidence (design §18.2).

Variables

View Source
var DefaultBounds = Bounds{Edges: 10_000, Contexts: 20_000, Matchers: 200_000,
	ContextsPerRow: 20, ContextsPerInstall: 30_000, EffectiveEdges: 20, ContextsPerEdge: 20, Depth: 100}

DefaultBounds are the caps of rules §5.7. ContextsPerInstall is 30,000 (our call, 2.4; D-022 retained heap). Edges is 10,000 (user, 2026-10-27; D-025): dense delegation must stay inside the chart's 512Mi memory limit. Depth is 100 (our call, 2.4; D-025): deep chains stay linear in memory.

Functions

func ClipDisplay

func ClipDisplay(p string, limit int) string

ClipDisplay cuts a display string to limit bytes at a UTF-8 boundary and adds a marker. Computed paths never pass through it.

func DecodeTargets

func DecodeTargets(u *unstructured.Unstructured) ([]TargetRef, []TargetSelector)

DecodeTargets returns a policy's spec.targetRefs and spec.targetSelectors as written. Entries that are not objects are skipped.

func DeployerLogClass

func DeployerLogClass(c string) bool

DeployerLogClass reports whether c is one of the deployer's error classes, which only deployer lines carry.

func KnownLogClass

func KnownLogClass(c string) bool

KnownLogClass reports whether c is on the fixed list of error classes.

func Subject

func Subject(parts ...string) string

Subject joins the subject parts of rules §9.1 with NUL.

Types

type Acceptance

type Acceptance int

Acceptance is a listener-bearing resource's own acceptance (rules §3.1).

const (
	Accepted Acceptance = iota
	Denied
	NoStatus
)

Acceptance values. A Gateway is always Accepted.

type Allows

type Allows string

Allows is which parents a child's parentRefs permit (rules §5.3).

const (
	// AllowsAny: the child has no parentRefs, so any parent may select it.
	AllowsAny Allows = "any"
	// AllowsThis: a parentRef names the selecting parent.
	AllowsThis Allows = "this"
	// AllowsOther: the parentRefs name other parents only.
	AllowsOther Allows = "other"
)

Allows values.

type AttachmentInput

type AttachmentInput struct {
	Resources []Resource
	Routes    []Route
	// NamespaceLabels holds each Namespace's labels; it is only meaningful when NamespacesOK.
	NamespaceLabels map[string]map[string]string
	NamespacesOK    bool
	Experimental    install.Setting
	ControllerNames []string
	// ScopeUnknown makes every count and outcome unknown: the candidates are a guess (rules §3.3).
	ScopeUnknown bool
}

AttachmentInput is everything view A reads for one install (rules §4.6).

type AttachmentResult

type AttachmentResult struct {
	Members  []Member
	Outcomes []RefOutcome
	Counts   []ListenerCount
}

AttachmentResult is view A for one install. Its Deps slices are read-only and may be shared between entries: never sort or append to them in place.

type Bounds

type Bounds struct {
	// Compute caps per install.
	Edges, Contexts, Matchers int
	// Retention caps: contexts per row and per install.
	ContextsPerRow, ContextsPerInstall int
	// Projection caps: parent edges per route, contexts per edge.
	EffectiveEdges, ContextsPerEdge int
	// Depth caps the routes on one path, which bounds each context's deps.
	Depth int
}

Bounds are the compute and retention caps of views B and C (rules §5.7).

type CheckKind

type CheckKind string

CheckKind names what a cross-check compares (rules §9.1).

const (
	KindListenerCount CheckKind = "listener-count"
	KindRouteAccepted CheckKind = "route-accepted"
)

Check kinds of view A.

const (
	KindChildEntry         CheckKind = "child-entry"
	KindParentResolvedRefs CheckKind = "parent-resolvedrefs"
)

Check kinds of views B and C.

const (
	KindDelegatedNotAttached CheckKind = "delegated-not-attached"
	KindOrphan               CheckKind = "orphan-not-attached"
)

Trigger kinds of KGWUI-011 (rules §9.1): the computed trigger per (route, parent) and the orphan trigger per route.

const KindPolicyTarget CheckKind = "policy-target"

KindPolicyTarget is the policy targets verifier: a current ancestor for a target the rule called missing (design §7.6).

type CheckResult

type CheckResult struct {
	ID    Identity
	Class Class
	// Unknown says why a ClassUnknown check could not be made, when a reason applies.
	Unknown  UnknownReason
	Verified bool
	Coverage []Coverage
	// Fingerprint hashes the inputs and evidence of rules §9.2.
	Fingerprint uint64
	// On is the object whose status disagrees (rules §9.3 step 5).
	On       objects.Ref
	Listener string
	Key      ReportKey
	Expected string
	Observed string
	// Deps and Contributors are read-only and may be shared.
	Deps          []objects.Ref
	Contributors  []objects.Ref
	ParentCurrent bool
	Note          string
	// State, Mature and Since (the window start) are set by the engine.
	State  State
	Mature bool
	Since  time.Time
}

CheckResult is one cross-check of a computed result against status.

func CheckAttachment

func CheckAttachment(install string, sel Selection, in AttachmentInput, r AttachmentResult) []CheckResult

CheckAttachment cross-checks view A against the controller's status (rules §8.1–§8.4): one listener-count check per listener count, and one route-accepted check per (route, report key). It never modifies r.

func CheckDelegation

func CheckDelegation(install string, sel Selection, in DelegationInput, r *DelegationResult) []CheckResult

CheckDelegation cross-checks views B and C against the controller's status (rules §8.1–§8.5): one child-entry check per (child, parent, report key), including entries no row expects, and one parent-resolvedrefs check per (parent, reporter key). Completeness comes from r.Complete. It sets each row's Unconfirmable and otherwise never modifies r.

func (CheckResult) Candidate

func (c CheckResult) Candidate() bool

Candidate reports whether c can mature into KGWUI-012 (rules §9.3 step 1).

func (CheckResult) Parent

func (c CheckResult) Parent() (objects.Ref, bool)

Parent is the parent route of a child-entry or delegated-not-attached check, read from its subject; ok is false for other kinds.

type ChildEffective

type ChildEffective struct {
	Edges     []EffectiveEdge
	Truncated bool
}

ChildEffective is one child's effective edges, sorted by parent, at most Bounds.EffectiveEdges; Truncated is set when more parents had one.

type Class

type Class string

Class is a cross-check's evidence class (rules §8.1, §8.3).

const (
	ClassContradicting Class = "contradicting"
	ClassStale         Class = "stale"
	ClassMissing       Class = "missing"
	ClassUnexpected    Class = "unexpected"
	ClassCompatible    Class = "compatible"
	ClassNotObservable Class = "not-observable"
	ClassInconclusive  Class = "inconclusive"
	ClassUnknown       Class = "unknown"
	// ClassTrigger is a KGWUI-011 trigger whose predicate holds (our call:
	// rules §8.3 gives it no class). It matures but never makes a check pending.
	ClassTrigger Class = "trigger"
)

Evidence classes.

type Completeness

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

Completeness says which aggregates of a delegation result are complete (rules §8.5). An aggregate on a route in a reach closure is incomplete: the missing work may reach it. The zero value has every route complete.

func NewCompleteness

func NewCompleteness(r DelegationResult) Completeness

NewCompleteness computes r's reach closures: from every uncertain point's route over r.Reach, transitively (rules §8.5). Each edge is walked once.

func (Completeness) Incomplete

func (c Completeness) Incomplete(route objects.Ref) bool

Incomplete reports whether route is in a reach closure.

func (Completeness) IncompleteKey

func (c Completeness) IncompleteKey(route objects.Ref, key ReportKey) bool

IncompleteKey reports whether a check on route under key is incomplete: route is in a reach closure, or key is one of route's Root.UncertainKeys. An uncertain key does not seed a closure, since the evaluation below a root is the same under every key; only the root's own report under it is uncertain.

type Context

type Context struct {
	ParentMatch objects.Match
	Path        *Path
	// Reporter is the report key of the parent's reporter (rules §7).
	Reporter ReportKey
	// Outcome must be set by the caller; an empty or unknown value counts as unknown.
	Outcome RowOutcome
	Unknown UnknownReason
	Reason  *FitFailure
	Rules   []EffectiveRule
	Deps    []objects.Ref
}

Context is one evaluation of a row under one incoming parent match (rules §5.1). Its slices are read-only once added to a row, so they may be shared.

type ContextHasher

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

ContextHasher hashes contexts for the row digests with the fingerprint encoding (rules §9.2). It reuses its buffers, so one hasher serves one caller.

func NewContextHasher

func NewContextHasher() *ContextHasher

NewContextHasher returns a ContextHasher.

func (*ContextHasher) Sum

func (h *ContextHasher) Sum(c *Context) uint64

Sum hashes c's incoming match, path, reporter and outcome.

type Coverage

type Coverage string

Coverage says what a passing cross-check verified (rules §8.4).

const (
	CoverageCount  Coverage = "count-agrees"
	CoverageStatus Coverage = "status-compatible"
	CoverageNone   Coverage = "not-verified"
)

Coverage labels.

type DelegRoute

type DelegRoute struct {
	Ref        objects.Ref
	Generation int64
	View       *objects.HTTPRouteView
	// Owned is true for a route of the install; TopLevel for an owned route
	// that has a Gateway or ListenerSet parent.
	Owned, TopLevel bool
}

DelegRoute is an in-scope HTTPRoute as views B and C read it.

type DelegationInput

type DelegationInput struct {
	// Routes are every in-scope HTTPRoute, sorted by (namespace, name).
	Routes []DelegRoute
	// Unwatched are the HTTPRoutes outside the scope.
	Unwatched map[objects.Ref]bool
	Roots     []Root
	// Wildcard is the delegation wildcard namespace setting (rules §5.2).
	Wildcard        install.Setting
	ControllerNames []string
	Bounds          Bounds
	// ScopeUnknown makes views B and C scope-unknown: the candidates are a guess (D-024).
	ScopeUnknown bool
}

DelegationInput is everything views B and C read for one install.

type DelegationResult

type DelegationResult struct {
	// Rows are in RowKey order.
	Rows []Row
	// Signals are the parents' ResolvedRefs failures, by (Parent, Key).
	Signals []ParentSignal
	// Reach is (route → permitted selected child) for every in-scope route
	// with delegation refs, from selection and permission alone (rules §8.5).
	// It is sorted by (Parent, Child).
	Reach []Edge
	// Uncertain are the uncertain points of rules §8.5, sorted by (Route, Rule, Ref).
	Uncertain []Uncertain
	// UncertainKeys are each root's Root.UncertainKeys, sorted: a check under
	// one of them makes no negative expectation (rules §8.5).
	UncertainKeys []RouteKey
	// Cap names the first compute cap hit: "", "edges", "contexts", "matchers" or "depth".
	Cap string
	// Complete says which routes are in a reach closure (rules §8.5).
	Complete Completeness
	// Effective is view C per child, projected from the retained contexts (rules §5.7, §6).
	Effective map[objects.Ref]ChildEffective
}

DelegationResult is views B and C for one install (rules §5, §6, §8.5).

type Delegator added in v0.6.0

type Delegator interface {
	Delegation(in DelegationInput) DelegationResult
}

Delegator is an optional interface of a Rules: it computes views B and C (rules §5, §6). A rule set without it has no delegation; view A stays.

type DepAcc

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

DepAcc gathers the sets of one growing aggregate; DepSets.Finish unites them.

func (*DepAcc) Add

func (a *DepAcc) Add(s []objects.Ref)

Add adds s, skipping an empty set or a repeat of the last one.

type DepSets

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

DepSets hash-conses the finished dependency sets of one delegation run, so equal sets share one backing slice however often rows and contexts hold them (rules §5.7). Aggregates grow in a DepAcc and are interned only when finished, so their superseded prefixes are never kept. Interned slices are read-only. The zero value is not usable; call NewDepSets.

func NewDepSets

func NewDepSets() *DepSets

NewDepSets returns an empty intern table.

func (*DepSets) Finish

func (t *DepSets) Finish(a *DepAcc) []objects.Ref

Finish is the canonical sorted union of a's sets; a is emptied.

func (*DepSets) Intern

func (t *DepSets) Intern(s []objects.Ref) []objects.Ref

Intern returns the canonical set equal to s, which becomes canonical itself when it is the first. s is never written; an empty s is returned as is.

type Edge

type Edge struct {
	Parent, Child objects.Ref
}

Edge is a reach graph edge: Parent selects Child and Child permits it.

type EffectiveEdge

type EffectiveEdge struct {
	Parent objects.Ref
	// Mode is ModeDefault or ModeInherit, from the child's annotation.
	Mode              string
	Contexts          []Context
	ContextsTruncated bool
	Deps              []objects.Ref
}

EffectiveEdge is view C for one (parent, child) edge: the union of the retained contexts of every row with that parent and child whose fit ran, in traversal order, at most Bounds.ContextsPerEdge (rules §5.7). Contexts is non-nil; ContextsTruncated is set when any contributing row was truncated or the union passed the cap. Deps cover every contributing row.

type EffectiveRule

type EffectiveRule struct {
	Index   int
	Kept    bool
	Matches []objects.Match
	Reason  *FitFailure
}

EffectiveRule is one child rule under one parent match (view C, rules §6). A kept rule has its effective matches; a dropped one has Reason.

type EnvoyNamer

type EnvoyNamer interface {
	Object(envoyName string) (objects.Ref, bool)
}

EnvoyNamer maps an Envoy resource name, such as a cluster or route config name from proxy stats, back to its Gateway API object (design §8.8). It is pinned per kgateway version and ships only with per-version fixtures.

type Fact

type Fact struct {
	Listener  string
	Code      FactCode
	Want, Got string
}

Fact is one reason a listener did not take a parentRef.

type FactCode

type FactCode string

FactCode names the listener property a fact compares.

const (
	FactKind          FactCode = "kind"
	FactNamespace     FactCode = "namespace"
	FactSelectorError FactCode = "selector-error"
	FactPort          FactCode = "port"
	FactSection       FactCode = "section"
	FactHostname      FactCode = "hostname"
)

Fact codes.

type FitClause

type FitClause string

FitClause names the clause of the default-mode fit that dropped a child rule (rules §6).

const (
	// ClausePathType: the parent path type is not PathPrefix.
	ClausePathType FitClause = "path-type"
	// ClausePathPrefix: the child path does not start with the parent's.
	ClausePathPrefix FitClause = "path-prefix"
	// ClauseHeader and ClauseQuery: a parent header or query param is missing from the child.
	ClauseHeader FitClause = "header"
	ClauseQuery  FitClause = "query"
	// ClauseMethod: the child does not have the parent's method.
	ClauseMethod FitClause = "method"
	// ClauseDefaultSlash: omitted matches default to PathPrefix /, outside a parent prefix other than /.
	ClauseDefaultSlash FitClause = "default-slash"
	// ClauseNoMatches: an explicit empty match list in default mode (our call).
	ClauseNoMatches FitClause = "no-matches"
)

Fit clauses (rules §6).

type FitFailure

type FitFailure struct {
	Rule, Match   int
	Clause        FitClause
	Parent, Child string
}

FitFailure is why a child rule was dropped: the clause its first match failed. Match is -1 for an explicit empty list. Parent and Child are the values the clause compared; Child is empty when the child has none.

type Identity

type Identity struct {
	Install, RuleSet string
	Kind             CheckKind
	Subject          string
}

Identity is a check's identity: a rule set change gives a new one (rules §9.1).

type Labeler added in v0.6.0

type Labeler interface {
	Label() string
}

Labeler is an optional interface of a Rules: its display name, such as "kgateway 2.4".

type ListenerCount

type ListenerCount struct {
	Resource objects.Ref
	Listener string
	Count    int
	Unknown  UnknownReason
	// Error is the listener's selector error. It is computed only: kgateway
	// never reports it, and the §8 cross-check never compares it.
	Error string
	// IsolationNote marks a count that plain-HTTP listener isolation may not program (rules §4.5).
	IsolationNote bool
}

ListenerCount is a listener's computed attachedRoutes (rule listener-count).

type LogFields

type LogFields struct {
	// Time is when the controller logged the line; zero means the reader's clock.
	Time time.Time
	// Marker is which of the parser's Markers the line is; empty means the one the reader found first.
	Marker string
	// Gateway is the Gateway the line names, by namespace and name; zero when none.
	Gateway objects.Ref
	// TypeURL is the xDS type URL of a reject.
	TypeURL string
	// Names are candidate Envoy resource names from Envoy's fixed NACK shapes.
	Names []string
	// Class is an error class; one KnownLogClass does not report becomes LogClassOther.
	Class string
	// Object is the object a deployer error names, nil when none.
	Object *objects.Ref
	// Frame is a panic's top frame function, from the previous container only.
	Frame string
}

LogFields are the fixed fields one controller log line yields (design §8.9). The reader keeps a value only when it is in a closed set, so a parser that returns log text loses it there.

type LogParser

type LogParser interface {
	// Markers are the fixed substrings of the lines Parse reads; a line without one is never parsed.
	Markers() []string
	// Parse reads one line, valid only during the call. ok false with a nil
	// error means the line is not one it reads; an error means it failed, in a fixed text without log content.
	Parse(line []byte) (fields LogFields, ok bool, err error)
}

LogParser is an optional interface of a Rules: it reads the controller log lines of its kgateway version. A rule set without it reads no logs.

type LogWindow

type LogWindow interface {
	// Window is how many lines after line, which holds marker m, ParseWindow reads,
	// at most MaxLogWindow; previous reports a read of the previous container. 0 means none.
	Window(line []byte, m string, previous bool) int
	// ParseWindow reads a marked line and the lines after it, fewer at the end
	// of the read; all are valid only during the call. Results are as for Parse.
	ParseWindow(line []byte, next [][]byte, previous bool) (fields LogFields, ok bool, err error)
}

LogWindow is an optional interface of a LogParser whose marker needs the lines after it, such as a Go panic's top frame (R102).

type Member

type Member struct {
	Resource  objects.Ref
	Listener  string
	Route     objects.Ref
	ParentRef int
	// Hostnames are the effective hostnames on this listener.
	Hostnames []string
	Deps      []objects.Ref
}

Member is a route attached to a listener through one parentRef.

type Outcome

type Outcome string

Outcome is a parentRef's attachment outcome; rejections use the controller's reasons.

const (
	OutcomeAccepted   Outcome = "accepted"
	OutcomeNotAllowed Outcome = "NotAllowedByListeners"
	OutcomeNoParent   Outcome = "NoMatchingParent"
	OutcomeNoHostname Outcome = "NoMatchingListenerHostname"
)

Attachment outcomes.

type ParentSignal

type ParentSignal struct {
	Parent  objects.Ref
	Key     ReportKey
	Reasons []string
	Deps    []objects.Ref
}

ParentSignal is the ResolvedRefs=False a delegating parent's reporter receives (rules §5.4 parentSignal). Reasons are in first-seen order; Deps cover every context that recorded a failure.

type Path

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

Path is a context's path, held as its last step and a link to the path before it. Paths are immutable, so the contexts under one parent share its prefix and retained paths grow linearly with depth. A nil Path is empty.

func PathOf

func PathOf(steps ...PathStep) *Path

PathOf returns a path of steps, root first.

func (*Path) All

func (p *Path) All() iter.Seq[PathStep]

All yields the steps from the last to the root.

func (*Path) AppendSteps

func (p *Path) AppendSteps(dst []PathStep) []PathStep

AppendSteps appends the steps, root first, to dst.

func (*Path) Extend

func (p *Path) Extend(s PathStep) *Path

Extend returns p followed by s. It never changes p.

func (*Path) Last

func (p *Path) Last() PathStep

Last is the last step; p must not be empty.

func (*Path) Len

func (p *Path) Len() int

Len is the number of steps.

func (*Path) MarshalJSON

func (p *Path) MarshalJSON() ([]byte, error)

MarshalJSON encodes the steps root first, as a slice would be.

func (*Path) Parent

func (p *Path) Parent() *Path

Parent is p without its last step.

func (*Path) Steps

func (p *Path) Steps() []PathStep

Steps copies the steps, root first. Callers materialize only the paths they return, so the copy stays linear per context.

type PathStep

type PathStep struct {
	Route objects.Ref
	Match objects.Match
}

PathStep is a route on a context's path and the match it delegated under (D-024).

type PolicyTargeter

type PolicyTargeter interface {
	PolicyTargets(in TargetInput) []TargetResult
}

PolicyTargeter is an optional interface of a Rules: it resolves a policy's targets for the computed KGWUI-016. A rule set without it raises no computed 016.

type RefOutcome

type RefOutcome struct {
	Route     objects.Ref
	ParentRef int
	Resource  objects.Ref
	Outcome   Outcome
	Listeners []string
	Facts     []Fact
	Unknown   UnknownReason
	Rule      string
	Deps      []objects.Ref
}

RefOutcome is the computed outcome of one parentRef. Rule names the deciding stage: allowed-routes, section-and-port or hostname-intersection.

type ReportKey

type ReportKey struct {
	Group, Kind, Namespace, Name, SectionName string
}

ReportKey is kgateway's status report key: a parentRef as written, with empty strings for omitted fields and no port (rules §7).

func KeyOf

func KeyOf(w objects.WrittenRef) ReportKey

KeyOf is w's report key. An omitted namespace stays empty, so it differs from an explicit one; the port is dropped.

func (ReportKey) Compare

func (k ReportKey) Compare(o ReportKey) int

Compare orders report keys field by field.

type Resource

type Resource struct {
	Ref objects.Ref
	// Parent is a ListenerSet's Gateway; zero for a Gateway.
	Parent         objects.Ref
	Generation     int64
	Listeners      []objects.Listener
	ListenerStatus []objects.ListenerStatus
	Acceptance     Acceptance
}

Resource is a Gateway or ListenerSet whose listeners routes attach to.

type Root

type Root struct {
	Route               objects.Ref
	FromStatus, Unknown bool
	// Deps are the root's eligibility dependencies (rules §5.6).
	Deps []objects.Ref
	// Keys are the report keys, as written, of the parentRefs view A accepted,
	// or of the status entry a status root used: the keys the root's
	// delegation failures are written under. Rejected parentRefs and those of
	// other controllers' Gateways have none.
	Keys []ReportKey
	// UncertainKeys are the keys of parentRefs whose view A outcome is
	// unknown, not in Keys: the controller may or may not write under them.
	UncertainKeys []ReportKey
}

Root is a route delegation is evaluated from (rules §5.1). FromStatus marks a root taken from the controller's status because view A is unknown for it; Unknown marks a route that may be a root but cannot be told.

func Roots

func Roots(routes []DelegRoute, att AttachmentResult, status StatusTarget) []Root

Roots takes the roots of views B and C from view A att (rules §5.1, §5.6). A top-level route is a root when an outcome is accepted. Otherwise, with every outcome unknown, a status entry found by status makes it a status root. Any other route with an unknown outcome is an unknown root; one with only known rejections is not a root (rules §5.1, §8.5).

type Route

type Route struct {
	Ref        objects.Ref
	Generation int64
	Hostnames  []string
	ParentRefs []objects.ParentRef
	Written    []objects.WrittenRef
	Parents    []objects.RouteParentStatus
	// ExperimentalOnly is true when the controller watches this route only with experimental features on.
	ExperimentalOnly bool
}

Route is a route as view A reads it. Written is index-aligned with ParentRefs.

type RouteKey

type RouteKey struct {
	Route objects.Ref
	Key   ReportKey
}

RouteKey is a report key of one route.

type Row

type Row struct {
	Key          RowKey
	RefAsWritten objects.DelegationRef
	Allows       Allows
	Outcome      RowOutcome
	Unknown      UnknownReason
	// SomeNotComputed: a positive outcome (attached, partial or
	// rejected-hostnames) while some paths were not computed.
	// Unconfirmable: status cannot confirm this row's own outcome.
	SomeNotComputed, Unconfirmable bool
	Reason                         *FitFailure
	Unresolved                     Unresolved
	Contexts                       []Context
	ContextsTruncated              bool
	Deps                           []objects.Ref
	Reporters                      []ReportKey
	ChildKey                       ReportKey
	WritesEntry                    bool
	// ContextDigest is an order-independent digest of every contributing
	// context's incoming match, path, reporter and outcome; KeyDigests is the
	// same digest per reporter, index-aligned with Reporters. Fingerprints
	// read them (rules §9.2).
	ContextDigest uint64
	KeyDigests    []uint64
	// KeyDeps are Deps per reporter, index-aligned with Reporters: the sorted
	// union of the deps of every context under that key. Its slices are
	// read-only and may be shared.
	KeyDeps [][]objects.Ref
}

Row is one delegation row aggregated over its contexts (rules §5.5). Deps, Reporters and the digests cover every context, retained or not (rules §5.7).

type RowKey

type RowKey struct {
	Parent    objects.Ref
	Rule, Ref int
	Child     objects.Ref
}

RowKey identifies a delegation row: a parent, its rule and ref indexes and the selected child. A ref that selects nothing has one row with a zero Child (rules §5.5).

func (RowKey) Compare

func (k RowKey) Compare(o RowKey) int

Compare orders keys by parent, rule, ref and child.

type RowMeta

type RowMeta struct {
	RefAsWritten objects.DelegationRef
	Allows       Allows
	Unresolved   Unresolved
	ScopeUnknown bool
}

RowMeta is what a row knows before its contexts: the ref as written, the child's permission and, for a zero-child row, why the ref selected nothing. ScopeUnknown makes the row unknown/scope-unknown even with no contexts (D-024).

type RowOutcome

type RowOutcome string

RowOutcome is a delegation row's outcome, per context or aggregated (rules §5.5).

const (
	OutcomeAttached          RowOutcome = "attached"
	OutcomePartial           RowOutcome = "partial"
	OutcomeDropped           RowOutcome = "dropped"
	OutcomeForbidden         RowOutcome = "forbidden"
	OutcomeRejectedHostnames RowOutcome = "rejected-hostnames"
	OutcomeCycle             RowOutcome = "cycle"
	OutcomeUnresolved        RowOutcome = "unresolved"
	OutcomeUnknown           RowOutcome = "unknown"
)

Row outcomes. Partial is only ever an aggregate.

type Rules

type Rules interface {
	// Version names the rule set, such as "kgateway-2.4".
	Version() string
	// Attachment computes view A (rules §4).
	Attachment(in AttachmentInput) AttachmentResult
}

Rules computes the views for one controller rule set (design §3.4). A rule set that computes delegation also implements Delegator.

type Selection

type Selection struct {
	Rules Rules
	// Note is the selection label; it is part of every result's check note. Empty when the set matches.
	Note string
	// GatewayAPI maps a kgateway minor to its Gateway API bundle minor; nil means rulesets.ExpectedGatewayAPI.
	GatewayAPI func(kgatewayMinor string) (bundle string, ok bool)
}

Selection is the rule set chosen for a controller, with its label (rules §2).

func (Selection) Delegator added in v0.6.0

func (s Selection) Delegator() Delegator

Delegator returns the selected rule set's delegator, or nil when it has none. A wrapping rule set forwards it to keep delegation.

func (Selection) EnvoyNamer

func (s Selection) EnvoyNamer() EnvoyNamer

EnvoyNamer returns the selected rule set's namer, or nil when it has none: Envoy names are then shown as Envoy names only. kgw23 and kgw24 have none.

func (Selection) Label added in v0.6.0

func (s Selection) Label() string

Label is the selected rule set's display name: its Label, else its Version; "" without one.

func (Selection) LogParser

func (s Selection) LogParser() LogParser

LogParser returns the selected rule set's log parser, or nil when it has none.

func (Selection) PolicyTargeter

func (s Selection) PolicyTargeter() PolicyTargeter

PolicyTargeter returns the selected rule set's targeter, or nil when it has none.

func (Selection) TargetStatusReporter

func (s Selection) TargetStatusReporter() TargetStatusReporter

TargetStatusReporter returns the selected rule set's reporter, or nil when it has none. A wrapping rule set forwards it to keep the status 016.

type State

type State string

State is a cross-check's state on the wire (rules §8.4).

const (
	StateChecked    State = "checked"
	StateDisagrees  State = "disagrees"
	StatePending    State = "pending"
	StateUnknown    State = "unknown"
	StateRestricted State = "restricted"
)

Check states. StateRestricted is set at serve time (design §7.4).

type StatusTarget

type StatusTarget func(r DelegRoute) (objects.Ref, ReportKey, bool)

StatusTarget finds a route's status root (rules §5.1): the target and report key, as written, of its first current Accepted=True entry from the install's controllers for one of its Gateway or ListenerSet parents.

type TargetInput

type TargetInput struct {
	Policy     objects.Ref
	TargetRefs []TargetRef
	Selectors  []TargetSelector
	// Lookup returns the cached object of a kind by namespace and name.
	Lookup func(gk objects.GroupKind, ns, name string) (*unstructured.Unstructured, bool)
	// Labelled reports whether some cached object of a kind in ns has every label in sel;
	// an empty ns means every namespace.
	Labelled func(gk objects.GroupKind, ns string, sel map[string]string) bool
	// Served reports whether a kind is served by the API server and watched by the UI.
	Served func(gk objects.GroupKind) bool
	// ScopeKnown is false when the install's discovery scope is unknown (D-024).
	ScopeKnown bool
	// GlobalPolicyNamespace is the controller's KGW_GLOBAL_POLICY_NAMESPACE, empty when unset.
	// GlobalPolicyNamespaceKnown is false when the UI cannot read it.
	GlobalPolicyNamespace      string
	GlobalPolicyNamespaceKnown bool
}

TargetInput is one policy's targets and the lookups the rule may use (computed-rules "Policy targets").

type TargetRef

type TargetRef struct {
	Group, Kind, Name string
	// SectionName is empty when not written.
	SectionName string
}

TargetRef is a policy's spec.targetRefs entry as written. Its namespace is the policy's (GEP-713).

type TargetResult

type TargetResult struct {
	Index   int
	Ref     TargetRef
	Outcome string
	// Verifiable is true when a current ancestor can be tied to this target alone (design §7.6).
	Verifiable bool
}

TargetResult is one target's outcome. Index counts TargetRefs first, then Selectors; a selector's Ref carries its group, kind and section, with no name.

type TargetSelector

type TargetSelector struct {
	Group, Kind string
	MatchLabels map[string]string
	// SectionName is empty when not written.
	SectionName string
}

TargetSelector is a policy's spec.targetSelectors entry as written.

type TargetStatusReporter

type TargetStatusReporter interface {
	ReportsTargetNotFound() bool
}

TargetStatusReporter is an optional interface of a Rules. ReportsTargetNotFound true means the controller writes TargetNotFound on policy ancestors, so KGWUI-016 comes from status, not PolicyTargeter.

type Uncertain

type Uncertain struct {
	Route     objects.Ref
	Rule, Ref int
	Reason    UnknownReason
}

Uncertain is an uncertain point (rules §8.5): a (route, rule, ref) that was cut by a bound or whose selection or context is unknown, or a route with Rule UncertainRoot or UncertainPossible, where Ref is -1.

type UnknownReason

type UnknownReason string

UnknownReason says why a result could not be computed (rules §3.3).

const (
	UnknownNamespaceLabels   UnknownReason = "namespace-labels-unavailable"
	UnknownListenerSetStatus UnknownReason = "listenerset-no-status"
	UnknownSetting           UnknownReason = "setting-unknown"
	UnknownNotReached        UnknownReason = "not-reached"
	UnknownContext           UnknownReason = "context-unknown"
	UnknownTooLarge          UnknownReason = "too-large"
	// UnknownScope: the install's discovery scope is unknown (user, 2026-10-24).
	UnknownScope UnknownReason = "scope-unknown"
)

Unknown reasons, as served on the wire.

type Unresolved

type Unresolved string

Unresolved says why a delegation ref selects no routes (rules §5.2). It is a code; pkg/api renders the text.

const (
	// UnresolvedMissing: no in-scope route matches the ref.
	UnresolvedMissing Unresolved = "missing"
	// UnresolvedUnwatched: a name ref's target exists outside the controller's scope.
	UnresolvedUnwatched Unresolved = "unwatched"
)

Unresolved codes.

type Views

type Views struct {
	// RuleSet is the rule set's Version, Label its display name and Note its selection label.
	RuleSet, Label, Note string
	Attachment           AttachmentResult
	// Delegation is views B and C (rules §5, §6).
	Delegation DelegationResult
	Checks     []CheckResult
}

Views are one install's computed views and their cross-checks (D-020). The engine sets each check's State, Mature and Since.

Directories

Path Synopsis
Package kgw23 is the rule set for kgateway 2.3 controllers (rules §2).
Package kgw23 is the rule set for kgateway 2.3 controllers (rules §2).
Package kgw24 is the rule set for kgateway 2.4 controllers (rules §2).
Package kgw24 is the rule set for kgateway 2.4 controllers (rules §2).
Package kgw25 is the rule set for kgateway 2.5 controllers (rules §2).
Package kgw25 is the rule set for kgateway 2.5 controllers (rules §2).
Package rulesets selects the computed rule set for a controller version (rules §2).
Package rulesets selects the computed rule set for a controller version (rules §2).
Package viewa computes view A, spec-level Gateway API attachment (D-020 (A), rules §4): sectionName and port, allowedRoutes namespaces and kinds, and hostname intersection.
Package viewa computes view A, spec-level Gateway API attachment (D-020 (A), rules §4): sectionName and port, allowedRoutes namespaces and kinds, and hostname intersection.

Jump to

Keyboard shortcuts

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