mersal-polling 0.1.0__py3-none-any.whl

mersal_polling/__init__.py

@@ -0,0 +1,21 @@
+from .config import (
+    PollingConfig,
+)
+from .default_poller import DefaultPoller
+from .message_completion_handler import (
+    message_completion_event_publisher,
+    register_message_completion_publishers,
+)
+from .poller import Poller, PollingResult
+from .poller_with_timeout import PollerWithTimeout, PollingTimeoutError
+
+__all__ = [
+    "DefaultPoller",
+    "Poller",
+    "PollerWithTimeout",
+    "PollingConfig",
+    "PollingResult",
+    "PollingTimeoutError",
+    "message_completion_event_publisher",
+    "register_message_completion_publishers",
+]

mersal_polling/config.py

@@ -0,0 +1,65 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+from mersal_polling.plugin import PollingPlugin
+from mersal_polling.poller import Poller
+
+__all__ = (
+    "FailedCompletionCorrelation",
+    "PollingConfig",
+    "SuccessfulCompletionCorrelation",
+)
+
+
+EventType = TypeVar("EventType")
+
+
+@dataclass
+class SuccessfulCompletionCorrelation(Generic[EventType]):
+    """Correlates an event with the successful completion of a message (usually a command).
+
+    The correlation is either based on a custom callback that is given the event
+    and should return the message id or by default; the correlation id will be used.
+    """
+
+    message_id_getter: Callable[[EventType], Any] | None = None
+
+
+@dataclass
+class FailedCompletionCorrelation(Generic[EventType]):
+    """Correlates an event with the failed completion of a message (usually a command).
+
+    The correlation is either based on a custom callback that is given the event
+    and should return the message id or by default; the correlation id will be used.
+    """
+
+    message_id_getter: Callable[[EventType], Any] | None = None
+
+    """
+    Callback that builds a custom exception to pass to the poller for the failed case.
+    """
+    exception_builder: Callable[[EventType], Exception] | None = None
+
+
+@dataclass
+class PollingConfig:
+    """Configuration for the polling functionality.
+
+    Args:
+        poller: The poller instance to use
+        successful_completion_events_map: Map of event types to successful completion correlations
+        failed_completion_events_map: Map of event types to failed completion correlations
+        auto_publish_completion_events: Whether to automatically publish message completion events
+        exclude_from_completion_events: Message types to exclude from automatic completion events
+    """
+
+    poller: Poller
+    successful_completion_events_map: dict[type, SuccessfulCompletionCorrelation] = field(default_factory=dict)
+    failed_completion_events_map: dict[type, FailedCompletionCorrelation] = field(default_factory=dict)
+    auto_publish_completion_events: bool = True
+    exclude_from_completion_events: set[type] = field(default_factory=set)
+
+    @property
+    def plugin(self) -> PollingPlugin:
+        return PollingPlugin(self)

mersal_polling/default_poller.py

@@ -0,0 +1,37 @@
+import uuid
+
+from anyio import Event
+
+from .poller import Poller, PollingResult
+
+__all__ = ("DefaultPoller",)
+
+
+class DefaultPoller(Poller):
+    def __init__(self) -> None:
+        self.results: dict[uuid.UUID, PollingResult] = {}
+        self.events: dict[uuid.UUID, Event] = {}
+
+    async def poll(self, message_id: uuid.UUID) -> PollingResult:
+        # Check if result already exists
+        message = self.results.get(message_id)
+        if message:
+            return message
+
+        # Create an event for this message_id if it doesn't exist
+        if message_id not in self.events:
+            self.events[message_id] = Event()
+
+        # Wait for the event to be set
+        await self.events[message_id].wait()
+
+        # Return the result (should be available now)
+        return self.results[message_id]
+
+    async def push(self, message_id: uuid.UUID, exception: Exception | None = None) -> None:
+        # Store the result
+        self.results[message_id] = PollingResult(message_id, exception)
+
+        # If there's a waiting event, trigger it
+        if message_id in self.events:
+            self.events[message_id].set()

mersal_polling/error_handler_poller_wrapper.py

@@ -0,0 +1,21 @@
+from mersal.messages import TransportMessage
+from mersal.retry import ErrorHandler
+from mersal.transport import TransactionContext
+from mersal_polling.poller import Poller
+
+__all__ = ("ErrorHandlerPollerWrapper",)
+
+
+class ErrorHandlerPollerWrapper(ErrorHandler):
+    def __init__(self, poller: Poller, error_handler: ErrorHandler) -> None:
+        self.poller = poller
+        self.error_handler = error_handler
+
+    async def handle_poison_message(
+        self,
+        message: TransportMessage,
+        transaction_context: TransactionContext,
+        exception: Exception,
+    ) -> None:
+        await self.error_handler.handle_poison_message(message, transaction_context, exception)
+        await self.poller.push(message.headers.message_id, exception)

