fix: synchronize provider shutdown state

Author: WuJiayi0307

README.md

@@ -92,9 +92,11 @@ FeatBit states are mapped as follows:
 | initializing | `NOT_READY` during provider initialization |
 | OK | `READY` |
 | interrupted | `STALE` |
-| normal off during provider shutdown | `NOT_READY` |
-| permanently off with an error | `FATAL` |
-| provider shutdown | `NOT_READY` |
+| off observed while provider is active | `FATAL` |
+
+After `api.shutdown()`, OpenFeature removes this provider and installs its default
+no-op provider. Status after that point belongs to the OpenFeature SDK rather than
+to FeatBit.
 
 The included `py.typed` marker declares this package as PEP 561 typed, allowing
 type checkers to use the annotations shipped with the provider after install.

featbit_openfeature/provider.py

@@ -62,7 +62,10 @@ def __init__(self, client: FBClient, initialization_timeout: float = 15.0):
         self._initialization_timeout = initialization_timeout
         self._context_converter = EvaluationContextConverter()
         self._details_converter = ResolutionDetailsConverter()
-        self._lifecycle_lock = threading.Lock()
+        # Listener registration and event emission can synchronously re-enter
+        # provider lifecycle methods through user callbacks.
+        self._lifecycle_lock = threading.RLock()
+        self._shutdown_started = False
         self._flag_change_listener: _FlagChangeListener | None = None
         self._status_listener_registered = False
 
@@ -75,19 +78,23 @@ def initialize(self, evaluation_context: EvaluationContext) -> None:
         # Register before waiting so a client that connects just after an
         # initialization timeout can still publish its recovery to OpenFeature.
         self._register_listeners()
-        if not self._client.initialize:
-            ready = self._client.update_status_provider.wait_for_OKState(
-                self._initialization_timeout
-            )
-            if not ready:
-                state = self._client.update_status_provider.current_state
-                message = self._state_message(state)
-                if state.state_type == StateType.OFF:
-                    raise ProviderFatalError(message)
-                raise ProviderNotReadyError(message)
+        with self._lifecycle_lock:
+            if self._shutdown_started:
+                raise ProviderFatalError("FeatBit provider is shut down")
+
+        ready = self._client.update_status_provider.wait_for_OKState(
+            self._initialization_timeout
+        )
+        if not ready:
+            state = self._client.update_status_provider.current_state
+            message = self._state_message(state)
+            if state.state_type == StateType.OFF:
+                raise ProviderFatalError(message)
+            raise ProviderNotReadyError(message)
 
     def shutdown(self) -> None:
         with self._lifecycle_lock:
+            self._shutdown_started = True
             flag_listener = self._flag_change_listener
             status_listener_registered = self._status_listener_registered
 
@@ -264,6 +271,9 @@ def _type_mismatch_details(default_value: Any) -> FlagResolutionDetails[Any]:
 
     def _register_listeners(self) -> None:
         with self._lifecycle_lock:
