Skip to content

feat: Add the file-based override source - #453

Draft
kinyoklion wants to merge 1 commit into
rlamb/overrides-ruby-eventsfrom
rlamb/overrides-ruby-file-source
Draft

kinyoklion wants to merge 1 commit into
rlamb/overrides-ruby-eventsfrom
rlamb/overrides-ruby-file-source

Conversation

@kinyoklion

@kinyoklion kinyoklion commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Summary

This PR is stacked on #452 because it supplies the override store that the earlier PRs add, and its client-level spec relies on the marked reasons and events they produce.

This change adds LaunchDarkly::Integrations::FileData.override_source, the file-based override source that the OVERRIDE specification defines. It is configured with LaunchDarkly::DataSystem::ConfigBuilder#overrides:

overrides = LaunchDarkly::Integrations::FileData.override_source(paths: ["/etc/launchdarkly/overrides.json"])
config = LaunchDarkly::Config.new(data_system: LaunchDarkly::DataSystem.default.overrides(overrides))

The source reads one or more JSON or YAML files in the file data source document format (flags, flagValues, segments) and supplies complete snapshots to the SDK's override store. Its options are paths (required, in precedence order), duplicate_keys_handling (:fail, the default, or :ignore, which keeps the first file's entry), change_detection (:polling, the default, or :watching through the optional listen gem), and poll_interval (default 1 second, raised to the 1 second minimum with a warning). Invalid options raise ArgumentError when the client is created, the same way other invalid component configuration is reported. Unlike the Go reference, an unrecognized duplicate_keys_handling value and an unknown option key are rejected rather than defaulted, because the specification treats invalid configuration as a construction error and an emergency mechanism should fail loudly.

Behavior comes from the shared file data code added in #449: a configured file that does not exist contributes no overrides, so a file can be created later and deleting a file removes its overrides; a file that exists but cannot be read or parsed fails that reload and keeps the last good overrides, with a logged failure and a retry; a rewrite with identical content is not reapplied; the initial load completes before the client constructor returns. A flagValues entry expands into a flag that is off and serves the value, so the evaluation reports the OFF reason kind. Every applied change is logged at Info with the overrides in effect and what each file supplied, and the reloader's log lines for this source carry a FileOverrideSource prefix.

Verification: specs for the builder (defaults, absolute paths, every invalid option, listen requirement, poll interval clamping), the initial load (merge, off-form expansion, YAML, missing file, all files missing, malformed file, duplicate keys under both handlings), the Info log format, polling change detection (change, appearance, deletion, malformed edit with recovery, identical rewrite, stop, stop before start), watching change detection (change, appearance, deletion), and a client-level check of serving and reloading overrides through LDClient. Full suite and RuboCop are clean. Each new spec was checked against a deliberate defect in the code it covers.

The existing FDv1 and FDv2 file data sources keep their current behavior. This series does not change them; the override feature is additive.

Adds `LaunchDarkly::Integrations::FileData.override_source`, the file-based
override source that the OVERRIDE specification defines, for use with
`LaunchDarkly::DataSystem::ConfigBuilder#overrides`.

The source reads one or more JSON or YAML files in the file data source
document format (`flags`, `flagValues`, `segments`) and supplies complete
snapshots to the SDK's override store. Options: `paths` (required, in
precedence order), `duplicate_keys_handling` (`:fail`, the default, or
`:ignore`, which keeps the first file's entry), `change_detection`
(`:polling`, the default, or `:watching` through the optional listen gem),
and `poll_interval` (default 1 second, raised to the 1 second minimum with
a warning). Invalid options, including an unknown option key, raise
`ArgumentError` when the client is created.

Behavior comes from the shared file data code: a configured file that
does not exist contributes no overrides, so a file can be created later
and deleting a file removes its overrides. A file that exists but cannot
be read or parsed fails that reload and keeps the last good overrides,
with a logged failure and a retry. A rewrite with identical content is
not reapplied. The initial load completes before the client constructor
returns. A `flagValues` entry expands into a flag that is off and serves
the value, so the evaluation reports the OFF reason kind. Every applied
change is logged at Info with the overrides in effect and what each file
supplied. The reloader's log lines for this source carry a
FileOverrideSource prefix.

Flag overrides are currently experimental and subject to change.
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-ruby-events branch from be39b66 to 6ff51f4 Compare September 28, 2026 20:36
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-ruby-file-source branch from 605d0ab to 5bda436 Compare September 28, 2026 20:36

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant