Merge branch 'main' into devin/1778880952-use-shared-contract-tests-action

Author: kinyoklion

.release-please-manifest.json

@@ -4,5 +4,5 @@
   "lib/shared/common": "2.4.0",
   "lib/shared/internal": "1.9.0",
   "lib/shared/test-helpers": "2.1.0",
-  "lib/sdk/server": "7.13.4"
+  "lib/sdk/server": "7.14.0"
 }

lib/sdk/server/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to the LaunchDarkly Java SDK will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [7.14.0](https://github.com/launchdarkly/java-core/compare/launchdarkly-java-server-sdk-7.13.4...launchdarkly-java-server-sdk-7.14.0) (2026-05-28)
+
+
+### Features
+
+* add X-LaunchDarkly-Instance-Id header (SDK-2356) ([#162](https://github.com/launchdarkly/java-core/issues/162)) ([a363777](https://github.com/launchdarkly/java-core/commit/a363777b45b550ec89cc7f2eca67f9b0681e1590))
+* Drop persistent-store cache after FDv2 in-memory store init ([#167](https://github.com/launchdarkly/java-core/issues/167)) ([90f14f1](https://github.com/launchdarkly/java-core/commit/90f14f1f4f5bdb5d6bdcf4ed290f451c5ffda183))
+
+
+### Bug Fixes
+
+* honor FDv1 fallback directive during initializer phase ([#158](https://github.com/launchdarkly/java-core/issues/158)) ([b0a3957](https://github.com/launchdarkly/java-core/commit/b0a3957afa481c9938684f22c521965e616f2785))
+
 ## [7.13.4](https://github.com/launchdarkly/java-core/compare/launchdarkly-java-server-sdk-7.13.3...launchdarkly-java-server-sdk-7.13.4) (2026-04-24)
 
 

lib/sdk/server/contract-tests/service/src/main/java/sdktest/TestService.java

@@ -42,7 +42,8 @@ public class TestService {
     "strongly-typed",
     "tags",
     "server-side-polling",
-    "fdv1-fallback"
+    "fdv1-fallback",
+    "instance-id"
   };
 
   static final Gson gson = new GsonBuilder().serializeNulls().create();

lib/sdk/server/gradle.properties

@@ -1,5 +1,5 @@
 #x-release-please-start-version
-version=7.13.4
+version=7.14.0
 #x-release-please-end
 
 # See https://github.com/gradle/gradle/issues/11308 regarding the following property

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

@@ -8,6 +8,7 @@
 import com.launchdarkly.sdk.server.subsystems.HttpConfiguration;
 import com.launchdarkly.sdk.server.subsystems.LoggingConfiguration;
 
+import java.util.UUID;
 import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 
@@ -37,7 +38,7 @@ private ClientContextImpl(
   ) {
     super(baseContext.getSdkKey(), baseContext.getApplicationInfo(), baseContext.getHttp(),
         baseContext.getLogging(), baseContext.isOffline(), baseContext.getServiceEndpoints(),
-        baseContext.getThreadPriority(), baseContext.getWrapperInfo());
+        baseContext.getThreadPriority(), baseContext.getWrapperInfo(), baseContext.getInstanceId());
     this.sharedExecutor = sharedExecutor;
     this.diagnosticStore = diagnosticStore;
     this.dataSourceUpdateSink = null;
@@ -79,22 +80,29 @@ static ClientContextImpl fromConfig(
       LDConfig config,
       ScheduledExecutorService sharedExecutor
       ) {
+    // Generate the instance ID once and thread it through every ClientContext we build for this
+    // LDClient. Subsystems built from any of these contexts will all observe the same value.
+    String instanceId = UUID.randomUUID().toString();
+
     ClientContext minimalContext = new ClientContext(sdkKey, config.applicationInfo, null,
-        null, config.offline, config.serviceEndpoints, config.threadPriority, config.wrapperInfo);
+        null, config.offline, config.serviceEndpoints, config.threadPriority, config.wrapperInfo,
+        instanceId);
     LoggingConfiguration loggingConfig = config.logging.build(minimalContext);
-    
+
     ClientContext contextWithLogging = new ClientContext(sdkKey, config.applicationInfo, null,
-        loggingConfig, config.offline, config.serviceEndpoints, config.threadPriority, config.wrapperInfo);
+        loggingConfig, config.offline, config.serviceEndpoints, config.threadPriority,
+        config.wrapperInfo, instanceId);
     HttpConfiguration httpConfig = config.http.build(contextWithLogging);
-    
+
     if (httpConfig.getProxy() != null) {
       contextWithLogging.getBaseLogger().info("Using proxy: {} {} authentication.",
           httpConfig.getProxy(),
           httpConfig.getProxyAuthentication() == null ? "without" : "with");
     }
-    
-    ClientContext contextWithHttpAndLogging = new ClientContext(sdkKey, config.applicationInfo, httpConfig,
-        loggingConfig, config.offline, config.serviceEndpoints, config.threadPriority, config.wrapperInfo);
+
+    ClientContext contextWithHttpAndLogging = new ClientContext(sdkKey, config.applicationInfo,
+        httpConfig, loggingConfig, config.offline, config.serviceEndpoints, config.threadPriority,
+        config.wrapperInfo, instanceId);
 
     // Create a diagnostic store only if diagnostics are enabled. Diagnostics are enabled as long as 1. the
     // opt-out property was not set in the config, and 2. we are using the standard event processor.

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

@@ -304,6 +304,15 @@ private Result transformResult(com.launchdarkly.sdk.server.subsystems.EventSende
   }
 
   static final class HttpConfigurationBuilderImpl extends HttpConfigurationBuilder {
+    /**
+     * HTTP header used to identify this SDK instance for the purpose of estimating
+     * server-connection-minutes when polling. It contains a v4 UUID that is generated once per SDK
+     * instance and remains constant for the lifetime of the client.
+     *
+     * <p>See: sdk-specs / SCMP-server-connection-minutes-polling.
+     */
+    static final String INSTANCE_ID_HEADER = "X-LaunchDarkly-Instance-Id";
+
     @Override
     public HttpConfiguration build(ClientContext clientContext) {
       LDLogger logger = clientContext.getBaseLogger();
@@ -340,6 +349,16 @@ else if (wrapperName != null) {
         headers.put("X-LaunchDarkly-Wrapper", wrapperId);
       }
 
+      // The instance ID originates on ClientContext (generated once when LDClient is constructed)
+      // so every subsystem built from the same context observes a consistent value for the
+      // lifetime of the SDK instance.
+      String instanceId = clientContext.getInstanceId();
+      if (instanceId != null && !instanceId.isEmpty()) {
+        headers.put(INSTANCE_ID_HEADER, instanceId);
+      }
+
+      // For consistency with other SDKs, custom headers are allowed to overwrite headers such as
+      // User-Agent and Authorization.
       if (!customHeaders.isEmpty()) {
           headers.putAll(customHeaders);
       }

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

@@ -0,0 +1,18 @@
+package com.launchdarkly.sdk.server;
+
+/**
+ * Optional interface for data stores that can disable their internal cache.
+ * <p>
+ * This is currently for internal implementations only.
+ */
+interface DisableableCache {
+  /**
+   * Disables the internal cache. After this call, the cache is no longer
+   * consulted on reads and no longer populated by writes.
+   * <p>
+   * Implementations should release the cache contents so the memory can be
+   * reclaimed. The call must be idempotent: subsequent invocations should be
+   * safe and have no further effect.
+   */
+  void disableCache();
+}

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

@@ -15,6 +15,8 @@
 import java.util.Collections;
 import java.util.Date;
 import java.util.List;
+import java.util.Set;
+import java.util.WeakHashMap;
 import java.util.concurrent.*;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.stream.Collectors;
@@ -591,21 +593,102 @@ private void maybeReportUnexpectedExhaustion(String message) {
 
     /**
      * Helper class to manage the lifecycle of conditions with automatic cleanup.
+     *
+     * <p>Before the aggregate completes, {@link #getFuture()} returns a
+     * <em>fresh</em> {@link CompletableFuture} per call. This matters because
+     * the run loop calls {@code CompletableFuture.anyOf(getFuture(),
+     * synchronizerNext)} on every iteration: if {@code getFuture()} returned
+     * the shared underlying aggregate while it was still pending, each
+     * {@code anyOf} call would permanently attach an {@code OrRelay}
+     * {@code Completion} to its {@code stack}. On a healthy primary
+     * synchronizer that streams ChangeSets without ever arming the fallback
+     * timer, the aggregate never completes, so those Completion nodes would
+     * accumulate monotonically for the synchronizer's full tenure -- a real
+     * memory leak proportional to event rate.
+     *
+     * <p>After the aggregate completes, {@link #getFuture()} returns the
+     * aggregate directly: any continuation registered on an already-completed
+     * CompletableFuture fires synchronously at registration time and is
+     * removed from the stack immediately by {@code cleanStack}, so the same
+     * accumulation cannot happen.
+     *
+     * <p>Fresh pre-completion futures are tracked in a {@link WeakHashMap}-backed
+     * set, so a fresh future whose only strong references were in the caller's
+     * loop iteration becomes garbage-collectable -- and automatically removed
+     * from {@code pending} -- once that iteration ends.
+     *
+     * <p>Package-private (rather than private) so that direct unit tests can
+     * exercise the API surface and assert per-call distinctness.
      */
-    private static class Conditions implements AutoCloseable {
+    static class Conditions implements AutoCloseable {
         private final List<Condition> conditions;
-        private final CompletableFuture<Object> conditionsFuture;
+        private final CompletableFuture<Object> aggregate;
+        private final Object lock = new Object();
+
+        /**
+         * Tracks futures previously returned by {@link #getFuture()} that have
+         * not yet been completed. Held weakly via {@link WeakHashMap} so that
+         * fresh futures abandoned by the caller (the typical end-of-iteration
+         * case) become GC-collectable. Set to {@code null} once the aggregate
+         * has fired and the entries have been drained. Mutated only under
+         * {@code lock}.
+         */
+        private Set<CompletableFuture<Object>> pending =
+            Collections.newSetFromMap(new WeakHashMap<>());
 
         public Conditions(List<Condition> conditions) {
             this.conditions = conditions;
-            this.conditionsFuture = conditions.isEmpty()
+            this.aggregate = conditions.isEmpty()
                 ? new CompletableFuture<>() // Never completes if no conditions
                 : CompletableFuture.anyOf(
-                conditions.stream().map(Condition::execute).toArray(CompletableFuture[]::new));
+                    conditions.stream().map(Condition::execute).toArray(CompletableFuture[]::new));
+
+            // Single permanent listener. This is the only Completion node ever
+            // attached to aggregate.stack while the aggregate is still pending
+            // -- subsequent pre-completion getFuture() calls do not touch the
+            // aggregate at all.
+            this.aggregate.whenComplete((result, throwable) -> {
+                List<CompletableFuture<Object>> snapshot;
+                synchronized (lock) {
+                    if (pending == null) {
+                        return;
+                    }
+                    // Copy under the lock: the ArrayList holds strong
+                    // references so entries that survived GC to this point
+                    // stay alive until we complete them below.
+                    snapshot = new ArrayList<>(pending);
+                    pending = null;
+                }
+                for (CompletableFuture<Object> cf : snapshot) {
+                    if (throwable != null) {
+                        cf.completeExceptionally(throwable);
+                    } else {
+                        cf.complete(result);
+                    }
+                }
+            });
         }
 
+        /**
+         * Returns a future that will complete when the underlying aggregate
+         * condition fires. Pre-completion, this is a fresh future per call;
+         * post-completion, this is the aggregate itself (already done).
+         */
         public CompletableFuture<Object> getFuture() {
-            return conditionsFuture;
+            if (aggregate.isDone()) {
+                return aggregate;
+            }
+
+            CompletableFuture<Object> fresh = new CompletableFuture<>();
+            synchronized (lock) {
+                if (pending == null) {
+                    // Raced with aggregate completion between isDone() and
+                    // the lock acquisition; aggregate is now done.
+                    return aggregate;
+                }
+                pending.add(fresh);
+            }
+            return fresh;
         }
 
         public void inform(FDv2SourceResult result) {
@@ -615,6 +698,11 @@ public void inform(FDv2SourceResult result) {
         @Override
         public void close() {
             conditions.forEach(Condition::close);
+            synchronized (lock) {
+                if (pending != null) {
+                    pending.clear();
+                }
+            }
         }
     }
 }

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

@@ -43,7 +43,7 @@
  * <p>
  * This class is only constructed by {@link PersistentDataStoreBuilder}.
  */
-final class PersistentDataStoreWrapper implements DataStore, SettableCache {
+final class PersistentDataStoreWrapper implements DataStore, SettableCache, DisableableCache {
   private final PersistentDataStore core;
   private final LoadingCache<CacheKey, Optional<ItemDescriptor>> itemCache;
   private final LoadingCache<DataKind, KeyedItems<ItemDescriptor>> allCache;
@@ -54,9 +54,15 @@ final class PersistentDataStoreWrapper implements DataStore, SettableCache {
   private final AtomicBoolean inited = new AtomicBoolean(false);
   private final ListeningExecutorService cacheExecutor;
   private final LDLogger logger;
-  
+
   private final Object externalStoreLock = new Object();
   private volatile CacheExporter externalCache;
+
+  // Once true, the cache is bypassed on reads and writes; entries already in
+  // the cache have been invalidated by disableCache(). The cache instances
+  // themselves remain alive until GC reclaims them; the LoadingCache loaders
+  // are short-circuited because every touch site checks this flag first.
+  private volatile boolean cacheDisabled;
 
   PersistentDataStoreWrapper(
       final PersistentDataStore core,
@@ -151,14 +157,26 @@ public void close() throws IOException {
     core.close();
   }
 
+  @Override
+  public void disableCache() {
+    if (cacheDisabled) return;
+    // Volatile write publishes the bypass flag before clearing cache contents.
+    // Future readers observe cacheDisabled == true and skip the cache call
+    // sites.
+    cacheDisabled = true;
+    if (itemCache != null) itemCache.invalidateAll();
+    if (allCache != null) allCache.invalidateAll();
+    if (initCache != null) initCache.invalidateAll();
+  }
+
   @Override
   public boolean isInitialized() {
     if (inited.get()) {
       return true;
     }
     boolean result;
     try {
-      if (initCache != null) {
+      if (initCache != null && !cacheDisabled) {
         result = initCache.get("");
       } else {
         result = core.isInitialized();
@@ -187,7 +205,7 @@ public void init(FullDataSet<ItemDescriptor> allData) {
       allBuilder.add(new AbstractMap.SimpleEntry<>(kind, items));
     }
     RuntimeException failure = initCore(new FullDataSet<>(allBuilder.build(), allData.shouldPersist()));
-    if (itemCache != null && allCache != null) {
+    if (itemCache != null && allCache != null && !cacheDisabled) {
       itemCache.invalidateAll();
       allCache.invalidateAll();
       if (failure != null && !cacheIndefinitely) {
@@ -228,7 +246,7 @@ private RuntimeException initCore(FullDataSet<SerializedItemDescriptor> allData)
   @Override
   public ItemDescriptor get(DataKind kind, String key) {
     try {
-      ItemDescriptor ret = itemCache != null ? itemCache.get(CacheKey.forItem(kind, key)).orNull() :
+      ItemDescriptor ret = (itemCache != null && !cacheDisabled) ? itemCache.get(CacheKey.forItem(kind, key)).orNull() :
         getAndDeserializeItem(kind, key);
       processError(null);
       return ret;
@@ -242,7 +260,7 @@ public ItemDescriptor get(DataKind kind, String key) {
   public KeyedItems<ItemDescriptor> getAll(DataKind kind) {
     try {
       KeyedItems<ItemDescriptor> ret;
-      ret = allCache != null ? allCache.get(kind) : getAllAndDeserialize(kind);
+      ret = (allCache != null && !cacheDisabled) ? allCache.get(kind) : getAllAndDeserialize(kind);
       processError(null);
       return ret;
     } catch (Exception e) {
@@ -281,7 +299,7 @@ public boolean upsert(DataKind kind, String key, ItemDescriptor item) {
       }
       failure = e;
     }
-    if (itemCache != null) {
+    if (itemCache != null && !cacheDisabled) {
       CacheKey cacheKey = CacheKey.forItem(kind, key);
       if (failure == null) {
         if (updated) {
@@ -297,7 +315,7 @@ public boolean upsert(DataKind kind, String key, ItemDescriptor item) {
         }
       }
     }
-    if (allCache != null) {
+    if (allCache != null && !cacheDisabled) {
       // If the cache has a finite TTL, then we should remove the "all items" cache entry to force
       // a reread the next time All is called. However, if it's an infinite TTL, we need to just
       // update the item within the existing "all items" entry (since we want things to still work
@@ -340,7 +358,7 @@ public void setCacheExporter(CacheExporter externalDataSource) {
 
   @Override
   public CacheStats getCacheStats() {
-    if (itemCache == null || allCache == null) {
+    if (itemCache == null || allCache == null || cacheDisabled) {
       return null;
     }
     com.google.common.cache.CacheStats itemStats = itemCache.stats();
@@ -443,8 +461,9 @@ private boolean pollAvailabilityAfterOutage() {
     }
 
     // Fall back to cache-based recovery if external store is not available/initialized
-    // and we're in infinite cache mode
-    if (cacheIndefinitely && allCache != null) {
+    // and we're in infinite cache mode. Under FDv2 this branch is dead once
+    // disableCache has run: the externalCache path above supersedes it.
+    if (cacheIndefinitely && allCache != null && !cacheDisabled) {
       // If we're in infinite cache mode, then we can assume the cache has a full set of current
       // flag data (since presumably the data source has still been running) and we can just
       // write the contents of the cache to the underlying data store.