chore: FDv2 Cache Initializer

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

@@ -207,6 +207,11 @@ public PersistentDataStoreWrapper.PerEnvironmentData getPerEnvironmentData() {
         return throwExceptionIfNull(perEnvironmentData);
     }
 
+    @Nullable
+    public PersistentDataStoreWrapper.PerEnvironmentData getPerEnvironmentDataIfAvailable() {
+        return perEnvironmentData;
+    }
+
     @Nullable
     public TransactionalDataStore getTransactionalDataStore() {
         return transactionalDataStore;

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

@@ -64,17 +64,39 @@ final class ContextDataManager implements TransactionalDataStore {
     /** Selector from the last applied changeset that carried one; in-memory only, not persisted. */
     @NonNull private Selector currentSelector = Selector.EMPTY;
 
+    /**
+     * @param skipCacheLoad true when an FDv2 cache initializer will handle loading cached
+     *                      flags as the first step in the initializer chain, making the
+     *                      cache load in {@link #switchToContext} redundant
+     */
     ContextDataManager(
             @NonNull ClientContext clientContext,
             @NonNull PersistentDataStoreWrapper.PerEnvironmentData environmentStore,
-            int maxCachedContexts
+            int maxCachedContexts,
+            boolean skipCacheLoad
     ) {
         this.environmentStore = environmentStore;
         this.index = environmentStore.getIndex();
         this.maxCachedContexts = maxCachedContexts;
         this.taskExecutor = ClientContextImpl.get(clientContext).getTaskExecutor();
         this.logger = clientContext.getBaseLogger();
-        switchToContext(clientContext.getEvaluationContext());
+        if (skipCacheLoad) {
+            setCurrentContext(clientContext.getEvaluationContext());
+        } else {
+            switchToContext(clientContext.getEvaluationContext());
+        }
+    }
+
+    /**
+     * Sets the current context without loading cached data. Used in the FDv2 path where
+     * the {@code FDv2CacheInitializer} handles cache loading as part of the initializer chain.
+     *
+     * @param context the context to switch to
+     */
+    public void setCurrentContext(@NonNull LDContext context) {
+        synchronized (lock) {
+            currentContext = context;
+        }
     }
 
     /**

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

@@ -14,6 +14,7 @@
 import com.launchdarkly.sdk.internal.http.HttpProperties;
 
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 
 import java.net.URI;
 import java.util.Arrays;
@@ -138,6 +139,31 @@ public Synchronizer build(DataSourceBuildInputs inputs) {
         }
     }
 
+    static final class CacheInitializerBuilderImpl implements DataSourceBuilder<Initializer> {
+        @Nullable
+        private final PersistentDataStoreWrapper.ReadOnlyPerEnvironmentData envData;
+
+        CacheInitializerBuilderImpl() {
+            this.envData = null;
+        }
+
+        CacheInitializerBuilderImpl(
+                @Nullable PersistentDataStoreWrapper.ReadOnlyPerEnvironmentData envData
+        ) {
+            this.envData = envData;
+        }
+
+        @Override
+        public Initializer build(DataSourceBuildInputs inputs) {
+            return new FDv2CacheInitializer(
+                    envData,
+                    inputs.getEvaluationContext(),
+                    inputs.getSharedExecutor(),
+                    inputs.getBaseLogger()
+            );
+        }
+    }
+
     /**
      * Returns a builder for a polling initializer.
      * <p>
@@ -188,6 +214,7 @@ public static StreamingSynchronizerBuilder streamingSynchronizer() {
      */
     @NonNull
     public static Map<ConnectionMode, ModeDefinition> makeDefaultModeTable() {
+        DataSourceBuilder<Initializer> cacheInitializer = new CacheInitializerBuilderImpl();
         DataSourceBuilder<Initializer> pollingInitializer = pollingInitializer();
         DataSourceBuilder<Synchronizer> pollingSynchronizer = pollingSynchronizer();
         DataSourceBuilder<Synchronizer> streamingSynchronizer = streamingSynchronizer();
@@ -202,32 +229,28 @@ public static Map<ConnectionMode, ModeDefinition> makeDefaultModeTable() {
 
         Map<ConnectionMode, ModeDefinition> table = new LinkedHashMap<>();
         table.put(ConnectionMode.STREAMING, new ModeDefinition(
-                // TODO: cacheInitializer — add once implemented
-                Arrays.asList(/* cacheInitializer, */ pollingInitializer),
+                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(cacheInitializer),
                 Collections.singletonList(pollingSynchronizer),
                 fdv1FallbackPollingSynchronizerForeground
         ));
         table.put(ConnectionMode.OFFLINE, new ModeDefinition(
-                // TODO: Arrays.asList(cacheInitializer) — add once implemented
-                Collections.<DataSourceBuilder<Initializer>>emptyList(),
+                Collections.singletonList(cacheInitializer),
                 Collections.<DataSourceBuilder<Synchronizer>>emptyList(),
                 null
         ));
         table.put(ConnectionMode.ONE_SHOT, new ModeDefinition(
-                // TODO: cacheInitializer and streamingInitializer — add once implemented
-                Arrays.asList(/* cacheInitializer, */ pollingInitializer /*, streamingInitializer, */),
+                // TODO: 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(cacheInitializer),
                 Collections.singletonList(backgroundPollingSynchronizer),
                 fdv1FallbackPollingSynchronizerBackground
         ));

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

@@ -0,0 +1,109 @@
+package com.launchdarkly.sdk.android;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import com.launchdarkly.logging.LDLogger;
+import com.launchdarkly.sdk.LDContext;
+import com.launchdarkly.sdk.android.DataModel.Flag;
+import com.launchdarkly.sdk.android.subsystems.FDv2SourceResult;
+import com.launchdarkly.sdk.android.subsystems.Initializer;
+import com.launchdarkly.sdk.fdv2.ChangeSet;
+import com.launchdarkly.sdk.fdv2.ChangeSetType;
+import com.launchdarkly.sdk.fdv2.Selector;
+
+import java.util.Collections;
+import java.util.Map;
+import java.util.concurrent.Executor;
+import java.util.concurrent.Future;
+
+/**
+ * FDv2 cache initializer: loads persisted flag data from the local cache as the first
+ * step in the initializer chain.
+ * <p>
+ * Per CONNMODE 4.1.2, the cache initializer returns data with {@code persist=false}
+ * and {@link Selector#EMPTY} (no selector), so the orchestrator continues to the next
+ * initializer (polling) to obtain a verified selector from the server. This provides
+ * immediate flag values from cache while the network initializer fetches fresh data.
+ * <p>
+ * A cache miss (or missing persistent store) is returned as a {@link ChangeSetType#None}
+ * changeset — analogous to "transfer of none" / 304 Not Modified (CSFDV2 9.1.2). This
+ * signals "I checked the source and there is nothing new" rather than an error, so the
+ * orchestrator records {@code anyDataReceived = true} and continues normally. This is
+ * critical for OFFLINE mode where no synchronizers follow: without it, a cache miss
+ * would leave the SDK in a failed initialization state.
+ */
+final class FDv2CacheInitializer implements Initializer {
+
+    @Nullable
+    private final PersistentDataStoreWrapper.ReadOnlyPerEnvironmentData envData;
+    private final LDContext context;
+    private final Executor executor;
+    private final LDLogger logger;
+    private final LDAwaitFuture<FDv2SourceResult> shutdownFuture = new LDAwaitFuture<>();
+
+    FDv2CacheInitializer(
+            @Nullable PersistentDataStoreWrapper.ReadOnlyPerEnvironmentData envData,
+            @NonNull LDContext context,
+            @NonNull Executor executor,
+            @NonNull LDLogger logger
+    ) {
+        this.envData = envData;
+        this.context = context;
+        this.executor = executor;
+        this.logger = logger;
+    }
+
+    @Override
+    @NonNull
+    public Future<FDv2SourceResult> run() {
+        LDAwaitFuture<FDv2SourceResult> resultFuture = new LDAwaitFuture<>();
+
+        executor.execute(() -> {
+            try {
+                if (envData == null) {
+                    logger.debug("No persistent store configured; skipping cache");
+                    resultFuture.set(FDv2SourceResult.changeSet(new ChangeSet<>(
+                            ChangeSetType.None,
+                            Selector.EMPTY,
+                            Collections.emptyMap(),
+                            null,
+                            false), false));
+                    return;
+                }
+                String hashedContextId = LDUtil.urlSafeBase64HashedContextId(context);
+                EnvironmentData stored = envData.getContextData(hashedContextId);
+                if (stored == null) {
+                    logger.debug("Cache miss for context");
+                    resultFuture.set(FDv2SourceResult.changeSet(new ChangeSet<>(
+                            ChangeSetType.None,
+                            Selector.EMPTY,
+                            Collections.emptyMap(),
+                            null,
+                            false), false));
+                    return;
+                }
+                Map<String, Flag> flags = stored.getAll();
+                ChangeSet<Map<String, Flag>> changeSet = new ChangeSet<>(
+                        ChangeSetType.Full,
+                        Selector.EMPTY,
+                        flags,
+                        null,
+                        false);
+                logger.debug("Cache hit: loaded {} flags for context", flags.size());
+                resultFuture.set(FDv2SourceResult.changeSet(changeSet, false));
+            } catch (Exception e) {
+                logger.warn("Cache initializer failed: {}", e.toString());
+                resultFuture.set(FDv2SourceResult.status(
+                        FDv2SourceResult.Status.interrupted(e), false));
+            }
+        });
+
+        return LDFutures.anyOf(shutdownFuture, resultFuture);
+    }
+
+    @Override
+    public void close() {
+        shutdownFuture.set(FDv2SourceResult.status(FDv2SourceResult.Status.shutdown(), false));
+    }
+}

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

@@ -1,6 +1,7 @@
 package com.launchdarkly.sdk.android;
 
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 
 import com.launchdarkly.sdk.android.subsystems.ClientContext;
 import com.launchdarkly.sdk.android.subsystems.ComponentConfigurer;
@@ -115,7 +116,9 @@ public DataSource build(ClientContext clientContext) {
         }
 
         DataSourceBuildInputs inputs = makeInputs(clientContext);
-        ResolvedModeDefinition resolved = resolve(modeDef, inputs);
+        PersistentDataStoreWrapper.ReadOnlyPerEnvironmentData envData =
+                ClientContextImpl.get(clientContext).getPerEnvironmentDataIfAvailable();
+        ResolvedModeDefinition resolved = resolve(modeDef, inputs, envData);
 
         DataSourceUpdateSink baseSink = clientContext.getDataSourceUpdateSink();
         if (!(baseSink instanceof DataSourceUpdateSinkV2)) {
@@ -149,28 +152,40 @@ public void close() {
     }
 
     private DataSourceBuildInputs makeInputs(ClientContext clientContext) {
-        TransactionalDataStore store = ClientContextImpl.get(clientContext).getTransactionalDataStore();
+        ClientContextImpl impl = ClientContextImpl.get(clientContext);
+        TransactionalDataStore store = impl.getTransactionalDataStore();
         SelectorSource selectorSource = store != null
                 ? new SelectorSourceFacade(store)
                 : () -> com.launchdarkly.sdk.fdv2.Selector.EMPTY;
+
         return new DataSourceBuildInputs(
                 clientContext.getEvaluationContext(),
                 clientContext.getServiceEndpoints(),
                 clientContext.getHttp(),
                 clientContext.isEvaluationReasons(),
                 selectorSource,
                 sharedExecutor,
-                ClientContextImpl.get(clientContext).getPlatformState().getCacheDir(),
+                impl.getPlatformState().getCacheDir(),
                 clientContext.getBaseLogger()
         );
     }
 
     private static ResolvedModeDefinition resolve(
-            ModeDefinition def, DataSourceBuildInputs inputs
+            ModeDefinition def, DataSourceBuildInputs inputs,
+            @Nullable PersistentDataStoreWrapper.ReadOnlyPerEnvironmentData envData
     ) {
         List<FDv2DataSource.DataSourceFactory<Initializer>> initFactories = new ArrayList<>();
         for (DataSourceBuilder<Initializer> builder : def.getInitializers()) {
-            initFactories.add(() -> builder.build(inputs));
+            // The cache initializer's dependency (ReadOnlyPerEnvironmentData) is only
+            // available at build time, not when the static mode table is constructed,
+            // so we inject it here by replacing the placeholder with a wired copy.
+            final DataSourceBuilder<Initializer> effective;
+            if (builder instanceof DataSystemComponents.CacheInitializerBuilderImpl) {
+                effective = new DataSystemComponents.CacheInitializerBuilderImpl(envData);
+            } else {
+                effective = builder;
+            }
+            initFactories.add(() -> effective.build(inputs));
         }
         List<FDv2DataSource.DataSourceFactory<Synchronizer>> syncFactories = new ArrayList<>();
         for (DataSourceBuilder<Synchronizer> builder : def.getSynchronizers()) {

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

@@ -421,10 +421,12 @@ protected LDClient(
                 taskExecutor
         );
 
+        boolean usingFDv2 = config.dataSource instanceof FDv2DataSourceBuilder;
         this.contextDataManager = new ContextDataManager(
                 clientContextImpl,
                 environmentStore,
-                config.getMaxCachedContexts()
+                config.getMaxCachedContexts(),
+                usingFDv2
         );
 
         eventProcessor = config.events.build(clientContextImpl);
@@ -497,11 +499,17 @@ private void identifyInternal(@NonNull LDContext context,
 
         clientContextImpl = clientContextImpl.setEvaluationContext(context);
 
-        // Calling initFromStoredData updates the current flag state *if* stored flags exist for
-        // this context. If they don't, it has no effect. Currently we do *not* return early from
-        // initialization just because stored flags exist; we're just making them available in case
-        // initialization times out or otherwise fails.
-        contextDataManager.switchToContext(context);
+        // Load cached flags for the new context so they're available in case initialization
+        // times out or otherwise fails. This does not short-circuit initialization — the data
+        // source still performs its network request regardless.
+        if (config.dataSource instanceof FDv2DataSourceBuilder) {
+            // FDv2: just set the context; the FDv2CacheInitializer handles cache loading
+            // as the first step in the initializer chain.
+            contextDataManager.setCurrentContext(context);
+        } else {
+            // FDv1: load cached flags immediately while the data source fetches from the network.
+            contextDataManager.switchToContext(context);
+        }
         connectivityManager.switchToContext(context, onCompleteListener);
         eventProcessor.recordIdentifyEvent(context);
     }

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

@@ -144,11 +144,26 @@ public void setGeneratedContextKey(ContextKind contextKind, String key) {
                 ANON_CONTEXT_KEY_PREFIX + contextKind.toString(), key);
     }
 
+    /**
+     * Read-only view of per-environment flag data. This is the subset of
+     * {@link PerEnvironmentData} needed by the FDv2 cache initializer.
+     */
+    interface ReadOnlyPerEnvironmentData {
+        /**
+         * Returns the stored flag data, if any, for a specific context.
+         *
+         * @param hashedContextId the hashed canonical key of the context
+         * @return the {@link EnvironmentData}, or null if not found
+         */
+        @Nullable
+        EnvironmentData getContextData(String hashedContextId);
+    }
+
     /**
      * Provides access to stored data that is specific to a single environment. This object is
      * returned by {@link PersistentDataStoreWrapper#perEnvironmentData(String)}.
      */
-    final class PerEnvironmentData {
+    final class PerEnvironmentData implements ReadOnlyPerEnvironmentData {
         private final String environmentNamespace;
 
         PerEnvironmentData(String mobileKey) {

launchdarkly-android-client-sdk/src/test/java/com/launchdarkly/sdk/android/ConnectivityManagerTest.java

@@ -131,7 +131,8 @@ private void createTestManager(
         contextDataManager = new ContextDataManager(
                 clientContext,
                 environmentStore,
-                1
+                1,
+                false
         );
         contextDataManager.registerAllFlagsListener(flagsUpdated -> {
             allFlagsReceived.add(flagsUpdated);

launchdarkly-android-client-sdk/src/test/java/com/launchdarkly/sdk/android/ContextDataManagerTestBase.java

@@ -60,7 +60,8 @@ protected ContextDataManager createDataManager(int maxCachedContexts) {
         return new ContextDataManager(
                 clientContext,
                 environmentStore,
-                maxCachedContexts
+                maxCachedContexts,
+                false
         );
     }