ldfiledata

Documentation

Overview

Package ldfiledata allows the LaunchDarkly client to read feature flag data from a file.

This is different from ldtestdata.DataSource, which allows you to simulate flag configurations programmatically rather than using a file.

To use the file-based data source in your SDK configuration, call ldfiledata.DataSource to obtain a configurable object that you will use as the configuration's DataSource:

config := ld.Config{
    DataSource: ldfiledata.DataSource()
        .FilePaths("./test-data/my-flags.json"),
}
client := ld.MakeCustomClient(mySdkKey, config, 5*time.Second)

Use FilePaths to specify any number of file paths. The files are not actually loaded until the client starts up. At that point, if any file does not exist or cannot be parsed, the data source will log an error and will not load any data.

Files may contain either JSON or YAML; if the first non-whitespace character is '{', the file is parsed as JSON, otherwise it is parsed as YAML. The file data should consist of an object with up to three properties:

- "flags": Feature flag definitions.

- "flagValues": Simplified feature flags that contain only a value.

- "segments": User segment definitions.

The format of the data in "flags" and "segments" is defined by the LaunchDarkly application and is subject to change. Rather than trying to construct these objects yourself, it is simpler to request existing flags directly from the LaunchDarkly server in JSON format, and use this output as the starting point for your file. In Linux you would do this:

curl -H "Authorization: <your sdk key>" https://app.launchdarkly.com/sdk/latest-all

The output will look something like this (but with many more properties):

{
  "flags": {
    "flag-key-1": {
      "key": "flag-key-1",
      "on": true,
      "variations": [ "a", "b" ]
    }
  },
  "segments": {
    "segment-key-1": {
      "key": "segment-key-1",
      "includes": [ "user-key-1" ]
    }
  }
}

Data in this format allows the SDK to exactly duplicate all the kinds of flag behavior supported by LaunchDarkly. However, in many cases you will not need this complexity, but will just want to set specific flag keys to specific values. For that, you can use a much simpler format:

{
  "flagValues": {
    "my-string-flag-key": "value-1",
    "my-boolean-flag-key": true,
    "my-integer-flag-key": 3
  }
}

Or, in YAML:

flagValues:
  my-string-flag-key: "value-1"
  my-boolean-flag-key: true
  my-integer-flag-key: 3

It is also possible to specify both "flags" and "flagValues", if you want some flags to have simple values and others to have complex behavior. However, it is an error to use the same flag key or segment key more than once, either in a single file or across multiple files, unless you specify otherwise with the DuplicateKeysHandling method.

If the data source encounters any error in any file-- malformed content, a missing file, or a duplicate key-- it will not load flags from any of the files.

Index

• type DataSourceBuilder
  • func DataSource() *DataSourceBuilder
  • func (b *DataSourceBuilder) CreateDataSource(context interfaces.ClientContext, ...) (interfaces.DataSource, error)
  • func (b *DataSourceBuilder) DuplicateKeysHandling(duplicateKeysHandling DuplicateKeysHandling) *DataSourceBuilder
  • func (b *DataSourceBuilder) FilePaths(paths ...string) *DataSourceBuilder
  • func (b *DataSourceBuilder) Reloader(reloaderFactory ReloaderFactory) *DataSourceBuilder
• type DuplicateKeysHandling
• type ReloaderFactory

Types

type DataSourceBuilder

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

DataSourceBuilder is a builder for configuring the file-based data source.

Obtain an instance of this type by calling DataSource(). After calling its methods to specify any desired custom settings, store it in the SDK configuration's DataSource field.

Builder calls can be chained, for example:

config.DataStore = ldfiledata.DataSource().FilePaths("file1").FilePaths("file2")

You do not need to call the builder's CreatePersistentDataSource() method yourself; that will be done by the SDK.

func DataSource

func DataSource() *DataSourceBuilder

DataSource returns a configurable builder for a file-based data source.

func (*DataSourceBuilder) CreateDataSource

func (b *DataSourceBuilder) CreateDataSource(
	context interfaces.ClientContext,
	dataSourceUpdates interfaces.DataSourceUpdates,
) (interfaces.DataSource, error)

CreateDataSource is called by the SDK to create the data source instance.

func (*DataSourceBuilder) DuplicateKeysHandling

func (b *DataSourceBuilder) DuplicateKeysHandling(duplicateKeysHandling DuplicateKeysHandling) *DataSourceBuilder

DuplicateKeysHandling specifies how to handle keys that are duplicated across files.

If this is not specified, or if you set it to an unrecognized value, the default is DuplicateKeysFail.

func (*DataSourceBuilder) FilePaths

func (b *DataSourceBuilder) FilePaths(paths ...string) *DataSourceBuilder

FilePaths specifies the input data files. The paths may be any number of absolute or relative file paths.

func (*DataSourceBuilder) Reloader

func (b *DataSourceBuilder) Reloader(reloaderFactory ReloaderFactory) *DataSourceBuilder

Reloader specifies a mechanism for reloading data files.

It is normally used with the ldfilewatch package, as follows:

config := ld.Config{
    DataSource: ldfiledata.DataSource().
        FilePaths(filePaths).
        Reloader(ldfilewatch.WatchFiles),
}

type DuplicateKeysHandling

type DuplicateKeysHandling string

DuplicateKeysHandling is a parameter type used with DataSourceBuilder.DuplicateKeysHandling.

const (
	// DuplicateKeysFail is an option for DataSourceBuilder.DuplicateKeysHandling, meaning that data loading
	// should fail if keys are duplicated across files. This is the default behavior.
	DuplicateKeysFail DuplicateKeysHandling = "fail"

	// DuplicateKeysIgnoreAllButFirst is an option for DataSourceBuilder.DuplicateKeysHandling, meaning that
	// if keys are duplicated across files the first occurrence will be used.
	DuplicateKeysIgnoreAllButFirst DuplicateKeysHandling = "ignore"
)

type ReloaderFactory

type ReloaderFactory func(paths []string, loggers ldlog.Loggers, reload func(), closeCh <-chan struct{}) error

ReloaderFactory is a function type used with DataSourceBuilder.Reloader, to specify a mechanism for detecting when data files should be reloaded. Its standard implementation is in the ldfilewatch package.