feature

Documentation

Overview

Package feature provides feature flagging capabilities for InfluxDB servers. This document describes this package and how it is used to control experimental features in `influxd`.

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 default implementation always returns the flag default configured in `flags.yml`. The override implementation allows an operator to override feature flag defaults at startup. Changing these overrides requires a restart.

In `influxd`, a `Flagger` instance is provided to a `Handler` middleware configured to intercept all API requests and annotate their request context with a map of feature flags.

A flag can opt in to be exposed externally in `flags.yml`. If exposed, this flag will be included in the response from the `/api/v2/flags` endpoint. This allows the UI and other API clients to control their behavior according to the flag in addition to the server itself.

A concrete example to illustrate the above:

I have a feature called "My Feature" that will involve turning on new code in both the UI and the server.

First, I add an entry to `flags.yml`.

```yaml

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

```

My flag type is inferred to be boolean by my default of `false` when I run `make flags` and the `feature` package now includes `func MyFeature() BoolFlag`.

I use this to control my backend code with

```go

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

  // new code...
}

```

and the `/api/v2/flags` response provides the same information to the frontend.

```json

{
  "myFeature": false
}

```

While `false` by default, I can turn on my experimental feature by starting my server with a flag override.

``` env INFLUXD_FEATURE_FLAGS="{\"flag1\":\value1\",\"key2\":\"value2\"}" influxd ```

``` influxd --feature-flags flag1=value1,flag2=value2 ```

Index

• func Annotate(ctx context.Context, f Flagger, flags ...Flag) (context.Context, error)
• func ExposedFlagsFromContext(ctx context.Context, byKey ByKeyFn) map[string]interface{}
• func FlagsFromContext(ctx context.Context) map[string]interface{}
• func NewFlagsHandler(errorHandler influxdb.HTTPErrorHandler, byKey ByKeyFn) http.Handler
• func NewHandler(log *zap.Logger, flagger Flagger, flags []Flag, next http.Handler) http.Handler
• type Base
  • func MakeBase(name, key, owner string, defaultValue interface{}, lifetime Lifetime, ...) Base
  • func (f Base) Default() interface{}
  • func (f Base) Expose() bool
  • func (f Base) Key() string
• type BoolFlag
  • func AppMetrics() BoolFlag
  • func BackendExample() BoolFlag
  • func CommunityTemplates() BoolFlag
  • func GroupWindowAggregateTranspose() BoolFlag
  • func MakeBoolFlag(name, key, owner string, defaultValue bool, lifetime Lifetime, expose bool) BoolFlag
  • func MemoryOptimizedFill() BoolFlag
  • func NewAuthPackage() BoolFlag
  • func NewHydrateVarsFunctionality() BoolFlag
  • func NewLabelPackage() BoolFlag
  • func PushDownGroupAggregateCount() BoolFlag
  • func PushDownGroupAggregateFirst() BoolFlag
  • func PushDownGroupAggregateLast() BoolFlag
  • func PushDownGroupAggregateSum() BoolFlag
  • func PushDownWindowAggregateCount() BoolFlag
  • func PushDownWindowAggregateFirst() BoolFlag
  • func PushDownWindowAggregateLast() BoolFlag
  • func PushDownWindowAggregateMax() BoolFlag
  • func PushDownWindowAggregateMean() BoolFlag
  • func PushDownWindowAggregateMin() BoolFlag
  • func PushDownWindowAggregateSum() BoolFlag
  • func SimpleTaskOptionsExtraction() BoolFlag
  • func UrmFreeTasks() BoolFlag
  • func (f BoolFlag) Enabled(ctx context.Context, flagger ...Flagger) bool
• type ByKeyFn
• type Flag
  • func ByKey(k string) (Flag, bool)
  • func Flags() []Flag
  • func MakeFlag(name, key, owner string, defaultValue interface{}, lifetime Lifetime, ...) Flag
• type Flagger
  • func DefaultFlagger() Flagger
• type FloatFlag
  • func MakeFloatFlag(name, key, owner string, defaultValue float64, lifetime Lifetime, expose bool) FloatFlag
  • func (f FloatFlag) Float(ctx context.Context, flagger ...Flagger) float64
• type HTTPProxy
  • func NewHTTPProxy(dest *url.URL, logger *zap.Logger, enabler ProxyEnabler) *HTTPProxy
  • func (p *HTTPProxy) Do(w http.ResponseWriter, r *http.Request) bool
• type Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type IntFlag
  • func FrontendExample() IntFlag
  • func MakeIntFlag(name, key, owner string, defaultValue int32, lifetime Lifetime, expose bool) IntFlag
  • func (f IntFlag) Int(ctx context.Context, flagger ...Flagger) int32
