explore

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: 21 Imported by: 0

Documentation

Overview

Package explore builds the per-install index of routes, Gateways and ListenerSets that the explorer serves (design §3.2, §3.5). An Index is built once per recompute and is immutable once published: handlers filter and page it, and never decode objects themselves.

Index

Constants

View Source
const (
	// MaxPaths is the number of complete paths a walk returns.
	MaxPaths = 5
	// MaxDepth is the most routes on one path.
	MaxDepth = 32
	// MaxNodes is the most route visits one walk makes.
	MaxNodes = 256
)

Up-chain bounds (design §5.3).

View Source
const (
	DefaultLimit = 50
	MaxLimit     = 200
)

Page limits (design §7.2).

View Source
const ListenerUnknown = "_unknown"

ListenerUnknown is the listener filter value that selects unknown refs. No listener name can contain "_", so it never shadows a listener.

Variables

View Source
var (
	ErrBadCursor = errors.New("bad cursor")
	ErrBadQuery  = errors.New("bad query")
)

Query errors; the handler answers both with 400 (design §7.2).

Functions

func DetailKinds

func DetailKinds(served []kinds.Served) []objects.GroupKind

DetailKinds returns the served group/kinds with a detail view: Gateway, every ListenerSet kind and HTTPRoute.

func RowState

func RowState(ref objects.Ref, rep health.Report) health.State

RowState is the state of ref's row from rep (design §6.3): any error finding on ref is error; else any required check not OK is unknown, for every row of the install; else any warning finding is warning; else healthy. Info findings never set a state.

func StatusTrueFor

func StatusTrueFor(res install.Resolved, o *install.Owned, dec objects.Decoder, gws map[objects.Ref]bool) map[objects.Ref][]objects.Ref

StatusTrueFor returns, per Gateway in gws, the owned objects whose current status is True for it (design §8.4), sorted. It is the set the gateway-rejecting flag marks.

Types

type Admission

type Admission struct {
	Owned  bool
	Reason CandidateReason
	// By is the first owned object that names a referenced candidate, or
	// the first owned parent route that selects a selected one; Referrers
	// are all of them, in row order, then ListenerSet order. Under a
	// restricting Authorizer the handler shows the first visible one.
	By        *objects.Ref
	Referrers []objects.Ref
	// NoParent marks a no-parent row; alone it admits the YAML view only.
	NoParent bool
}

Admission is why an object may be shown for the install (design §7.1).

type AncestorPath

type AncestorPath struct {
	Steps []AncestorStep
	Cycle bool
}

AncestorPath runs from the root (a Gateway or ListenerSet) down to the route asked about. Cycle marks a path whose first step is a route that already appears later on it.

type AncestorStep

type AncestorStep struct {
	Ref        objects.Ref
	Restricted bool
	Hidden     bool
}

AncestorStep is one step of an up-chain. A Restricted step, a Gateway or ListenerSet the caller may not view, has a zero Ref. A Hidden step is an ancestor route the caller may not view: it keeps its Ref, which the API sends with link none (design §7.4 rule 3, D-024).

type Attachment

type Attachment string

Attachment is how a route relates to one parent, from status only.

const (
	AttachmentAccepted    Attachment = "accepted"
	AttachmentNotAccepted Attachment = "not-accepted"
	AttachmentPending     Attachment = "pending"
	AttachmentUnwatched   Attachment = "unwatched"
	AttachmentDeclared    Attachment = "declared"
)

Attachments (design §7.3 ParentSummary).

type BackendUse

type BackendUse struct {
	Row    RowID
	Mirror bool
}

BackendUse is one row naming a backend. Mirror is set when the row names it only through RequestMirror filters.

type CandidateReason

type CandidateReason string

CandidateReason is why an object the install does not own is admitted.

const (
	ReasonFinding    CandidateReason = "finding"
	ReasonReferenced CandidateReason = "referenced"
	// ReasonSelected: a view B row of an owned parent selects the route (2.4).
	ReasonSelected CandidateReason = "selected"
)

Candidate reasons (design §7.1).

type DelegRow

type DelegRow struct {
	computed.Row
	Deps        DepSet
	ContextDeps []DepSet
	Check       *computed.CheckResult
}

DelegRow is one view B row (rules §5.5) with its dependencies interned. Deps and ContextDeps, index-aligned with Contexts, leave out the routes on each context's path, which never restrict (design §7.4 rule 4b, D-024). Check is the row's child-entry check, joined by (child, parent, ChildKey); nil when none.

