flags

Documentation

Overview

Package flags provides access to feature flags and product toggles. It wraps the LaunchDarkly SDK and exposes a convenient and consistent way of configuring and using the client.

The client is configured automatically based on the presence of the LAUNCHDARKLY_CONFIGURATION environment variable which contains a JSON structured string. You should declare this variable in your CDK configuration for your infrastructure. The correct value for the environment your service is running in can be retrieved from the AWS Secrets Manager under the key `/common/launchdarkly-ops/sdk-configuration/<farm>`.

You can provide overrides for some of the properties of LAUNCHDARKLY_CONFIGURATION. Refer to the documentation for the WithProxyMode and WithLambdaMode options in config.go.

If the LAUNCHDARKLY_CONFIGURATION variable does not exist, the SDK will fall-back to test mode. Test mode disables connections to LaunchDarkly and allows you to specify your own values for flags. By default, it attempts to find a file named .ld-flags.json in the directory that you invoked your Go program from. Failing this, it configures the SDK to use dynamic test data sourced at runtime. You can also specify your own path to a JSON file to source flag data from. See WithTestMode() in config.go for more information.

The client can be configured and used as a managed singleton or as an instance returned from a constructor function. The managed singleton provides a layer of convenience by removing the need for your application to maintain a handle on the flags client.

To configure the client as a singleton:

err := flags.Configure()
if err != nil {
  // handle invalid configuration
}

To configure the client as a instance that you manage:

client, err := flags.NewClient()
if err != nil {
  // handle invalid configuration
}

err = client.Connect()
if err != nil {
  // handle errors connecting to LaunchDarkly
}

The client will attempt to proxy requests through the LD Relay by default. You can optionally choose to connect directly to DynamoDB by specifying the WithLambdaMode() option to the flags.NewClient() or flags.Configure() functions.

Querying for flags is done on the client instance. You can get instance from the managed singleton with GetDefaultClient():

client, err := flags.GetDefaultClient()
if err != nil {
  // client not configured or connected
}

A typical query takes three pieces of data:

1. The flag name (the "key" within the LaunchDarkly UI).
2. The evaluation context, which contains the identifiers and attributes of an entity that you wish to query the state of a flag for. See the evaluationcontext package for more information.
3. The fallback value to return if an evaluation error occurs. This value will always be reflected as the value of the flag if err is not nil.

In most cases, the client can automatically build the evaluation context from the request context (provided the context has been augmented with the ca-go/request package):

flagVal, err := client.QueryBool(ctx, "my-flag", false)

You can also supply your own evaluation context:

evalcontext := flags.NewEvaluationContext(
          flags.WithUserID("user-id"),
          flags.WithUserAccountID("account-id"),
)

val, err := client.QueryBoolWithEvaluationContext("my-flag", evalcontext, false)

You will not need to manually shut down your SDK in most situations. If you know your application is about to terminate, or if you're testing an app, you should manually Shutdown() the LaunchDarkly client before quitting to ensure it delivers any pending analytics events to LaunchDarkly:

client.Shutdown()

Index

• func Configure(opts ...ConfigOption) error
• type Client
  • func GetDefaultClient() (*Client, error)
  • func NewClient(opts ...ConfigOption) (*Client, error)
  • func (c *Client) Connect() error
  • func (c *Client) QueryBool(ctx context.Context, key FlagName, fallbackValue bool) (bool, error)
  • func (c *Client) QueryBoolWithEvaluationContext(key FlagName, evalContext evaluationcontext.Context, fallbackValue bool) (bool, error)
  • func (c *Client) QueryInt(ctx context.Context, key FlagName, fallbackValue int) (int, error)
  • func (c *Client) QueryIntWithEvaluationContext(key FlagName, evalContext evaluationcontext.Context, fallbackValue int) (int, error)
  • func (c *Client) QueryString(ctx context.Context, key FlagName, fallbackValue string) (string, error)
  • func (c *Client) QueryStringWithEvaluationContext(key FlagName, evalContext evaluationcontext.Context, fallbackValue string) (string, error)
  • func (c *Client) RawClient() interface{}
  • func (c *Client) Shutdown() error
  • func (c *Client) TestDataSource() (*ldtestdata.TestDataSource, error)
• type ConfigOption
  • func WithBigSegmentsDisabled() ConfigOption
  • func WithInitWait(t time.Duration) ConfigOption
  • func WithLambdaMode(cfg *LambdaModeConfig) ConfigOption
  • func WithLogger(logger *log.Logger) ConfigOption
  • func WithProxyMode(cfg *ProxyModeConfig) ConfigOption
  • func WithTestMode(cfg *TestModeConfig) ConfigOption
• type FlagName
• type LambdaModeConfig
• type ProxyModeConfig
• type TestModeConfig

Functions

func Configure

func Configure(opts ...ConfigOption) error

Configure configures the client as a managed singleton.

Types

type Client

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

Client is a wrapper around the LaunchDarkly client.

func GetDefaultClient

func GetDefaultClient() (*Client, error)

GetDefaultClient returns the managed singleton client. An error is returned if the client is not yet configured.

func NewClient

func NewClient(opts ...ConfigOption) (*Client, error)

