feat: Add support for hooks (#287)

docs/api-main.rst

@@ -20,6 +20,12 @@ ldclient.config module
     :members:
     :special-members: __init__
 
+ldclient.hook module
+--------------------------
+
+.. automodule:: ldclient.hook
+    :members:
+
 ldclient.evaluation module
 --------------------------
 

ldclient/client.py

@@ -2,7 +2,7 @@
 This submodule contains the client class that provides most of the SDK functionality.
 """
 
-from typing import Optional, Any, Dict, Mapping, Union, Tuple, Callable
+from typing import Optional, Any, Dict, Mapping, Union, Tuple, Callable, List
 
 from .impl import AnyNum
 
@@ -15,6 +15,7 @@
 from ldclient.config import Config
 from ldclient.context import Context
 from ldclient.feature_store import _FeatureStoreDataSetSorter
+from ldclient.hook import Hook, EvaluationSeriesContext, _EvaluationWithHookResult
 from ldclient.evaluation import EvaluationDetail, FeatureFlagsState
 from ldclient.impl.big_segments import BigSegmentStoreManager
 from ldclient.impl.datasource.feature_requester import FeatureRequesterImpl
@@ -187,8 +188,10 @@ def __init__(self, config: Config, start_wait: float=5):
         self._config = config
         self._config._validate()
 
+        self.__hooks_lock = ReadWriteLock()
+        self.__hooks = config.hooks  # type: List[Hook]
+
         self._event_processor = None
-        self._lock = Lock()
         self._event_factory_default = EventFactory(False)
         self._event_factory_with_reasons = EventFactory(True)
 
@@ -395,8 +398,11 @@ def variation(self, key: str, context: Context, default: Any) -> Any:
           available from LaunchDarkly
         :return: the variation for the given context, or the ``default`` value if the flag cannot be evaluated
         """
-        detail, _ = self._evaluate_internal(key, context, default, self._event_factory_default)
-        return detail.value
+        def evaluate():
+            detail, _ = self._evaluate_internal(key, context, default, self._event_factory_default)
+            return _EvaluationWithHookResult(evaluation_detail=detail)
+
+        return self.__evaluate_with_hooks(key=key, context=context, default_value=default, method="variation", block=evaluate).evaluation_detail.value
 
     def variation_detail(self, key: str, context: Context, default: Any) -> EvaluationDetail:
         """Calculates the value of a feature flag for a given context, and returns an object that
@@ -412,8 +418,11 @@ def variation_detail(self, key: str, context: Context, default: Any) -> Evaluati
         :return: an :class:`ldclient.evaluation.EvaluationDetail` object that includes the feature
           flag value and evaluation reason
         """
-        detail, _ = self._evaluate_internal(key, context, default, self._event_factory_with_reasons)
-        return detail
+        def evaluate():
+            detail, _ = self._evaluate_internal(key, context, default, self._event_factory_with_reasons)
+            return _EvaluationWithHookResult(evaluation_detail=detail)
+
+        return self.__evaluate_with_hooks(key=key, context=context, default_value=default, method="variation_detail", block=evaluate).evaluation_detail
 
     def migration_variation(self, key: str, context: Context, default_stage: Stage) -> Tuple[Stage, OpTracker]:
         """
@@ -429,17 +438,21 @@ def migration_variation(self, key: str, context: Context, default_stage: Stage)
             log.error(f"default stage {default_stage} is not a valid stage; using 'off' instead")
             default_stage = Stage.OFF
 
-        detail, flag = self._evaluate_internal(key, context, default_stage.value, self._event_factory_default)
+        def evaluate():
+            detail, flag = self._evaluate_internal(key, context, default_stage.value, self._event_factory_default)
+
+            if isinstance(detail.value, str):
+                stage = Stage.from_str(detail.value)
+                if stage is not None:
+                    tracker = OpTracker(key, flag, context, detail, default_stage)
+                    return _EvaluationWithHookResult(evaluation_detail=detail, results={'default_stage': stage, 'tracker': tracker})
 
-        if isinstance(detail.value, str):
-            stage = Stage.from_str(detail.value)
-            if stage is not None:
-                tracker = OpTracker(key, flag, context, detail, default_stage)
-                return stage, tracker
+            detail = EvaluationDetail(default_stage.value, None, error_reason('WRONG_TYPE'))
+            tracker = OpTracker(key, flag, context, detail, default_stage)
+            return _EvaluationWithHookResult(evaluation_detail=detail, results={'default_stage': default_stage, 'tracker': tracker})
 
-        detail = EvaluationDetail(default_stage.value, None, error_reason('WRONG_TYPE'))
-        tracker = OpTracker(key, flag, context, detail, default_stage)
-        return default_stage, tracker
+        hook_result = self.__evaluate_with_hooks(key=key, context=context, default_value=default_stage, method="migration_variation", block=evaluate)
+        return hook_result.results['default_stage'], hook_result.results['tracker']
 
     def _evaluate_internal(self, key: str, context: Context, default: Any, event_factory) -> Tuple[EvaluationDetail, Optional[FeatureFlag]]:
         default = self._config.get_default(key, default)
@@ -451,8 +464,7 @@ def _evaluate_internal(self, key: str, context: Context, default: Any, event_fac
             if self._store.initialized:
                 log.warning("Feature Flag evaluation attempted before client has initialized - using last known values from feature store for feature key: " + key)
             else:
-                log.warning("Feature Flag evaluation attempted before client has initialized! Feature store unavailable - returning default: "
-                         + str(default) + " for feature key: " + key)
+                log.warning("Feature Flag evaluation attempted before client has initialized! Feature store unavailable - returning default: " + str(default) + " for feature key: " + key)
                 reason = error_reason('CLIENT_NOT_READY')
                 self._send_event(event_factory.new_unknown_flag_event(key, context, default, reason))
                 return EvaluationDetail(default, None, reason), None
@@ -583,6 +595,70 @@ def secure_mode_hash(self, context: Context) -> str:
             return ""
         return hmac.new(str(self._config.sdk_key).encode(), context.fully_qualified_key.encode(), hashlib.sha256).hexdigest()
 
+    def add_hook(self, hook: Hook):
+        """
+        Add a hook to the client. In order to register a hook before the client starts, please use the `hooks` property of
+        `Config`.
+
+        Hooks provide entrypoints which allow for observation of SDK functions.
+
+        :param hook:
+        """
+        if not isinstance(hook, Hook):
+            return
+
+        self.__hooks_lock.lock()
+        self.__hooks.append(hook)
+        self.__hooks_lock.unlock()
+
+    def __evaluate_with_hooks(self, key: str, context: Context, default_value: Any, method: str, block: Callable[[], _EvaluationWithHookResult]) -> _EvaluationWithHookResult:
+        """
+        # evaluate_with_hook will run the provided block, wrapping it with evaluation hook support.
+        #
+        # :param key:
+        # :param context:
+        # :param default:
+        # :param method:
+        # :param block:
+        # :return:
+        """
+        hooks = []  # type: List[Hook]
+        try:
+            self.__hooks_lock.rlock()
+
+            if len(self.__hooks) == 0:
+                return block()
+
+            hooks = self.__hooks.copy()
+        finally:
+            self.__hooks_lock.runlock()
+
+        series_context = EvaluationSeriesContext(key=key, context=context, default_value=default_value, method=method)
+        hook_data = self.__execute_before_evaluation(hooks, series_context)
+        evaluation_result = block()
+        self.__execute_after_evaluation(hooks, series_context, hook_data, evaluation_result.evaluation_detail)
+
+        return evaluation_result
+
+    def __execute_before_evaluation(self, hooks: List[Hook], series_context: EvaluationSeriesContext) -> List[Any]:
+        return [
+            self.__try_execute_stage("beforeEvaluation", hook.metadata.name, lambda: hook.before_evaluation(series_context, {}))
+            for hook in hooks
+        ]
+
+    def __execute_after_evaluation(self, hooks: List[Hook], series_context: EvaluationSeriesContext, hook_data: List[Any], evaluation_detail: EvaluationDetail) -> List[Any]:
+        return [
+            self.__try_execute_stage("afterEvaluation", hook.metadata.name, lambda: hook.after_evaluation(series_context, data, evaluation_detail))
+            for (hook, data) in reversed(list(zip(hooks, hook_data)))
+        ]
+
+    def __try_execute_stage(self, method: str, hook_name: str, block: Callable[[], dict]) -> Optional[dict]:
+        try:
+            return block()
+        except BaseException as e:
+            log.error(f"An error occurred in {method} of the hook {hook_name}: #{e}")
+            return None
+
     @property
     def big_segment_store_status_provider(self) -> BigSegmentStoreStatusProvider:
         """

ldclient/config.py

@@ -8,6 +8,7 @@
 from threading import Event
 
 from ldclient.feature_store import InMemoryFeatureStore
+from ldclient.hook import Hook
 from ldclient.impl.util import log, validate_application_info
 from ldclient.interfaces import BigSegmentStore, EventProcessor, FeatureStore, UpdateProcessor, DataSourceUpdateSink
 
@@ -173,7 +174,8 @@ def __init__(self,
                  wrapper_version: Optional[str]=None,
                  http: HTTPConfig=HTTPConfig(),
                  big_segments: Optional[BigSegmentsConfig]=None,
-                 application: Optional[dict]=None):
+                 application: Optional[dict]=None,
+                 hooks: Optional[List[Hook]]=None):
         """
         :param sdk_key: The SDK key for your LaunchDarkly account. This is always required.
         :param base_uri: The base URL for the LaunchDarkly server. Most users should use the default
@@ -238,6 +240,7 @@ def __init__(self,
         :param http: Optional properties for customizing the client's HTTP/HTTPS behavior. See
           :class:`HTTPConfig`.
         :param application: Optional properties for setting application metadata. See :py:attr:`~application`
+        :param hooks: Hooks provide entrypoints which allow for observation of SDK functions.
         """
         self.__sdk_key = sdk_key
 