type DelegationQuery

type DelegationQuery struct {
	Rule, Ref *int
	Outcomes  []computed.RowOutcome
	// Limit is 1–MaxLimit; 0 means DefaultLimit.
	Limit  int
	Cursor string
}

DelegationQuery is one delegation page request after parsing (design §7.2). Zero fields do not filter; Outcomes are OR-ed. The order is fixed.

type DepSet

type DepSet []int32

DepSet is a computed result's dependencies, as indexes into Index.Refs.

type EffectiveEntry

type EffectiveEntry struct {
	computed.ChildEffective
	EdgeDeps    []DepSet
	ContextDeps [][]DepSet
}

EffectiveEntry is view C of one child (rules §6). EdgeDeps are index-aligned with Edges and ContextDeps with each edge's Contexts; both leave out the routes on the paths, as DelegRow's do.

type Flag

type Flag uint16

Flag is a set of route row condition states (design §6.1).

const (
	FlagAccepted Flag = 1 << iota
	FlagNotAccepted
	FlagRefsUnresolved
	FlagNotProgrammed
	FlagPending
	FlagDeclared
	FlagNoParent
	// FlagDisagrees: the row's object has KGWUI-012.
	FlagDisagrees
	// FlagListenerUnknown: a status-accepted parentRef whose outcome is unknown or has no listener.
	FlagListenerUnknown
	// FlagDropped: a view B row of an owned parent selects the route and is
	// dropped, forbidden or rejected-hostnames (2.4).
	FlagDropped
	// FlagGatewayRejecting: the row's current status is True for a Gateway
	// with an active KGWUI-001 (design §8.4).
	FlagGatewayRejecting
)

Flags owned by sub-phase 2.2.

func ParseFlag

func ParseFlag(s string) (Flag, bool)

ParseFlag returns the flag with wire name s.

func (Flag) Names

func (f Flag) Names() []string

Names returns the wire names of the flags in f, in bit order.

type GatewayRow

type GatewayRow struct {
	Ref   objects.Ref
	Obj   *unstructured.Unstructured
	View  *objects.GatewayView
	State health.State
	// AttachedRoutes is the sum of status.listeners[].attachedRoutes as written.
	AttachedRoutes int32
	// Routes and NotAccepted index Index.Routes; they include routes
	// through the Gateway's ListenerSets.
	Routes, NotAccepted []RowID
	// ListenerSets index Index.ListenerSets.
	ListenerSets []RowID
	// Members are the distinct member routes of the Gateway's own listeners whose count is known.
	Members []RowID
	// Disagreements counts the checks in state disagrees on the Gateway.
	Disagreements int
}

GatewayRow is one Gateway of the install.

type Index

type Index struct {
	// Routes are sorted by (namespace, name, group, kind); a RowID into it is
	// stable within one Index only.
	Routes       []RouteRow
	Gateways     []GatewayRow
	ListenerSets []ListenerSetRow
	// ByParent keys Gateways and ListenerSets; a Gateway key also covers
	// routes through its ListenerSets. It also keys the target of an
	// unwatched row of any kind, an HTTPRoute included.
	ByParent map[objects.Ref][]RowID
	// ByParentRoute keys an HTTPRoute and lists the rows with a reported edge to it.
	ByParentRoute map[objects.Ref][]RowID
	// Declared keys an HTTPRoute and lists the rows that declare it with no reported edge.
	Declared map[objects.Ref][]RowID
	// ByBackend keys backend identity after defaults, Services and Backends
	// alike, from rule backendRefs and RequestMirror filters. Delegation refs
	// are never indexed.
	ByBackend   map[objects.Ref][]BackendUse
	ByNamespace map[string][]RowID
	// ParentRoutes maps a route to the HTTPRoutes of its reported edges.
	ParentRoutes map[objects.Ref][]objects.Ref
	NoParent     []RowID
	// Findings holds the worst error and warning finding and the finding count per object.
	Findings map[objects.Ref]Worst
	// Refs is the install's dependency table; a DepSet indexes it (design §7.4 rule 10).
	// Refs[i] for i < len(Routes) is route row i's ref.
	Refs []objects.Ref
	// ByListener lists view A's members per listener whose count is known, by row and parentRef.
	ByListener map[ListenerKey][]Member
	// Listeners holds every computed listener count.
	Listeners map[ListenerKey]ListenerFacts
	// RuleSet and RuleNote are view A's rule set and its selection label.
	RuleSet, RuleNote string
	// DelegRows are view B's rows, sorted by (parent, rule, ref, child), each
	// ref by (namespace, name, group, kind).
	DelegRows []DelegRow
	// Delegation maps a parent route to its rows, as DelegRows indexes in order.
	Delegation map[objects.Ref][]int
	// RefRows maps one delegation ref of a parent to its rows, as Delegation does.
	RefRows map[RefKey][]int
	// Effective is view C per child route.
	Effective map[objects.Ref]EffectiveEntry
	// RefScope is, per delegation ref, the routes its selection reads; a
	// caller who cannot view them all sees the ref as selection-restricted.
	RefScope map[RefKey]DepSet
	// TooLarge holds the refs a compute cap (edges, contexts or matchers) cut;
	// one with no rows reads too large to compute (rules §5.7, D-025).
	TooLarge map[RefKey]bool
	// Unreached maps a child route to its rows that no context reached and
	// whose Deps, its parent's root eligibility, are not empty, as
	// DelegRows indexes in order. Such a row has no effective edge.
	Unreached map[objects.Ref][]int
	// DelegationCap names the first compute cap views B and C hit, or "".
	DelegationCap string
	// contains filtered or unexported fields
}

