feat: add custom headers support for sync providers

[raflFaisal]

Summary

Add support for custom headers in HTTP and gRPC sync providers

Problem

flagd's sync providers cannot inject custom request headers into outbound requests. This limits integration with environments where intermediaries (API gateways, reverse proxies, service meshes) require specific headers for routing, tenant identification, or policy enforcement, resulting in errors like 421 Misdirected Request or misrouting.

Solution

flagd start --sources='[{"uri":"https://proxy-gateway.xyz.com/flags/sync","provider":"http","headers":{"X-Proxy-Gateway-Host":"backend-api.service"}}]'

Headers are sent as HTTP request headers for HTTP sync and as gRPC metadata for gRPC sync.

Examples:

gRPC with headers:

flagd start \
  --sources='[{"uri":"proxy-gateway-server.xyz.com","provider":"grpc","selector":"features","headers":{"X-Routing-Target-Host":"b.flags-server.service"}}]'

Using environment variables:

export FLAGD_SOURCES='[{"uri":"https://proxy-gateway.bk-eu-west6.service-mesh.dqs.booking.com/v2/flags/sync?project=flags","provider":"http", "headers":{"X-Proxy-Gateway-Host":"b-flags-api.service"}}]' 
./bin/flagd start  --debug 

Scope & compatibility

Fully backward compatible, headers are optional and default to empty
No behavior change for existing configurations
Covers both HTTP and gRPC sync providers

Test plan

Unit tests for HTTP sync header injection
Unit tests for gRPC sync metadata injection

[netlify]

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

Name	Link
🔨 Latest commit	f0d2b3c
🔍 Latest deploy log	https://app.netlify.com/projects/polite-licorice-3db33c/deploys/69feff6011eb3300081607d7
😎 Deploy Preview	https://deploy-preview-1960--polite-licorice-3db33c.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

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

[gemini-code-assist]

Code Review

This pull request introduces support for custom headers in both HTTP and gRPC sync providers, allowing users to specify key-value pairs via a new --sync-headers CLI flag or per-source configuration. The implementation includes logic to merge global and per-source headers, with per-source values taking precedence. Feedback focuses on ensuring deterministic behavior and correct precedence by handling header key case-insensitivity, specifically suggesting canonicalization of keys in the HTTP provider and using case-insensitive checks when merging global headers.

[toddbaert]

IMO it'd be simpler to drop the global --sync-headers flag and keep headers per-source only, like other source-level params (authHeader, certPath, etc.).

The global + per-source merging adds complexity:

• case-insensitive precedence logic with EqualFold
• env var parsing fallback since viper can't handle StringToString from env
• implicit override behavior that users need to reason about
• map[string]string is natural in the per-source JSON config but awkward as a CLI flag (custom parsing, comma-separated key=value strings)

If someone has multiple sources needing the same headers, duplicating them in the source config is straightforward and explicit. WDYT?

[toddbaert]

I'm in favor of this, but unless there's strong reason to, I'd prefer not to duplicate this as both a source option and a global option: #1960 (comment)

[raflFaisal]

Thanks @toddbaert for the review.
Makes sense, agreed. I've dropped the global --sync-headers flag and kept headers per-source only. This removes the precedence logic and keeps the solution simple.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud