api

package
v0.8.0 Latest Latest
Warning

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

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

Documentation

Overview

Package api serves the read-only JSON API (design §7), the probes and the SPA.

Index

Constants

View Source
const (
	// MissAbsent is a check with no cached answer: never asked, or evicted.
	MissAbsent = "absent"
	// MissAllowExpired and MissDenyExpired are checks whose cached allow or deny expired.
	MissAllowExpired = "allow-expired"
	MissDenyExpired  = "deny-expired"
)

Why an uncached check missed the cache, as an authoriser passes it to SpendCheckOn.

View Source
const (
	AuditCheckFailed    = "check-failed"
	AuditCheckLimit     = "check-limit"
	AuditFullReadFailed = "full-read-failed"
	AuditExpired        = "expired"
	AuditIdentity       = "identity-stale"
	// AuditQueueFull is a request refused because too many were waiting for admission (D-116).
	AuditQueueFull = "queue-full"
)

Reasons the commit wrapper passes to the WithAuthzAudit hook.

View Source
const (
	RefAttributed = "attributed"
	RefCandidate  = "candidate"
	RefWaiting    = "waiting"
)

Kinds of a reference explanation (design §10).

View Source
const (
	// DataPlaneOK: the xDS rejects check ran and found no reject for the Gateway.
	DataPlaneOK = "ok"
	// DataPlaneRejects: the Gateway has a KGWUI-001.
	DataPlaneRejects = "rejects"
	// DataPlaneWithheld: no KGWUI-001, but a KGWUI-024 error: the proxies get no config updates.
	DataPlaneWithheld = "withheld"
	// DataPlaneUnknown: no reject, but the xDS rejects check is not OK or did not run.
	DataPlaneUnknown = "unknown"
)

The values of OverviewGatewayRow.DataPlane.

View Source
const (
	DelegationReported    = "reported"
	DelegationNotReported = "not-reported"
	DelegationNotFound    = "not-found"
	DelegationRestricted  = "restricted"
)

Delegation ref states (design §7.3), status-based, for name refs only.

View Source
const (
	FeatureDelegation = "delegation"
	FeatureComputed   = "computed"
	FeatureDataPlane  = "dataplane"
	FeatureProcesses  = "processes"
)

Install features, as InstallSummary.Features lists them (Phase 5 design §10).

View Source
const (
	ActionBackend        = "backend"
	ActionRedirect       = "redirect"
	ActionDirectResponse = "direct-response"
	ActionNone           = "none"
	ActionDelegate       = "delegate"
)

Path row actions (design §4.1): what a row's rule does with a request. A delegation row is the parent's rule handing requests to child routes.

View Source
const (
	NoteUnknown       = "unknown"
	NoteUnconfirmable = "unconfirmable"
	NoteNotComputed   = "not-computed"
)

Path row notes: a view C state that leaves the row's outcome open (design §4.2).

View Source
const CheckLimit = 1000

CheckLimit is the most uncached authorisation checks one request may make (design §6.4, R25). The global limiter protects the API server; this bounds one request's spend.

View Source
const ComputedBy = "ui"

ComputedBy marks a fact the UI computed (D-020).

View Source
const EndpointsSourceKubernetes = "kubernetes"

EndpointsSourceKubernetes is the endpoints source read from the cluster's EndpointSlices.

View Source
const MaxRequestBody = 1 << 20

MaxRequestBody bounds the body of a secure /api/ request other than GET or HEAD, which commit reads in full before admission; a larger one answers 413.

View Source
const NotComputedNoAttachments = "no-attachments"

NotComputedNoAttachments says the install has no computed views, so no path is derived.

Variables

View Source
var ErrBusy = errors.New("authorisation: too many requests waiting for admission")

ErrBusy is an Admit error for a request refused because too many are waiting; the commit wrapper answers 503 authz-busy (D-116).

View Source
var ErrCheckLimit = errors.New("authorisation check limit reached")

ErrCheckLimit is the error of a request that needs more uncached checks than CheckLimit.

View Source
var ErrNotAdmitted = errors.New("authorisation: request not admitted")

ErrNotAdmitted is the error of an uncached check made before its request was admitted; the commit wrapper admits the request and builds it again (D-116).

Functions

func CheckCapabilities

func CheckCapabilities(platformNames []string, sources ...func() []Capability) error

CheckCapabilities calls each source once and reports a name that is empty, repeated, or reserved by the core or the platform, and an unknown state.

func CheckExtMounts

func CheckExtMounts(m ...ExtMount) error

CheckExtMounts reports every mount whose name or pattern is invalid, whose path leaves /api/ext/{name}/, or that the mux rejects, such as two patterns it cannot tell apart.

func CheckExtName

func CheckExtName(name string) error

CheckExtName reports whether name can name an extension: a lowercase letter, then up to 62 lowercase letters, digits or dashes.

func HostGuard added in v0.8.0

func HostGuard(allowed []string, next http.Handler) http.Handler

HostGuard serves only requests whose Host is localhost, 127.0.0.1, [::1] (any port) or one of allowed (any port); others get 421. A request with an Origin that is not its own http(s) origin gets 403. It never sets CORS headers.

func NewHandler

func NewHandler(src ModelSource, ui fs.FS, authz Authorizer, opts ...HandlerOption) http.Handler

NewHandler returns the HTTP handler for the API, the probes and the SPA in ui. Every response with resources, findings or counts goes through authz; a nil authz means AllowAll (D-013), except in secure mode, where it means DenyAll. Options add extension endpoints. In secure mode every /api/ response goes through the commit wrapper (commit.go).

func NoteAllow added in v0.8.0

func NoteAllow(r *http.Request, expires time.Time)

NoteAllow records that r's request used an allow valid until expires; the commit wrapper rebuilds a response whose earliest allow expired (D-100). Denials are not noted: a stale denial only hides. It is a no-op outside a committed request.

func ProbeHandler added in v0.8.0

func ProbeHandler(ready Ready, reg *obs.Registry) http.Handler

ProbeHandler serves /healthz, /readyz and /metrics, and nothing else.

func ReportAuthzError added in v0.8.0

func ReportAuthzError(r *http.Request, err error)

ReportAuthzError records the first authorisation error of r's request. It is a no-op outside a committed request.

func SpendCheck added in v0.8.0

func SpendCheck(r *http.Request) error

SpendCheck counts one uncached check for r's request and returns ErrCheckLimit past the limit, or ErrNotAdmitted, counting nothing, before the request is admitted. It is nil outside a committed request.

func SpendCheckOn added in v0.8.0

func SpendCheckOn(r *http.Request, reason string, key any) error

SpendCheckOn is SpendCheck for a check the authoriser names by key, which missed for reason (a Miss constant); WithCheckTrace hears each counted one.

func Visible

func Visible[T any](r *http.Request, a Authorizer, items []T, ref func(T) objects.Ref) (visible []T, hidden int)

Visible returns the items whose ref the caller of r may view, in order, and the number hidden, asking a about each ref once (D-013). Under AllowAll or a full read, it makes no calls and returns items, clipped so an append cannot alias it. A nil a is AllowAll, or DenyAll in secure mode. An ErrAuthorizer's error is recorded for the request and hides the ref; the API then answers 503. In secure mode hidden is always 0 (D-085); Deps.View with VisibleTo is the secure-mode form.

func VisibleTo added in v0.8.0

func VisibleTo[T any](v Viewer, items []T, ref func(T) objects.Ref) []T

VisibleTo returns the items whose ref v may see as population members, in order. It sends no hidden count: in secure mode a hidden object leaves no trace (D-085). Its input must not depend on hidden objects: for Install.Owned.Backends use Viewer.Backends.

func WriteError

func WriteError(w http.ResponseWriter, code int, msg string)

WriteError writes the API's JSON error body with status code.

func WriteJSON

func WriteJSON(w http.ResponseWriter, v any)

WriteJSON writes v as an uncached JSON response, as core handlers do.

Types

type Admitter added in v0.8.0

type Admitter interface {
	// Admit waits under r's context for admission and returns its release, or why it could not admit.
	Admit(r *http.Request) (release func(), err error)
}

Admitter admits requests that need uncached checks a few at a time (D-116). The commit wrapper first builds a GET or HEAD without admission; a build that meets an uncached check is discarded, and the request waits in Admit and is built afresh. Other methods are admitted first. A request holds its admission until its response is final, not while it is written.

type AllowAll

type AllowAll struct{}

AllowAll lets every caller see everything the UI can read: the Phase 1 trust model, in which whoever reaches the UI may view all it shows.

func (AllowAll) Authorize

func (AllowAll) Authorize(*http.Request, objects.Ref) bool

Authorize implements Authorizer.

type AllowedListenersDTO

type AllowedListenersDTO struct {
	Set              bool           `json:"set"`
	Value            map[string]any `json:"value,omitempty"`
	CRDHint          bool           `json:"crdHint"`
	CRDField         string         `json:"crdField,omitempty"`
	CRDChannel       string         `json:"crdChannel,omitempty"`
	CRDBundleVersion string         `json:"crdBundleVersion,omitempty"`
}

AllowedListenersDTO is the parent Gateway's spec.allowedListeners as written; CRDHint is set whenever it is absent, and CRDField says whether the Gateway CRD defines it ("defined", "missing").

type AllowedRoutesDTO

type AllowedRoutesDTO struct {
	Namespaces RouteNamespacesDTO  `json:"namespaces"`
	Kinds      []objects.GroupKind `json:"kinds"`
}

AllowedRoutesDTO is a listener's allowedRoutes.

type AncestorPathDTO

type AncestorPathDTO struct {
	Steps []AncestorStepDTO `json:"steps"`
	Cycle bool              `json:"cycle"`
}

AncestorPathDTO is one up-chain path, root first.

type AncestorStepDTO

type AncestorStepDTO struct {
	Ref        *LinkedRef `json:"ref,omitempty"`
	Matches    []MatchDTO `json:"matches,omitempty"`
	Restricted bool       `json:"restricted,omitempty"`
}

AncestorStepDTO is one up-chain step: a ref, or Restricted with no identity. A hidden ancestor route has link none and Matches, the matches it delegated under in view B, and nothing else (design §7.4 rule 3, D-024).

type Attachment

