launchdarkly · tanderson-ld · Dec 17, 2025 · Dec 1, 2025 · Dec 2, 2025 · Dec 3, 2025
@@ -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>

@@ -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,31 @@ 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
+                    fdv1FallbackApplierFactory
                 ));
             }
 
-            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 +284,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
+            }
+        }
     }
 }
@@ -96,6 +96,12 @@ 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.Any(h => string.Equals(h.Key, "x-ld-fd-fallback", StringComparison.OrdinalIgnoreCase));
+                }
 
                 if (HttpErrors.IsRecoverable(ex.StatusCode))
                 {

@@ -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)

@@ -275,6 +275,13 @@ 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.Any(h => string.Equals(h.Key, "x-ld-fd-fallback", StringComparison.OrdinalIgnoreCase));
+                }
+
                 RecordStreamInit(true);
                 if (!HttpErrors.IsRecoverable(status))
                 {

@@ -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>
 

@@ -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

@@ -1,6 +1,9 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Net;
+using System.Net.Http;
+using System.Net.Http.Headers;
 using System.Text.Json;
 using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Internal.Http;
@@ -818,5 +821,91 @@ public async Task JsonErrorInEventHasInvalidDataErrorKind()
                 Assert.True(dataSource.Initialized);
             }
         }
+
+        [Fact]
+        public void RecoverableHttpErrorWithFallbackHeaderSetsFDv1Fallback()
+        {
+            // Create an HttpResponseMessage with the fallback header
+            using (var response = new HttpResponseMessage((HttpStatusCode)503))
+            {
+                response.Headers.Add("x-ld-fd-fallback", "true");
+                var exception = new UnsuccessfulResponseException(503, response.Headers);
+
+                _mockRequestor.Setup(r => r.PollingRequestAsync(It.IsAny<Selector>()))
+                    .ThrowsAsync(exception);
+
+                using (var dataSource = MakeDataSource())
+                {
+                    _ = dataSource.Start();
+
+                    var status = _updateSink.StatusUpdates.ExpectValue();
+                    Assert.Equal(DataSourceState.Interrupted, status.State);
+                    Assert.NotNull(status.LastError);
+                    Assert.Equal(DataSourceStatus.ErrorKind.ErrorResponse, status.LastError.Value.Kind);
+                    Assert.Equal(503, status.LastError.Value.StatusCode);
+                    Assert.True(status.LastError.Value.FDv1Fallback, "FDv1Fallback should be true when fallback header is present");
+
+                    Assert.False(dataSource.Initialized);
+                }
+            }
+        }
+
+        [Fact]
+        public async Task UnrecoverableHttpErrorWithFallbackHeaderSetsFDv1Fallback()
+        {
+            // Create an HttpResponseMessage with the fallback header
+            using (var response = new HttpResponseMessage((HttpStatusCode)401))
+            {
+                response.Headers.Add("x-ld-fd-fallback", "true");
+                var exception = new UnsuccessfulResponseException(401, response.Headers);
+
+                _mockRequestor.Setup(r => r.PollingRequestAsync(It.IsAny<Selector>()))
+                    .ThrowsAsync(exception);
+
+                using (var dataSource = MakeDataSource())
+                {
+                    var startTask = dataSource.Start();
+
+                    var result = await startTask;
+                    Assert.True(result); // Init task completes even on error
+
+                    var status = _updateSink.StatusUpdates.ExpectValue();
+                    Assert.Equal(DataSourceState.Off, status.State);
+                    Assert.NotNull(status.LastError);
+                    Assert.Equal(DataSourceStatus.ErrorKind.ErrorResponse, status.LastError.Value.Kind);
+                    Assert.Equal(401, status.LastError.Value.StatusCode);
+                    Assert.True(status.LastError.Value.FDv1Fallback, "FDv1Fallback should be true when fallback header is present");
+
+                    Assert.False(dataSource.Initialized);
+                }
+            }
+        }
+
+        [Fact]
+        public void RecoverableHttpErrorWithoutFallbackHeaderDoesNotSetFDv1Fallback()
+        {
+            // Create an HttpResponseMessage without the fallback header
+            using (var response = new HttpResponseMessage((HttpStatusCode)503))
+            {
+                var exception = new UnsuccessfulResponseException(503, response.Headers);
+
+                _mockRequestor.Setup(r => r.PollingRequestAsync(It.IsAny<Selector>()))
+                    .ThrowsAsync(exception);
+
+                using (var dataSource = MakeDataSource())
+                {
+                    _ = dataSource.Start();
+
+                    var status = _updateSink.StatusUpdates.ExpectValue();
+                    Assert.Equal(DataSourceState.Interrupted, status.State);
+                    Assert.NotNull(status.LastError);
+                    Assert.Equal(DataSourceStatus.ErrorKind.ErrorResponse, status.LastError.Value.Kind);
+                    Assert.Equal(503, status.LastError.Value.StatusCode);
+                    Assert.False(status.LastError.Value.FDv1Fallback, "FDv1Fallback should be false when fallback header is not present");
+
+                    Assert.False(dataSource.Initialized);
+                }
+            }
+        }
     }
 }