feature

package
v0.3.26 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2024 License: Apache-2.0 Imports: 29 Imported by: 0

README

Feature Tree

Feature flags are stored as n-ary trees, with each non-root node having a rule and an optional default value. The root node has no rule, and has a non-optional default value.

Feature evaluation traverses the n-ary in depth-first search fashion, starting at the root, and ending as soon as a leaf node evaluates to true or there are no further paths to traverse. The algorithm returns the last non-null value it visited.

Feature Name: illustration
Description: Complex feature tree to illustrate node paths


                                            *Root*
                                            Path: []
                                            Value: 12
                                            /   |   \
                           -----------------    |    -------------------
                          /                     |                        \
                    Rule: a == 1            Rule: a > 10             Rule: a > 5
                    Path: [0]               Path: [1]                Path: [2]
                    Value: 38               Value: NULL              Value: 23
                        /                       |
             -----------                        |
            /                                   |
    Rule: x IN ["a", "b"]                   Rule: x == "c"
    Path: [0,0]                             Path: [1,0]
    Value: 108                              Value: 21
   

*** Tests ***

Context: {}
Value: 12
Path: []

Context: {"a": 1}
Value: 38
Path: [0]

Context: {"a": 11}
Value: 12
Path: []

Context: {"a": 11, "x": "c"}
Value: 21
Path: [1,0]

Context: {"a": 8}
Value: 23
Path: [2]

Context: {"a": 8}
Value: 108
Path: [0,0]

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrDeprecatedVersion error = errors.New("namespace version is deprecated, please upgrade")
	ErrUnknownVersion    error = errors.New("namespace version is unknown")
)
View Source 
var ErrTypeMismatch = fmt.Errorf("type mismatch")

Functions

func AnyToVal 

func AnyToVal(a *anypb.Any, fType eval.ConfigType, registry *protoregistry.Types) (interface{}, error)

Translates the pb any object to a go-native object based on the given type. Also takes an optional protbuf type registry, in case the value depends on a user-defined protobuf type.

func ComplianceCheck 

func ComplianceCheck(f FeatureFile, nsMD *metadata.NamespaceConfigRepoMetadata) error

func ParseFeaturePath 

func ParseFeaturePath(featurePath string) (namespaceName string, featureName string, err error)

func ProtoToJSON 

func ProtoToJSON(fProto *featurev1beta1.Feature, registry *protoregistry.Types) ([]byte, error)

func SuggestGroupedNames added in v0.3.9 

func SuggestGroupedNames(configs ...*Feature) []string

Automagically suggest names for a grouped config based on the inputs Should return options from highest to lowest confidence Lowest confidence item will be a simple concatenation of names TODO: take options like max len, call an API endpoint, etc.

func ValToAny 

func ValToAny(value interface{}, ft eval.ConfigType) (*anypb.Any, error)

Takes a go value and an associated type, and converts the value to a language-agnostic protobuf any type.

Types

type CallableUnitTest added in v0.2.23 

type CallableUnitTest struct {
	Context     map[string]interface{}
	Registry    *protoregistry.Types
	TestFunc    starlark.Callable
	ContextStar string
	FeatureType eval.ConfigType
}

CallableUnitTest is a unit test that calls a function on the value of the evaluated feature

func NewCallableUnitTest added in v0.2.23 

func NewCallableUnitTest(ctx map[string]interface{}, r *protoregistry.Types, testFn starlark.Callable, ctxStar string, ft eval.ConfigType) *CallableUnitTest

func (*CallableUnitTest) Run added in v0.2.23 

func (c *CallableUnitTest) Run(idx int, eval eval.EvaluableConfig) *TestResult

type CompiledFeature 

type CompiledFeature struct {
	Feature          *Feature
	TestResults      []*TestResult
	ValidatorResults []*ValidatorResult
}

Contains the compiled feature model, along with any validator results and unit test results that were collected as part of compilation.

type Feature 

type Feature struct {
	Key, Description string
	Value            interface{}
	FeatureType      eval.ConfigType
	Namespace        string
	Metadata         map[string]any

	Overrides []*Override
	UnitTests []UnitTest
}

func FromProto 

func FromProto(fProto *featurev1beta1.Feature, registry *protoregistry.Types) (*Feature, error)

Converts a feature from its protobuf representation into a go-native representation. Takes an optional proto registry in case we require user-defined types in order to parse the feature.

func NewBoolFeature 

func NewBoolFeature(value bool) *Feature

func NewEncodedJSONFeature 

func NewEncodedJSONFeature(encodedJSON []byte) (*Feature, error)

func NewFloatFeature 

func NewFloatFeature(value float64) *Feature

func NewIntFeature 

func NewIntFeature(value int64) *Feature

func NewJSONFeature 

func NewJSONFeature(value *structpb.Value) *Feature

func NewProtoFeature added in v0.2.6 