type Attachment struct {
	Outcome     string               `json:"outcome,omitempty"`
	Listeners   []ListenerAttachment `json:"listeners"`
	Explanation string               `json:"explanation,omitempty"`
	Computed    Computed             `json:"computed"`
}

Attachment is view A's outcome of one parentRef. Outcome is absent when the outcome is unknown or restricted; Explanation is set on a rejection.

type AuditEvent added in v0.8.0

type AuditEvent struct {
	// Request is the request as its route saw it; Pattern is the route template, empty when no route ran.
	Request *http.Request
	// Route is the route template the path matches, or "unmatched"; never the path itself.
	Route string
	// Status is the answer's HTTP status.
	Status int
	Kind   AuditKind
	// Install is the install the path names, or empty.
	Install string
	// Subject is the object a read names: the path's object, or a finding's resource; nil for other routes.
	Subject *objects.Ref
	// Denied is set when the Authorizer refused Subject by name and the read answered 404.
	Denied bool
	// Filters are the filters a list's endpoint takes, each with its well-formed values joined by commas.
	Filters map[string]string
	// Returned are the typed object references in a successful response, with Subject; set only with disclosure.
	Returned []objects.Ref
}

AuditEvent is what the API knows about one answered /api/ request.

type AuditKind added in v0.8.0

type AuditKind uint8

AuditKind is how the audit stream treats an /api/ route (design §9.2).

const (
	// AuditOther is a route that is neither a read nor a list; only the
	// requests and disclosure levels record it.
	AuditOther AuditKind = iota
	// AuditRead is a detail or YAML read.
	AuditRead
	// AuditList is list or overview access, recorded as a summary.
	AuditList
)

type Authorizer

type Authorizer interface {
	// Authorize reports whether the caller of r may view the object ref.
	Authorize(r *http.Request, ref objects.Ref) bool
}

Authorizer decides, per request, which objects the caller may see (D-013). Findings are filtered by applying it to each finding's resource. Phase 1 ships AllowAll; per-user authorisation plugs in here later.

type AuthorizerFunc

type AuthorizerFunc func(r *http.Request, ref objects.Ref) bool

AuthorizerFunc adapts a function to Authorizer.

func (AuthorizerFunc) Authorize

func (f AuthorizerFunc) Authorize(r *http.Request, ref objects.Ref) bool

Authorize implements Authorizer.

type BackendDetail added in v0.7.0

type BackendDetail struct {
	Install      string              `json:"install"`
	Ref          LinkedRef           `json:"ref"`
	Kind         string              `json:"kind"`
	Type         string              `json:"type,omitempty"`
	Problem      ProblemDTO          `json:"problem"`
	Status       []SignalDTO         `json:"status"`
	Exposure     PathsResponse       `json:"exposure"`
	Consumers    []ConsumerDTO       `json:"consumers"`
	Sources      []EndpointsDTO      `json:"sources"`
	PortChain    []PortChainDTO      `json:"portChain"`
	Explanations []RefExplanationDTO `json:"explanations"`
	Service      *ServiceFactDTO     `json:"service,omitempty"`
	Conditions   []Condition         `json:"conditions,omitempty"`
	// DelegationNotChecked says the caller gets no paths through parent routes (D-114).
	DelegationNotChecked bool      `json:"delegationNotChecked,omitempty"`
	CollectedAt          time.Time `json:"collectedAt"`
}

BackendDetail is GET …/backends/{group}/{kind}/{ns}/{name} (design §8.2). Status is the backend's own signals, which the status line phrases; Problem also covers its paths. Exposure is the first page of its paths. Sources has one kubernetes entry per referenced Service port, with the scoped read's endpoints when it has them. Service holds a Service's cached facts and Conditions a Backend's.

type BackendFacetsDTO added in v0.7.0

type BackendFacetsDTO struct {
	Gateways   []BackendGatewayFacetDTO   `json:"gateways"`
	Namespaces []BackendNamespaceFacetDTO `json:"namespaces"`
}

BackendFacetsDTO lists the gateway and namespace filter values, sorted by name.

type BackendGatewayFacetDTO added in v0.7.0

type BackendGatewayFacetDTO struct {
	Ref      LinkedRef `json:"ref"`
	Backends int       `json:"backends"`
}

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

type BackendNamespaceFacetDTO added in v0.7.0

type BackendNamespaceFacetDTO struct {
	Name     string `json:"name"`
	Backends int    `json:"backends"`
}

BackendNamespaceFacetDTO is a namespace and the backends in it.

type BackendRefDTO

type BackendRefDTO struct {
	Ref             LinkedRef         `json:"ref"`
	Port            int32             `json:"port,omitempty"`
	Weight          int32             `json:"weight"`
	WeightDefaulted bool              `json:"weightDefaulted,omitempty"`
	Filters         []FilterDTO       `json:"filters"`
	Delegation      *DelegationRefDTO `json:"delegation,omitempty"`
	Backend         *BackendStateDTO  `json:"backend,omitempty"`
	Share           *float64          `json:"share,omitempty"`
	ShareState      string            `json:"shareState,omitempty"`
	Problem         *ProblemDTO       `json:"problem,omitempty"`
	Endpoints       *EndpointsDTO     `json:"endpoints,omitempty"`
}

BackendRefDTO is one rule backendRef. An absent weight is 1 with WeightDefaulted; an absent port is omitted. Share, ShareState, Problem and Endpoints come from the ref's visible paths, absent without one: Problem is the worst across the route's attachments.

type BackendRowDTO added in v0.7.0

type BackendRowDTO struct {
	Ref       LinkedRef      `json:"ref"`
	Kind      string         `json:"kind"`
	Endpoints []EndpointsDTO `json:"endpoints"`
	Routes    int            `json:"routes"`
	Gateways  int            `json:"gateways"`
	Consumers int            `json:"consumers"`
	Confirmed int            `json:"confirmed"`
	Problem   ProblemDTO     `json:"problem"`
}

BackendRowDTO is one backend of the Backends list (design §8.1). Kind is "Service", "Backend · <spec.type>" or the ref's kind. Endpoints has one entry per referenced Service port, or one not-applicable entry for a Backend. Routes, Gateways and Consumers count what the caller may see; Confirmed counts its paths on an attachment the route's status accepts.

type BackendStateDTO

type BackendStateDTO struct {
	State      health.State `json:"state,omitempty"`
	Accepted   *Condition   `json:"accepted,omitempty"`
	Restricted bool         `json:"restricted,omitempty"`
}

BackendStateDTO is a Backend's state and Accepted condition, or only Restricted when the caller may not view the Backend (design §7.4 rule 3).

type BackendsResponse added in v0.7.0

type BackendsResponse struct {
	Install string          `json:"install"`
	Rows    []BackendRowDTO `json:"rows"`
	Next    string          `json:"next,omitempty"`
	Prev    string          `json:"prev,omitempty"`
	Hidden  bool            `json:"hidden,omitempty"`
	// Facets are the Gateways and namespaces of the visible backends, each
	// counted with every filter but its own.
	Facets *BackendFacetsDTO `json:"facets,omitempty"`
	// DelegationNotChecked says the caller gets no paths through parent routes (D-114).
	DelegationNotChecked bool      `json:"delegationNotChecked,omitempty"`
	CollectedAt          time.Time `json:"collectedAt"`
}

BackendsResponse is GET …/backends. Hidden says a backend, path, route or consumer was left out for the caller (design §13); secure mode never sets it, since the permissions note replaces it (design §7.5).

type BatchAuthorizer added in v0.8.0

type BatchAuthorizer interface {
	// ResolveLists answers qs in order, or why it could not tell.
	ResolveLists(r *http.Request, qs []ListQuery) ([]bool, error)
}

BatchAuthorizer resolves many population list questions at once, in parallel, before a handler renders (D-100 item 6). Each answer is the list half of ErrAuthorizer's: a namespaced kind without a namespace is false.

type Candidate

type Candidate struct {
	Reason explore.CandidateReason `json:"reason"`
	By     *LinkedRef              `json:"by,omitempty"`
}

Candidate says why an object the install does not own has a detail page. By is the visible owned object that names a referenced candidate.

type Capability

type Capability struct {
	Name   string          `json:"name"`
	State  CapabilityState `json:"state"`
	Reason string          `json:"reason,omitempty"`
}

Capability is one named capability and its state; Reason says why it is not on.

type CapabilityState

type CapabilityState string

CapabilityState is whether a capability works for this caller and install.

const (
	CapOn      CapabilityState = "on"
	CapOff     CapabilityState = "off"
	CapDenied  CapabilityState = "denied"
	CapFailing CapabilityState = "failing"
)

The capability states. Only CapOn also appears in MetaResponse.Capabilities.

type Computed

type Computed struct {
	By       string   `json:"by"`
	Rules    string   `json:"rules"`
	Label    string   `json:"label,omitempty"`
	Rule     string   `json:"rule,omitempty"`
	State    string   `json:"state"`
	Coverage []string `json:"coverage,omitempty"`
	Reason   string   `json:"reason,omitempty"`
	Note     string   `json:"note,omitempty"`
}

Computed labels a computed fact with its rule set, rule and check state (design §7.3, rules §8.4). By is always ComputedBy. Reason is the unknown reason; a restricted fact carries no Rule, Reason or Note (design §7.4 rule 4). Label is the rule set's display name, such as "kgateway 2.4".

type Condition

type Condition struct {
	Type               string    `json:"type"`
	Status             string    `json:"status"`
	Reason             string    `json:"reason"`
	Message            string    `json:"message"`
	ObservedGeneration int64     `json:"observedGeneration"`
	LastTransitionTime time.Time `json:"lastTransitionTime"`
	Stale              bool      `json:"stale"`
}

Condition is a status condition on the wire. Stale marks one whose observedGeneration is below the object's generation (Phase 1 freshness).

type ConflictEvidence

type ConflictEvidence struct {
	Others []ConflictListener `json:"others,omitempty"`
	// contains filtered or unexported fields
}

ConflictEvidence is KGWUI-017's evidence on the wire: each other listener's owner carries its link.

func (*ConflictEvidence) EvidenceKind

func (*ConflictEvidence) EvidenceKind() string

EvidenceKind implements health.Evidence.

func (*ConflictEvidence) MarshalJSON

