feat: Add the file-based override source

[kinyoklion]

Summary

Adds the file-based override source, as defined by the OVERRIDE specification, on top of the shared file loading code and the override layer from the earlier changes in this series. The existing file data source keeps its current behavior: it does not use the shared code, and nothing in this change touches it.

Configuration: FileOverrides.Source() returns a FileOverrideSourceBuilder that is passed to DataSystemBuilder.Overrides(...). Its options are FilePaths (one or more files, in precedence order, required), DuplicateKeysHandling (Fail, the default, or Ignore, which keeps the first configured file's entry), ChangeDetection (Polling, the default, or Watching), PollInterval (one second by default and at minimum; a lower value is raised to the minimum with a warning), and Parser for non-JSON content such as YAML. Building a source with no file paths, or with an option outside its enumeration, throws, so the client constructor fails the same way it does for other invalid component configuration. A path listed more than once is logged at Warn and the repeats are ignored; the first occurrence keeps its place in the order. Every public member carries the note that flag overrides are currently experimental and subject to change.

Behavior: the files use the file data source document format (flags, flagValues, segments); a flagValues entry expands to a flag that is on and serves its single value by fallthrough, so it evaluates with the FALLTHROUGH reason. The initial load runs inside the client constructor. Change detection is in place before the initial load, so a change made between the two is not missed. In watching mode a configured path that is a link to a file in another directory is detected only through the periodic directory check; polling, the default, follows the link directly. A configured file that does not exist contributes no overrides and produces no error log; creating it later adds its overrides and deleting it removes them. A file that exists but cannot be read or parsed, or a duplicate key under Fail, fails that whole reload: the previously loaded overrides stay in effect, the failure is logged, and the source retries after a bounded delay and on the next change. Every applied change is logged at Info level with the overrides in effect and what each configured file supplied (for example Flag overrides in effect: 2 flags, 1 segment (/etc/ld/a.json: 2 flags, 1 segment; /etc/ld/b.json: absent)). Polling examines the files' modification time, size, and existence once per interval; watching uses file system notifications on each file's directory.

YAML: the SDK does not bundle a YAML parser, following the existing file data source, so YAML files require the application to supply a parser through the Parser option. The specification asks for YAML support in the source itself; this is the deliberate deviation for the .NET SDK, and adding a YAML dependency to the SDK package is the alternative.

Tests cover the builder validation and defaults, every file behavior above in both change detection modes, the Info log lines, and a client end-to-end scenario in which an operator adds, changes, and removes an override on a running client that never obtains LaunchDarkly data.

This PR is based on the branch of the server events change, which it depends on.

SDK-3248

---

Note

Overview
Adds an experimental file-based flag override integration so operators can force flag/segment values from local files via DataSystemBuilder.Overrides(FileOverrides.Source().FilePaths(...)), without restarting the client.

The public surface is FileOverrides, FileOverrideSourceBuilder, and FileOverrideTypes (duplicate-key handling, polling vs watching, poll interval, optional custom parser for YAML). FileOverrideSource merges one or more file-data-format JSON files through shared FileDataReloader machinery, applies full snapshots to the override layer on startup and on change, keeps the last good overrides on parse/duplicate-key failures, and logs what is in effect per file. Docs on DataSystemBuilder.Overrides and IOverrideSource now point at FileOverrides.

Tests cover builder validation, reload/merge/missing-file behavior in both detection modes, and end-to-end LdClient evaluations with OverrideAffected.

^{Reviewed by Cursor Bugbot for commit 6bdec5e. 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]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6bdec5e. Configure here.}

[cursor]

Duplicate paths missed on Windows

Low Severity

Path deduplication uses Distinct() with case-sensitive equality after Path.GetFullPath, which preserves input casing. On Windows the same file listed twice with different casing is kept as two paths, so default Fail handling treats every key as a duplicate of itself and the reload never applies.

 

^{Reviewed by Cursor Bugbot for commit 6bdec5e. Configure here.}