mersal_polling/message_completion_handler.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from mersal.messages.message_completed_event import MessageCompletedEvent
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from mersal.activation import HandlerActivator
+    from mersal.app import Mersal
+    from mersal.pipeline import MessageContext
+    from mersal.types import AsyncAnyCallable
+
+__all__ = (
+    "message_completion_event_publisher",
+    "register_message_completion_publishers",
+)
+
+
+def message_completion_event_publisher(
+    message_context: MessageContext,
+    app: Mersal,
+    _: list[AsyncAnyCallable],
+) -> Callable[[Any], Awaitable[None]]:
+    """Create a handler that publishes a MessageCompletedEvent.
+
+    This function creates a message handler that publishes a MessageCompletedEvent
+    when invoked, allowing for tracking message processing completion.
+
+    Args:
+        message_context: The message context for the current message
+        app: The Mersal application instance
+        _: Unused parameter for compatibility with handler factory signature
+
+    Returns:
+        A message handler function that publishes a completion event
+    """
+
+    async def handler(_: Any) -> None:
+        """Handler that publishes a MessageCompletedEvent.
+
+        Args:
+            _: The message (not used in this handler)
+        """
+        completed_message_id = message_context.headers.message_id
+        published_message_id = uuid.uuid4()
+        await app.publish(
+            MessageCompletedEvent(completed_message_id=completed_message_id),
+            headers={"message_id": published_message_id},
+        )
+
+    return handler
+
+
+def register_message_completion_publishers(
+    activator: HandlerActivator,
+    exclude_types: set[type] | None = None,
+) -> None:
+    """Register message completion event publishers for all message types.
+
+    This function registers handlers that publish MessageCompletedEvent for all
+    message types that already have handlers registered in the activator, except
+    for those in the exclude_types set.
+
+    Args:
+        activator: The handler activator to register completion publishers with
+        exclude_types: Message types to exclude from completion event publishing
+    """
+    # Create exclude set (always exclude MessageCompletedEvent itself)
+    exclude: set[type] = set() if exclude_types is None else exclude_types.copy()
+    exclude.add(MessageCompletedEvent)
+
+    # Get all registered message types
+    completion_event_registry: set[type] = set()
+
+    # Register completion event publishers for all message types
+    for message_type in activator.registered_message_types:
+        if message_type not in exclude and message_type not in completion_event_registry:
+            # For each message type, register a handler that publishes completion events
+            def completion_publisher_factory(
+                message_context: MessageContext,
+                app: Mersal,
+            ) -> Callable[[Any], Awaitable[None]]:
+                return message_completion_event_publisher(
+                    message_context=message_context,
+                    app=app,
+                    _=[],
+                )
+
+            activator.register(message_type, completion_publisher_factory)
+            completion_event_registry.add(message_type)

