fastapi-factory-utilities 0.2.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

fastapi_factory_utilities/core/plugins/aiopika/configs.py

@@ -0,0 +1,85 @@
+"""Provides the configuration for the Aiopika plugin."""
+
+from typing import Annotated, Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field, UrlConstraints
+from pydantic_core import Url, ValidationError
+
+from fastapi_factory_utilities.core.utils.importlib import get_path_file_in_package
+from fastapi_factory_utilities.core.utils.yaml_reader import (
+    UnableToReadYamlFileError,
+    YamlFileReader,
+)
+
+from .exceptions import AiopikaPluginConfigError
+
+
+class AiopikaConfig(BaseModel):
+    """Provides the configuration model for the Aiopika plugin.
+
+    https://docs.aio-pika.com/#aio-pika-connect-robust-function-and-aio-pika-robustconnection-class-specific
+
+    Possible query parameters for the AMQP URL:
+        name (str url encoded) - A string that will be visible in the RabbitMQ management console
+        and in the server logs, convenient for diagnostics.
+        cafile (str) - Path to Certificate Authority file
+        capath (str) - Path to Certificate Authority directory
+        cadata (str url encoded) - URL encoded CA certificate content
+        keyfile (str) - Path to client ssl private key file
+        certfile (str) - Path to client ssl certificate file
+        no_verify_ssl - No verify server SSL certificates. 0 by default and means False other value means True.
+        heartbeat (int-like) - interval in seconds between AMQP heartbeat packets. 0 disables this feature.
+        reconnect_interval (float-like) - is the period in seconds, not more often than the attempts
+        to re-establish the connection will take place.
+        fail_fast (true/yes/y/enable/on/enabled/1 means True, otherwise False) - special behavior
+        for the start connection attempt, if it fails, all other attempts stops
+        and an exception will be thrown at the connection stage. Enabled by default, if you are sure you need
+        to disable this feature, be ensures for the passed URL is really working.
+        Otherwise, your program will go into endless reconnection attempts that can not be successed.
+
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True, extra="forbid")
+
+    amqp_url: Annotated[Url, UrlConstraints(allowed_schemes=["amqp", "amqps"])] = Field(description="The AMQP URL.")
+
+
+def build_config_from_package(package_name: str) -> AiopikaConfig:
+    """Build the configuration from the package.
+
+    Args:
+        package_name (str): The package name.
+
+    Returns:
+        AiopikaConfig: The Aiopika configuration.
+
+    Raises:
+        AiopikaPluginConfigError: If the configuration cannot be read or created or the configuration is invalid.
+    """
+    try:
+        yaml_file_content: dict[str, Any] = YamlFileReader(
+            file_path=get_path_file_in_package(
+                filename="application.yaml",
+                package=package_name,
+            ),
+            yaml_base_key="aiopika",
+            use_environment_injection=True,
+        ).read()
+    except (FileNotFoundError, ImportError, UnableToReadYamlFileError) as exception:
+        raise AiopikaPluginConfigError(
+            message="Unable to read the application configuration file for the Aiopika plugin in the package.",
+            package_name=package_name,
+        ) from exception
+
+    # Create the application configuration model
+    config: AiopikaConfig
+    try:
+        config = AiopikaConfig(**yaml_file_content)
+    except ValidationError as exception:
+        raise AiopikaPluginConfigError(
+            message="Unable to create the application configuration model for the Aiopika plugin in the package.",
+            package_name=package_name,
+            validation_errors=exception.errors(),
+        ) from exception
+
+    return config

fastapi_factory_utilities/core/plugins/aiopika/depends.py

@@ -0,0 +1,20 @@
+"""Provides the dependencies for the Aiopika plugin."""
+
+from typing import cast
+
+from aio_pika.abc import AbstractRobustConnection
+from fastapi import Request
+
+from .exceptions import AiopikaPluginBaseError
+
+DEPENDS_AIOPIKA_ROBUST_CONNECTION_KEY: str = "aiopika_robust_connection"
+
+
+def depends_aiopika_robust_connection(request: Request) -> AbstractRobustConnection:
+    """Get the Aiopika robust connection."""
+    robust_connection: AbstractRobustConnection | None = cast(
+        AbstractRobustConnection | None, getattr(request.app.state, DEPENDS_AIOPIKA_ROBUST_CONNECTION_KEY, None)
+    )
+    if robust_connection is None:
+        raise AiopikaPluginBaseError("Aiopika robust connection not found in the application state.")
+    return robust_connection

fastapi_factory_utilities/core/plugins/aiopika/exceptions.py

@@ -0,0 +1,29 @@
+"""Provides the exceptions for the Aiopika plugin."""
+
+from typing import Any
+
+from fastapi_factory_utilities.core.exceptions import FastAPIFactoryUtilitiesError
+
+
+class AiopikaPluginBaseError(FastAPIFactoryUtilitiesError):
+    """Base class for all exceptions raised by the Aiopika plugin."""
+
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        """Initialize the Aiopika plugin base exception."""
+        super().__init__(message, **kwargs)
+
+
+class AiopikaPluginConfigError(AiopikaPluginBaseError):
+    """Exception for the Aiopika plugin configuration."""
+
+
+class AiopikaPluginConnectionNotProvidedError(AiopikaPluginBaseError):
+    """Exception for the Aiopika plugin connection not provided."""
+
+
+class AiopikaPluginExchangeNotDeclaredError(AiopikaPluginBaseError):
+    """Exception for the Aiopika plugin exchange not declared."""
+
+
+class AiopikaPluginQueueNotDeclaredError(AiopikaPluginBaseError):
+    """Exception for the Aiopika plugin queue not declared."""

fastapi_factory_utilities/core/plugins/aiopika/exchange.py

@@ -0,0 +1,70 @@
+"""Provides the abstract class for the exchange port for the Aiopika plugin."""
+
+from typing import ClassVar, Self
+
+from aio_pika import Exchange as AiopikaExchange
+from aio_pika import ExchangeType
+from aio_pika.abc import TimeoutType
+
+from .abstract import AbstractAiopikaResource
+from .exceptions import AiopikaPluginBaseError, AiopikaPluginExchangeNotDeclaredError
+
+
+class Exchange(AbstractAiopikaResource):
+    """Abstract class for the exchange port for the Aiopika plugin."""
+
+    DEFAULT_OPERATION_TIMEOUT: ClassVar[TimeoutType] = 10.0
+
+    def __init__(  # pylint: disable=too-many-arguments # noqa: PLR0913
+        self,
+        name: str,
+        exchange_type: ExchangeType,
+        durable: bool = True,
+        auto_delete: bool = False,
+        internal: bool = False,
+        passive: bool = False,
+        timeout: TimeoutType = DEFAULT_OPERATION_TIMEOUT,
+    ) -> None:
+        """Initialize the exchange port."""
+        super().__init__()
+        self._name: str = name
+        self._exchange_type: ExchangeType = exchange_type
+        self._durable: bool = durable
+        self._auto_delete: bool = auto_delete
+        self._internal: bool = internal
+        self._passive: bool = passive
+        self._timeout: TimeoutType = timeout
+        self._aiopika_exchange: AiopikaExchange | None = None
+        self._is_declared: bool = False
+
+    @property
+    def exchange(self) -> AiopikaExchange:
+        """Get the Aiopika exchange."""
+        if self._aiopika_exchange is None:
+            raise AiopikaPluginExchangeNotDeclaredError(message="Exchange not declared.", exchange=self._name)
+        return self._aiopika_exchange
+
+    async def _declare(self) -> Self:
+        """Declare the exchange."""
+        try:
+            self._aiopika_exchange = await self._channel.declare_exchange(  # pyright: ignore
+                name=self._name,
+                type=self._exchange_type,
+                durable=self._durable,
+                auto_delete=self._auto_delete,
+                internal=self._internal,
+                passive=self._passive,
+                timeout=self._timeout,
+            )
+        except Exception as exception:
+            raise AiopikaPluginBaseError(
+                message="Failed to declare the exchange.",
+            ) from exception
+        return self
+
+    async def setup(self) -> Self:
+        """Setup the exchange."""
+        await super().setup()
+        if self._aiopika_exchange is None:
+            await self._declare()
+        return self

fastapi_factory_utilities/core/plugins/aiopika/listener/__init__.py

@@ -0,0 +1,7 @@
+"""Provides the listener ports for the Aiopika plugin."""
+
+from .abstract import AbstractListener
+
+__all__: list[str] = [
+    "AbstractListener",
+]

fastapi_factory_utilities/core/plugins/aiopika/listener/abstract.py

@@ -0,0 +1,72 @@
+"""Provides the abstract class for the listener port for the Aiopika plugin."""
+
+from abc import abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import Any, ClassVar, Generic, Self, TypeVar, cast, get_args
+
+from aio_pika.abc import ConsumerTag, TimeoutType
+from aio_pika.message import IncomingMessage
+
+from ..abstract import AbstractAiopikaResource
+from ..message import AbstractMessage
+from ..queue import Queue
+
+GenericMessage = TypeVar("GenericMessage", bound=AbstractMessage[Any])
+
+
+class AbstractListener(AbstractAiopikaResource, Generic[GenericMessage]):
+    """Abstract class for the listener port for the Aiopika plugin."""
+
+    DEFAULT_OPERATION_TIMEOUT: ClassVar[TimeoutType] = 10.0
+
+    def __init__(self, queue: Queue, name: str | None = None) -> None:
+        """Initialize the listener port."""
+        super().__init__()
+        self._name: str = name or self.__class__.__name__
+        self._queue: Queue = queue
+        self._consumer_tag: ConsumerTag | None = None
+        generic_args: tuple[Any, ...] = get_args(self.__orig_bases__[0])  # type: ignore
+        self._message_type: type[GenericMessage] = generic_args[0]
+
+    async def setup(self) -> Self:
+        """Setup the listener."""
+        await super().setup()
+        await self._queue.setup()
+        return self
+
+    async def listen(self) -> None:
+        """Listen for messages."""
+        self._consumer_tag = await self._queue.queue.consume(  # pyright: ignore
+            callback=cast(Callable[[IncomingMessage], Awaitable[Any]], self._on_message),  # pyright: ignore
+            exclusive=True,
+        )
+
+    async def _on_message(self, incoming_message: IncomingMessage) -> None:
+        """On message."""
+        message: GenericMessage = self._message_type.model_validate_json(incoming_message.body)
+        message.set_incoming_message(incoming_message=incoming_message)
+        await self.on_message(message=message)
+
+    async def close(self) -> None:
+        """Close the listener.
+
+        Returns:
+            - None: The listener is closed.
+
+        Raises:
+            - AiopikaPluginBaseException: If the listener cannot be closed.
+        """
+        if self._consumer_tag is not None:
+            await self._queue.queue.cancel(consumer_tag=self._consumer_tag)
+
+    @abstractmethod
+    async def on_message(self, message: GenericMessage) -> None:
+        """On message.
+
+        Args:
+            message (GenericMessage): The message.
+
+        Returns:
+            - None: The message is processed.
+        """
+        raise NotImplementedError

fastapi_factory_utilities/core/plugins/aiopika/message.py

@@ -0,0 +1,86 @@
+"""Provides the message for the Aiopika plugin."""
+
+from enum import StrEnum, auto
+from typing import ClassVar, Generic, TypeVar
+
+from aio_pika.abc import DeliveryMode, HeadersType
+from aio_pika.message import IncomingMessage, Message
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+
+GenericMessageData = TypeVar("GenericMessageData", bound=BaseModel)
+
+
+class SenderModel(BaseModel):
+    """Sender model."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(description="The name of the sender.")
+
+
+class MessageTypeEnum(StrEnum):
+    """Message type enum."""
+
+    FUNCTIONAL_EVENT = auto()
+
+
+class AbstractMessage(BaseModel, Generic[GenericMessageData]):
+    """Abstract message."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", frozen=True)
+
+    message_type: MessageTypeEnum = Field(
+        description="The type of the message.", default=MessageTypeEnum.FUNCTIONAL_EVENT
+    )
+    sender: SenderModel = Field(description="The sender of the message.")
+    data: GenericMessageData = Field(description="The data of the message.")
+
+    _incoming_message: IncomingMessage | None = PrivateAttr()
+    _headers: HeadersType = PrivateAttr(default_factory=dict)
+
+    def get_headers(self) -> HeadersType:
+        """Get the headers of the message."""
+        return self._headers
+
+    def set_headers(self, headers: HeadersType) -> None:
+        """Set the headers of the message."""
+        self._headers = headers
+
+    def set_incoming_message(self, incoming_message: IncomingMessage) -> None:
+        """Set the incoming message."""
+        self._incoming_message = incoming_message
+        self.set_headers(headers=incoming_message.headers)
+
+    async def ack(self) -> None:
+        """Ack the message.
+
+        Raises:
+            - ValueError: If the incoming message is not set.
+        """
+        if self._incoming_message is None:
+            raise ValueError("Incoming message is not set.")
+        await self._incoming_message.ack(multiple=False)
+
+    async def reject(self, requeue: bool = True) -> None:
+        """Reject the message.
+
+        Args:
+            requeue (bool): Whether to requeue the message.
+
+        Raises:
+            - ValueError: If the incoming message is not set.
+        """
+        if self._incoming_message is None:
+            raise ValueError("Incoming message is not set.")
+        await self._incoming_message.reject(requeue=requeue)
+
+    def to_aiopika_message(self) -> Message:
+        """Convert the message to an Aiopika message."""
+        return Message(
+            body=self.model_dump_json().encode("utf-8"),
+            headers=self.get_headers(),
+            content_type="application/json",
+            content_encoding="utf-8",
+            delivery_mode=DeliveryMode.PERSISTENT,
+            priority=0,
+        )

fastapi_factory_utilities/core/plugins/aiopika/plugins.py

@@ -0,0 +1,84 @@
+"""Provides the Aiopika plugin."""
+
+from typing import cast
+
+from aio_pika import connect_robust  # pyright: ignore[reportUnknownMemberType]
+from aio_pika.abc import AbstractRobustConnection
+from fastapi import Request
+from opentelemetry.instrumentation.aio_pika import AioPikaInstrumentor  # pyright: ignore[reportMissingTypeStubs]
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.trace import TracerProvider
+from structlog.stdlib import BoundLogger, get_logger
+
+from fastapi_factory_utilities.core.plugins.abstracts import PluginAbstract
+
+from .configs import AiopikaConfig, build_config_from_package
+from .depends import DEPENDS_AIOPIKA_ROBUST_CONNECTION_KEY
+from .exceptions import AiopikaPluginBaseError
+
+_logger: BoundLogger = get_logger(__package__)
+
+
+class AiopikaPlugin(PluginAbstract):
+    """Aiopika plugin."""
+
+    def __init__(self, aiopika_config: AiopikaConfig | None = None) -> None:
+        """Initialize the Aiopika plugin."""
+        super().__init__()
+        self._aiopika_config: AiopikaConfig | None = aiopika_config
+        self._robust_connection: AbstractRobustConnection | None = None
+
+    @property
+    def robust_connection(self) -> AbstractRobustConnection:
+        """Get the robust connection."""
+        assert self._robust_connection is not None
+        return self._robust_connection
+
+    def on_load(self) -> None:
+        """On load."""
+        assert self._application is not None
+
+        # Build the configuration if not provided
+        if self._aiopika_config is None:
+            self._aiopika_config = build_config_from_package(package_name=self._application.PACKAGE_NAME)
+
+    async def on_startup(self) -> None:
+        """On startup."""
+        assert self._application is not None
+        assert self._aiopika_config is not None
+
+        tracer_provider: TracerProvider | None = cast(
+            TracerProvider | None, getattr(self._application.get_asgi_app().state, "tracer_provider", None)
+        )
+        meter_provider: MeterProvider | None = cast(
+            MeterProvider | None, getattr(self._application.get_asgi_app().state, "meter_provider", None)
+        )
+        if tracer_provider is None or meter_provider is None:
+            raise AiopikaPluginBaseError("Tracer provider or meter provider not found in the application state.")
+
+        AioPikaInstrumentor().instrument(
+            tracer_provider=tracer_provider,
+            meter_provider=meter_provider,
+        )
+
+        self._robust_connection = await connect_robust(url=str(self._aiopika_config.amqp_url))
+        self._add_to_state(key=DEPENDS_AIOPIKA_ROBUST_CONNECTION_KEY, value=self._robust_connection)
+        _logger.debug("Aiopika plugin connected to the AMQP server.", amqp_url=self._aiopika_config.amqp_url)
+
+    async def on_shutdown(self) -> None:
+        """On shutdown."""
+        if self._robust_connection is not None:
+            await self._robust_connection.close()
+        _logger.debug("Aiopika plugin shutdown.")
+
+
+def depends_robust_connection(request: Request) -> AbstractRobustConnection:
+    """Depends on the robust connection.
+
+    Args:
+        request (Request): The request.
+
+    Returns:
+        AbstractRobustConnection: The robust connection.
+    """
+    return request.app.state.robust_connection

fastapi_factory_utilities/core/plugins/aiopika/publisher/__init__.py

@@ -0,0 +1,7 @@
+"""Provides the publisher ports for the Aiopika plugin."""
+
+from .abstract import AbstractPublisher
+
+__all__: list[str] = [
+    "AbstractPublisher",
+]

fastapi_factory_utilities/core/plugins/aiopika/publisher/abstract.py

@@ -0,0 +1,66 @@
+"""Provides the abstract class for the publisher port for the Aiopika plugin."""
+
+from typing import Any, ClassVar, Generic, Self, TypeVar
+
+from aio_pika.abc import TimeoutType
+from aio_pika.message import Message
+from aiormq.abc import ConfirmationFrameType, DeliveredMessage
+from pamqp.commands import Basic
+
+from ..abstract import AbstractAiopikaResource
+from ..exceptions import AiopikaPluginBaseError
+from ..exchange import Exchange
+from ..message import AbstractMessage
+
+GenericMessage = TypeVar("GenericMessage", bound=AbstractMessage[Any])
+
+
+class AbstractPublisher(AbstractAiopikaResource, Generic[GenericMessage]):
+    """Abstract class for the publisher port for the Aiopika plugin."""
+
+    DEFAULT_OPERATION_TIMEOUT: ClassVar[TimeoutType] = 10.0
+
+    def __init__(self, exchange: Exchange, name: str | None = None) -> None:
+        """Initialize the publisher port."""
+        super().__init__()
+        self._name: str = name or self.__class__.__name__
+        self._exchange: Exchange = exchange
+
+    async def setup(self) -> Self:
+        """Setup the publisher."""
+        await super().setup()
+        await self._exchange.setup()
+        return self
+
+    async def publish(self, message: GenericMessage, routing_key: str) -> None:
+        """Publish a message."""
+        # Transform the message to an Aiopika message
+        aiopika_message: Message
+        try:
+            aiopika_message = message.to_aiopika_message()
+        except Exception as exception:
+            raise AiopikaPluginBaseError(
+                message="Failed to convert the message to an Aiopika message.",
+            ) from exception
+        # Publish the message
+        confirmation: ConfirmationFrameType | DeliveredMessage | None
+        try:
+            confirmation = await self._exchange.exchange.publish(  # pyright: ignore
+                message=aiopika_message,
+                routing_key=routing_key,
+                mandatory=True,
+                timeout=self.DEFAULT_OPERATION_TIMEOUT,
+            )
+        except Exception as exception:
+            raise AiopikaPluginBaseError(
+                message="Failed to publish the message.",
+            ) from exception
+
+        if confirmation is None:
+            raise AiopikaPluginBaseError(
+                message="Failed to publish the message.",
+            )
+        if isinstance(confirmation, Basic.Return):
+            raise AiopikaPluginBaseError(
+                message="Failed to publish the message.",
+            )

fastapi_factory_utilities/core/plugins/aiopika/queue.py

@@ -0,0 +1,86 @@
+"""Provides the queue for the Aiopika plugin."""
+
+from typing import ClassVar, Self
+
+from aio_pika.abc import AbstractQueue, TimeoutType
+
+from .abstract import AbstractAiopikaResource
+from .exceptions import AiopikaPluginBaseError, AiopikaPluginQueueNotDeclaredError
+from .exchange import Exchange
+
+
+class Queue(AbstractAiopikaResource):
+    """Queue."""
+
+    DEFAULT_OPERATION_TIMEOUT: ClassVar[TimeoutType] = 10.0
+
+    def __init__(  # pylint: disable=too-many-arguments # noqa: PLR0913
+        self,
+        name: str,
+        exchange: Exchange,
+        routing_key: str,
+        durable: bool = True,
+        auto_delete: bool = False,
+        exclusive: bool = True,
+        timeout: TimeoutType = DEFAULT_OPERATION_TIMEOUT,
+    ) -> None:
+        """Initialize the queue."""
+        super().__init__()
+        # Initialize the queue properties
+        self._name: str = name
+        self._routing_key: str = routing_key
+        self._durable: bool = durable
+        self._auto_delete: bool = auto_delete
+        self._exclusive: bool = exclusive
+        self._timeout: TimeoutType = timeout
+        # Behavior properties
+        self._exchange: Exchange = exchange
+        self._queue: AbstractQueue | None = None
+
+    @property
+    def queue(self) -> AbstractQueue:
+        """Get the Aiopika queue."""
+        if self._queue is None:
+            raise AiopikaPluginQueueNotDeclaredError(
+                message="Queue not declared.",
+                queue=self._name,
+            )
+        return self._queue
+
+    async def _declare(self) -> Self:
+        """Declare the queue."""
+        try:
+            self._queue = await self._channel.declare_queue(  # pyright: ignore
+                name=self._name,
+                durable=self._durable,
+                auto_delete=self._auto_delete,
+                exclusive=self._exclusive,
+                timeout=self._timeout,
+            )
+        except Exception as exception:
+            raise AiopikaPluginBaseError(
+                message="Failed to declare the queue.",
+            ) from exception
+        return self
+
+    async def _bind(self) -> Self:
+        """Bind the queue to the exchange."""
+        try:
+            await self._queue.bind(  # pyright: ignore
+                exchange=self._exchange.exchange,
+                routing_key=self._routing_key,
+                timeout=self._timeout,
+            )
+        except Exception as exception:
+            raise AiopikaPluginBaseError(
+                message="Failed to bind the queue to the exchange.",
+            ) from exception
+        return self
+
+    async def setup(self) -> Self:
+        """Setup the queue."""
+        await super().setup()
+        if self._queue is None:
+            await self._declare()
+        await self._bind()
+        return self