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

fastapi_factory_utilities/core/app/fastapi_builder.py

@@ -0,0 +1,85 @@
+"""Provides the FastAPIBuilder class."""
+
+from typing import Any, NamedTuple, Self
+
+from fastapi import APIRouter, FastAPI
+from fastapi.middleware import Middleware
+from fastapi.middleware.cors import CORSMiddleware
+
+from fastapi_factory_utilities.core.app.config import RootConfig
+
+
+class MiddlewareArgs(NamedTuple):
+    """Middleware arguments."""
+
+    middleware_class: type[Middleware]
+    kwargs: dict[str, Any]
+
+
+class FastAPIBuilder:
+    """FastAPI builder."""
+
+    def __init__(self, root_config: RootConfig) -> None:
+        """Instantiate the FastAPIBuilder."""
+        self._root_config: RootConfig = root_config
+        self._base_router: APIRouter = APIRouter()
+        self._middleware_list: list[MiddlewareArgs] = []
+
+    def add_api_router(self, router: APIRouter, without_resource_path: bool = False) -> Self:
+        """Add the API router to the FastAPI application.
+
+        Args:
+            router: The API router.
+            without_resource_path: If True, the resource path will not be added to the router.
+
+        Returns:
+            Self: The FastAPI builder.
+        """
+        self._base_router.include_router(
+            router=router, prefix=self._root_config.application.root_path if not without_resource_path else ""
+        )
+        return self
+
+    def add_middleware(self, middleware_class: type[Middleware], **kwargs: Any) -> Self:
+        """Add a middleware to the FastAPI application.
+
+        Args:
+            middleware_class: The middleware class.
+            *args: The middleware arguments.
+            **kwargs: The middleware keyword arguments.
+
+        Returns:
+            Self: The FastAPI builder.
+        """
+        self._middleware_list.append(MiddlewareArgs(middleware_class=middleware_class, kwargs=kwargs))
+        return self
+
+    def build(self, lifespan: Any) -> FastAPI:
+        """Build the FastAPI application.
+
+        Returns:
+            FastAPI: The FastAPI application.
+        """
+        fastapi = FastAPI(
+            title=self._root_config.application.service_name,
+            description="",
+            version=self._root_config.application.version,
+            lifespan=lifespan,  # type: ignore
+        )
+
+        fastapi.add_middleware(
+            middleware_class=CORSMiddleware,
+            allow_origins=self._root_config.cors.allow_origins,
+            allow_credentials=self._root_config.cors.allow_credentials,
+            allow_methods=self._root_config.cors.allow_methods,
+            allow_headers=self._root_config.cors.allow_headers,
+        )
+
+        for middleware_args in self._middleware_list:
+            fastapi.add_middleware(
+                middleware_class=middleware_args.middleware_class, **middleware_args.kwargs  # type: ignore
+            )
+
+        fastapi.include_router(router=self._base_router)
+
+        return fastapi

fastapi_factory_utilities/core/app/plugin_manager/__init__.py

@@ -0,0 +1,15 @@
+"""Provide PluginManager."""
+
+from .exceptions import (
+    InvalidPluginError,
+    PluginManagerError,
+    PluginPreConditionNotMetError,
+)
+from .plugin_manager import PluginManager
+
+__all__: list[str] = [
+    "PluginManager",
+    "PluginManagerError",
+    "InvalidPluginError",
+    "PluginPreConditionNotMetError",
+]

fastapi_factory_utilities/core/app/plugin_manager/exceptions.py

@@ -0,0 +1,33 @@
+"""Provide the exceptions for the plugin manager."""
+
+from fastapi_factory_utilities.core.exceptions import FastAPIFactoryUtilitiesError
+
+
+class PluginManagerError(FastAPIFactoryUtilitiesError):
+    """Generic plugin manager error."""
+
+
+class InvalidPluginError(PluginManagerError):
+    """The plugin is invalid."""
+
+    def __init__(self, plugin_name: str, message: str) -> None:
+        """Instantiate the exception.
+
+        Args:
+            plugin_name (str): The plugin name.
+            message (str): The message
+        """
+        super().__init__(message=f"Invalid plugin: {plugin_name}, {message}")
+
+
+class PluginPreConditionNotMetError(PluginManagerError):
+    """The plugin pre-condition is not met."""
+
+    def __init__(self, plugin_name: str, message: str) -> None:
+        """Instantiate the exception.
+
+        Args:
+            plugin_name (str): The plugin name.
+            message (str): The message
+        """
+        super().__init__(message=f"Plugin pre-condition not met: {plugin_name}, {message}")