func NewProtoFeature(value protoreflect.ProtoMessage) *Feature

func NewStringFeature 

func NewStringFeature(value string) *Feature

func (*Feature) AddBoolOverride added in v0.3.0 

func (f *Feature) AddBoolOverride(rule string, astNew *rulesv1beta3.Rule, val bool) error

func (*Feature) AddFloatOverride added in v0.3.0 

func (f *Feature) AddFloatOverride(rule string, astNew *rulesv1beta3.Rule, val float64) error

func (*Feature) AddIntOverride added in v0.3.0 

func (f *Feature) AddIntOverride(rule string, astNew *rulesv1beta3.Rule, val int64) error

func (*Feature) AddJSONOverride added in v0.3.0 

func (f *Feature) AddJSONOverride(rule string, astNew *rulesv1beta3.Rule, val *structpb.Value) error

func (*Feature) AddJSONUnitTest 

func (f *Feature) AddJSONUnitTest(context map[string]interface{}, val *structpb.Value, starCtx, starVal string) error

func (*Feature) AddStringOverride added in v0.3.0 

func (f *Feature) AddStringOverride(rule string, astNew *rulesv1beta3.Rule, val string) error

func (*Feature) PrintJSON 

func (f *Feature) PrintJSON(registry *protoregistry.Types)

func (*Feature) RunUnitTests 

func (f *Feature) RunUnitTests() ([]*TestResult, error)

func (*Feature) ToEvaluableConfig added in v0.3.2 

func (f *Feature) ToEvaluableConfig() (eval.EvaluableConfig, error)

func (*Feature) ToJSON 

func (f *Feature) ToJSON(registry *protoregistry.Types) ([]byte, error)

func (*Feature) ToProto 

func (f *Feature) ToProto() (*featurev1beta1.Feature, error)

type FeatureContents 

type FeatureContents struct {
	File *FeatureFile

	Star  []byte
	JSON  []byte
	Proto []byte
	SHA   string
}

type FeatureFile 

type FeatureFile struct {
	Name string
	// Filename of the featureName.star file.
	StarlarkFileName string
	// Filename of an featureName.proto file.
	// This is optional.
	ProtoFileName string
	// Filename of a compiled .json file.
	CompiledJSONFileName string
	// Filename of a compiled .proto.bin file.
	CompiledProtoBinFileName string
	// name of the namespace directory
	NamespaceName string
}

FeatureFile is a parsed feature from an on desk representation. This is intended to remain stable across feature versions.

func GroupFeatureFiles 

func GroupFeatureFiles(
	ctx context.Context,
	pathToNamespace string,
	fsProvider fs.Provider,
) ([]FeatureFile, error)

This groups feature files in a way that is governed by the namespace metadata. TODO naming conventions.

func NewFeatureFile 

func NewFeatureFile(nsName, featureName string) FeatureFile

func (FeatureFile) RootPath 

func (ff FeatureFile) RootPath(filename string) string

func (FeatureFile) Verify 

func (ff FeatureFile) Verify() error

type NamespaceVersion added in v0.2.8 

type NamespaceVersion string
const (
	NamespaceVersionV1Beta1 NamespaceVersion = "v1beta1"
	NamespaceVersionV1Beta2 NamespaceVersion = "v1beta2"
	NamespaceVersionV1Beta3 NamespaceVersion = "v1beta3"
	// Supports generating n-ary rules AST
	NamespaceVersionV1Beta4 NamespaceVersion = "v1beta4"
	// Supports != operator
	NamespaceVersionV1Beta5 NamespaceVersion = "v1beta5"
	// Supports using "overrides" instead of "rules" and "export(Config(...))" instead of "result = feature(...)" (dual support)
	NamespaceVersionV1Beta6 NamespaceVersion = "v1beta6"
	// Supports `metadata` field
	NamespaceVersionV1Beta7 NamespaceVersion = "v1beta7"
)

func AllNamespaceVersions added in v0.2.8 

func AllNamespaceVersions() []NamespaceVersion

Returns all namespace versions in the order that they were released

func LatestNamespaceVersion added in v0.2.8 

func LatestNamespaceVersion() NamespaceVersion

Returns the latest namespace version.

func NewNamespaceVersion added in v0.2.8 

func NewNamespaceVersion(v string) NamespaceVersion

func SupportedNamespaceVersions added in v0.2.8 

func SupportedNamespaceVersions() []NamespaceVersion

Returns the list of namespace versions that are supported.

func (NamespaceVersion) Before added in v0.2.8 

func (nv NamespaceVersion) Before(cmp NamespaceVersion) bool

func (NamespaceVersion) IsLatest added in v0.2.8 

func (nv NamespaceVersion) IsLatest() bool

func (NamespaceVersion) String added in v0.2.8 

func (nv NamespaceVersion) String() string

func (NamespaceVersion) Supported added in v0.2.8 

