v0.166.0
  1import logging
  2from abc import ABC, abstractmethod
  3from functools import cached_property
  4from typing import Any
  5
  6from opentelemetry import trace
  7from opentelemetry.semconv._incubating.attributes.feature_flag_attributes import (
  8    FEATURE_FLAG_KEY,
  9    FEATURE_FLAG_PROVIDER_NAME,
 10    FEATURE_FLAG_RESULT_REASON,
 11    FEATURE_FLAG_RESULT_VALUE,
 12    FeatureFlagResultReasonValues,
 13)
 14from plain.runtime import settings
 15from plain.utils import timezone
 16
 17from . import exceptions
 18from .utils import coerce_key
 19
 20logger = logging.getLogger(__name__)
 21tracer = trace.get_tracer("plain.flags")
 22
 23
 24class Flag(ABC):
 25    @abstractmethod
 26    def get_key(self) -> Any:
 27        """
 28        Determine a unique key for this instance of the flag.
 29        This should be a quick operation, as it will be called on every use of the flag.
 30
 31        For convenience, you can return an instance of a Plain Model
 32        and it will be converted to a string automatically.
 33
 34        Return a falsy value if you don't want to store the flag result.
 35        """
 36        ...
 37
 38    @abstractmethod
 39    def get_value(self) -> Any:
 40        """
 41        Compute the resulting value of the flag.
 42
 43        The value needs to be JSON serializable.
 44
 45        If get_key() returns a value, this will only be called once per key
 46        and then subsequent calls will return the saved value from the DB.
 47        """
 48        ...
 49
 50    def get_db_name(self) -> str:
 51        """
 52        Should basically always be the name of the class.
 53        But this is overridable in case of renaming/refactoring/importing.
 54        """
 55        return self.__class__.__name__
 56
 57    def retrieve_or_compute_value(self) -> Any:
 58        """
 59        Retrieve the value from the DB if it exists,
 60        otherwise compute the value and save it to the DB.
 61        """
 62        from .models import Flag, FlagResult  # So Plain app is ready...
 63
 64        flag_name = self.get_db_name()
 65
 66        with tracer.start_as_current_span(
 67            f"flag {flag_name}",
 68            attributes={
 69                FEATURE_FLAG_PROVIDER_NAME: "plain.flags",
 70            },
 71        ) as span:
 72            # Resolve the key first so it's set on the span regardless of
 73            # which path we take below — including the disabled path, where
 74            # dashboards filtering by key still need to see the evaluation.
 75            key = self.get_key()
 76            if key:
 77                key = coerce_key(key)
 78                span.set_attribute(FEATURE_FLAG_KEY, key)
 79
 80            # Create an associated DB Flag that we can use to enable/disable
 81            # and tie the results to
 82            flag_obj, _ = Flag.query.upsert(
 83                name=flag_name,
 84                defaults={"used_at": timezone.now()},
 85                unique_fields=[Flag.name],
 86            )
 87
 88            if not flag_obj.enabled:
 89                msg = f"The {flag_obj} flag has been disabled and should either not be called, or be re-enabled."
 90                span.set_attribute(
 91                    FEATURE_FLAG_RESULT_REASON,
 92                    FeatureFlagResultReasonValues.DISABLED.value,
 93                )
 94
 95                if settings.DEBUG:
 96                    raise exceptions.FlagDisabled(msg)
 97                else:
 98                    logger.exception(msg)
 99                    # Might not be the type of return value expected! Better than totally crashing now though.
100                    return None
101
102            if not key:
103                # No key, so we always recompute the value and return it
104                value = self.get_value()
105
106                span.set_attribute(
107                    FEATURE_FLAG_RESULT_REASON,
108                    FeatureFlagResultReasonValues.TARGETING_MATCH.value,
109                )
110                span.set_attribute(FEATURE_FLAG_RESULT_VALUE, str(value))
111
112                return value
113
114            try:
115                flag_result = FlagResult.query.get(
116                    FlagResult.flag.id.equals(flag_obj.id),
117                    FlagResult.key.equals(key),
118                )
119
120                span.set_attribute(
121                    FEATURE_FLAG_RESULT_REASON,
122                    FeatureFlagResultReasonValues.CACHED.value,
123                )
124                span.set_attribute(FEATURE_FLAG_RESULT_VALUE, str(flag_result.value))
125
126                return flag_result.value
127            except FlagResult.DoesNotExist:
128                value = self.get_value()
129                flag_result = FlagResult.query.create(
130                    flag=flag_obj, key=key, value=value
131                )
132
133                # Per OTel semconv, `targeting_match` is "dynamic evaluation,
134                # such as a rule or specific user-targeting" — `get_value()`
135                # ran with this key. `static` would mean "no dynamic
136                # evaluation," which doesn't apply here.
137                span.set_attribute(
138                    FEATURE_FLAG_RESULT_REASON,
139                    FeatureFlagResultReasonValues.TARGETING_MATCH.value,
140                )
141                span.set_attribute(FEATURE_FLAG_RESULT_VALUE, str(value))
142
143                return flag_result.value
144
145    @cached_property
146    def value(self) -> Any:
147        """
148        Cached version of retrieve_or_compute_value()
149        """
150        return self.retrieve_or_compute_value()
151
152    def __bool__(self) -> bool:
153        """
154        Allow for use in boolean expressions.
155        """
156        return bool(self.value)
157
158    def __contains__(self, item: Any) -> bool:
159        """
160        Allow for use in `in` expressions.
161        """
162        return item in self.value
163
164    def __eq__(self, other: object) -> bool:
165        """
166        Allow for use in `==` expressions.
167        """
168        return self.value == other