diff --git a/.github/workflows/sdk-compliance.yml b/.github/workflows/sdk-compliance.yml index 407411d37..a9b8f8e69 100644 --- a/.github/workflows/sdk-compliance.yml +++ b/.github/workflows/sdk-compliance.yml @@ -41,7 +41,7 @@ jobs: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ matrix.compression }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} env: - HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness:1.32.0@sha256:7eb6c62e2241ddd48a2dfb326652e7933cd2fe26e0ffcad98cd385d603b4eb82 + HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness:1.34.0@sha256:43f75861fbcf5bc6c3d35511caa2be2d55274054c6071ebeb943aca0bcd0633a steps: - name: Check out source code uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 diff --git a/.sampo/changesets/known-absent-property-keys.md b/.sampo/changesets/known-absent-property-keys.md new file mode 100644 index 000000000..2f4fee61a --- /dev/null +++ b/.sampo/changesets/known-absent-property-keys.md @@ -0,0 +1,5 @@ +--- +posthog: minor +--- + +Add `person_property_keys_known_absent` and `group_property_keys_known_absent` to flag evaluation. Local evaluation treats a listed key as absent, so `is_not_set` and negated operators match without a `/flags` request, and a listed `$feature_enrollment/` means not enrolled. Remote requests send the listed keys. Each list allows at most 1000 keys; a longer list raises `ValueError` and nothing is sent. diff --git a/posthog/__init__.py b/posthog/__init__.py index eafc2a3ac..f4edfc7e1 100644 --- a/posthog/__init__.py +++ b/posthog/__init__.py @@ -1,5 +1,5 @@ import datetime # noqa: F401 -from typing import Any, Callable, Dict, Mapping, Optional, Union # noqa: F401 +from typing import Any, Callable, Dict, Iterable, Mapping, Optional, Union # noqa: F401 from typing_extensions import Unpack @@ -847,6 +847,9 @@ def feature_enabled( send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[bool]: """ Use feature flags to enable or disable features for users. @@ -865,6 +868,10 @@ def feature_enabled( send_feature_flag_events: Whether to send feature flag events disable_geoip: Whether to disable GeoIP lookup device_id: Optional device ID override for experience-continuity flags + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Details: You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests. @@ -891,6 +898,8 @@ def feature_enabled( send_feature_flag_events=send_feature_flag_events, disable_geoip=disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) @@ -904,6 +913,9 @@ def get_feature_flag( send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[FlagValue]: """ Get feature flag variant for users. Used with experiments. @@ -922,6 +934,10 @@ def get_feature_flag( send_feature_flag_events: Whether to send feature flag events disable_geoip: Whether to disable GeoIP lookup device_id: Optional device ID override for experience-continuity flags + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Details: `groups` are a mapping from group type to group key. So, if you have a group type of "organization" and a group key of "5", you would pass groups={"organization": "5"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type "organization" and the group key "5", with the properties name, and employee count, you'll send these as: group_properties={"organization": {"name": "PostHog", "employees": 11}}. @@ -948,6 +964,8 @@ def get_feature_flag( send_feature_flag_events=send_feature_flag_events, disable_geoip=disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) @@ -960,6 +978,9 @@ def get_all_flags( disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[dict[str, FlagValue]]: """ Get all flags for a given user. @@ -973,6 +994,10 @@ def get_all_flags( disable_geoip: Whether to disable GeoIP lookup device_id: Optional device ID override for experience-continuity flags flag_keys_to_evaluate: Optional list of flag keys to evaluate (evaluates all if None) + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Details: Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False. @@ -996,6 +1021,8 @@ def get_all_flags( disable_geoip=disable_geoip, device_id=device_id, flag_keys_to_evaluate=flag_keys_to_evaluate, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) @@ -1009,6 +1036,9 @@ def get_feature_flag_result( send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[FeatureFlagResult]: """ Get a FeatureFlagResult object which contains the flag result and payload. @@ -1030,6 +1060,10 @@ def get_feature_flag_result( send_feature_flag_events: Whether to send a $feature_flag_called event. disable_geoip: Whether to disable GeoIP lookup. device_id: Optional device ID override for experience-continuity flags. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Example: ```python @@ -1051,6 +1085,8 @@ def get_feature_flag_result( send_feature_flag_events=send_feature_flag_events, disable_geoip=disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) @@ -1065,6 +1101,9 @@ def get_feature_flag_payload( send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[object]: """ Get the payload associated with a feature flag value. @@ -1083,6 +1122,10 @@ def get_feature_flag_payload( send_feature_flag_events: Whether to send a $feature_flag_called event. disable_geoip: Whether to disable GeoIP lookup. device_id: Optional device ID override for experience-continuity flags. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Returns: The payload associated with the matched feature flag value, or None. @@ -1104,6 +1147,8 @@ def get_feature_flag_payload( send_feature_flag_events=send_feature_flag_events, disable_geoip=disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) @@ -1136,6 +1181,9 @@ def get_all_flags_and_payloads( disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> FlagsAndPayloads: """ Get all feature flag values and payloads for a user. @@ -1150,6 +1198,10 @@ def get_all_flags_and_payloads( device_id: Optional device ID override for experience-continuity flags. flag_keys_to_evaluate: Optional list of flag keys to evaluate. Evaluates all flags when omitted. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Returns: A dict with ``featureFlags`` and ``featureFlagPayloads`` entries. @@ -1167,6 +1219,8 @@ def get_all_flags_and_payloads( disable_geoip=disable_geoip, device_id=device_id, flag_keys_to_evaluate=flag_keys_to_evaluate, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) @@ -1179,6 +1233,9 @@ def evaluate_flags( disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> FeatureFlagEvaluations: """Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / @@ -1208,6 +1265,17 @@ def evaluate_flags( device_id: Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes. + person_property_keys_known_absent: Person property keys the caller knows are + absent for this person. Local evaluation treats a listed key as absent, + even when ``person_properties`` supplies a value for it: ``is_not_set`` + and the negated operators match, and every other operator does not, with + no remote fallback. A listed ``$feature_enrollment/`` means not + enrolled. Keys starting with ``__posthog_person_metadata__`` are ignored. + Sent to ``/flags`` on remote evaluation. At most 1000 keys, counting + duplicates; a longer list raises ``ValueError`` and nothing is evaluated. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. A key applies only to its own group type. Same + rules and per-group-type limit as ``person_property_keys_known_absent``. Examples: ```python @@ -1231,6 +1299,8 @@ def evaluate_flags( disable_geoip=disable_geoip, flag_keys=flag_keys, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) diff --git a/posthog/async_client.py b/posthog/async_client.py index 7401e3740..cc9caed8b 100644 --- a/posthog/async_client.py +++ b/posthog/async_client.py @@ -11,7 +11,7 @@ import weakref from dataclasses import replace from datetime import datetime, timezone -from typing import Any, Callable, Dict, Mapping, Optional, Union +from typing import Any, Callable, Dict, Iterable, Mapping, Optional, Union from uuid import UUID from typing_extensions import Unpack @@ -94,6 +94,7 @@ ) from .consumer import AI_MAX_MSG_SIZE, MAX_MSG_SIZE from .emails import AsyncEmails, _client_emails, _validate_options +from .feature_flags import _validate_known_absent_keys from .feature_flag_evaluations import ( FeatureFlagEvaluations, _EvaluatedFlagRecord, @@ -1117,6 +1118,8 @@ async def _get_flags_decision( disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[list[str]] = None, + group_property_keys_known_absent: Optional[dict[str, list[str]]] = None, ): if disable_geoip is None: disable_geoip = self.disable_geoip @@ -1130,6 +1133,14 @@ async def _get_flags_decision( } if flag_keys: request_data["flag_keys_to_evaluate"] = flag_keys + if person_property_keys_known_absent: + request_data["person_property_keys_known_absent"] = ( + person_property_keys_known_absent + ) + if group_property_keys_known_absent: + request_data["group_property_keys_known_absent"] = ( + group_property_keys_known_absent + ) response = await _async_flags( self.api_key, self.host, @@ -1155,6 +1166,8 @@ async def evaluate_flags( disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> FeatureFlagEvaluations: """Evaluate flags remotely without blocking the event loop. @@ -1162,8 +1175,17 @@ async def evaluate_flags( ``capture(flags=...)`` to attach the exact values used for branching. This client does not evaluate flags locally, so the snapshot's ``unresolved_flags`` is always empty. + + ``person_property_keys_known_absent`` and ``group_property_keys_known_absent`` + (keyed by group type) list property keys the caller knows are absent. They + are sent to ``/flags``, which treats each listed key as absent even when a + value is supplied for it. Each list holds at most 1000 keys, counting + duplicates; a longer list raises ``ValueError`` and no request is sent. """ host = self._get_feature_flag_evaluations_host() + person_keys_known_absent, group_keys_known_absent = _validate_known_absent_keys( + person_property_keys_known_absent, group_property_keys_known_absent + ) if distinct_id is None: distinct_id = _get_context_distinct_id() if device_id is None: @@ -1207,6 +1229,8 @@ async def evaluate_flags( disable_geoip=disable_geoip, flag_keys=flag_keys, device_id=device_id, + person_property_keys_known_absent=person_keys_known_absent, + group_property_keys_known_absent=group_keys_known_absent, ) request_id = response.get("requestId") raw_evaluated_at = response.get("evaluatedAt") diff --git a/posthog/client.py b/posthog/client.py index 7d4de2c8a..341bfc0a1 100644 --- a/posthog/client.py +++ b/posthog/client.py @@ -19,6 +19,7 @@ Callable, Dict, FrozenSet, + Iterable, List, Mapping, NamedTuple, @@ -124,6 +125,8 @@ RequiresServerEvaluation, _get_definition_unresolved_reason, _group_key_to_string, + _mark_known_absent_properties, + _validate_known_absent_keys, match_feature_flag_properties, resolve_bucketing_value, ) @@ -2085,6 +2088,9 @@ def get_feature_variants( disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> dict[str, Union[bool, str]]: """ Get feature flag variants for a user. @@ -2098,6 +2104,10 @@ def get_feature_variants( flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Category: Feature flags @@ -2110,6 +2120,8 @@ def get_feature_variants( disable_geoip, flag_keys_to_evaluate, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) return to_values(resp_data) or {} @@ -2122,6 +2134,9 @@ def get_feature_payloads( disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> dict[str, Optional[str]]: """ Get feature flag payloads for a user, preserving valid serialized JSON. @@ -2135,6 +2150,10 @@ def get_feature_payloads( flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Examples: ```python @@ -2152,6 +2171,8 @@ def get_feature_payloads( disable_geoip, flag_keys_to_evaluate, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) return { key: _parse_flag_payload(payload, decode=False) @@ -2167,6 +2188,9 @@ def get_feature_flags_and_payloads( disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> FlagsAndPayloads: """ Get feature flags and payloads for a user. @@ -2180,6 +2204,10 @@ def get_feature_flags_and_payloads( flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Examples: ```python @@ -2197,6 +2225,8 @@ def get_feature_flags_and_payloads( disable_geoip, flag_keys_to_evaluate, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) response = to_flags_and_payloads(resp) payloads = response.get("featureFlagPayloads") @@ -2216,6 +2246,9 @@ def get_flags_decision( disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> FlagsResponse: """ Get feature flags decision. @@ -2229,6 +2262,10 @@ def get_flags_decision( flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Examples: ```python @@ -2238,6 +2275,9 @@ def get_flags_decision( Category: Feature flags """ + person_keys_known_absent, group_keys_known_absent = _validate_known_absent_keys( + person_property_keys_known_absent, group_property_keys_known_absent + ) try: return self._get_flags_decision( distinct_id, @@ -2247,6 +2287,8 @@ def get_flags_decision( disable_geoip, flag_keys_to_evaluate, device_id=device_id, + person_property_keys_known_absent=person_keys_known_absent, + group_property_keys_known_absent=group_keys_known_absent, ) except Exception as err: self.log.exception("Unable to get feature flags: %s", err) @@ -2261,6 +2303,9 @@ def _get_flags_decision( disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, + *, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> FlagsResponse: if self.disabled: return normalize_flags_response({}) @@ -2293,6 +2338,14 @@ def _get_flags_decision( if flag_keys_to_evaluate: request_data["flag_keys_to_evaluate"] = flag_keys_to_evaluate + person_keys_known_absent, group_keys_known_absent = _validate_known_absent_keys( + person_property_keys_known_absent, group_property_keys_known_absent + ) + if person_keys_known_absent: + request_data["person_property_keys_known_absent"] = person_keys_known_absent + if group_keys_known_absent: + request_data["group_property_keys_known_absent"] = group_keys_known_absent + resp_data = flags( self.api_key, self.host, @@ -2496,6 +2549,12 @@ def _capture( disable_geoip=disable_geoip, only_evaluate_locally=True, flag_keys_to_evaluate=flag_options["flag_keys_filter"], + person_property_keys_known_absent=flag_options.get( + "person_property_keys_known_absent" + ), + group_property_keys_known_absent=flag_options.get( + "group_property_keys_known_absent" + ), ) elif flag_options["only_evaluate_locally"] is False: # Remote evaluation explicitly requested @@ -2506,6 +2565,12 @@ def _capture( group_properties=flag_options["group_properties"], disable_geoip=disable_geoip, flag_keys_to_evaluate=flag_options["flag_keys_filter"], + person_property_keys_known_absent=flag_options.get( + "person_property_keys_known_absent" + ), + group_property_keys_known_absent=flag_options.get( + "group_property_keys_known_absent" + ), ) elif self.feature_flags: # Local flags available, prefer local evaluation @@ -2517,6 +2582,12 @@ def _capture( disable_geoip=disable_geoip, only_evaluate_locally=True, flag_keys_to_evaluate=flag_options["flag_keys_filter"], + person_property_keys_known_absent=flag_options.get( + "person_property_keys_known_absent" + ), + group_property_keys_known_absent=flag_options.get( + "group_property_keys_known_absent" + ), ) else: # Fall back to remote evaluation @@ -2527,6 +2598,12 @@ def _capture( group_properties=flag_options["group_properties"], disable_geoip=disable_geoip, flag_keys_to_evaluate=flag_options["flag_keys_filter"], + person_property_keys_known_absent=flag_options.get( + "person_property_keys_known_absent" + ), + group_property_keys_known_absent=flag_options.get( + "group_property_keys_known_absent" + ), ) except Exception as e: self.log.exception( @@ -2574,7 +2651,7 @@ def _parse_send_feature_flags(self, send_feature_flags) -> SendFeatureFlagsOptio TypeError: If send_feature_flags is not bool or dict """ if isinstance(send_feature_flags, dict): - return { + options: SendFeatureFlagsOptions = { "should_send": True, "only_evaluate_locally": send_feature_flags.get( "only_evaluate_locally" @@ -2583,6 +2660,19 @@ def _parse_send_feature_flags(self, send_feature_flags) -> SendFeatureFlagsOptio "group_properties": send_feature_flags.get("group_properties"), "flag_keys_filter": send_feature_flags.get("flag_keys_filter"), } + # Validate here so invalid keys fail the whole capture call instead of + # being swallowed as a flag enrichment failure. + person_keys_known_absent, group_keys_known_absent = ( + _validate_known_absent_keys( + send_feature_flags.get("person_property_keys_known_absent"), + send_feature_flags.get("group_property_keys_known_absent"), + ) + ) + if person_keys_known_absent: + options["person_property_keys_known_absent"] = person_keys_known_absent + if group_keys_known_absent: + options["group_property_keys_known_absent"] = group_keys_known_absent + return options elif isinstance(send_feature_flags, bool): return { "should_send": send_feature_flags, @@ -4699,6 +4789,8 @@ def feature_enabled( send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[bool]: """ Check if a feature flag is enabled for a user. @@ -4717,6 +4809,10 @@ def feature_enabled( send_feature_flag_events: Whether to send feature flag events. disable_geoip: Whether to disable GeoIP for this request. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Examples: ```python @@ -4750,6 +4846,8 @@ def feature_enabled( send_feature_flag_events=send_feature_flag_events, disable_geoip=disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) response = flag_result.get_value() if flag_result else None @@ -4783,7 +4881,12 @@ def _get_feature_flag_result( send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[FeatureFlagResult]: + person_keys_known_absent, group_keys_known_absent = _validate_known_absent_keys( + person_property_keys_known_absent, group_property_keys_known_absent + ) if self.disabled: return None @@ -4813,15 +4916,21 @@ def _get_feature_flag_result( if device_id is None: device_id = get_context_device_id() - local_person_properties = self._person_properties_for_local_evaluation( - distinct_id, person_properties + local_person_properties, local_group_properties = ( + self._properties_for_local_evaluation( + distinct_id, + person_properties, + group_properties, + person_keys_known_absent, + group_keys_known_absent, + ) ) flag_value, snapshot = self._locally_evaluate_flag( key, distinct_id, groups, local_person_properties, - group_properties, + local_group_properties, device_id, ) local_definition_version = snapshot["flag_definition_version"] @@ -4880,6 +4989,8 @@ def _get_feature_flag_result( group_properties, disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_keys_known_absent, + group_property_keys_known_absent=group_keys_known_absent, ) errors = [] if errors_while_computing: @@ -5002,6 +5113,8 @@ def get_feature_flag_result( send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[FeatureFlagResult]: """ Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely @@ -5030,6 +5143,10 @@ def get_feature_flag_result( send_feature_flag_events: Whether to send feature flag events. disable_geoip: Whether to disable GeoIP for this request. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Returns: Optional[FeatureFlagResult]: The evaluated result, including a healthy @@ -5046,6 +5163,8 @@ def get_feature_flag_result( send_feature_flag_events=send_feature_flag_events, disable_geoip=disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) def get_feature_flag( @@ -5060,6 +5179,8 @@ def get_feature_flag( send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[FlagValue]: """ Get multivariate feature flag value for a user. @@ -5078,6 +5199,10 @@ def get_feature_flag( send_feature_flag_events: Whether to send feature flag events. disable_geoip: Whether to disable GeoIP for this request. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Examples: ```python @@ -5111,6 +5236,8 @@ def get_feature_flag( send_feature_flag_events=send_feature_flag_events, disable_geoip=disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) return feature_flag_result.get_value() if feature_flag_result else None @@ -5166,6 +5293,8 @@ def get_feature_flag_payload( send_feature_flag_events: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[object]: """ Get the payload for a feature flag. @@ -5185,6 +5314,10 @@ def get_feature_flag_payload( send_feature_flag_events: Deprecated. Use get_feature_flag() instead if you need events. disable_geoip: Whether to disable GeoIP for this request. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Returns: The payload associated with the matched feature flag value, or None. @@ -5231,6 +5364,8 @@ def get_feature_flag_payload( send_feature_flag_events=send_feature_flag_events, disable_geoip=disable_geoip, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) return feature_flag_result.payload if feature_flag_result else None @@ -5243,6 +5378,8 @@ def _get_feature_flag_details_from_server( group_properties: dict[str, dict[str, Any]], disable_geoip: Optional[bool], device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[list[str]] = None, + group_property_keys_known_absent: Optional[dict[str, list[str]]] = None, ) -> tuple[Optional[FeatureFlag], Optional[str], Optional[int], bool, bool]: """ Calls /flags and returns the flag details, request id, evaluated at timestamp, @@ -5258,6 +5395,8 @@ def _get_feature_flag_details_from_server( disable_geoip, flag_keys_to_evaluate=[key], device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) request_id = resp_data.get("requestId") evaluated_at = resp_data.get("evaluatedAt") @@ -5458,6 +5597,8 @@ def get_all_flags( disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> Optional[dict[str, Union[bool, str]]]: """ Get all feature flags for a user. @@ -5472,6 +5613,10 @@ def get_all_flags( flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Examples: ```python @@ -5490,6 +5635,8 @@ def get_all_flags( disable_geoip=disable_geoip, flag_keys_to_evaluate=flag_keys_to_evaluate, device_id=device_id, + person_property_keys_known_absent=person_property_keys_known_absent, + group_property_keys_known_absent=group_property_keys_known_absent, ) return response["featureFlags"] @@ -5505,6 +5652,8 @@ def get_all_flags_and_payloads( disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> FlagsAndPayloads: """ Get all feature flags and their payloads for a user. @@ -5519,6 +5668,10 @@ def get_all_flags_and_payloads( flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance. device_id: The device ID for this request. + person_property_keys_known_absent: Person property keys known to be absent. + See ``evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. See ``evaluate_flags``. Examples: ```python @@ -5528,6 +5681,9 @@ def get_all_flags_and_payloads( Category: Feature flags """ + person_keys_known_absent, group_keys_known_absent = _validate_known_absent_keys( + person_property_keys_known_absent, group_property_keys_known_absent + ) if self.disabled: return {"featureFlags": None, "featureFlagPayloads": None} @@ -5543,14 +5699,20 @@ def get_all_flags_and_payloads( groups = groups or {} - local_person_properties = self._person_properties_for_local_evaluation( - distinct_id, person_properties + local_person_properties, local_group_properties = ( + self._properties_for_local_evaluation( + distinct_id, + person_properties, + group_properties, + person_keys_known_absent, + group_keys_known_absent, + ) ) response, fallback_to_flags, _ = self._get_all_flags_and_payloads_locally( distinct_id, groups=groups, person_properties=local_person_properties, - group_properties=group_properties, + group_properties=local_group_properties, flag_keys_to_evaluate=flag_keys_to_evaluate, device_id=device_id, ) @@ -5565,6 +5727,8 @@ def get_all_flags_and_payloads( disable_geoip=disable_geoip, flag_keys_to_evaluate=flag_keys_to_evaluate, device_id=device_id, + person_property_keys_known_absent=person_keys_known_absent, + group_property_keys_known_absent=group_keys_known_absent, ) remote_response = to_flags_and_payloads(decide_response) # A key the server marked failed keeps its locally computed value @@ -5616,6 +5780,8 @@ def evaluate_flags( disable_geoip: Optional[bool] = None, flag_keys: Optional[List[str]] = None, device_id: Optional[str] = None, + person_property_keys_known_absent: Optional[Iterable[str]] = None, + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None, ) -> FeatureFlagEvaluations: """Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / @@ -5649,6 +5815,17 @@ def evaluate_flags( device_id: Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes. + person_property_keys_known_absent: Person property keys the caller knows are + absent for this person. Local evaluation treats a listed key as absent, + even when ``person_properties`` supplies a value for it: ``is_not_set`` + and the negated operators match, and every other operator does not, with + no remote fallback. A listed ``$feature_enrollment/`` means not + enrolled. Keys starting with ``__posthog_person_metadata__`` are ignored. + Sent to ``/flags`` on remote evaluation. At most 1000 keys, counting + duplicates; a longer list raises ``ValueError`` and nothing is evaluated. + group_property_keys_known_absent: Group property keys known to be absent, + keyed by group type. A key applies only to its own group type. Same + rules and per-group-type limit as ``person_property_keys_known_absent``. Returns: A :class:`FeatureFlagEvaluations` snapshot. @@ -5668,6 +5845,9 @@ def evaluate_flags( Feature flags """ host = self._get_feature_flag_evaluations_host() + person_keys_known_absent, group_keys_known_absent = _validate_known_absent_keys( + person_property_keys_known_absent, group_property_keys_known_absent + ) if distinct_id is None: distinct_id = get_context_distinct_id() @@ -5711,15 +5891,21 @@ def evaluate_flags( locally_evaluated_keys: set[str] = set() unresolved: Dict[str, UnresolvedFlagReason] = {} # Try local evaluation first when the poller has loaded definitions. - local_person_properties = self._person_properties_for_local_evaluation( - distinct_id, person_properties + local_person_properties, local_group_properties = ( + self._properties_for_local_evaluation( + distinct_id, + person_properties, + group_properties, + person_keys_known_absent, + group_keys_known_absent, + ) ) local_result, fallback_to_server, definition_snapshot = ( self._get_all_flags_and_payloads_locally( distinct_id, groups=dict(groups), person_properties=local_person_properties, - group_properties=group_properties, + group_properties=local_group_properties, flag_keys_to_evaluate=flag_keys, device_id=device_id, unresolved=unresolved, @@ -5767,6 +5953,8 @@ def evaluate_flags( disable_geoip=disable_geoip, flag_keys_to_evaluate=flag_keys, device_id=device_id, + person_property_keys_known_absent=person_keys_known_absent, + group_property_keys_known_absent=group_keys_known_absent, ) request_id = response.get("requestId") raw_evaluated_at = response.get("evaluatedAt") @@ -6077,10 +6265,22 @@ def get_feature_flag_keys_by_evaluation_runtime( ).matches(wanted) ] - def _person_properties_for_local_evaluation(self, distinct_id, person_properties): + def _properties_for_local_evaluation( + self, + distinct_id, + person_properties, + group_properties, + person_property_keys_known_absent=None, + group_property_keys_known_absent=None, + ): local_person_properties = dict(person_properties or {}) local_person_properties.setdefault("distinct_id", distinct_id) - return local_person_properties + return _mark_known_absent_properties( + local_person_properties, + group_properties or {}, + person_property_keys_known_absent, + group_property_keys_known_absent, + ) def _add_local_person_and_group_properties( self, groups, person_properties, group_properties diff --git a/posthog/feature_flags.py b/posthog/feature_flags.py index 6a2e98693..aed937dc2 100644 --- a/posthog/feature_flags.py +++ b/posthog/feature_flags.py @@ -1,16 +1,18 @@ import calendar import datetime import hashlib +import itertools import json import logging import math import numbers import re import warnings +from collections.abc import Iterable, Mapping from decimal import Decimal from enum import Enum from functools import lru_cache as _lru_cache -from typing import NamedTuple, NoReturn, Optional +from typing import Any, NamedTuple, NoReturn, Optional from posthog import utils as utils from posthog.types import FlagValue, UnresolvedFlagReason @@ -29,6 +31,108 @@ NONE_VALUES_ALLOWED_OPERATORS = ["is_not"] +# The flags service rejects longer known-absent key lists with HTTP 400. +_MAX_KNOWN_ABSENT_KEYS = 1000 +_PERSON_METADATA_KEY_PREFIX = "__posthog_person_metadata__" + +# For a known-absent key these operators match, and every other operator does not. +_KNOWN_ABSENT_MATCHING_OPERATORS = frozenset( + ( + "is_not_set", + "is_not", + "not_icontains", + "not_starts_with", + "not_ends_with", + "not_regex", + ) +) + + +class _KnownAbsent: + """Value of a property the caller listed as known absent, in the property maps + used for local evaluation. It replaces any value supplied for the same key.""" + + __slots__ = () + + def __repr__(self) -> str: + return "" + + +_KNOWN_ABSENT = _KnownAbsent() + + +def _known_absent_key_list(keys, field: str) -> Optional[list[str]]: + if keys is None: + return None + if isinstance(keys, (str, bytes)) or not isinstance(keys, Iterable): + raise TypeError(f"{field} must be a collection of strings") + # Read one key past the limit so an unbounded iterable can't exhaust memory. + key_list = list(itertools.islice(keys, _MAX_KNOWN_ABSENT_KEYS + 1)) + if len(key_list) > _MAX_KNOWN_ABSENT_KEYS: + raise ValueError( + f"{field} allows at most {_MAX_KNOWN_ABSENT_KEYS} keys, got more" + ) + if not all(isinstance(key, str) for key in key_list): + raise TypeError(f"{field} must contain only strings") + return key_list or None + + +def _validate_known_absent_keys( + person_property_keys_known_absent: Optional[Iterable[str]], + group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]], +) -> tuple[Optional[list[str]], Optional[dict[str, list[str]]]]: + """Check the caller's known-absent keys against the flags service limits. + + Returns them as lists, with ``None`` for anything empty. Raises ``TypeError`` + for a wrong type and ``ValueError`` for a list over the limit, so nothing is + evaluated or sent. Lists are never truncated. + """ + person_keys = _known_absent_key_list( + person_property_keys_known_absent, "person_property_keys_known_absent" + ) + if group_property_keys_known_absent is None: + return person_keys, None + if not isinstance(group_property_keys_known_absent, Mapping): + raise TypeError( + "group_property_keys_known_absent must map group types to collections of strings" + ) + group_keys: dict[str, list[str]] = {} + for group_type, keys in group_property_keys_known_absent.items(): + if not isinstance(group_type, str) or keys is None: + raise TypeError( + "group_property_keys_known_absent must map group types to collections of strings" + ) + key_list = _known_absent_key_list( + keys, f"group_property_keys_known_absent[{group_type!r}]" + ) + if key_list: + group_keys[group_type] = key_list + return person_keys, group_keys or None + + +def _mark_known_absent_properties( + person_properties: dict[str, Any], + group_properties: dict[str, dict[str, Any]], + person_property_keys_known_absent: Optional[list[str]], + group_property_keys_known_absent: Optional[dict[str, list[str]]], +) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]: + """Return copies of the local evaluation property maps with each listed key + set to the known-absent value, replacing supplied and SDK-added values.""" + if person_property_keys_known_absent: + person_properties = dict(person_properties) + for key in person_property_keys_known_absent: + # Known absence never hides a persons-table field. + if not key.startswith(_PERSON_METADATA_KEY_PREFIX): + person_properties[key] = _KNOWN_ABSENT + if group_property_keys_known_absent: + group_properties = dict(group_properties) + for group_type, keys in group_property_keys_known_absent.items(): + group_properties[group_type] = { + **(group_properties.get(group_type) or {}), + **{key: _KNOWN_ABSENT for key in keys}, + } + return person_properties, group_properties + def _warn_malformed_flag_dependency_once(flag_key, reason): """Emit a throttled warning for a malformed flag dependency condition. @@ -556,7 +660,9 @@ def match_feature_flag_properties( flag_filters = flag.get("filters") or {} if flag_filters.get("feature_enrollment") is True: - return _match_feature_enrollment(flag, flag_filters, properties) + enrolled = _match_feature_enrollment(flag, flag_filters, properties) + if enrolled is not None: + return enrolled # Holdouts are evaluated before release conditions, so a held-out value is excluded # from the flag's targeting entirely rather than being bucketed into a variant. @@ -779,13 +885,17 @@ def _get_valid_variant_keys(flag_filters): return [variant["key"] for variant in flag_variants] -def _match_feature_enrollment(flag, flag_filters, properties) -> bool: +def _match_feature_enrollment(flag, flag_filters, properties) -> Optional[bool]: + """Return the enrollment value, or None when the person is known not to be + enrolled and evaluation continues to holdouts and release conditions.""" enrollment_key = f"$feature_enrollment/{flag.get('key')}" if flag_filters.get("aggregation_group_type_index") is not None: raise InconclusiveMatchError( "Group flag has feature enrollment, which reads person properties", reason=UnresolvedFlagReason.UNSUPPORTED_DEFINITION, ) + if properties.get(enrollment_key) is _KNOWN_ABSENT: + return None if enrollment_key not in properties: raise InconclusiveMatchError( f"Flag has feature enrollment and '{enrollment_key}' was not passed", @@ -1465,6 +1575,11 @@ def _match_property_value( reason=UnresolvedFlagReason.UNSUPPORTED_DEFINITION, ) + if key in property_values and property_values[key] is _KNOWN_ABSENT: + # An unusable filter stays inconclusive even for a known-absent key. + _assert_filter_supported(property) + return operator in _KNOWN_ABSENT_MATCHING_OPERATORS + if key not in property_values: raise InconclusiveMatchError( "can't match properties without a given property value", diff --git a/posthog/test/test_evaluate_flags.py b/posthog/test/test_evaluate_flags.py index 89a8c71f0..b10c29722 100644 --- a/posthog/test/test_evaluate_flags.py +++ b/posthog/test/test_evaluate_flags.py @@ -68,7 +68,7 @@ def test_empty_flag_keys_returns_empty_without_evaluation_work(self): self.client, "_add_local_person_and_group_properties" ) as add_local_properties, mock.patch.object( - self.client, "_person_properties_for_local_evaluation" + self.client, "_properties_for_local_evaluation" ) as local_person_properties, mock.patch.object( self.client, "_get_all_flags_and_payloads_locally" diff --git a/posthog/test/test_feature_flags_known_absent.py b/posthog/test/test_feature_flags_known_absent.py new file mode 100644 index 000000000..04c27df4d --- /dev/null +++ b/posthog/test/test_feature_flags_known_absent.py @@ -0,0 +1,523 @@ +"""Known-absent property keys in local evaluation and the /flags request body.""" + +import itertools +import unittest +from unittest import mock + +import pytest +from parameterized import parameterized + +from posthog import AsyncPosthog +from posthog.client import Client +from posthog.feature_flags import _KNOWN_ABSENT, InconclusiveMatchError, match_cohort +from posthog.test.test_utils import FAKE_TEST_API_KEY +from posthog.types import UnresolvedFlagReason + +pytestmark = [ + pytest.mark.filterwarnings( + r"ignore:`(feature_enabled|get_feature_flag|get_feature_flag_payload)` is deprecated:DeprecationWarning" + ), + pytest.mark.filterwarnings( + r"ignore:`send_feature_flags` is deprecated:DeprecationWarning" + ), +] + +REMOTE_VALUE = "remote-value" + + +def _flag(key, properties, **filters): + return { + "id": 1, + "key": key, + "active": True, + "filters": { + "groups": [{"properties": properties, "rollout_percentage": 100}], + **filters, + }, + } + + +def _person_filter(operator, value=None, key="plan"): + prop = {"key": key, "operator": operator, "type": "person"} + if value is not None: + prop["value"] = value + return prop + + +class TestKnownAbsentLocalEvaluation(unittest.TestCase): + def setUp(self): + self.client = Client(FAKE_TEST_API_KEY, secret_key="test") + self.client.capture = mock.Mock() + self.client.group_type_mapping = {"0": "organization", "1": "project"} + flags_patch = mock.patch("posthog.client.flags") + self.flags = flags_patch.start() + self.addCleanup(flags_patch.stop) + self.flags.return_value = { + "featureFlags": {"flag": REMOTE_VALUE, "beta-feature": REMOTE_VALUE} + } + + def evaluate(self, flag, **kwargs): + self.client.feature_flags = [flag] + return self.client.get_feature_flag(flag["key"], "user-1", **kwargs) + + def assert_local(self, flag, expected, **kwargs): + self.assertEqual(self.evaluate(flag, **kwargs), expected) + self.flags.assert_not_called() + + def assert_remote(self, flag, **kwargs): + self.assertEqual(self.evaluate(flag, **kwargs), REMOTE_VALUE) + self.assertEqual(self.flags.call_count, 1) + + @parameterized.expand( + [ + ("is_not_set", None, True), + ("is_set", None, False), + ("exact", "pro", False), + ("exact", ["pro", "free"], False), + ("is_not", "pro", True), + ("icontains", "pro", False), + ("not_icontains", "pro", True), + ("starts_with", "pro", False), + ("not_starts_with", "pro", True), + ("ends_with", "pro", False), + ("not_ends_with", "pro", True), + ("regex", "^pro", False), + ("not_regex", "^pro", True), + ("gt", "10", False), + ("gte", "10", False), + ("lt", "10", False), + ("lte", "10", False), + ("is_date_before", "2025-01-01T10:00:00Z", False), + ("is_date_after", "2025-01-01T10:00:00Z", False), + ("semver_eq", "1.2.3", False), + ("semver_neq", "1.2.3", False), + ("semver_gt", "1.2.3", False), + ("semver_tilde", "1.2.3", False), + ] + ) + def test_listed_key_resolves_operator_locally(self, operator, value, expected): + flag = _flag("flag", [_person_filter(operator, value)]) + self.assert_local(flag, expected, person_property_keys_known_absent=["plan"]) + + def test_listed_key_overrides_a_supplied_value(self): + flag = _flag("flag", [_person_filter("is_not_set")]) + self.assert_local( + flag, + True, + person_properties={"plan": "pro"}, + person_property_keys_known_absent=["plan"], + ) + + def test_listed_key_overrides_the_sdk_added_distinct_id(self): + flag = _flag("flag", [_person_filter("is_not_set", key="distinct_id")]) + self.assert_local(flag, True, person_property_keys_known_absent=["distinct_id"]) + + def test_omitted_key_that_is_not_listed_stays_inconclusive(self): + flag = _flag("flag", [_person_filter("is_not_set")]) + self.assert_remote(flag, person_property_keys_known_absent=["region"]) + body = self.flags.call_args.kwargs + self.assertEqual(body["person_property_keys_known_absent"], ["region"]) + + def test_person_metadata_key_is_ignored(self): + flag = _flag( + "flag", + [_person_filter("is_set", key="__posthog_person_metadata__created_at")], + ) + self.assert_local( + flag, + True, + person_properties={"__posthog_person_metadata__created_at": "2024"}, + person_property_keys_known_absent=["__posthog_person_metadata__created_at"], + ) + + @parameterized.expand( + [ + ("unknown operator", "icontains_multi", ["pro"]), + ("unsupported negated operator", "not_between", [1, 2]), + ("malformed numeric value", "gt", "not-a-number"), + ("malformed date value", "is_date_before", "not-a-date"), + ] + ) + def test_unsupported_filter_on_listed_key_still_falls_back( + self, _name, operator, value + ): + flag = _flag("flag", [_person_filter(operator, value)]) + self.assert_remote(flag, person_property_keys_known_absent=["plan"]) + + def test_group_key_applies_only_to_its_group_type(self): + flag = _flag( + "flag", + [{"key": "tier", "operator": "is_not_set", "type": "group"}], + aggregation_group_type_index=0, + ) + groups = {"organization": "org-1", "project": "proj-1"} + self.assert_remote( + flag, + groups=groups, + group_property_keys_known_absent={"project": ["tier"]}, + ) + self.assertEqual( + self.flags.call_args.kwargs["group_property_keys_known_absent"], + {"project": ["tier"]}, + ) + + self.flags.reset_mock() + self.assert_local( + flag, + True, + groups=groups, + group_properties={"organization": {"tier": "gold"}}, + group_property_keys_known_absent={"organization": ["tier"]}, + ) + + def test_group_key_overrides_the_sdk_added_group_key(self): + flag = _flag( + "flag", + [{"key": "$group_key", "operator": "is_set", "type": "group"}], + aggregation_group_type_index=0, + ) + self.assert_local( + flag, + False, + groups={"organization": "org-1"}, + group_property_keys_known_absent={"organization": ["$group_key"]}, + ) + + def test_person_keys_do_not_apply_to_group_properties(self): + flag = _flag( + "flag", + [{"key": "tier", "operator": "is_not_set", "type": "group"}], + aggregation_group_type_index=0, + ) + self.assert_remote( + flag, + groups={"organization": "org-1"}, + person_property_keys_known_absent=["tier"], + ) + + @parameterized.expand([(False, True), (True, False)]) + def test_cohort_leaf_uses_known_absence_before_negation(self, negation, expected): + self.client.cohorts = { + "5": { + "type": "AND", + "values": [ + { + "key": "plan", + "operator": "is_not_set", + "type": "person", + "negation": negation, + } + ], + } + } + flag = _flag("flag", [{"key": "id", "value": 5, "type": "cohort"}]) + self.assert_local(flag, expected, person_property_keys_known_absent=["plan"]) + + @parameterized.expand([(False,), (True,)]) + def test_cohort_leaf_unsupported_operator_falls_back_before_known_absence( + self, negation + ): + cohort = { + "type": "AND", + "values": [ + { + "key": "plan", + "operator": "not_between", + "value": [1, 2], + "type": "person", + "negation": negation, + } + ], + } + cohort_filter = {"key": "id", "value": 5, "type": "cohort"} + with self.assertRaises(InconclusiveMatchError) as ctx: + match_cohort(cohort_filter, {"plan": _KNOWN_ABSENT}, {"5": cohort}) + self.assertEqual( + ctx.exception.reason, UnresolvedFlagReason.UNSUPPORTED_DEFINITION + ) + + self.client.cohorts = {"5": cohort} + flag = _flag("flag", [cohort_filter]) + self.assert_remote(flag, person_property_keys_known_absent=["plan"]) + + def test_flag_dependency_uses_the_same_listing(self): + dependency = _flag("dependency", [_person_filter("is_not_set")]) + dependency["id"] = 2 + dependent = _flag( + "flag", + [ + { + "key": "dependency", + "operator": "flag_evaluates_to", + "value": True, + "type": "flag", + "dependency_chain": ["dependency"], + } + ], + ) + self.client.feature_flags = [dependency, dependent] + value = self.client.get_feature_flag( + "flag", "user-1", person_property_keys_known_absent=["plan"] + ) + self.assertIs(value, True) + self.flags.assert_not_called() + + def test_listed_enrollment_key_continues_to_release_conditions(self): + flag = _flag("beta-feature", [], feature_enrollment=True) + self.assert_local( + flag, + True, + person_properties={"$feature_enrollment/beta-feature": True}, + person_property_keys_known_absent=["$feature_enrollment/beta-feature"], + ) + + def test_listed_enrollment_key_continues_to_holdouts(self): + flag = _flag( + "beta-feature", + [], + feature_enrollment=True, + holdout={"id": 1, "exclusion_percentage": 100}, + ) + self.assert_local( + flag, + "holdout-1", + person_property_keys_known_absent=["$feature_enrollment/beta-feature"], + ) + + def test_listed_enrollment_key_still_reports_unsupported_group_enrollment(self): + flag = _flag( + "beta-feature", + [], + feature_enrollment=True, + aggregation_group_type_index=0, + ) + self.assert_remote( + flag, + groups={"organization": "org-1"}, + person_property_keys_known_absent=["$feature_enrollment/beta-feature"], + ) + + def test_evaluate_flags_and_all_flags_honor_listing(self): + self.client.feature_flags = [_flag("flag", [_person_filter("is_not_set")])] + snapshot = self.client.evaluate_flags( + "user-1", + person_properties={"plan": "pro"}, + person_property_keys_known_absent=["plan"], + only_evaluate_locally=True, + ) + self.assertIs(snapshot.is_enabled("flag"), True) + self.assertEqual( + self.client.get_all_flags( + "user-1", person_property_keys_known_absent=["plan"] + ), + {"flag": True}, + ) + self.flags.assert_not_called() + + +class TestKnownAbsentRemoteBody(unittest.TestCase): + def setUp(self): + self.client = Client(FAKE_TEST_API_KEY) + self.client.capture = mock.Mock() + flags_patch = mock.patch("posthog.client.flags") + self.flags = flags_patch.start() + self.addCleanup(flags_patch.stop) + self.flags.return_value = {"featureFlags": {"flag": True}} + + def test_fallback_sends_listed_keys(self): + self.client.get_feature_flag( + "flag", + "user-1", + groups={"organization": "org-1"}, + person_property_keys_known_absent=["plan"], + group_property_keys_known_absent={"organization": ["tier"]}, + ) + body = self.flags.call_args.kwargs + self.assertEqual(body["person_property_keys_known_absent"], ["plan"]) + self.assertEqual( + body["group_property_keys_known_absent"], {"organization": ["tier"]} + ) + + @parameterized.expand( + [ + ("not provided", {}), + ( + "empty", + { + "person_property_keys_known_absent": [], + "group_property_keys_known_absent": {"organization": []}, + }, + ), + ] + ) + def test_omits_fields_without_listed_keys(self, _name, kwargs): + self.client.get_feature_flag("flag", "user-1", **kwargs) + body = self.flags.call_args.kwargs + self.assertNotIn("person_property_keys_known_absent", body) + self.assertNotIn("group_property_keys_known_absent", body) + + def test_every_remote_entry_point_sends_listed_keys(self): + kwargs = {"person_property_keys_known_absent": ["plan"]} + calls = [ + lambda: self.client.evaluate_flags("user-1", **kwargs), + lambda: self.client.get_all_flags_and_payloads("user-1", **kwargs), + lambda: self.client.get_feature_flag_result("flag", "user-1", **kwargs), + lambda: self.client.get_feature_flag_payload("flag", "user-1", **kwargs), + lambda: self.client.feature_enabled("flag", "user-1", **kwargs), + lambda: self.client.get_feature_variants("user-1", **kwargs), + lambda: self.client.get_flags_decision("user-1", **kwargs), + ] + for call in calls: + self.flags.reset_mock() + call() + self.assertEqual( + self.flags.call_args.kwargs["person_property_keys_known_absent"], + ["plan"], + ) + + def test_send_feature_flags_options_send_listed_keys(self): + client = Client(FAKE_TEST_API_KEY, send=False) + client.capture( + "event", + distinct_id="user-1", + send_feature_flags={ + "only_evaluate_locally": False, + "person_property_keys_known_absent": ["plan"], + }, + ) + self.assertEqual( + self.flags.call_args.kwargs["person_property_keys_known_absent"], ["plan"] + ) + + @parameterized.expand( + [ + ("person", {"person_property_keys_known_absent": ["plan"] * 1001}), + ( + "group", + {"group_property_keys_known_absent": {"organization": ["t"] * 1001}}, + ), + ] + ) + def test_over_limit_raises_without_a_request(self, _name, kwargs): + for call in ( + lambda: self.client.get_feature_flag("flag", "user-1", **kwargs), + lambda: self.client.evaluate_flags("user-1", **kwargs), + lambda: self.client.get_all_flags("user-1", **kwargs), + lambda: self.client.get_flags_decision("user-1", **kwargs), + ): + with self.assertRaisesRegex(ValueError, "at most 1000 keys"): + call() + self.flags.assert_not_called() + + def test_send_feature_flags_over_limit_raises_without_a_request(self): + client = Client(FAKE_TEST_API_KEY, send=False, debug=True) + with self.assertRaisesRegex(ValueError, "at most 1000 keys"): + client.capture( + "event", + distinct_id="user-1", + send_feature_flags={ + "only_evaluate_locally": False, + "person_property_keys_known_absent": ["plan"] * 1001, + }, + ) + self.flags.assert_not_called() + + def test_send_feature_flags_over_limit_drops_event_with_default_settings(self): + client = Client(FAKE_TEST_API_KEY) + with mock.patch.object(client, "_enqueue") as enqueue: + result = client.capture( + "event", + distinct_id="user-1", + send_feature_flags={ + "only_evaluate_locally": False, + "person_property_keys_known_absent": ["plan"] * 1001, + }, + ) + self.assertIsNone(result) + enqueue.assert_not_called() + self.flags.assert_not_called() + + def test_unbounded_iterable_raises_without_a_request(self): + with self.assertRaisesRegex(ValueError, "at most 1000 keys"): + self.client.get_flags_decision( + "user-1", person_property_keys_known_absent=itertools.repeat("plan") + ) + self.flags.assert_not_called() + + def test_get_flags_decision_sends_iterator_inputs(self): + self.client.get_flags_decision( + "user-1", + groups={"organization": "org-1"}, + person_property_keys_known_absent=iter(["plan"]), + group_property_keys_known_absent={"organization": iter(["tier"])}, + ) + body = self.flags.call_args.kwargs + self.assertEqual(body["person_property_keys_known_absent"], ["plan"]) + self.assertEqual( + body["group_property_keys_known_absent"], {"organization": ["tier"]} + ) + + def test_limit_counts_duplicates_and_is_per_group_type(self): + self.client.get_feature_flag( + "flag", + "user-1", + person_property_keys_known_absent=["plan"] * 1000, + group_property_keys_known_absent={ + "organization": ["t"] * 1000, + "project": ["t"] * 1000, + }, + ) + body = self.flags.call_args.kwargs + self.assertEqual(len(body["person_property_keys_known_absent"]), 1000) + self.assertEqual(len(body["group_property_keys_known_absent"]["project"]), 1000) + + @parameterized.expand( + [ + ("string", {"person_property_keys_known_absent": "plan"}), + ("non-string key", {"person_property_keys_known_absent": [1]}), + ("group list", {"group_property_keys_known_absent": ["tier"]}), + ("non-string group type", {"group_property_keys_known_absent": {1: ["t"]}}), + ("None group keys", {"group_property_keys_known_absent": {"org": None}}), + ] + ) + def test_wrong_type_raises_without_a_request(self, _name, kwargs): + with self.assertRaises(TypeError): + self.client.get_feature_flag("flag", "user-1", **kwargs) + self.flags.assert_not_called() + + +@pytest.mark.asyncio +async def test_async_evaluate_flags_sends_listed_keys(): + client = AsyncPosthog(FAKE_TEST_API_KEY, send=False) + with mock.patch( + "posthog.async_client._async_flags", + new=mock.AsyncMock(return_value={"flags": {}}), + ) as async_flags: + await client.evaluate_flags( + "user-1", + person_property_keys_known_absent=["plan"], + group_property_keys_known_absent={"organization": ["tier"], "x": []}, + ) + await client.evaluate_flags("user-1") + first, second = async_flags.call_args_list + assert first.kwargs["person_property_keys_known_absent"] == ["plan"] + assert first.kwargs["group_property_keys_known_absent"] == { + "organization": ["tier"] + } + assert "person_property_keys_known_absent" not in second.kwargs + assert "group_property_keys_known_absent" not in second.kwargs + await client.shutdown() + + +@pytest.mark.asyncio +async def test_async_evaluate_flags_rejects_over_limit_lists(): + client = AsyncPosthog(FAKE_TEST_API_KEY, send=False) + with mock.patch( + "posthog.async_client._async_flags", new=mock.AsyncMock() + ) as async_flags: + with pytest.raises(ValueError, match="at most 1000 keys"): + await client.evaluate_flags( + "user-1", person_property_keys_known_absent=["plan"] * 1001 + ) + async_flags.assert_not_called() + await client.shutdown() diff --git a/posthog/types.py b/posthog/types.py index 9335274e5..f474c7f88 100644 --- a/posthog/types.py +++ b/posthog/types.py @@ -68,6 +68,10 @@ class SendFeatureFlagsOptions(TypedDict, total=False): group_properties: Group properties to use for feature flag evaluation specific to this event. Format: { group_type_name: { group_properties } } flag_keys_filter: Optional list of flag keys to evaluate and attach. + person_property_keys_known_absent: Person property keys known to be + absent. See ``Client.evaluate_flags``. + group_property_keys_known_absent: Group property keys known to be + absent, keyed by group type. See ``Client.evaluate_flags``. """ should_send: bool @@ -75,6 +79,8 @@ class SendFeatureFlagsOptions(TypedDict, total=False): person_properties: Optional[dict[str, Any]] group_properties: Optional[dict[str, dict[str, Any]]] flag_keys_filter: Optional[list[str]] + person_property_keys_known_absent: Optional[list[str]] + group_property_keys_known_absent: Optional[dict[str, list[str]]] class FeatureFlagEvaluationRuntime(str, Enum): diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt index c9e0b430e..bc4fad813 100644 --- a/references/public_api_snapshot.txt +++ b/references/public_api_snapshot.txt @@ -1247,8 +1247,10 @@ attribute posthog.types.FlagsResponse.requestId: str attribute posthog.types.LegacyFlagMetadata.payload: Any attribute posthog.types.SendFeatureFlagsOptions.flag_keys_filter: Optional[list[str]] attribute posthog.types.SendFeatureFlagsOptions.group_properties: Optional[dict[str, dict[str, Any]]] +attribute posthog.types.SendFeatureFlagsOptions.group_property_keys_known_absent: Optional[dict[str, list[str]]] attribute posthog.types.SendFeatureFlagsOptions.only_evaluate_locally: Optional[bool] attribute posthog.types.SendFeatureFlagsOptions.person_properties: Optional[dict[str, Any]] +attribute posthog.types.SendFeatureFlagsOptions.person_property_keys_known_absent: Optional[list[str]] attribute posthog.types.SendFeatureFlagsOptions.should_send: bool attribute posthog.types.UnresolvedFlagReason.EXPERIENCE_CONTINUITY = 'experience_continuity' attribute posthog.types.UnresolvedFlagReason.MISSING_CONTEXT = 'missing_context' @@ -1552,7 +1554,7 @@ function posthog.contexts.set_context_device_id(device_id: str) -> None function posthog.contexts.set_context_option(key: str, value: Any) -> None function posthog.contexts.set_context_session(session_id: str) -> None function posthog.contexts.tag(key: str, value: Any) -> None -function posthog.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations +function posthog.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> FeatureFlagEvaluations function posthog.exception_utils.attach_code_variables_to_frames(all_exceptions, exc_info, mask_patterns, ignore_patterns, mask_url_credentials=True, detect_secrets=DEFAULT_CODE_VARIABLES_DETECT_SECRETS) function posthog.exception_utils.construct_artificial_traceback(e) function posthog.exception_utils.event_hint_with_exc_info(exc_info=None) @@ -1585,7 +1587,7 @@ function posthog.exception_utils.to_string(value) function posthog.exception_utils.to_timestamp(value) function posthog.exception_utils.try_attach_code_variables_to_frames(all_exceptions, exc_info, mask_patterns, ignore_patterns, mask_url_credentials=True, detect_secrets=DEFAULT_CODE_VARIABLES_DETECT_SECRETS) function posthog.exception_utils.walk_exception_chain(exc_info) -function posthog.feature_enabled(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[bool] +function posthog.feature_enabled(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[bool] function posthog.feature_flag_definitions() function posthog.feature_flags.evaluate_flag_dependency(property, flags_by_key, evaluation_cache, distinct_id, properties, cohort_properties, device_id=None, property_matching_version: int = 1) function posthog.feature_flags.get_matching_variant(flag, bucketing_value) @@ -1602,14 +1604,14 @@ function posthog.feature_flags.resolve_bucketing_value(flag, distinct_id, device function posthog.feature_flags.variant_lookup_table(feature_flag) function posthog.flush(timeout_seconds: Optional[float] = 10) -> None function posthog.get_active_span() -> Optional[Span] -function posthog.get_all_flags(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None) -> Optional[dict[str, FlagValue]] -function posthog.get_all_flags_and_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None) -> FlagsAndPayloads +function posthog.get_all_flags(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[dict[str, FlagValue]] +function posthog.get_all_flags_and_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> FlagsAndPayloads function posthog.get_context_options() -> Dict[str, Any] -function posthog.get_feature_flag(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FlagValue] +function posthog.get_feature_flag(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[FlagValue] function posthog.get_feature_flag_evaluation_runtime(key: str) -> Optional[FeatureFlagEvaluationRuntime] function posthog.get_feature_flag_keys_by_evaluation_runtime(evaluation_runtime: Union[FeatureFlagEvaluationRuntime, str]) -> list[str] -function posthog.get_feature_flag_payload(key: str, distinct_id: ID_TYPES, match_value: Optional[FlagValue] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[object] -function posthog.get_feature_flag_result(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FeatureFlagResult] +function posthog.get_feature_flag_payload(key: str, distinct_id: ID_TYPES, match_value: Optional[FlagValue] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[object] +function posthog.get_feature_flag_result(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[FeatureFlagResult] function posthog.get_remote_config_payload(key: str) function posthog.get_tags() -> Dict[str, Any] function posthog.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime.datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] @@ -1827,7 +1829,7 @@ method posthog.async_client.AsyncClient.capture_ai(event: str, **kwargs: Unpack[ method posthog.async_client.AsyncClient.capture_ai_immediate(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.async_client.AsyncClient.capture_exception(exception: Optional[ExceptionArg] = None, *, level: Optional[str] = None, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.async_client.AsyncClient.capture_immediate(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] -method posthog.async_client.AsyncClient.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations +method posthog.async_client.AsyncClient.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> FeatureFlagEvaluations method posthog.async_client.AsyncClient.flush(timeout_seconds: Optional[float] = 10) -> None method posthog.async_client.AsyncClient.get_remote_config_payload(key: str) -> Optional[Any] method posthog.async_client.AsyncClient.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] @@ -1842,23 +1844,23 @@ method posthog.client.Client.alias(previous_id: ID_TYPES, distinct_id: Optional[ method posthog.client.Client.capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.client.Client.capture_ai(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.client.Client.capture_exception(exception: Optional[ExceptionArg], *, level: Optional[str] = None, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] -method posthog.client.Client.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[List[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations -method posthog.client.Client.feature_enabled(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[bool] +method posthog.client.Client.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[List[str]] = None, device_id: Optional[str] = None, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> FeatureFlagEvaluations +method posthog.client.Client.feature_enabled(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[bool] method posthog.client.Client.feature_flag_definitions() method posthog.client.Client.flush(timeout_seconds: Optional[float] = 10) -> None method posthog.client.Client.get_active_span() -> Optional[Span] -method posthog.client.Client.get_all_flags(distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> Optional[dict[str, Union[bool, str]]] -method posthog.client.Client.get_all_flags_and_payloads(distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsAndPayloads +method posthog.client.Client.get_all_flags(distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[dict[str, Union[bool, str]]] +method posthog.client.Client.get_all_flags_and_payloads(distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> FlagsAndPayloads method posthog.client.Client.get_context_options() -> Dict[str, Any] -method posthog.client.Client.get_feature_flag(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FlagValue] +method posthog.client.Client.get_feature_flag(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[FlagValue] method posthog.client.Client.get_feature_flag_evaluation_runtime(key: str) -> Optional[FeatureFlagEvaluationRuntime] method posthog.client.Client.get_feature_flag_keys_by_evaluation_runtime(evaluation_runtime: Union[FeatureFlagEvaluationRuntime, str]) -> list[str] -method posthog.client.Client.get_feature_flag_payload(key: str, distinct_id: ID_TYPES, *, match_value: Optional[FlagValue] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[object] -method posthog.client.Client.get_feature_flag_result(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FeatureFlagResult] -method posthog.client.Client.get_feature_flags_and_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsAndPayloads -method posthog.client.Client.get_feature_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> dict[str, Optional[str]] -method posthog.client.Client.get_feature_variants(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> dict[str, Union[bool, str]] -method posthog.client.Client.get_flags_decision(distinct_id: Optional[ID_TYPES] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsResponse +method posthog.client.Client.get_feature_flag_payload(key: str, distinct_id: ID_TYPES, *, match_value: Optional[FlagValue] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[object] +method posthog.client.Client.get_feature_flag_result(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> Optional[FeatureFlagResult] +method posthog.client.Client.get_feature_flags_and_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> FlagsAndPayloads +method posthog.client.Client.get_feature_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> dict[str, Optional[str]] +method posthog.client.Client.get_feature_variants(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> dict[str, Union[bool, str]] +method posthog.client.Client.get_flags_decision(distinct_id: Optional[ID_TYPES] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, *, person_property_keys_known_absent: Optional[Iterable[str]] = None, group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None) -> FlagsResponse method posthog.client.Client.get_remote_config_payload(key: str) method posthog.client.Client.get_tags() -> Dict[str, Any] method posthog.client.Client.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] diff --git a/sdk_compliance_adapter/CONTRIBUTING.md b/sdk_compliance_adapter/CONTRIBUTING.md index e98cd7497..7b841176b 100644 --- a/sdk_compliance_adapter/CONTRIBUTING.md +++ b/sdk_compliance_adapter/CONTRIBUTING.md @@ -4,7 +4,7 @@ This package contains the PostHog Python SDK compliance adapter used with the Po ## Running tests -Tests run automatically in CI via GitHub Actions against harness **1.26.0**. The compliance job runs once for each capture compression (gzip, deflate and zstd). Each run opts into the local-evaluation suite and fails on compliance regressions. +Tests run automatically in CI via GitHub Actions against harness **1.34.0**. The compliance job runs once for each capture compression (gzip, deflate and zstd). Each run opts into the local-evaluation suite and fails on compliance regressions. Run adapter protocol tests from the repository root in an activated virtual environment: @@ -44,7 +44,7 @@ docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-pyt docker run --rm \ --name test-harness \ --network test-network \ - ghcr.io/posthog/sdk-test-harness:1.26.0 \ + ghcr.io/posthog/sdk-test-harness:1.34.0@sha256:43f75861fbcf5bc6c3d35511caa2be2d55274054c6071ebeb943aca0bcd0633a \ run --adapter-url http://sdk-adapter:8080 --mock-url http://test-harness:8081 # Cleanup diff --git a/sdk_compliance_adapter/README.md b/sdk_compliance_adapter/README.md index 703f5873a..deec73a91 100644 --- a/sdk_compliance_adapter/README.md +++ b/sdk_compliance_adapter/README.md @@ -59,6 +59,14 @@ explicit property matching; it does not change the SDK's default matching mode. enabled, forced remote calls use a separate definitions-free SDK Client so they cannot accidentally resolve from local rules. Legacy remote responses and flag-called events are preserved. Reset disposes both Clients. +- The adapter also advertises `feature_flags_known_absent_v1`. `/get_feature_flag` + passes optional `person_property_keys_known_absent` and + `group_property_keys_known_absent` to the SDK unchanged, including empty or + over-limit lists, so the SDK's own validation is tested. A rejected list + returns HTTP 500 with the SDK's error. With `allow_remote_fallback: true` it + calls the SDK's default getter on the Client with local definitions, which + evaluates locally and falls back to `/flags` when inconclusive. That mode + conflicts with `force_remote: true` and `only_evaluate_locally: true` (HTTP 400). The adapter is sequential (it does not advertise parallel-test support). diff --git a/sdk_compliance_adapter/adapter.py b/sdk_compliance_adapter/adapter.py index 18d36976c..c3d690b6d 100644 --- a/sdk_compliance_adapter/adapter.py +++ b/sdk_compliance_adapter/adapter.py @@ -318,6 +318,7 @@ def health(): "fail_open", "encoding_" + compression_name(), "feature_flags_local_evaluation_v1", + "feature_flags_known_absent_v1", # Remote /flags requests send ?v=4 and read the v4 flag record. "flags_response_v4", # The legacy payload accessor is exposed on /get_feature_flag_payload. @@ -632,14 +633,33 @@ def get_feature_flag(): person_properties = data.get("person_properties") groups = data.get("groups") group_properties = data.get("group_properties") + # Passed through unchanged so the SDK's own validation is exercised. + known_absent = { + name: data[name] + for name in ( + "person_property_keys_known_absent", + "group_property_keys_known_absent", + ) + if name in data + } disable_geoip = data.get("disable_geoip") only_evaluate_locally = data.get("only_evaluate_locally", False) - force_remote = data.get("force_remote", not only_evaluate_locally) + allow_remote_fallback = data.get("allow_remote_fallback", False) + force_remote = data.get( + "force_remote", not only_evaluate_locally and not allow_remote_fallback + ) if only_evaluate_locally and force_remote: return jsonify( {"error": "only_evaluate_locally conflicts with force_remote"} ), 400 + if allow_remote_fallback and (only_evaluate_locally or force_remote): + return jsonify( + { + "error": "allow_remote_fallback conflicts with force_remote " + "and only_evaluate_locally" + } + ), 400 if not key: return jsonify({"error": "key is required"}), 400 if not distinct_id: @@ -655,6 +675,7 @@ def get_feature_flag(): disable_geoip=disable_geoip, only_evaluate_locally=True, send_feature_flag_events=False, + **known_absent, ) # The real local-only SDK API returns None for inconclusive results; # a conclusive false is a FeatureFlagResult, not a cache miss. @@ -665,16 +686,32 @@ def get_feature_flag(): locally_evaluated=conclusive, ) - client = (state.remote_client or state.client) if force_remote else state.client - value = client.get_feature_flag( - key, - distinct_id, - person_properties=person_properties, - groups=groups, - group_properties=group_properties, - disable_geoip=disable_geoip, - only_evaluate_locally=not force_remote, - ) + if allow_remote_fallback: + # The default getter: local evaluation, then /flags when inconclusive. + client = state.client + value = client.get_feature_flag( + key, + distinct_id, + person_properties=person_properties, + groups=groups, + group_properties=group_properties, + disable_geoip=disable_geoip, + **known_absent, + ) + else: + client = ( + (state.remote_client or state.client) if force_remote else state.client + ) + value = client.get_feature_flag( + key, + distinct_id, + person_properties=person_properties, + groups=groups, + group_properties=group_properties, + disable_geoip=disable_geoip, + only_evaluate_locally=not force_remote, + **known_absent, + ) # Ensure the SDK's side-effect $feature_flag_called event is sent before # the adapter action returns. Otherwise the harness may reset mock-server diff --git a/sdk_compliance_adapter/docker-compose.yml b/sdk_compliance_adapter/docker-compose.yml index 23a8bd6cc..d02ab8639 100644 --- a/sdk_compliance_adapter/docker-compose.yml +++ b/sdk_compliance_adapter/docker-compose.yml @@ -16,7 +16,7 @@ services: # Test harness test-harness: - image: ghcr.io/posthog/sdk-test-harness:1.26.0 + image: ghcr.io/posthog/sdk-test-harness:1.34.0@sha256:43f75861fbcf5bc6c3d35511caa2be2d55274054c6071ebeb943aca0bcd0633a command: ["run", "--adapter-url", "http://sdk-adapter:8080", "--mock-url", "http://test-harness:8081"] networks: - test-network diff --git a/sdk_compliance_adapter/test_adapter.py b/sdk_compliance_adapter/test_adapter.py index 6c12e86ee..01d1d36f8 100644 --- a/sdk_compliance_adapter/test_adapter.py +++ b/sdk_compliance_adapter/test_adapter.py @@ -88,6 +88,7 @@ def test_health_and_init_use_one_codec(adapter, monkeypatch, env_value, codec): monkeypatch.setenv("COMPRESSION", env_value) capabilities = adapter.app.test_client().get("/health").json["capabilities"] assert "feature_flags_local_evaluation_v1" in capabilities + assert "feature_flags_known_absent_v1" in capabilities assert { "capture_v1", "capture_ai_v1", @@ -296,6 +297,103 @@ def test_rejects_conflicting_evaluation_modes(adapter, route): assert response.status_code == 400 +def test_known_absent_keys_resolve_locally(adapter, monkeypatch): + client = initialize(adapter) + monkeypatch.setattr( + posthog.client, "get", Mock(return_value=GetResponse(data=definitions())) + ) + client.post("/reload_feature_flag_definitions", json={}) + remote = Mock(side_effect=AssertionError("Local-only must never request /flags")) + monkeypatch.setattr(adapter.state.client, "_get_flags_decision", remote) + response = client.post( + "/get_feature_flag", + json={ + "key": "flag", + "distinct_id": "user", + "person_properties": {"plan": "banana"}, + "person_property_keys_known_absent": ["plan"], + "only_evaluate_locally": True, + }, + ) + assert response.json == { + "success": True, + "value": False, + "locally_evaluated": True, + } + remote.assert_not_called() + + +def test_allow_remote_fallback_sends_known_absent_keys(adapter, monkeypatch): + client = initialize(adapter) + monkeypatch.setattr( + posthog.client, "get", Mock(return_value=GetResponse(data=definitions())) + ) + client.post("/reload_feature_flag_definitions", json={}) + remote = Mock( + return_value=posthog.client.normalize_flags_response( + {"featureFlags": {"flag": True}} + ) + ) + monkeypatch.setattr(adapter.state.client, "_get_flags_decision", remote) + monkeypatch.setattr( + adapter.state.remote_client, + "_get_flags_decision", + Mock(side_effect=AssertionError("Fallback must use the local client")), + ) + monkeypatch.setattr(adapter.state.client, "capture", Mock()) + response = client.post( + "/get_feature_flag", + json={ + "key": "flag", + "distinct_id": "user", + "person_property_keys_known_absent": ["region"], + "group_property_keys_known_absent": {"organization": ["tier"]}, + "allow_remote_fallback": True, + }, + ) + assert response.json == {"success": True, "value": True} + remote.assert_called_once() + assert remote.call_args.kwargs["person_property_keys_known_absent"] == ["region"] + assert remote.call_args.kwargs["group_property_keys_known_absent"] == { + "organization": ["tier"] + } + + +def test_over_limit_known_absent_keys_are_rejected_by_the_sdk(adapter, monkeypatch): + client = initialize(adapter) + remote = Mock(side_effect=AssertionError("Over-limit lists must not be sent")) + monkeypatch.setattr(adapter.state.client, "_get_flags_decision", remote) + response = client.post( + "/get_feature_flag", + json={ + "key": "flag", + "distinct_id": "user", + "person_property_keys_known_absent": ["plan"] * 1001, + "allow_remote_fallback": True, + }, + ) + assert response.status_code == 500 + assert "at most 1000" in response.json["error"] + remote.assert_not_called() + + +@pytest.mark.parametrize( + "mode", [{"force_remote": True}, {"only_evaluate_locally": True}] +) +def test_allow_remote_fallback_conflicts_with_other_modes(adapter, mode): + client = initialize(adapter) + response = client.post( + "/get_feature_flag", + json={ + "key": "flag", + "distinct_id": "user", + "allow_remote_fallback": True, + **mode, + }, + ) + assert response.status_code == 400 + + @pytest.mark.parametrize("timeout", [0, -1, 30001, True, "100", None]) def test_reload_validates_deadline(adapter, timeout): client = initialize(adapter)