extension

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

Documentation

Overview

Package extension is the public seam through which downstream distributions extend the UI backend without forking it (D-003). A downstream main calls app.Run with options from this package.

Compatibility

API v1 (the /api/v1 paths and their JSON) and the SPA URLs are stable from the first release. This Go API (this package and the types it carries) changes only with a README upgrade note and a release-note entry. The 3.1 check-contract change is the last planned break; later additions are optional interfaces, detected by type assertion. When the provider seam arrives, a Kubernetes Detector keeps working as that provider's adapter (D-016).

Index

Constants

View Source
const UpstreamPrefix = "KGWUI-"

UpstreamPrefix is the finding-code prefix reserved for upstream checks.

Variables

This section is empty.

Functions

This section is empty.

Types

type Collector

type Collector interface {
	Name() string
	// Start runs until ctx is done, publishing through d.Publish and d.Fail.
	// An error return is logged once; the collector is not restarted and its
	// values turn unavailable.
	Start(ctx context.Context, d Deps) error
}

Collector is a long-running source of values for checks (design §4.1 gap 2), such as a scraper or a prober. Name follows the WithHandlers rules.

type CollectorEnv added in v0.6.0

type CollectorEnv struct {
	// Kube reads Pods, their logs and, outside the cluster, pods/proxy.
	Kube kubernetes.Interface
	// InCluster reads Pod IPs directly; otherwise through pods/proxy.
	InCluster bool
	// Scraper replaces the controller metrics scraper InCluster selects; nil keeps it.
	Scraper ctrlmetrics.Scraper
	// Interval is the collection interval; MaxAge, 3 × Interval, is when a value is stale.
	Interval, MaxAge time.Duration
	// Clock drives the collectors; nil means the real clock.
	Clock clock.WithTicker
	// Installs and Current return the published model's installs and the model.
	Installs func() []install.Install
	Current  func() *engine.Published
	// Discovered is closed after the first model with an install over a settled cache.
	Discovered <-chan struct{}
	// Collected is the store the collectors publish to; one may read another's values.
	Collected *collect.Store
	// NoProxyStats turns proxy stats off; ControllerLogs turns log reading on.
	NoProxyStats, ControllerLogs bool
	// Pack is the pack's name and Impl its hooks, read when the app is built.
	Pack string
	Impl Impl
}

CollectorEnv is what the app builds a pack's collectors with (Phase 5 design §7.1). A factory only builds, so it may get a zero CollectorEnv to tell its name; the collector starts in Start.

type Deps

type Deps struct {
	// Current returns the published model, nil before the first publication.
	// A handler calls it once per request and serves from that value.
	Current func() *engine.Published
	// Authorizer is the core handler's; handlers filter objects through View, not with it directly.
	// Nil means AllowAll, or DenyAll in secure mode, as for api.NewHandler.
	Authorizer api.Authorizer
	// View is the caller's api.Viewer, through the core handler's authoriser.
	// A handler that serves cluster objects must use it (api.VisibleTo, Can, CanNamed,
	// CanList, Shown), so a change to an object the caller cannot read never changes its response.
	// Install.Owned.Backends depends on hidden consumer routes: use Viewer.Backends.
	View func(r *http.Request) api.Viewer
	// Capabilities returns the states every WithCapabilities source reports now,
	// in registration order; /api/v1/meta lists the same to every viewer.
	Capabilities func() []api.Capability
	// Logger carries the extension's name.
	Logger *slog.Logger
	// Publish stores value under "<collector name>/<key>" and hands it over:
	// the collector never mutates it afterwards. ttl 0 means no expiry. Nil for handlers.
	Publish func(key string, value any, fingerprint uint64, ttl time.Duration)
	// Fail marks a collector key failing or off with a reason. Nil for handlers.
	Fail func(key string, st collect.State, reason string)
}

Deps is what the app gives an extension's handlers (design §4.1 gap 1).

type Impl added in v0.6.0

type Impl struct {
	Scope    install.ScopeProvider
	Verifier scopeverify.Verifier
	Settings func(install.Install) install.Settings
	RulesFor func(version string) computed.Selection
	// Version is the install's implementation version, the input of RulesFor.
	Version func(install.Install) string
	// Reported reads the version the controller reports from the collected
	// values; false keeps the last one (engine.Hooks.Reported).
	Reported func(install.Install, collect.Snapshot) (string, bool)
	// ExperimentalOnly reports whether the controller watches served kind k only
	// with experimental Gateway API features on.
	ExperimentalOnly func(k kinds.Served, inst install.Install) bool
	ProxyMode        proxymode.Resolver
	Process          process.Source
	ProxyStats       proxystats.Source
	Commands         diagnose.Commands
	// Conditions are the implementation's condition types beyond Gateway API's.
	Conditions health.ConditionTypes
	// BackendConsumers lists the backends the install's non-route objects use.
	BackendConsumers func(install.Install, *install.Owned) []objects.Consumer
}

