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
- type Collector
- type Deps
- type Option
- func WithAuthorizer(a api.Authorizer) Option
- func WithCapabilities(f func() []api.Capability) Option
- func WithChecks(prefix string, c ...health.Check) Option
- func WithCollectors(c ...Collector) Option
- func WithCommands(c diagnose.Commands) Option
- func WithComputedRules(f func(controllerVersion string) computed.Selection) Option
- func WithDetectors(d ...install.Detector) Option
- func WithHandlers(name string, f func(r Router, d Deps)) Option
- func WithKinds(d ...kinds.Descriptor) Option
- func WithProcessSource(s process.Source) Option
- func WithProxyModeResolver(p proxymode.Resolver) Option
- func WithProxyStatsSource(s proxystats.Source) Option
- func WithScopeProvider(p install.ScopeProvider) Option
- func WithScopeVerifier(v scopeverify.Verifier) Option
- type Registry
- func (r *Registry) CapabilityStates() []api.Capability
- func (r *Registry) CheckCapabilities(platformNames []string) error
- func (r *Registry) Collectors() []Collector
- func (r *Registry) Err() error
- func (r *Registry) Mounts(d Deps) ([]api.ExtMount, error)
- func (r *Registry) RunCollectors(ctx context.Context, d Deps, s *collect.Store)
- type Router
Constants ¶
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 ¶
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 ¶
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 ¶
WithCommands replaces diagnose.Kubectl, for a platform without kubectl or with its own commands. A method that returns "" hides that step.
func WithComputedRules ¶
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 ¶
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 ¶
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 ¶
WithProcessSource replaces process.Kube, for example to add extension Pods or to report processes that do not run in Pods.
func WithProxyModeResolver ¶
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 (*Registry) CapabilityStates ¶
func (r *Registry) CapabilityStates() []api.Capability
CapabilityStates returns what every source reports now, in registration order.
func (*Registry) CheckCapabilities ¶
CheckCapabilities reports a capability name that collides with a core one or the platform's platformNames, or another source.
func (*Registry) Collectors ¶
Collectors returns the registered collectors, in order.
func (*Registry) Err ¶
Err returns the registration errors joined, or nil. app.Build returns it before it starts anything.