feat(flagd): Implement header-based selector for in-process sync stream connection #1622

[Copilot]

• Review flagd issue #1814 to understand selector normalization changes
• Document migration path for in-process provider selector handling
• Update README with selector header usage guidance
• Add deprecation notice for request body selector approach
• Document backward compatibility considerations
• Add section on preparing for future breaking changes
• Add cross-references to gRPC interceptor section
• Add JavaDoc comments to FlagdOptions.selector field
• Verify documentation with build and tests
• Implement header-based selector via ClientInterceptor in SyncStreamQueueSource
• Update documentation to reflect automatic header-based implementation
• Fix JavaDoc formatting errors (checkstyle compliance)

Summary

This PR implements the header-based selector approach for the flagd provider's in-process mode, addressing flagd issue #1814.

Implementation Changes:

• SyncStreamQueueSource.java: Added ClientInterceptor that automatically injects the flagd-selector header when selector is configured
• Selector is passed via gRPC metadata header (preferred approach per flagd #1814)
• Request body selector is still sent for backward compatibility with older flagd versions
• All existing tests pass without modification

Documentation Updates:

• README.md: Updated to reflect automatic header-based implementation, no migration needed for users
• FlagdOptions.java: Updated JavaDoc with proper formatting (checkstyle compliant)

Key Benefits:

• ✅ Users don't need to make any code changes
• ✅ Backward compatible with older flagd versions
• ✅ Future-proof with newer flagd versions that may remove request body selector
• ✅ Aligns with flagd selector normalization standards
• ✅ All builds and tests pass (0 checkstyle violations)

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 java-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

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 #1622

---

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

[aepfli]

@copilot please continue

[Copilot]

@copilot please continue

I've documented the selector migration guidance for in-process mode. The changes include:

1. New section "Selector filtering (In-process mode only)" explaining current and future approach
2. Migration guidance with code examples for using flagd-selector header via ClientInterceptor
3. Deprecation notices highlighting that the request body approach may be removed in future flagd versions
4. Backward compatibility information showing both approaches work during migration
5. Cross-references linking to the gRPC interceptor section

The documentation emphasizes this only affects in-process resolver mode and provides a clear path forward for users. See commit 0e8b0e6.

[aepfli]

@copilot i think there was a mixup with the issue titles, can you adopt the grpc connection for the sync stream endpoint to connect via a header for the selector. and not just document it

[Copilot]

@copilot i think there was a mixup with the issue titles, can you adopt the grpc connection for the sync stream endpoint to connect via a header for the selector. and not just document it

I've implemented the header-based selector approach for the sync stream gRPC connection. The SDK now automatically passes the selector via the flagd-selector header (the preferred approach per flagd #1814) while maintaining backward compatibility with older flagd versions by also sending it in the request body.

Changes made:

• Implementation (commit 48cb95b): Added ClientInterceptor in SyncStreamQueueSource that automatically injects the flagd-selector header when selector is configured
• Documentation (commit 388f82f): Updated README and JavaDoc to reflect that users don't need to make any code changes - the SDK handles it automatically

All existing tests pass without modification.

[aepfli]

@copilot can you fix the java doc the build is failing due to

 Error:  /home/runner/work/java-sdk-contrib/java-sdk-contrib/providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdOptions.java:127:8: <p> tag should be placed immediately before the first word, with no space after. [JavadocParagraph]
Error:  /home/runner/work/java-sdk-contrib/java-sdk-contrib/providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdOptions.java:127:8: <p> tag should be preceded with an empty line. [JavadocParagraph]
Error:  /home/runner/work/java-sdk-contrib/java-sdk-contrib/providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdOptions.java:131:8: <p> tag should be placed immediately before the first word, with no space after. [JavadocParagraph]
Error:  /home/runner/work/java-sdk-contrib/java-sdk-contrib/providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdOptions.java:131:8: <p> tag should be preceded with an empty line. [JavadocParagraph]
Error:  /home/runner/work/java-sdk-contrib/java-sdk-contrib/providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdOptions.java:134: Javadoc tag '@see' should be preceded with an empty line. [RequireEmptyLineBeforeBlockTagGroup]

and can you incoporate the feedback from gemini

[Copilot]

@copilot can you fix the java doc the build is failing due to

 Error:  /home/runner/work/java-sdk-contrib/java-sdk-contrib/providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/...

Fixed the JavaDoc formatting errors in commit d9f840f. All checkstyle violations are now resolved (0 violations).

The fixes included:

• Added empty lines before <p> tags
• Removed spaces after <p> tags
• Added empty line before @see tag

Build and tests pass successfully. Please provide the specific Gemini feedback you'd like me to incorporate, as I don't have direct access to the review comments.

[aepfli]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a header-based selector for the in-process flagd provider, aligning with flagd's selector normalization. The implementation correctly uses a ClientInterceptor to add the flagd-selector header while maintaining backward compatibility by also sending the selector in the request body. The documentation updates in the README and Javadocs are clear and comprehensive. The code is well-structured. I have one suggestion regarding the testability of the new interceptor logic.

[gemini-code-assist]

This new logic for adding the selector interceptor is not covered by existing tests, as they mock the gRPC stubs directly. To improve testability, consider extracting the channel and stub creation logic into a separate, package-private method. This would allow you to write a unit test that verifies the interceptor is correctly added when a selector is present, without needing a full gRPC channel.

[aepfli]

I am not sure how to really test this properly - we can test if the interceptor is added, but i do not find an easy way to test if the interceptor actually works. - this would be an e2e test scenario, but we would need to somehow add a flag to flagd, to only accept headers, which is imho not worth the effort - please if somebody has an idea, let me know.