chore: adds FDv1 Fallback support to FDv2 Data Source (#203)

**Requirements**

- [x] I have added test coverage for new or changed functionality
- [x] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
- [ ] I have validated my changes against all supported platform
versions
Will be done as final integration testing

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds FDv1 fallback to FDv2 data sources, triggered by the
`x-ld-fd-fallback` header and configured via SDK DataSystem to use a
polling fallback synchronizer.
> 
> - **FDv2 data source fallback**:
> - Add `FDv1FallbackActionApplier` in `FDv2DataSource` to switch from
FDv2 synchronizers to FDv1 synchronizers when `ErrorInfo.FDv1Fallback`
is true.
> - Include optional FDv1 synchronizers composite in the combined
`CompositeSource`.
> - **Error signaling**:
>   - Add `DataSourceStatus.ErrorInfo.FDv1Fallback` flag.
> - Set this flag in `FDv2PollingDataSource` and
`FDv2StreamingDataSource` when the `x-ld-fd-fallback` header is present
on HTTP errors.
> - **SDK config wiring (contract tests)**:
> - In `SdkClientEntity`, configure FDv1 polling fallback synchronizer
derived from the selected synchronizer and align global polling
`ServiceEndpoints` when a custom polling base URI is provided.
> - **Tests**:
> - Add tests covering header parsing, fallback triggering, and FDv1
synchronizer activation across polling/streaming and composite behavior.
> - Update `test-supressions-fdv2.txt` to reflect new FDv1 fallback
handling.
> - **Dependencies**:
> - Bump `LaunchDarkly.EventSource` to `5.3.0` and
`LaunchDarkly.InternalSdk` to `3.6.0`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
25910ad. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Ryan Lamb <[email protected]>

Author: tanderson-ld

pkgs/sdk/server/contract-tests/SdkClientEntity.cs

@@ -514,6 +514,45 @@ private static Configuration BuildSdkConfig(SdkConfigParams sdkParams, ILogAdapt
                     if (synchronizers.Count > 0)
                     {
                         dataSystemBuilder.Synchronizers(synchronizers.ToArray());
+                        
+                        // Find the best synchronizer to use for FDv1 fallback configuration
+                        // Prefer polling synchronizers since FDv1 fallback is polling-based
+                        SdkConfigSynchronizerParams synchronizerForFallback = null;
+                        
+                        // First, try to find a polling synchronizer (check secondary first, then primary)
+                        if (sdkParams.DataSystem.Synchronizers.Secondary != null && 
+                            sdkParams.DataSystem.Synchronizers.Secondary.Polling != null)
+                        {
+                            synchronizerForFallback = sdkParams.DataSystem.Synchronizers.Secondary;
+                        }
+                        else if (sdkParams.DataSystem.Synchronizers.Primary != null && 
+                                 sdkParams.DataSystem.Synchronizers.Primary.Polling != null)
+                        {
+                            synchronizerForFallback = sdkParams.DataSystem.Synchronizers.Primary;
+                        }
+                        // If no polling synchronizer found, use primary synchronizer (could be streaming)
+                        else if (sdkParams.DataSystem.Synchronizers.Primary != null)
+                        {
+                            synchronizerForFallback = sdkParams.DataSystem.Synchronizers.Primary;
+                        }
+                        
+                        if (synchronizerForFallback != null)
+                        {
+                            // Only configure global polling endpoints if we have a polling synchronizer with a custom base URI
+                            // This ensures the FDv1 fallback synchronizer uses the same base URI without overwriting
+                            // existing polling endpoint configuration
+                            if (synchronizerForFallback.Polling != null && 
+                                synchronizerForFallback.Polling.BaseUri != null)
+                            {
+                                endpoints.Polling(synchronizerForFallback.Polling.BaseUri);
+                            }
+                            
+                            var fdv1Fallback = CreateFDv1FallbackSynchronizer(synchronizerForFallback);
+                            if (fdv1Fallback != null)
+                            {
+                                dataSystemBuilder.FDv1FallbackSynchronizer(fdv1Fallback);
+                            }
+                        }
                     }
                 }
 
@@ -568,6 +607,33 @@ private static IComponentConfigurer<IDataSource> CreateSynchronizer(
             return null;
         }
 
+        private static IComponentConfigurer<IDataSource> CreateFDv1FallbackSynchronizer(
+            SdkConfigSynchronizerParams synchronizer)
+        {
+            // FDv1 fallback synchronizer is always polling-based
+            var fdv1PollingBuilder = DataSystemComponents.FDv1Polling();
+            
+            // Configure polling interval if the synchronizer has polling configuration
+            if (synchronizer.Polling != null)
+            {
+                if (synchronizer.Polling.PollIntervalMs.HasValue)
+                {
+                    fdv1PollingBuilder.PollInterval(TimeSpan.FromMilliseconds(synchronizer.Polling.PollIntervalMs.Value));
+                }
+                // Note: FDv1 polling doesn't support ServiceEndpointsOverride, so base URI
+                // will use the global service endpoints configuration
+            }
+            else if (synchronizer.Streaming != null)
+            {
+                // For streaming synchronizers, we still create a polling fallback
+                // Use default polling interval since streaming doesn't have a poll interval
+                // Note: FDv1 polling doesn't support ServiceEndpointsOverride, so base URI
+                // will use the global service endpoints configuration
+            }
+            
+            return fdv1PollingBuilder;
+        }
+
         private MigrationVariationResponse DoMigrationVariation(MigrationVariationParams migrationVariation)
         {
             var defaultStage = MigrationStageExtensions.FromDataModelString(migrationVariation.DefaultStage);

pkgs/sdk/server/contract-tests/test-supressions-fdv2.txt

@@ -5,6 +5,5 @@ streaming/retry behavior/do not retry after unrecoverable HTTP error on reconnec
 streaming/retry behavior/do not retry after unrecoverable HTTP error on reconnect/error 403
 streaming/retry behavior/do not retry after unrecoverable HTTP error on reconnect/error 405
 streaming/fdv2/reconnection state management/initializes from 2 polling initializers
-streaming/fdv2/fallback to FDv1 handling
 streaming/fdv2/disconnects on goodbye
 streaming/fdv2/reconnection state management/initializes from polling initializer

pkgs/sdk/server/src/Interfaces/DataSourceStatus.cs

@@ -80,6 +80,12 @@ public struct ErrorInfo
             /// </summary>
             public DateTime Time { get; set; }
 
+            /// <summary>
+            /// The error indicates to fall back to FDv1. (At the time of writing this, this was indicated
+            /// via the x-ld-fd-fallback header, but this may change in the future. This is just info for posterity.)
+            /// </summary>
+            public bool FDv1Fallback { get; set; }
+
             /// <summary>
             /// Constructs an instance based on an exception.
             /// </summary>

pkgs/sdk/server/src/Internal/FDv2DataSources/FDv2DataSource.cs

@@ -4,6 +4,7 @@
 using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Server.Interfaces;
 using LaunchDarkly.Sdk.Server.Subsystems;
+
 using static LaunchDarkly.Sdk.Server.Subsystems.DataStoreTypes;
 
 namespace LaunchDarkly.Sdk.Server.Internal.DataSources
@@ -16,7 +17,7 @@ internal static class FDv2DataSource
         /// <param name="updatesSink">the sink that receives updates from the active source</param>
         /// <param name="initializers">List of data source factories used for initialization</param>
         /// <param name="synchronizers">List of data source factories used for synchronization</param>
-        /// <param name="fdv1Synchronizers">List of data source factories used for FDv1 synchronization</param>
+        /// <param name="fdv1Synchronizers">List of data source factories used for FDv1 synchronization if fallback to FDv1 occurs</param>
         /// <returns>a new data source instance</returns>
         public static IDataSource CreateFDv2DataSource(
             IDataSourceUpdatesV2 updatesSink,
@@ -31,7 +32,7 @@ public static IDataSource CreateFDv2DataSource(
             ActionApplierFactory fastFallbackApplierFactory = (actionable) => new ActionApplierFastFallback(actionable);
             ActionApplierFactory timedFallbackAndRecoveryApplierFactory =
                 (actionable) => new ActionApplierTimedFallbackAndRecovery(actionable);
-
+            ActionApplierFactory fdv1FallbackApplierFactory = (actionable) => new FDv1FallbackActionApplier(actionable);
             var underlyingComposites = new List<(SourceFactory Factory, ActionApplierFactory ActionApplierFactory)>();
 
             // Only create the initializers composite if initializers are provided
@@ -71,13 +72,32 @@ public static IDataSource CreateFDv2DataSource(
 
                         return new CompositeSource(sink as IDataSourceUpdatesV2, synchronizersFactoryTuples);
                     },
-                    null // TODO: add fallback to FDv1 logic, null for the moment as once we're on the synchronizers, we stay there
+                    // Only attach FDv1 fallback applier if FDv1 synchronizers are actually provided
+                    (fdv1Synchronizers != null && fdv1Synchronizers.Count > 0) ? fdv1FallbackApplierFactory : null
                 ));
             }
 
-            var combinedCompositeSource = new CompositeSource(updatesSink, underlyingComposites, circular: false);
+            // Add the FDv1 fallback synchronizers composite if provided
+            if (fdv1Synchronizers != null && fdv1Synchronizers.Count > 0)
+            {
+                underlyingComposites.Add((
+                    // Create fdv1SynchronizersCompositeSource with action logic unique to fdv1Synchronizers
+                    (sink) =>
+                    {
+                        var fdv1SynchronizersFactoryTuples =
+                            new List<(SourceFactory Factory, ActionApplierFactory ActionApplierFactory)>();
+                        for (int i = 0; i < fdv1Synchronizers.Count; i++)
+                        {
+                            fdv1SynchronizersFactoryTuples.Add((fdv1Synchronizers[i], timedFallbackAndRecoveryApplierFactory)); // fdv1 synchronizers behave same as synchronizers
+                        }
+
+                        return new CompositeSource(sink as IDataSourceUpdatesV2, fdv1SynchronizersFactoryTuples);
+                    },
+                    null // no action applier for fdv1Synchronizers as a whole
+                ));
+            }
 
-            // TODO: add fallback to FDv1 logic
+            var combinedCompositeSource = new CompositeSource(updatesSink, underlyingComposites, circular: false);
 
             return combinedCompositeSource;
         }
