perf: Skip env-doc re-parse when document hasn't changed

``update_environment`` now sends a HEAD first and compares the
``x-flagsmith-document-updated-at`` response header against the value
stored from the last successful fetch. When they match, the GET, the
JSON parse, ``map_environment_document_to_context``, and the
overrides-index rebuild are all skipped — the cached evaluation
context is reused as-is.

On the customer's QA env this eliminates the ~5ms p99 GIL stall the
polling thread imposes every ``environment_refresh_interval_seconds``
(default 60s) — which is the largest remaining contributor to
identity-flag-eval p99 once lazy is enabled. Standard 60s polling
against a stable env now does HEAD-only round trips between actual
changes.

HEAD failures (e.g. proxy that doesn't permit it) silently fall
through to the existing GET path, so no environment regresses to a
worse-than-current behaviour if the optimisation can't apply.

beep boop

Author: khvn26

flagsmith/flagsmith.py

@@ -133,6 +133,10 @@ def __init__(
         self.__evaluation_context: typing.Optional[SDKEvaluationContext] = None
         self._segment_overrides_index: SegmentOverridesIndex = {}
         self._environment_updated_at: typing.Optional[datetime] = None
+        # Tracks the value of the ``x-flagsmith-document-updated-at`` header
+        # from the last successful environment fetch, so we can short-circuit
+        # an unchanged-document refresh without re-parsing the body.
+        self._environment_document_updated_at_header: typing.Optional[str] = None
 
         # argument validation
         if offline_mode and not offline_handler:
@@ -351,24 +355,60 @@ def track_event(
         )
 
     def update_environment(self) -> None:
+        # Cheap unchanged-document check via the API's HEAD response.
+        # The env doc is hundreds of KB and Python-parsing+mapping it
+        # holds the GIL for several ms — costs we'd rather not pay on
+        # every refresh tick when the document is identical to last time.
+        # HEAD is an optimisation only: if it fails for any reason
+        # (server, proxy, network) we just fall through to the canonical
+        # GET path and the standard error handling kicks in there.
         try:
-            environment_data = self._get_json_response(
-                self.environment_url, method="GET"
+            head = self.session.head(
+                self.environment_url,
+                timeout=self.request_timeout_seconds,
             )
-        except FlagsmithAPIError:
+            head.raise_for_status()
+            updated_at = head.headers.get("x-flagsmith-document-updated-at")
+            if (
+                updated_at is not None
+                and updated_at == self._environment_document_updated_at_header
+            ):
+                # Document is identical to the last fetch — skip the GET,
+                # the parse, and the index rebuild entirely.
+                return
+        except requests.RequestException:
+            pass
+
+        try:
+            response = self.session.get(
+                self.environment_url,
+                timeout=self.request_timeout_seconds,
+            )
+            response.raise_for_status()
+            environment_data = response.json()
+        except (requests.RequestException, ValueError):
             logger.exception("Error retrieving environment document from API")
-        else:
-            try:
-                self._evaluation_context = map_environment_document_to_context(
+            return
+
+        try:
+            self._evaluation_context = map_environment_document_to_context(
+                environment_data,
+            )
+            self._environment_updated_at = (
+                map_environment_document_to_environment_updated_at(
                     environment_data,
                 )
-                self._environment_updated_at = (
-                    map_environment_document_to_environment_updated_at(
-                        environment_data,
-                    )
-                )
-            except (KeyError, TypeError, ValueError):
-                logger.exception("Error parsing environment document")
+            )
+        except (KeyError, TypeError, ValueError):
+            logger.exception("Error parsing environment document")
+            return
+
+        # Only record the freshness marker once we've successfully
+        # applied the new document — partial failures shouldn't suppress
+        # the next refresh.
+        self._environment_document_updated_at_header = response.headers.get(
+            "x-flagsmith-document-updated-at",
+        )
 
     @property
     def _evaluation_context(self) -> typing.Optional[SDKEvaluationContext]:

tests/test_flagsmith.py

@@ -56,6 +56,69 @@ def test_update_environment_sets_environment(
     assert flagsmith._evaluation_context == evaluation_context
 
 
+@responses.activate()
+def test_update_environment__unchanged_document__skips_parse(
+    flagsmith: Flagsmith,
+    environment_json: str,
+) -> None:
+    # Given: every request (HEAD or GET) returns the same updated-at
+    # header so the second refresh sees an unchanged document.
+    fixed_header = {"x-flagsmith-document-updated-at": "1777306230.090367"}
+    responses.add(
+        method="GET",
+        url=flagsmith.environment_url,
+        body=environment_json,
+        headers=fixed_header,
+    )
+    responses.add(
+        method="HEAD",
+        url=flagsmith.environment_url,
+        headers=fixed_header,
+    )
+
+    # When: first refresh populates the context.
+    flagsmith.update_environment()
+    first_context_id = id(flagsmith._evaluation_context)
+    assert (
+        flagsmith._environment_document_updated_at_header
+        == fixed_header["x-flagsmith-document-updated-at"]
+    )
+
+    # And: second refresh sees a HEAD with the same updated-at header and
+    # short-circuits before doing the body GET / parse / index rebuild.
+    flagsmith.update_environment()
+
+    # Then: only one body GET was made (the rest are HEADs), and the
+    # context object is the same instance — never re-parsed.
+    get_calls = [c for c in responses.calls if c.request.method == "GET"]
+    head_calls = [c for c in responses.calls if c.request.method == "HEAD"]
+    assert len(get_calls) == 1
+    assert len(head_calls) >= 1
+    assert id(flagsmith._evaluation_context) == first_context_id
+
+
+@responses.activate()
+def test_update_environment__head_failure__falls_through_to_get(
+    flagsmith: Flagsmith,
+    environment_json: str,
+) -> None:
+    # Given: HEAD fails (e.g. proxy doesn't allow it) but GET works.
+    responses.add(method="HEAD", url=flagsmith.environment_url, status=405)
+    responses.add(
+        method="GET",
+        url=flagsmith.environment_url,
+        body=environment_json,
+        headers={"x-flagsmith-document-updated-at": "1777306230.090367"},
+    )
+
+    # When
+    flagsmith.update_environment()
+
+    # Then: the HEAD failure is swallowed and the GET path still applies
+    # the document, so we never lose the ability to refresh.
+    assert flagsmith._evaluation_context is not None
+
+
 @responses.activate()
 def test_get_environment_flags_calls_api_when_no_local_environment(
     api_key: str, flagsmith: Flagsmith, flags_json: str