• type Lifetime
  • func (l *Lifetime) UnmarshalYAML(unmarshal func(interface{}) error) error
• type ProxyEnabler
• type StringFlag
  • func MakeStringFlag(name, key, owner string, defaultValue string, lifetime Lifetime, expose bool) StringFlag
  • func (f StringFlag) String(ctx context.Context, flagger ...Flagger) string

Functions

func Annotate

func Annotate(ctx context.Context, f Flagger, flags ...Flag) (context.Context, error)

Annotate the context with a map computed of computed flags.

func ExposedFlagsFromContext

func ExposedFlagsFromContext(ctx context.Context, byKey ByKeyFn) map[string]interface{}

ExposedFlagsFromContext returns the filtered map of exposed flags attached to the context by Annotate, or nil if none is found.

func FlagsFromContext

func FlagsFromContext(ctx context.Context) map[string]interface{}

FlagsFromContext returns the map of flags attached to the context by Annotate, or nil if none is found.

func NewFlagsHandler

func NewFlagsHandler(errorHandler influxdb.HTTPErrorHandler, byKey ByKeyFn) http.Handler

NewFlagsHandler returns a handler that returns the map of computed feature flags on the request context.

func NewHandler

func NewHandler(log *zap.Logger, flagger Flagger, flags []Flag, next http.Handler) http.Handler

NewHandler returns a configured feature flag middleware that will annotate request context with a computed map of the given flags using the provided Flagger.

Types

type Base

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

flag base type.

func MakeBase

func MakeBase(name, key, owner string, defaultValue interface{}, lifetime Lifetime, expose bool) Base

MakeBase constructs a flag flag.

func (Base) Default

func (f Base) Default() interface{}

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

func (Base) Expose

func (f Base) Expose() bool

Expose 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 AppMetrics

func AppMetrics() BoolFlag

AppMetrics - Send UI Telementry to Tools cluster - should always be false in OSS

func BackendExample

func BackendExample() BoolFlag

BackendExample - A permanent backend example boolean flag

func CommunityTemplates

func CommunityTemplates() BoolFlag

CommunityTemplates - Replace current template uploading functionality with community driven templates

func GroupWindowAggregateTranspose

func GroupWindowAggregateTranspose() BoolFlag

GroupWindowAggregateTranspose - Enables the GroupWindowAggregateTransposeRule for all enabled window aggregates

func MakeBoolFlag

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

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

func MemoryOptimizedFill

func MemoryOptimizedFill() BoolFlag

MemoryOptimizedFill - Enable the memory optimized fill()

func NewAuthPackage

func NewAuthPackage() BoolFlag

NewAuthPackage - Enables the refactored authorization api

func NewHydrateVarsFunctionality

func NewHydrateVarsFunctionality() BoolFlag

NewHydrateVarsFunctionality - Enables a minimalistic variable hydration

func NewLabelPackage

func NewLabelPackage() BoolFlag

NewLabelPackage - Enables the refactored labels api

func PushDownGroupAggregateCount

func PushDownGroupAggregateCount() BoolFlag

PushDownGroupAggregateCount - Enable the count variant of PushDownGroupAggregate planner rule

func PushDownGroupAggregateFirst

func PushDownGroupAggregateFirst() BoolFlag

PushDownGroupAggregateFirst - Enable the first variant of PushDownGroupAggregate planner rule

func PushDownGroupAggregateLast

func PushDownGroupAggregateLast() BoolFlag

PushDownGroupAggregateLast - Enable the last variant of PushDownGroupAggregate planner rule

func PushDownGroupAggregateSum

func PushDownGroupAggregateSum() BoolFlag

PushDownGroupAggregateSum - Enable the sum variant of PushDownGroupAggregate planner rule

func PushDownWindowAggregateCount

func PushDownWindowAggregateCount() BoolFlag

PushDownWindowAggregateCount - Enable Count variant of PushDownWindowAggregateRule and PushDownBareAggregateRule

func PushDownWindowAggregateFirst

func PushDownWindowAggregateFirst() BoolFlag

PushDownWindowAggregateFirst - Enable First variant of PushDownWindowAggregateRule and PushDownBareAggregateRule

func PushDownWindowAggregateLast

func PushDownWindowAggregateLast() BoolFlag

PushDownWindowAggregateLast - Enable Last variant of PushDownWindowAggregateRule and PushDownBareAggregateRule

func PushDownWindowAggregateMax

func PushDownWindowAggregateMax() BoolFlag

PushDownWindowAggregateMax - Enable Max variant of PushDownWindowAggregateRule and PushDownBareAggregateRule

func PushDownWindowAggregateMean

func PushDownWindowAggregateMean() BoolFlag

