Documentation
¶
Overview ¶
Package ldoverrides provides sources for the SDK's flag override capability. Flag overrides are currently experimental and subject to change.
Overrides are flag and segment definitions that take precedence over data received from LaunchDarkly at evaluation time, on a per-key basis. They exist for resilience during an incident. An operator can force one or more flags to a known state on a running application, whether or not the application can reach LaunchDarkly. The override stays in effect until the operator removes it. Flags not present in the override data are completely unaffected.
This package currently provides one source: FileSource, which reads overrides from local files and reloads them as the files change. Configure it with the data system builder:
config := ld.Config{
DataSystem: ldcomponents.DataSystem().Default().
Overrides(ldoverrides.FileSource().FilePaths("/etc/ld/overrides.json")),
}
An evaluation that an override affects is marked. The marking is direct or transitive. It applies when the evaluated flag, a prerequisite at any depth, or a segment read during the evaluation came from the override layer. The evaluation reason's IsOverrideAffected method reports the marking. Marked evaluations appear in analytics summary events only, under separate counters, so LaunchDarkly can distinguish them. They produce no individual evaluation events.
Index ¶
- Constants
- type ChangeDetection
- type DuplicateKeysHandling
- type FileSourceBuilder
- func (b *FileSourceBuilder) Build(context subsystems.ClientContext) (subsystems.OverrideSource, error)
- func (b *FileSourceBuilder) ChangeDetection(mode ChangeDetection) *FileSourceBuilder
- func (b *FileSourceBuilder) DuplicateKeysHandling(handling DuplicateKeysHandling) *FileSourceBuilder
- func (b *FileSourceBuilder) FilePaths(paths ...string) *FileSourceBuilder
- func (b *FileSourceBuilder) PollInterval(interval time.Duration) *FileSourceBuilder
Constants ¶
const ( // DefaultPollInterval is the interval at which the file source examines the files for // changes in Polling mode when no interval was specified. Because the source reads local // files rather than contacting a service, a short interval keeps an override responsive // during an incident at negligible cost. DefaultPollInterval = time.Second // MinimumPollInterval is the shortest allowed polling interval. A configured interval // below this is raised to it. The minimum exists only to prevent a pathological tight // loop over the filesystem. MinimumPollInterval = time.Second )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ChangeDetection ¶
type ChangeDetection string
ChangeDetection is a parameter type used with FileSourceBuilder.ChangeDetection. It selects how the source learns that a file changed.
const ( // Polling is an option for FileSourceBuilder.ChangeDetection. The source examines the // files on a fixed interval and reloads when the modification time or the size of a file // changes. Polling works on every file system, including network mounts and directories // whose contents are swapped through symbolic links, as Kubernetes does for mounted // ConfigMaps. It is the default. Polling ChangeDetection = "polling" // Watching is an option for FileSourceBuilder.ChangeDetection. The source reloads in // response to file system change notifications. It reacts faster than polling. It // depends on notifications, which some file systems do not deliver reliably. Watching ChangeDetection = "watching" )
type DuplicateKeysHandling ¶
type DuplicateKeysHandling string
DuplicateKeysHandling is a parameter type used with FileSourceBuilder.DuplicateKeysHandling.
const ( // DuplicateKeysFail is an option for FileSourceBuilder.DuplicateKeysHandling. With this // option, a reload fails if the same flag or segment key appears in more than one file. // The previously loaded overrides stay in effect. DuplicateKeysFail DuplicateKeysHandling = "fail" // DuplicateKeysKeepFirst is an option for FileSourceBuilder.DuplicateKeysHandling. With // this option, when the same key appears in more than one file, the entry from the first // configured file is kept. The others are discarded. DuplicateKeysKeepFirst DuplicateKeysHandling = "ignore" )
type FileSourceBuilder ¶
type FileSourceBuilder struct {
// contains filtered or unexported fields
}
FileSourceBuilder is a builder created by FileSource. Configure it with the builder methods, then pass it to the Overrides method of the data system configuration builder in the ldcomponents package.
func FileSource ¶
func FileSource() *FileSourceBuilder
FileSource returns a builder for a file-based override source. The source reads flag and segment overrides from one or more local files and reloads them as the files change.
The files use the same document format as the file data sources (ldfiledata and ldfiledatav2). Each file is a JSON or YAML document with optional "flags", "flagValues", and "segments" members. "flagValues" entries are expanded into full flag definitions that return the given value for every context. When multiple files are configured, their entries are combined. The configured order determines which file wins under the duplicate-key handling.
A reload replaces the entire override set, so removing an entry from the files removes the override. A configured file that does not exist contributes no overrides. Deleting a file therefore removes its overrides, and deleting every file removes them all. A file that exists but cannot be read or parsed makes that whole reload fail. The previously loaded overrides stay in effect. The source logs the failure, retries after a short delay, and recovers on its own once the file is readable again.
Whenever the set of overrides in effect changes, including at startup, the source logs the overrides in effect and what each configured file supplied, at Info level.
By default the source polls the files for changes once per second. See ChangeDetection and PollInterval.
func (*FileSourceBuilder) Build ¶
func (b *FileSourceBuilder) Build(context subsystems.ClientContext) (subsystems.OverrideSource, error)
Build is called internally by the SDK.
func (*FileSourceBuilder) ChangeDetection ¶
func (b *FileSourceBuilder) ChangeDetection(mode ChangeDetection) *FileSourceBuilder
ChangeDetection selects how the source detects file changes. The default is Polling. The two modes are alternatives, so setting one replaces the other.
func (*FileSourceBuilder) DuplicateKeysHandling ¶
func (b *FileSourceBuilder) DuplicateKeysHandling(handling DuplicateKeysHandling) *FileSourceBuilder
DuplicateKeysHandling specifies how to handle the same key appearing in more than one file. If not specified, or set to an unrecognized value, the default is DuplicateKeysFail.
func (*FileSourceBuilder) FilePaths ¶
func (b *FileSourceBuilder) FilePaths(paths ...string) *FileSourceBuilder
FilePaths specifies the files to load overrides from. The order is significant: it determines which file wins under the duplicate-key handling when the same key appears in more than one file.
func (*FileSourceBuilder) PollInterval ¶
func (b *FileSourceBuilder) PollInterval(interval time.Duration) *FileSourceBuilder
PollInterval sets the interval between examinations of the files in Polling mode. Watching mode ignores it. The default is DefaultPollInterval. An interval below MinimumPollInterval is raised to the minimum.
Source Files