Documentation
¶
Overview ¶
Package flags is gridctl's experimental feature-flag registry. A flag is born experimental and off by default, is enabled per stack through the top-level `experimental:` map in stack.yaml (or per process through a GRIDCTL_EXPERIMENTAL_<NAME> environment variable), and graduates by having its behavior promoted to a real config block. Registry entries are never deleted: a graduated or removed flag keeps its entry so a stale stack.yaml gets a specific migration message instead of a generic unknown-key warning.
Stage semantics follow the OpenTelemetry Collector featuregate model. Setting an unknown or concluded flag name is always a warning, never an error: a stack.yaml written against a newer gridctl must still start on an older one (Article IX).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Flag ¶
type Flag struct {
// Name is the snake_case flag key, spelled identically to the stable
// config key the feature will graduate to.
Name string
// Description is the one-line summary shown in docs and the UI.
Description string
// Stage is the lifecycle position.
Stage Stage
// Since is the release that introduced the flag (bare semver, e.g. "0.1.0").
Since string
// GraduatesBy is the release by which an experimental flag must
// graduate or have its deadline deliberately extended. Required for
// experimental flags; the enforcement test fails past it.
GraduatesBy string
// Message is the migration text for graduated and removed flags, e.g.
// "graduated in 0.2.0; remove the entry, the feature is now always on".
Message string
}
Flag is one registry entry.
func Overdue ¶
Overdue returns the experimental flags whose GraduatesBy deadline is at or before currentVersion. An empty, "dev", or unparseable currentVersion returns nil: development builds never enforce the graduation clock. Pre-release suffixes are ignored — the clock compares major.minor.patch only, so 0.3.0-beta.1 already counts as 0.3.0.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is an ordered, indexed set of flags.
func Default ¶
func Default() *Registry
Default returns the built-in registry. The entries are compile-time constants validated by TestBuiltinRegistryValid; if construction ever fails at runtime an empty registry is returned so no flag resolves on.
func NewRegistry ¶
NewRegistry validates and indexes a set of flags. It returns an error for duplicate or empty names, a missing Since, an experimental flag without a GraduatesBy, or a concluded flag without a migration Message.
type Resolved ¶
type Resolved struct {
// Enabled maps every known experimental flag name that resolved to true.
// Flags resolving to false are absent. Nil when nothing is enabled.
Enabled map[string]bool
// Warnings lists unknown names, concluded names, and malformed env
// overrides encountered during resolution.
Warnings []Warning
}
Resolved is the outcome of resolving a stack's experimental map against a registry and the process environment.
func Resolve ¶
Resolve computes the effective flag set from the stack.yaml `experimental:` map and per-flag GRIDCTL_EXPERIMENTAL_<NAME> env overrides. An env override beats the YAML value; an unset env var defers to YAML; a malformed env value warns and defers to YAML (never silently false). Unknown YAML names warn listing the valid flags; graduated and removed names warn with their migration message and contribute nothing.
type Stage ¶
type Stage string
Stage is a flag's lifecycle position.
const ( // StageExperimental flags are off by default and settable via the // `experimental:` map or env override. StageExperimental Stage = "experimental" // StageGraduated flags have been promoted to a real config block. // Setting one warns with its migration message; the value is ignored. StageGraduated Stage = "graduated" // StageRemoved flags no longer exist in any form. Setting one warns // with its migration message; the value is ignored. StageRemoved Stage = "removed" )
Source Files