@@ -270,6 +273,7 @@ def __init__(self,
         self.__http = http
         self.__big_segments = BigSegmentsConfig() if not big_segments else big_segments
         self.__application = validate_application_info(application or {}, log)
+        self.__hooks = [hook for hook in hooks if isinstance(hook, Hook)] if hooks else []
         self._data_source_update_sink: Optional[DataSourceUpdateSink] = None
 
     def copy_with_new_sdk_key(self, new_sdk_key: str) -> 'Config':
@@ -442,6 +446,19 @@ def application(self) -> dict:
         """
         return self.__application
 
+    @property
+    def hooks(self) -> List[Hook]:
+        """
+        Initial set of hooks for the client.
+
+        Hooks provide entrypoints which allow for observation of SDK functions.
+
+        LaunchDarkly provides integration packages, and most applications will
+        not need to implement their own hooks. Refer to the
+        `launchdarkly-server-sdk-otel`.
+        """
+        return self.__hooks
+
     @property
     def data_source_update_sink(self) -> Optional[DataSourceUpdateSink]:
         """

ldclient/hook.py

@@ -0,0 +1,85 @@
+from ldclient.context import Context
+from ldclient.evaluation import EvaluationDetail
+
+from abc import ABCMeta, abstractmethod, abstractproperty
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class EvaluationSeriesContext:
+    """
+    Contextual information that will be provided to handlers during evaluation
+    series.
+    """
+
+    key: str  #: The flag key used to trigger the evaluation.
+    context: Context  #: The context used during evaluation.
+    default_value: Any  #: The default value provided to the evaluation method
+    method: str  #: The string version of the method which triggered the evaluation series.
+
+
+@dataclass
+class Metadata:
+    """
+    Metadata data class used for annotating hook implementations.
+    """
+
+    name: str  #: A name representing a hook instance.
+
+
+class Hook:
+    """
+    Abstract class for extending SDK functionality via hooks.
+
+    All provided hook implementations **MUST** inherit from this class.
+
+    This class includes default implementations for all hook handlers. This
+    allows LaunchDarkly to expand the list of hook handlers without breaking
+    customer integrations.
+    """
+    __metaclass__ = ABCMeta
+
+    @abstractproperty
+    def metadata(self) -> Metadata:
+        """
+        Get metadata about the hook implementation.
+        """
+        return Metadata(name='UNDEFINED')
+
+    @abstractmethod
+    def before_evaluation(self, series_context: EvaluationSeriesContext, data: dict) -> dict:
+        """
+        The before method is called during the execution of a variation method
+        before the flag value has been determined. The method is executed
+        synchronously.
+
+        :param series_context: Contains information about the evaluation being performed. This is not mutable.
+        :param data: A record associated with each stage of hook invocations.
+            Each stage is called with the data of the previous stage for a series.
+            The input record should not be modified.
+        :return: Data to use when executing the next state of the hook in the evaluation series.
+        """
+        return data
+
+    @abstractmethod
+    def after_evaluation(self, series_context: EvaluationSeriesContext, data: dict, detail: EvaluationDetail) -> dict:
+        """
+        The after method is called during the execution of the variation method
+        after the flag value has been determined. The method is executed
+        synchronously.
+
+        :param series_context: Contains read-only information about the
+            evaluation being performed.
+        :param data: A record associated with each stage of hook invocations.
+            Each stage is called with the data of the previous stage for a series.
+        :param detail: The result of the evaluation. This value should not be modified.
+        :return: Data to use when executing the next state of the hook in the evaluation series.
+        """
+        return data
+
+
+@dataclass
+class _EvaluationWithHookResult:
+    evaluation_detail: EvaluationDetail
+    results: Any = None