feat(flagd): Implement dual-mode selector handling (header and body) for in-process mode in python-sdk-contrib

[Copilot]

This PR implements dual-mode selector passing for the flagd provider, specifically for in-process and file resolver modes only. RPC mode is not affected by these changes.

Context

Refer to open-feature/flagd#1814 and the related implementation change to selector normalization across flagd services.

Changes Made

Implementation Updates

• Dual transmission implementation: Updated GrpcWatcher to pass selector via both flagd-selector gRPC metadata header and request body
• Type system enhancement: Extended GrpcMultiCallableArgs to support gRPC metadata headers
• Test coverage: Added test to verify selector is passed via both metadata header and request body
• Maximum compatibility: Implementation ensures compatibility with all flagd versions (older and v0.11.0+)

Documentation Updates

• Updated "Selector Handling" section in the flagd provider README to reflect dual transmission approach
• Clear scope indication: Documented that selector changes only affect in-process and file resolver modes (not RPC)
• Backward compatibility documentation: Explained dual transmission strategy for maximum compatibility
• Configuration table note: Added reference to the selector handling section
• Provider docstring update: Updated the selector parameter documentation to reflect dual transmission approach

Key Implementation Details

• Current behavior: The SDK passes selectors via both methods simultaneously:
  • flagd-selector gRPC metadata header (for flagd v0.11.0+ selector normalization)
  • Request body field (for backward compatibility with older flagd versions)
• Full backward compatibility: Works seamlessly with both older and newer flagd versions
• No migration required: Existing user code continues to work without changes; the implementation detail of how selectors are transmitted is handled internally
• Links to upstream: Referenced the upstream flagd issue #1814 for additional context

Technical Changes

1. GrpcWatcher (grpc_watcher.py):

   • Added _create_metadata() method to construct gRPC metadata with flagd-selector header
   • Updated _create_request_args() to include selector in request body for backward compatibility
   • Updated listen() method to include metadata in gRPC calls

2. Type Definitions (types.py):

   • Added metadata field to GrpcMultiCallableArgs TypedDict

3. Test Suite (test_grpc_watcher.py):

   • Added test_selector_passed_via_both_metadata_and_body() to verify selector is passed via both methods

Fixes #319

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[flagd] Document migration guidance and update samples for selector handling</issue_title>
<issue_description>### Context
Refer to open-feature/flagd#1814 and the related implementation change to selector handling across flagd services.

Requirements

• Document migration path for users of python-sdk-contrib with respect to selector normalization, specifically calling out changes to usage of flagd-selector header
• Update SDK and plugin usage samples to reflect the preferred approach
• Add deprecation notice to any examples or docs that still use request body selector
• Ensure backwards compatibility documentation is included.

Tasks

1. Update user-facing documentation and guides for selector normalization
2. Ensure SDK/plugin samples use the new preferred header
3. Add a section on maintaining backward compatibility and preparing for future major version breaking change

Additional notes

• Work should align with documentation approaches used in core flagd
• Link to upstream issue: [FEATURE] Normalize selector handling across sync, evaluation, and OFREP services flagd#1814
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [flagd] Update selector handling for consistency with sync, evaluation, and OFREP services #319

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[gemini-code-assist]

Code Review

This pull request successfully implements dual-mode selector handling for the flagd provider's in-process mode, ensuring backward compatibility by passing the selector in both gRPC metadata and the request body. The changes are well-implemented across the provider logic, type definitions, and documentation. A new test case effectively verifies the dual-transmission behavior. My review includes a minor suggestion to improve code readability in the test suite. Overall, this is a solid contribution that enhances compatibility.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.53%. Comparing base (8434aab) to head (5ec3a67).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #320      +/-   ##
==========================================
+ Coverage   94.56%   95.53%   +0.96%     
==========================================
  Files          22       16       -6     
  Lines        1068      874     -194     
==========================================
- Hits         1010      835     -175     
+ Misses         58       39      -19     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[aepfli]

/gemini review

[gemini-code-assist]

Code Review

This pull request successfully implements dual-mode selector handling for the flagd provider's in-process mode, ensuring backward compatibility by passing the selector in both the gRPC metadata header and the request body. The changes are well-structured, with logic correctly refactored into new methods in GrpcWatcher and types updated accordingly. A new test case has been added to verify the dual-transmission behavior. The documentation has also been updated to reflect these changes. I've found a minor inaccuracy in the README documentation that should be addressed.