feat: normalize selector in sync (use header as in OFREP and RPC)

[Copilot]

Problem

Currently, flagd services have inconsistent handling of selectors:

• Sync Service: Uses selector field from the request body
• Evaluation Service (v1 & v2): Uses Flagd-Selector header
• OFREP Service: Uses Flagd-Selector header

This inconsistency makes the API surface less predictable and can lead to confusion for users.

Solution

This PR normalizes selector handling by updating the sync service to accept the Flagd-Selector header as the primary method, aligning it with the evaluation and OFREP services. The implementation maintains full backward compatibility by falling back to the request body selector when the header is not present.

Changes

Core Implementation

Modified flagd/pkg/service/flag-sync/handler.go:

• Added getSelectorExpression() helper method that checks for Flagd-Selector header (via gRPC metadata) first
• Falls back to request body selector field if header is not present
• Logs a deprecation warning when the request body selector is used
• Applied the new logic to both SyncFlags() and FetchAllFlags() methods

Test Coverage

Added 5 comprehensive test cases in handler_test.go:

• Header-based selector (verifies no deprecation warning)
• Request body selector (verifies backward compatibility and deprecation warning)
• Header precedence (verifies header takes priority when both are provided)
• FetchAllFlags with header selector
• FetchAllFlags with request body selector

All existing tests continue to pass.

Migration Path

The change is fully backward compatible. Users can migrate at their convenience:

Current (deprecated):

req := &syncv1.FetchAllFlagsRequest{
    Selector: "source:my-source",
}
resp, err := client.FetchAllFlags(ctx, req)

Recommended:

md := metadata.New(map[string]string{
    "Flagd-Selector": "source:my-source",
})
ctx := metadata.NewOutgoingContext(context.Background(), md)
req := &syncv1.FetchAllFlagsRequest{}
resp, err := client.FetchAllFlags(ctx, req)

Benefits

• Consistency: All flagd services now use the same Flagd-Selector header pattern
• Backward Compatibility: Existing clients continue to work without modification
• Clear Migration Path: Deprecation warnings guide users to adopt the new approach
• Aligns with Standards: Using headers/metadata for query/filter parameters is a common gRPC pattern

Breaking Changes

None. The request body selector will be removed in a future major version (e.g., v2.0.0).

Related

Addresses #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[FEATURE] Normalize selector handling across sync, evaluation, and OFREP services</issue_title>
<issue_description>### Requirements

Problem

Currently, we have inconsistent handling of selectors across different flagd services:

• Sync Service (flagd/pkg/service/flag-sync/handler.go:34): Uses req.GetSelector() from the request body
• Evaluation Service: Uses flagd-selector header
• OFREP Service: Uses flagd-selector header

This inconsistency can lead to confusion for users and makes the API surface less predictable.

Proposal

Normalize selector handling across all services by:

1. Preferred approach: Use the flagd-selector header as the primary method for all services
2. Backward compatibility: For the sync service, continue to accept selector in the request body as a fallback for a deprecation period

Implementation Strategy

1. Update sync service to check for flagd-selector header first
2. Fall back to request body selector field if header is not present
3. Log deprecation warning when using request body selector
4. Document the change and migration path
5. Remove request body selector support in a future major version (e.g., v2.0.0)

Benefits

• Consistent API across all flagd services
• Easier to understand and use for developers
• Aligns with common patterns for query/filter parameters in gRPC metadata

Breaking Changes

None initially (backward compatible), but request body selector would be removed in a future major release.

Additional Context

The sync service currently processes the selector at:

selectorExpression := req.GetSelector()
selector := store.NewSelector(selectorExpression)

This should be updated to prioritize metadata/header values while maintaining backward compatibility.</issue_description>

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

Fixes #1814

---

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

Relates to: open-feature/flagd-schemas#199

[netlify]

✅ Deploy Preview for polite-licorice-3db33c ready!

Name	Link
🔨 Latest commit	a968b90
🔍 Latest deploy log	https://app.netlify.com/projects/polite-licorice-3db33c/deploys/690b7fe16edc770008e10325
😎 Deploy Preview	https://deploy-preview-1815--polite-licorice-3db33c.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[aepfli]

/Gemini review

[gemini-code-assist]

Code Review

This pull request normalizes selector handling in the sync service to align with other services, prioritizing the Flagd-Selector header while maintaining backward compatibility with the request body selector. The changes are well-implemented and include comprehensive tests for all scenarios. My review includes a few suggestions to refactor the new logic and test code for improved maintainability and to reduce duplication.

[toddbaert]

/gemini review

[toddbaert]

I pushed some changes in tests and reverted the go.mod/sum files.

I manually tested this and it works as expected.

[gemini-code-assist]

Code Review

This pull request successfully normalizes selector handling in the sync service by prioritizing the Flagd-Selector header over the request body, which aligns it with other services. The implementation is backward compatible and includes new tests. My review focuses on two main points: ensuring the deprecation warning for the body selector is logged at an appropriate level (Warn instead of Debug) and enhancing the tests to verify that this warning is correctly emitted. These changes will improve user guidance and test coverage.

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud