paths

package
v0.7.0 Latest Latest
Warning

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

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

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

View Source
const (
	BackendSortProblem = "problem"
	BackendSortName    = "name"
	BackendSortUsed    = "used"
)

Backend list sort keys (design §8.1); the empty key is BackendSortProblem.

View Source
const (
	UsedYes = "yes"
	UsedNo  = "no"
)

Values of BackendQuery.Used.

View Source
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).

View Source
const (
	EndpointsComplete      = "complete"
	EndpointsFailed        = "failed"
	EndpointsUnavailable   = "unavailable"
	EndpointsNotApplicable = "not-applicable"
)

Endpoint completeness (design §9.2). Only a complete read establishes zero.

View Source
const (
	SortProblem  = "problem"
	SortGateway  = "gateway"
	SortRoute    = "route"
	SortBackend  = "backend"
	SortHostname = "hostname"
)

Sort keys (design §5); the empty key is SortProblem.

View Source
const (
	MirrorInclude = "include"
	MirrorOnly    = "only"
	MirrorExclude = "exclude"
)

Mirror filter values; the empty value is MirrorInclude.

View Source
const (
	DefaultLimit = explore.DefaultLimit
	MaxLimit     = explore.MaxLimit
)

Page limits, as the explorer's.

View Source
const EndpointsOn = "on"

EndpointsOn is the endpoints capability state in which counts are read.

View Source
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 Action

type Action uint8

Action is what a row's rule does with a request, as written.

const (
	ActionBackend Action = iota
	ActionRedirect
	ActionDirectResponse
	ActionNone
)

Actions. A rule with no backendRef has its written action; no intent is inferred.

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.

func (*Backend) Used

func (b *Backend) Used() int

Used is the number of visible routes and consumers that use b.

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

type BackendGatewayFacet struct {
	Ref      objects.Ref
	Backends int
}

BackendGatewayFacet is a Gateway and the backends it has a visible path to.

type BackendNamespaceFacet

type BackendNamespaceFacet struct {
	Name     string
	Backends int
}

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

type BackendSet struct {
	Items  []Backend
	Hidden bool
}

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

type GatewayFacet struct {
	Ref   objects.Ref
	Paths int
}

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 Listener

type Listener struct {
	Name, Protocol string
	// Port is 0 when unset.
	Port int32
}

Listener is the listener a row's attachment is on.

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

func (m *Memo) Prune(md *engine.Model)

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.

func (*Memo) Topology

func (m *Memo) Topology(key TopoKey, build func() *Topology) (*Topology, bool)

Topology returns key's topology, building it on a miss. false means it is over the cap and not kept; the install's older generation is dropped too. A build for an older publication than the stored one is not kept.

type NamespaceFacet

type NamespaceFacet struct {
	Name  string
	Paths int
}

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.

func Run

func Run(t *Topology, p *Projection, q Query, visible func(explore.DepSet) bool) (Page, error)

Run pages the rows of t, projected by p, that match q and that visible admits. visible runs on every row's deps before filtering, counting and paging (design §13); nil admits every row. Bad input is explore.ErrBadQuery or explore.ErrBadCursor.

type Problem

type Problem struct {
	State   health.State
	Signals []Signal
}

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
	Shares    []Share
	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 {
	Percent float64
	State   ShareState
}

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

func Shares(rule *objects.Rule) []Share

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

func (s Share) WithAttribution(attributed, candidate bool) Share

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 (
	ShareShown     ShareState = "shown"
	ShareNotShown  ShareState = "not-shown"
	ShareNoTraffic ShareState = "no-traffic"
	ShareFailing   ShareState = "failing"
	ShareMayFail   ShareState = "may-fail"
	ShareMirror    ShareState = "mirror"
)

Share states.

type Signal

type Signal struct {
	Kind     string
	Code     string
	Ref      objects.Ref
	State    health.State
	Listener string
}

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

func Build(in Input) *Topology

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

func (t *Topology) Action(r Row) 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

func (t *Topology) Attachment(r Row) int32

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

func (t *Topology) Bytes() int

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

func (t *Topology) Chain(r Row) []objects.Ref

Chain is the row's route chain, root first.

func (*Topology) Delegation

func (t *Topology) Delegation(r Row) DelegState

Delegation is the row's delegation state.

func (*Topology) Deps

func (t *Topology) Deps(r Row) explore.DepSet

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

func (t *Topology) Gateway(r Row) objects.Ref

Gateway is the row's Gateway; a ListenerSet attachment projects to its parent.

func (*Topology) Hostnames

func (t *Topology) Hostnames(r Row) []string

Hostnames are the attachment's effective hostnames; nil for kinds without hostnames.

func (*Topology) Listener

func (t *Topology) Listener(r Row) Listener

Listener is the row's listener.

func (*Topology) ListenerSet

func (t *Topology) ListenerSet(r Row) *objects.Ref

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

func (t *Topology) RefIndex(r Row) (int, bool)

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

func (t *Topology) Route(r Row) objects.Ref

Route is the last route of the row's chain, whose rule the row is on.

func (*Topology) RowID

func (t *Topology) RowID(r Row) string

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

func (*Topology) Rule

func (t *Topology) Rule(r Row) *objects.Rule

Rule is the row's rule in the last route of its chain.

Jump to

Keyboard shortcuts

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