Skip to content

Commit 7619e92

Browse files
committed
feat(featuregate): version-keyed feature gates with readiness-gated alpha opt-ins (#1275)
Introduce solo-provisioner's feature-gate system, a thin adapter over github.com/automa-saga/gatekit that lets a behaviour or contract change land behind an off-by-default gate instead of forcing every change to stay backward-compatible. Layer 1 of epic #1275 (gate + maturity); Layer 2 (finalize, state-backed activation axis, gated migrations) is out of scope. Core model (internal/featuregate) - A registry keys every gated behaviour by an activation version (ActiveFrom) and tags it with a maturity (Alpha/Beta/GA). CurrentActivationVersion is the in-force version (1, the GA floor); SupportWindow is the single source of the window W. - Two axes: a feature is on when the last spec with ActiveFrom <= current resolves on; Alpha needs an operator opt-in, Beta/GA follow the version axis alone. Readiness-gated opt-ins - An operator opt-in (--experimental or SOLO_PROVISIONER_ENABLE_<FEATURE>) enables an alpha only when its spec is ready (Default:true). An unfinished Alpha,Default:false feature is dormant: no opt-in can turn it on, yet gate.Enabled(f) still compiles and returns false, so a feature can be merged incrementally with no risk of exposing a half-done path. --experimental is command-scoped and shares one gate with business code, so command availability and in-code behaviour are one decision. CLI - `solo-provisioner feature list` inspects the catalog (maturity, ActiveFrom, enabled, opt-in env var) with filters; read-only, runs unprivileged. - common.GateFeature / GateFeatureFlag gate a command or a single flag by maturity: an alpha is hidden from --help and refused unless opted in; a persistent flag is gated on PersistentPreRunE so inheriting subcommands are covered too. A golden --help surface test pins the visible command/flag surface so accidental exposure can't merge. - `kube cluster upgrade` moved onto the KubeClusterUpgrade alpha gate. Lints (ordinary CI, pure-Go) - Removal lint, baseline lint (against testdata/baseline_registry.json, regenerated only at release with -update-baseline), and a dev-gate-window warning. Docs - docs/dev/feature-gates.md: the model, defining and promoting a feature, the opt-in surfaces, development vs compatibility gates, and the lints. Replaces the bespoke --experimental command gate (GateExperimental) and moves the whole system onto gatekit v0.7.0. Signed-off-by: Lenin Mehedy <lenin.mehedy@hashgraph.com>
1 parent d0a29a7 commit 7619e92

24 files changed

Lines changed: 2031 additions & 186 deletions

‎cmd/cli/commands/common/experimental_gate.go‎

Lines changed: 0 additions & 98 deletions
This file was deleted.

‎cmd/cli/commands/common/experimental_gate_test.go‎

Lines changed: 0 additions & 75 deletions
This file was deleted.
Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
3+
package common
4+
5+
import (
6+
"fmt"
7+
"strings"
8+
9+
"github.com/automa-saga/errx"
10+
gatekit "github.com/automa-saga/gatekit"
11+
"github.com/hashgraph/solo-weaver/internal/featuregate"
12+
"github.com/hashgraph/solo-weaver/pkg/reasons"
13+
"github.com/joomcode/errorx"
14+
"github.com/spf13/cobra"
15+
)
16+
17+
// experimentalFlagName is the hidden, command-scoped alpha opt-in flag. It enables the
18+
// command's feature only if it is ready (see featuregate.ExperimentalReady).
19+
const experimentalFlagName = "experimental"
20+
21+
// GateFeature gates a command by its feature's maturity: an ALPHA command is hidden
22+
// from --help, a BETA command is labelled "[beta]", and both refuse to run unless the
23+
// operator opts in (--experimental or SOLO_PROVISIONER_ENABLE_<FEATURE>) and the
24+
// feature is ready; GA commands always run. On a command group it gates the whole
25+
// subtree; on a leaf, just that command. Hidden alpha commands stay discoverable via
26+
// `solo-provisioner feature list`.
27+
func GateFeature(cmd *cobra.Command, f gatekit.Feature) {
28+
// Label / hide the command by its maturity (static, registry-derived).
29+
switch featuregate.MaturityOf(f) {
30+
case gatekit.Alpha:
31+
cmd.Short = strings.TrimSpace(cmd.Short) + " [alpha]"
32+
cmd.Hidden = true
33+
case gatekit.Beta:
34+
cmd.Short = strings.TrimSpace(cmd.Short) + " [beta]"
35+
}
36+
37+
installExperimentalFlag(cmd)
38+
39+
prev := cmd.PersistentPreRunE
40+
cmd.PersistentPreRunE = func(c *cobra.Command, args []string) error {
41+
// Chain the prior pre-run (or the root pre-run cobra now skips), then the gate.
42+
if prev != nil {
43+
if err := prev(c, args); err != nil {
44+
return err
45+
}
46+
} else if err := RunPersistentPreRun(c, args); err != nil {
47+
return err
48+
}
49+
return requireFeatureEnabled(c, f)
50+
}
51+
}
52+
53+
// GateFeatureFlag gates a single flag (not the whole command) by its feature's
54+
// maturity — use it when a GA command gains an unproven flag. An ALPHA flag is hidden
55+
// and errors if set without opting in; a BETA flag is labelled "[beta]". Opt-in is the
56+
// same as GateFeature. The flag must already be registered on cmd.
57+
func GateFeatureFlag(cmd *cobra.Command, flagName string, f gatekit.Feature) {
58+
// A persistent flag is inherited by subcommands; a local one is not — this decides
59+
// where the check must live (see below).
60+
persistent := cmd.PersistentFlags().Lookup(flagName)
61+
flag := persistent
62+
if flag == nil {
63+
flag = cmd.Flags().Lookup(flagName)
64+
}
65+
if flag == nil {
66+
return
67+
}
68+
69+
installExperimentalFlag(cmd)
70+
71+
switch featuregate.MaturityOf(f) {
72+
case gatekit.Alpha:
73+
flag.Hidden = true
74+
flag.Usage = strings.TrimSpace(flag.Usage) + " [alpha]"
75+
case gatekit.Beta:
76+
flag.Usage = strings.TrimSpace(flag.Usage) + " [beta]"
77+
}
78+
79+
// enforce refuses the flag unless opted in — but only when the flag was set.
80+
enforce := func(c *cobra.Command, args []string) error {
81+
if c.Flags().Changed(flagName) {
82+
return requireFeatureEnabled(c, f)
83+
}
84+
return nil
85+
}
86+
87+
if persistent != nil {
88+
// cobra inherits PersistentPreRunE but NOT PreRunE, so an inherited flag must
89+
// be checked here to cover subcommands. Chain the prior/root pre-run first.
90+
prev := cmd.PersistentPreRunE
91+
cmd.PersistentPreRunE = func(c *cobra.Command, args []string) error {
92+
if prev != nil {
93+
if err := prev(c, args); err != nil {
94+
return err
95+
}
96+
} else if err := RunPersistentPreRun(c, args); err != nil {
97+
return err
98+
}
99+
return enforce(c, args)
100+
}
101+
return
102+
}
103+
104+
// A local flag is usable only on cmd itself, so PreRunE is sufficient.
105+
prev := cmd.PreRunE
106+
cmd.PreRunE = func(c *cobra.Command, args []string) error {
107+
if prev != nil {
108+
if err := prev(c, args); err != nil {
109+
return err
110+
}
111+
}
112+
return enforce(c, args)
113+
}
114+
}
115+
116+
// installExperimentalFlag registers the hidden, command-scoped --experimental opt-in
117+
// once on cmd (inherited by subcommands when persistent).
118+
func installExperimentalFlag(cmd *cobra.Command) {
119+
if cmd.PersistentFlags().Lookup(experimentalFlagName) == nil {
120+
cmd.PersistentFlags().Bool(experimentalFlagName, false,
121+
"Enable experimental (alpha) features (not supported in production)")
122+
_ = cmd.PersistentFlags().MarkHidden(experimentalFlagName)
123+
}
124+
}
125+
126+
// requireFeatureEnabled returns nil when the operator may run an f-gated command, else
127+
// a decorated refusal. GA/BETA commands always pass; an ALPHA command passes only when
128+
// opted in (--experimental or the env var) AND ready. It stores the resolved gate on
129+
// the command context so business code (featuregate.Gate(ctx)) resolves f the same way.
130+
func requireFeatureEnabled(cmd *cobra.Command, f gatekit.Feature) error {
131+
if featuregate.MaturityOf(f) != gatekit.Alpha {
132+
return nil
133+
}
134+
135+
// --experimental only enables a ready alpha; for a dormant one it is dropped.
136+
ready, err := featuregate.ExperimentalReady(f)
137+
if err != nil {
138+
return err
139+
}
140+
var overrides map[gatekit.Feature]bool
141+
if experimental, _ := cmd.Flags().GetBool(experimentalFlagName); experimental && ready {
142+
overrides = map[gatekit.Feature]bool{f: true}
143+
}
144+
gate, err := featuregate.New(featuregate.Options{Overrides: overrides})
145+
if err != nil {
146+
return err
147+
}
148+
// Share this exact gate with the command's business code.
149+
cmd.SetContext(featuregate.NewContext(cmd.Context(), gate))
150+
151+
if gate.Enabled(f) {
152+
return nil
153+
}
154+
if !ready {
155+
// The feature is registered but unfinished: no opt-in can enable it.
156+
return errx.Decorate(
157+
errorx.RejectedOperation.New("%s is under active development and cannot be enabled yet", f),
158+
reasons.PreconditionNotMet,
159+
"This feature is incomplete and is intentionally not switchable on.",
160+
"It becomes available once it is marked ready in a future release.")
161+
}
162+
return errx.Decorate(
163+
errorx.RejectedOperation.New("%s is an experimental feature and not supported in production", f),
164+
reasons.PreconditionNotMet,
165+
"This feature is under active development and not production-ready.",
166+
fmt.Sprintf("To use it in a non-production environment, pass --experimental (reliable under sudo) or set %s=1.",
167+
featuregate.OverrideEnvVar(f)))
168+
}

0 commit comments

Comments
 (0)