fastapi-factory-utilities 0.3.6__py3-none-any.whl → 0.9.1__py3-none-any.whl

fastapi_factory_utilities/core/plugins/taskiq_plugins/schedulers.py

@@ -0,0 +1,187 @@
+"""Scheduler module for fastapi_factory_utilities.
+
+This module provides components and utilities for scheduling tasks using Taskiq, FastAPI, and Redis.
+It enables registration, configuration, and management of scheduled tasks in FastAPI applications.
+"""
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any, Self, cast
+
+import taskiq_fastapi
+from fastapi import FastAPI
+from structlog.stdlib import get_logger
+from taskiq import (
+    AsyncBroker,
+    AsyncTaskiqDecoratedTask,
+    ScheduleSource,
+    TaskiqScheduler,
+)
+from taskiq.api import run_receiver_task, run_scheduler_task
+from taskiq.scheduler.created_schedule import CreatedSchedule
+from taskiq.scheduler.scheduled_task import ScheduledTask
+from taskiq_redis import (
+    ListRedisScheduleSource,
+    RedisAsyncResultBackend,
+    RedisStreamBroker,
+)
+
+_logger = get_logger(__package__)
+
+
+class SchedulerComponent:
+    """Scheduler component."""
+
+    NAME_SUFFIX: str = "tiktok_integration"
+
+    def __init__(self) -> None:
+        """Initialize the scheduler component."""
+        self._result_backend: RedisAsyncResultBackend[Any] | None = None
+        self._stream_broker: RedisStreamBroker | None = None
+        self._scheduler: TaskiqScheduler | None = None
+        self._scheduler_source: ListRedisScheduleSource | None = None
+        self._dyn_task: AsyncTaskiqDecoratedTask[Any, Any] | None = None
+        self._schedule_cron: ScheduledTask | None = None
+        self._schedulers_tasks: dict[str, AsyncTaskiqDecoratedTask[Any, Any]] = {}
+
+    def register_task(self, task: Coroutine[Any, Any, Any], task_name: str) -> None:
+        """Register a task.
+
+        Args:
+            task: The task to register.
+            task_name: The name of the task.
+
+        Raises:
+            ValueError: If the task is already registered.
+            ValueError: If the stream broker is not initialized.
+        """
+        if self._stream_broker is None:
+            raise ValueError("Stream broker is not initialized")
+
+        if task_name in self._schedulers_tasks:
+            raise ValueError(f"Task {task_name} already registered")
+
+        self._schedulers_tasks[task_name] = self._stream_broker.register_task(task, task_name)  # type: ignore
+
+    def get_task(self, task_name: str) -> AsyncTaskiqDecoratedTask[Any, Any]:
+        """Get a task.
+
+        Args:
+            task_name: The name of the task.
+
+        Returns:
+            AsyncTaskiqDecoratedTask: The task.
+
+        Raises:
+            ValueError: If the task is not registered.
+        """
+        if task_name not in self._schedulers_tasks:
+            raise ValueError(f"Task {task_name} not registered")
+        return self._schedulers_tasks[task_name]
+
+    def configure(self, redis_connection_string: str, app: FastAPI) -> Self:
+        """Configure the scheduler component."""
+        self._result_backend = RedisAsyncResultBackend(
+            redis_url=redis_connection_string,
+            prefix_str=f"velmios_taskiq_result_backend_{self.NAME_SUFFIX}",
+            result_ex_time=120,
+        )
+        self._stream_broker = RedisStreamBroker(
+            url=redis_connection_string,
+            queue_name=f"velmios_taskiq_stream_broker_{self.NAME_SUFFIX}",
+            consumer_group_name=f"velmios_taskiq_consumer_group_{self.NAME_SUFFIX}",
+        ).with_result_backend(self._result_backend)
+
+        taskiq_fastapi.populate_dependency_context(self._stream_broker, app)
+
+        self._scheduler_source = ListRedisScheduleSource(
+            url=redis_connection_string,
+            prefix=f"velmios_taskiq_schedule_source_{self.NAME_SUFFIX}",
+        )
+
+        self._scheduler = TaskiqScheduler(
+            broker=self._stream_broker,
+            sources=[self._scheduler_source],
+        )
+
+        return self
+
+    async def startup(self, app: FastAPI) -> None:
+        """Start the scheduler."""
+        if self._result_backend is None:
+            raise ValueError("Result backend is not initialized")
+        if self._stream_broker is None:
+            raise ValueError("Stream broker is not initialized")
+        if self._scheduler is None:
+            raise ValueError("Scheduler is not initialized")
+        if self._scheduler_source is None:
+            raise ValueError("Scheduler source is not initialized")
+
+        _logger.info("Starting scheduler")
+        await self._result_backend.startup()
+        await self._stream_broker.startup()
+        await self._scheduler.startup()
+        _logger.info("Scheduler started")
+        _logger.info("Scheduling task")
+        schedules: list[ScheduledTask] = await self._scheduler_source.get_schedules()
+        _logger.info("Schedules retrieved", schedules=schedules)
+
+        self._schedule_cron = next(filter(lambda x: x.task_name == "heartbeat", schedules), None)
+
+        if self._schedule_cron is None:
+            _logger.info("No schedules found, scheduling task")
+            self._dyn_task = self.get_task("heartbeat")
+            task_created: CreatedSchedule[Any] = await self._dyn_task.schedule_by_cron(
+                source=self._scheduler_source, cron="* * * * *", msg="every minute"
+            )
+            self._schedule_cron = task_created.task
+            _logger.info("Task scheduled")
+        else:
+            _logger.info("Schedules found, skipping scheduling")
+
+        _logger.info("Starting worker and scheduler tasks")
+        taskiq_fastapi.populate_dependency_context(self._stream_broker, app, app.state)  # type: ignore
+        self._worker_task: asyncio.Task[None] = asyncio.create_task(run_receiver_task(self._stream_broker))
+        self._scheduler_task: asyncio.Task[None] = asyncio.create_task(run_scheduler_task(self._scheduler))
+        _logger.info("Worker and scheduler tasks started")
+
+    async def shutdown(self) -> None:
+        """Stop the scheduler."""
+        _logger.info("Stopping worker")
+        self._worker_task.cancel()
+        self._scheduler_task.cancel()
+        try:
+            await self._worker_task
+        except (asyncio.CancelledError, RuntimeError) as e:
+            _logger.info("Worker task cancelled", error=e)
+        try:
+            await self._scheduler_task
+        except (asyncio.CancelledError, RuntimeError) as e:
+            _logger.info("Scheduler task cancelled", error=e)
+
+        while not self._worker_task.done() or not self._scheduler_task.done():
+            await asyncio.sleep(0.1)
+
+        _logger.info("Stopping scheduler")
+        if self._scheduler is not None:
+            await self._scheduler.shutdown()
+        if self._stream_broker is not None:
+            await self._stream_broker.shutdown()
+        if self._result_backend is not None:
+            await self._result_backend.shutdown()
+        _logger.info("Scheduler stopped")
+
+    @property
+    def scheduler(self) -> TaskiqScheduler:
+        """Get the scheduler."""
+        return cast(TaskiqScheduler, self._scheduler)
+
+    @property
+    def broker(self) -> AsyncBroker:
+        """Get the broker."""
+        return cast(AsyncBroker, self._stream_broker)
+
+    @property
+    def scheduler_source(self) -> ScheduleSource:
+        """Get the scheduler source."""
+        return cast(ScheduleSource, self._scheduler_source)

