[kinyoklion]

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 file whose name ends in .yaml or .yml, in any case, is YAML, and any other file is JSON; a file is read as UTF-8, or in the encoding that a byte order mark names. A flagValues entry becomes a flag that is on and serves the value as its single variation by fallthrough, so it evaluates with the FALLTHROUGH 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. When the watch service cannot be created at all (for example, the limit on inotify instances is reached), the source logs an error and polls the files instead, at no less than the minimum poll interval.
• 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. An empty JSON file is not a valid document, so it fails the reload too; to remove a file's overrides, delete it or write {}. An empty YAML file has no entries.
• Files can be rewritten in place. A file whose content is in effect and that a reload finds empty is held back by the reloader from the earlier change: the overrides in effect, and the other files' changes, stay until the new content is written, for at most one retry delay (1 s) after the file was last written while empty and five retry delays from the first hold. FileOverrideSourceImpl passes the loader itself to the reloader, so that the loader learns which content is in effect, and takes the retry delay as a package-private constructor parameter for tests. For a YAML file, replacing its contents in one operation avoids briefly applying a partly written file.
• 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, a null poll interval, or a file path that is not on the default file system (a zip file system, for example) with WATCHING selected is a configuration error that fails client construction. Polling reads such a path through its own provider. A path listed more than once is logged at Warn and the repeats are ignored; the first occurrence keeps its place in the order.

The public docs say what an application needs: the extension rule and the encoding, that files can be rewritten in place, how to remove a file's overrides, that an empty JSON file is not a valid document, and replacing a YAML file in one operation. The hold's delay and bound stay in the internal comments and in the description of the earlier change. Every public override API, including the builder methods, the poll interval constants and the change detection modes, says that flag overrides are currently experimental and subject to change.

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.

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.

Testing

• FileOverrideSourceTest: configuration, merging, missing and malformed files, polling and watching reloads, the polling fallback, thread release on close, and at startup an empty YAML file with no entries and an empty JSON file (also with no extension) failing to load.
• FileOverrideSourceInPlaceRewriteTest, end to end with real in-place rewrites (truncate, pause, write through the same stream): the source never applies a snapshot without the override, for JSON and YAML, watching (300 ms pause) and polling (1.2 s pause, longer than the poll interval); two quick rewrites while watching; the defaults (polling every second, 1 s retry) through the public builder with two rewrites about a second apart; a client with LaunchDarkly data serving a -> b and never the LaunchDarkly value, for JSON and YAML.
• The in-place rewrite handling was reviewed in eight rounds as fix: Keep the overrides in effect while an override file is rewritten in place #248 (general and adversarial reviews, Bugbot). Mutation check with a clean build per mutant: 57 mutants, each failing at least one test. The override test classes ran 12 times in a row with no failure. The harness flag overrides suite passes against the contract test service at the top of the stack: 38 tests.

SDK-3246

_{Opened from termag}

---

Note

Overview
Adds FileOverrides.source() so operators can load flag and segment overrides from local JSON/YAML files via DataSystemBuilder.overrides(...), using the same document shape as the file data source.

The builder supports multiple ordered files, duplicate-key FAIL vs IGNORE, POLLING (default, 1s) vs WATCHING change detection, and validation at client build time (paths required, non-default FS + watching rejected). FileOverrideSourceImpl performs a synchronous initial load, pushes full snapshots to the override sink, keeps the last good set on read/parse failures, handles in-place rewrites without dropping overrides, and falls back to polling if the watch service cannot be created.

Docs on OverrideSource and DataSystemBuilder point at FileOverrides. Tests cover configuration, reload behavior, in-place rewrites end-to-end, and client-side allFlagsState semantics for flagValues vs full flags with clientSide.

^{Reviewed by Cursor Bugbot for commit 43d6c3d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 43d6c3d. Configure here.}