mersal_polling/plugin.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from mersal.activation import HandlerActivator
+from mersal.lifespan import LifespanHandler
+from mersal.messages import MessageCompletedEvent
+from mersal.plugins import Plugin
+from mersal.retry import ErrorHandler
+from mersal_polling.error_handler_poller_wrapper import (
+    ErrorHandlerPollerWrapper,
+)
+from mersal_polling.message_completion_handler import register_message_completion_publishers
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from mersal.app import Mersal
+    from mersal.configuration import StandardConfigurator
+    from mersal.pipeline.message_context import MessageContext
+    from mersal_polling.config import (
+        FailedCompletionCorrelation,
+        PollingConfig,
+        SuccessfulCompletionCorrelation,
+    )
+
+__all__ = ("PollingPlugin",)
+
+
+class PollingPlugin(Plugin):
+    """Plugin that adds polling functionality to a Mersal application.
+
+    This plugin enables waiting for message processing completion through polling.
+    It registers handlers for MessageCompletedEvent and custom completion events,
+    and can automatically add completion event publishers for registered message types.
+    """
+
+    def __init__(self, config: PollingConfig) -> None:
+        """Initialize a new polling plugin.
+
+        Args:
+            config: The configuration for the polling plugin
+        """
+        self._poller = config.poller
+        self._successfull_completion_events_map = config.successful_completion_events_map
+        self._failed_completion_events_map = config.failed_completion_events_map
+        self._auto_publish_completion_events = config.auto_publish_completion_events
+        self._exclude_from_completion_events = config.exclude_from_completion_events
+
+    def __call__(self, configurator: StandardConfigurator) -> None:
+        """Configure the Mersal application with polling functionality.
+
+        Args:
+            configurator: The standard configurator for the application
+        """
+        # Configure event subscriptions for MessageCompletedEvent and other events
+        self._configure_event_subscriptions(configurator)
+
+        # Integrate with error handling
+        self._configure_error_handler(configurator)
+
+        # Register handlers for completion events
+        self._configure_completion_event_handlers(configurator)
+
+        # If auto-publish is enabled, register completion event publishers for all message types
+        if self._auto_publish_completion_events:
+            self._configure_auto_completion_event_publishing(configurator)
+
+    def _configure_event_subscriptions(self, configurator: StandardConfigurator) -> None:
+        """Configure event subscriptions for the polling plugin.
+
+        Args:
+            configurator: The standard configurator for the application
+        """
+
+        def decorate(configurator: StandardConfigurator) -> Any:
+            events_to_subscribe_to: list[type] = [
+                MessageCompletedEvent,
+            ]
+            lifespan_handler: LifespanHandler = configurator.get(LifespanHandler)  # type: ignore[type-abstract]
+            app: Mersal = configurator.mersal
+
+            # Add all custom completion events
+            for event in self._successfull_completion_events_map:
+                events_to_subscribe_to.append(event)
+            for event in self._failed_completion_events_map:
+                events_to_subscribe_to.append(event)
+
+            # Register a startup hook to subscribe to all events
+            lifespan_handler.register_on_startup_hook(self._subscribe(app, events_to_subscribe_to))  # type: ignore[arg-type]
+
+            return lifespan_handler
+
+        configurator.decorate(LifespanHandler, decorate)
+
+    def _configure_error_handler(self, configurator: StandardConfigurator) -> None:
+        """Configure error handling integration with polling.
+
+        Args:
+            configurator: The standard configurator for the application
+        """
+
+        def decorate_error_handler(configurator: StandardConfigurator) -> Any:
+            error_handler: ErrorHandler = configurator.get(ErrorHandler)  # type: ignore[type-abstract]
+            return ErrorHandlerPollerWrapper(self._poller, error_handler)
+
+        configurator.decorate(ErrorHandler, decorate_error_handler)
+
+    def _configure_completion_event_handlers(self, configurator: StandardConfigurator) -> None:
+        """Configure handlers for message completion events.
+
+        Args:
+            configurator: The standard configurator for the application
+        """
+
+        def decorate_activator(configurator: StandardConfigurator) -> Any:
+            activator: HandlerActivator = configurator.get(HandlerActivator)  # type: ignore[type-abstract]
+
+            # Register handler for MessageCompletedEvent
+            activator.register(
+                MessageCompletedEvent,
+                lambda __, _: self._message_completed_event_handler,
+            )
+
+            # Register handlers for custom success completion events
+            for (
+                event_type,
+                success_correlator,
+            ) in self._successfull_completion_events_map.items():
+                activator.register(
+                    event_type,
+                    lambda message_context,  # type: ignore[misc]
+                    _,
+                    sc=success_correlator: self._successfull_custom_completion_event_handler_factory(
+                        sc, message_context
+                    ),
+                )
+
+            # Register handlers for custom failure completion events
+            for (
+                event_type,
+                failure_correlator,
+            ) in self._failed_completion_events_map.items():
+                activator.register(
+                    event_type,
+                    lambda message_context,  # type: ignore[misc]
+                    _,
+                    fc=failure_correlator: self._failed_custom_completion_event_handler_factory(fc, message_context),
+                )
+
+            return activator
+
+        configurator.decorate(HandlerActivator, decorate_activator)
+
+    def _configure_auto_completion_event_publishing(self, configurator: StandardConfigurator) -> None:
+        """Configure automatic completion event publishing.
+
+        Args:
+            configurator: The standard configurator for the application
+        """
+
+        def decorate_activator(configurator: StandardConfigurator) -> Any:
+            activator: HandlerActivator = configurator.get(HandlerActivator)  # type: ignore[type-abstract]
+            register_message_completion_publishers(activator, self._exclude_from_completion_events)
+            return activator
+
+        configurator.decorate(HandlerActivator, decorate_activator)
+
+    async def _message_completed_event_handler(self, event: MessageCompletedEvent) -> None:
+        """Handle MessageCompletedEvent by updating the poller.
+
+        Args:
+            event: The message completed event
+        """
+        await self._poller.push(event.completed_message_id, None)
+
+    def _successfull_custom_completion_event_handler_factory(
+        self,
+        correlator: SuccessfulCompletionCorrelation,
+        message_context: MessageContext,
+    ) -> Callable[[Any], Awaitable[None]]:
+        """Create a handler for custom successful completion events.
+
+        Args:
+            correlator: The correlation configuration
+            message_context: The message context
+
+        Returns:
+            A handler function that processes the event
+        """
+
+        async def _custom_completion_event_handler(event: Any) -> None:
+            if message_id_getter := correlator.message_id_getter:
+                message_id = message_id_getter(event)
+            else:
+                message_id = message_context.headers.correlation_id
+            await self._poller.push(message_id, None)
+
+        return _custom_completion_event_handler
+
+    def _failed_custom_completion_event_handler_factory(
+        self, correlator: FailedCompletionCorrelation, message_context: MessageContext
+    ) -> Callable[[Any], Awaitable[None]]:
+        """Create a handler for custom failure completion events.
+
+        Args:
+            correlator: The correlation configuration
+            message_context: The message context
+
+        Returns:
+            A handler function that processes the event
+        """
+
+        async def _custom_completion_event_handler(event: Any) -> None:
+            if message_id_getter := correlator.message_id_getter:
+                message_id = message_id_getter(event)
+            else:
+                message_id = message_context.headers.correlation_id
+
+            if exception_builder := correlator.exception_builder:
+                exception = exception_builder(event)
+            else:
+                exception = Exception("Event error")
+            await self._poller.push(message_id, exception)
+
+        return _custom_completion_event_handler
+
+    def _subscribe(self, app: Mersal, events: list[type]) -> Callable[[list[type]], Awaitable[None]]:
+        """Create a function that subscribes to the given events.
+
+        Args:
+            app: The Mersal application
+            events: The list of event types to subscribe to
+
+        Returns:
+            A function that performs the subscriptions
+        """
+
+        async def subscribe(
+            events: list[type] = events,
+        ) -> None:
+            for e in events:
+                await app.subscribe(e)
+
+        return subscribe

