featuregate

type Feature string

type FeatureGate interface {
	// Enabled returns true if the key is enabled.
	Enabled(key Feature) bool
	// KnownFeatures returns a slice of strings describing the FeatureGate's known features.
	KnownFeatures() []string
	// Dependencies returns a copy of the known feature dependencies.
	Dependencies() map[Feature][]Feature
	// DeepCopy returns a deep copy of the FeatureGate object, such that gates can be
	// set on the copy without mutating the original. This is useful for validating
	// config against potential feature gate changes before committing those changes.
	DeepCopy() MutableVersionedFeatureGate
	// Validate checks if the flag gates are valid at the emulated version.
	Validate() []error
}

type FeatureSpec struct {
	// Default is the default enablement state for the feature
	Default bool
	// LockToDefault indicates that the feature is locked to its default and cannot be changed
	LockToDefault bool
	// PreRelease indicates the current maturity level of the feature
	PreRelease prerelease
	// Version indicates the earliest version from which this FeatureSpec is valid.
	// If multiple FeatureSpecs exist for a Feature, the one with the highest version that is less
	// than or equal to the effective version of the component is used.
	Version *version.Version
	// MinCompatibilityVersion indicates the lowest version that this feature spec is compatible with.
	// The component's minimum compatibility version must be greater than or equal to this version for this spec to be used.
	// This allows features with skew compatibility implications to be introduced as Beta,
	// but only on by default once the minimum compatibility version is high enough.
	// If unspecified, it is inherited from the previous feature stage.
	// If specified, it must be preceded by another FeatureSpec with the same version and different default but without the MinCompatibilityVersion.
	// i.e. MinCompatibilityVersion should only be used to specify a different default value at the same version.
	//
	// Version vs. MinCompatibilityVersion:
	//  - Version determines the stability of the feature based on the server's emulation version.
	//  - MinCompatibilityVersion adds a further check based on the version compatibility
	// with all servers in the control plane this server expects to communicate with.
	//
	// Example:
	// 	FeatureA: []FeatureSpec{
	// 		{Version: version.MustParse("1.35"), Default: false, PreRelease: Beta},
	// 		{Version: version.MustParse("1.35"), Default: true, PreRelease: Beta, MinCompatibilityVersion: version.MustParse("1.35")},
	// 	}
	// In a server running version 1.35:
	//  - With --min-compatibility-version=1.34 (default), FeatureA is Beta and disabled by default.
	//  - With --min-compatibility-version=1.35, FeatureA becomes enabled by default.
	MinCompatibilityVersion *version.Version
}

type MutableFeatureGate interface {
	FeatureGate

	// AddFlag adds a flag for setting global feature gates to the specified FlagSet.
	AddFlag(fs *pflag.FlagSet)
	// Close sets closed to true, and prevents subsequent calls to Add
	Close()
	// Set parses and stores flag gates for known features
	// from a string like feature1=true,feature2=false,...
	Set(value string) error
	// SetFromMap stores flag gates for known features from a map[string]bool or returns an error
	SetFromMap(m map[string]bool) error
	// Add adds features to the featureGate.
	Add(features map[Feature]FeatureSpec) error
	// GetAll returns a copy of the map of known feature names to feature specs.
	GetAll() map[Feature]FeatureSpec
	// AddMetrics adds feature enablement metrics
	AddMetrics()
	// OverrideDefault sets a local override for the registered default value of a named
	// feature. If the feature has not been previously registered (e.g. by a call to Add), has a
	// locked default, or if the gate has already registered itself with a FlagSet, a non-nil
	// error is returned.
	//
	// When two or more components consume a common feature, one component can override its
	// default at runtime in order to adopt new defaults before or after the other
	// components. For example, a new feature can be evaluated with a limited blast radius by
	// overriding its default to true for a limited number of components without simultaneously
	// changing its default for all consuming components.
	OverrideDefault(name Feature, override bool) error
}

type MutableVersionedFeatureGate interface {
	MutableFeatureGate
	// EmulationVersion returns the version the feature gate is set to emulate.
	// If set, the feature gate would enable/disable features based on
	// feature availability and pre-release at the emulated version instead of the binary version.
	EmulationVersion() *version.Version
	// MinCompatibilityVersion returns the minimum version of all control plane components
	// that the current server must maintain compatibility with.
	// This is used to gate features that have cross-component compatibility concerns, for example, during cluster upgrades/rollbacks.
	// If not explicitly set, it defaults to one minor version prior to EmulationVersion().
	// A feature stage is disabled if its FeatureSpec.MinCompatibilityVersion is greater than this version.
	MinCompatibilityVersion() *version.Version
	// SetEmulationVersion overrides the emulationVersion of the feature gate, and
	// overrides the minCompatibilityVersion to 1 minor before emulationVersion.`
	// Otherwise, the emulationVersion will be the same as the binary version.
	// If set, the feature defaults and availability will be as if the binary is at the emulated version.
	SetEmulationVersion(emulationVersion *version.Version) error
	// SetEmulationVersion overrides the emulationVersion and minCompatibilityVersion of the feature gate.
	SetEmulationVersionAndMinCompatibilityVersion(emulationVersion *version.Version, minCompatibilityVersion *version.Version) error
	// GetAll returns a copy of the map of known feature names to versioned feature specs.
	GetAllVersioned() map[Feature]VersionedSpecs
	// AddVersioned adds versioned feature specs to the featureGate.
	AddVersioned(features map[Feature]VersionedSpecs) error
	// AddDependencies marks features that depend on other features. Must be called after all
	// referenced features have already been added (dependents & depnedencies). Cycles are forbidden.
	AddDependencies(features map[Feature][]Feature) error
	// OverrideDefaultAtVersion sets a local override for the registered default value of a named
	// feature for the prerelease lifecycle the given version is at.
	// If the feature has not been previously registered (e.g. by a call to Add),
	// has a locked default, or if the gate has already registered itself with a FlagSet, a non-nil
	// error is returned.
	//
	// When two or more components consume a common feature, one component can override its
	// default at runtime in order to adopt new defaults before or after the other
	// components. For example, a new feature can be evaluated with a limited blast radius by
	// overriding its default to true for a limited number of components without simultaneously
	// changing its default for all consuming components.
	OverrideDefaultAtVersion(name Feature, override bool, ver *version.Version) error
	// ExplicitlySet returns true if the feature value is explicitly set instead of
	// being derived from the default values or special features.
	ExplicitlySet(name Feature) bool
	// ResetFeatureValueToDefault resets the value of the feature back to the default value.
	ResetFeatureValueToDefault(name Feature) error
	// DeepCopyAndReset copies all the registered features of the FeatureGate object, with all the known features and overrides,
	// and resets all the enabled status of the new feature gate.
	// This is useful for creating a new instance of feature gate without inheriting all the enabled configurations of the base feature gate.
	DeepCopyAndReset() MutableVersionedFeatureGate
}

type PromotionVersionMapping map[prerelease]string

type VersionedSpecs []FeatureSpec