feat: Add environment ID support for hooks.

[kinyoklion]

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

Implements the environmentId field of EvaluationSeriesContext from the hooks spec, which the OTel tracing hook uses for feature_flag.set.id. Mirrors launchdarkly/dotnet-core#81.

Describe the solution you've provided

EvaluationSeriesContext gains an optional environment_id, populated from the X-LD-EnvID response header sent by LaunchDarkly. Both data systems are supported, and each exposes it through a new DataSystem.environment_id property that the client reads when building the series context. Per the spec, it is only recorded from successful responses, so hooks never see an environment ID scraped off an error page.

• FDv2 already parsed the header into Basis.environment_id / Update.environment_id but discarded it; FDv2 now latches the last value seen on a success path (a _Success basis, or an update whose state is VALID).
• FDv1 had no access to the header. Streaming reads it from the Start action of the SSE client, polling reads it from the response headers, and both record it on DataSourceUpdateSinkImpl.

Sketch of the FDv1 path:

# streaming
if isinstance(action, Start):
    record_environment_id(self._data_source_update_sink, action.headers)

# polling
(all_data, headers) = self._get_all_data_with_headers()
record_environment_id(self._data_source_update_sink, headers)

Describe alternatives you've considered

Following the .NET implementation more literally, where the environment ID is stored as init metadata on the data store, would require optional extension interfaces on the public FeatureStore/DataSourceUpdateSink types. Instead, header handling stays inside the data sources and is surfaced by the data system, so externally implemented stores, sinks, feature requesters, and update processors continue to work unchanged (they simply report no environment ID).

Additional context

• No change is needed in launchdarkly-eventsource: it already exposes response headers on Start and Fault (unlike the .NET event source, which needed feat: Report event source headers on open. dotnet-eventsource#104).
• The async (experimental) client does not run hooks yet, so the async data source path is untouched.
• The environmentId support in the OTel tracing hook lives in python-server-sdk-otel and is a follow-up.

Link to Devin session: https://app.devin.ai/sessions/bfe54128e2804a96bb100e6120e9a3ef
Requested by: @kinyoklion

---

Note

Overview
Adds optional environment_id on EvaluationSeriesContext so evaluation hooks (e.g. OTel feature_flag.set.id) can see which LaunchDarkly environment the SDK is connected to, matching the hooks spec.

The ID comes from the X-LD-EnvID header on successful data-source responses only—not from error responses. FDv1 records it via streaming Start headers and polling response headers into DataSourceUpdateSinkImpl; FDv2 latches values already present on successful Basis / VALID Update objects. DataSystem.environment_id exposes the value and LDClient passes it when building hook series context.

Custom FeatureRequester implementations without get_all_data_with_headers still work (no env ID). Contract tests add the hook-environment-id capability.

^{Reviewed by Cursor Bugbot for commit 7ce7b6a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[kinyoklion]

Note

These comments were generated by Claude (multi-agent review: general / security / adversarial agents), run and posted by @rlamb.

No crash or flag-data-integrity issues found — thread safety, None-safety, backward compat, and the eventsource header contract all checked out under adversarial testing (full report available on request). Two findings worth addressing, posted inline:

1. Environment ID is recorded from error responses and exposed to hooks before initialization — diverges from the HOOK spec and the .NET implementation this PR mirrors (proven with a runnable repro).
2. The two new polling tests use unbounded ready.wait() — a regression in the fallback path hangs CI instead of failing (proven by mutation).

[kinyoklion]

[Claude] Medium: env ID is latched from error responses and exposed to hooks pre-initialization

This Fault-path record means the env ID is captured from failed responses: per ld_eventsource, Fault.headers is populated exactly when the response was non-2xx or wrong content type. The same happens in FDv2 from failed-initializer headers (fdv2.py:226) and from every synchronizer update including INTERRUPTED/OFF (fdv2.py:425), and the value is never cleared once set.

Proven with a repro: a 401 (invalid SDK key) response carrying X-LD-EnvID: env-from-401 leaves the SDK permanently uninitialized (variation() returns defaults), yet every hook receives environment_id == 'env-from-401' for the process lifetime.

This diverges from both references:

• The hooks spec says the environment ID is "provided by LaunchDarkly and only available once initialization has completed."
• The .NET implementation this PR mirrors (feat: Add environment ID support for hooks. dotnet-core#81) records it only as store init metadata written together with successfully applied data; its error handlers read only x-ld-fd-fallback. Under the same 401, .NET hooks get null.

Practical impact: any middlebox that synthesizes an error page on the SDK↔LD path (TLS-intercepting proxy, LB in front of a Relay Proxy) can permanently poison the value that downstream OTel hooks emit as feature_flag.set.id — even after the real connection recovers.

Suggestion: record only from success paths — Start here, the _Success basis in _run_initializers (drop the _Fail-headers record at fdv2.py:226), and gate fdv2.py:425 on VALID updates — then update/remove test_records_environment_id_from_error_response_headers and test_environment_id_from_initializer_error_headers, which currently codify the error-latching. If latching from errors is intentional, it deserves an explicit callout since it's a Python-only behavioral divergence.

Rider: FDv2._record_environment_id (fdv2.py:511) only skips None, so a present-but-empty X-LD-EnvID overwrites a previously correct value; the FDv1 helper filters '' (datasource_common.py). Worth applying the same isinstance(str) and != '' guard there for consistency.

[devin-ai-integration]

Agreed — fixed in b9fcb4c. Env ID is now only recorded from success paths: Start in FDv1 streaming (dropped the Fault record), the _Success basis in _run_initializers (dropped the _Fail-headers record), and synchronizer updates gated on DataSourceState.VALID. FDv2._record_environment_id now applies the same isinstance(str) and != '' guard as the FDv1 helper. The two tests that codified error-latching now assert the opposite (test_does_not_record_environment_id_from_error_response_headers, test_environment_id_is_not_recorded_from_initializer_error_headers), plus a new test_environment_id_is_not_recorded_from_non_valid_updates.

[kinyoklion]

[Claude] Medium: unbounded ready.wait() turns a regression into a CI hang

This wait (and the one at line 180) has no timeout. If the external-requester fallback in PollingUpdateProcessor._get_all_data_with_headers regresses, the resulting exception is swallowed by _poll's generic handler, ready is never set, and the test hangs forever — the repo configures no pytest-timeout, so CI hangs until the job limit rather than reporting a failure.

Verified by mutation: replacing the fallback with an unconditional self._requester.get_all_data_with_headers() call makes test_environment_id_is_none_when_requester_provides_no_headers hang rather than fail.

Suggestion: assert ready.wait(2) in both new tests, matching the bounded waits already used elsewhere in this file (e.g. ready.wait(0.5) at lines 115/137).

[devin-ai-integration]

Done in b9fcb4c — both new polling tests now use assert ready.wait(2).

[jsonbailey]

@devin rebase this PR on main and resolve the conflicts

[devin-ai-integration]

Rebased on main and pushed (585459b). The only conflict was the typing import in ldclient/impl/datasystem/__init__.py, now TYPE_CHECKING, Optional, Protocol, runtime_checkable. make lint and the full suite pass (1339 passed).