fastapi_factory_utilities/core/protocols.py

@@ -1,17 +1,15 @@
 """Protocols for the base application."""
 
 from abc import abstractmethod
-from typing import TYPE_CHECKING, ClassVar, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, ClassVar, Protocol
 
 from beanie import Document
 from fastapi import FastAPI
 
-from fastapi_factory_utilities.core.plugins import PluginsEnum
 from fastapi_factory_utilities.core.services.status.services import StatusService
 
 if TYPE_CHECKING:
     from fastapi_factory_utilities.core.app.config import RootConfig
-    from fastapi_factory_utilities.core.plugins import PluginState
 
 
 class ApplicationAbstractProtocol(Protocol):
@@ -21,8 +19,6 @@ class ApplicationAbstractProtocol(Protocol):
 
     ODM_DOCUMENT_MODELS: ClassVar[list[type[Document]]]
 
-    DEFAULT_PLUGINS_ACTIVATED: ClassVar[list[PluginsEnum]]
-
     @abstractmethod
     def get_config(self) -> "RootConfig":
         """Get the application configuration."""
@@ -34,52 +30,3 @@ class ApplicationAbstractProtocol(Protocol):
     @abstractmethod
     def get_status_service(self) -> StatusService:
         """Get the status service."""
-
-
-@runtime_checkable
-class PluginProtocol(Protocol):
-    """Defines the protocol for the plugins."""
-
-    @abstractmethod
-    def pre_conditions_check(self, application: ApplicationAbstractProtocol) -> bool:
-        """Check the pre-conditions for the plugin.
-
-        Args:
-            application (BaseApplicationProtocol): The application.
-
-        Returns:
-            bool: True if the pre-conditions are met, False otherwise.
-        """
-
-    @abstractmethod
-    def on_load(self, application: ApplicationAbstractProtocol) -> list["PluginState"] | None:
-        """The actions to perform on load for the plugin.
-
-        Args:
-            application (BaseApplicationProtocol): The application.
-
-        Returns:
-            None
-        """
-
-    @abstractmethod
-    async def on_startup(self, application: ApplicationAbstractProtocol) -> list["PluginState"] | None:
-        """The actions to perform on startup for the plugin.
-
-        Args:
-            application (BaseApplicationProtocol): The application.
-
-        Returns:
-            None
-        """
-
-    @abstractmethod
-    async def on_shutdown(self, application: ApplicationAbstractProtocol) -> None:
-        """The actions to perform on shutdown for the plugin.
-
-        Args:
-            application (BaseApplicationProtocol): The application.
-
-        Returns:
-            None
-        """