fastapi_factory_utilities/core/app/plugin_manager/plugin_manager.py

@@ -0,0 +1,190 @@
+"""Plugin manager.
+
+This module provides the plugin manager for the application.
+
+Objective:
+    - Provide a way to manage plugins for the application.
+    - The plugins are activated based on the configuration.
+    - The plugins are checked for pre-conditions.
+    - The plugins are loaded on application load.
+    - The plugins are started on application startup.
+    - The plugins are stopped on application shutdown.
+"""
+
+from importlib import import_module
+from types import ModuleType
+from typing import Self
+
+from fastapi_factory_utilities.core.plugins import PluginsEnum, PluginState
+from fastapi_factory_utilities.core.protocols import (
+    ApplicationAbstractProtocol,
+    PluginProtocol,
+)
+
+from .exceptions import InvalidPluginError, PluginPreConditionNotMetError
+
+
+class PluginManager:
+    """Plugin manager for the application."""
+
+    DEFAULT_PLUGIN_PACKAGE: str = "fastapi_factory_utilities.core.plugins"
+
+    @classmethod
+    def _import_module(cls, name: str, package: str) -> ModuleType:
+        """Import the module. This is a wrapper around the import_module function to be able to mock it in the tests.
+
+        Args:
+            name (str): The name of the module.
+            package (str): The package of the module.
+
+        Returns:
+            ModuleType: The module.
+
+        Raises:
+            ImportError: If the module cannot be imported.
+            ModuleNotFoundError: If the module is not found.
+        """
+        return import_module(name=f"{package}.{name}")
+
+    @classmethod
+    def _check_pre_conditions(
+        cls, plugin_package: str, want_to_activate_plugins: list[PluginsEnum], application: ApplicationAbstractProtocol
+    ) -> list[PluginProtocol]:
+        """Check the pre-conditions for the plugins.
+
+        Args:
+            plugin_package (str): The package for the plugins.
+            want_to_activate_plugins (list[PluginsEnum]): The plugins to activate.
+            application (BaseApplicationProtocol): The application.
+
+        Returns:
+            list[PluginProtocol]: The activated plugins.
+
+        Raises:
+            InvalidPluginError: If the plugin is invalid.
+            PluginPreConditionNotMetError: If the pre-conditions are not met.
+        """
+        plugins: list[PluginProtocol] = []
+
+        for plugin_enum in want_to_activate_plugins:
+
+            try:
+                # Using a custom import function to be able to mock it in the tests.
+                plugin_module: ModuleType = cls._import_module(name=plugin_enum.value, package=plugin_package)
+            except (ImportError, ModuleNotFoundError) as import_error:
+                # TODO: Later, if we introduce extra mecanism to manage dependencies,
+                # we must handle a part of the error here. To be able to provide a better error message.
+                # For now, we just raise the error.
+                raise InvalidPluginError(
+                    plugin_name=plugin_enum.value, message="Error importing the plugin "
+                ) from import_error
+
+            if not isinstance(plugin_module, PluginProtocol):
+                raise InvalidPluginError(
+                    plugin_name=plugin_enum.value, message="The plugin does not implement the PluginProtocol"
+                )
+
+            if not plugin_module.pre_conditions_check(application=application):
+                raise PluginPreConditionNotMetError(
+                    plugin_name=plugin_enum.value, message="The pre-conditions are not met"
+                )
+
+            plugins.append(plugin_module)
+
+        return plugins
+
+    def __init__(self, activated: list[PluginsEnum] | None = None, plugin_package: str | None = None) -> None:
+        """Instanciate the plugin manager."""
+        self._plugin_package: str = plugin_package or self.DEFAULT_PLUGIN_PACKAGE
+        self._plugins_wanted_to_be_activated: list[PluginsEnum] = activated or []
+        self._activated_plugins: list[PluginProtocol] = []
+        self._states: list[PluginState] = []
+
+    def activate(self, plugin: PluginsEnum) -> Self:
+        """Activate a plugin.
+
+        Args:
+            plugin (PluginsEnum): The plugin to activate.
+
+        Returns:
+            Self: The plugin manager.
+        """
+        self._plugins_wanted_to_be_activated.append(plugin)
+
+        return self
+
+    @property
+    def states(self) -> list[PluginState]:
+        """Get the states."""
+        return self._states
+
+    def add_application_context(self, application: ApplicationAbstractProtocol) -> Self:
+        """Add the application context to the plugins.
+
+        Args:
+            application (BaseApplicationProtocol): The application.
+
+        Returns:
+            Self: The plugin manager.
+        """
+        self._application: ApplicationAbstractProtocol = application
+
+        return self
+
+    def add_states(self, states: list[PluginState]) -> Self:
+        """Add the states to the plugin manager.
+
+        Args:
+            states (list[PluginState]): The states.
+
+        Returns:
+            Self: The plugin manager.
+        """
+        for state in states:
+            self._states.append(state)
+        return self
+
+    def clear_states(self) -> Self:
+        """Clear the states."""
+        self._states = []
+        return self
+
+    def load(self) -> Self:
+        """Load the plugins.
+
+        Returns:
+            Self: The plugin manager.
+
+        Raises:
+            InvalidPluginError: If the plugin is invalid.
+            PluginPreConditionNotMetError: If the pre-conditions are not met.
+
+        """
+        # Remove duplicates.
+        self._plugins_wanted_to_be_activated = list(set(self._plugins_wanted_to_be_activated))
+        # Check the pre-conditions for the plugins.
+        self._activated_plugins = self._check_pre_conditions(
+            plugin_package=self._plugin_package,
+            want_to_activate_plugins=self._plugins_wanted_to_be_activated,
+            application=self._application,
+        )
+        # Load from the previous check.
+        for plugin in self._activated_plugins:
+            self.add_states(states=plugin.on_load(application=self._application) or [])
+
+        return self
+
+    async def trigger_startup(self) -> Self:
+        """Trigger the startup of the plugins."""
+        for plugin in self._activated_plugins:
+            states: list[PluginState] | None = await plugin.on_startup(application=self._application)
+            self.add_states(states=states or [])
+
+        return self
+
+    async def trigger_shutdown(self) -> Self:
+        """Trigger the shutdown of the plugins."""
+        for plugin in self._activated_plugins:
+            await plugin.on_shutdown(application=self._application)
+
+        return self

