extension

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 22 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 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 registry's; filter objects with api.Visible.
	Authorizer api.Authorizer
	// Capabilities returns the states every WithCapabilities source reports now,
	// in registration order; /api/v1/meta lists the same.
	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 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).

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.

func WithChecks

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

WithChecks adds health checks; by convention their finding codes start with prefix, such as "ACME-". A reserved or repeated prefix adds nothing and Registry.Err reports it.

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 replaces rulesets.Select. A downstream distribution maps its controller to a rule set; a build that is not the kgateway edition receives "" as the version (D-018 §3).

func WithDetectors

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

WithDetectors adds install detectors. They are tried before the upstream detector, 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 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 Registry

type Registry struct {
	Kinds     []kinds.Descriptor
	Detectors []install.Detector
	Scope     install.ScopeProvider
	// Verifier checks scope against the controller. Nil means the upstream
	// verifier, which the app sizes from the metrics interval.
	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.

func New

func New(opts ...Option) *Registry

New returns the upstream registry with opts applied.

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