PushDownWindowAggregateMean - Enable Mean variant of PushDownWindowAggregateRule and PushDownBareAggregateRule

func PushDownWindowAggregateMin

func PushDownWindowAggregateMin() BoolFlag

PushDownWindowAggregateMin - Enable Min variant of PushDownWindowAggregateRule and PushDownBareAggregateRule

func PushDownWindowAggregateSum

func PushDownWindowAggregateSum() BoolFlag

PushDownWindowAggregateSum - Enable Sum variant of PushDownWindowAggregateRule and PushDownBareAggregateRule

func SimpleTaskOptionsExtraction

func SimpleTaskOptionsExtraction() BoolFlag

SimpleTaskOptionsExtraction - Simplified task options extraction to avoid undefined functions when saving tasks

func UrmFreeTasks

func UrmFreeTasks() BoolFlag

UrmFreeTasks - allow task system to operate without creating additional urms

func (BoolFlag) Enabled

func (f BoolFlag) Enabled(ctx context.Context, flagger ...Flagger) bool

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

type ByKeyFn

type ByKeyFn func(string) (Flag, bool)

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{}
	// Expose the flag.
	Expose() bool
}

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

func ByKey

func ByKey(k string) (Flag, bool)

ByKey returns the Flag corresponding to the given key.

func Flags

func Flags() []Flag

Flags returns all feature flags.

func MakeFlag

func MakeFlag(name, key, owner string, defaultValue interface{}, lifetime Lifetime, expose bool) Flag

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

type Flagger

type Flagger interface {
	// Flags returns a map of flag keys to flag values.
	//
	// If an authorization is present on the context, it may be used to compute flag
	// values according to the affiliated user ID and its organization and other mappings.
	// Otherwise, they should be computed generally or return a default.
	//
	// One or more flags may be provided to restrict the results.
	// Otherwise, all flags should be computed.
	Flags(context.Context, ...Flag) (map[string]interface{}, error)
}

Flagger returns flag values.

func DefaultFlagger

func DefaultFlagger() Flagger

DefaultFlagger returns a flagger that always returns default values.

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, lifetime Lifetime, expose bool) FloatFlag

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

func (FloatFlag) Float

func (f FloatFlag) Float(ctx context.Context, flagger ...Flagger) float64

Float value of the flag on the request context.

type HTTPProxy

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

HTTPProxy is an HTTP proxy that's guided by a feature flag. If the feature flag presented to it is enabled, it will perform the proxying behavior. Otherwise it will be a no-op.

func NewHTTPProxy

func NewHTTPProxy(dest *url.URL, logger *zap.Logger, enabler ProxyEnabler) *HTTPProxy

NewHTTPProxy returns a new Proxy.

func (*HTTPProxy) Do

func (p *HTTPProxy) Do(w http.ResponseWriter, r *http.Request) bool

Do performs the proxying. It returns whether or not the request was proxied.

type Handler

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

Handler is a middleware that annotates the context with a map of computed feature flags. To accurately compute identity-scoped flags, this middleware should be executed after any authorization middleware has annotated the request context with an authorizer.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP annotates the request context with a map of computed feature flags before continuing to serve the request.

type IntFlag

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

IntFlag implements Flag for integer values.

func FrontendExample

func FrontendExample() IntFlag

FrontendExample - A temporary frontend example integer flag

func MakeIntFlag

func MakeIntFlag(name, key, owner string, defaultValue int32, lifetime Lifetime, expose bool) IntFlag

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

func (IntFlag) Int

func (f IntFlag) Int(ctx context.Context, flagger ...Flagger) int32

Int value of the flag on the request context.

type Lifetime

type Lifetime int

Lifetime represents the intended lifetime of the feature flag.

The zero value is Temporary, the most common case, but Permanent is included to mark special cases where a flag is not intended to be removed, e.g. enabling debug tracing for an organization.

TODO(gavincabbage): This may become a stale date, which can then

be used to trigger a notification to the contact when the flag
has become stale, to encourage flag cleanup.

const (
	// Temporary indicates a flag is intended to be removed after a feature is no longer in development.
	Temporary Lifetime = iota
	// Permanent indicates a flag is not intended to be removed.
	Permanent
)

func (*Lifetime) UnmarshalYAML

func (l *Lifetime) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler and interprets a case-insensitive text representation as a lifetime constant.

type ProxyEnabler

type ProxyEnabler interface {
	Key() string
	Enabled(ctx context.Context, fs ...Flagger) bool
}

ProxyEnabler is a boolean feature flag.

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, lifetime Lifetime, expose bool) StringFlag

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

func (StringFlag) String

func (f StringFlag) String(ctx context.Context, flagger ...Flagger) string

String value of the flag on the request context.