@@ -265,5 +285,31 @@ public void Apply(ChangeSet<ItemDescriptor> changeSet)
                 _actionable.StartCurrent();
             }
         }
+
+        private class FDv1FallbackActionApplier : IDataSourceObserver
+        {
+            private readonly ICompositeSourceActionable _actionable;
+
+            public FDv1FallbackActionApplier(ICompositeSourceActionable actionable)
+            {
+                _actionable = actionable ?? throw new ArgumentNullException(nameof(actionable));
+            }
+
+            public void UpdateStatus(DataSourceState newState, DataSourceStatus.ErrorInfo? newError)
+            {
+                if (newError != null && newError.Value.FDv1Fallback)
+                {
+                    _actionable.BlacklistCurrent(); // blacklist the synchronizers altogether
+                    _actionable.DisposeCurrent(); // dispose the synchronizers
+                    _actionable.GoToNext(); // go to the FDv1 fallback synchronizer
+                    _actionable.StartCurrent(); // start the FDv1 fallback synchronizer
+                }
+            }
+
+            public void Apply(ChangeSet<ItemDescriptor> changeSet)
+            {
+                // this FDv1 fallback action applier doesn't care about apply, it only looks for the FDv1Fallback flag in the errors
+            }
+        }
     }
 }

pkgs/sdk/server/src/Internal/FDv2DataSources/FDv2PollingDataSource.cs

