[DO NOT MERGE] featureflag: prototype license-aware feature gates #171314
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,17 +1,36 @@ | ||
| load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") | ||
|
|
||
| go_library( | ||
| name = "featureflag", | ||
| srcs = [ | ||
| "feature_flags.go", | ||
| "feature_gate.go", | ||
| ], | ||
| importpath = "github.com/cockroachdb/cockroach/pkg/featureflag", | ||
| visibility = ["//visibility:public"], | ||
| deps = [ | ||
| "//pkg/server/license/licensepb", | ||
| "//pkg/server/telemetry", | ||
| "//pkg/settings", | ||
| "//pkg/settings/cluster", | ||
| "//pkg/sql/pgwire/pgcode", | ||
| "//pkg/sql/pgwire/pgerror", | ||
| "//pkg/sql/sqltelemetry", | ||
| "//pkg/util/log", | ||
| "//pkg/util/metric", | ||
| "@com_github_cockroachdb_errors//:errors", | ||
| ], | ||
| ) | ||
|
|
||
| go_test( | ||
| name = "featureflag_test", | ||
| srcs = ["feature_gate_example_test.go"], | ||
| deps = [ | ||
| ":featureflag", | ||
| "//pkg/server/license/licensepb", | ||
| "//pkg/settings/cluster", | ||
| "//pkg/util/leaktest", | ||
| "//pkg/util/log", | ||
| "@com_github_stretchr_testify//require", | ||
| ], | ||
| ) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,192 @@ | ||
| // Copyright 2026 The Cockroach Authors. | ||
| // | ||
| // Use of this software is governed by the CockroachDB Software License | ||
| // included in the /LICENSE file. | ||
|
|
||
| package featureflag | ||
|
|
||
| import ( | ||
| "context" | ||
| "slices" | ||
|
|
||
| "github.com/cockroachdb/cockroach/pkg/server/license/licensepb" | ||
| "github.com/cockroachdb/cockroach/pkg/server/telemetry" | ||
| "github.com/cockroachdb/cockroach/pkg/settings" | ||
| "github.com/cockroachdb/cockroach/pkg/settings/cluster" | ||
| "github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgcode" | ||
| "github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgerror" | ||
| "github.com/cockroachdb/cockroach/pkg/sql/sqltelemetry" | ||
| "github.com/cockroachdb/errors" | ||
| ) | ||
|
|
||
| // FeatureGate combines a license-entitlement check with an optional operator | ||
| // cluster setting (and stubs for experimental/cloud-only gating) into a single | ||
| // enforcement point for a feature. | ||
| // | ||
| // The license-entitlement check reads the installed license proto directly (via | ||
| // GetLicenseHook) and asks whether the gate's feature is among the entitlements | ||
| // the license grants. This deliberately avoids relying on denormalized cluster | ||
| // settings so that entitlements remain a single source of truth. | ||
| // | ||
| // The operator setting, when supplied via WithSetting, is a feature.*.enabled | ||
| // cluster-setting bool that the gate registers on the caller's behalf. Operators | ||
| // retain the ability to turn a feature off even when the license permits it. | ||
| // | ||
| // Lifecycle: a FeatureGate is constructed once, typically in a package-level | ||
| // var via Register, and is immutable thereafter. It is evaluated per-use by | ||
| // calling Enabled, which performs the ordered license-then-operator checks. | ||
| type FeatureGate struct { | ||
| // feature is the license entitlement this gate guards. | ||
| feature licensepb.Feature | ||
|
|
||
| // setting is the operator cluster setting that can additionally disable | ||
| // this feature, or nil if the gate has no operator setting. | ||
| setting *settings.BoolSetting | ||
|
|
||
| // experimental marks the gate as experimental. This is currently a stub: | ||
| // Enabled does not yet enforce any experimental semantics. | ||
| experimental bool | ||
|
|
||
| // cloudOnly marks the gate as available only in cloud deployments. This is | ||
| // currently a stub: Enabled does not yet enforce any cloud-only semantics. | ||
| cloudOnly bool | ||
|
|
||
| // name is the human-readable name used in error messages. It defaults to | ||
| // the feature's enum String() when WithName is not supplied. | ||
| name string | ||
| } | ||
|
|
||
| // Option configures a FeatureGate during construction. Options follow the | ||
| // functional-options pattern and are applied in order by Register. | ||
| type Option func(*FeatureGate) | ||
|
|
||
| // Register constructs a FeatureGate for the given license feature, applies the | ||
| // supplied options, and returns it. It is typically called once to initialize a | ||
| // package-level var. If no WithName option is supplied, the gate's display name | ||
| // defaults to the feature's enum String(). | ||
| func Register(feature licensepb.Feature, opts ...Option) *FeatureGate { | ||
| g := &FeatureGate{ | ||
| feature: feature, | ||
| } | ||
| for _, opt := range opts { | ||
| opt(g) | ||
| } | ||
| if g.name == "" { | ||
| g.name = feature.String() | ||
| } | ||
| return g | ||
| } | ||
|
|
||
| // WithSetting registers a feature.*.enabled cluster-setting bool with the given | ||
| // name and attaches it to the gate. The setting defaults to | ||
| // FeatureFlagEnabledDefault (true). When the setting is false, Enabled denies | ||
| // the feature even if the license permits it. Use Setting() to access the | ||
| // registered *BoolSetting for direct reads or test overrides. | ||
| func WithSetting(name string) Option { | ||
| return func(g *FeatureGate) { | ||
| g.setting = settings.RegisterBoolSetting( | ||
| settings.ApplicationLevel, | ||
| settings.InternalKey(name), | ||
| "set to true to enable the feature, false to disable; default is true", | ||
| FeatureFlagEnabledDefault, | ||
| settings.WithPublic, | ||
| ) | ||
| } | ||
| } | ||
|
|
||
| // Setting returns the operator cluster setting attached to this gate, or nil if | ||
| // the gate was constructed without WithSetting. | ||
| func (g *FeatureGate) Setting() *settings.BoolSetting { | ||
| return g.setting | ||
| } | ||
|
|
||
| // WithName overrides the display name used in error messages. Without it, the | ||
| // gate's name defaults to the feature's enum String(). | ||
| func WithName(name string) Option { | ||
| return func(g *FeatureGate) { | ||
| g.name = name | ||
| } | ||
| } | ||
|
|
||
| // WithExperimental marks the gate as experimental. | ||
| // | ||
| // TODO(vishalv): stub — not enforced by Enabled yet. The real implementation | ||
| // would allow experimental features in non-release builds and require an | ||
| // explicit unsafe-experimental-mode interlock in release builds. | ||
| func WithExperimental() Option { | ||
| return func(g *FeatureGate) { | ||
| g.experimental = true | ||
| } | ||
| } | ||
|
|
||
| // WithCloudOnly marks the gate as available only in cloud deployments. | ||
| // | ||
| // TODO(vishalv): stub — not enforced by Enabled yet. The real implementation | ||
| // would check the MSO environment variable to determine cloud context. | ||
| func WithCloudOnly() Option { | ||
| return func(g *FeatureGate) { | ||
| g.cloudOnly = true | ||
| } | ||
| } | ||
|
|
||
| // GetLicenseHook returns the currently installed license, or nil if none is | ||
| // installed. It is populated by an init() in pkg/server/license to avoid an | ||
| // import cycle (server/license imports featureflag, not the reverse). When | ||
| // nil, the license gate is permissive. | ||
| var GetLicenseHook func(st *cluster.Settings) (*licensepb.License, error) | ||
|
Contributor
There was a problem hiding this comment. not a blocking concern right now but eventually I think this would be cleaner if we could have featureflag depend on the license setting; perhaps that means the setting is in the wrong place if pkg/server/license is depending on featureflag and we'd want to move the setting itself to a util pkg separate from the the higher level code in pkg/server that is probably what's pulling in featureflag. but again, not blocking for now -- just something i'd maybe have in a TODO.
Contributor
Author
There was a problem hiding this comment. Agreed, the hook is there purely to break the cycle. Moving the license setting (or at least the |
||
|
|
||
| // Enabled evaluates the gate against the current cluster state and returns nil | ||
| // if the feature is permitted, or an error describing why it is denied. | ||
| // | ||
| // The checks are evaluated in order: | ||
| // | ||
| // 1. License entitlement. If no license is installed (or no hook is wired up), | ||
| // the gate is permissive. If a license is present, the feature must appear | ||
| // in the license's entitlement list; otherwise the call is denied with an | ||
| // InsufficientPrivilege error. | ||
| // 2. Operator setting. If the gate has an operator setting and it is disabled, | ||
| // the call is denied with an OperatorIntervention error and a denial | ||
| // telemetry counter is incremented. | ||
| // | ||
| // Experimental and cloud-only gating are stubs and not yet enforced. | ||
| func (g *FeatureGate) Enabled(ctx context.Context, st *cluster.Settings) error { | ||
| // License gate first. | ||
| // | ||
| // During this prototype, the absence of a license is permissive: with no | ||
| // hook wired up or no license installed we allow the feature and fall | ||
| // through to the operator-setting gate. | ||
| if GetLicenseHook != nil { | ||
| lic, err := GetLicenseHook(st) | ||
| if err != nil { | ||
| return errors.Wrap(err, "reading license") | ||
| } | ||
| if lic != nil { | ||
| // TODO: an installed license whose Features list is empty predates | ||
| // the entitlements field. This prototype treats that as permissive | ||
| // (allow). Whether empty-features should be strict (deny) or | ||
| // permissive (allow) is an open decision for David. | ||
| if len(lic.Features) > 0 && !slices.Contains(lic.Features, g.feature) { | ||
| err := pgerror.Newf( | ||
| pgcode.InsufficientPrivilege, | ||
| "feature %s is not included in your license", | ||
| g.name, | ||
| ) | ||
| return errors.WithHint(err, "upgrade your license to enable this feature") | ||
| } | ||
| } | ||
| } | ||
|
|
||
| // Operator setting gate second. | ||
| if g.setting != nil { | ||
| if !g.setting.Get(&st.SV) { | ||
| telemetry.Inc(sqltelemetry.FeatureDeniedByFeatureFlagCounter) | ||
| return pgerror.Newf( | ||
| pgcode.OperatorIntervention, | ||
| "feature %s was disabled by the database administrator", | ||
| g.name, | ||
| ) | ||
| } | ||
| } | ||
|
|
||
| return nil | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| // Copyright 2026 The Cockroach Authors. | ||
| // | ||
| // Use of this software is governed by the CockroachDB Software License | ||
| // included in the /LICENSE file. | ||
|
|
||
| // This file is a compiling demonstration of the feature-gate API shape for the | ||
| // prototype. It exercises both kinds of gate that featureflag.Register can | ||
| // build: a license-only gate (modeled on multi-region) and a license+setting | ||
| // gate (modeled on changefeed), and shows how Enabled evaluates each. It is | ||
| // deliberately self-contained and does not touch any real call sites; the | ||
| // setting it registers is a throwaway used solely to drive the operator gate. | ||
| package featureflag_test | ||
|
|
||
| import ( | ||
| "context" | ||
| "testing" | ||
|
|
||
| "github.com/cockroachdb/cockroach/pkg/featureflag" | ||
| "github.com/cockroachdb/cockroach/pkg/server/license/licensepb" | ||
| "github.com/cockroachdb/cockroach/pkg/settings/cluster" | ||
| "github.com/cockroachdb/cockroach/pkg/util/leaktest" | ||
| "github.com/cockroachdb/cockroach/pkg/util/log" | ||
| "github.com/stretchr/testify/require" | ||
| ) | ||
|
|
||
| // cfGate is a license+setting gate modeled on changefeed. It is declared at | ||
| // package scope because WithSetting calls settings.RegisterBoolSetting, which | ||
| // must happen at init time so that cluster settings objects pick up the default. | ||
| var cfGate = featureflag.Register( | ||
| licensepb.Feature_CHANGEFEED, | ||
| featureflag.WithSetting("test.featuregate.changefeed.enabled"), | ||
| ) | ||
|
|
||
| // TestFeatureGateExample demonstrates the feature-gate API shape by building | ||
| // and evaluating both kinds of gate. Because pkg/server/license is not imported | ||
| // here, GetLicenseHook stays nil and the license gate is permissive, which lets | ||
| // the test focus on the operator-setting path. | ||
| func TestFeatureGateExample(t *testing.T) { | ||
| defer leaktest.AfterTest(t)() | ||
| defer log.Scope(t).Close(t) | ||
|
|
||
| ctx := context.Background() | ||
| st := cluster.MakeTestingClusterSettings() | ||
|
|
||
| // A license-only gate (like multi-region) has no operator setting. With no | ||
| // license installed the license gate is permissive, so Enabled allows it. | ||
| mrGate := featureflag.Register(licensepb.Feature_MULTIREGION) | ||
| require.NoError(t, mrGate.Enabled(ctx, st)) | ||
|
|
||
| // A license+setting gate (like changefeed) additionally consults an operator | ||
| // setting. With the setting defaulting true and no license installed, both | ||
| // gates allow the feature. | ||
| require.NoError(t, cfGate.Enabled(ctx, st)) | ||
|
|
||
| // Disabling the operator setting denies the feature even though the license | ||
| // gate remains permissive. | ||
| cfGate.Setting().Override(ctx, &st.SV, false) | ||
| require.Error(t, cfGate.Enabled(ctx, st)) | ||
| } | ||
|
|
||
| // TestFeatureGateLicenseDenial exercises the license-entitlement path by | ||
| // overriding GetLicenseHook to return a license that grants only a subset of | ||
| // features. This is normally wired by pkg/server/license, but the prototype | ||
| // keeps the hook exported so a license-gated decision can be demonstrated in | ||
| // isolation. | ||
| func TestFeatureGateLicenseDenial(t *testing.T) { | ||
| defer leaktest.AfterTest(t)() | ||
| defer log.Scope(t).Close(t) | ||
|
|
||
| ctx := context.Background() | ||
| st := cluster.MakeTestingClusterSettings() | ||
|
|
||
| // Install a license that entitles BACKUP but not CHANGEFEED. | ||
| featureflag.GetLicenseHook = func(*cluster.Settings) (*licensepb.License, error) { | ||
| return &licensepb.License{ | ||
| Features: []licensepb.Feature{licensepb.Feature_BACKUP}, | ||
| }, nil | ||
| } | ||
| defer func() { featureflag.GetLicenseHook = nil }() | ||
|
|
||
| // An entitled feature passes the license gate. | ||
| backupGate := featureflag.Register(licensepb.Feature_BACKUP) | ||
| require.NoError(t, backupGate.Enabled(ctx, st)) | ||
|
|
||
| // A feature absent from the license is denied, even with no operator setting. | ||
| changefeedGate := featureflag.Register(licensepb.Feature_CHANGEFEED) | ||
| require.Error(t, changefeedGate.Enabled(ctx, st)) | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.