Skip to content

feat: Add reload infrastructure for file-based flag overrides - #220

Draft
kinyoklion wants to merge 1 commit into
feat/overridesfrom
rlamb/overrides-java-filedata-reloader
Draft

kinyoklion wants to merge 1 commit into
feat/overridesfrom
rlamb/overrides-java-filedata-reloader

Conversation

@kinyoklion

@kinyoklion kinyoklion commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Summary

The flag overrides feature defined by the OVERRIDE specification needs a file source that reloads reliably: coalesced change notifications, retry after a failed read, retention of the last good data, sequential reloads, and support for files that do not exist yet. This change adds that infrastructure to the integrations package for the file-based override source that follows. It is purely additive: the existing file data source keeps its current behavior.

  • FileDataReloader serializes reloads, debounces change signals with a 100 ms settle window, keeps the last good data on failure by not applying, retries a failed load after one second, reports an identical repeated failure once, and skips a reload whose raw content did not change. Close never waits for an in-flight read.
  • FileDataPoller detects changes by examining each file's modification time and size on a fixed interval, including a file that appears or disappears.
  • FileDataWatcher watches parent directories through the file system watch service and signals once after start so a change made between an initial load and the start of watching is not missed.
  • OverrideFileLoader reads a list of files with the override source's rules: a file that does not exist contributes no entries, entries keep the versions that the documents specify, a value-only entry becomes a flag that is off and serves the value, a document that parses but holds a flag the model rejects is reported as a file data error, and the result carries a per-file summary and a content digest. It shares only the parsing code (FlagFileParser) with the file data source, plus two new FlagFactory methods that keep document versions.

The existing file data source keeps its current behavior: FileDataSourceImpl, FileSynchronizer, FileInitializer, FileDataSourceBase, and FileDataSourceParsing.FileDataException are unchanged from feat/overrides (the only edit to a legacy file is the two additive FlagFactory methods). It still requires every configured file to exist, assigns a load version to every entry, expands a value-only entry to an on flag with a single fallthrough variation, reloads on every watch event with no debounce, no retry timer, and no skip, and reports every failure. Two new test classes pin that behavior: FileSynchronizerReloadBehaviorTest (identical rewrite emits another change set, every failed reload is reported and logged as the plain description at error level, no retry without a file change, missing file logged with the path) and FileDataLoadingBehaviorTest (a model-rejected document escapes as a SerializationException, and FileDataException.getDescription requires a cause). The baseline test files pass unmodified.

The flag overrides feature needs a file source that reloads reliably:
coalesced change notifications, retry after a failed read, retention of
the last good data, sequential reloads, and support for files that do
not exist yet. This adds that infrastructure to the integrations package
as a purely additive change. The existing file data source keeps its
current behavior.

- FileDataReloader serializes reloads, debounces change signals, keeps
  the last good data on failure by not applying, retries a failed load
  after a bounded delay, reports an identical repeated failure once, and
  skips a reload whose raw content did not change. Close never waits for
  an in-flight read.
- FileDataPoller detects changes by examining each file's modification
  time and size on a fixed interval, including a file that appears or
  disappears.
- FileDataWatcher watches parent directories and signals once after
  start so a change between an initial load and the start of watching is
  not missed.
- OverrideFileLoader reads a list of files with the override source's
  rules: a missing file contributes no entries, entries keep the
  versions that the documents specify, a value-only entry becomes a flag
  that is off and serves the value, a document that the model rejects is
  a file data error, and the result carries a per-file summary and a
  content digest. Two additive FlagFactory methods keep document
  versions.

FileDataSourceImpl, FileSynchronizer, FileInitializer,
FileDataSourceBase, and FileDataException are unchanged. Two new test
classes pin the file data source's reload and error behavior: a reload
on every watch event with no debounce, no retry, and no skip, every
failure reported and logged as the plain description at error level, a
model-rejected document escaping as a SerializationException, and a
description that requires a cause.
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-java-filedata-reloader branch from f0038ed to 79250a7 Compare September 28, 2026 21:03
@kinyoklion kinyoklion changed the title feat: Add debounce, retry, and last-good retention to file data loading feat: Add reload infrastructure for file-based flag overrides Sep 28, 2026

This branch has not been deployed

No deployments
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