func (e *ConflictEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type ConflictListener

type ConflictListener struct {
	Owner    LinkedRef `json:"owner"`
	Name     string    `json:"name"`
	Protocol string    `json:"protocol,omitempty"`
	Hostname string    `json:"hostname,omitempty"`
}

ConflictListener is a health.ConflictingListener whose owner carries its link.

type ConsumerDTO added in v0.7.0

type ConsumerDTO struct {
	Consumer LinkedRef `json:"consumer"`
	Role     string    `json:"role"`
	Field    string    `json:"field"`
	Port     int       `json:"port,omitempty"`
}

ConsumerDTO is a non-route object that uses the backend (design §8.3): its role, such as ext-auth, the JSON path of its reference and the port written there.

type DataPlaneDTO

type DataPlaneDTO struct {
	Rejecting          bool             `json:"rejecting"`
	Rejects            []DataPlaneTypes `json:"rejects"`
	StatusSaysHealthy  bool             `json:"statusSaysHealthy"`
	Snapshot           *SnapshotDTO     `json:"snapshot,omitempty"`
	NextSteps          []NextStep       `json:"nextSteps"`
	RecentlyChanged    []LinkedRef      `json:"recentlyChanged"`
	EvidenceRestricted bool             `json:"evidenceRestricted,omitempty"`
	// Unavailable is set while the xDS rejects check is not OK: Rejecting false then means unknown.
	Unavailable bool          `json:"unavailable,omitempty"`
	ProxyStats  ProxyStatsDTO `json:"proxyStats"`
	// Withheld is set when the controller log shows the Gateway's proxies may get no config updates (R105).
	Withheld *WithheldDTO `json:"withheld,omitempty"`
	// ConfigWithheld is set while the Gateway has a KGWUI-024 error: its proxies get no config updates.
	ConfigWithheld bool `json:"configWithheld,omitempty"`
	// ControllerLogs says whether the install's controller log was read; without it, no withheld means unobserved (D-006).
	ControllerLogs string `json:"controllerLogs"`
}

DataPlaneDTO is a Gateway's data plane (design §13.3). Rejecting says a KGWUI-001 is active; its Rejects and RecentlyChanged need every evidence dependency (§14 rule 12), else EvidenceRestricted. A viewer without the full read in secure mode gets no data plane: every fact in it is derived.

type DataPlaneSummary

type DataPlaneSummary struct {
	Gateways  int `json:"gateways"`
	Rejecting int `json:"rejecting"`
	// Withheld counts Gateways with a KGWUI-024 error: their proxies get no config updates.
	Withheld    int  `json:"withheld,omitempty"`
	Unavailable bool `json:"unavailable,omitempty"`
}

DataPlaneSummary counts Gateways with a KGWUI-001 over every finding, beside the visible Gateways and those a rejecting row names; Unavailable is set while the xDS rejects check is not OK.

type DataPlaneTypes

type DataPlaneTypes struct {
	TypeURL   string    `json:"typeUrl"`
	Streams   int       `json:"streams"`
	FirstSeen time.Time `json:"firstSeen"`
}

DataPlaneTypes is one rejected xDS type: the rejecting streams and when the UI first saw them.

type DelegationContext

type DelegationContext struct {
	Restricted  bool          `json:"restricted,omitempty"`
	ParentMatch *MatchDTO     `json:"parentMatch,omitempty"`
	Path        []PathStepDTO `json:"path,omitempty"`
	Outcome     string        `json:"outcome,omitempty"`
	Reason      string        `json:"reason,omitempty"`
}

DelegationContext is one retained context of a row, or only Restricted when a dependency other than the routes on its path is hidden (design §7.4 rules 4, 4b).

type DelegationObserved

type DelegationObserved struct {
	Entry           *ParentStatus `json:"entry,omitempty"`
	ParentCondition *Condition    `json:"parentCondition,omitempty"`
}

DelegationObserved is what the controller wrote for a row: the child's status entry under the row's report key, and the parent's ResolvedRefs condition under one of its reporter keys.

type DelegationRefDTO

type DelegationRefDTO struct {
	Mode      objects.DelegationMode `json:"mode"`
	Namespace string                 `json:"namespace"`
	Name      string                 `json:"name,omitempty"`
	Label     string                 `json:"label,omitempty"`
	State     string                 `json:"state,omitempty"`
	Selected  *int                   `json:"selected,omitempty"`
	Attached  *int                   `json:"attached,omitempty"`
	Computed  *Computed              `json:"computed,omitempty"`
}

DelegationRefDTO is a delegation backendRef as classified. Selected and Attached count the visible children of view B's rows (2.4, design §7.4 rule 5); each is nil when the count is not known to the caller. Computed merges the rows' checks worst first (D-023 decision 2, PF14).

type DelegationRow

type DelegationRow struct {
	Rule              int                 `json:"rule"`
	Ref               int                 `json:"ref"`
	RefAsWritten      DelegationRefDTO    `json:"refAsWritten"`
	Child             *LinkedRef          `json:"child,omitempty"`
	Allows            string              `json:"allows,omitempty"`
	Outcome           string              `json:"outcome,omitempty"`
	Reason            string              `json:"reason,omitempty"`
	Contexts          []DelegationContext `json:"contexts"`
	ContextsTruncated bool                `json:"contextsTruncated,omitempty"`
	Computed          Computed            `json:"computed"`
	Observed          DelegationObserved  `json:"observed"`
}

DelegationRow is one view B row of GET …/delegation (design §7.3). Child is absent on a row whose ref selected no route. A restricted row has no Outcome and no Reason (design §7.4 rule 4).

type DenyAll added in v0.8.0

type DenyAll struct{}

DenyAll denies every ref; secure mode uses it until a real authoriser is wired.

func (DenyAll) Authorize added in v0.8.0

func (DenyAll) Authorize(*http.Request, objects.Ref) bool

Authorize implements Authorizer.

type DetailReason added in v0.7.1

type DetailReason struct {
	health.RowReason
	Finding string     `json:"finding,omitempty"`
	Backend *LinkedRef `json:"backend,omitempty"`
}

DetailReason is a detail page's reason: the list row's (D-063) plus, for kind finding, the deciding finding's id, so the page can open it. Backend is as on RouteReason.

type Diagnostics

type Diagnostics struct {
	Install string  `json:"install"`
	Verdict Verdict `json:"verdict"`
	// Groups are the first maxGroups of the GroupTotal ranked groups with a problem.
	Groups      []GroupRow           `json:"groups"`
	GroupTotal  int                  `json:"groupTotal"`
	Processes   ProcessSummaries     `json:"processes"`
	DataPlane   DataPlaneSummary     `json:"dataPlane"`
	Checks      []health.CheckResult `json:"checks"`
	CollectedAt time.Time            `json:"collectedAt"`
}

Diagnostics is GET …/diagnostics (design §13.3): the verdict, the top groups of "Needs attention" and the process and data-plane summaries.

type EffectiveContext

type EffectiveContext struct {
	Restricted  bool               `json:"restricted,omitempty"`
	ParentMatch *MatchDTO          `json:"parentMatch,omitempty"`
	Rules       []EffectiveRuleDTO `json:"rules,omitempty"`
}

EffectiveContext is the route's rules under one parent match, or only Restricted (design §7.4 rule 4).

type EffectiveDTO

type EffectiveDTO struct {
	Parent            LinkedRef          `json:"parent"`
	Mode              string             `json:"mode"`
	ContextsTruncated bool               `json:"contextsTruncated,omitempty"`
	Contexts          []EffectiveContext `json:"contexts"`
	Computed          Computed           `json:"computed"`
}

EffectiveDTO is view C for one parent edge of a route (computed-rules §5.7, §6). Contexts is sent as [] when none was kept; ContextsTruncated says contexts were cut.

type EffectiveRuleDTO

type EffectiveRuleDTO struct {
	Index   int        `json:"index"`
	Kept    bool       `json:"kept"`
	Matches []MatchDTO `json:"matches"`
	Reason  string     `json:"reason,omitempty"`
}

EffectiveRuleDTO is one rule under a parent match: kept with its effective matches, or dropped with Reason.

type EndpointDTO added in v0.7.0

type EndpointDTO struct {
	Address     string `json:"address"`
	Port        int32  `json:"port,omitempty"`
	Ready       bool   `json:"ready"`
	Serving     bool   `json:"serving"`
	Terminating bool   `json:"terminating"`
	Pod         string `json:"pod,omitempty"`
}

EndpointDTO is one endpoint of a backend detail read (design §9.3).

type EndpointsDTO added in v0.7.0

type EndpointsDTO struct {
	Source  string      `json:"source"`
	Port    *PortDTO    `json:"port,omitempty"`
	Runtime *RuntimeDTO `json:"runtime,omitempty"`
	// ReadAt is meaningless when Complete is not-applicable or not-permitted: nothing was read.
	ReadAt time.Time `json:"readAt"`
	// Complete is complete, partial, failed, unavailable, stale, not-applicable
	// or not-permitted (the caller may not list the Service's EndpointSlices);
	// a backend detail's scoped read may also be timed-out or busy.
	Complete string `json:"complete"`
	// Ready and Total are absent unless the read establishes a count.
	Ready *int          `json:"ready,omitempty"`
	Total *int          `json:"total,omitempty"`
	Items []EndpointDTO `json:"items,omitempty"`
	// CachedReady is the cache's ready count, set only when a complete read
	// finds none ready while the cache counts some: the two sources disagree.
	CachedReady *int `json:"cachedReady,omitempty"`
}

EndpointsDTO is one backend port's endpoints from one source (design §9.5).

type ErrAuthorizer added in v0.8.0

type ErrAuthorizer interface {
	// AuthorizeErr reports whether the caller of r may view ref, or why it could not tell.
	AuthorizeErr(r *http.Request, ref objects.Ref) (bool, error)
}

ErrAuthorizer can say that it could not decide (design §6.3). The API then answers 503 "authz-unavailable" instead of an empty or partial view.

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error"`
}

ErrorResponse is the body of every non-2xx API response.

type ExtMount

type ExtMount struct {
	Name, Pattern string
	Handler       http.Handler
}

ExtMount is one extension endpoint (design §4.1 gap 1). Pattern is "[METHOD ]/path" relative to /api/ext/{Name}, so the endpoint never collides with API v1, another extension or the SPA.

type FilterDTO