fastapi_factory_utilities/core/security/__init__.py

@@ -0,0 +1,5 @@
+"""Security module."""
+
+from .abstracts import AuthenticationAbstract
+
+__all__: list[str] = ["AuthenticationAbstract"]

fastapi_factory_utilities/core/security/abstracts.py

@@ -0,0 +1,42 @@
+"""Provides the security authentication abstract classes."""
+
+from abc import ABC, abstractmethod
+
+from fastapi import Request
+
+
+class AuthenticationAbstract(ABC):
+    """Authentication abstract class."""
+
+    def __init__(self, raise_exception: bool = True) -> None:
+        """Initialize the authentication abstract class.
+
+        Args:
+            raise_exception (bool): Whether to raise an exception or return None.
+        """
+        self._raise_exception: bool = raise_exception
+        self._errors: list[Exception] = []
+
+    def has_errors(self) -> bool:
+        """Check if the authentication has errors.
+
+        Returns:
+            bool: True if the authentication has errors, False otherwise.
+        """
+        return len(self._errors) > 0
+
+    def raise_exception(self, exception: Exception) -> None:
+        """Raise the exception if the authentication has errors.
+
+        Args:
+            exception (Exception): The exception to raise.
+        """
+        if self._raise_exception:
+            raise exception
+        else:
+            self._errors.append(exception)
+
+    @abstractmethod
+    async def authenticate(self, request: Request) -> None:
+        """Authenticate the request."""
+        raise NotImplementedError()

fastapi_factory_utilities/core/security/jwt/__init__.py

