feat: Add the file-based override source - #529
Draft
kinyoklion wants to merge 1 commit into
Draft
kinyoklion wants to merge 1 commit into
kinyoklion wants to merge 1 commit into
Conversation
Adds ldclient.integrations.overrides.FileOverrideSourceBuilder, the file-based override source described by the OVERRIDE specification. The source reads one or more JSON or YAML files in the file data source document format, with optional flags, flagValues, and segments members, and supplies each successful load to the SDK's override sink as a full snapshot. Files are combined in the configured order. The duplicate keys handling is fail by default, which rejects the reload and keeps the previously loaded overrides, or ignore, which keeps the first file's entry. A configured file that does not exist contributes no overrides, so a file can be created later and deleting a file removes its overrides. A file that exists but cannot be read or parsed fails that reload, the last good overrides stay in effect, the failure is logged, and the load is retried after a bounded delay and on the next detected change. Change detection is one of two modes: polling, the default, examines the files once per second by default with a one second minimum, and watching reacts to file system notifications through the watchdog package. Watching without the watchdog package and a builder with no paths are construction errors. The initial load completes during client construction. Every applied change is logged at Info level with the overrides in effect and what each configured file supplied.
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 is the fifth step of the flag overrides port described by the OVERRIDE specification. It is based on the events branch because the phases are stacked; retarget to
feat/overridesonce that branch merges.ldclient.integrations.overrides.FileOverrideSourceBuilderis the public entry point. It is passed todatasystem.ConfigBuilder.overrides(...)and builds an override source that reads one or more local files in the file data source document format (optionalflags,flagValues, andsegmentsmembers, JSON or YAML) and supplies each successful load to the SDK's override sink as a full snapshot.flagValuesentries expand into full flag definitions through the shared file data code, so the layer holds only full entities.Behavior:
duplicate_keys_handlingisfailby default, which rejects the reload and keeps the previously loaded overrides, orignore, which keeps the first configured file's entry.change_detectionis one of two alternatives.polling(the default) compares modification time and size on an interval, one second by default with a one second minimum; a lower interval is raised to the minimum with a warning.watchinguses thewatchdogpackage and is a construction error when the package is not installed. Notifications are debounced so a burst from one edit produces one reload.start, which the data system calls during client construction, so an override present at startup takes effect from the first evaluation.Flag overrides in effect: 2 flags, 1 segment (/etc/ld/a.json: 2 flags, 1 segment; /etc/ld/b.json: absent), orFlag overrides: none in effect (...).change_detectionorduplicate_keys_handlingvalues raiseValueErrorwhen set. This is stricter than the Go builder, which treats an unrecognized duplicate keys handling asfail.The module is added to the API reference (
docs/api-integrations.rst) and every public docstring carries the experimental note.Tests cover the builder validation and defaults, synchronous initial load, YAML, multi-file order and duplicate handling, absent files appearing and disappearing, the Info log lines, both change detection modes, last-good retention across a malformed edit in both modes, the automatic retry with no change signal, close semantics, and an end-to-end run through
LDClientwhere a file is added, changed, and emptied while the client never receives LaunchDarkly data.