type FilterDTO struct {
	Type         string         `json:"type"`
	ExtensionRef *LinkedRef     `json:"extensionRef,omitempty"`
	Mirror       *MirrorDTO     `json:"mirror,omitempty"`
	Config       map[string]any `json:"config,omitempty"`
}

FilterDTO is one filter in written order; Config is the filter as written.

type FindingDTO

type FindingDTO struct {
	health.Finding
	Resource           *LinkedRef `json:"resource,omitempty"`
	EvidenceRestricted bool       `json:"evidenceRestricted,omitempty"`
}

FindingDTO is a finding on the wire: its resource carries a link, and EvidenceRestricted marks a detail replaced because it quotes a hidden object.

func (*FindingDTO) UnmarshalJSON

func (d *FindingDTO) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the typed evidence by its kind, which encoding/json cannot do for the Evidence interface; Go clients decode /health with it.

type FindingDetail

type FindingDetail struct {
	Install      string          `json:"install"`
	Finding      FindingRow      `json:"finding"`
	Evidence     health.Evidence `json:"evidence,omitempty"`
	SuggestedFix *SuggestedFix   `json:"suggestedFix,omitempty"`
	NextSteps    []NextStep      `json:"nextSteps,omitempty"`
	Affected     Page[LinkedRef] `json:"affected"`
	CollectedAt  time.Time       `json:"collectedAt"`
}

FindingDetail is GET …/findings/{findingId}; Affected pages through the visible objects of its group (§14 rule 13). A restricted or evidence-restricted finding has no Evidence (rule 12).

func (*FindingDetail) UnmarshalJSON

func (d *FindingDetail) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the typed evidence by its kind; Go clients decode a detail with it.

type FindingRow

type FindingRow struct {
	ID                 string          `json:"id"`
	Code               string          `json:"code"`
	Slug               string          `json:"slug"`
	Severity           health.Severity `json:"severity"`
	Resource           *LinkedRef      `json:"resource,omitempty"`
	Message            string          `json:"message,omitempty"`
	Detail             string          `json:"detail,omitempty"`
	Since              *time.Time      `json:"since,omitempty"`
	Group              string          `json:"group,omitempty"`
	Restricted         bool            `json:"restricted,omitempty"`
	EvidenceRestricted bool            `json:"evidenceRestricted,omitempty"`
}

FindingRow is one finding of GET …/findings (design §13.3); restricted rows keep identity only (§14 rule 11), EvidenceRestricted hides the detail (rule 12). It has no docs link: the SPA builds the docs/findings.md anchor from Code.

type FractionDTO

type FractionDTO struct {
	Numerator   int32 `json:"numerator"`
	Denominator int32 `json:"denominator"`
}

FractionDTO is a mirror fraction; the denominator defaults to 100.

type FullReader added in v0.8.0

type FullReader interface {
	// FullRead reports whether the caller of r reads everything, or why it could not tell.
	FullRead(r *http.Request) (bool, error)
}

FullReader answers the full-read fast path (design §6.4): whether the caller may list every served kind cluster-wide and so sees the allow-all view.

type GRPCMatchDTO added in v0.7.0

type GRPCMatchDTO struct {
	Method  *GRPCMethodDTO `json:"method,omitempty"`
	Headers []KeyMatchDTO  `json:"headers,omitempty"`
}

GRPCMatchDTO is one GRPCRouteMatch as written.

type GRPCMethodDTO added in v0.7.0

type GRPCMethodDTO struct {
	Type    string `json:"type,omitempty"`
	Service string `json:"service,omitempty"`
	Method  string `json:"method,omitempty"`
}

GRPCMethodDTO is a GRPCRoute method match as written.

type GatewayDetail

type GatewayDetail struct {
	Install              string        `json:"install"`
	Ref                  LinkedRef     `json:"ref"`
	Generation           int64         `json:"generation"`
	Class                string        `json:"class"`
	Health               health.State  `json:"health"`
	Reason               *DetailReason `json:"reason,omitempty"`
	Candidate            *Candidate    `json:"candidate,omitempty"`
	RuleSet              string        `json:"ruleSet,omitempty"`
	RuleSetLabel         string        `json:"ruleSetLabel,omitempty"`
	Conditions           []Condition   `json:"conditions"`
	Addresses            []string      `json:"addresses"`
	Listeners            []ListenerDTO `json:"listeners"`
	AttachedListenerSets *int32        `json:"attachedListenerSets,omitempty"`
	ListenerSets         int           `json:"listenerSets"`
	RouteCounts          RouteCounts   `json:"routeCounts"`
	// DataPlane and Proxies are sent for a Gateway the install owns (design §13.1).
	DataPlane   *DataPlaneDTO  `json:"dataPlane,omitempty"`
	Proxies     *ProcessSetDTO `json:"proxies,omitempty"`
	CollectedAt time.Time      `json:"collectedAt"`
}

GatewayDetail is GET …/gateways/{ns}/{name}. Its ListenerSets are paged through the ListenerSets list, never embedded; ListenerSets is that list's total for the caller (design §7.4 rule 5).

type GatewayFacetDTO added in v0.7.0

type GatewayFacetDTO struct {
	Ref   LinkedRef `json:"ref"`
	Paths int       `json:"paths"`
}

GatewayFacetDTO is a Gateway and the paths through it.

type GatewayListRow

type GatewayListRow struct {
	Ref    LinkedRef    `json:"ref"`
	Class  string       `json:"class"`
	Health health.State `json:"health"`
	// Reason is as on RouteRow.
	Reason         *health.RowReason `json:"reason,omitempty"`
	Listeners      int               `json:"listeners"`
	AttachedRoutes int32             `json:"attachedRoutes"`
	NotAccepted    int               `json:"notAccepted"`
	// Routes is view A's distinct routes on the Gateway's own listeners,
	// hidden ones too; nil when a count is unknown (rule 5).
	Routes       *int `json:"routes,omitempty"`
	ListenerSets int  `json:"listenerSets"`
	// Disagreements counts the Gateway's checks in state disagrees. Like
	// health it is not filtered per caller (rule 9).
	Disagreements int      `json:"disagreements,omitempty"`
	Addresses     []string `json:"addresses"`
}