Impl is one pack's per-install hooks, used for the installs its detectors claim (Phase 5 design §4.2). A nil hook is the core's: all namespaces assumed in scope, no settings read, no version, no experimental-only kinds, no scope verification, no processes, every proxy managed and the API's default commands.

type Option

type Option func(*Registry)

Option modifies a Registry.

func WithAuthorizer

func WithAuthorizer(a api.Authorizer) Option

WithAuthorizer replaces the default api.AllowAll. Every API response with resources, findings or counts goes through it (D-013). In secure mode it only narrows the SAR authoriser: both must allow.

func WithCapabilities

func WithCapabilities(f func() []api.Capability) Option

WithCapabilities adds a source of capability states for /api/v1/meta. A capability that is on is also listed in capabilities. Names must not collide with core, platform or other extension capabilities; app.Build calls each source once to check, so a source must report a stable set of names. Sources run on every /api/v1/meta request: keep them fast and safe for concurrent use. Every viewer gets the same states, so a source reports only the extension's own state, never cluster objects.

func WithChecks

func WithChecks(prefix string, c ...health.Check) Option

WithChecks adds health checks to the default pack (kgateway in New, the core in NewCore); by convention their finding codes start with prefix, such as "ACME-". A reserved or repeated prefix adds nothing and Registry.Err reports it. In secure mode a viewer without the full read sees their results as "Not checked" and none of their findings (D-106).

func WithCollectors

func WithCollectors(c ...Collector) Option

WithCollectors adds collectors that the app starts after the cache. Names are unique among collectors; "proxy-stats" is the core collector's and app.Build rejects it. A rejected name is reported by Registry.Err.

func WithCommands

func WithCommands(c diagnose.Commands) Option

WithCommands replaces diagnose.Kubectl, for a platform without kubectl or with its own commands. A method that returns "" hides that step.

func WithComputedRules

func WithComputedRules(f func(controllerVersion string) computed.Selection) Option