Index is the explorer's view of one install. It is immutable.

func Build

func Build(in Input) *Index

Build builds the index of one install. It is pure: the same input gives the same rows in the same order, whatever the snapshot's order.

func (*Index) Admission

func (ix *Index) Admission(ref objects.Ref) (Admission, bool)

Admission returns why ref is admitted, or false when it is not. Admitted does not mean the object exists: a referenced ref may name an absent one. The handler still looks the object up and applies the Authorizer.

func (*Index) Ancestors

func (ix *Index) Ancestors(route objects.Ref, visible func(objects.Ref) bool) (paths []AncestorPath, truncated bool)

Ancestors walks up from route over reported edges, depth-first with parents sorted by (namespace, name). It stops after MaxPaths paths, at MaxDepth routes per path, or after MaxNodes route visits, whichever comes first, and then reports truncated; it never counts what remains.

A path ends at a Gateway or ListenerSet whose status reported the route as accepted or not accepted. A route with no such root yields no path.

A Gateway or ListenerSet that visible rejects becomes a Restricted step with no identity; paths identical after that redaction are returned once. An ancestor route that visible rejects becomes a Hidden step that keeps its name (D-024). The walk does not continue past either, so a hidden route's own parents, read from its status, are never named (design §7.4 rule 3).

func (*Index) DupFacts

func (ix *Index) DupFacts(id RowID, l ParentLink, k int) *RefFacts

DupFacts returns view A's facts for l's spec index l.Dups[k], or nil.

func (*Index) Facts

func (ix *Index) Facts(id RowID, l ParentLink) *RefFacts

Facts returns view A's facts for parent link l of row id, or nil.

func (*Index) FindGateway

func (ix *Index) FindGateway(ref objects.Ref) (RowID, bool)

FindGateway returns the row of Gateway ref.

func (*Index) FindListenerSet

func (ix *Index) FindListenerSet(ref objects.Ref) (RowID, bool)

FindListenerSet returns the row of ListenerSet ref.

func (*Index) GatewayMemberCount

func (ix *Index) GatewayMemberCount(id RowID) (n int, ok bool)

GatewayMemberCount is the routes column of Gateway row id and its sort value: its distinct member routes, hidden ones too, as a listener's count (design §7.4 rule 5). ok is false when a listener's count is unknown.

func (*Index) ListenerSetMemberCount

func (ix *Index) ListenerSetMemberCount(id RowID) (n int, ok bool)

ListenerSetMemberCount is GatewayMemberCount for ListenerSet row id.

func (*Index) QueryDelegation

func (ix *Index) QueryDelegation(parent objects.Ref, q DelegationQuery, visible func(objects.Ref) bool) (Page, error)

QueryDelegation pages parent's delegation rows that match q; Page.IDs index DelegRows, and a negative ID -1-i is the restricted row of a selection-restricted ref, the ref of DelegRows[i]: it replaces the ref's zero-child rows and matches no outcome (our call, 2.4). A row whose child visible rejects is left out; a row with no child never is (design §7.4 rule 3). The outcome filter matches a row only when visible admits every ref of its Deps, which leave out the routes on its paths (rules 4a, 4b). Both apply before Total and paging; nil admits every row.

func (*Index) QueryGateways