GatewayListRow is one row of the Gateways list (the design's GatewayRow2). AttachedRoutes is the status sum as written; NotAccepted and ListenerSets count visible rows only.

type GatewayProcesses

type GatewayProcesses struct {
	Gateway     LinkedRef     `json:"gateway"`
	Health      health.State  `json:"health"`
	NotAssessed bool          `json:"notAssessed,omitempty"`
	Set         ProcessSetDTO `json:"set"`
	Rejects     *int          `json:"rejects,omitempty"`
	Skew        bool          `json:"skew,omitempty"`
}

GatewayProcesses is one Gateway's proxies: Health is its worst process or data-plane finding, Rejects its rejecting streams, Skew a proxy on another controller version, patches included (never a finding). NotAssessed is as on ProcessSummary: Health is then unknown.

type GrantShape

type GrantShape struct {
	FromNamespace string `json:"fromNamespace"`
	ToNamespace   string `json:"toNamespace"`
	ToGroup       string `json:"toGroup"`
	ToKind        string `json:"toKind"`
}

GrantShape is the (from namespace, to namespace, to group and kind) one ReferenceGrant allows; ToGroup is "" for the core group.

type GroupRow

type GroupRow struct {
	ID            string          `json:"id"`
	Title         string          `json:"title"`
	Code          string          `json:"code"`
	Severity      health.Severity `json:"severity"`
	Class         diagnose.Class  `json:"class"`
	Cause         *LinkedRef      `json:"cause,omitempty"`
	Members       int             `json:"members"`
	Affected      []LinkedRef     `json:"affected"`
	AffectedTotal int             `json:"affectedTotal"`
	Since         *time.Time      `json:"since,omitempty"`
	NextSteps     []NextStep      `json:"nextSteps,omitempty"`
	Restricted    bool            `json:"restricted,omitempty"`
	// Grant is the shape of a "Not permitted" group, which has no cause object (design §5.2).
	Grant *GrantShape `json:"grant,omitempty"`
}

GroupRow is one ranked group with its rank keys (design §13.2); Code and Title are its top member's, and a restricted row has no title, affected list, since or steps (§14 rule 13).

type HandlerOption

type HandlerOption func(*handlerConfig)

HandlerOption configures NewHandler.

func WithAuthzAudit added in v0.8.0

func WithAuthzAudit(audit func(r *http.Request, reason string)) HandlerOption

WithAuthzAudit calls audit once for each secure /api/ request answered 503 authz-unavailable, with AuditCheckFailed, AuditCheckLimit, AuditFullReadFailed, AuditExpired or AuditIdentity, or 503 authz-busy, with AuditQueueFull.

func WithBackendConsumers added in v0.7.0

func WithBackendConsumers(f func(install.Install, *install.Owned) []objects.Consumer) HandlerOption

WithBackendConsumers gives each install's non-route backend consumers, such as GatewayExtensions (design §8.3). Without it there are none.

func WithCapabilitySources

func WithCapabilitySources(f ...func() []Capability) HandlerOption

WithCapabilitySources adds sources of capability states for /api/v1/meta. Each source runs on every /api/v1/meta request, so it must be fast, safe for concurrent use and report a stable set of names.

func WithCheckCapHit added in v0.8.0

func WithCheckCapHit(hit func(r *http.Request)) HandlerOption

WithCheckCapHit calls hit once for each secure /api/ request that passes CheckLimit, whatever it is answered, before the answer is chosen.

func WithCheckTrace added in v0.8.0

func WithCheckTrace(trace func(r *http.Request, build int, reason string, key any)) HandlerOption

WithCheckTrace calls trace for each uncached check a secure /api/ request counts, with the build it was counted in (1-based, discarded builds included), why the check was a miss (a Miss reason, or "" when the authoriser gives none) and the authoriser's key for the check. It runs while the authoriser holds its locks, so it must be quick and must not call back.

func WithCommands

func WithCommands(c diagnose.Commands) HandlerOption

WithCommands sets the next-step commands; the default is diagnose.Kubectl.

func WithCommitCheck added in v0.8.0

func WithCommitCheck(check func(w http.ResponseWriter, r *http.Request) (*http.Request, error)) HandlerOption

WithCommitCheck runs check on every secure /api/ request r after its handler and before its response is written. Answering r commits; nil means check wrote its own response, which replaces the handler's; another request rebuilds the response with it; an error answers 503 authz-unavailable.

func WithCommitClock added in v0.8.0

func WithCommitClock(now func() time.Time) HandlerOption

WithCommitClock sets the clock commit compares allow expiries with; without it, time.Now.

func WithCoreCapabilities

func WithCoreCapabilities(f func() []Capability) HandlerOption

WithCoreCapabilities sets the source of the core names' states; it runs on every /api/v1/meta request, and any other name it reports is dropped.

func WithExtMounts

func WithExtMounts(m ...ExtMount) HandlerOption

WithExtMounts serves m under /api/ext/{name}/. Callers check them with CheckExtMounts first; NewHandler logs and skips a mount that fails it.

func WithInstallCommands added in v0.6.0

func WithInstallCommands(f func(install.Install) diagnose.Commands) HandlerOption

WithInstallCommands sets each install's next-step commands, such as its pack's; a nil result keeps WithCommands'.

func WithInstallFeatures added in v0.6.0

func WithInstallFeatures(f func(install.Install) []string) HandlerOption

WithInstallFeatures sets each install's pack features. The API drops FeatureComputed without a rule set and FeatureDelegation without a Delegator.

func WithInstallKinds added in v0.6.0

func WithInstallKinds(f func(install.Install, objects.GroupKind) bool) HandlerOption

WithInstallKinds reports whether a served kind applies to an install, such as a pack's kind to that pack's installs; overview counts keep only those.

func WithPacks added in v0.6.0

func WithPacks(names ...string) HandlerOption

WithPacks names the packs this server runs, for MetaResponse.Packs.

func WithRequestAudit added in v0.8.0

func WithRequestAudit(hear func(AuditEvent), disclosure bool) HandlerOption

WithRequestAudit calls hear once for each /api/ request, after its answer is written. With disclosure, each successful answer reports the object references its response value holds; the body is never parsed.

func WithScopedReader added in v0.7.0

func WithScopedReader(r endpoints.ScopedReader) HandlerOption

WithScopedReader reads one Service's endpoints for backend detail (design §9.3). Without it, or with nil, those endpoints are unavailable.

func WithSecureMode added in v0.8.0

func WithSecureMode() HandlerOption

WithSecureMode marks the handler secure: every /api/ response goes through the per-viewer projection and the commit wrapper.

func WithSessionGate added in v0.8.0

func WithSessionGate(gate func(http.Handler) http.Handler) HandlerOption

WithSessionGate wraps the handler in gate, inside the request audit and outside the commit wrapper, so a request gate refuses is still heard.

type HealthResponse

type HealthResponse struct {
	health.Report
	Findings []FindingDTO `json:"findings"`
}

HealthResponse is GET …/health. It carries the install ID. Findings shadows the report's, so the change from health.Report is additive.

type HealthSummary

type HealthSummary struct {
	State  health.State            `json:"state"`
	Counts map[health.Severity]int `json:"counts"`
}

HealthSummary is the state and per-severity counts.

type InstallSummary

type InstallSummary struct {
	ID              string                 `json:"id"`
	DisplayName     string                 `json:"displayName"`
	Namespace       string                 `json:"namespace,omitempty"`
	Name            string                 `json:"name,omitempty"`
	Version         string                 `json:"version"`
	Edition         string                 `json:"edition"`
	ControllerNames []string               `json:"controllerNames"`
	Readiness       overview.Readiness     `json:"readiness"`
	Scope           *overview.ScopeSummary `json:"scope,omitempty"`
	Health          HealthSummary          `json:"health"`
	// GroupRows is the number of groups diagnostics lists: the install page
	// reserves that many Needs attention rows while diagnostics load.
	GroupRows int `json:"groupRows"`
	// ComputedAt is when the model behind Health was computed; in secure mode without
	// the full read it is the confirmation time (D-109). Clients fall back
	// to it when ConfirmedAt is absent.
	ComputedAt time.Time `json:"computedAt"`
	// ConfirmedAt is when the model was last confirmed to match the cluster
	// (D-019); clients apply the stale rule to it.
	ConfirmedAt *time.Time `json:"confirmedAt,omitempty"`
	// Features are the install's UI features (Feature*); always sent, so an
	// absent list means an older server (Phase 5 design §10).
	Features []string `json:"features"`
	// DetailsHidden is set when the caller may not read the source of every
	// metadata field, which is then empty (design §7.4).
	DetailsHidden bool `json:"detailsHidden,omitempty"`
}

InstallSummary is one entry of GET /api/v1/installs. Namespace, Name and Scope are absent where the platform has no such notion (D-016).

type KeyMatchDTO

type KeyMatchDTO struct {
	Type  string `json:"type"`
	Name  string `json:"name"`
	Value string `json:"value"`
}

KeyMatchDTO is a header or query parameter match after defaults.

type Link string

Link is how the SPA may open a reference (design §7.1). Clients render it as given and never derive one from a kind.

const (
	// LinkDetail: admitted, and its kind has a detail view.
	LinkDetail Link = "detail"
	// LinkYAML: admitted without a detail view, or a no-parent row.
	LinkYAML Link = "yaml"
	// LinkBackend: not detail, and the backend detail serves it to the caller, absent or not (D-079).
	LinkBackend Link = "backend"
	// LinkNone: denied, absent, never served or not admitted (D-013).
	LinkNone Link = "none"
)

Links.

type LinkedRef

type LinkedRef struct {
	objects.Ref
	Link Link `json:"link"`
}

LinkedRef is a reference with its link.

type ListAuthorizer added in v0.8.0

type ListAuthorizer interface {
	// CanList reports whether the caller of r may list gk in namespace.
	CanList(r *http.Request, gk objects.GroupKind, namespace string) (bool, error)
}

ListAuthorizer answers population checks (design §7.6, §8.1): whether the caller may list a kind in a namespace, "" meaning cluster-wide.

type ListQuery added in v0.8.0

type ListQuery struct {
	Kind      objects.GroupKind
	Namespace string
}

ListQuery is one population list question: may the caller list Kind in Namespace. A cluster-scoped kind is listed cluster-wide whatever Namespace says.

type ListScanner added in v0.8.0

type ListScanner interface {
	// NamedGetScan reports whether a member the list denies is still asked by named get.
	NamedGetScan() bool
}

ListScanner says whether a list denial is final for a population member (D-100). Without it, a denied member is asked again through ErrAuthorizer.

type ListenerAttachment

type ListenerAttachment struct {
	Resource           LinkedRef `json:"resource"`
	Listener           string    `json:"listener"`
	EffectiveHostnames []string  `json:"effectiveHostnames,omitempty"`
	Computed           Computed  `json:"computed"`
}

ListenerAttachment is one listener a parentRef attaches to (view A). EffectiveHostnames is sent only in state checked or disagrees.

type ListenerDTO

type ListenerDTO struct {
	Name          string             `json:"name"`
	Port          int32              `json:"port,omitempty"`
	Protocol      string             `json:"protocol"`
	Hostname      string             `json:"hostname,omitempty"`
	TLS           *ListenerTLSDTO    `json:"tls,omitempty"`
	AllowedRoutes AllowedRoutesDTO   `json:"allowedRoutes"`
	Status        *ListenerStatusDTO `json:"status,omitempty"`
	// ComputedRoutes is view A's count, hidden members too; nil when unknown (rule 5).
	ComputedRoutes *int      `json:"computedRoutes,omitempty"`
	Computed       *Computed `json:"computed,omitempty"`
	// IsolationNote: Envoy may serve fewer hostnames on this listener (rules §4.5).
	IsolationNote bool `json:"isolationNote,omitempty"`
}

ListenerDTO is one spec listener with its status block, when there is one.

type ListenerSetDetail

type ListenerSetDetail struct {
	Install                string               `json:"install"`
	Ref                    LinkedRef            `json:"ref"`
	Generation             int64                `json:"generation"`
	Health                 health.State         `json:"health"`
	Reason                 *DetailReason        `json:"reason,omitempty"`
	Candidate              *Candidate           `json:"candidate,omitempty"`
	RuleSet                string               `json:"ruleSet,omitempty"`
	RuleSetLabel           string               `json:"ruleSetLabel,omitempty"`
	Parent                 LinkedRef            `json:"parent"`
	ParentFound            bool                 `json:"parentFound"`
	Conditions             []Condition          `json:"conditions"`
	Listeners              []ListenerDTO        `json:"listeners"`
	ExperimentalHint       string               `json:"experimentalHint,omitempty"`
	RouteCounts            RouteCounts          `json:"routeCounts"`
	ParentAllowedListeners *AllowedListenersDTO `json:"parentAllowedListeners,omitempty"`
	CollectedAt            time.Time            `json:"collectedAt"`
}

ListenerSetDetail is GET …/listenersets/{group}/{kind}/{ns}/{name}. ParentFound is false when the parent does not open for the caller (absent, hidden or unadmitted). ParentAllowedListeners is sent only while the ListenerSet's current Accepted condition is False with reason NotAllowed and its parent is found.

type ListenerSetRow

type ListenerSetRow struct {
	Ref    LinkedRef    `json:"ref"`
	Parent LinkedRef    `json:"parent"`
	Health health.State `json:"health"`
	// Reason is as on RouteRow.
	Reason         *health.RowReason `json:"reason,omitempty"`
	Listeners      int               `json:"listeners"`
	AcceptedReason string            `json:"acceptedReason,omitempty"`
	// Routes and Disagreements are as on GatewayListRow.
	Routes        *int `json:"routes,omitempty"`
	Disagreements int  `json:"disagreements,omitempty"`
}

ListenerSetRow is one row of the ListenerSets list.

type ListenerStatusDTO

type ListenerStatusDTO struct {
	AttachedRoutes int32               `json:"attachedRoutes"`
	SupportedKinds []objects.GroupKind `json:"supportedKinds"`
	Conditions     []Condition         `json:"conditions"`
}

ListenerStatusDTO is a listener's status block as written.

type ListenerTLSDTO

type ListenerTLSDTO struct {
	Mode            string      `json:"mode"`
	CertificateRefs []LinkedRef `json:"certificateRefs"`
}

ListenerTLSDTO is a listener's TLS block. Certificate refs always link none: Secrets are never read (design §11).

type MatchDTO

type MatchDTO struct {
	Path        *PathMatchDTO  `json:"path,omitempty"`
	Headers     []KeyMatchDTO  `json:"headers,omitempty"`
	QueryParams []KeyMatchDTO  `json:"queryParams,omitempty"`
	Method      string         `json:"method,omitempty"`
	GRPCMethod  *GRPCMethodDTO `json:"grpcMethod,omitempty"`
}

MatchDTO is one HTTPRouteMatch after defaults, or one GRPCRouteMatch as written: its headers and GRPCMethod. Method is the HTTP method only.

type MetaResponse

type MetaResponse struct {
	Version string `json:"version"`
	Pinned  string `json:"pinned,omitempty"`
	Synced  bool   `json:"synced"`
	// Platform names the platform for display, for example "Kubernetes".
	Platform string `json:"platform"`
	// Capabilities are what the platform offers (platform.Scope,
	// platform.Workloads). Clients branch on these, never on Platform.
	Capabilities []string `json:"capabilities"`
	// CapabilityStates lists the core and extension capabilities with their state, by name.
	// Those that are on are also in Capabilities.
	CapabilityStates []Capability `json:"capabilityStates,omitempty"`
	// Kinds are the kinds the resource endpoint can serve: the served kinds,
	// plus apps/Deployment under the workloads capability. The frontend links only these.
	Kinds []kinds.Served `json:"kinds"`
	// Views are the group/kinds with a detail view; informational only.
	Views []objects.GroupKind `json:"views,omitempty"`
	// Packs names the implementation packs this server runs, such as
	// "kgateway"; always sent, so an absent list means an older server.
	Packs []string `json:"packs"`
	// Filters lists, per list, the filters added after v1, so a client sends
	// one only when this backend applies it (design §7.2).
	Filters map[string][]string `json:"filters,omitempty"`
	// AuthMode is "secure" when the server was built with WithSecureMode, else "local" (no sign-in).
	AuthMode string `json:"authMode"`
	// LimitedView is set in secure mode when the caller may not list every
	// served kind cluster-wide; only the caller's own rights decide it (design §7.5).
	LimitedView bool `json:"limitedView,omitempty"`
}

MetaResponse is GET /api/v1/meta.

type MirrorDTO

type MirrorDTO struct {
	BackendRef LinkedRef    `json:"backendRef"`
	Port       int32        `json:"port,omitempty"`
	Percent    *int32       `json:"percent,omitempty"`
	Fraction   *FractionDTO `json:"fraction,omitempty"`
}

MirrorDTO is a RequestMirror filter's target. Port is omitted when absent.

type ModelSource

type ModelSource interface {
	Current() *engine.Published
	Platform() platform.Info
}

ModelSource provides the current publication and the platform it is computed for.

type NamedAuthorizer added in v0.8.0

type NamedAuthorizer interface {
	// AuthorizeNamedErr reports whether the caller of r may view the named ref, or why it could not tell.
	AuthorizeNamedErr(r *http.Request, ref objects.Ref) (bool, error)
}

NamedAuthorizer answers named-ref checks (D-100): a detail page's subject, or an object named in a readable object. Without it a named ref is checked as a population member.

type NamespaceFacetDTO added in v0.7.0

type NamespaceFacetDTO struct {
	Name  string `json:"name"`
	Paths int    `json:"paths"`
}

NamespaceFacetDTO is a route namespace and the paths with a route in it.

type NamespacesResponse added in v0.8.0

type NamespacesResponse struct {
	Install     string    `json:"install"`
	Namespaces  []string  `json:"namespaces"`
	CollectedAt time.Time `json:"collectedAt"`
}

NamespacesResponse is GET …/namespaces: the sorted namespaces of the install's route, Gateway and ListenerSet rows the caller can see.

type Narrowed added in v0.8.0

type Narrowed struct {
	Base, Policy Authorizer
}

Narrowed allows only what both Base and Policy allow: secure mode puts a build's own authoriser behind SAR this way. The API uses Base's list, batch, full-read and admission answers and ANDs Policy into each decision.

func (Narrowed) Authorize added in v0.8.0

func (n Narrowed) Authorize(r *http.Request, ref objects.Ref) bool

Authorize implements Authorizer.

type NextStep

type NextStep struct {
	Title   string   `json:"title"`
	Command string   `json:"command"`
	Needs   []string `json:"needs,omitempty"`
	Note    string   `json:"note,omitempty"`
}

NextStep is one command a user can run to learn more. Needs names the permissions it requires, for example "pods/log".

type OverviewGatewayRow

type OverviewGatewayRow struct {
	overview.GatewayRow
	Link      Link   `json:"link,omitempty"`
	DataPlane string `json:"dataPlane,omitempty"`
}

OverviewGatewayRow is an overview Gateway row with its link and its Data plane column (design §6).

type OverviewResponse

type OverviewResponse struct {
	overview.Overview
	Gateways    []OverviewGatewayRow `json:"gateways"`
	CollectedAt time.Time            `json:"collectedAt"`
}

OverviewResponse is GET …/overview. Gateways shadows the overview's rows, so adding their link is additive on the wire.

type Page

type Page[T any] struct {
	Install         string `json:"install"`
	Items           []T    `json:"items"`
	Total           int    `json:"total"`
	Next            string `json:"next,omitempty"`
	Prev            string `json:"prev,omitempty"`
	DeniedInInstall int    `json:"deniedInInstall,omitempty"`
	// DelegationNotChecked says the caller gets no delegation analysis here (D-114).
	DelegationNotChecked bool      `json:"delegationNotChecked,omitempty"`
	CollectedAt          time.Time `json:"collectedAt"`
}

Page is one page of a list (design §7.3). Total counts the visible rows that match; DeniedInInstall is the unfiltered number of the install's rows of the listed kinds the caller may not view (design §7.4 rule 2).

type ParentStatus

type ParentStatus struct {
	ParentRef      objects.ParentRef `json:"parentRef"`
	Target         LinkedRef         `json:"target"`
	ControllerName string            `json:"controllerName"`
	Ours           bool              `json:"ours"`
	Conditions     []Condition       `json:"conditions"`
}

ParentStatus is one status.parents entry of a route. Ours marks an entry written by one of the install's controllers.

type ParentSummary

type ParentSummary struct {
	Ref           LinkedRef          `json:"ref"`
	SectionName   string             `json:"sectionName,omitempty"`
	Port          int32              `json:"port,omitempty"`
	Via           *LinkedRef         `json:"via,omitempty"`
	ViaRestricted bool               `json:"viaRestricted,omitempty"`
	Attachment    explore.Attachment `json:"attachment"`
	ConditionType string             `json:"conditionType,omitempty"`
	Reason        string             `json:"reason,omitempty"`
	Message       string             `json:"message,omitempty"`
	// Computed is view A's outcome for this parentRef (2.3); nil when none was computed.
	Computed *Attachment `json:"computed,omitempty"`
}

ParentSummary is one parent of a route row, from status. Via is the Gateway of a ListenerSet parent; ViaRestricted replaces it when the caller may not view that Gateway. ConditionType, Reason and Message are the deciding condition; a pending parent has only Reason, the pending reason.

type PathCountsDTO added in v0.7.0

type PathCountsDTO struct {
	Paths    int `json:"paths"`
	Routes   int `json:"routes"`
	Gateways int `json:"gateways"`
	Backends int `json:"backends"`
}

PathCountsDTO counts filtered visible paths and the distinct routes, Gateways and backends they reach.

type PathFacetsDTO added in v0.7.0

type PathFacetsDTO struct {
	Gateways   []GatewayFacetDTO   `json:"gateways"`
	Namespaces []NamespaceFacetDTO `json:"namespaces"`
}

PathFacetsDTO lists the gateway and namespace filter values, sorted by name.

type PathListenerDTO added in v0.7.0

type PathListenerDTO struct {
	Name     string `json:"name"`
	Protocol string `json:"protocol,omitempty"`
	Port     int32  `json:"port,omitempty"`
}

PathListenerDTO is a path row's listener. Protocol and port are absent when the spec has no listener of that name.

type PathMatchDTO

type PathMatchDTO struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

PathMatchDTO is a path match after defaults.

type PathRowDTO added in v0.7.0

type PathRowDTO struct {
	ID          string          `json:"id,omitempty"`
	Gateway     LinkedRef       `json:"gateway"`
	ListenerSet *LinkedRef      `json:"listenerSet,omitempty"`
	Listener    PathListenerDTO `json:"listener"`
	Hostnames   []string        `json:"hostnames"`
	// Routes are the route chain, root first.
	Routes      []LinkedRef       `json:"routes"`
	Delegated   bool              `json:"delegated"`
	Rule        int               `json:"rule"`
	Matches     []MatchDTO        `json:"matches"`
	GRPCMatches []GRPCMatchDTO    `json:"grpcMatches,omitempty"`
	Action      string            `json:"action"`
	Delegation  *DelegationRefDTO `json:"delegation,omitempty"`
	Backend     *LinkedRef        `json:"backend,omitempty"`
	Port        int32             `json:"port,omitempty"`
	Weight      int32             `json:"weight"`
	Share       *float64          `json:"share,omitempty"`
	ShareState  string            `json:"shareState"`
	Mirror      bool              `json:"mirror"`
	// MirrorPercent is the mirror's written percent, not a share.
	MirrorPercent *float64      `json:"mirrorPercent,omitempty"`
	Problem       ProblemDTO    `json:"problem"`
	Endpoints     *EndpointsDTO `json:"endpoints,omitempty"`
	Note          string        `json:"note,omitempty"`
}

PathRowDTO is one path (design §4.1). Matches applies to HTTPRoute rows and GRPCMatches to GRPCRoute rows; TCPRoute and TLSRoute rows have neither. Matches is null on a delegated row whose view C match is unknown. Share is set for shown, failing, may-fail and no-traffic shares; MirrorPercent only on a mirror row. ID is the row's identity, unique among the rows of one Revision: its attachment, path context, rule, ref and mirror.

type PathSignal added in v0.8.0

type PathSignal struct {
	State      health.State `json:"state"`
	Reason     *RouteReason `json:"reason,omitempty"`
	Incomplete bool         `json:"incomplete"`
}

PathSignal is a route's traffic path signal. Reason is as on RouteRow; Incomplete says the caller may not read everything the path needs (design §8.1).

type PathStepDTO

type PathStepDTO struct {
	Ref   LinkedRef `json:"ref"`
	Match MatchDTO  `json:"match"`
}

PathStepDTO is a route on a context's path and the match it delegated under. A hidden ancestor has link none and nothing else (D-024).

type PathSummaryDTO added in v0.7.0

type PathSummaryDTO struct {
	PathCountsDTO
	ByState          map[string]PathCountsDTO `json:"byState"`
	NotComputed      string                   `json:"notComputed,omitempty"`
	EndpointsNotRead bool                     `json:"endpointsNotRead,omitempty"`
	Hidden           bool                     `json:"hidden,omitempty"`
	Unmemoised       bool                     `json:"unmemoised,omitempty"`
	// Facets are the Gateways and route namespaces of the visible rows,
	// each counted with every filter but its own.
	Facets PathFacetsDTO `json:"facets"`
}

PathSummaryDTO summarises the whole filtered result the caller may see (design §5, §13). Hidden says some paths were left out for the caller; secure mode never sets it, since the permissions note replaces it (design §7.5). Unmemoised says the topology was over the memo cap and derived per request; a viewer without the full read in secure mode is never told. NotComputed says why there are no paths to compute, such as no computed views.

type PathsResponse added in v0.7.0

type PathsResponse struct {
	Install  string         `json:"install"`
	Revision string         `json:"revision,omitempty"`
	Rows     []PathRowDTO   `json:"rows"`
	Next     string         `json:"next,omitempty"`
	Prev     string         `json:"prev,omitempty"`
	Summary  PathSummaryDTO `json:"summary"`
	// DelegationNotChecked says the caller gets no paths through parent routes (D-114).
	DelegationNotChecked bool      `json:"delegationNotChecked,omitempty"`
	CollectedAt          time.Time `json:"collectedAt"`
}

PathsResponse is GET …/paths. Revision is a digest of the whole ordered result the page was cut from, visible rows only: pages of one walk agree on it while the result holds, and a walk whose pages differ must restart.

type PortChainDTO added in v0.7.0

type PortChainDTO struct {
	RefPort         int32   `json:"refPort"`
	ServicePort     *int32  `json:"servicePort,omitempty"`
	ServicePortName string  `json:"servicePortName,omitempty"`
	TargetPort      string  `json:"targetPort,omitempty"`
	TargetName      string  `json:"targetName,omitempty"`
	SlicePorts      []int32 `json:"slicePorts"`
	NoSuchPort      bool    `json:"noSuchPort,omitempty"`
	NoSlicePort     bool    `json:"noSlicePort,omitempty"`
}

PortChainDTO is one referenced port's chain as written and observed (design §9.4): the Service port it matches, its numeric target or target name, and the slice ports observed for that port's name. NoSuchPort is set when the cached Service has no such port, NoSlicePort only when a complete read found no slice port for the name.

type PortDTO added in v0.7.0

type PortDTO struct {
	Port int32  `json:"port"`
	Name string `json:"name,omitempty"`
}

PortDTO is a backend port and its Service port name, when known.

type ProblemDTO added in v0.7.0

type ProblemDTO struct {
	State   health.State `json:"state"`
	Signals []SignalDTO  `json:"signals"`
}

ProblemDTO is a row's worst state and its signals that are not healthy (design §4.5).

type ProcessDTO

type ProcessDTO struct {
	Name           string                   `json:"name"`
	Ready          *bool                    `json:"ready,omitempty"`
	Restarts       *int32                   `json:"restarts,omitempty"`
	RestartsRecent *int32                   `json:"restartsRecent,omitempty"`
	LastStart      *time.Time               `json:"lastStart,omitempty"`
	Termination    *health.TerminationFacts `json:"termination,omitempty"`
	Waiting        string                   `json:"waiting,omitempty"`
	Version        string                   `json:"version,omitempty"`
	Probe          *health.ProbeFacts       `json:"probe,omitempty"`
}

ProcessDTO is one replica or proxy; an absent field was not observed. RestartsRecent are the restarts its KGWUI-019 counts in the window.

type ProcessSetDTO

type ProcessSetDTO struct {
	Observed    bool         `json:"observed"`
	Desired     *int32       `json:"desired,omitempty"`
	Ready       *int32       `json:"ready,omitempty"`
	Processes   []ProcessDTO `json:"processes"`
	Rollout     *RolloutDTO  `json:"rollout,omitempty"`
	Restricted  bool         `json:"restricted,omitempty"`
	NotAssessed bool         `json:"notAssessed,omitempty"`
}

ProcessSetDTO is the processes behind one role; Observed false is "not observed", never failing. Processes lists the Pods the caller may view; Restricted keeps the counts only (§14 rule 16) and is unset in secure mode, where a set the caller may not read is NotAssessed with no counts.

type ProcessSummaries

type ProcessSummaries struct {
	Controller ProcessSummary `json:"controller"`
	Proxies    ProxySummary   `json:"proxies"`
}

ProcessSummaries are the Processes lines of the overview (design §6).

type ProcessSummary

type ProcessSummary struct {
	State    health.State `json:"state"`
	Observed bool         `json:"observed"`
	Ready    *int32       `json:"ready,omitempty"`
	Desired  *int32       `json:"desired,omitempty"`
	// Version is the version every visible replica runs; empty when they differ.
	Version     string `json:"version,omitempty"`
	Restricted  bool   `json:"restricted,omitempty"`
	NotAssessed bool   `json:"notAssessed,omitempty"`
}

ProcessSummary is the controller line. State is the worst controller finding, unknown when not observed and none fired; Restricted keeps the counts and state only (§14 rule 16) and is unset in secure mode. NotAssessed marks a state from derived findings, which a viewer without the full read is not shown (D-106): its State is unknown, and its counts are absent when the Deployment is hidden.

type ProcessesResponse

type ProcessesResponse struct {
	Install     string                 `json:"install"`
	Controller  ProcessSetDTO          `json:"controller"`
	Proxies     Page[GatewayProcesses] `json:"proxies"`
	CollectedAt time.Time              `json:"collectedAt"`
}

ProcessesResponse is GET …/processes: the controller's processes and a page of the Gateways' proxy processes (design §13.1).

type ProxyStatsDTO

type ProxyStatsDTO struct {
	Available   bool                `json:"available"`
	Unavailable health.Availability `json:"unavailable,omitempty"`
	Reason      string              `json:"reason,omitempty"`
}

ProxyStatsDTO says whether proxy stats feed a Gateway; Unavailable and Reason say why not (D-034).

type ProxySummary

type ProxySummary struct {
	State       health.State `json:"state"`
	NotAssessed bool         `json:"notAssessed,omitempty"`
	Gateways    int          `json:"gateways"`
	Ready       int          `json:"ready"`
	Rejecting   int          `json:"rejecting"`
	Skew        int          `json:"skew"`
	Restarting  int          `json:"restarting"`
	NotObserved int          `json:"notObserved"`
	SelfManaged int          `json:"selfManaged"`
}

ProxySummary counts the visible Gateways: those with every proxy ready, with a reject, with version skew, with a restart, whose proxies are not observed, and whose proxies are self-managed (KGWUI-010; also counted in NotObserved). State is the worst known health of those Gateways; unknown when none is known.

NotAssessed is as on ProcessSummary; then Ready and NotObserved count only the Gateways whose proxy Deployments and Pods the viewer may list.

type Ready added in v0.8.0

type Ready func() (ready bool, reason string)

Ready reports whether the process can serve; the reason is for the log only.

func ModelReady added in v0.8.0

func ModelReady(src ModelSource) Ready

ModelReady is ready once the model is synced and no install was rejected (D-016). A rejected install's ID goes in the reason, never into a response.

type RefExplanationDTO added in v0.7.0

type RefExplanationDTO struct {
	Route       LinkedRef     `json:"route"`
	Rule        int           `json:"rule"`
	Ref         int           `json:"ref"`
	Path        string        `json:"path"`
	Kind        string        `json:"kind"`
	Reason      string        `json:"reason,omitempty"`
	Explanation string        `json:"explanation,omitempty"`
	Fix         *SuggestedFix `json:"fix,omitempty"`
}

RefExplanationDTO explains one route ref to the backend that does not resolve (design §10). Kind is attributed, candidate or waiting. Ref is the backendRefs index, which a backendRef's own mirror shares, and -1 for a rule filter's mirror; Path, where the route writes the ref, tells them apart.

type RolloutDTO

type RolloutDTO struct {
	Progressing bool   `json:"progressing"`
	Reason      string `json:"reason,omitempty"`
}

RolloutDTO is a workload's last rollout; Reason is a stuck one's.

type RouteAnnotations

type RouteAnnotations struct {
	InheritParentMatcher *bool `json:"inheritParentMatcher,omitempty"`
}

RouteAnnotations are the route annotations the UI reads. A nil field is an absent annotation.

type RouteAttachment

type RouteAttachment struct {
	ParentRef objects.ParentRef `json:"parentRef"`
	Index     int               `json:"index"`
	Target    LinkedRef         `json:"target"`
	Result    Attachment        `json:"result"`
}

RouteAttachment is view A for one Gateway or ListenerSet parentRef of a route, by its index in spec.parentRefs.

type RouteCounts

type RouteCounts struct {
	Accepted    int `json:"accepted"`
	NotAccepted int `json:"notAccepted"`
	Pending     int `json:"pending"`
	Unwatched   int `json:"unwatched"`
}

RouteCounts counts the visible routes under a parent per attachment, as the routes list with that parent and attachment totals them.

type RouteDetail

type RouteDetail struct {
	Install            string               `json:"install"`
	Ref                LinkedRef            `json:"ref"`
	Generation         int64                `json:"generation"`
	Health             health.State         `json:"health"`
	Reason             *DetailReason        `json:"reason,omitempty"`
	Candidate          *Candidate           `json:"candidate,omitempty"`
	RuleSet            string               `json:"ruleSet,omitempty"`
	RuleSetLabel       string               `json:"ruleSetLabel,omitempty"`
	Hostnames          []string             `json:"hostnames"`
	Annotations        RouteAnnotations     `json:"annotations"`
	ParentRefs         []SpecParentRef      `json:"parentRefs"`
	Parents            []ParentStatus       `json:"parents"`
	Attachments        []RouteAttachment    `json:"attachments,omitempty"`
	Serves             []TraceAttachmentDTO `json:"serves,omitempty"`
	Rules              []RuleDTO            `json:"rules"`
	Effective          []EffectiveDTO       `json:"effective,omitempty"`
	EffectiveTruncated bool                 `json:"effectiveTruncated,omitempty"`
	Ancestors          []AncestorPathDTO    `json:"ancestors"`
	AncestorsTruncated bool                 `json:"ancestorsTruncated"`
	ChildCount         int                  `json:"childCount"`
	DeclaredCount      int                  `json:"declaredCount"`
	// DelegationNotChecked says the caller gets no delegation analysis (D-114).
	DelegationNotChecked bool      `json:"delegationNotChecked,omitempty"`
	CollectedAt          time.Time `json:"collectedAt"`
	// Config and Path are as on RouteRow; Health is their summary.
	Config RouteSignal `json:"config"`
	Path   PathSignal  `json:"path"`
}

RouteDetail is GET …/routes/{group}/{kind}/{ns}/{name} for HTTPRoute, GRPCRoute, TCPRoute and TLSRoute. ChildCount and DeclaredCount count visible routes only. Effective is view C per parent edge (2.4); EffectiveTruncated says the route had more parent edges than were kept. Serves are the attachments the route's visible paths run through (design §7.1), in the path model's attachment order; look-alike ones merge, worst state first.

type RouteNamespacesDTO

type RouteNamespacesDTO struct {
	From     string                `json:"from"`
	Selector *metav1.LabelSelector `json:"selector,omitempty"`
}

RouteNamespacesDTO is allowedRoutes.namespaces.

type RouteReason added in v0.7.1

type RouteReason struct {
	health.RowReason
	Backend *LinkedRef `json:"backend,omitempty"`
}

RouteReason is a route row's reason plus, on kind backend-problem, the backend when the caller may view it; else that kind keeps only its code (D-082).

type RouteRow

type RouteRow struct {
	Ref          LinkedRef       `json:"ref"`
	Hostnames    []string        `json:"hostnames"`
	Parents      []ParentSummary `json:"parents"`
	ParentRoutes []LinkedRef     `json:"parentRoutes"`
	Children     int             `json:"children"`
	Flags        []string        `json:"flags"`
	// Health is the summary of Config and Path (design §8.3).
	Health health.State `json:"health"`
	// Reason says why Health is not healthy (D-063).
	Reason *RouteReason `json:"reason,omitempty"`
	Mirror bool         `json:"mirror,omitempty"`
	// Config and Path are the route's two signals (design §8.1).
	Config RouteSignal `json:"config"`
	Path   PathSignal  `json:"path"`
}

RouteRow is one row of the routes list. Mirror is set only under a backend filter, when every matched use of the row is a RequestMirror.

type RouteSignal added in v0.8.0

type RouteSignal struct {
	State  health.State      `json:"state"`
	Reason *health.RowReason `json:"reason,omitempty"`
}

RouteSignal is a route's configuration signal: its own findings.

type RuleDTO

type RuleDTO struct {
	Index            int             `json:"index"`
	Name             string          `json:"name,omitempty"`
	Matches          []MatchDTO      `json:"matches"`
	Filters          []FilterDTO     `json:"filters"`
	BackendRefs      []BackendRefDTO `json:"backendRefs"`
	EffectiveFilters []FilterDTO     `json:"effectiveFilters,omitempty"`
}

RuleDTO is one spec rule. Omitted matches carry the CRD default, one PathPrefix "/" match. An explicit empty list stays [] as written; kgateway treats it as match-all (or, for an inheriting child, the parent's match), so clients must not render it as "matches nothing". A TCPRoute or TLSRoute rule has no matches: []. EffectiveFilters is reserved and never set.

type RuleEvidence

type RuleEvidence struct {
	Policy *LinkedRef `json:"policy,omitempty"`
	// contains filtered or unexported fields
}

RuleEvidence is KGWUI-015's evidence on the wire: the policy carries its link.

func (*RuleEvidence) EvidenceKind

func (*RuleEvidence) EvidenceKind() string

EvidenceKind implements health.Evidence.

func (*RuleEvidence) MarshalJSON

func (e *RuleEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type RuntimeDTO added in v0.7.0

type RuntimeDTO struct {
	Install  string    `json:"install"`
	Gateway  LinkedRef `json:"gateway"`
	Proxy    string    `json:"proxy"`
	Instance string    `json:"instance"`
}

RuntimeDTO names the proxy process a per-proxy endpoints source reads (#35). Instance changes when the proxy is replaced.

type ServiceFactDTO added in v0.7.0

type ServiceFactDTO struct {
	Type  string    `json:"type"`
	Ports []PortDTO `json:"ports"`
}

ServiceFactDTO is what the cache keeps of a Service: its type and ports.

type SignalDTO added in v0.7.0

type SignalDTO struct {
	Kind       string       `json:"kind"`
	Code       string       `json:"code,omitempty"`
	Title      string       `json:"title,omitempty"`
	Ref        *LinkedRef   `json:"ref,omitempty"`
	State      health.State `json:"state"`
	Attachment *int         `json:"attachment,omitempty"`
	Listener   string       `json:"listener,omitempty"`
}

SignalDTO is one existing signal on a row's chain: its kind, its code (a finding code, condition type, capability state or view C reason) and object. Title is a finding signal's message, as the findings API shows it. Attachment, on a route detail backendRef only, indexes the serves entry an attachment's Gateway, listener or parent status signal came from. Listener names the listener of Ref a listener's signal is about, waiting ones included.

type SnapshotDTO

type SnapshotDTO struct {
	By        string `json:"by"`
	Listeners int    `json:"listeners"`
	Routes    int    `json:"routes"`
	Clusters  int    `json:"clusters"`
	Endpoints int    `json:"endpoints"`
	Secrets   int    `json:"secrets"`
}

SnapshotDTO is kgateway_xds_snapshot_resources for one Gateway. By is always "controller": what it built, not what proxies accepted; never a finding.

type SpecParentRef

type SpecParentRef struct {
	objects.ParentRef
	Target LinkedRef `json:"target"`
}

SpecParentRef is a spec parentRef with its target's link, so a parent without a status entry still links through admission (design §7.1).

type SuggestedFix

type SuggestedFix struct {
	Title  string    `json:"title"`
	Target LinkedRef `json:"target"`
	Create bool      `json:"create"`
	Path   string    `json:"path,omitempty"`
	YAML   string    `json:"yaml"`
	Basis  string    `json:"basis"`
}

SuggestedFix is the one change the evidence leaves (design §7.7). Path is the fragment's location when Create is false.

type TraceAttachmentDTO added in v0.7.0

type TraceAttachmentDTO struct {
	Gateway     LinkedRef       `json:"gateway"`
	ListenerSet *LinkedRef      `json:"listenerSet,omitempty"`
	Listener    PathListenerDTO `json:"listener"`
	Hostnames   []string        `json:"hostnames"`
	State       health.State    `json:"state"`
}

TraceAttachmentDTO is one attachment a route serves through, with the state of its own Gateway, listener and parent status signals.

type TrailRefs

type TrailRefs struct {
	Install string      `json:"install"`
	Refs    []LinkedRef `json:"refs"`
}

TrailRefs is GET …/refs: each requested ref with its link, in request order.

type Verdict

type Verdict struct {
	State       health.State            `json:"state"`
	Problems    int                     `json:"problems"`
	Counts      map[health.Severity]int `json:"counts"`
	OldestSince *time.Time              `json:"oldestSince,omitempty"`
	Reason      string                  `json:"reason,omitempty"`
}

Verdict is the install's state over every finding (§14 rule 18); Reason names the required check that made it unknown, and OldestSince is the oldest since the caller may see.

type Viewer added in v0.8.0

type Viewer interface {
	// Secure reports whether the request runs in secure mode.
	Secure() bool
	// ReadsAll reports whether the caller has the full read (design §6.4).
	ReadsAll() bool
	// Can reports whether the caller may see ref as a population member: a row, count or aggregate.
	Can(objects.Ref) bool
	// CanNamed reports whether the caller may see ref by name: a detail page's subject.
	CanNamed(objects.Ref) bool
	// CanList reports whether the caller may list gk in namespace, "" meaning cluster-wide.
	CanList(gk objects.GroupKind, namespace string) bool
	// Shown reports whether the caller sees f: always outside secure mode and
	// under the full read; else only an own-object finding on readable objects (D-106).
	Shown(*health.Finding) bool
	// Backends are install i's Backends the caller may see. In secure mode
	// without the full read, only those a readable route of i names (D-107).
	Backends(i *engine.InstallModel) []*unstructured.Unstructured
}

Viewer is what the caller of one request may see, for extension handlers that serve cluster objects (design §7.2). It answers as the core handlers do, so an extension applies the same rule (D-085). One request uses it, on one goroutine. Install.Owned.Backends depends on hidden consumer routes: use Backends instead. Only pkg/api implements it, so methods may be added.

func ViewerOf added in v0.8.0

func ViewerOf(r *http.Request, a Authorizer) Viewer

ViewerOf is the Viewer of r's caller through a, the handler's Authorizer (nil means AllowAll, or DenyAll in secure mode). It is secure when r carries the commit wrapper's state.

type WithheldDTO

type WithheldDTO struct {
	Message string    `json:"message"`
	First   time.Time `json:"first"`
	Last    time.Time `json:"last"`
}

WithheldDTO is the snapshot deferral that recurred after the proxies connected: the first and last such line (kgateway 2.3 and 2.4).

type XDSEvidence

type XDSEvidence struct {
	RecentlyChanged []LinkedRef `json:"recentlyChanged,omitempty"`
	// contains filtered or unexported fields
}

XDSEvidence is KGWUI-001's evidence on the wire: recently changed objects are those the caller may view, each with its link (§14 rule 14).

func (*XDSEvidence) EvidenceKind

func (*XDSEvidence) EvidenceKind() string

EvidenceKind implements health.Evidence.

func (*XDSEvidence) MarshalJSON

func (e *XDSEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

Jump to

Keyboard shortcuts

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