feat: Add async hook, plugin, and flag tracker

ldclient/hook.py

@@ -79,6 +79,65 @@ def after_evaluation(self, series_context: EvaluationSeriesContext, data: dict,
         return data
 
 
+class AsyncHook(ABC):
+    """
+    Abstract class for extending AsyncLDClient functionality via hooks.
+
+    .. caution::
+        This feature is experimental and should NOT be considered ready for production
+        use. It may change or be removed without notice and is not subject to backwards
+        compatibility guarantees. Pin to a specific minor version and review the changelog
+        before upgrading.
+
+    All provided async 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.
+
+    Unlike :class:`Hook`, the before and after methods are coroutines and will
+    be awaited by the async client.
+    """
+
+    @property
+    @abstractmethod
+    def metadata(self) -> Metadata:
+        """
+        Get metadata about the hook implementation.
+        """
+        return Metadata(name='UNDEFINED')
+
+    async 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 a coroutine
+        and will be awaited.
+
+        :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
+
+    async 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 a coroutine
+        and will be awaited.
+
+        :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

ldclient/impl/async_flag_tracker.py

@@ -0,0 +1,60 @@
+from typing import Any, Callable
+
+from ldclient.context import Context
+from ldclient.impl.aio.concurrency import AsyncCallbackScheduler, AsyncLock
+from ldclient.impl.listeners import Listeners
+from ldclient.interfaces import AsyncFlagTracker, FlagChange, FlagValueChange
+
+
+class AsyncFlagValueChangeListener:
+    """Calls the user's listener when a specific flag's evaluated value changes for a specific context."""
+
+    def __init__(self, key: str, context: Context, listener: Callable[[FlagValueChange], None], eval_fn: Callable, scheduler: AsyncCallbackScheduler, initial_value: Any):
+        self.__key = key
+        self.__context = context
+        self.__listener = listener
+        self.__eval_fn = eval_fn
+        self.__scheduler = scheduler
+
+        self.__lock = AsyncLock()
+        self.__value = initial_value
+
+    @classmethod
+    async def create(cls, key: str, context: Context, listener: Callable[[FlagValueChange], None], eval_fn: Callable, scheduler: AsyncCallbackScheduler) -> 'AsyncFlagValueChangeListener':
+        """Evaluates the flag once to capture the baseline value, then returns the listener."""
+        initial_value = await eval_fn(key, context)
+        return cls(key, context, listener, eval_fn, scheduler, initial_value)
+
+    def __call__(self, flag_change: FlagChange):
+        if flag_change.key != self.__key:
+            return
+        self.__scheduler.call(self._on_flag_change)
+
+    async def _on_flag_change(self):
+        async with self.__lock:
+            new_value = await self.__eval_fn(self.__key, self.__context)
+            old_value, self.__value = self.__value, new_value
+
+        if new_value == old_value:
+            return
+
+        self.__listener(FlagValueChange(self.__key, old_value, new_value))
+
+
+class AsyncFlagTrackerImpl(AsyncFlagTracker):
+    def __init__(self, listeners: Listeners, eval_fn: Callable):
+        self.__listeners = listeners
+        self.__eval_fn = eval_fn
+        self.__scheduler = AsyncCallbackScheduler()
+
+    def add_listener(self, listener: Callable[[FlagChange], None]):
+        self.__listeners.add(listener)
+
+    def remove_listener(self, listener: Callable[[FlagChange], None]):
+        self.__listeners.remove(listener)
+
+    async def add_flag_value_change_listener(self, key: str, context: Context, fn: Callable[[FlagValueChange], None]) -> Callable[[FlagChange], None]:
+        listener = await AsyncFlagValueChangeListener.create(key, context, fn, self.__eval_fn, self.__scheduler)
+        self.add_listener(listener)
+
+        return listener

ldclient/interfaces.py

@@ -310,6 +310,11 @@ class AsyncReadOnlyStore(Protocol):
     Both async data systems expose their active store through this uniform interface:
     :class:`AsyncFeatureStore` satisfies it directly (FDv1), and FDv2 adapts its
     synchronous in-memory store to it. This is the async analog of :class:`ReadOnlyStore`.
+
+    .. caution::
+        This feature is experimental and should NOT be considered ready for production
+        use. It may change or be removed without notice and is not subject to backwards
+        compatibility guarantees.
     """
 
     @abstractmethod
@@ -691,6 +696,10 @@ def status(self) -> BigSegmentStoreStatus:
         """
         Gets the current status of the store.
 
+        Before the first poll completes, the synchronous SDK performs a blocking store query and
+        returns its result, while the async SDK (``AsyncLDClient``) returns the last polled status
+        without blocking -- ``available=False`` until the first background poll completes.
+
         :return: the status
         """
         pass
@@ -1187,6 +1196,56 @@ def add_flag_value_change_listener(self, key: str, context: Context, listener: C
         pass
 
 
+class AsyncFlagTracker(ABC):
+    """
+    An interface for tracking changes in feature flag configurations, for use with the async client
+    (:class:`ldclient.async_client.AsyncLDClient`). It mirrors :class:`FlagTracker`, except
+    :meth:`add_flag_value_change_listener` is a coroutine.
+
+    .. caution::
+        This feature is experimental and should NOT be considered ready for production
+        use. It may change or be removed without notice and is not subject to backwards
+        compatibility guarantees.
+
+    An implementation of this abstract class is returned by
+    :meth:`ldclient.async_client.AsyncLDClient.flag_tracker`. Application code never needs to
+    implement this interface.
+    """
+
+    @abstractmethod
+    def add_listener(self, listener: Callable[[FlagChange], None]) -> None:
+        """
+        Registers a listener to be notified of feature flag changes in general. Behaves identically
+        to :meth:`FlagTracker.add_listener`.
+
+        :param listener: listener to call when a flag has changed
+        """
+        pass
+
+    @abstractmethod
+    def remove_listener(self, listener: Callable[[FlagChange], None]) -> None:
+        """
+        Unregisters a listener so that it will no longer be notified of feature flag changes.
+
+        :param listener: the listener to remove
+        """
+        pass
+
+    @abstractmethod
+    async def add_flag_value_change_listener(self, key: str, context: Context, listener: Callable[[FlagValueChange], None]) -> Callable[[FlagChange], None]:
+        """
+        Registers a listener to be notified when a specific flag's evaluated value changes for a
+        specific context. Behaves like :meth:`FlagTracker.add_flag_value_change_listener`, but is a
+        **coroutine** and must be awaited (it evaluates the flag to capture the baseline value).
+
+        :param key: the flag key to monitor
+        :param context: the context to evaluate against the flag
+        :param listener: the listener to trigger if the value has changed
+        :return: the subscription; pass it to :meth:`remove_listener` to unsubscribe
+        """
+        pass
+
+
 class DataStoreStatus:
     """
     Information about the data store's status.

ldclient/plugin.py

@@ -6,7 +6,7 @@
 
 from ldclient.context import Context
 from ldclient.evaluation import EvaluationDetail, FeatureFlagsState
-from ldclient.hook import Hook
+from ldclient.hook import AsyncHook, Hook
 from ldclient.impl import AnyNum
 from ldclient.impl.evaluator import error_reason
 from ldclient.interfaces import (
@@ -17,6 +17,7 @@
 )
 
 if TYPE_CHECKING:
+    from ldclient.async_client import AsyncLDClient
     from ldclient.client import LDClient
 
 
@@ -108,3 +109,64 @@ def get_hooks(self, metadata: EnvironmentMetadata) -> List[Hook]:
         :return: A list of hooks to be registered with the SDK
         """
         return []
+
+
+class AsyncPlugin(ABC):
+    """
+    Abstract base class for extending AsyncLDClient functionality via plugins.
+
+    .. caution::
+        This feature is experimental and should NOT be considered ready for production
+        use. It may change or be removed without notice and is not subject to backwards
+        compatibility guarantees. Pin to a specific minor version and review the changelog
+        before upgrading.
+
+    All provided async plugin implementations **MUST** inherit from this class.
+
+    This class includes default implementations for optional methods. This
+    allows LaunchDarkly to expand the list of plugin methods without breaking
+    customer integrations.
+
+    Unlike :class:`Plugin`, the register() method is a coroutine and will be
+    awaited by the async client, allowing plugins to perform asynchronous
+    initialization such as connecting to telemetry backends.
+    """
+
+    @property
+    @abstractmethod
+    def metadata(self) -> PluginMetadata:
+        """
+        Get metadata about the plugin implementation.
+
+        :return: Metadata containing information about the plugin
+        """
+        return PluginMetadata(name='UNDEFINED')
+
+    async def register(self, client: 'AsyncLDClient', metadata: EnvironmentMetadata) -> None:
+        """
+        Register the plugin with the async SDK client.
+
+        This method is called during SDK initialization to allow the plugin
+        to set up any necessary integrations, register hooks, or perform
+        other initialization tasks. The method is a coroutine and will be
+        awaited, allowing asynchronous I/O during registration.
+
+        :param client: The AsyncLDClient instance
+        :param metadata: Metadata about the environment in which the SDK is running
+        """
+        pass
+
+    def get_hooks(self, metadata: EnvironmentMetadata) -> List[AsyncHook]:
+        """
+        Get a list of hooks that this plugin provides.
+
+        This method is called before register() to collect all hooks from
+        plugins. The hooks returned will be added to the SDK's hook configuration.
+        Async plugins provide async :class:`AsyncHook` instances only.
+
+        This method is synchronous (returns a list immediately — no I/O).
+
+        :param metadata: Metadata about the environment in which the SDK is running
+        :return: A list of hooks to be registered with the SDK
+        """
+        return []