Skip to content

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

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

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

Conversation

@kinyoklion

@kinyoklion kinyoklion commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Summary

This adds the file-based override source that the OVERRIDE specification defines, as FileOverrides.source() in the integrations package, configured through DataSystemBuilder.overrides(...):

LDConfig config = new LDConfig.Builder()
    .dataSystem(Components.dataSystem().defaultMode()
        .overrides(FileOverrides.source().filePaths("/etc/launchdarkly/overrides.json")))
    .build();

The source reads one or more JSON or YAML files in the file data source document format (flags, flagValues, segments) in the configured order. A flagValues entry becomes a flag that is off and serves the value as its single variation, so it evaluates with the OFF reason kind. Entries keep the versions that the documents specify.

  • duplicateKeysHandling: FAIL (the default) fails the reload when the same key appears in more than one file; IGNORE keeps the entry from the first configured file.
  • changeDetection: POLLING (the default) examines each file's modification time and size on an interval; WATCHING uses file system notifications. The two are alternatives.
  • pollInterval: one second by default and at minimum; a smaller value is raised to the minimum with a warning.
  • A configured file that does not exist contributes no overrides and is not an error. Creating it later takes effect, and deleting it removes its overrides.
  • A file that exists but cannot be read or parsed fails that whole reload: the last good overrides stay in effect, the failure is logged, and the source retries after a bounded delay as well as on the next change.
  • The initial load completes during client construction. Every applied change is logged at Info with the overrides in effect and what each file supplied.
  • No file paths, a null change detection mode, or a null poll interval is a configuration error that fails client construction.

The source is built on OverrideFileLoader, FileDataReloader, FileDataPoller, and FileDataWatcher from the earlier change. The existing file data source keeps its current behavior; this change does not touch its code paths. Flag overrides are currently experimental and subject to change.

This PR depends on the override layer and the reload infrastructure changes and is based on the events branch (rlamb/overrides-java-override-events); retarget it to feat/overrides once that branch merges.

The OVERRIDE specification defines a file-based override source that
reads override entries from one or more local files and reloads them
when the files change. FileOverrides.source() provides it, configured
through DataSystemBuilder.overrides(...).

The source accepts the file data source document format (flags,
flagValues, segments) in JSON or YAML, merges the files in the
configured order with the configured duplicate keys handling (fail by
default, or ignore all but the first), and keeps the versions that the
documents specify. A flagValues entry becomes a flag that is off and
serves the value as its single variation. Change detection is polling
(the default, one second by default and at minimum) or watching. A
configured file that does not exist contributes no overrides. A file
that exists but cannot be read or parsed fails that reload, keeps the
last good overrides, logs the failure, and is retried. The initial load
completes during client construction. Every applied change is logged at
Info with the overrides in effect and what each file supplied. Missing
file paths, a null change detection mode, or a null poll interval fail
client construction.

Flag overrides are currently experimental and subject to change.
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-java-override-events branch from bd3633b to e1dd774 Compare September 28, 2026 21:04
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-java-file-override-source branch from bc2e4a9 to 657a598 Compare September 28, 2026 21:04

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