fastapi_factory_utilities/core/exceptions.py

@@ -0,0 +1,43 @@
+"""FastAPI Factory Utilities exceptions."""
+
+import logging
+from typing import Any
+
+from opentelemetry.trace import Span, get_current_span
+from structlog.stdlib import BoundLogger, get_logger
+
+_logger: BoundLogger = get_logger()
+
+
+class FastAPIFactoryUtilitiesError(Exception):
+    """Base exception for the FastAPI Factory Utilities."""
+
+    def __init__(
+        self,
+        *args: tuple[Any],
+        message: str | None = None,
+        level: int = logging.ERROR,
+        **kwargs: dict[str, Any],
+    ) -> None:
+        """Instanciate the exception.
+
+        Args:
+            *args (Tuple[Any]): The arguments.
+            message (str | None): The message.
+            level (int): The logging level.
+            **kwargs (dict[str, Any]): The keyword arguments
+        """
+        # Log the Exception
+        if message:
+            _logger.log(level=level, event=message)
+            self.message = message
+            self.level = level
+            args = (message, *args)  # type: ignore
+        # Propagate the exception
+        span: Span = get_current_span()
+        # If not otel is setup, INVALID_SPAN is retrive from get_current_span
+        # and it will respond False to the is_recording method
+        if span.is_recording():
+            span.record_exception(self)
+        # Call the parent class
+        super().__init__(*args, **kwargs)

fastapi_factory_utilities/core/plugins/__init__.py

@@ -1,6 +1,7 @@
 """Package for plugins."""
 
 from enum import StrEnum, auto
+from typing import Any
 
 
 class PluginsEnum(StrEnum):
