[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 rewritten in place, 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. The format comes from the file name: a name that ends in .yaml or .yml, in any case (a file named .yaml included), is YAML, and any other file, including one with no extension, is JSON. The parser checks that the document and its flags, flagValues, and segments members are objects; a JSON null, array or scalar is an error.
  • Whether an empty file is valid depends on the format. An empty or white-space JSON file fails to parse (the file has no content, which is not a JSON document). Empty or white-space YAML (a tab included), or YAML that is only a comment, --- or a null, is a document with no entries.
  • Files are read as bytes and taken as UTF-8, without a UTF-8 byte order mark, whatever the process's default encoding. Content that is not valid UTF-8 fails to parse in either format; a file with a UTF-16 or UTF-32 byte order mark is reported as such (encoded in UTF-16 or UTF-32; data files must be UTF-8).
  • JSON is parsed with JSON.parse, so JSON numbers are numbers (1e3 is 1000.0), and content after the document, a # comment or a trailing comma is an error. Comments and duplicate keys inside one object follow the application's json gem: 3.x rejects both.
• 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 paths, presence and content are identical to the last applied ones. A configured file that does not exist can be made to contribute no data. 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. An error that a load does not expect is logged and retried, and the worker thread survives it.
• In-place rewrites. Applications and editors truncate a file and then write the new content, and a load in between finds the file empty. A load that finds a file with no content (empty, white space, or YAML read as nothing) while the data in effect has content from that file holds the file back: it keeps the current data, logs at debug level, and arms the retry, without reporting a failure.
  • A file is held back until it has stayed so, unwritten, for one retry delay (1 second), timed from the clock read after that file's own read. A change of its state (modification time and size, read through any symbolic link with the poller's helper) is a new rewrite and starts the delay over, as does a read that finds it with content, even content that fails to parse, or missing.
  • Each file is held for at most five retry delays from its first hold; its bound starts over only at a load that holds nothing back, whether that load applies, is skipped, or fails.
  • A load reads and classifies every file, even after one fails to read or parse, so files emptied together are held and applied together; it then fails with the first failure, holds files back, or merges, in that order.
  • The retry of a hold is armed for the rest of the first due file's delay or bound, plus a tenth of the retry delay.
  • A file that contributed no content to the data in effect (a placeholder that has always been empty, a file that was missing, a file whose emptying has been applied) is parsed at once, and so is every file when retries are off.
  • After the delay, an empty JSON file fails to parse and keeps the data; an empty YAML file has no entries.
• A stat-based poller that compares existence, modification time, and size, through symbolic links. 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.

Not changed: YAML that is cut off mid-write can still parse, with fewer entries or a value cut short, so the override source docs recommend replacing a YAML file in one operation. A writer that pauses longer than the retry delay gets the empty file applied (YAML) or reported (JSON).

Testing

• Unit specs for the document parser (format by name, empty JSON and YAML, UTF-8 and byte order marks, JSON numbers and trailing content), merge, poller (including symbolic links), reloader (debounce, retry, last-good retention, sequential reloads, stop, and the hold of an emptied file), 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.
• The reloader specs rewrite their files in place with real, deliberately slow writes (InPlaceWrites.rewrite in spec/in_place_writes.rb), and the hold's delays, bounds and retries are tested on a controlled clock with synchronous loads, with a few real-clock tests for the retry firing.
• The in-place rewrite handling was reviewed in eight rounds as fix: Keep overrides through an in-place rewrite of their files #479, with multi-agent and Bugbot reviews, and is shared with the other SDKs' ports. On that code: a mutation check reverted each part of the fix on its own (67 mutants); 60 fail at least one test, and the other 7 are equivalent (the retries-off guard, the clearing of held-file records on apply or skip, starting over every file instead of the files read, and the path or the presence alone in the digest). The changed spec files ran 10 times in a row on Ruby 3.2 and on JRuby 9.4 with no failures.
• Full suite and RuboCop are clean, apart from can be automatically loaded by Bundler.require, which needs write access to the system gem directory on the test machine. 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

_{Opened from termag}

[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]

This reply was written by an AI agent (Claude Code) working on behalf of @kinyoklion.

Leaving this as is. Under YAML 1.1 an unquoted on key parses as the boolean true. Ruby's existing file data sources read YAML the same way (YAML.safe_load followed by symbolize_all_keys in file_data_source.rb and file_data_source_v2.rb on main), as do the Go and Python ports. The override docs (launchdarkly/sdk-meta#714, launchdarkly/ld-docs-private#8869) quote "on" in the YAML example and tell readers to do the same.

[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.}

[kinyoklion]

Follow-up to the poller-test change in the other ports: the reloader spec retries a failed reload after the retry delay and recovers when the file is fixed had the same flaw. It fixed the file with an ordinary File.write while the 0.1 s retry was pending and expected the retry to apply the fixed content. If the retry reads the file between the truncation and the write it sees an empty file, which is a valid document, so the retry applies an empty result and stops; the fixed content is never loaded and the spec fails with got: {}.

Reproduced locally with a deliberately slow write (truncate, sleep 0.3 s, write): the old expectation failed 3/3 and the new one passed 3/3. The spec now accepts the recovery the retry made and loads the fixed content on demand when the retry did not see it (5babf80). reloader_spec 5/5 runs green, spec/impl/file_data 76 examples green, and the file data plus override specs at the top of the stack (3758acf) 165 examples green. The stack above is rebased onto this commit.

Written by Claude Code on behalf of @kinyoklion.