@@ -0,0 +1,43 @@
+"""Provides security-related functions for the API."""
+
+from .configs import JWTBearerAuthenticationConfig
+from .decoders import JWTBearerTokenDecoder, JWTBearerTokenDecoderAbstract, decode_jwt_token_payload
+from .exceptions import (
+    InvalidJWTError,
+    InvalidJWTPayploadError,
+    JWTAuthenticationError,
+    MissingJWTCredentialsError,
+    NotVerifiedJWTError,
+)
+from .objects import JWTPayload
+from .services import (
+    JWTAuthenticationService,
+    JWTAuthenticationServiceAbstract,
+)
+from .stores import JWKStoreAbstract, JWKStoreMemory
+from .types import JWTToken, OAuth2Audience, OAuth2Issuer, OAuth2Scope, OAuth2Subject
+from .verifiers import JWTNoneVerifier, JWTVerifierAbstract
+
+__all__: list[str] = [
+    "InvalidJWTError",
+    "InvalidJWTPayploadError",
+    "JWKStoreAbstract",
+    "JWKStoreMemory",
+    "JWTAuthenticationError",
+    "JWTAuthenticationService",
+    "JWTAuthenticationServiceAbstract",
+    "JWTBearerAuthenticationConfig",
+    "JWTBearerTokenDecoder",
+    "JWTBearerTokenDecoderAbstract",
+    "JWTNoneVerifier",
+    "JWTPayload",
+    "JWTToken",
+    "JWTVerifierAbstract",
+    "MissingJWTCredentialsError",
+    "NotVerifiedJWTError",
+    "OAuth2Audience",
+    "OAuth2Issuer",
+    "OAuth2Scope",
+    "OAuth2Subject",
+    "decode_jwt_token_payload",
+]

fastapi_factory_utilities/core/security/jwt/configs.py