func (ix *Index) QueryGateways(in Query, visible func(objects.Ref) bool) (Page, error)

QueryGateways pages the Gateway rows, as QueryRoutes does. The routes sort uses GatewayMemberCount, as the list row's routes column does.

func (*Index) QueryListenerSets

func (ix *Index) QueryListenerSets(in Query, visible func(objects.Ref) bool) (Page, error)

QueryListenerSets pages the ListenerSet rows, as QueryRoutes does. Parent, when set, is a Gateway.

func (*Index) QueryRoutes

func (ix *Index) QueryRoutes(q Query, visible func(objects.Ref) bool) (Page, error)

QueryRoutes pages the route rows that match q and that visible admits. visible runs before Total, paging and cursors (design §7.4 rule 1); nil admits every row. The Backends filter reads the visible routes' specs through ByBackend and never looks up a backend (rule 2a).

func (*Index) Ref

func (ix *Index) Ref(i int32) objects.Ref

Ref returns the ref at index i of the dependency table.

func (*Index) Row

func (ix *Index) Row(ref objects.Ref) (RowID, bool)

Row returns the row of route ref. It searches by index, as slices.BinarySearchFunc would copy a whole RouteRow per probe.

func (*Index) RowFlags

func (ix *Index) RowFlags(id RowID, visible func(objects.Ref) bool) Flag

RowFlags are row id's flags for a caller: listener-unknown needs the dependencies of any one unknown parent visible, and dropped those of any one flagging row (design §7.4 rule 6); disagrees is a finding (rule 9).

func (*Index) SelectionHidden

func (ix *Index) SelectionHidden(k RefKey, visible func(objects.Ref) bool) bool

SelectionHidden reports whether visible rejects a route that ref k's selection reads: the ref is then selection-restricted (our call, 2.4).

func (*Index) Under

func (ix *Index) Under(id RowID, parent objects.Ref, a Attachment, visible func(objects.Ref) bool) bool

Under reports whether route row id is listed under parent with attachment a, or any attachment when a is "". A link through a ListenerSet counts only when visible admits the ListenerSet, whose spec names the Gateway (design §7.4 rule 3); nil admits every one.

func (*Index) Visible

func (ix *Index) Visible(d DepSet, visible func(objects.Ref) bool) bool

Visible reports whether visible admits every ref of d; nil admits all.

type Input

type Input struct {
	Install    install.Resolved
	Owned      *install.Owned
	Assignment install.Assignment
	Snapshot   *cache.Snapshot
	Served     []kinds.Served
	Health     health.Report
	// Views decodes typed views; nil decodes directly.
	Views objects.Decoder
	// Computed is the install's view A; nil computes no members or computed flags.
	Computed *computed.Views
}

Input is everything Build reads for one install.

type ListenerFacts

type ListenerFacts struct {
	Count         int
	Known         bool
	Unknown       computed.UnknownReason
	Error         string
	IsolationNote bool
	// Check is the listener-count cross-check, shared with the views; nil when none.
	Check *computed.CheckResult
}

ListenerFacts is a listener's computed count and its cross-check.

type ListenerHit

type ListenerHit struct {
	Listener  string
	Hostnames []string
	Deps      DepSet
}

ListenerHit is one listener an accepted parentRef attaches to.

type ListenerKey

type ListenerKey struct {
	Resource objects.Ref
	Listener string
}

ListenerKey names one listener of a Gateway or ListenerSet.

type ListenerSetRow

type ListenerSetRow struct {
	Ref         objects.Ref
	Obj         *unstructured.Unstructured
	View        *objects.ListenerSetView
	Parent      objects.Ref
	ParentFound bool
	State       health.State
	// AcceptedReason is the reason of an Accepted condition that is not True.
	AcceptedReason string
	// Routes index Index.Routes.
	Routes []RowID
	// Members and Disagreements are as on GatewayRow.
	Members       []RowID
	Disagreements int
}

ListenerSetRow is one ListenerSet of the install.

type Member

type Member struct {
	Row       RowID
	ParentRef int
	Hostnames []string
	Deps      DepSet
}

Member is a route row on a listener through one parentRef (spec index).

type Page

type Page struct {
	IDs        []RowID
	Total      int
	Next, Prev string
}

Page is one page of a list. IDs index the list the query ran on. Total counts every visible row that matches, not only this page.

