Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/sdk-compliance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,20 +29,20 @@ jobs:

compliance:
name: PostHog SDK compliance tests (capture v0)
uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@75fb00092c6045daef60c30acc10ac83afefbfe9 # 1.27.0
uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@003d4162421193b458bbaa93fbb7bb0d0104bc3b # 1.31.1
with:
adapter-dockerfile: "sdk_compliance_adapter/Dockerfile"
adapter-context: "."
test-harness-version: "1.28.0"
test-harness-version: "1.31.1"
continue-on-error: false
report-name: "sdk-compliance-report-v0"

compliance-v1:
name: PostHog SDK compliance tests (capture v1)
uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@75fb00092c6045daef60c30acc10ac83afefbfe9 # 1.27.0
uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@003d4162421193b458bbaa93fbb7bb0d0104bc3b # 1.31.1
with:
adapter-dockerfile: "sdk_compliance_adapter/Dockerfile.v1"
adapter-context: "."
test-harness-version: "1.28.0"
test-harness-version: "1.31.1"
continue-on-error: false
report-name: "sdk-compliance-report-v1"
5 changes: 5 additions & 0 deletions .sampo/changesets/fix-failed-flag-records.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: patch
---

Treat server-marked failed feature flag records as unevaluated: direct result, value, enabled and payload getters return None rather than a disabled False result or placeholder payload. Snapshot value and payload reads return None, enablement honors the caller's default, and failed keys are omitted from enumeration and capture enrichment. Bulk value and payload maps omit failed remote records while preserving successful locally computed values and payloads for those keys. Preserve selected or accessed failure diagnostics through snapshot filters and report local_evaluation_inconclusive alongside evaluation_failed after an unresolved failed fallback; healthy False and malformed-record compatibility are unchanged.
5 changes: 5 additions & 0 deletions .sampo/changesets/openfeature-failed-flag-defaults.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/openfeature-provider-posthog: patch
---