func (nv NamespaceVersion) Supported() error

type Override added in v0.3.0 

type Override struct {
	Rule      string // source of truth
	RuleASTV3 *rulesv1beta3.Rule
	Value     interface{}
}

type ProtoDefBuilder added in v0.3.9 

type ProtoDefBuilder struct {
	// contains filtered or unexported fields
}

Builder for a protobuf message definition string

func NewProtoDefBuilder added in v0.3.9 

func NewProtoDefBuilder(name string) *ProtoDefBuilder

func (*ProtoDefBuilder) AddEnum added in v0.3.10 

func (b *ProtoDefBuilder) AddEnum(enumDefStr string)

Use ProtoEnumDefBuilder to get the enum definition string

func (*ProtoDefBuilder) AddField added in v0.3.9 

func (b *ProtoDefBuilder) AddField(name string, typeName string, comment string) string

func (*ProtoDefBuilder) Build added in v0.3.9 

func (b *ProtoDefBuilder) Build() string

func (*ProtoDefBuilder) ToProtoTypeName added in v0.3.9 

func (b *ProtoDefBuilder) ToProtoTypeName(ct eval.ConfigType) (string, error)

Convert config type to applicable proto type name Returns error if type is not supported

type ProtoEnumDefBuilder added in v0.3.10 

type ProtoEnumDefBuilder struct {
	// contains filtered or unexported fields
}

Builder for a protobuf enum definition string

func NewProtoEnumDefBuilder added in v0.3.10 

func NewProtoEnumDefBuilder(name string) *ProtoEnumDefBuilder

func (*ProtoEnumDefBuilder) AddValue added in v0.3.10 

func (b *ProtoEnumDefBuilder) AddValue(value string) string

Returns the canonical translated enum field name

func (*ProtoEnumDefBuilder) Build added in v0.3.10 

func (b *ProtoEnumDefBuilder) Build() string

type TestResult 

type TestResult struct {
	Test      string // a string representation of the test, as written in starlark
	TestIndex int    // The index of the test in the list of tests.
	Error     error  // human-readable error
}

This struct holds information about a test run.

func NewTestResult 

func NewTestResult(testStar string, testIndex int) *TestResult

func (*TestResult) DebugString 

func (tr *TestResult) DebugString() string

func (*TestResult) Identifier 

func (tr *TestResult) Identifier() string

Creates a short string - a human-readable version of this unit test that is helpful for debugging and printing errors. e.g. 'test 1 ["{"org"...]' idx refers to the index of the unit test in the list of unit tests written in starlark.

func (*TestResult) Passed 

func (tr *TestResult) Passed() bool

func (*TestResult) WithError 

func (tr *TestResult) WithError(err error) *TestResult

type UnitTest 

type UnitTest interface {
	// Run runs the unit test
	Run(idx int, eval eval.EvaluableConfig) *TestResult
}

type ValidatorResult 

type ValidatorResult struct {
	// Indicates whether this validator result applies on a rule value, the default value, or a test value.
	Type ValidatorResultType
	// If this is a rule value validator result, specifies the index of the rule that this result applies to.
	// If this is a test value validator result, specifies the index of the unit test that this result applies to.
	Index int
	// A string representation of the starlark value that was invalid
	Value string
	Error error // human-readable error describing what the validation error was
}

Holds the results of validation checks performed on the compiled feature. Since a validation check is done on a single final feature value, There will be 1 validator result for the default value and 1 for each subsequent rule.

func NewValidatorResult 

func NewValidatorResult(t ValidatorResultType, index int, starVal string) *ValidatorResult

func (*ValidatorResult) DebugString 

func (vr *ValidatorResult) DebugString() string

func (*ValidatorResult) Identifier 

func (vr *ValidatorResult) Identifier() string

func (*ValidatorResult) Passed 

func (vr *ValidatorResult) Passed() bool

func (*ValidatorResult) WithError 

func (vr *ValidatorResult) WithError(err error) *ValidatorResult

type ValidatorResultType 

type ValidatorResultType int
const (
	ValidatorResultTypeDefault ValidatorResultType = iota
	ValidatorResultTypeOverride
	ValidatorResultTypeTest
)

type ValueUnitTest added in v0.2.23 

type ValueUnitTest struct {
	Context       map[string]interface{}
	ExpectedValue interface{}
	// The starlark textual representation of the context and expected value.
	// These fields are helpful for print statements.
	ContextStar, ExpectedValueStar string
}

ValueUnitTest is a unit test that does an equality check

func NewValueUnitTest added in v0.2.23 

func NewValueUnitTest(context map[string]interface{}, val interface{}, starCtx, starVal string) *ValueUnitTest

func (ValueUnitTest) Run added in v0.2.23 

func (ut ValueUnitTest) Run(idx int, eval eval.EvaluableConfig) *TestResult

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.