feat: Add the override store, overlay, and data system wiring - #451
Draft
kinyoklion wants to merge 1 commit into
Draft
kinyoklion wants to merge 1 commit into
kinyoklion wants to merge 1 commit into
Conversation
kinyoklion
force-pushed
the
rlamb/overrides-ruby-model-evaluator
branch
from
September 25, 2026 22:51
0f89736 to
4810ac9
Compare
kinyoklion
force-pushed
the
rlamb/overrides-ruby-store-overlay
branch
from
September 25, 2026 22:51
e2df553 to
e4d05bb
Compare
Adds the override layer that the OVERRIDE specification describes: a runtime-mutable collection of flag and segment definitions that takes precedence over LaunchDarkly data at the store read boundary. - `LaunchDarkly::Interfaces::Overrides::OverrideSource` and `OverrideSink` define how a source supplies complete snapshots to the SDK. - `Impl::Overrides::Layer` holds marked entries in an immutable hash that is swapped on update, so the layer holds exactly one snapshot at any instant. - `Impl::Overrides::Overlay` sits at the store read boundary. A read for a key returns the override entry when one exists and the LaunchDarkly entry otherwise. An enumeration is the union with the override entry winning. Initialization status is the base store's alone. - `Impl::Overrides::Sink` applies snapshots and notifies flag change listeners of every flag whose merged-view evaluation may have changed, including flags that depend on an overridden prerequisite or segment. - `DataSystem::ConfigBuilder#overrides` accepts one override source builder. The FDv2 data system builds it at construction, so an invalid configuration raises from `LDClient.new`, starts it before its run loop so the initial load is in effect before the constructor returns, serves reads through the overlay, and stops it when the client closes. Offline clients build no source. - The client consults the override store before the not-initialized short-circuit: an overridden flag is served before LaunchDarkly data arrives, and a flag that is not overridden still returns the client-not-ready default. `all_flags_state` reads through the overlay and, before initialization, returns only the overridden flags. A wrong-type migration result keeps the marking of the evaluation it replaces. - `FileData.make_flag_with_value` gains an off form, which the override source uses so that a value-only override reports the OFF reason kind. The file data sources keep their existing form. The OVERRIDE specification's test vectors run as a spec through the full client stack. The per-evaluation summary marker in the vectors is asserted once the event processor carries it. Flag overrides are currently experimental and subject to change.
kinyoklion
force-pushed
the
rlamb/overrides-ruby-model-evaluator
branch
from
September 28, 2026 20:36
4810ac9 to
20eea70
Compare
kinyoklion
force-pushed
the
rlamb/overrides-ruby-store-overlay
branch
from
September 28, 2026 20:36
e4d05bb to
09915cc
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR is stacked on #450 because it uses the override marker, the evaluator marking, and the reason indicator that PR adds.
This change adds the override layer that the OVERRIDE specification describes: a runtime-mutable collection of flag and segment definitions that takes precedence over LaunchDarkly data at the store read boundary, populated by an override source through a sink. With no override source configured the SDK behaves exactly as before. The file-based source, the events changes, and the contract test service follow in later PRs.
LaunchDarkly::Interfaces::Overrides::OverrideSourceandOverrideSinkdefine how a source supplies complete snapshots to the SDK. The sink accepts data model objects or hashes in the flag and segment data model. The SDK marks the entries itself.Impl::Overrides::Layerholds marked entries in an immutable hash that is swapped on update, so the layer holds exactly one snapshot at any instant and reads are lock-free.Impl::Overrides::Overlaysits at the store read boundary: a read for a key returns the override entry when one exists and the LaunchDarkly entry otherwise, an enumeration is the union with the override entry winning, and initialization status is the base store's alone.Impl::Overrides::Sinkapplies snapshots and notifies flag change listeners of every flag whose merged-view evaluation may have changed, including flags that depend on an overridden prerequisite or segment. It computes dependency edges over both the old and the new merged view, as the Go reference does.DataSystem::ConfigBuilder#overridesaccepts one override source builder, the samebuild(sdk_key, config)protocol as the data source builders. The FDv2 data system builds the source at construction, so an invalid configuration raises fromLDClient.newlike other invalid component configuration. It starts the source before its run loop, so the initial load is in effect before the constructor returns. It serves reads through the overlay and stops the source when the client closes. An offline client builds no source.The client consults the override store before the not-initialized short-circuit. An overridden flag is served before LaunchDarkly data arrives, and a flag that is not overridden still returns the client-not-ready default.
all_flags_statereads through the overlay and, before initialization, returns only the overridden flags, with a once-per-client warning. A wrong-type migration result keeps the marking of the evaluation it replaces.A value-only override expands, through the file loading code from #449, into a flag that is off and serves its single value, which reports the OFF reason kind as the specification describes.
The OVERRIDE specification's test vectors (
spec/fixtures/override-vectors/vectors.json) run as a spec through the full client stack, checking value, variation index, and reason under the vectors' comparison rules. The vectors' per-evaluation summary marker is asserted once the event processor carries the marking, in the events PR.One existing defect found while writing the sink is left as is and noted here:
Impl::DataStore::Storeseeds its dependency fan-out with symbol keys whileImpl::DependencyTrackerindexes dependents under the string keys that prerequisite and segment references use, so a LaunchDarkly data change through the FDv2 store never notifies dependent flags. The sink normalizes its own keys and is not affected.Verification: specs for the layer (marking, replacement, snapshot atomicity under concurrent writers), the overlay (precedence, union, deleted base items, base failure, initialization), the sink (added, removed, changed, and unchanged entries, dependency fan-out through prerequisites and nested segments, both merged views, no-listener path, base failure, serialized updates), the FDv2 wiring (construction, start order, overlay reads, stop, offline, availability unaffected), the client (not-ready gate, all-flags state, change notifications through the flag tracker, migration marker, lifecycle), and the specification vectors. Full suite and RuboCop are clean. Each new spec was checked against a deliberate defect in the code it covers.
The existing FDv1 and FDv2 file data sources keep their current behavior. This series does not change them; the override feature is additive.