NewClient configures and returns an instance of the client. The client is configured automatically from the LAUNCHDARKLY_CONFIGURATION environment variable if it exists. Otherwise, the client falls back to test mode. See launchdarkly/flags/doc.go for more information.

func (*Client) Connect

func (c *Client) Connect() error

Connect attempts to establish the initial connection to LaunchDarkly. An error is returned if a connection has already been established, or a connection error occurs.

func (*Client) QueryBool

func (c *Client) QueryBool(ctx context.Context, key FlagName, fallbackValue bool) (bool, error)

QueryBool retrieves the value of a boolean flag. User attributes are extracted from the context. The supplied fallback value is always reflected in the returned value regardless of whether an error occurs.

func (*Client) QueryBoolWithEvaluationContext

func (c *Client) QueryBoolWithEvaluationContext(key FlagName, evalContext evaluationcontext.Context, fallbackValue bool) (bool, error)

QueryBoolWithEvaluationContext retrieves the value of a boolean flag. An evaluation context must be supplied manually. The supplied fallback value is always reflected in the returned value regardless of whether an error occurs.

func (*Client) QueryInt

func (c *Client) QueryInt(ctx context.Context, key FlagName, fallbackValue int) (int, error)

QueryInt retrieves the value of an integer flag. User attributes are extracted from the context. The supplied fallback value is always reflected in the returned value regardless of whether an error occurs.

func (*Client) QueryIntWithEvaluationContext

func (c *Client) QueryIntWithEvaluationContext(key FlagName, evalContext evaluationcontext.Context, fallbackValue int) (int, error)

QueryIntWithEvaluationContext retrieves the value of an integer flag. An evaluation context must be supplied manually. The supplied fallback value is always reflected in the returned value regardless of whether an error occurs.

func (*Client) QueryString

func (c *Client) QueryString(ctx context.Context, key FlagName, fallbackValue string) (string, error)

QueryString retrieves the value of a string flag. User attributes are extracted from the context. The supplied fallback value is always reflected in the returned value regardless of whether an error occurs.

func (*Client) QueryStringWithEvaluationContext

func (c *Client) QueryStringWithEvaluationContext(key FlagName, evalContext evaluationcontext.Context, fallbackValue string) (string, error)

QueryStringWithEvaluationContext retrieves the value of a string flag. An evaluation context must be supplied manually. The supplied fallback value is always reflected in the returned value regardless of whether an error occurs.

func (*Client) RawClient

func (c *Client) RawClient() interface{}

RawClient returns the wrapped LaunchDarkly client. The return value should be casted to an *ld.LDClient instance.

func (*Client) Shutdown

func (c *Client) Shutdown() error

Shutdown instructs the wrapped LaunchDarkly client to close any open connections and flush any flag evaluation events.

func (*Client) TestDataSource

func (c *Client) TestDataSource() (*ldtestdata.TestDataSource, error)

TestDataSource returns the dynamic test data source used by the client, or an error if: - the client wasn't configured in test mode. - the client was configured to read test data from a JSON file.

See https://docs.launchdarkly.com/sdk/features/test-data-sources for more information on using the test data source returned by this method.

type ConfigOption

type ConfigOption func(c *Client)

ConfigOption are functions that can be supplied to Configure and NewClient to configure the flags client.

func WithBigSegmentsDisabled

func WithBigSegmentsDisabled() ConfigOption

func WithInitWait

func WithInitWait(t time.Duration) ConfigOption

WithInitWait configures the client to wait for the given duration for the LaunchDarkly client to connect. If you don't provide this option, the client will wait up to 5 seconds by default.

func WithLambdaMode

func WithLambdaMode(cfg *LambdaModeConfig) ConfigOption

WithLambdaMode configures the client to connect to Dynamo for flags.

func WithLogger

func WithLogger(logger *log.Logger) ConfigOption

WithLogger configures the client to use a supplied logger (using the ca-go log package), without this configuration, a new logger from background context will be used instead.

func WithProxyMode

func WithProxyMode(cfg *ProxyModeConfig) ConfigOption

WithProxyMode configures the client to connect to LaunchDarkly via the Relay Proxy. This is typically set automatically based on the LAUNCHDARKLY_CONFIGURATION environment variable. Only use this ConfigOption if you need to override the URL of the Relay Proxy to connect to.

func WithTestMode

func WithTestMode(cfg *TestModeConfig) ConfigOption

WithTestMode configures the client in test mode. No connections are made to LaunchDarkly in this mode; all flag results are sourced from a local JSON file or at runtime through a dynamic test data source. See https://docs.launchdarkly.com/sdk/features/test-data-sources and https://docs.launchdarkly.com/sdk/features/flags-from-files for more information on test data sources.

type FlagName

type FlagName string

FlagName establishes a type for flag names.

type LambdaModeConfig

type LambdaModeConfig struct {
	DynamoCacheTTL time.Duration
}

LambdaModeConfig declares optional overrides for configuring the client in Lambda mode.

type ProxyModeConfig

type ProxyModeConfig struct {
	RelayProxyURL string
}

ProxyModeConfig declares optional overrides for configuring the client in Proxy mode.

type TestModeConfig

type TestModeConfig struct {
	FlagFilename string
	// contains filtered or unexported fields
}

TestModeConfig declares configuration for running the client in test mode. Provide an instance of this struct if you wish to use a local JSON file as the source of flag data.