WithComputedRules sets the rule-set choice of the default pack (in New, the kgateway pack's rulesets.Select). A downstream distribution maps its controller to a rule set; a build that is not the kgateway edition receives its BaseVersion, "" when unknown (D-018 §3).

func WithDetectors

func WithDetectors(d ...install.Detector) Option

WithDetectors adds install detectors for the default pack. They are tried before the detectors already registered, so a downstream can claim Deployments the upstream one would also match.

func WithHandlers

func WithHandlers(name string, f func(r Router, d Deps)) Option

WithHandlers adds endpoints under /api/ext/{name}/; f registers them when the app is built. name is a lowercase letter, then up to 62 lowercase letters, digits or dashes, and registers once. A rejected name, and a pattern that is malformed or leaves the prefix, is reported by Registry.Err or app.Build.

func WithKinds

func WithKinds(d ...kinds.Descriptor) Option

WithKinds adds kinds to watch, count and serve. Kinds are unique by group and kind: a descriptor for a registered kind replaces it in place.

func WithPack added in v0.6.0

func WithPack(p Pack) Option

WithPack adds p: its kinds, its detectors (tried before those already registered) and its checks. The first pack added becomes the default pack (kgateway in New): the old hook options, WithDetectors and the Registry hook fields set its hooks, whatever their order. A later pack keeps p.Impl. A pack name that is empty or already registered adds nothing, and a collector whose name is invalid or another pack's is dropped; Registry.Err reports both.

func WithProcessSource

func WithProcessSource(s process.Source) Option

WithProcessSource replaces process.Kube, for example to add extension Pods or to report processes that do not run in Pods.

func WithProxyModeResolver

func WithProxyModeResolver(p proxymode.Resolver) Option

WithProxyModeResolver replaces the upstream GatewayParameters resolution.

func WithProxyStatsSource

func WithProxyStatsSource(s proxystats.Source) Option

WithProxyStatsSource replaces proxystats.Kube, for example for proxies that do not run in Pods or another stats format. The core collector keeps the interval, bounds, concurrency and publishing.

func WithScopeProvider

func WithScopeProvider(p install.ScopeProvider) Option

WithScopeProvider replaces the scope provider.

func WithScopeVerifier

func WithScopeVerifier(v scopeverify.Verifier) Option

WithScopeVerifier replaces the scope verifier.

type Pack added in v0.6.0

type Pack struct {
	Name      string
	Kinds     []kinds.Descriptor
	Detectors []install.Detector
	Impl      Impl
	Checks    []health.Check
	// Collectors build the pack's collectors when the app is built. Their names
	// are reserved: a WithCollectors collector cannot take them.
	Collectors []func(CollectorEnv) Collector
	// Features are the UI features the pack's installs support (api.Feature*);
	// the API drops computed and delegation where the rule set lacks them.
	Features []string
}

Pack is one implementation's contributions to the core. Its Name is stamped on each install its detectors claim (install.Install.Impl).

type Registry

type Registry struct {
	Kinds     []kinds.Descriptor
	Detectors []install.Detector
	Scope     install.ScopeProvider
	// Verifier checks scope against the controller. Nil means the upstream
	// verifier for kgateway installs, which the app sizes from the metrics
	// interval; any other install gets none.
	Verifier scopeverify.Verifier
	Checks   []health.Check
	// Authorizer decides per request what the caller may see (D-013).
	Authorizer api.Authorizer
	// ProxyMode decides whether a Gateway's proxy is self-managed. It mirrors
	// controller logic, so a downstream with its own parameters kind replaces it.
	ProxyMode proxymode.Resolver
	// RulesFor selects the computed rule set for a controller's kgateway
	// version, "" when unknown (D-020).
	RulesFor func(controllerVersion string) computed.Selection
	// Process reports each install's controller and proxy processes (D-016).
	Process process.Source
	// ProxyStats finds proxies and reads their stats (design §8.8); nil means
	// proxystats.Kube over the app's clients.
	ProxyStats proxystats.Source
	// Commands fills in the next-step commands (design §8.5).
	Commands diagnose.Commands
	// contains filtered or unexported fields
}

Registry holds everything the backend is built from. Its hook fields (Scope, Verifier, ProxyMode, RulesFor, Process, ProxyStats, Commands) are the hooks of the default pack: kgateway in New, the core in NewCore (see WithPack).

func New

func New(opts ...Option) *Registry

New returns the core plus the kgateway pack, with opts applied. The kinds and checks keep the order of kinds.Upstream and health.Upstream.

func NewCore added in v0.6.0

func NewCore(opts ...Option) *Registry

NewCore returns the core alone, with opts applied: Gateway API kinds, no detectors, the core checks and no pack hooks.

func (*Registry) CapabilityStates

func (r *Registry) CapabilityStates() []api.Capability

CapabilityStates returns what every source reports now, in registration order.

func (*Registry) CheckCapabilities

func (r *Registry) CheckCapabilities(platformNames []string) error

CheckCapabilities reports a capability name that collides with a core one or the platform's platformNames, or another source.

func (*Registry) ChecksFor added in v0.6.0

func (r *Registry) ChecksFor(impl string) []health.Check

ChecksFor returns the checks that run on installs of pack impl, in registration order: the core's and that pack's. WithChecks adds checks to the default pack, so they run on its installs.

func (*Registry) Collectors

func (r *Registry) Collectors() []Collector

Collectors returns the registered collectors, in order.

func (*Registry) Err

func (r *Registry) Err() error

Err returns the registration errors joined, or nil. app.Build returns it before it starts anything.

func (*Registry) FeaturesFor added in v0.6.0

func (r *Registry) FeaturesFor(i install.Install) []string

FeaturesFor returns the UI features of the pack that claimed i; none for the core.

func (*Registry) ImplFor added in v0.6.0

func (r *Registry) ImplFor(i install.Install) Impl

ImplFor returns the hooks of the pack that claimed i, read from the Registry fields for the default pack. An install no registered pack claims, such as a class-only install, gets the core's hooks.

func (*Registry) KindAppliesTo added in v0.6.0

func (r *Registry) KindAppliesTo(i install.Install, gk objects.GroupKind) bool

KindAppliesTo reports whether served kind gk applies to install i: a pack's own kind applies only to that pack's installs, every other kind to all.

func (*Registry) Mounts

func (r *Registry) Mounts(d Deps) ([]api.ExtMount, error)

Mounts runs every WithHandlers function with d, its Logger tagged with the extension's name, and returns the endpoints for api.WithExtMounts. It returns an error if any endpoint fails api.CheckExtMounts.

func (*Registry) PackCollectors added in v0.6.0

func (r *Registry) PackCollectors(env CollectorEnv) []Collector

PackCollectors builds every pack's collectors with env, in registration order, each with its pack's name and hooks.

func (*Registry) Packs added in v0.6.0

func (r *Registry) Packs() []string

Packs returns the registered pack names, the default pack first.

func (*Registry) RunCollectors

func (r *Registry) RunCollectors(ctx context.Context, d Deps, s *collect.Store)

RunCollectors starts each collector in its own goroutine with d, its Publish and Fail writing to s under the collector's name. When Start returns, its values expire in s.

type Router

type Router interface {
	Handle(pattern string, h http.Handler)
}

Router registers an extension's endpoints. pattern is "[METHOD ]/path" relative to /api/ext/{name}, such as "GET /widgets/{id}".

Jump to

Keyboard shortcuts

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