[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 series targets dotnet-server-sdk-v9, the branch that prepares the next major version. 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, which registers a parsing function for a file extension, for formats other than JSON such as YAML. Building a source with no file paths, with an option outside its enumeration, or with a YAML file for which no parser is registered, 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 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 parser for a file is chosen by its extension, and a file whose extension has no registered parser is parsed as JSON. A flag or segment is listed under its key; a key property in the definition is optional and must be equal to it, and a version property is optional. 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 register a parser for the .yaml or .yml extension through the Parser option. A YAML file configured without one is reported when the client is created, not on every reload. The specification allows the application to supply the parser.

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

It depends on the server events change, #366, which is merged into dotnet-server-sdk-v9.

SDK-3248

Release Please could not parse the squash commit for this PR, so this block supplies its changelog entry:

BEGIN_COMMIT_OVERRIDE
feat: Add the file-based override source (#367)
END_COMMIT_OVERRIDE

---

Note

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

The public surface is FileOverrides, FileOverrideSourceBuilder, and FileOverrideTypes (duplicate-key policy, polling vs watching, poll interval, optional per-extension parsers for YAML). The internal FileOverrideSource merges multiple paths in order, loads synchronously on startup, hot-reloads through shared file-loading helpers, pushes full snapshots to the override layer, and logs what is in effect per file. Failed reloads keep the last good snapshot; missing files are ignored until they appear.

Docs on DataSystemBuilder.Overrides and IOverrideSource now point at FileOverrides. Tests cover builder validation, reload/merge/error behavior, and end-to-end LdClient evaluation (including OverrideAffected and client-side AllFlagsState rules).

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

_{Opened from termag}

[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 f18639e. Configure here.}