@@ -96,6 +96,15 @@ private async Task UpdateTaskAsync()
             catch (UnsuccessfulResponseException ex)
             {
                 var errorInfo = DataSourceStatus.ErrorInfo.FromHttpError(ex.StatusCode);
+                
+                // Check for LD fallback header
+                if (ex.Headers != null)
+                {
+                    errorInfo.FDv1Fallback = ex.Headers
+                        .Where(h => string.Equals(h.Key, "x-ld-fd-fallback", StringComparison.OrdinalIgnoreCase))
+                        .SelectMany(h => h.Value)
+                        .Any(v => string.Equals(v, "true", StringComparison.OrdinalIgnoreCase));
+                }
 
                 if (HttpErrors.IsRecoverable(ex.StatusCode))
                 {

pkgs/sdk/server/src/Internal/FDv2DataSources/FDv2PollingRequestor.cs

@@ -105,7 +105,7 @@ internal FDv2PollingRequestor(LdClientContext context, Uri baseUri)
 
                         if (!response.IsSuccessStatusCode)
                         {
-                            throw new UnsuccessfulResponseException((int)response.StatusCode);
+                            throw new UnsuccessfulResponseException((int)response.StatusCode, response.Headers);
                         }
 
                         lock (_etags)

pkgs/sdk/server/src/Internal/FDv2DataSources/FDv2StreamingDataSource.cs

@@ -275,6 +275,16 @@ private void OnError(object sender, ExceptionEventArgs e)
             {
                 var status = respEx.StatusCode;
                 errorInfo = DataSourceStatus.ErrorInfo.FromHttpError(status);
+                
+                // Check for LD fallback header
+                if (respEx.Headers != null)
+                {
+                    errorInfo.FDv1Fallback = respEx.Headers
+                        .Where(h => string.Equals(h.Key, "x-ld-fd-fallback", StringComparison.OrdinalIgnoreCase))
+                        .SelectMany(h => h.Value)
+                        .Any(v => string.Equals(v, "true", StringComparison.OrdinalIgnoreCase));
+                }
+                
                 RecordStreamInit(true);
                 if (!HttpErrors.IsRecoverable(status))
                 {

pkgs/sdk/server/src/LaunchDarkly.ServerSdk.csproj

@@ -40,8 +40,8 @@
   <ItemGroup>
     <PackageReference Include="LaunchDarkly.Cache" Version="1.0.2" />
     <PackageReference Include="LaunchDarkly.CommonSdk" Version="7.1.1" />
-    <PackageReference Include="LaunchDarkly.EventSource" Version="5.2.1" />
-    <PackageReference Include="LaunchDarkly.InternalSdk" Version="3.5.5" />
+    <PackageReference Include="LaunchDarkly.EventSource" Version="5.3.0" />
+    <PackageReference Include="LaunchDarkly.InternalSdk" Version="3.6.0" />
     <PackageReference Include="LaunchDarkly.Logging" Version="2.0.0" />
   </ItemGroup>
 

pkgs/sdk/server/test/Internal/FDv2DataSources/FDv2DataSourceTest.cs

@@ -1045,6 +1045,133 @@ public async Task CanDisposeWhenSynchronizersFallingBackUnthrottled()
             // The result may be true or false depending on implementation, but the key is that disposal works
         }
 
+        [Fact]
+        public async Task ErrorWithFDv1FallbackTriggersFallbackToFDv1Synchronizers()
+        {
+            // Create a capturing sink to observe all updates
+            var capturingSink = new CapturingDataSourceUpdatesWithHeaders();
+
+            // Track whether the synchronizer factory was invoked
+            bool synchronizerFactoryInvoked = false;
+            IDataSourceUpdatesV2 synchronizerUpdateSink = null;
+
+            // Create synchronizer factory: emits Initializing, then reports Interrupted with FDv1Fallback error
+            SourceFactory synchronizerFactory = (updatesSink) =>
+            {
+                synchronizerFactoryInvoked = true;
+                synchronizerUpdateSink = updatesSink;
+                var source = new MockDataSourceWithInit(
+                    async () =>
+                    {
+                        // Emit Initializing
+                        updatesSink.UpdateStatus(DataSourceState.Initializing, null);
+                        await Task.Delay(10);
+
+                        // Report Interrupted with error that has FDv1Fallback = true
+                        var errorInfo = new DataSourceStatus.ErrorInfo
+                        {
+                            Kind = DataSourceStatus.ErrorKind.ErrorResponse,
+                            StatusCode = 503,
+                            FDv1Fallback = true,
+                            Time = DateTime.Now
+                        };
+                        updatesSink.UpdateStatus(DataSourceState.Interrupted, errorInfo);
+                        await Task.Delay(10);
+                    }
+                );
+                return source;
+            };
+
+            // Track whether the fdv1Synchronizer factory was invoked
+            bool fdv1SynchronizerFactoryInvoked = false;
+            IDataSourceUpdatesV2 fdv1SynchronizerUpdateSink = null;
+
+            // Create dummy data for fdv1Synchronizer
+            var fdv1SynchronizerDummyData = new FullDataSet<ItemDescriptor>(new Dictionary<DataKind, KeyedItems<ItemDescriptor>>());
+
+            // Create fdv1Synchronizer factory: emits Initializing, calls init with dummy data, then reports Valid
+            SourceFactory fdv1SynchronizerFactory = (updatesSink) =>
+            {
+                fdv1SynchronizerFactoryInvoked = true;
+                fdv1SynchronizerUpdateSink = updatesSink;
+                var source = new MockDataSourceWithInit(
+                    async () =>
+                    {
+                        // Emit Initializing
+                        updatesSink.UpdateStatus(DataSourceState.Initializing, null);
+                        await Task.Delay(10);
+
+                        // Report Valid
+                        updatesSink.UpdateStatus(DataSourceState.Valid, null);
+                        await Task.Delay(10);
+
+                        // Call Apply with dummy data
+                        updatesSink.Apply(new ChangeSet<ItemDescriptor>(
+                            ChangeSetType.Full,
+                            Selector.Empty,
+                            fdv1SynchronizerDummyData.Data,
+                            null
+                        ));
+                        await Task.Delay(10);
+                    }
+                );
+                return source;
+            };
+
+            // Create FDv2DataSource with no initializers, one synchronizer, and one fdv1Synchronizer
+            var initializers = new List<SourceFactory>();
+            var synchronizers = new List<SourceFactory> { synchronizerFactory };
+            var fdv1Synchronizers = new List<SourceFactory> { fdv1SynchronizerFactory };
+
+            var dataSource = FDv2DataSource.CreateFDv2DataSource(
+                capturingSink,
+                initializers,
+                synchronizers,
+                fdv1Synchronizers
+            );
+
+            // Start the data source
+            var startTask = dataSource.Start();
+
+            // Wait for status updates - we expect:
+            // 1. Initializing (from synchronizer)
+            // 2. Interrupted (from synchronizer with FDv1Fallback error)
+            // 3. Interrupted (initializing from fdv1Synchronizer is mapped to interrupted by sanitizer after fallback)
+            // 4. Valid (from fdv1Synchronizer)
+            var statusUpdates = capturingSink.WaitForStatusUpdates(4, TimeSpan.FromSeconds(5));
+
+            // Verify that Start() completed successfully
+            var startResult = await startTask;
+            Assert.True(startResult);
+
+            // Verify status updates
+            Assert.True(statusUpdates.Count >= 4, $"Expected at least 4 status updates, got {statusUpdates.Count}");
+
+            // Position 0: Initializing (from synchronizer)
+            Assert.Equal(DataSourceState.Initializing, statusUpdates[0].State);
+
+            // Position 1: Interrupted (from synchronizer with FDv1Fallback error)
+            Assert.Equal(DataSourceState.Interrupted, statusUpdates[1].State);
+            Assert.NotNull(statusUpdates[1].LastError);
+            Assert.True(statusUpdates[1].LastError.Value.FDv1Fallback, "FDv1Fallback should be true in the error");
+
+            // Position 2: Interrupted (initializing from fdv1Synchronizer is mapped to interrupted by sanitizer after fallback)
+            Assert.Equal(DataSourceState.Interrupted, statusUpdates[2].State);
+
+            // Position 3: Valid (from fdv1Synchronizer)
+            Assert.Equal(DataSourceState.Valid, statusUpdates[3].State);
+
+            // Verify that both factories were invoked
+            Assert.True(synchronizerFactoryInvoked, "Synchronizer factory should have been invoked");
+            Assert.True(fdv1SynchronizerFactoryInvoked, "FDv1Synchronizer factory should have been invoked after fallback");
+
+            // Verify that Apply was called with fdv1Synchronizer dummy data
+            var changeSet = capturingSink.Applies.ExpectValue(TimeSpan.FromSeconds(1));
+            Assert.Equal(ChangeSetType.Full, changeSet.Type);
+
+            dataSource.Dispose();
+        }
+
 
         // Mock data source that executes an async action when started
         private class MockDataSourceWithInit : IDataSource