fix: address provider lifecycle and release review

Author: WuJiayi0307

.github/workflows/ci.yml

@@ -18,15 +18,19 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install
         run: |
           python -m pip install --upgrade pip
           python -m pip install "openfeature-sdk>=0.10,<1" "build>=1,<2" "flake8>=7,<8" "pytest>=8,<10"
-          python -m pip install "fb-python-sdk @ git+https://github.com/featbit/featbit-python-sdk.git@refs/pull/14/head"
+          # Temporary immutable pin until fb-python-sdk 1.1.8 is published.
+          python -m pip install "fb-python-sdk @ git+https://github.com/featbit/featbit-python-sdk.git@7c74e19bbb5934084802c0bee2cab6d39f4ec00d"
           python -m pip install -e . --no-deps
+          python -m pip check
       - name: Lint
         run: python -m flake8 featbit_openfeature tests
       - name: Test

.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "build>=1,<2"
+          python -m build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/featbit-openfeature-server
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -48,12 +48,11 @@ details = client.get_boolean_details(
 print(details.value, details.reason, details.variant)
 
 api.shutdown()
-fb_client.stop()
 ```
 
-The application owns the injected `FBClient`. Calling `api.shutdown()` removes
-provider listeners but does not stop the FeatBit client; call `fb_client.stop()`
-afterward so queued events are flushed and background resources are released.
+The provider owns the injected `FBClient`. Calling `api.shutdown()` removes
+provider listeners and stops the FeatBit client so queued events are flushed
+and background resources are released.
 
 ## Supported mappings
 
@@ -93,9 +92,13 @@ FeatBit states are mapped as follows:
 | initializing | `NOT_READY` during provider initialization |
 | OK | `READY` |
 | interrupted | `STALE` |
-| permanently off | `FATAL` |
+| normal off during provider shutdown | `NOT_READY` |
+| permanently off with an error | `FATAL` |
 | provider shutdown | `NOT_READY` |
 
+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.
+
 ## Development tests
 
 Unit tests use mocks, and the integration test uses FeatBit offline data. Neither
@@ -106,3 +109,14 @@ python -m pytest -q
 python -m flake8 featbit_openfeature tests
 python -m build
 ```
+
+## Release
+
+Publishing is handled by `.github/workflows/release.yml` when a GitHub Release
+is published. The build and publish jobs are separated so package build code
+never receives an OpenID Connect token. The publish job uses PyPI Trusted
+Publishing and does not store a long-lived PyPI password in GitHub.
+
+Before the first release, configure the PyPI trusted publisher with owner
+`featbit`, repository `openfeature-provider-python-server`, workflow
+`release.yml`, and GitHub environment `pypi`.

featbit_openfeature/provider.py

@@ -46,9 +46,9 @@ def on_flag_change(self, notice: FlagChangedNotice):
 class FeatBitProvider(AbstractProvider):
     """OpenFeature provider backed by an existing thread-safe ``FBClient``.
 
-    The provider does not own the client. ``shutdown`` removes the listeners
-    installed by the provider, but the application remains responsible for
-    calling ``FBClient.stop`` when it no longer needs the SDK.
+    The provider owns the injected client's lifecycle. ``shutdown`` removes
+    its listeners and stops the client so queued events and background
+    resources are released with the OpenFeature lifecycle.
     """
 
     def __init__(self, client: FBClient, initialization_timeout: float = 15.0):
@@ -72,6 +72,9 @@ def client(self) -> FBClient:
         return self._client
 
     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
@@ -83,8 +86,6 @@ def initialize(self, evaluation_context: EvaluationContext) -> None:
                     raise ProviderFatalError(message)
                 raise ProviderNotReadyError(message)
 
-        self._register_listeners()
-
     def shutdown(self) -> None:
         with self._lifecycle_lock:
             flag_listener = self._flag_change_listener
@@ -111,6 +112,13 @@ def shutdown(self) -> None:
                 with self._lifecycle_lock:
                     self._status_listener_registered = False
 
+        try:
+            self._client.stop()
+        except Exception:
+            # Provider shutdown is application lifecycle code; an extension
+            # failure in the underlying SDK must not escape into OpenFeature.
+            logger.exception("Failed to stop FeatBit client")
+
     def get_metadata(self) -> Metadata:
         return Metadata("featbit-openfeature-server")
 
@@ -292,12 +300,17 @@ def _handle_data_update_status(self, state: State) -> None:
                     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),
+                if state.error_track is not None:
+                    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_offline_integration.py

@@ -46,4 +46,3 @@ def test_openfeature_client_evaluates_with_real_featbit_sdk_offline():
         assert client.get_provider_status() == ProviderStatus.READY
     finally:
         api.shutdown()
-        fb_client.stop()

tests/test_provider.py

@@ -172,6 +172,10 @@ def test_initialize_timeout_raises_provider_not_ready():
     with pytest.raises(ProviderNotReadyError):
         provider.initialize(EvaluationContext())
 
+    client.update_status_provider.add_listener.assert_called_once_with(
+        provider._handle_data_update_status
+    )
+
 
 def test_initialize_off_state_raises_provider_fatal():
     client = make_client(initialized=False)
@@ -207,7 +211,7 @@ def test_flag_change_is_emitted_and_shutdown_removes_listener():
     client.update_status_provider.remove_listener.assert_called_once_with(
         provider._handle_data_update_status
     )
-    client.stop.assert_not_called()
+    assert client.stop.call_count == 2
 
 
 def test_flag_change_callback_exception_never_escapes():
@@ -234,11 +238,22 @@ def test_shutdown_retries_listener_removal_after_failure():
     ]
 
     provider.shutdown()
-    provider.initialize(EvaluationContext())
     provider.shutdown()
 
     client.flag_tracker.add_flag_changed_listener.assert_called_once_with(listener)
     assert client.flag_tracker.remove_flag_change_notifier.call_count == 2
+    assert client.stop.call_count == 2
+
+
+def test_shutdown_never_exposes_client_stop_failure():
+    client = make_client()
+    client.stop.side_effect = RuntimeError("boom")
+    provider = FeatBitProvider(client)
+    provider.initialize(EvaluationContext())
+
+    provider.shutdown()
+
+    client.stop.assert_called_once_with()
 
 
 def test_runtime_featbit_status_updates_openfeature_provider_status():
@@ -258,11 +273,19 @@ 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.
+        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
+    client.stop.assert_called_once_with()
+
 
 def test_status_callback_exception_never_escapes():
     client = make_client()