feat: Add file loading code for flag overrides

[kinyoklion]

Summary

This is the first of a series that adds flag overrides, as defined by the OVERRIDE specification, to the Ruby server SDK. The existing FDv1 and FDv2 file data sources keep their current behavior: this PR does not change lib/ldclient-rb/impl/integrations/file_data_source.rb, file_data_source_v2.rb, or their specs, and the override feature is additive throughout the series.

The file-based override source must tolerate a missing file, a file that is being written, and a burst of change notifications, and it must keep the last good data when a reload fails. This change adds LaunchDarkly::Impl::FileData, the file reading, parsing, merging, and reloading code that source needs:

• Document parsing for JSON and YAML. The parser checks that the document and its flags, flagValues, and segments members are objects.
• An ordered merge of several documents with duplicate keys handling of fail or ignore, expansion of each flagValues entry into a flag that is on and serves the value by fallthrough (so an evaluation reports the FALLTHROUGH reason kind, as the specification describes), deserialization into the data model classes, and per-document entry counts.
• A reloader that serializes reloads, debounces change signals, keeps the last good result when a reload fails, retries after a bounded delay, reports each distinct failure once, and can skip a reload whose content is byte-identical to the last applied content. A configured file that does not exist can be treated as a file with no content. An exception raised by the consumer's apply is treated as a failed reload: nothing from that load is remembered, the failure is reported, and the reload is retried.
• A stat-based poller that compares existence, modification time, and size. A file that appears or disappears is a change.
• A watcher that uses rb-inotify on Linux (a dependency of the optional listen gem) to watch the directory of each file without descending into subdirectories, and listen elsewhere. It picks up a file that does not exist yet when it appears, and it watches each directory on its own: a directory that does not exist is retried once per second while the others stay watched, and one change is signaled when a retry sets up a watch. Non-recursive watching matters because listen scans the whole tree under a watched directory and fails when a subdirectory cannot be read, as happens for a file in the system temporary directory. On Linux, a watched directory that is deleted is watched again once it exists, and one change is signaled so the reload picks up what was written meanwhile.

A new spec, spec/integrations/file_data_source_compatibility_spec.rb, pins the behaviors of the existing file data sources that their other specs did not assert (per-file version numbering, keying by the entry's own key, the on-plus-fallthrough expansion of flagValues, no retry of a failed load, log messages, modification-time-only polling, no reaction to a deleted file when polling, the FDv1 poller's reload cadence after a change, and use of listen when it is present), so that they stay as they are while this code exists beside them.

Verification: unit specs for the document parser, merge, poller, reloader (including debounce, retry, last-good retention, sequential reloads, and stop), and watcher (including a directory with an unreadable subdirectory and the inotify thread lifecycle), the new compatibility pins, and the unchanged existing file data source specs. Full suite and RuboCop are clean. Each new spec was checked against a deliberate defect in the code it covers, and each compatibility pin against a deliberate change to the existing source it pins.

SDK-3249

---

Note

Overview
Introduces LaunchDarkly::Impl::FileData, shared infrastructure for upcoming file-based flag overrides. It does not change the existing FDv1/FDv2 integrations in this PR.

Document handling: JSON/YAML parsing into flags, flagValues, and segments, with ReadError for per-file failures and helpers to expand flagValues into on/fallthrough flags.

Multi-file merge: Ordered combination with fail or ignore duplicate-key policy, model deserialization, and per-document counts.

Reload pipeline: Reloader serializes loads, debounces change signals, retries failures, keeps the last good data on error, optionally skips byte-identical reloads, and can treat missing files as empty. Poller detects changes via existence/mtime/size; Watcher uses rb-inotify (Linux, non-recursive) or optional listen elsewhere, with retries for missing or deleted watch directories.

Tests: Unit specs for each component plus file_data_source_compatibility_spec.rb to lock current FDv1/FDv2 behavior (version numbering, polling semantics, logging, etc.) while the new code lives alongside them.

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

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

YAML on key silently disables flags

Medium Severity

YAML.safe_load treats unquoted on as a boolean, and symbolize_keys then stores that field as :true. Full flag definitions never see :on, so FeatureFlag treats them as off. Natural YAML like on: true therefore loads as a disabled flag instead of failing or preserving the on field.

Additional Locations (1)

• lib/ldclient-rb/impl/file_data/document.rb#L75-L87

 

^{Reviewed by Cursor Bugbot for commit 2e31db3. Configure here.}

[kinyoklion]

bugbot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

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

^{Reviewed by Cursor Bugbot for commit 73afbaa. Configure here.}