Documentation
¶
Overview ¶
Package paths builds the path model of Phase 6 (design §4): one row per way traffic can flow from a Gateway listener through a route rule to a backend. Topology is derived from one snapshot generation and is immutable once built.
Index ¶
- Constants
- type Action
- type Backend
- type BackendFacets
- type BackendGatewayFacet
- type BackendNamespaceFacet
- type BackendPage
- type BackendQuery
- type BackendSet
- type BackendsInput
- type Counts
- type DelegState
- type Endpoints
- type Facets
- type GatewayFacet
- type Input
- type Listener
- type Memo
- type NamespaceFacet
- type Page
- type Problem
- type ProjectInput
- type Projection
- type Query
- type Row
- type Share
- type ShareState
- type Signal
- type Summary
- type TopoKey
- type Topology
- func (t *Topology) Action(r Row) Action
- func (t *Topology) Attachment(r Row) int32
- func (t *Topology) Backend(r Row) (objects.BackendRef, bool)
- func (t *Topology) Bytes() int
- func (t *Topology) Chain(r Row) []objects.Ref
- func (t *Topology) Delegation(r Row) DelegState
- func (t *Topology) Deps(r Row) explore.DepSet
- func (t *Topology) Gateway(r Row) objects.Ref
- func (t *Topology) Hostnames(r Row) []string
- func (t *Topology) Listener(r Row) Listener
- func (t *Topology) ListenerSet(r Row) *objects.Ref
- func (t *Topology) Mirror(r Row) (objects.MirrorFilter, bool)
- func (t *Topology) RefIndex(r Row) (int, bool)
- func (t *Topology) Route(r Row) objects.Ref
- func (t *Topology) RowID(r Row) string
- func (t *Topology) Rule(r Row) *objects.Rule
Constants ¶
const ( BackendSortProblem = "problem" BackendSortName = "name" BackendSortUsed = "used" )
Backend list sort keys (design §8.1); the empty key is BackendSortProblem.
const ( UsedYes = "yes" UsedNo = "no" )
Values of BackendQuery.Used.
const ( SignalGateway = "gateway" SignalListener = "listener" SignalRouteStatus = "route-status" SignalWaiting = "waiting" SignalFinding = "finding" SignalDelegation = "delegation" SignalCoverage = "coverage" )
Signal kinds: where a problem's signal comes from (design §4.5).
const ( EndpointsComplete = "complete" EndpointsFailed = "failed" EndpointsNotApplicable = "not-applicable" )
Endpoint completeness (design §9.2). Only a complete read establishes zero.
const ( SortProblem = "problem" SortGateway = "gateway" SortRoute = "route" SortBackend = "backend" SortHostname = "hostname" )
Sort keys (design §5); the empty key is SortProblem.
const ( MirrorInclude = "include" MirrorOnly = "only" MirrorExclude = "exclude" )
Mirror filter values; the empty value is MirrorInclude.
const ( DefaultLimit = explore.DefaultLimit MaxLimit = explore.MaxLimit )
Page limits, as the explorer's.
const EndpointsOn = "on"
EndpointsOn is the endpoints capability state in which counts are read.
const TopologyCap = 2 << 20
TopologyCap is the topology memo's cap per install generation, in Bytes (design §14).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend struct {
Ref objects.Ref
// Type is a kgateway Backend's spec.type; "" for other kinds.
Type string
// Paths are its visible path rows; Confirmed those on an attachment its
// route's status accepts.
Paths, Confirmed int
// Routes write it; Gateways carry its paths. Both are sorted.
Routes, Gateways []objects.Ref
Consumers []objects.Consumer
// Ports are the distinct ports written for it, sorted; 0 is left out.
Ports []int32
// Endpoints are a Service's per Ports entry the cache knows, or one
// not-applicable summary for a Backend.
Endpoints []*Endpoints
// Own are its own distinct signals, as Problem orders them: endpoints,
// KGWUI-002, else the judge's verdict.
Own []Signal
// Problem is the worst of its path problems, its own signals and the
// attachment signals of routes that write it with no path to it.
Problem Problem
}
Backend is one listed backend as a viewer may see it (design §8.1). Everything it holds is visible to that viewer.
type BackendFacets ¶
type BackendFacets struct {
Gateways []BackendGatewayFacet
Namespaces []BackendNamespaceFacet
}
BackendFacets list the values of the gateway and namespace filters over the set's backends, which are the visible ones. Each facet applies every filter but its own, so a selected value leaves the others selectable. Both are sorted by name.
type BackendGatewayFacet ¶
BackendGatewayFacet is a Gateway and the backends it has a visible path to.
type BackendNamespaceFacet ¶
BackendNamespaceFacet is a namespace and the backends in it.
type BackendPage ¶
type BackendPage struct {
Items []int
Next, Prev string
Facets BackendFacets
}
BackendPage is one page of a BackendSet's items, as indexes into Items, and the facets of the whole set.
func RunBackends ¶
func RunBackends(set BackendSet, q BackendQuery) (BackendPage, error)
RunBackends pages the items of set that match q. Bad input is explore.ErrBadQuery or explore.ErrBadCursor.
type BackendQuery ¶
type BackendQuery struct {
// Kind is the backend's kind, such as Service or Backend.
Kind string
Namespace string
States []health.State
// Used is yes for a backend a visible route or consumer uses, no for one none does.
Used string
// Gateways match a backend with a visible path through one of them, by namespace and name.
Gateways []objects.Ref
// Q matches, ignoring case, the backend's namespace/name.
Q string
// Sort orders by its key, Desc reversing it; ties keep namespace, name, group and kind order.
Sort string
Desc bool
Cursor string
// Limit is 1–MaxLimit; 0 means DefaultLimit.
Limit int
}
BackendQuery is one backend list request (design §8.1). Zero fields do not filter.
type BackendSet ¶
BackendSet is the listed backends, in no order, and whether any backend, path row, route or consumer was left out for the viewer.
func Backends ¶
func Backends(t *Topology, p *Projection, in BackendsInput) BackendSet
Backends lists the backends of design §8.1 from t, projected by p: every in-scope Backend, every backendRef or mirror target an owned route writes (attached or not), and every consumer's backend. A backend, row, route or consumer the viewer may not see is left out and counted nowhere.
type BackendsInput ¶
type BackendsInput struct {
ProjectInput
// Served are the model's served kinds, for the in-scope Backends.
Served []kinds.Served
// Consumers are the install's non-route backend consumers.
Consumers []objects.Consumer
// Visible admits a path row by its deps and Can a ref; nil admits all (design §13).
Visible func(explore.DepSet) bool
Can func(objects.Ref) bool
// Only, when set, lists that backend alone, if it is listed.
Only *objects.Ref
}
BackendsInput is what Backends reads besides the topology and projection.
type Counts ¶
type Counts struct{ Paths, Routes, Gateways, Backends int }
Counts are a Summary's counts for one state.
type DelegState ¶
type DelegState struct {
// Provenance are the routes that delegated to the row's route, root first.
Provenance []objects.Ref
// Matches are the view C effective matches of a delegated row's rule on
// this path; nil on a root route or where view C has none.
Matches []objects.Match
// Unknown is set when view C cannot tell this path's outcome.
Unknown computed.UnknownReason
// Unconfirmable, NotComputed and Truncated are the view C row's
// Unconfirmable, SomeNotComputed and ContextsTruncated: a truncated row
// has more paths not computed.
Unconfirmable, NotComputed, Truncated bool
}
DelegState is a row's delegation state from view C (design §4.2). It is zero on a root route's row other than a delegation row.
type Endpoints ¶
type Endpoints struct {
Complete string
Ready, Total *int
ReadAt time.Time
Port int32
PortName string
}
Endpoints is a row's backend port endpoint summary. Ready and Total are set only for a complete read.
type Facets ¶
type Facets struct {
Gateways []GatewayFacet
Namespaces []NamespaceFacet
}
Facets list the values of the gateway and namespace filters over the visible rows. Each facet applies every filter but its own, so a selected Gateway leaves the others selectable. Both are sorted by name.
type GatewayFacet ¶
GatewayFacet is a Gateway and the paths through it.
type Input ¶
type Input struct {
// Index locates the attached routes, Gateways and ListenerSets.
Index *explore.Index
// Views holds view A; Delegation is set only with a Delegator.
Views *computed.Views
// Decode decodes HTTPRoute rules.
Decode objects.Decoder
// Delegates is true when the selection has a Delegator.
Delegates bool
}
Input is everything Build reads for one install. A nil Index, Views or Decode builds an empty topology.
type Memo ¶
type Memo struct {
// contains filtered or unexported fields
}
Memo holds, per install, one topology generation and one projection of it (design §4.3). It is viewer-independent; callers authorise every row per request, memo hits included.
Invariant: the memo keeps no pointer to a Model, Snapshot, Index or object, so an old publication is collectable as soon as the engine drops it. A Topology shares only decoded rules and view C matches; a Projection holds only data it made. A projection is keyed by its model's Seq, not the model.
func NewMemo ¶
func NewMemo(c clock.PassiveClock) *Memo
NewMemo returns an empty memo whose projections expire by c; nil is the real clock.
func NewMemoCap ¶
func NewMemoCap(c clock.PassiveClock, capBytes int) *Memo
NewMemoCap is NewMemo with a topology cap of capBytes instead of TopologyCap.
func (*Memo) Projection ¶
func (m *Memo) Projection(pub *engine.Published, install string, t *Topology, project func() *Projection) *Projection
Projection returns t's projection for pub's model, projecting on a miss. It is kept only for the install's memoised topology, and never reused at or after its Next, nor for another model, even over the same snapshot.
func (*Memo) Prune ¶
Prune drops the entries of installs that publication m does not have. It runs once per newer Seq; older or repeated publications return at once.
type NamespaceFacet ¶
NamespaceFacet is a route namespace and the paths whose chain has a route in it.
type Page ¶
type Page struct {
Rows []int32
Next, Prev string
Summary Summary
// Digest is the whole ordered result's Projection.Digest, every page's alike.
Digest uint64
}
Page is one page of rows, as indexes into Topology.Rows, and the summary of every visible row the filters match.
type Problem ¶
Problem is a row's worst signal state and the signals that are not healthy.
func AttachmentProblems ¶
func AttachmentProblems(t *Topology, in ProjectInput, rows []int32) []Problem
AttachmentProblems is the own problem of each row's attachment, index-aligned with rows: its Gateway, listener and route parent status signals as Project derives them, a current ResolvedRefs=False included. Nothing is retained.
type ProjectInput ¶
type ProjectInput struct {
Model *engine.InstallModel
// Next is engine.Model.Next of the publication that Model is part of.
Next engine.Deadline
Snapshot *cache.Snapshot
Now time.Time
// EndpointsCap is the endpoints capability state: on, off, denied or failing.
EndpointsCap string
}
ProjectInput is what Project reads besides the topology.
type Projection ¶
type Projection struct {
Problems []Problem
Endpoints []*Endpoints
// Order are the row indexes, problem first, then Gateway, listener, route, rule and RowID.
Order []int32
// Next is ProjectInput.Next: the projection is not reused once it is due.
Next engine.Deadline
// contains filtered or unexported fields
}
Projection is the health of a topology's rows for one model publication. Problems, Shares and Endpoints are index-aligned with Topology.Rows.
func Project ¶
func Project(t *Topology, in ProjectInput) *Projection
Project maps each row of t to its problem: the worst existing signal along its whole chain (design §4.5). It adds no checks. in.Model must be set.
func (*Projection) Bytes ¶
func (p *Projection) Bytes() int
Bytes estimates the projection's retained size: its row tables plus each distinct signal set and endpoint summary once. Strings shared with the topology and the model are not counted.
func (*Projection) Digest ¶
func (p *Projection) Digest(rows []int32) uint64
Digest is the ordered digest of rows: each row's content in that order. Two results digest alike only when a client would show them alike.
type Query ¶
type Query struct {
// Gateways match a row's Gateway by namespace and name; a ListenerSet row has its parent's.
Gateways []objects.Ref
// Listener is a listener name.
Listener string
// Route matches any route of the row's chain.
Route *objects.Ref
// Backends match the row's backendRef or mirror target; a delegation is no backend.
Backends []objects.Ref
// Namespace matches the namespace of any route of the chain.
Namespace string
States []health.State
// Kind is the root route's kind, such as GRPCRoute.
Kind string
Mirror string
// Q matches, ignoring case, any hostname, a route name of the chain or the backend name.
Q string
// Sort orders by its key, Desc reversing it; ties keep the problem-first order.
Sort string
Desc bool
Cursor string
// Limit is 1–MaxLimit; 0 means DefaultLimit.
Limit int
}
Query is one path list request (design §5). Zero fields do not filter.
type Row ¶
type Row struct {
// contains filtered or unexported fields
}
Row is one path: an attachment, a rule of the last route of its chain, and one backendRef or mirror of that rule. It holds indexes into its Topology.
type Share ¶
type Share struct {
}
Share is a ref's percent of its own rule's requests, never of Gateway traffic.
func MirrorShare ¶
func MirrorShare(m *objects.MirrorFilter) Share
MirrorShare is a mirror's written percent (100 when unset), not a share.
func Shares ¶
Shares returns one Share per rule.BackendRefs entry, as weight over the sum of the rule's weights. Rules with a delegation ref show no shares.
func (Share) WithAttribution ¶
WithAttribution marks a shown share failing when the failure is attributed to its ref, or may-fail when the ref is only a candidate. The percent is kept.
type ShareState ¶
type ShareState string
ShareState is how a backend ref's share is presented (design §4.4).
const ( )
Share states.
type Signal ¶
Signal is one existing signal on a row's chain. Code is a finding code, a condition type, a capability state or a view C reason; Ref is its object. Listener names the listener of Ref a listener's signal is about; "" otherwise.
type Summary ¶
type Summary struct {
Paths, Routes, Gateways, Backends int
// ByState holds every state, zero counts included.
ByState map[health.State]Counts
// EndpointsNotRead is set when a row's endpoints failed or were not read.
EndpointsNotRead bool
// Hidden is set when visible dropped any row.
Hidden bool
// Facets are the Gateways and route namespaces the viewer can narrow to.
Facets Facets
// Unmemoised is set by the caller when the topology was over the memo cap.
Unmemoised bool
}
Summary counts the filtered rows a viewer may see (design §5, §13). Routes are the routes whose rule a row is on; Backends exclude delegations.
type TopoKey ¶
type TopoKey struct {
Install string
// Source is the snapshot's Source; equal sources describe the same objects.
Source cache.Fingerprint
// Views is the install's computed.Views.Generation; 0 without views.
Views uint64
// Seq is the publication's Model.Seq; an older key never replaces a newer one.
Seq uint64
}
TopoKey is a topology's generation: its install's snapshot source and computed views generation, and the publication that asked for it.
type Topology ¶
type Topology struct {
Rows []Row
// Refs is the dependency table; a row's Deps index it.
Refs []objects.Ref
// contains filtered or unexported fields
}
Topology is the path rows of one install for one snapshot generation. It and everything its accessors return are read-only.
func Build ¶
Build derives the topology of in: one row per (view A attachment, rule, backendRef), one per rule with no backendRef, and one per RequestMirror, then the same per view C context for delegated routes.
func (*Topology) Action ¶
Action is what the row's rule does: ActionBackend for a backendRef or a mirror, else the rule's written action.
func (*Topology) Attachment ¶
Attachment is the index of row r's attachment; rows of one view A member share it.
func (*Topology) Backend ¶
func (t *Topology) Backend(r Row) (objects.BackendRef, bool)
Backend is the row's backendRef; false for a mirror row or a rule with no backendRef. Without a Delegator, a ref to an HTTPRoute is ordinary.
func (*Topology) Bytes ¶
Bytes estimates the topology's retained size, for the memo cap (design §14). HTTPRoute rules and view C matches are shared, not counted.
func (*Topology) Delegation ¶
func (t *Topology) Delegation(r Row) DelegState
Delegation is the row's delegation state.
func (*Topology) Deps ¶
Deps is the row's dependency set: its attachment's, the Gateway, every route of its chain, its backend or mirror target and, on a delegated route, its view C row's, as indexes into Refs.
func (*Topology) Gateway ¶
Gateway is the row's Gateway; a ListenerSet attachment projects to its parent.
func (*Topology) Hostnames ¶
Hostnames are the attachment's effective hostnames; nil for kinds without hostnames.
func (*Topology) ListenerSet ¶
ListenerSet is the row's ListenerSet, or nil for a Gateway attachment.
func (*Topology) Mirror ¶
func (t *Topology) Mirror(r Row) (objects.MirrorFilter, bool)
Mirror is the row's RequestMirror filter; false unless it is a mirror row.
func (*Topology) RefIndex ¶
RefIndex is the index of row r's backendRef in its rule; false for a mirror row or a rule with no backendRef.
func (*Topology) RowID ¶
RowID is r's identity: a hash of what the row shows of its attachment (Gateway, ListenerSet, listener, parentRef), chain, effective matches, rule, ref and mirror, then its place among rows that hash alike. No two rows of one Topology share it; equal input gives equal IDs. Being content, not a position, it says nothing of rows a viewer may not see (design §13).