mersal_polling/poller.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+__all__ = (
+    "Poller",
+    "PollingResult",
+)
+
+
+@dataclass
+class PollingResult:
+    message_id: Any
+    exception: Exception | None
+
+
+class Poller(Protocol):
+    async def poll(self, message_id: Any) -> PollingResult: ...
+
+    async def push(
+        self,
+        message_id: Any,
+        exception: Exception | None = None,
+    ) -> None: ...

mersal_polling/poller_with_timeout.py

@@ -0,0 +1,28 @@
+import uuid
+
+from anyio import fail_after
+
+from mersal.exceptions import MersalExceptionError
+
+from .poller import Poller, PollingResult
+
+__all__ = (
+    "PollerWithTimeout",
+    "PollingTimeoutError",
+)
+
+
+class PollingTimeoutError(MersalExceptionError):
+    pass
+
+
+class PollerWithTimeout:
+    def __init__(self, poller: Poller) -> None:
+        self._poller = poller
+
+    async def poll(self, message_id: uuid.UUID, timeout: float = 30) -> PollingResult:
+        try:
+            with fail_after(timeout):
+                return await self._poller.poll(message_id)
+        except TimeoutError as e:
+            raise PollingTimeoutError() from e

mersal_polling-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: mersal-polling
+Version: 0.1.0
+Summary: Add your description here
+Author-email: Abdulhaq Emhemmed <abdulhaq.emhemmed@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: mersal
+Description-Content-Type: text/markdown
+
+# mersal-polling
+
+Describe your project here.

mersal_polling-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mersal_polling/__init__.py,sha256=t-oEGj1muawyoI1cf-dOzEvHsjfRZQcZ3BtHDF_fdpY,559
+mersal_polling/config.py,sha256=nFosx1a3xlNd2u3TxCBxofYcmjEATCvDmw_9YH2JWDs,2311
+mersal_polling/default_poller.py,sha256=ZMcI4mUyooI9Tr-Dhfij9g_XPZJAd4PraRK031O4Bmk,1140
+mersal_polling/error_handler_poller_wrapper.py,sha256=I4CC_m9YCAI2gr1vHs4MIihPqAjEdsx1Z6EJO9Jj8Q4,759
+mersal_polling/message_completion_handler.py,sha256=l040OVm6_DTsbhJBvmMh0qa21ML4_MWZ0Oq9PmaA_6M,3344
+mersal_polling/plugin.py,sha256=j0rQIb3DZVl1Jsb4PB_BTvIwlsvc4FvCRUjAa56pLfI,9562
+mersal_polling/poller.py,sha256=2_JExVWr4_DTsLrQyqShb-vECcVyXJiv_QPVfxwrCPE,416
+mersal_polling/poller_with_timeout.py,sha256=Rxd-IJDBHT7dJRWp1TaQej-FcIaaEkxK9e940XarRGQ,648
+mersal_polling/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mersal_polling-0.1.0.dist-info/METADATA,sha256=f7VohAqhJ1nLB9iGZzBulaQNN2rtkHmmUfgo7k2MvDY,288
+mersal_polling-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mersal_polling-0.1.0.dist-info/RECORD,,

mersal_polling-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any