@@ -0,0 +1,32 @@
+"""Provides the configurations for the JWT bearer token."""
+
+from typing import ClassVar
+
+from jwt.algorithms import get_default_algorithms, requires_cryptography
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class JWTBearerAuthenticationConfig(BaseModel):
+    """JWT bearer token authentication configuration."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True, extra="forbid")
+
+    authorized_algorithms: list[str] = Field(
+        default_factory=lambda: list(get_default_algorithms().keys()), description="The authorized algorithms."
+    )
+
+    audience: str = Field(description="The audience to be included in the JWT token.")
+    authorized_audiences: list[str] | None = Field(default=None, description="The authorized audiences.")
+    authorized_issuers: list[str] | None = Field(default=None, description="The authorized issuers.")
+
+    @field_validator("authorized_algorithms")
+    @classmethod
+    def validate_authorized_algorithms(cls, v: list[str]) -> list[str]:
+        """Validate the authorized algorithms."""
+        invalid_algorithms: list[str] = []
+        for algorithm in v:
+            if algorithm not in requires_cryptography:
+                invalid_algorithms.append(algorithm)
+        if invalid_algorithms:
+            raise ValueError(f"Invalid algorithms: {invalid_algorithms}")
+        return v

fastapi_factory_utilities/core/security/jwt/decoders.py

@@ -0,0 +1,130 @@
+"""Provides the JWT bearer token decoders.
+
+Can be implemented to support different JWT bearer token formats or additional claims.
+https://www.iana.org/assignments/jwt/jwt.xhtml#claims
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from jwt import InvalidTokenError, decode, get_unverified_header
+from jwt.api_jwk import PyJWK
+from pydantic import ValidationError
+
+from .configs import JWTBearerAuthenticationConfig
+from .exceptions import InvalidJWTError, InvalidJWTPayploadError
+from .objects import JWTPayload
+from .stores import JWKStoreAbstract
+from .types import JWTToken, OAuth2Subject
+
+JWTBearerPayloadGeneric = TypeVar("JWTBearerPayloadGeneric", bound=JWTPayload)
+
+
+async def decode_jwt_token_payload(
+    jwt_token: JWTToken,
+    public_key: PyJWK,
+    jwt_bearer_authentication_config: JWTBearerAuthenticationConfig,
+    subject: OAuth2Subject | None = None,
+) -> dict[str, Any]:
+    """Decode the JWT bearer token payload.
+
+    Args:
+        jwt_token (JWTToken): The JWT bearer token.
+        public_key (PyJWK): The public key.
+        jwt_bearer_authentication_config (JWTBearerAuthenticationConfig): The JWT bearer authentication configuration.
+        subject (OAuth2Subject | None): The subject.
+
+    Returns:
+        dict[str, Any]: The decoded JWT bearer token payload.
+
+    Raises:
+        JWTBearerTokenDecoderError: If the JWT bearer token is invalid.
+    """
+    # Additional kwargs for the decode function
+    kwargs: dict[str, Any] = {}
+    if jwt_bearer_authentication_config.authorized_issuers:
+        kwargs["issuer"] = jwt_bearer_authentication_config.authorized_issuers
+    if jwt_bearer_authentication_config.authorized_audiences:
+        kwargs["audience"] = jwt_bearer_authentication_config.authorized_audiences
+    if subject:
+        kwargs["subject"] = subject
+    # Decode the JWT bearer token payload
+    try:
+        return decode(
+            jwt=jwt_token,
+            key=public_key,
+            algorithms=jwt_bearer_authentication_config.authorized_algorithms,
+            options={"verify_signature": True},
+            **kwargs,
+        )
+    except InvalidTokenError as e:
+        raise InvalidJWTError("Failed to decode the JWT bearer token payload") from e
+
+
+class JWTBearerTokenDecoderAbstract(ABC, Generic[JWTBearerPayloadGeneric]):
+    """JWT bearer token decoder."""
+
+    def get_kid_from_jwt_unsafe_header(self, jwt_token: JWTToken) -> str:
+        """Get the kid from the JWT header.
+
+        Args:
+            jwt_token (JWTToken): The JWT bearer token.
+
+        Returns:
+            str: The kid.
+        """
+        try:
+            jwt_unsafe_headers: dict[str, Any] = get_unverified_header(jwt_token)
+            return jwt_unsafe_headers["kid"]
+        except (KeyError, InvalidTokenError) as e:
+            raise InvalidJWTError("Failed to get the kid from the JWT header") from e
+
+    @abstractmethod
+    async def decode_payload(self, jwt_token: JWTToken) -> JWTBearerPayloadGeneric:
+        """Decode the JWT bearer token payload.
+
+        Args:
+            jwt_token (JWTToken): The JWT bearer token.
+
+        Returns:
+            JWTBearerPayloadGeneric: The decoded JWT bearer token payload.
+
+        Raises:
+            InvalidJWTError: If the JWT bearer token is invalid.
+            InvalidJWTPayploadError: If the JWT bearer token payload is invalid.
+        """
+        raise NotImplementedError()
+
+
+class JWTBearerTokenDecoder(JWTBearerTokenDecoderAbstract[JWTPayload]):
+    """JWT bearer token classic decoder."""
+
+    def __init__(
+        self, jwt_bearer_authentication_config: JWTBearerAuthenticationConfig, jwks_store: JWKStoreAbstract
+    ) -> None:
+        """Initialize the JWT bearer token classic decoder.
+
+        Args:
+            jwt_bearer_authentication_config (JWTBearerAuthenticationConfig): The JWT bearer authentication
+            configuration.
+            jwks_store (JWKStoreAbstract): The JWKS store.
+        """
+        self._jwt_bearer_authentication_config: JWTBearerAuthenticationConfig = jwt_bearer_authentication_config
+        self._jwks_store: JWKStoreAbstract = jwks_store
+
+    async def decode_payload(self, jwt_token: JWTToken) -> JWTPayload:
+        """Decode the JWT bearer token."""
+        # Get the kid from the JWT header
+        kid: str = self.get_kid_from_jwt_unsafe_header(jwt_token=jwt_token)
+        # Get the JWK from the JWKS store
+        jwk: PyJWK = await self._jwks_store.get_jwk(kid=kid)
+        # Decode the JWT bearer token payload
+        jwt_decoded: dict[str, Any] = await decode_jwt_token_payload(
+            jwt_token=jwt_token,
+            public_key=jwk,
+            jwt_bearer_authentication_config=self._jwt_bearer_authentication_config,
+        )
+        try:
+            return JWTPayload.model_validate(jwt_decoded)
+        except ValidationError as e:
+            raise InvalidJWTPayploadError("Failed to validate the JWT bearer token payload") from e

fastapi_factory_utilities/core/security/jwt/exceptions.py

@@ -0,0 +1,23 @@
+"""Provides the exceptions for the JWT authentication."""
+
+from fastapi_factory_utilities.core.exceptions import FastAPIFactoryUtilitiesError
+
+
+class JWTAuthenticationError(FastAPIFactoryUtilitiesError):
+    """JWT authentication error."""
+
+
+class MissingJWTCredentialsError(JWTAuthenticationError):
+    """Missing JWT authentication credentials error."""
+
+
+class InvalidJWTError(JWTAuthenticationError):
+    """Invalid JWT authentication credentials error."""
+
+
+class InvalidJWTPayploadError(JWTAuthenticationError):
+    """Invalid JWT payload error."""
+
+
+class NotVerifiedJWTError(JWTAuthenticationError):
+    """Not verified JWT error."""