@@ -8,6 +9,26 @@ class PluginsEnum(StrEnum):
 
     OPENTELEMETRY_PLUGIN = auto()
     ODM_PLUGIN = auto()
+    HTTPX_PLUGIN = auto()
+
+
+class PluginState:
+    """PluginState represent the state a plugin which to be share to the application and other plugins."""
+
+    def __init__(self, key: str, value: Any) -> None:
+        """Initialize the PluginState."""
+        self._key: str = key
+        self._value = value
+
+    @property
+    def key(self) -> str:
+        """Get the key."""
+        return self._key
+
+    @property
+    def value(self) -> Any:
+        """Get the value."""
+        return self._value
 
 
 __all__: list[str] = [

fastapi_factory_utilities/core/plugins/example/__init__.py

@@ -0,0 +1,31 @@
+"""Example Plugin Module."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi_factory_utilities.core.plugins import PluginState
+    from fastapi_factory_utilities.core.protocols import ApplicationAbstractProtocol
+
+
+def pre_conditions_check(application: "ApplicationAbstractProtocol") -> bool:  # pylint: disable=unused-argument
+    """Check the pre-conditions for the example plugin."""
+    return True
+
+
+def on_load(
+    application: "ApplicationAbstractProtocol",  # pylint: disable=unused-argument
+) -> list["PluginState"] | None:
+    """Actions to perform on load for the example plugin."""
+    return
+
+
+async def on_startup(
+    application: "ApplicationAbstractProtocol",  # pylint: disable=unused-argument
+) -> list["PluginState"] | None:
+    """Actions to perform on startup for the example plugin."""
+    return
+
+
+async def on_shutdown(application: "ApplicationAbstractProtocol") -> None:  # pylint: disable=unused-argument
+    """Actions to perform on shutdown for the example plugin."""
+    return

fastapi_factory_utilities/core/plugins/httpx_plugin/__init__.py

@@ -0,0 +1,31 @@
+"""Httpx Plugin Module."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi_factory_utilities.core.plugins import PluginState
+    from fastapi_factory_utilities.core.protocols import ApplicationAbstractProtocol
+
+
+def pre_conditions_check(application: "ApplicationAbstractProtocol") -> bool:  # pylint: disable=unused-argument
+    """Check the pre-conditions for the example plugin."""
+    return True
+
+
+def on_load(
+    application: "ApplicationAbstractProtocol",  # pylint: disable=unused-argument
+) -> list["PluginState"] | None:
+    """Actions to perform on load for the example plugin."""
+    return
+
+
+async def on_startup(
+    application: "ApplicationAbstractProtocol",  # pylint: disable=unused-argument
+) -> list["PluginState"] | None:
+    """Actions to perform on startup for the example plugin."""
+    return
+
+
+async def on_shutdown(application: "ApplicationAbstractProtocol") -> None:  # pylint: disable=unused-argument
+    """Actions to perform on shutdown for the example plugin."""
+    return

fastapi_factory_utilities/core/plugins/odm_plugin/__init__.py

@@ -5,16 +5,28 @@ from typing import Any
 
 from beanie import init_beanie  # pyright: ignore[reportUnknownVariableType]
 from motor.motor_asyncio import AsyncIOMotorClient
+from reactivex import Subject
 from structlog.stdlib import BoundLogger, get_logger
 
-from fastapi_factory_utilities.core.protocols import BaseApplicationProtocol
+from fastapi_factory_utilities.core.plugins import PluginState
+from fastapi_factory_utilities.core.protocols import ApplicationAbstractProtocol
+from fastapi_factory_utilities.core.services.status.enums import (
+    ComponentTypeEnum,
+    HealthStatusEnum,
+    ReadinessStatusEnum,
+)
+from fastapi_factory_utilities.core.services.status.services import StatusService
+from fastapi_factory_utilities.core.services.status.types import (
+    ComponentInstanceType,
+    Status,
+)
 
 from .builder import ODMBuilder
 
 _logger: BoundLogger = get_logger()
 
 
-def pre_conditions_check(application: BaseApplicationProtocol) -> bool:
+def pre_conditions_check(application: ApplicationAbstractProtocol) -> bool:
     """Check the pre-conditions for the OpenTelemetry plugin.
 
     Args:
@@ -28,8 +40,8 @@ def pre_conditions_check(application: BaseApplicationProtocol) -> bool:
 
 
 def on_load(
-    application: BaseApplicationProtocol,
-) -> None:
+    application: ApplicationAbstractProtocol,
+) -> list["PluginState"] | None:
     """Actions to perform on load for the OpenTelemetry plugin.
 
     Args:
@@ -43,8 +55,8 @@ def on_load(
 
 
 async def on_startup(
-    application: BaseApplicationProtocol,
-) -> None:
+    application: ApplicationAbstractProtocol,
+) -> list["PluginState"] | None:
     """Actions to perform on startup for the ODM plugin.
 
     Args:
@@ -54,36 +66,77 @@ async def on_startup(
     Returns:
         None
     """
+    states: list[PluginState] = []
+
+    status_service: StatusService = application.get_status_service()
+    component_instance: ComponentInstanceType = ComponentInstanceType(
+        component_type=ComponentTypeEnum.DATABASE, identifier="MongoDB"
+    )
+    monitoring_subject: Subject[Status] = status_service.register_component_instance(
+        component_instance=component_instance
+    )
+
     try:
         odm_factory: ODMBuilder = ODMBuilder(application=application).build_all()
     except Exception as exception:  # pylint: disable=broad-except
         _logger.error(f"ODM plugin failed to start. {exception}")
-        return
+        # TODO: Report the error to the status_service
+        # this will report the application as unhealthy
+        monitoring_subject.on_next(
+            value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
+        )
+        return states
 
     if odm_factory.odm_database is None or odm_factory.odm_client is None:
         _logger.error(
             f"ODM plugin failed to start. Database: {odm_factory.odm_database} - " f"Client: {odm_factory.odm_client}"
         )
-        return
-    # TODO: Find a way to add type to the state
-    application.get_asgi_app().state.odm_client = odm_factory.odm_client
-    application.get_asgi_app().state.odm_database = odm_factory.odm_database
+        # TODO: Report the error to the status_service
+        # this will report the application as unhealthy
+        monitoring_subject.on_next(
+            value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
+        )
+        return states
 
-    # TODO: Find a better way to initialize beanie with the document models of the concrete application
-    # through an hook in the application ?
-    await init_beanie(
-        database=odm_factory.odm_database,
-        document_models=application.ODM_DOCUMENT_MODELS,
+    # Add the ODM client and database to the application state
+    states.append(
+        PluginState(key="odm_client", value=odm_factory.odm_client),
+    )
+    states.append(
+        PluginState(
+            key="odm_database",
+            value=odm_factory.odm_database,
+        ),
     )
 
+    # TODO: Find a better way to initialize beanie with the document models of the concrete application
+    # through an hook in the application, a dynamis import ?
+    try:
+        await init_beanie(
+            database=odm_factory.odm_database,
+            document_models=application.ODM_DOCUMENT_MODELS,
+        )
+    except Exception as exception:  # pylint: disable=broad-except
+        _logger.error(f"ODM plugin failed to start. {exception}")
+        # TODO: Report the error to the status_service
+        # this will report the application as unhealthy
+        monitoring_subject.on_next(
+            value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
+        )
+        return states
+
     _logger.info(
         f"ODM plugin started. Database: {odm_factory.odm_database.name} - "
         f"Client: {odm_factory.odm_client.address} - "
         f"Document models: {application.ODM_DOCUMENT_MODELS}"
     )
 
+    monitoring_subject.on_next(value=Status(health=HealthStatusEnum.HEALTHY, readiness=ReadinessStatusEnum.READY))
+
+    return states
+
 
-async def on_shutdown(application: BaseApplicationProtocol) -> None:
+async def on_shutdown(application: ApplicationAbstractProtocol) -> None:
     """Actions to perform on shutdown for the ODM plugin.
 
     Args:
@@ -92,6 +145,10 @@ async def on_shutdown(application: BaseApplicationProtocol) -> None:
     Returns:
         None
     """
+    # Skip if the ODM plugin was not started correctly
+    if not hasattr(application.get_asgi_app().state, "odm_client"):
+        return
+
     client: AsyncIOMotorClient[Any] = application.get_asgi_app().state.odm_client
     client.close()
     _logger.debug("ODM plugin shutdown.")