docs: Mark initialization as supported in the feature matrix

Co-Authored-By: rlamb@launchdarkly.com <4955475+kinyoklion@users.noreply.github.com>

Author: devin-ai-integration[bot]

README.md

@@ -14,6 +14,28 @@ This provider is designed primarily for use in multi-user systems such as web se
 
 This version of the LaunchDarkly provider works with Java 11 and above.
 
+## Feature matrix
+
+This matrix mirrors the [feature matrix of the OpenFeature SDK for Java](https://github.com/open-feature/java-sdk#-features) and describes what this provider supports. Rows which are not supported state whether the limitation comes from the OpenFeature Java SDK or from the provider.
+
+| Status | Feature                         | Notes                                                                                                                                                                                                                     |
+|--------|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ✅      | Providers                       | Evaluates boolean, string, integer, double, and object flags through the LaunchDarkly Java SDK.                                                                                                                            |
+| ✅      | Targeting                       | The `EvaluationContext` is converted to a LaunchDarkly single or multi-context. See [OpenFeature Specific Considerations](#openfeature-specific-considerations).                                                           |
+| ✅      | Multi-provider (experimental)   | Provided by the OpenFeature SDK, which delegates to each provider in turn; no provider support is required.                                                                                                                |
+| ✅      | Hooks                           | Hooks are registered on the OpenFeature API and client; the provider requires no additional support and its results are visible to hooks, including [flag metadata](#flag-metadata).                                       |
+| ✅      | Tracking                        | `track` sends a LaunchDarkly custom event for the evaluation context, with the tracking event value and remaining details attached.                                                                                        |
+| ✅      | Logging                         | The provider logs through the logging configuration of the `LDConfig` it is given.                                                                                                                                         |
+| ✅      | Domains                         | Domains bind clients to providers in the OpenFeature SDK; a separate provider instance may be registered per domain.                                                                                                       |
+| ✅      | Eventing                        | LaunchDarkly data source status changes are emitted as `PROVIDER_READY`, `PROVIDER_STALE`, and `PROVIDER_ERROR`. Flag changes are emitted as `PROVIDER_CONFIGURATION_CHANGED` with the changed flag key.                    |
+| ✅      | Initialization                  | `initialize` reports whether the LaunchDarkly client became ready, and a failure results in the `ERROR` state so that cached or fallback flag data is still evaluated. `Provider(String, LDConfig, Duration)` bounds initialization with a start wait duration; the other constructors wait until the data source becomes valid or permanently fails. |
+| ✅      | Shutdown                        | `shutdown` closes the LaunchDarkly client. A closed client cannot be restarted, so a new provider instance is required afterward.                                                                                          |
+| ✅      | Transaction Context Propagation | Provided by the OpenFeature SDK, which merges the transaction context into the evaluation context before the provider is called; no provider support is required.                                                          |
+| ✅      | Extending                       | This provider is itself an extension of the OpenFeature SDK. The underlying LaunchDarkly client is available through `getLdClient()` for functionality with no OpenFeature equivalent.                                      |
+| ✅      | Flag metadata                   | LaunchDarkly evaluation reason details are returned as OpenFeature flag metadata. See [Flag Metadata](#flag-metadata).                                                                                                     |
+
+<sub>Supported: ✅ | Partially supported: ⚠️ | Not supported: ❌</sub>
+
 ## Getting started
 
 ### Requisites

src/main/java/com/launchdarkly/openfeature/serverprovider/Provider.java

@@ -53,6 +53,8 @@ public String getName() {
 
     private final Object stateLock = new Object();
 
+    private boolean initializing = false;
+
     /**
      * Create a provider with the specified SDK and default configuration.
      * <p>
@@ -182,6 +184,7 @@ public void initialize(EvaluationContext evaluationContext) throws Exception {
             setState(ProviderState.READY);
         }
 
+        setInitializing(true);
         var completer = new CompletableFuture<Boolean>();
 
         client.getFlagTracker().addFlagChangeListener(detail -> {
@@ -194,19 +197,26 @@ public void initialize(EvaluationContext evaluationContext) throws Exception {
         });
 
         if (getState() == ProviderState.READY) {
+            setInitializing(false);
             return;
         }
 
-        handleDataSourceStatus(client.getDataSourceStatusProvider().getStatus(), completer);
+        boolean successfullyInitialized;
+        try {
+            handleDataSourceStatus(client.getDataSourceStatusProvider().getStatus(), completer);
 
-        // With a start wait the client constructor has already waited, so the data source has either become valid,
-        // failed permanently, or run out of time; the outcome is whatever it is now.
-        if (!startWait.isZero() && !completer.isDone()) {
-            setState(ProviderState.ERROR);
-            throw new RuntimeException("The client did not initialize within the start wait duration.");
+            // With a start wait the client constructor has already waited, so the data source has either become valid,
+            // failed permanently, or run out of time; the outcome is whatever it is now.
+            if (!startWait.isZero() && !completer.isDone()) {
+                setState(ProviderState.ERROR);
+                throw new RuntimeException("The client did not initialize within the start wait duration.");
+            }
+            successfullyInitialized = completer.get();
+        } finally {
+            setInitializing(false);
         }
 
-        if (!completer.get()) {
+        if (!successfullyInitialized) {
             throw new RuntimeException("Failed to initialize LaunchDarkly client.");
         }
     }
@@ -225,19 +235,24 @@ private void handleDataSourceStatus(DataSourceStatusProvider.Status res, Complet
             }
             break;
             case VALID: {
+                boolean becameReady = false;
                 boolean emit = false;
                 synchronized (stateLock) {
                     // If we are ready, then we don't want to emit it again. Other conditions we may be updating the
                     // reason we are stale or interrupted, so we want to emit an event each time.
                     if (state != ProviderState.READY) {
-                        emit = true;
-                        setState(ProviderState.READY);
+                        becameReady = true;
+                        // The OpenFeature SDK emits its own ready event when initialization succeeds.
+                        emit = !initializing;
+                        state = ProviderState.READY;
                     }
                 }
 
-                if (emit) {
+                if (becameReady) {
                     completer.complete(true);
-                    emitProviderReady(ProviderEventDetails.builder().build());
+                    if (emit) {
+                        emitProviderReady(ProviderEventDetails.builder().build());
+                    }
                 }
             }
             break;
@@ -254,6 +269,12 @@ private void handleDataSourceStatus(DataSourceStatusProvider.Status res, Complet
         }
     }
 
+    private void setInitializing(boolean initializing) {
+        synchronized (stateLock) {
+            this.initializing = initializing;
+        }
+    }
+
     private void setState(ProviderState state) {
         synchronized (stateLock) {
             this.state = state;

src/test/java/com/launchdarkly/openfeature/serverprovider/LifeCycleTest.java

@@ -106,6 +106,29 @@ public void close() throws IOException {
     }
 }
 
+class ControllableDataSource implements DataSource {
+    public Future<Void> start() {
+        return new CompletableFuture<>();
+    }
+
+    public boolean isInitialized() {
+        return false;
+    }
+
+    public void close() throws IOException {
+    }
+}
+
+class ControllableDataSourceFactory implements ComponentConfigurer<DataSource> {
+    final CompletableFuture<DataSourceUpdateSink> sink = new CompletableFuture<>();
+
+    @Override
+    public DataSource build(ClientContext clientContext) {
+        sink.complete(clientContext.getDataSourceUpdateSink());
+        return new ControllableDataSource();
+    }
+}
+
 class DelayedDataSourceFactory implements ComponentConfigurer<DataSource> {
     private Duration startDelay;
     private boolean willError;
@@ -254,14 +277,19 @@ public void itCanHandleClientThatIsNotInitializedImmediately() throws Exception
         assertEquals(ProviderState.NOT_READY, provider.getState());
 
         var readyCount = new AtomicInteger();
+        CompletableFuture<Boolean> gotReadyEvent = new CompletableFuture<>();
 
         OpenFeatureAPI.getInstance().on(ProviderEvent.PROVIDER_READY, (detail) -> {
             readyCount.getAndIncrement();
+            gotReadyEvent.complete(true);
         });
 
         OpenFeatureAPI.getInstance().setProviderAndWait(provider);
 
         assertEquals(ProviderState.READY, provider.getState());
+        assertTrue(gotReadyEvent.get(1000, TimeUnit.MILLISECONDS));
+
+        Thread.sleep(100);
         assertEquals(1, readyCount.get());
     }
 
@@ -366,6 +394,54 @@ public void initializationWaitsIndefinitelyWhenStartWaitIsZero() throws Exceptio
         provider.shutdown();
     }
 
+    @Test
+    public void itEmitsReadyWhenTheDataSourceRecoversFromAFailedInitialization() throws Exception {
+        var dataSourceFactory = new ControllableDataSourceFactory();
+        var config = new LDConfig.Builder()
+            .startWait(Duration.ZERO)
+            .dataSource(dataSourceFactory)
+            .events(Components.noEvents())
+            .build();
+        var provider = new Provider("fake-key", config);
+        var sink = dataSourceFactory.sink.get(1000, TimeUnit.MILLISECONDS);
+
+        var readyCount = new AtomicInteger();
+        CompletableFuture<Boolean> gotReadyEvent = new CompletableFuture<>();
+        CompletableFuture<Boolean> gotErrorEvent = new CompletableFuture<>();
+
+        OpenFeatureAPI.getInstance().on(ProviderEvent.PROVIDER_READY, (detail) -> {
+            readyCount.getAndIncrement();
+            gotReadyEvent.complete(true);
+        });
+
+        OpenFeatureAPI.getInstance().on(ProviderEvent.PROVIDER_ERROR, (detail) -> {
+            gotErrorEvent.complete(true);
+        });
+
+        sink.updateStatus(DataSourceStatusProvider.State.OFF, new DataSourceStatusProvider.ErrorInfo(
+            DataSourceStatusProvider.ErrorKind.NETWORK_ERROR,
+            404,
+            "bad",
+            LocalDateTime.now().toInstant(ZoneOffset.UTC)));
+
+        GeneralError initializationError = null;
+        try {
+            OpenFeatureAPI.getInstance().setProviderAndWait(provider);
+        } catch (GeneralError e) {
+            initializationError = e;
+        }
+
+        assertNotNull(initializationError);
+        assertTrue(gotErrorEvent.get(1000, TimeUnit.MILLISECONDS));
+
+        sink.updateStatus(DataSourceStatusProvider.State.VALID, null);
+
+        assertTrue(gotReadyEvent.get(1000, TimeUnit.MILLISECONDS));
+
+        Thread.sleep(100);
+        assertEquals(1, readyCount.get());
+    }
+
     @Test
     public void itIncludesTheDataSourceErrorInErrorEvents() throws Exception {
         var config = new LDConfig.Builder()