fastapi_factory_utilities/core/security/jwt/objects.py

@@ -0,0 +1,107 @@
+"""Provides the JWT bearer token objects."""
+
+import datetime
+from typing import Annotated, Any, ClassVar
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+from .types import OAuth2Audience, OAuth2Issuer, OAuth2Scope, OAuth2Subject
+
+
+def validate_string_list_field(value: Any) -> list[str]:
+    """Validate a string list field.
+
+    Accepts either a space-separated string or a list of strings.
+    Converts all values to lowercase strings.
+
+    Args:
+        value: Either a string (space-separated) or a list of strings.
+
+    Returns:
+        A list of lowercase strings.
+
+    Raises:
+        ValueError: If the value is not a string or list, or if the resulting list is empty.
+    """
+    cleaned_value: list[str]
+    if isinstance(value, str):
+        cleaned_value = value.split(sep=" ")
+    elif isinstance(value, list):
+        cleaned_value = [str(item) for item in value if item is not None]
+    else:
+        raise ValueError(f"Invalid value type: expected str or list, got {type(value).__name__}")
+    cleaned_value = [item.lower() for item in cleaned_value if item.strip()]
+    if len(cleaned_value) == 0:
+        raise ValueError("Invalid value: empty list after processing")
+    return cleaned_value
+
+
+def validate_timestamp_field(value: Any) -> datetime.datetime:
+    """Validate a timestamp field.
+
+    Accepts either a Unix timestamp (int or string) or a datetime object.
+    Converts timestamps to UTC datetime objects.
+
+    Args:
+        value: Either a Unix timestamp (int or string) or a datetime object.
+
+    Returns:
+        A datetime object in UTC timezone.
+
+    Raises:
+        ValueError: If the value cannot be converted to a datetime.
+    """
+    if isinstance(value, datetime.datetime):
+        return value
+    if isinstance(value, str):
+        try:
+            value = int(value)
+        except ValueError as e:
+            raise ValueError(f"Invalid timestamp string: {value}") from e
+    if isinstance(value, int):
+        try:
+            return datetime.datetime.fromtimestamp(value, tz=datetime.UTC)
+        except (ValueError, OSError) as e:
+            raise ValueError(f"Invalid timestamp value: {value}") from e
+    raise ValueError(f"Invalid value type: expected int, str, or datetime, got {type(value).__name__}")
+
+
+class JWTPayload(BaseModel):
+    """JWT bearer token payload.
+
+    Represents a decoded JWT bearer token with OAuth2 claims.
+    All fields are required and validated according to OAuth2/JWT standards.
+
+    Attributes:
+        scope: List of OAuth2 scopes granted by the token.
+        aud: List of audiences (intended recipients) of the token.
+        iss: The issuer of the JWT token.
+        exp: The expiration date/time of the JWT token (UTC).
+        iat: The issued at date/time of the JWT token (UTC).
+        nbf: The not before date/time of the JWT token (UTC).
+        sub: The subject (user identifier) of the JWT token.
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="ignore",
+        frozen=True,
+    )
+
+    scope: Annotated[list[OAuth2Scope], BeforeValidator(validate_string_list_field)] = Field(
+        description="The scope of the JWT token."
+    )
+    aud: Annotated[list[OAuth2Audience], BeforeValidator(validate_string_list_field)] = Field(
+        description="The audiences of the JWT token."
+    )
+    iss: OAuth2Issuer = Field(description="The issuer of the JWT token.")
+    exp: Annotated[datetime.datetime, BeforeValidator(validate_timestamp_field)] = Field(
+        description="The expiration date of the JWT token."
+    )
+    iat: Annotated[datetime.datetime, BeforeValidator(validate_timestamp_field)] = Field(
+        description="The issued at date of the JWT token."
+    )
+    nbf: Annotated[datetime.datetime, BeforeValidator(validate_timestamp_field)] = Field(
+        description="The not before date of the JWT token."
+    )
+    sub: OAuth2Subject = Field(description="The subject of the JWT token.")