+            if self._shutdown_started:
+                return
+
             if not self._status_listener_registered:
                 try:
                     self._client.update_status_provider.add_listener(
@@ -285,32 +295,33 @@ def _register_listeners(self) -> None:
 
     def _emit_configuration_changed(self, flag_key: str) -> None:
         try:
-            self.emit_provider_configuration_changed(
-                ProviderEventDetails(flags_changed=[flag_key])
-            )
+            with self._lifecycle_lock:
+                if self._shutdown_started:
+                    return
+                self.emit_provider_configuration_changed(
+                    ProviderEventDetails(flags_changed=[flag_key])
+                )
         except Exception:
             logger.exception("Failed to emit OpenFeature configuration change event")
 
     def _handle_data_update_status(self, state: State) -> None:
         try:
-            if state.state_type == StateType.OK:
-                self.emit_provider_ready(ProviderEventDetails())
-            elif state.state_type == StateType.INTERRUPTED:
-                self.emit_provider_stale(
-                    ProviderEventDetails(message=self._state_message(state))
-                )
-            elif state.state_type == StateType.OFF:
-                if state.error_track is not None:
+            with self._lifecycle_lock:
+                if self._shutdown_started:
+                    return
+                if state.state_type == StateType.OK:
+                    self.emit_provider_ready(ProviderEventDetails())
+                elif state.state_type == StateType.INTERRUPTED:
+                    self.emit_provider_stale(
+                        ProviderEventDetails(message=self._state_message(state))
+                    )
+                elif state.state_type == StateType.OFF:
                     self.emit_provider_error(
                         ProviderEventDetails(
                             error_code=ErrorCode.PROVIDER_FATAL,
                             message=self._state_message(state),
                         )
                     )
-                # A normal OFF is produced by FBClient.stop(). Provider
-                # shutdown unregisters this listener before stopping the
-                # client; OpenFeature then removes the provider status, whose
-                # standard fallback is NOT_READY. Do not misreport it FATAL.
         except Exception:
             logger.exception("Failed to emit OpenFeature provider status event")
 

tests/test_provider.py

@@ -1,4 +1,5 @@
 from concurrent.futures import ThreadPoolExecutor
+from threading import Event, Thread
 from unittest.mock import Mock
 
 import pytest
@@ -26,6 +27,7 @@ def make_client(initialized=True):
     client.initialize = initialized
     client.flag_tracker = Mock()
     client.update_status_provider = Mock()
+    client.update_status_provider.wait_for_OKState.return_value = True
     return client
 
 
@@ -149,7 +151,7 @@ def test_initialize_returns_immediately_when_client_is_ready():
 
     provider.initialize(EvaluationContext())
 
-    client.update_status_provider.wait_for_OKState.assert_not_called()
+    client.update_status_provider.wait_for_OKState.assert_called_once_with(15.0)
     client.flag_tracker.add_flag_changed_listener.assert_called_once()
 
 
@@ -256,6 +258,48 @@ def test_shutdown_never_exposes_client_stop_failure():
     client.stop.assert_called_once_with()
 
 
+def test_shutdown_prevents_concurrent_listener_registration_and_events():
+    client = make_client()
+    provider = FeatBitProvider(client)
+    emitter = Mock()
+    provider.attach(emitter)
+    stop_entered = Event()
+    release_stop = Event()
+
+    def blocking_stop():
+        stop_entered.set()
+        release_stop.wait(timeout=2)
+
+    client.stop.side_effect = blocking_stop
+    shutdown_thread = Thread(target=provider.shutdown)
+    shutdown_thread.start()
+    assert stop_entered.wait(timeout=2)
+
+    provider._register_listeners()
+    provider._handle_data_update_status(State.ok_state())
+    provider._emit_configuration_changed("checkout")
+
+    release_stop.set()
+    shutdown_thread.join(timeout=2)
+    assert not shutdown_thread.is_alive()
+    client.update_status_provider.add_listener.assert_not_called()
+    client.flag_tracker.add_flag_changed_listener.assert_not_called()
+    emitter.assert_not_called()
+
+
+def test_initialize_after_shutdown_is_fatal_and_registers_no_listeners():
+    client = make_client()
+    provider = FeatBitProvider(client)
+    provider.shutdown()
+
+    with pytest.raises(ProviderFatalError):
+        provider.initialize(EvaluationContext())
+
+    client.update_status_provider.add_listener.assert_not_called()
+    client.flag_tracker.add_flag_changed_listener.assert_not_called()
+    client.update_status_provider.wait_for_OKState.assert_not_called()
+
+
 def test_runtime_featbit_status_updates_openfeature_provider_status():
     client = make_client()
     provider = FeatBitProvider(client)
@@ -273,17 +317,16 @@ def test_runtime_featbit_status_updates_openfeature_provider_status():
         listener(State.ok_state())
         assert openfeature_client.get_provider_status() == ProviderStatus.READY
 
-        # A clean OFF is the result of lifecycle shutdown and must not be
-        # reported as a fatal provider failure.
+        # Any OFF observed while the provider is active means the underlying
+        # client can no longer evaluate flags safely.
         listener(State.normal_off_state())
-        assert openfeature_client.get_provider_status() == ProviderStatus.READY
-
-        listener(State.error_off_state("credential", "invalid secret"))
         assert openfeature_client.get_provider_status() == ProviderStatus.FATAL
     finally:
         api.shutdown()
 
-    assert openfeature_client.get_provider_status() == ProviderStatus.NOT_READY
+    # OpenFeature shutdown replaces the registered provider with its ready
+    # no-op provider; the FeatBit provider itself no longer emits events.
+    assert openfeature_client.get_provider_status() == ProviderStatus.READY
     client.stop.assert_called_once_with()