Implement selector passing via gRPC metadata header for in-process mode

- Update GrpcWatcher to pass selector via flagd-selector metadata header
- Add GrpcMultiCallableArgs.metadata field to support gRPC metadata
- Update README to reflect current header-based implementation
- Add test to verify selector is passed via metadata, not request body
- Aligns with flagd v0.11.0+ selector normalization standard

Co-authored-by: aepfli <[email protected]>

Author: Copilot

providers/openfeature-provider-flagd/README.md

@@ -111,12 +111,9 @@ The default options can be defined in the FlagdProvider constructor.
 > [!IMPORTANT]
 > This section only applies to **in-process** and **file** resolver modes. RPC mode is not affected by selector handling changes.
 
-#### Migration Guidance
+#### Current Implementation
 
-As of flagd v0.11.0 and related services, selector normalization has been updated to prefer gRPC metadata headers over request body fields for the `selector` parameter. This change affects how the in-process provider communicates with flagd's sync service.
-
-**Current Behavior (Preferred):**
-The Python SDK currently passes the `selector` via the gRPC request body when using in-process mode. While this approach continues to work for backward compatibility, the flagd ecosystem is transitioning to header-based selector passing.
+As of this SDK version, the `selector` parameter is passed via gRPC metadata headers (`flagd-selector`) when using in-process mode. This aligns with flagd v0.11.0+ selector normalization standards.
 
 **Configuration Example:**
 ```python
@@ -126,22 +123,19 @@ from openfeature.contrib.provider.flagd.config import ResolverType
 
 api.set_provider(FlagdProvider(
     resolver_type=ResolverType.IN_PROCESS,
-    selector="my-flag-source",  # Currently passed in request body
+    selector="my-flag-source",  # Passed via flagd-selector header
 ))
 ```
 
-#### Backward Compatibility
-
-The current implementation maintains backward compatibility by continuing to pass selectors in the request body. flagd services support both approaches:
-- **Request body selector** (current implementation) - Supported for backward compatibility
-- **Header-based selector** (future preferred) - Will be supported in a future SDK update
+The selector is automatically passed via the `flagd-selector` gRPC metadata header, ensuring compatibility with flagd services that implement selector normalization.
 
-#### Future Breaking Change
+#### Backward Compatibility
 
-In a future major version of this SDK, the selector handling will be updated to use gRPC metadata headers (`flagd-selector`) instead of the request body field. This aligns with the flagd ecosystem's standardized approach to selector normalization.
+flagd services maintain backward compatibility with both selector passing approaches:
+- **gRPC metadata header** (`flagd-selector`) - Current implementation (recommended)
+- **Request body selector** - Legacy approach (still supported by flagd for backward compatibility)
 
-**Action Required:**
-No immediate action is required. The current implementation will continue to work with both current and future versions of flagd services. Monitor release notes for announcements about the transition to header-based selectors.
+This ensures the Python SDK works correctly with both older and newer versions of flagd services.
 
 **Related Resources:**
 - Upstream issue: [open-feature/flagd#1814](https://github.com/open-feature/flagd/issues/1814)

providers/openfeature-provider-flagd/src/openfeature/contrib/provider/flagd/provider.py

@@ -76,8 +76,7 @@ def __init__(  # noqa: PLR0913
         :param timeout: the maximum time to wait before a request times out
         :param retry_backoff_ms: the number of milliseconds to backoff
         :param selector: filter flag configurations by source (in-process mode only)
-                         Note: Currently passed via request body. Future versions will use
-                         gRPC metadata headers. See README for migration guidance.
+                         Passed via flagd-selector gRPC metadata header.
         :param offline_flag_source_path: the path to the flag source file
         :param stream_deadline_ms: the maximum time to wait before a request times out
         :param keep_alive_time: the number of milliseconds to keep alive

providers/openfeature-provider-flagd/src/openfeature/contrib/provider/flagd/resolvers/process/connector/grpc_watcher.py

@@ -205,13 +205,24 @@ def shutdown(self) -> None:
 
     def _create_request_args(self) -> dict:
         request_args = {}
-        if self.selector is not None:
-            request_args["selector"] = self.selector
+        # Note: selector is now passed via gRPC metadata header instead of request body
+        # This maintains compatibility with flagd v0.11.0+ selector normalization
         if self.provider_id is not None:
             request_args["provider_id"] = self.provider_id
 
         return request_args
 
+    def _create_metadata(self) -> typing.Optional[typing.List[typing.Tuple[str, str]]]:
+        """Create gRPC metadata headers for the request.
+        
+        Returns gRPC metadata as a list of tuples containing header key-value pairs.
+        The selector is passed via the 'flagd-selector' header per flagd v0.11.0+ specification.
+        """
+        if self.selector is None:
+            return None
+        
+        return [("flagd-selector", self.selector)]
+
     def _fetch_metadata(self) -> typing.Optional[sync_pb2.GetMetadataResponse]:
         if self.config.sync_metadata_disabled:
             return None
@@ -233,6 +244,12 @@ def listen(self) -> None:  # noqa: C901
         call_args: GrpcMultiCallableArgs = {"wait_for_ready": True}
         if self.streamline_deadline_seconds > 0:
             call_args["timeout"] = self.streamline_deadline_seconds
+        
+        # Add selector via gRPC metadata header (flagd v0.11.0+ preferred approach)
+        metadata = self._create_metadata()
+        if metadata is not None:
+            call_args["metadata"] = metadata
+        
         request_args = self._create_request_args()
 
         while self.active:

providers/openfeature-provider-flagd/src/openfeature/contrib/provider/flagd/resolvers/types.py

@@ -4,3 +4,4 @@
 class GrpcMultiCallableArgs(typing.TypedDict, total=False):
     timeout: typing.Optional[float]
     wait_for_ready: typing.Optional[bool]
+    metadata: typing.Optional[typing.Sequence[typing.Tuple[str, str]]]

providers/openfeature-provider-flagd/tests/test_grpc_watcher.py

@@ -133,3 +133,31 @@ def test_listen_with_sync_metadata_disabled_in_config(self):
             self.provider_details.message, "gRPC sync connection established"
         )
         self.assertEqual(self.context, {})
+
+    def test_selector_passed_via_metadata_header(self):
+        """Test that selector is passed via gRPC metadata header, not request body"""
+        self.grpc_watcher.selector = "test-selector"
+        mock_stream = iter(
+            [
+                SyncFlagsResponse(flag_configuration='{"flag_key": "flag_value"}'),
+            ]
+        )
+        self.mock_stub.SyncFlags = Mock(return_value=mock_stream)
+
+        self.run_listen_and_shutdown_after()
+
+        # Verify SyncFlags was called
+        self.mock_stub.SyncFlags.assert_called_once()
+        
+        # Get the call arguments
+        call_args = self.mock_stub.SyncFlags.call_args
+        
+        # Verify the request doesn't contain selector in body
+        request = call_args[0][0]  # First positional argument is the request
+        self.assertFalse(hasattr(request, 'selector') and request.selector)
+        
+        # Verify metadata contains flagd-selector header
+        kwargs = call_args[1]
+        self.assertIn('metadata', kwargs)
+        metadata = kwargs['metadata']
+        self.assertEqual(metadata, [('flagd-selector', 'test-selector')])