feature

README

Feature Library

The feature library is a Go library to provide feature flagging capabilities to Go programs. It is common in Go programs to introduce new functionality or performance improvements. But, it is also a common problem that changes to code can potentially have unintended consequences or bugs that will sometimes reach customers. In order to control the functionality of the code at runtime, some form of feature flag is used. In its most basic form, a feature flag might just be some configuration option in the server configuration or an environment variable that is set on the deployment.

In some circumstances, more fine-controlled or responsive feature flagging is required. This library is intended to provide this more fine-controlled and responsive feature flagging.

Flags

A Flag is a definition of a feature flag. It is represented by a human-readable name, a description of the flag, the programmatic key, and a default value. It also contains metadata for whether the flag is intended to be exposed to an end-user, the expected lifetime of the flag (temporary or permanent), and a contact for the person, team, or other entity that added the feature flag.

These flags can be represented in YAML form as the following:

- name: My Feature
  description: My feature is awesome
  key: myFeature
  default: false
  expose: true
  contact: My Name
  lifetime: temporary

The flag type is inferred from the default value. In this case, the default value is a boolean so this is a boolean flag. The feature command can be used to process the above YAML and to generate the code for a list of feature flags.

$ mkdir feature/
$ feature -in flags.yml -out feature/feature.go

From our backend code, we can check the feature flag by importing the package for the generated code and using the following code:

if feature.MyFeature.Enabled(ctx) {
  // new code...
} else {
  // new code...
}

To toggle the flag from the default value, the Flagger is used.

Flagger

The Flagger is the component that checks the value for a feature flag. This interface will be implemented by the specific application depending on how it wants to expose feature flags. A Flagger backend can be static or dynamic depending on the underlying implementation.

Documentation

Overview

Package feature provides feature flagging capabilities for a Go application.

Flags are defined using the `MakeXXXFlag` functions. These can either be defined in code or generated using the feature generator included in this module.

Flags are configured in `flags.yml` at the top of this repository. Running `make flags` generates Go code based on this configuration to programmatically test flag values in a given request context. Boolean flags are the most common case, but integers, floats and strings are supported for more complicated experiments.

The `Flagger` interface is the crux of this package. It computes a map of feature flag values for a given request context. The implementation is application dependent. The result can be attached to the context using `Annotate` and then the results will be used when checking feature flags.

Flags can be checked using the context after it has been annotated. For example, to check a boolean flag that was generated by the `feature` command, you might do it this way:

if feature.MyFeature().Enabled(ctx) {
    // my feature is enabled
} else {
    // my feature is disabled
}

Index

• func Inject(ctx context.Context, flagger Flagger) context.Context
• func SetMetrics(m Metrics)
• type Base
  • func MakeBase(name, key, owner string, defaultValue interface{}) Base
  • func (f Base) Default() interface{}
  • func (f Base) Key() string
• type BoolFlag
  • func MakeBoolFlag(name, key, owner string, defaultValue bool) BoolFlag
  • func (f BoolFlag) Enabled(ctx context.Context) (v bool)
• type Flag
  • func MakeFlag(name, key, owner string, defaultValue interface{}) Flag
• type Flagger
  • func GetFlagger(ctx context.Context) Flagger
• type FloatFlag
  • func MakeFloatFlag(name, key, owner string, defaultValue float64) FloatFlag
  • func (f FloatFlag) Float(ctx context.Context) (v float64)
• type IntFlag
  • func MakeIntFlag(name, key, owner string, defaultValue int) IntFlag
  • func (f IntFlag) Int(ctx context.Context) (v int)
• type Metrics
• type StringFlag
  • func MakeStringFlag(name, key, owner string, defaultValue string) StringFlag
  • func (f StringFlag) String(ctx context.Context) (v string)

Functions

func Inject

func Inject(ctx context.Context, flagger Flagger) context.Context

Inject will inject the Flagger into the context.

func SetMetrics

func SetMetrics(m Metrics)

SetMetrics sets the metric store for feature flags.

Types

type Base

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

Base implements the base of the Flag type.

func MakeBase

func MakeBase(name, key, owner string, defaultValue interface{}) Base

MakeBase constructs a flag.

func (Base) Default

func (f Base) Default() interface{}

Default returns the type-agnostic zero value for the flag.

func (Base) Key

func (f Base) Key() string

Key returns the programmatic backend identifier for the flag.

type BoolFlag

type BoolFlag struct {
	Base
	// contains filtered or unexported fields
}

BoolFlag implements Flag for boolean values.

func MakeBoolFlag

func MakeBoolFlag(name, key, owner string, defaultValue bool) BoolFlag

MakeBoolFlag returns a string flag with the given Base and default.

func (BoolFlag) Enabled

func (f BoolFlag) Enabled(ctx context.Context) (v bool)

Enabled indicates whether flag is true or false on the request context.

type Flag

type Flag interface {
	// Key returns the programmatic backend identifier for the flag.
	Key() string
	// Default returns the type-agnostic zero value for the flag.
	// Type-specific flag implementations may expose a typed default
	// (e.g. BoolFlag includes a boolean Default field).
	Default() interface{}
}

Flag represents a generic feature flag with a key and a default.

func MakeFlag

func MakeFlag(name, key, owner string, defaultValue interface{}) Flag

MakeFlag constructs a Flag. The concrete implementation is inferred from the provided default.

type Flagger

type Flagger interface {
	// FlagValue returns the value for a given flag.
	FlagValue(ctx context.Context, flag Flag) interface{}
}

Flagger returns flag values.

func GetFlagger

func GetFlagger(ctx context.Context) Flagger

GetFlagger returns the Flagger for this context or the default flagger.

type FloatFlag

type FloatFlag struct {
	Base
	// contains filtered or unexported fields
}

FloatFlag implements Flag for float values.

func MakeFloatFlag

func MakeFloatFlag(name, key, owner string, defaultValue float64) FloatFlag

MakeFloatFlag returns a string flag with the given Base and default.

func (FloatFlag) Float

func (f FloatFlag) Float(ctx context.Context) (v float64)

Float value of the flag on the request context.

type IntFlag

type IntFlag struct {
	Base
	// contains filtered or unexported fields
}

IntFlag implements Flag for integer values.

func MakeIntFlag

func MakeIntFlag(name, key, owner string, defaultValue int) IntFlag

MakeIntFlag returns a string flag with the given Base and default.

func (IntFlag) Int

func (f IntFlag) Int(ctx context.Context) (v int)

Int value of the flag on the request context.

type Metrics

type Metrics interface {
	Inc(key string, value interface{})
}

type StringFlag

type StringFlag struct {
	Base
	// contains filtered or unexported fields
}

StringFlag implements Flag for string values.

func MakeStringFlag

func MakeStringFlag(name, key, owner string, defaultValue string) StringFlag

MakeStringFlag returns a string flag with the given Base and default.

func (StringFlag) String

func (f StringFlag) String(ctx context.Context) (v string)

String value of the flag on the request context.