[vazarkevych]

Summary

The SDK talked to a single host with only the headers it sets itself, so it could not be pointed at a
deployment where streaming is served separately — features from a CDN, streaming through a GrowthBook
Proxy — nor used behind a gateway that expects an authentication header. Both are configurable in the
reference JS SDK; this brings the Flutter SDK to parity.

Option	Applies to
streamingHost	the streaming (SSE) endpoint only; falls back to hostURL
apiHostRequestHeaders	features request + every remote-evaluation request
streamingHostRequestHeaders	streaming connection, including its reconnects

Behaviour

Semantics follow getApiHosts() in sdk-js:
the streaming host falls back to the API host, trailing slashes are dropped, and a path on the host is
preserved. Features and remote evaluation always stay on hostURL.

The header maps are copied on the way in, so a later edit of the caller's map cannot change what
requests are already carrying. Streaming headers are re-applied on every SSE reconnect, not just on
the first connection.

Reserved headers are rejected, unlike in the JS SDK. JS merges caller headers over its own
({ "Content-Type": ..., ...headers }), which lets a supplied If-None-Match silently break ETag
revalidation. Here User-Agent, If-None-Match and Cache-Control throw an ArgumentError from
initialize() in any letter case, matching the C# SDK, and the client still applies its own headers
last as a second line of defence. Content-Type is deliberately not reserved — setting
text/event-stream on the streaming connection is a real nginx workaround.

A streamingHost that is not an absolute http/https URL is rejected the same way, so a
misconfiguration surfaces at startup rather than as a failed fetch later.

Refactor in the first commit

Endpoints were built two ways: GBContext assembled the features and remote-eval URLs itself, while
FeatureURLBuilder assembled the ones the data source actually requested, including streaming. Both
were correct but had to be kept in step by hand, and a second host would have had to be threaded
through both. FeatureURLBuilder is now an instance holding the hosts, GBContext delegates to it
and gained getStreamingURL(), and the data source asks the context. No behaviour change.

Breaking change

BaseClient gained an optional {Map<String, String>? headers} on its three methods — the only
channel through which headers can reach an injected client. This breaks anyone supplying a custom
client via client:; inside the repo it only affected the test doubles. Needs a CHANGELOG note.

Tests

+19 tests, 321 in the suite, all green. flutter analyze clean, dart format clean.

• gb_sdk_request_headers_test.dart (14): API headers on the features GET and on the remote-eval
  POST but not on the stream; streaming headers on the stream but not on the API host; nothing added
  when unconfigured; a later edit of the caller's map does not leak through; SSE uses streamingHost
  when set and hostURL when not, while features and remote eval stay on the API host; invalid
  streaming hosts and reserved header names (any case, both maps) throw ArgumentError.
• utility_classes_test.dart (+5, plus the two existing builder tests updated): features, streaming
  and remote-eval endpoints, host path preservation, null host or client key, and the streaming-host
  fallback.

Notes

• Header values are never logged: no log statement receives the maps, and the existing redaction
  tests cover the failure path.
• apiHost is not added as a separate option — the existing hostURL already plays that role and
  renaming it would be breaking for no gain.
• One coupling with the open feature/attributes-merge-semantics branch: it adds three test clients
  that implement BaseClient. Whichever of the two merges second needs the new headers parameter
  added to those overrides — about five lines, and CI flags it immediately.

[andywhite37]

Please confirm the streaming-host/header API, reserved-header policy, and release target for the breaking BaseClient signatures. Existing custom clients must update their overrides, and #176 adds clients needing the same adjustment. Record the compatibility decision so review can proceed.

[vazarkevych]

Decisions:

• API: streamingHost, apiHostRequestHeaders, streamingHostRequestHeaders as proposed; names match the JS SDK.
• Reserved headers: User-Agent, If-None-Match and Cache-Control are rejected at startup (stricter than JS), so a caller cannot break ETag revalidation. Accepted.
• Release target: the BaseClient signature change is breaking, so this ships in 5.0.0 as feat!: with a migration note: custom BaseClient implementations add {Map<String, String>? headers} to the three methods.
• Merge order: after the 4.6.0 release and feat!: reject unsupported remoteEval configurations and add setUrl #189, before the 5.0.0 release PR (see Release plan #192). By then main will contain feat: add CacheStorage abstraction with per-connection namespace and custom cache directory #185, fix: re-evaluate remotely on every context change and discard stale responses #187–fix: redact the client key and request details from logs #191, so this PR will be rebased once onto main:
  • add the headers parameter to the 5 test clients from fix: re-evaluate remotely on every context change and discard stale responses #187 and feat!: reject unsupported remoteEval configurations and add setUrl #189 (feat!: add updateAttributes merge semantics and fix remote evaluation #176 was split, so the clients it added live there now);
  • replace CachingManager in its tests (feat: add CacheStorage abstraction with per-connection namespace and custom cache directory #185);
  • keep both sides where feat!: reject unsupported remoteEval configurations and add setUrl #189/feat: key the remote-eval cache by evaluation inputs and add cacheKey… #190 add their own builder options and startup checks next to this PR's;
  • add the migration note.