Skip to content

feat: Add the override store, overlay, and data system wiring - #527

Draft
kinyoklion wants to merge 1 commit into
rlamb/overrides-python-model-markerfrom
rlamb/overrides-python-override-store
Draft

kinyoklion wants to merge 1 commit into
rlamb/overrides-python-model-markerfrom
rlamb/overrides-python-override-store

Conversation

@kinyoklion

Copy link
Copy Markdown
Member

Summary

This is the third step of the flag overrides port described by the OVERRIDE specification. It is based on the model marker branch because the phases are stacked; retarget to feat/overrides once that branch merges.

The override layer (ldclient/impl/overrides). OverrideLayer is the override store: it holds marked shallow copies of the flag and segment definitions a source supplies, keyed by key, and is replaced wholesale on each update, so the layer's contents are exactly one snapshot at any instant and an empty snapshot clears it. Dictionaries are decoded with the model constructors, and an invalid definition raises rather than being defaulted. OverrideStoreView is the overlay at the store read boundary: a read of a flag or segment returns the override entry when one exists and the LaunchDarkly entry otherwise, whatever the state of the base store, and an enumeration is the union of both with the override entry winning, including over a deleted item. When the base enumeration fails and the layer holds entries, the layer's entries are returned alone. OverrideSinkImpl applies each snapshot as one serialized operation and notifies flag change listeners of every flag whose merged-view evaluation may have changed: entries added, removed, or changed, plus every flag that depends on them through prerequisites or segment references. An identical snapshot notifies nothing.

Configuration and wiring. OverrideSource and OverrideSink are public protocols in ldclient.interfaces, so a custom source can be supplied. OverrideSourceBuilder and DataSystemConfig.override_source (also on AsyncDataSystemConfig) plus ConfigBuilder.overrides(...) make the source an option of the FDv2 data system. The source is built with the data system, so invalid configuration raises from the client constructor like any other invalid component configuration. It starts before the data system's own threads and its initial load completes before the constructor returns; it is closed when the client is closed; it is not started when the client is offline. The data system's store becomes the overlay when a source is configured, so evaluation, prerequisite and segment resolution, and the all-flags read all see override precedence. The override source has no effect on initialization status, data availability, or data source status. The legacy FDv1 data system reports no override source.

The client facade. Both LDClient and AsyncLDClient consult the override store before the not-initialized short-circuit: an overridden flag is served before the client has LaunchDarkly data, and a flag absent from the override store still returns the client-not-ready default with the same warning and event as before. The all-flags state reads through the overlay; while the client has no LaunchDarkly data it contains only the overridden flags (with a once-per-client warning) and is invalid when the layer is empty. On the async client, override change notifications are marshalled onto the event loop, like every other change notification.

Tests. Unit tests for the layer, overlay (sync and async), and sink; client tests for the gate, source lifecycle, construction errors, offline, precedence, prerequisite and segment overrides, all-flags state, and flag change and flag value change listeners, for both clients; and a runner for the OVERRIDE specification test vectors (ldclient/testing/testdata/override-vectors/vectors.json) through the full client stack. The vector runner's per-evaluation summary marker assertion is added with the events step.

Adds the override layer described by the OVERRIDE specification: an override
store that holds marked flag and segment definitions, an overlay at the store
read boundary that returns the override entry for a key in preference to
LaunchDarkly data and enumerates the union of both, and a sink that applies
each snapshot as a single replacement and notifies flag change listeners of
every flag whose evaluation may have changed, including flags that depend on
a changed prerequisite or segment.

The override source is an option of the FDv2 data system configuration:
DataSystemConfig.override_source and ConfigBuilder.overrides(). The source
is built with the data system, so invalid configuration raises from the
client constructor. It starts before the data system's own threads, so its
initial load completes before the constructor returns, and it is closed with
the client. OverrideSource and OverrideSink are public protocols so a custom
source can be supplied.

The client consults the override store before its not-initialized
short-circuit. An overridden flag is served before the client has
LaunchDarkly data, and a flag absent from the override store still returns
the client-not-ready default. The all-flags state reads through the overlay
and, while the client has no LaunchDarkly data, contains only the overridden
flags. The async client and data system receive the same changes, with
override change notifications delivered on the event loop.

The OVERRIDE specification test vectors run as a unit test through the full
client stack.
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-python-model-marker branch from 34322d8 to ee313c1 Compare September 28, 2026 20:28
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-python-override-store branch from 3fcdc80 to 19f88eb Compare September 28, 2026 20:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant