chore: Add FDv2 data source interfaces. #100

kinyoklion · 2026-01-13T18:55:58Z

BEGIN_COMMIT_OVERRIDE
chore: Add FDv2 data source interfaces.
chore: Add FDv2 polling data source.
chore: Scaffold FDv2 Data Source.
END_COMMIT_OVERRIDE

Note

Adds an experimental FDv2 data source pipeline with polling and change propagation.

Implements DefaultFDv2Requestor for FDv2 HTTP polling with version/state query params, ETag caching, header passthrough, and robust error handling
Introduces FDv2SourceResult, Initializer, Synchronizer, and SelectorSource interfaces and FDv2DataSource coordinator to run initializers then synchronizers
Provides PollingBase, PollingInitializerImpl, and PollingSynchronizerImpl (scheduled) to process events, map errors, and emit ChangeSet/status updates
Adds FDv2ChangeSetTranslator to convert FDv2 changes to DataStoreTypes.ChangeSet (flags/segments), with logging for unknown kinds
Adds IterableAsyncQueue utility for async result delivery
Extends StandardEndpoints with FDV2_POLLING_REQUEST_PATH and FDV2_STREAMING_REQUEST_PATH
Extensive unit tests for requestor, translator, initializer/synchronizer behaviors and queue

^{Written by Cursor Bugbot for commit 117b85c. This will update automatically on new commits. Configure here.}

kinyoklion · 2026-01-13T18:59:16Z

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/FDv2SourceResult.java

+     */
+    public static class Status {
+        private final State state;
+        private final DataSourceStatusProvider.ErrorInfo errorInfo;


I don't particularly care for this type, but also we may not want what is effectively a duplicate.

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/FDv2SourceResult.java

tanderson-ld · 2026-01-13T19:10:37Z

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/FDv2SourceResult.java

+ * an FDv2 synchronizer produces a stream of results.
+ */
+public class FDv2SourceResult {
+    public enum State {


Do you want running in this enum?

Maybe I shouldn't call it State. Its more like a notification of change, and it doesn't represents valid/running because that is handled by a changeset.

tanderson-ld · 2026-01-13T19:18:00Z

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/FDv2SourceResult.java

+        /**
+         * The data source has been instructed to disconnect and will not produce any further results.
+         */
+        GOODBYE,


The current description of GOODBYE and SHUTDOWN leaves room for me to think GOODBYE -> SHUTDOWN could be a thing.

I see the diagrams in the specific ones down below that shows that is not possible, but the enum details make it look like it could be?

GOODBYE is effectively a more specific shutdown. We didn't handle it in .Net because SDKs generally don't seem to have handled it yet, but it also is really hard to handle with data source updates.

Basically in .Net we had an overload broad OFF and it is hard to get the correct behavior because there were are really 2-3 different meanings. Overall we don't need to emit any data source status in most situations for something being shutdown or something being told to exit by flag delivery (but we may handle them different, I am still unsure how to handle goodbye).

SHUTDOWN means I asked the thing to shutdown.
GOODBYE means that FD or some external source asked it to disconnect. Having it different means we can decide to do something different. (I think just by entering this situation we handle most of the problems, because we can be like, cool we aren't running anymore, I don't care about this disconnect I just got from the event source.)
TERMINAL_ERROR means something has gone wrong.

…-interfaces

lib/sdk/server/build.gradle

…dd-fdv2-data-source-interfaces

kinyoklion · 2026-01-14T19:12:10Z

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

This is very early scaffold that gives an idea how this stuff would connect together.

kinyoklion · 2026-01-14T19:12:45Z

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/IterableAsyncQueue.java

Convenience class that allows for easy mapping of producer/consumer to an iterator.

kinyoklion · 2026-01-14T19:13:23Z

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java

Encapsulates all the poll-specific logic which is then used by the polling synchronizer/initializer.

…unchdarkly/java-core into rlamb/add-fdv2-data-source-interfaces

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/IterableAsyncQueue.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/DefaultFDv2Requestor.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

cursor · 2026-01-15T18:32:04Z

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

+            }
+            runSynchronizers();
+            // TODO: Handle. We have ran out of sources or we are shutting down.
+        });


Missing startFuture completion when sources exhausted

High Severity

When all data sources are exhausted without receiving data (all initializers and synchronizers fail or lists are empty), startFuture is never completed. The TODO comment at line 99 acknowledges this needs handling but nothing is implemented. Any caller waiting on start().get() without a timeout would block forever since startFuture.complete() is only called in close() or upon successful data receipt.

Yep. Not implemented in this PR.

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingSynchronizerImpl.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/DefaultFDv2Requestor.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/IterableAsyncQueue.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java

cursor · 2026-01-15T23:29:42Z

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/FDv2SourceResult.java

+    public static FDv2SourceResult goodbye(String reason) {
+        // TODO: Goodbye reason.
+        return new FDv2SourceResult(null, new Status(State.GOODBYE, null), ResultType.STATUS);
+    }


Method parameter reason is silently discarded

Low Severity

The goodbye(String reason) method accepts a reason parameter but completely ignores it, passing null to the Status constructor instead. When PollingBase calls FDv2SourceResult.goodbye() with the reason extracted from the protocol handler, that diagnostic information is silently discarded. This makes debugging connection termination issues harder since the server's provided reason (e.g., "service-unavailable") is lost.

Additional Locations (1)

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java#L121-L123

Will be handled in a future update.

tanderson-ld and others added 6 commits January 12, 2026 11:47

chore: adds fdv2 payload parsing and protocol handling

19d9c02

adding package info files and fixing package name issue

fbea872

more checkstyle fixes

adcaa0e

chore: Add interfaces for synchronizer/initializer.

f2b209d

Merge branch 'main' into rlamb/add-fdv2-data-source-interfaces

8c115cc

Revert version change

de2fded

kinyoklion commented Jan 13, 2026

View reviewed changes

tanderson-ld reviewed Jan 13, 2026

View reviewed changes

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/FDv2SourceResult.java Outdated Show resolved Hide resolved

tanderson-ld reviewed Jan 13, 2026

View reviewed changes

kinyoklion added 4 commits January 13, 2026 14:19

feat: Add FDv2 polling support.

98d3b39

Merge remote-tracking branch 'origin' into rlamb/add-fdv2-data-source…

da3c639

…-interfaces

WIP: Polling initializer/synchronizer.

8fb88ed

Use updated internal lib.

da27015

kinyoklion changed the title ~~Rlamb/add fdv2 data source interfaces~~ chore: Add FDv2 data source interfaces. Jan 14, 2026

kinyoklion added 3 commits January 13, 2026 16:25

Update comment

aba46ef

Add termination.

7401331

Remove test file that isn't ready.

bba0cdc

kinyoklion commented Jan 14, 2026

View reviewed changes

lib/sdk/server/build.gradle Outdated Show resolved Hide resolved

kinyoklion commented Jan 14, 2026

View reviewed changes

lib/sdk/server/build.gradle Outdated Show resolved Hide resolved

kinyoklion added 5 commits January 13, 2026 17:39

Polling tests and some fixes.

89bd017

Try pre block.

228f3e6

Add streaming path.

9469b23

Merge branch 'main' of github.com:launchdarkly/java-core into rlamb/a…

9a450e6

…dd-fdv2-data-source-interfaces

Use the DataStoreTypes.ChangeSet type for data source results.

4b8313b

kinyoklion force-pushed the rlamb/add-fdv2-data-source-interfaces branch from dcbd9fd to 4b8313b Compare January 14, 2026 19:00

Make iterable async queue package private.

31eb13e

kinyoklion commented Jan 14, 2026

View reviewed changes

kinyoklion added 3 commits January 15, 2026 09:10

Merge branch 'main' into rlamb/add-fdv2-data-source-interfaces

a90b536

PR feedback

8d3e869

Merge branch 'rlamb/add-fdv2-data-source-interfaces' of github.com:la…

295138a

…unchdarkly/java-core into rlamb/add-fdv2-data-source-interfaces

cursor bot reviewed Jan 15, 2026

View reviewed changes

kinyoklion added 4 commits January 15, 2026 09:46

Don't double queue async items

ff02c1e

More comments

f805c7e

PR feedback

71130ac

Fix polling recoverable logic error.

bd8e72b

cursor bot reviewed Jan 15, 2026

View reviewed changes

kinyoklion added 4 commits January 15, 2026 10:12

Better testing

ff95a85

Guard source shutdown

fd6c3af

More safe closing.

8243b82

Correct serialization error type.

962afb7

tanderson-ld approved these changes Jan 15, 2026

View reviewed changes

cursor bot reviewed Jan 15, 2026

View reviewed changes

Polling better goodbye handling.

fc24f63

cursor bot reviewed Jan 15, 2026

View reviewed changes

kinyoklion added 4 commits January 15, 2026 10:50

Fix exception type.

e6edc88

Fix early return

1821373

EMPTY selector.

bc10b18

More PR feedback.

47d55c3

cursor bot reviewed Jan 15, 2026

View reviewed changes

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java Outdated Show resolved Hide resolved

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java Show resolved Hide resolved

Remove unsafe cast from throwable to exception.

201a92c

cursor bot reviewed Jan 15, 2026

View reviewed changes

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/IterableAsyncQueue.java Outdated Show resolved Hide resolved

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/FDv2DataSource.java Show resolved Hide resolved

cursor bot reviewed Jan 15, 2026

View reviewed changes

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/PollingBase.java Outdated Show resolved Hide resolved

Async iterable tests.

117b85c

kinyoklion force-pushed the rlamb/add-fdv2-data-source-interfaces branch from d7385d9 to 117b85c Compare January 15, 2026 23:16

cursor bot reviewed Jan 15, 2026

View reviewed changes

kinyoklion merged commit bef2500 into main Jan 15, 2026
21 checks passed

kinyoklion deleted the rlamb/add-fdv2-data-source-interfaces branch January 15, 2026 23:31

chore: Add FDv2 data source interfaces. #100

chore: Add FDv2 data source interfaces. #100

Uh oh!

Conversation

kinyoklion commented Jan 13, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot Jan 15, 2026

Choose a reason for hiding this comment

Missing startFuture completion when sources exhausted

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot Jan 15, 2026

Choose a reason for hiding this comment

Method parameter reason is silently discarded

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kinyoklion commented Jan 13, 2026 •

edited by cursor bot

Loading

Method parameter `reason` is silently discarded