type ParentLink struct {
	// Target is the object the parentRef names; Ref is the parentRef after defaults.
	Target objects.Ref
	Ref    objects.ParentRef
	// Via is the Gateway of a ListenerSet target, when the install owns it.
	Via        *objects.Ref
	Attachment Attachment
	// Cond is the deciding condition: the first current False among
	// Accepted, ResolvedRefs and kgateway.dev/Programmed (design §7.3).
	Cond *metav1.Condition
	// Pending is why the status entry is not current, for a pending link.
	Pending string
	// Spec is the index of Ref in the row's spec parentRefs, or -1.
	Spec int
	// Dups are the later spec indexes that resolve to Ref; one written
	// differently has its own report key and check (rules §8.2). Usually nil.
	Dups []int
}

ParentLink is one parent of a route row.

type Query

type Query struct {
	Namespaces []string
	Kinds      []objects.GroupKind
	Parent     *objects.Ref
	Attachment Attachment
	// Listener needs a Gateway or ListenerSet Parent: a listener name selects
	// its computed members; ListenerUnknown the rows whose ref to Parent is unknown.
	Listener string
	// Backends are OR-ed through ByBackend: specs only, never the backend object.
	Backends []objects.Ref
	States   Flag
	Health   []health.State
	Q        string
	Sort     Sort
	// Limit is 1–MaxLimit; 0 means DefaultLimit.
	Limit  int
	Cursor string
}

Query is one list request after parsing (design §7.2). Zero fields do not filter. Kinds, Parent, Attachment, Listener, Backends and States apply to routes only; Parent on ListenerSets is a Gateway.

type RefFacts

type RefFacts struct {
	Out       *computed.RefOutcome
	Listeners []ListenerHit
	// Check is the route-accepted cross-check of the ref's report key, shared with the views; nil when none.
	Check *computed.CheckResult
	Deps  DepSet
}

RefFacts is view A's outcome of one parentRef of a route row. Out is the source outcome, shared with the views: its ParentRef is the spec index and its Resource the target. Listeners and Deps replace Out's.

type RefKey

type RefKey struct {
	Parent    objects.Ref
	Rule, Ref int
}

RefKey names one delegation ref of a parent route by rule and ref index.

type RouteRow

type RouteRow struct {
	Ref  objects.Ref
	Kind kinds.Served
	Obj  *unstructured.Unstructured
	// View is the decoded HTTPRoute; nil for other kinds.
	View      *objects.HTTPRouteView
	Hostnames []string
	Parents   []ParentLink
	// ParentRoutes are the HTTPRoutes of the row's reported edges.
	ParentRoutes []objects.Ref
	// Children counts the routes with a reported edge to this one.
	Children int
	Flags    Flag
	State    health.State
	// Owned is true when the install owns the route.
	Owned bool
	// Computed is view A per parentRef to a Gateway or ListenerSet, in parentRef order.
	Computed []RefFacts
	// UnknownDeps are the distinct dependency sets of the parentRefs that set
	// FlagListenerUnknown, one per parent. The flag shows when any one of them
	// is visible (design §7.4 rule 6).
	UnknownDeps []DepSet
	// DroppedDeps are the distinct Deps of the rows that set FlagDropped,
	// which leave out the routes on their paths (D-024). The flag shows when
	// any one of them is visible.
	DroppedDeps []DepSet
	// contains filtered or unexported fields
}

RouteRow is one route the install lists (design §3.5): an owned route, attached or not; an in-scope route naming a missing parent; an unwatched route that targets the install; a declared candidate; or a no-parent row.

type RowID

type RowID int32

RowID indexes Index.Routes, Index.Gateways or Index.ListenerSets, as the field holding it says.

type Sort

type Sort struct {
	Key  string
	Desc bool
}

Sort is a list order. The empty key is name. Every order ends with the ascending (namespace, name, group, kind) tie-break; for name that tuple is the order itself, so name.desc reverses it.

type Worst

type Worst struct {
	Error, Warning *health.Finding
	N              int
}

Worst is the first error and the first warning finding on one object, and N counts all of its findings, info included.

func (Worst) Add

func (w Worst) Add(f *health.Finding) Worst

Add counts f and records it if it is the first error or warning.

func (Worst) Reason

func (w Worst) Reason(st health.State) *health.RowReason

Reason says why a row in state st with these findings is not healthy: its deciding finding, the install-wide unknown, or else a rejecting Gateway, the only other way to warning (D-063). It is nil for a healthy row.

func (Worst) State

func (w Worst) State(unknown bool) health.State

State applies the row rule; unknown is set when a required check is not OK.

Jump to

Keyboard shortcuts

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