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
- Variables
- func DetailKinds(served []kinds.Served) []objects.GroupKind
- func RowState(ref objects.Ref, rep health.Report) health.State
- func StatusTrueFor(res install.Resolved, o *install.Owned, dec objects.Decoder, ...) map[objects.Ref][]objects.Ref
- type Admission
- type AncestorPath
- type AncestorStep
- type Attachment
- type BackendUse
- type CandidateReason
- type DelegRow
- type DelegationQuery
- type DepSet
- type EffectiveEntry
- type Flag
- type GatewayRow
- type Index
- func (ix *Index) Admission(ref objects.Ref) (Admission, bool)
- func (ix *Index) Ancestors(route objects.Ref, visible func(objects.Ref) bool) (paths []AncestorPath, truncated bool)
- func (ix *Index) DupFacts(id RowID, l ParentLink, k int) *RefFacts
- func (ix *Index) Facts(id RowID, l ParentLink) *RefFacts
- func (ix *Index) FindGateway(ref objects.Ref) (RowID, bool)
- func (ix *Index) FindListenerSet(ref objects.Ref) (RowID, bool)
- func (ix *Index) GatewayMemberCount(id RowID) (n int, ok bool)
- func (ix *Index) ListenerSetMemberCount(id RowID) (n int, ok bool)
- func (ix *Index) QueryDelegation(parent objects.Ref, q DelegationQuery, visible func(objects.Ref) bool) (Page, error)
- func (ix *Index) QueryGateways(in Query, visible func(objects.Ref) bool) (Page, error)
- func (ix *Index) QueryListenerSets(in Query, visible func(objects.Ref) bool) (Page, error)
- func (ix *Index) QueryRoutes(q Query, visible func(objects.Ref) bool) (Page, error)
- func (ix *Index) Ref(i int32) objects.Ref
- func (ix *Index) Row(ref objects.Ref) (RowID, bool)
- func (ix *Index) RowFlags(id RowID, visible func(objects.Ref) bool) Flag
- func (ix *Index) SelectionHidden(k RefKey, visible func(objects.Ref) bool) bool
- func (ix *Index) Under(id RowID, parent objects.Ref, a Attachment, visible func(objects.Ref) bool) bool
- func (ix *Index) Visible(d DepSet, visible func(objects.Ref) bool) bool
- type Input
- type ListenerFacts
- type ListenerHit
- type ListenerKey
- type ListenerSetRow
- type Member
- type Page
- type ParentLink
- type Query
- type RefFacts
- type RefKey
- type RouteRow
- type RowID
- type Sort
- type Worst
Constants ¶
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).
const ( DefaultLimit = 50 MaxLimit = 200 )
Page limits (design §7.2).
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 ¶
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 ¶
DetailKinds returns the served group/kinds with a detail view: Gateway, every ListenerSet kind and HTTPRoute.
func RowState ¶
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 ¶
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 ¶
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 ¶
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.
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, RuleLabel and RuleNote are view A's rule set, its display name and its selection label.
RuleSet, RuleLabel, 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 ¶
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 ¶
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 ¶
FindGateway returns the row of Gateway ref.
func (*Index) FindListenerSet ¶
FindListenerSet returns the row of ListenerSet ref.
func (*Index) GatewayMemberCount ¶
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 ¶
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 ¶
QueryGateways pages the Gateway rows, as QueryRoutes does. The routes sort uses GatewayMemberCount, as the list row's routes column does.
func (*Index) QueryListenerSets ¶
QueryListenerSets pages the ListenerSet rows, as QueryRoutes does. Parent, when set, is a Gateway.
func (*Index) QueryRoutes ¶
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) Row ¶
Row returns the row of route ref. It searches by index, as slices.BinarySearchFunc would copy a whole RouteRow per probe.
func (*Index) RowFlags ¶
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 ¶
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.
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
// Conditions are the install's route condition types beyond Gateway API's;
// nil means health.KgatewayConditions, as for health.Input.
Conditions *health.ConditionTypes
}
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 ¶
ListenerHit is one listener an accepted parentRef attaches to.
type ListenerKey ¶
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 Page ¶
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 ¶
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 the install's optional route types (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 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 ¶
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 ¶
Worst is the first error and the first warning finding on one object, and N counts all of its findings, info included.