featureguards

README

Go SDK for FeatureGuards

The official FeatureGuards Go client library.

Installation

Make sure your project is using Go Modules (it will have a go.mod file in its root if it already is):

go mod init

Then, reference featureguards-go/v2 in a Go program with import:

import (
	featureguards "github.com/featureguards/featureguards-go/v2"
)

Run any of the normal go commands (build/install/test). The Go toolchain will resolve and fetch the featureguards-go module automatically.

Alternatively, you can also explicitly go get the package into a project:

go get -u github.com/featureguards/featureguards-go/v2

Documentation

For details on all the functionality in this library, see the Go documentation.

Below are a few simple examples:

IsOn

// Create the client once.
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// The only require parameter is the API Key. Other options are available. See [goref].
ft := featureguards.New(ctx, featureguards.WithApiKey("API_KEY"), featureguards.WithDefaults(map[string]bool{"TEST": true}))

// Call IsOn multiple times.
on, err := ft.IsOn("TEST")

IsOn with attributes

// Create the client once.
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// The only require parameter is the API Key. Other options are available. See [goref].
ft := featureguards.New(ctx, featureguards.WithApiKey("API_KEY"), featureguards.WithDefaults(map[string]bool{"TEST": true}))

// Call IsOn multiple times.
on, _ := ft.IsOn("FOO", featureguards.WithAttributes(
	featureguards.Attributes{}.Int64("user_id", 123).String("company_slug", "acme")))

Documentation

Overview

package provides APIs for feature flags.

Index

• Variables
• type Attributes
  • func (a Attributes) Bool(name string, v bool) Attributes
  • func (a Attributes) Float(name string, n float32) Attributes
  • func (a Attributes) Int(name string, n int) Attributes
  • func (a Attributes) Int64(name string, n int64) Attributes
  • func (a Attributes) String(name string, v string) Attributes
  • func (a Attributes) Time(name string, t time.Time) Attributes
• type FeatureGuards
  • func New(ctx context.Context, options ...Options) *FeatureGuards
  • func (r *FeatureGuards) IsOn(name string, options ...FeatureToggleOptions) (bool, error)
• type FeatureToggleOptions
  • func WithAttributes(a Attributes) FeatureToggleOptions
• type LogLevel
• type Options
  • func WithApiKey(key string) Options
  • func WithDefaults(v map[string]bool) Options
  • func WithDialOptions(options ...grpc.DialOption) Options
  • func WithDynamicSettings(v *dynamic_settings.DynamicSettings) Options

Examples

• FeatureGuards.IsOn
• FeatureGuards.IsOn (Attributes)

Variables

var (
	ErrNoFeatureToggles error = errors.New("can't connect to feature guards")
)

Types

type Attributes

type Attributes map[string]interface{}

Attributes is a dictionary of keys that will be used for evaluation to values.

func (Attributes) Bool

func (a Attributes) Bool(name string, v bool) Attributes

Bool adds a new boolean attribute.

func (Attributes) Float

func (a Attributes) Float(name string, n float32) Attributes

Float adds a new float32 attribute.

func (Attributes) Int

func (a Attributes) Int(name string, n int) Attributes

Int adds a new int attribute.

func (Attributes) Int64

func (a Attributes) Int64(name string, n int64) Attributes

Int64 adds a new int64 attribute.

func (Attributes) String

func (a Attributes) String(name string, v string) Attributes

String adds a new string attribute.

func (Attributes) Time

func (a Attributes) Time(name string, t time.Time) Attributes

Time adds a new time.Time attribute.

type FeatureGuards

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

func New

func New(ctx context.Context, options ...Options) *FeatureGuards

New creates a new FeatureGuards client. The context passed in is expected to be long-running and controls the life-time of the client, usually the same lifetime as the binary. New dials in a separate go routine and will try to establish connection to FeatureGuards over time.

func (*FeatureGuards) IsOn

func (r *FeatureGuards) IsOn(name string, options ...FeatureToggleOptions) (bool, error)

IsOn returns whether the feature toggle with the given name is on or not based on its settings and the passed in options, which include any attributes FeatureGuards rules match against.

Example

package main

import (
	"context"
	"fmt"

	featureguards "github.com/featureguards/featureguards-go/v2"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	ft := featureguards.New(ctx, featureguards.WithApiKey("API_KEY"),
		featureguards.WithDefaults(map[string]bool{"TEST": true}))
	on, _ := ft.IsOn("TEST")
	fmt.Printf("%v\n", on)
}

Output:

true

Example (Attributes)

package main

import (
	"context"
	"fmt"

	featureguards "github.com/featureguards/featureguards-go/v2"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	ft := featureguards.New(ctx, featureguards.WithApiKey("API_KEY"),
		featureguards.WithDefaults(map[string]bool{"TEST": true}))
	on, _ := ft.IsOn("FOO", featureguards.WithAttributes(
		featureguards.Attributes{}.Int64("user_id", 123).String("company_slug", "acme")))
	fmt.Printf("%v\n", on)
}

Output:

false

type FeatureToggleOptions

type FeatureToggleOptions func(o *ftOptions) error

FeatureToggleOptions provides optional options to IsOn, such as attributes.

func WithAttributes

func WithAttributes(a Attributes) FeatureToggleOptions

WithAttributes specifies which attributes are passed to FeatureGuards for rule evaluation. For example, user_id, session_id or other attributes. Note: It's case sensitive.

type LogLevel

type LogLevel = logger.LogLevel

LogLevel controls the verbosity logging level.

type Options

type Options = func(o *toggleOptions) error

Options specifies the options passed to the FeatueGuards client.

func WithApiKey

func WithApiKey(key string) Options

WithApiKey is required and specifies the API key specific to the FeatureGuards project and environment.

func WithDefaults

func WithDefaults(v map[string]bool) Options

WithDefaults adds default values for feature toggle names. This is useful to ensure that in cases where FeatureGuards is down or cannot be reached, you can specify different values to be returned. By default, every feature toggle is off unless a different value is specified here.

func WithDialOptions

func WithDialOptions(options ...grpc.DialOption) Options

WithDialOptions adds gRPC dial options. Can be used to enforce a timeout on the initial dial.

func WithDynamicSettings

func WithDynamicSettings(v *dynamic_settings.DynamicSettings) Options

WithDynamicSettings adds the dynamic settings to be updated via FeatureGuards.