chore: Handle Fallback From FDv2 to FDv1

contract-tests/src/main/java/com/launchdarkly/sdktest/TestService.java

@@ -40,7 +40,8 @@ public class TestService extends NanoHTTPD {
             "client-prereq-events",
             "evaluation-hooks",
             "track-hooks",
-            "client-per-context-summaries"
+            "client-per-context-summaries",
+            "client-event-source-http-errors"
     };
     private static final String MIME_JSON = "application/json";
     static final Gson gson = new GsonBuilder()

launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/DataSystemComponents.java

@@ -8,11 +8,18 @@
 import com.launchdarkly.sdk.android.integrations.StreamingSynchronizerBuilder;
 import com.launchdarkly.sdk.android.interfaces.ServiceEndpoints;
 import com.launchdarkly.sdk.android.subsystems.DataSourceBuildInputs;
+import com.launchdarkly.sdk.android.subsystems.DataSourceBuilder;
 import com.launchdarkly.sdk.android.subsystems.Initializer;
 import com.launchdarkly.sdk.android.subsystems.Synchronizer;
 import com.launchdarkly.sdk.internal.http.HttpProperties;
 
+import androidx.annotation.NonNull;
+
 import java.net.URI;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
 
 /**
  * Factory methods for FDv2 data source components used with the
@@ -102,6 +109,35 @@ public Synchronizer build(DataSourceBuildInputs inputs) {
         }
     }
 
+    static final class FDv1PollingSynchronizerBuilderImpl implements DataSourceBuilder<Synchronizer> {
+
+        protected int pollIntervalMillis = LDConfig.DEFAULT_POLL_INTERVAL_MILLIS;
+
+        public FDv1PollingSynchronizerBuilderImpl pollIntervalMillis(int pollIntervalMillis) {
+            this.pollIntervalMillis = pollIntervalMillis <= LDConfig.DEFAULT_POLL_INTERVAL_MILLIS ?
+                    LDConfig.DEFAULT_POLL_INTERVAL_MILLIS : pollIntervalMillis;
+            return this;
+        }
+
+        @Override
+        public Synchronizer build(DataSourceBuildInputs inputs) {
+            FeatureFetcher fetcher = new HttpFeatureFlagFetcher(
+                inputs.getServiceEndpoints().getPollingBaseUri(),
+                inputs.isEvaluationReasons(),
+                inputs.getHttp().isUseReport(),
+                LDUtil.makeHttpProperties(inputs.getHttp()),
+                inputs.getCacheDir(),
+                inputs.getBaseLogger()
+            );
+            return new FDv1PollingSynchronizer(
+                inputs.getEvaluationContext(), fetcher,
+                inputs.getSharedExecutor(), 0,
+                pollIntervalMillis,
+                inputs.getBaseLogger()
+            );
+        }
+    }
+
     /**
      * Returns a builder for a polling initializer.
      * <p>
@@ -141,6 +177,63 @@ public static StreamingSynchronizerBuilder streamingSynchronizer() {
         return new StreamingSynchronizerBuilderImpl();
     }
 
+    /**
+     * Produces the default mode table used by {@link DataSystemBuilder#buildModeTable}.
+     * Defined here (rather than in {@code DataSystemBuilder}) because the FDv1 fallback
+     * synchronizer references package-private types that are not visible from the
+     * {@code integrations} package.
+     * <p>
+     * This method is public only for cross-package access within the SDK; it is not
+     * intended for use by application code.
+     */
+    @NonNull
+    public static Map<ConnectionMode, ModeDefinition> makeDefaultModeTable() {
+        DataSourceBuilder<Initializer> pollingInitializer = pollingInitializer();
+        DataSourceBuilder<Synchronizer> pollingSynchronizer = pollingSynchronizer();
+        DataSourceBuilder<Synchronizer> streamingSynchronizer = streamingSynchronizer();
+        DataSourceBuilder<Synchronizer> backgroundPollingSynchronizer =
+                pollingSynchronizer()
+                        .pollIntervalMillis(LDConfig.DEFAULT_BACKGROUND_POLL_INTERVAL_MILLIS);
+        DataSourceBuilder<Synchronizer> fdv1FallbackPollingSynchronizerForeground =
+                new FDv1PollingSynchronizerBuilderImpl();
+
+        DataSourceBuilder<Synchronizer> fdv1FallbackPollingSynchronizerBackground =
+                new FDv1PollingSynchronizerBuilderImpl().pollIntervalMillis(LDConfig.DEFAULT_BACKGROUND_POLL_INTERVAL_MILLIS);
+
+        Map<ConnectionMode, ModeDefinition> table = new LinkedHashMap<>();
+        table.put(ConnectionMode.STREAMING, new ModeDefinition(
+                // TODO: cacheInitializer — add once implemented
+                Arrays.asList(/* cacheInitializer, */ pollingInitializer),
+                Arrays.asList(streamingSynchronizer, pollingSynchronizer),
+                fdv1FallbackPollingSynchronizerForeground
+        ));
+        table.put(ConnectionMode.POLLING, new ModeDefinition(
+                // TODO: Arrays.asList(cacheInitializer) — add once implemented
+                Collections.<DataSourceBuilder<Initializer>>emptyList(),
+                Collections.singletonList(pollingSynchronizer),
+                fdv1FallbackPollingSynchronizerForeground
+        ));
+        table.put(ConnectionMode.OFFLINE, new ModeDefinition(
+                // TODO: Arrays.asList(cacheInitializer) — add once implemented
+                Collections.<DataSourceBuilder<Initializer>>emptyList(),
+                Collections.<DataSourceBuilder<Synchronizer>>emptyList(),
+                null
+        ));
+        table.put(ConnectionMode.ONE_SHOT, new ModeDefinition(
+                // TODO: cacheInitializer and streamingInitializer — add once implemented
+                Arrays.asList(/* cacheInitializer, */ pollingInitializer /*, streamingInitializer, */),
+                Collections.<DataSourceBuilder<Synchronizer>>emptyList(),
+                null
+        ));
+        table.put(ConnectionMode.BACKGROUND, new ModeDefinition(
+                // TODO: Arrays.asList(cacheInitializer) — add once implemented
+                Collections.<DataSourceBuilder<Initializer>>emptyList(),
+                Collections.singletonList(backgroundPollingSynchronizer),
+                fdv1FallbackPollingSynchronizerBackground
+        ));
+        return table;
+    }
+
     /**
      * Returns a builder for configuring automatic connection mode switching in response to
      * platform events (foreground/background and network availability).

launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/DefaultFDv2Requestor.java

@@ -177,15 +177,21 @@ public void onResponse(@NonNull Call call, @NonNull Response response) {
         return future;
     }
 
+    private static boolean isFdv1Fallback(@NonNull Response response) {
+        String value = response.header(HeaderConstants.FDV1_FALLBACK_HEADER);
+        return value != null && value.equalsIgnoreCase("true");
+    }
+
     private void handleResponse(
             @NonNull Response response,
             @NonNull LDAwaitFuture<FDv2PayloadResponse> future) {
         try {
             int code = response.code();
+            boolean fdv1Fallback = isFdv1Fallback(response);
 
             if (code == 304) {
                 logger.debug("FDv2 polling: 304 Not Modified");
-                future.set(FDv2PayloadResponse.notModified());
+                future.set(FDv2PayloadResponse.notModified(fdv1Fallback));
                 return;
             }
 
@@ -197,7 +203,7 @@ private void handleResponse(
                 } else {
                     logger.warn("Polling request failed with HTTP {}", code);
                 }
-                future.set(FDv2PayloadResponse.failure(code));
+                future.set(FDv2PayloadResponse.failure(code, fdv1Fallback));
                 return;
             }
 
@@ -216,7 +222,7 @@ private void handleResponse(
             String bodyStr = body.string();
             logger.debug("Polling response received");
             List<FDv2Event> events = FDv2Event.parseEventsArray(bodyStr);
-            future.set(FDv2PayloadResponse.success(events, code));
+            future.set(FDv2PayloadResponse.success(events, code, fdv1Fallback));
 
         } catch (Exception e) {
             future.setException(e);

launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/FDv1PollingSynchronizer.java

@@ -0,0 +1,191 @@
+package com.launchdarkly.sdk.android;
+
+import androidx.annotation.NonNull;
+
+import com.launchdarkly.logging.LDLogger;
+import com.launchdarkly.sdk.LDContext;
+import com.launchdarkly.sdk.android.DataModel.Flag;
+import com.launchdarkly.sdk.android.subsystems.Callback;
+import com.launchdarkly.sdk.android.subsystems.FDv2SourceResult;
+import com.launchdarkly.sdk.android.subsystems.Synchronizer;
+import com.launchdarkly.sdk.fdv2.ChangeSet;
+import com.launchdarkly.sdk.fdv2.ChangeSetType;
+import com.launchdarkly.sdk.fdv2.Selector;
+import com.launchdarkly.sdk.fdv2.SourceResultType;
+import com.launchdarkly.sdk.fdv2.SourceSignal;
+import com.launchdarkly.sdk.json.SerializationException;
+
+import java.io.IOException;
+import java.util.Map;
+import java.util.concurrent.Future;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ScheduledFuture;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * FDv1 polling synchronizer used as a fallback when the server signals that FDv2 endpoints
+ * are unavailable via the {@code x-ld-fd-fallback} response header.
+ * <p>
+ * Delegates the actual HTTP fetch to a {@link FeatureFetcher} (the same transport used by the
+ * production FDv1 polling data source) and converts the response into {@link FDv2SourceResult}
+ * objects so it can be used as a drop-in synchronizer within the FDv2 data source pipeline.
+ */
+final class FDv1PollingSynchronizer implements Synchronizer {
+
+    private final LDContext evaluationContext;
+    private final FeatureFetcher fetcher;
+    private final LDLogger logger;
+
+    private final LDAsyncQueue<FDv2SourceResult> resultQueue = new LDAsyncQueue<>();
+    private final LDAwaitFuture<FDv2SourceResult> shutdownFuture = new LDAwaitFuture<>();
+
+    private volatile ScheduledFuture<?> scheduledTask;
+    private final Object taskLock = new Object();
+
+    /**
+     * @param evaluationContext  the context to evaluate flags for
+     * @param fetcher            the HTTP transport for FDv1 polling requests
+     * @param executor           scheduler for recurring poll tasks
+     * @param initialDelayMillis delay before the first poll in milliseconds
+     * @param pollIntervalMillis delay between the end of one poll and the start of the next
+     * @param logger             logger
+     */
+    FDv1PollingSynchronizer(
+            @NonNull LDContext evaluationContext,
+            @NonNull FeatureFetcher fetcher,
+            @NonNull ScheduledExecutorService executor,
+            long initialDelayMillis,
+            long pollIntervalMillis,
+            @NonNull LDLogger logger) {
+        this.evaluationContext = evaluationContext;
+        this.fetcher = fetcher;
+        this.logger = logger;
+
+        synchronized (taskLock) {
+            scheduledTask = executor.scheduleWithFixedDelay(
+                    this::pollAndEnqueue,
+                    initialDelayMillis,
+                    pollIntervalMillis,
+                    TimeUnit.MILLISECONDS);
+        }
+    }
+
+    private void pollAndEnqueue() {
+        try {
+            FDv2SourceResult result = doPoll();
+
+            if (result.getResultType() == SourceResultType.STATUS) {
+                FDv2SourceResult.Status status = result.getStatus();
+                if (status != null && status.getState() == SourceSignal.TERMINAL_ERROR) {
+                    synchronized (taskLock) {
+                        if (scheduledTask != null) {
+                            scheduledTask.cancel(false);
+                            scheduledTask = null;
+                        }
+                    }
+                    shutdownFuture.set(result);
+                    return;
+                }
+            }
+
+            resultQueue.put(result);
+        } catch (RuntimeException e) {
+            LDUtil.logExceptionAtErrorLevel(logger, e, "Unexpected exception in FDv1 polling synchronizer task");
+            resultQueue.put(FDv2SourceResult.status(FDv2SourceResult.Status.interrupted(e), false));
+        }
+    }
+
+    /**
+     * Fetches flags via FDv1 polling and converts the result to an {@link FDv2SourceResult}.
+     * <p>
+     * All result/error processing happens inside the {@link Callback} so the future carries a
+     * fully-formed {@link FDv2SourceResult}. This keeps application-level error classification
+     * (e.g. {@link LDInvalidResponseCodeFailure}) at the callback layer rather than unwrapping
+     * it from a {@link java.util.concurrent.Future#get()} exception.
+     */
+    private FDv2SourceResult doPoll() {
+        LDAwaitFuture<FDv2SourceResult> resultFuture = new LDAwaitFuture<>();
+
+        fetcher.fetch(evaluationContext, new Callback<String>() {
+            @Override
+            public void onSuccess(String json) {
+                try {
+                    logger.debug("FDv1 fallback polling response received");
+                    EnvironmentData envData = EnvironmentData.fromJson(json);
+                    Map<String, Flag> flags = envData.getAll();
+
+                    ChangeSet<Map<String, Flag>> changeSet = new ChangeSet<>(
+                            ChangeSetType.Full,
+                            Selector.EMPTY,
+                            flags,
+                            null,
+                            true);
+                    resultFuture.set(FDv2SourceResult.changeSet(changeSet, false));
+                } catch (SerializationException e) {
+                    LDUtil.logExceptionAtErrorLevel(logger, e, "FDv1 fallback polling failed to parse response");
+                    LDFailure failure = new LDFailure(
+                            "FDv1 fallback: invalid JSON response", e, LDFailure.FailureType.INVALID_RESPONSE_BODY);
+                    resultFuture.set(FDv2SourceResult.status(FDv2SourceResult.Status.interrupted(failure), false));
+                }
+            }
+
+            @Override
+            public void onError(Throwable e) {
+                if (e instanceof LDInvalidResponseCodeFailure) {
+                    int code = ((LDInvalidResponseCodeFailure) e).getResponseCode();
+                    if (code == 400) {
+                        logger.error("Received 400 response when fetching flag values. " +
+                                "Please check recommended R8 and/or ProGuard settings");
+                    }
+                    boolean recoverable = LDUtil.isHttpErrorRecoverable(code);
+                    logger.warn("FDv1 fallback polling failed with HTTP {}", code);
+                    LDFailure failure = new LDInvalidResponseCodeFailure(
+                            "FDv1 fallback polling request failed", e, code, recoverable);
+                    if (!recoverable) {
+                        resultFuture.set(FDv2SourceResult.status(FDv2SourceResult.Status.terminalError(failure), false));
+                    } else {
+                        resultFuture.set(FDv2SourceResult.status(FDv2SourceResult.Status.interrupted(failure), false));
+                    }
+                } else if (e instanceof IOException) {
+                    LDUtil.logExceptionAtErrorLevel(logger, e, "FDv1 fallback polling failed with network error");
+                    resultFuture.set(FDv2SourceResult.status(FDv2SourceResult.Status.interrupted(e), false));
+                } else {
+                    LDUtil.logExceptionAtErrorLevel(logger, e, "FDv1 fallback polling failed");
+                    resultFuture.set(FDv2SourceResult.status(FDv2SourceResult.Status.interrupted(e), false));
+                }
+            }
+        });
+
+        try {
+            return resultFuture.get();
+        } catch (InterruptedException e) {
+            return FDv2SourceResult.status(FDv2SourceResult.Status.interrupted(e), false);
+        } catch (Exception e) {
+            // Should not happen — all callback paths call set(), never setException()
+            Throwable cause = e.getCause() != null ? e.getCause() : e;
+            LDUtil.logExceptionAtErrorLevel(logger, cause, "FDv1 fallback polling failed unexpectedly");
+            return FDv2SourceResult.status(FDv2SourceResult.Status.interrupted(cause), false);
+        }
+    }
+
+    @Override
+    @NonNull
+    public Future<FDv2SourceResult> next() {
+        return LDFutures.anyOf(shutdownFuture, resultQueue.take());
+    }
+
+    @Override
+    public void close() {
+        synchronized (taskLock) {
+            if (scheduledTask != null) {
+                scheduledTask.cancel(false);
+                scheduledTask = null;
+            }
+        }
+        shutdownFuture.set(FDv2SourceResult.status(FDv2SourceResult.Status.shutdown(), false));
+        try {
+            fetcher.close();
+        } catch (IOException ignored) {
+        }
+    }
+}