Document failed-record default handling with the updated PostHog SDK: a server-marked failed flag supplies no result, so the provider's existing FlagNotFoundError mapping lets OpenFeature return the caller's default instead of treating the failed record as a healthy disabled flag. This behavior requires upgrading the installed posthog dependency; the provider's compatible dependency range is unchanged and this patch intent does not force that upgrade.
72 changes: 52 additions & 20 deletions posthog/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -666,18 +666,19 @@ def _capture_flag_events(

Every read that sends flag events comes here, on both clients: the single-flag
getters and the reads of an ``evaluate_flags()`` snapshot. Both events are built
from ``details``, the parsed ``/flags`` record that supplied the value, and the
call's ``properties``; the flag is never evaluated again.
from ``details``, the parsed ``/flags`` record supplying the value or failure
diagnostics, and the call's ``properties``; the flag is never evaluated again.

``$feature_flag_called`` is sent if the (distinct_id, flag, response, groups)
tuple hasn't already been reported on this client. Group context is included so
that group-scoped flags fire a separate event for each group a user is evaluated
under. A config version 2 record that supplied the reported value
under. A config version 2 record supplying the value or failed-record diagnostics
(``value_from_details``) adds its attribution to the event and to that tuple, so
equal-valued A/A arms, successive experiments of one flag, and holdouts are each
reported. Its reason code replaces the human-readable ``$feature_flag_reason``.
A config version 1 event and tuple are unchanged, and so are those of a read
whose value the record did not supply.
A failed record keeps its config version and reason code, but no rule tuple or
experiment exposure. Config version 1 events and reads reporting a successful
caller override or stale cached value keep their existing attribution.

``has_experiment`` is the server-reported signal for whether the flag is linked
to an experiment (``None`` when the server did not report it). When the
Expand Down Expand Up @@ -710,9 +711,8 @@ def _capture_flag_events(
groups_key = (
tuple(sorted((str(k), str(v)) for k, v in groups.items())) if groups else ()
)
# Only a record that supplied the reported value attributes it. A caller's
# match_value and a stale cached value are reported as before, with no config
# version 2 properties, even when a config version 2 record came with them.
# A failed record still reports its config version and reason code. A successful
# caller override or stale cached value has no config version 2 attribution.
attribution = _rule_attribution(details) if value_from_details else None
# What both config version 2 events report about the read itself. Each event
# pins it, so a super property cannot make the pair disagree.
Expand Down Expand Up @@ -5030,10 +5030,10 @@ def _get_remote_flag_result(
self.log.debug(
f"Successfully computed flag remotely: #{key} -> #{read.result}"
)
# A payload lookup for a caller's match_value reports that value, not
# the record's. A failure above falls back to a stale cached value.
read.value_from_details = (
read.details is not None and override_match_value is None
# A successful payload override reports the caller's value. A failed
# record keeps its config version and reason code, never the override.
read.value_from_details = read.details is not None and (
override_match_value is None or read.details._server_marked_failed
)
except QuotaLimitError as e:
self.log.warning(f"[FEATURE FLAGS] Quota limit exceeded: {e}")
Expand Down Expand Up @@ -5096,6 +5096,8 @@ def _remote_flag_result_error(errors_while_computing, flag_details):
errors.append(FeatureFlagError.ERRORS_WHILE_COMPUTING)
if flag_details is None:
errors.append(FeatureFlagError.FLAG_MISSING)
elif flag_details._server_marked_failed:
errors.append(FeatureFlagError.EVALUATION_FAILED)
return ",".join(errors) if errors else None

def _capture_flag_read_result(
Expand Down Expand Up @@ -5190,7 +5192,9 @@ def get_feature_flag_result(
device_id: The device ID for this request.

Returns:
Optional[FeatureFlagResult]: The feature flag result or None if disabled/not found.
Optional[FeatureFlagResult]: The evaluated result, including a healthy
disabled flag, or None when no result is available (for example,
a missing flag or a server-marked failure without a successful fallback).
"""
return self._get_feature_flag_result(
key,
Expand Down Expand Up @@ -5439,9 +5443,8 @@ def _capture_feature_flag_called(
local_flag_id: Optional[int] = None,
local_flag_version: Optional[int] = None,
*,
# Keyword-only, and false by default: a caller that does not say the record
# supplied the value reports no config version 2 attribution and sends no
# $experiment_exposure.
# Opt in when the record supplies the value or failed-record diagnostics.
# Failed records keep config version and reason code, but send no exposure.
value_from_details: bool = False,
):
properties: dict[str, Any] = {
Expand Down Expand Up @@ -5511,9 +5514,9 @@ def _capture_feature_flag_called_if_needed(
Shared by the single-flag evaluation path and the reads of a
``FeatureFlagEvaluations`` snapshot, so every read reports and dedupes
identically. ``details`` is the parsed ``/flags`` record of the read, or
``None`` for a locally evaluated flag. ``value_from_details`` says whether that
record supplied the reported value; only then does the read report config
version 2 attribution or send an exposure.
``None`` for a locally evaluated flag. ``value_from_details`` includes a
failed record supplying config-version and reason-code diagnostics despite
having no value. Only a successful experiment split sends an exposure.
"""
_capture_flag_events(
self.capture,
Expand Down Expand Up @@ -5725,7 +5728,32 @@ def get_all_flags_and_payloads(
flag_keys_to_evaluate=flag_keys_to_evaluate,
device_id=device_id,
)
response = to_flags_and_payloads(decide_response)
remote_response = to_flags_and_payloads(decide_response)
# A key the server marked failed keeps its locally computed value
# and payload. Successful remote records replace local results.
failed_keys = {
key
for key, detail in decide_response.get("flags", {}).items()
if detail._server_marked_failed
}
response = {
"featureFlags": {
**{
k: v
for k, v in (response["featureFlags"] or {}).items()
if k in failed_keys
},
**(remote_response["featureFlags"] or {}),
},
"featureFlagPayloads": {
**{
k: v
for k, v in (response["featureFlagPayloads"] or {}).items()
if k in failed_keys
},
**(remote_response["featureFlagPayloads"] or {}),
},
}
except Exception as e:
self.log.exception(
f"[FEATURE FLAGS] Unable to get feature flags and payloads: {e}"
Expand Down Expand Up @@ -5930,6 +5958,10 @@ def _evaluate_flags_with_context(
key: reason
for key, reason in unresolved.items()
if key not in result.records
or (
isinstance(record := result.records[key], _RemoteFlagRecord)
and record.details._server_marked_failed
)
},
)

Expand Down
61 changes: 42 additions & 19 deletions posthog/feature_flag_evaluations.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
from typing import Any, Callable, Dict, List, Mapping, Optional, Set, Union

from .types import FeatureFlag as _FeatureFlag
from .types import FeatureFlagError as _FeatureFlagError
from .types import FlagMetadata as _FlagMetadata
from .types import FlagValue, UnresolvedFlagReason, _parse_flag_payload

Expand Down Expand Up @@ -152,7 +153,13 @@ def __init__(
"""Internal — instances are created by the SDK via ``Client.evaluate_flags()``."""
self._host = host
self._distinct_id = distinct_id
self._flags = flags
self._failed_flags = {
key: flag
for key, flag in flags.items()
if isinstance(flag, _RemoteFlagRecord)
and flag.details._server_marked_failed
}
self._flags = {k: v for k, v in flags.items() if k not in self._failed_flags}
Comment thread
marandaneto marked this conversation as resolved.
Resolved
Comment thread
marandaneto marked this conversation as resolved.
Resolved
Comment thread
marandaneto marked this conversation as resolved.
Resolved
self._groups: Dict[str, Union[str, int]] = dict(groups or {})
self._disable_geoip = disable_geoip
self._request_id = request_id
Expand Down Expand Up @@ -181,9 +188,10 @@ def is_enabled(
Args:
key: The feature flag key.
default_value: Returned when the flag has no value in this evaluation —
the key was not part of the evaluated set, or the evaluation itself
came back empty (failed ``/flags`` request, quota limit, or no
resolvable ``distinct_id``). Defaults to ``False``.
the key was not part of the evaluated set, the server marked its
record failed, or the evaluation itself came back empty (failed
``/flags`` request, quota limit, or no resolvable ``distinct_id``).
Defaults to ``False``.
send_feature_flag_events: Whether this read sends ``$feature_flag_called``.
When ``False``, no event is sent and the dedupe cache is left alone,
but the key still counts as accessed for :meth:`only_accessed`.
Expand All @@ -202,7 +210,8 @@ def get_flag(

Returns the variant string for multivariate flags, ``True`` for enabled flags
without a variant, ``False`` for disabled flags, and ``None`` for flags that
were not returned by the evaluation.
were not returned or whose remote record was marked failed by the server.
An unreadable remote record retains its disabled (``False``) result.

Pass ``send_feature_flag_events=False`` to skip the event for this read, as
with :meth:`is_enabled`.
Expand All @@ -229,13 +238,23 @@ def only_accessed(self) -> "FeatureFlagEvaluations":

Order-dependent: if nothing has been accessed yet, the returned snapshot is
empty. The method honors its name — pre-access if you want a populated result.
Accessed failures retain private diagnostics, not values or enrichment.
"""
filtered = {k: self._flags[k] for k in self._accessed if k in self._flags}
filtered.update(
{
k: self._failed_flags[k]
for k in self._accessed
if k in self._failed_flags
}
)
return self._clone_with(filtered)

def only(self, keys: List[str]) -> "FeatureFlagEvaluations":
"""Return a filtered copy containing only flags with the given keys. Keys that
are not present in the evaluation are dropped and logged as a warning.
Selected failures retain private diagnostics but remain absent from values,
keys and enrichment; their existing missing-value warning is unchanged.
"""
filtered: Dict[str, _EvaluatedFlagRecord] = {}
missing: List[str] = []
Expand All @@ -250,6 +269,9 @@ def only(self, keys: List[str]) -> "FeatureFlagEvaluations":
"FeatureFlagEvaluations.only() was called with flag keys that are not in the "
f"evaluation set and will be dropped: {', '.join(missing)}"
)
filtered.update(
{k: self._failed_flags[k] for k in keys if k in self._failed_flags}
)
return self._clone_with(filtered)

@property
Expand All @@ -265,8 +287,9 @@ def unresolved_flags(self) -> Mapping[str, UnresolvedFlagReason]:
A flag is listed when it has a loaded local definition, was in the requested
scope, was inconclusive locally, and no remote value filled the gap. Listed
flags are not part of :attr:`keys`, and reading one reports the
``local_evaluation_inconclusive`` error instead of ``flag_missing``. Reading
this mapping does not count as an access and does not fire any event.
``local_evaluation_inconclusive`` error instead of ``flag_missing``.
A server-marked failed fallback additionally reports ``evaluation_failed``.
Reading this mapping does not count as an access and does not fire any event.
Snapshots returned by :meth:`only` and :meth:`only_accessed`, and by
``AsyncClient.evaluate_flags()``, which evaluates only remotely, carry no
entries.
Expand Down Expand Up @@ -337,8 +360,8 @@ def _record_access(self, key: str, send_feature_flag_events: bool) -> None:
if not self._distinct_id:
return

flag = self._flags.get(key)
response = _flag_response(flag)
flag = self._flags.get(key) or self._failed_flags.get(key)
response = None if key in self._failed_flags else _flag_response(flag)
properties = self._get_flag_called_properties(key, flag, response)

self._host.capture_flag_called_event_if_needed(
Expand All @@ -350,8 +373,8 @@ def _record_access(self, key: str, send_feature_flag_events: bool) -> None:
properties=properties,
has_experiment=flag.has_experiment if flag else None,
minimal_flag_called_events=self._minimal_flag_called_events,
# The record that supplied the value. A remotely evaluated experiment
# split also sends $experiment_exposure, whatever this read returned.
# A failed record still supplies config-version and reason-code diagnostics.
# Only a successful experiment split also sends $experiment_exposure.
details=flag.details if isinstance(flag, _RemoteFlagRecord) else None,
value_from_details=True,
)
Expand Down Expand Up @@ -381,19 +404,19 @@ def _get_flag_called_properties(self, key, flag, response) -> Dict[str, Any]:
def _get_access_errors(self, key, flag) -> List[str]:
# Build the comma-joined `$feature_flag_error` matching the single-flag path's
# granularity: response-level errors (errors-while-computing, quota-limited) are
# combined with per-flag errors (flag-missing or local-evaluation-inconclusive)
# so consumers can filter by type.
# combined with per-flag errors. A failed remote fallback must not hide the
# original snapshot's local-inconclusive diagnostic.
errors: List[str] = []
if self._errors_while_computing:
errors.append("errors_while_computing_flags")
if self._quota_limited:
errors.append("quota_limited")
if flag is None:
errors.append(
"local_evaluation_inconclusive"
if key in self._unresolved_flags
else "flag_missing"
)
if key in self._failed_flags:
errors.append(_FeatureFlagError.EVALUATION_FAILED)
if key in self._unresolved_flags:
errors.append(_FeatureFlagError.LOCAL_EVALUATION_INCONCLUSIVE)
elif flag is None:
errors.append("flag_missing")
return errors


Expand Down
Loading
Loading