feat: Add the override layer, the store overlay, and the override source configuration by kinyoklion · Pull Request #222 · launchdarkly/java-core

kinyoklion · 2026-09-25T23:11:00Z

Summary

This adds the override layer that the OVERRIDE specification describes: an override source supplies complete snapshots of flag and segment definitions to an override store, and an overlay at the store read boundary returns the store's entry for a key in preference to LaunchDarkly data. Evaluation, prerequisite and segment resolution, and the all-flags state all read through the overlay, so an override is a full definition that evaluates like any other. Overrides do not take part in the data system: they have no effect on initialization status, data availability, or data source status, and they are never written to a persistent store.

Public surface, all marked experimental and subject to change:

DataSystemBuilder.overrides(ComponentConfigurer<OverrideSource>) and DataSystemConfiguration.getOverrideSource(). The option lives on the FDv2 data system builder only. An FDv1 data source configuration has no place to supply one.
subsystems.OverrideSource (start with a sink, close) and subsystems.OverrideSink (replace the whole layer with one snapshot). The SDK builds the source like any other component, starts it before the data source so its initial load completes during client construction, and closes it with the client; the sink stops accepting snapshots before the source is closed, and an exception from the source's close is logged while the rest of the shutdown proceeds. An offline client does not build or start the override source, and logs a warning that it does not. A source that cannot be built fails client construction the same way other invalid component configuration does. An exception from the source's start does not: the SDK logs it, closes the source, clears anything the source supplied before failing, and the client runs without overrides.

Internals:

OverrideLayer holds marked shallow copies of the supplied entities in an immutable map that is swapped on each update. The source's objects are never modified.
OverrideOverlayStore implements the read boundary: per-key reads prefer the layer, enumeration is the union with override precedence, and a failure of the base store propagates, as it does without the overlay.
OverrideSinkImpl serializes snapshot application and fires the normal flag change notifications for every flag whose merged-view evaluation may have changed, using the dependency tracker over both the old and the new merged views so prerequisite and segment dependents are included.
The not-initialized short-circuit consults the layer first: a flag that the layer holds is served before the client has LaunchDarkly data, and any other flag returns the client-not-ready default as before. Before the store is initialized, the all-flags state contains only the flags that the layer holds, read from the layer rather than the merged store so that LaunchDarkly data in a store without an init marker stays out, and it logs once that it returned only override entries; with no override flags the state is invalid, as it is without a source. Without a source this state is empty, because the SDK reports no flags before the store is initialized, so the override flags only add to what it reports; overrides never remove a flag from the state. When the store fails to list its flags, the failure is logged as before; the state, invalid and empty without a source, then holds the override layer's flags and stays invalid (empty and invalid when the layer holds no flags), because a client-side SDK bootstrapped from it uses its flags whatever $valid says. The all-flags state presents an override-affected flag with trackEvents and trackReason false and no debugEventsUntilDate.

The OVERRIDE specification's test vectors run as a unit test through the full client stack (value, variation index, and reason). The per-evaluation summary marker in the vectors is asserted by the events change that follows.

This PR depends on the model and evaluator marking change (rlamb/overrides-java-model-marker) and is based on that branch; retarget it to feat/overrides once that branch merges.

The existing file data source keeps its current behavior; this change does not touch its code paths.

SDK-3246

Follow-ups from review

A LaunchDarkly change now notifies the flags whose overrides depend on it. The override layer keeps the dependency edges of its own entries, rebuilt on every replacement, and DataSourceUpdatesImpl expands each changed LaunchDarkly item through both its own tracker and the layer's until nothing new is reached, so an override that matches a LaunchDarkly segment or has a LaunchDarkly prerequisite is notified like the LaunchDarkly flags that depend on it.
isFlagKnown consults the override layer before the not-initialized short circuit, the same as evaluation does, so an override-only flag is known while the client is uninitialized.
When the evaluation of a flag throws during allFlagsState, the EXCEPTION result carries that flag's own override marking, so an overridden flag keeps its marked reason with event tracking off.

Note

Overview
Adds experimental flag/segment overrides for the FDv2 data system: operators can configure an OverrideSource via DataSystemBuilder.overrides() that pushes full snapshots into an internal layer; reads go through OverrideOverlayStore so per-key override definitions win over LaunchDarkly data without affecting init status or persistence.

FDv2 wiring builds and starts the override source before the main data source (skipped offline); start failures log, close the source, clear the layer, and the client continues without overrides. OverrideSinkImpl applies snapshots and emits flag-change events from merged-view diffs plus dependency fan-out.

Evaluation and client API changes: overridden flags evaluate before the not-initialized short-circuit; isFlagKnown treats override-only flags as known when uninitialized; allFlagsState can return only layer flags before init (or when listing the store fails) and turns off per-flag event tracking when results are override-affected.

LaunchDarkly update notifications now cross the override boundary: DataSourceUpdatesImpl expands affected items through both the store dependency graph and the layer’s ExternalDependencies, so LD segment/prerequisite changes reach dependent overridden flags.

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

_{Opened from termag}

kinyoklion · 2026-10-03T01:23:34Z

bugbot review

cursor