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

fastapi_factory_utilities/core/exceptions.py

@@ -1,8 +1,7 @@
 """FastAPI Factory Utilities exceptions."""
 
 import logging
-from collections.abc import Sequence
-from typing import NotRequired, TypedDict, Unpack
+from typing import Any, cast
 
 from opentelemetry.trace import Span, get_current_span
 from opentelemetry.util.types import AttributeValue
@@ -11,42 +10,49 @@ from structlog.stdlib import BoundLogger, get_logger
 _logger: BoundLogger = get_logger()
 
 
-class ExceptionParameters(TypedDict):
-    """Parameters for the exception."""
-
-    message: NotRequired[str]
-    level: NotRequired[int]
-
-
 class FastAPIFactoryUtilitiesError(Exception):
     """Base exception for the FastAPI Factory Utilities."""
 
+    FILTERED_ATTRIBUTES: tuple[str, ...] = ()
+    DEFAULT_LOGGING_LEVEL: int = logging.ERROR
+    DEFAULT_MESSAGE: str | None = None
+
     def __init__(
         self,
         *args: object,
-        **kwargs: Unpack[ExceptionParameters],
+        **kwargs: Any,
     ) -> None:
         """Instantiate the exception.
 
         Args:
             *args: The arguments.
-            message: The message.
-            level: The logging level.
             **kwargs: The keyword arguments.
 
         """
+        # If Default Message is not set, try to extract it from docstring (first line)
+        default_message: str = self.DEFAULT_MESSAGE or "An error occurred"
+        if self.DEFAULT_MESSAGE is None and self.__doc__ is not None:
+            default_message = self.__doc__.split("\n", maxsplit=1)[0]
         # Extract the message and the level from the kwargs if they are present
-        self.message: str | None = kwargs.pop("message", None)
-        self.level: int = kwargs.pop("level", logging.ERROR)
+        self.message: str | None = cast(str | None, kwargs.pop("message", None))
+        self.level: int = cast(int, kwargs.pop("level", self.DEFAULT_LOGGING_LEVEL))
 
         # If the message is not present, try to extract it from the args
         if self.message is None and len(args) > 0 and isinstance(args[0], str):
             self.message = args[0]
+        elif self.message is None:
+            self.message = default_message
 
         # Log the Exception
         if self.message:
             _logger.log(level=self.level, event=self.message)
 
+        # Set the kwargs as attributes of the exception
+        for key, value in kwargs.items():
+            if key in self.FILTERED_ATTRIBUTES:
+                continue
+            setattr(self, key, value)
+
         try:
             # Propagate the exception
             span: Span = get_current_span()
@@ -55,8 +61,10 @@ class FastAPIFactoryUtilitiesError(Exception):
             if span.is_recording():
                 span.record_exception(self)
                 for key, value in kwargs.items():
+                    if key in self.FILTERED_ATTRIBUTES:
+                        continue
                     attribute_value: AttributeValue
-                    if not isinstance(value, (str, bool, int, float, Sequence)):
+                    if not isinstance(value, (str, bool, int, float)):
                         attribute_value = str(value)
                     else:
                         attribute_value = value

fastapi_factory_utilities/core/plugins/aiopika/exchange.py

@@ -2,9 +2,7 @@
 
 from typing import ClassVar, Self
 
-from aio_pika import Exchange as AiopikaExchange
-from aio_pika import ExchangeType
-from aio_pika.abc import TimeoutType
+from aio_pika.abc import AbstractExchange, ExchangeType, TimeoutType
 
 from .abstract import AbstractAiopikaResource
 from .exceptions import AiopikaPluginBaseError, AiopikaPluginExchangeNotDeclaredError
@@ -34,11 +32,11 @@ class Exchange(AbstractAiopikaResource):
         self._internal: bool = internal
         self._passive: bool = passive
         self._timeout: TimeoutType = timeout
-        self._aiopika_exchange: AiopikaExchange | None = None
+        self._aiopika_exchange: AbstractExchange | None = None
         self._is_declared: bool = False
 
     @property
-    def exchange(self) -> AiopikaExchange:
+    def exchange(self) -> AbstractExchange:
         """Get the Aiopika exchange."""
         if self._aiopika_exchange is None:
             raise AiopikaPluginExchangeNotDeclaredError(message="Exchange not declared.", exchange=self._name)
@@ -46,6 +44,7 @@ class Exchange(AbstractAiopikaResource):
 
     async def _declare(self) -> Self:
         """Declare the exchange."""
+        assert self._channel is not None
         try:
             self._aiopika_exchange = await self._channel.declare_exchange(  # pyright: ignore
                 name=self._name,

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

@@ -4,8 +4,7 @@ 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 aio_pika.abc import AbstractIncomingMessage, ConsumerTag, TimeoutType
 
 from ..abstract import AbstractAiopikaResource
 from ..message import AbstractMessage
@@ -36,12 +35,13 @@ class AbstractListener(AbstractAiopikaResource, Generic[GenericMessage]):
 
     async def listen(self) -> None:
         """Listen for messages."""
+        assert self._queue.queue is not None
         self._consumer_tag = await self._queue.queue.consume(  # pyright: ignore
-            callback=cast(Callable[[IncomingMessage], Awaitable[Any]], self._on_message),  # pyright: ignore
+            callback=cast(Callable[[AbstractIncomingMessage], Awaitable[Any]], self._on_message),  # pyright: ignore
             exclusive=True,
         )
 
-    async def _on_message(self, incoming_message: IncomingMessage) -> None:
+    async def _on_message(self, incoming_message: AbstractIncomingMessage) -> None:
         """On message."""
         message: GenericMessage = self._message_type.model_validate_json(incoming_message.body)
         message.set_incoming_message(incoming_message=incoming_message)

fastapi_factory_utilities/core/plugins/aiopika/message.py

@@ -3,8 +3,8 @@
 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 aio_pika.abc import AbstractIncomingMessage, DeliveryMode, HeadersType
+from aio_pika.message import Message
 from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
 
 GenericMessageData = TypeVar("GenericMessageData", bound=BaseModel)
@@ -35,7 +35,7 @@ class AbstractMessage(BaseModel, Generic[GenericMessageData]):
     sender: SenderModel = Field(description="The sender of the message.")
     data: GenericMessageData = Field(description="The data of the message.")
 
-    _incoming_message: IncomingMessage | None = PrivateAttr()
+    _incoming_message: AbstractIncomingMessage | None = PrivateAttr()
     _headers: HeadersType = PrivateAttr(default_factory=dict)
 
     def get_headers(self) -> HeadersType:
@@ -46,7 +46,7 @@ class AbstractMessage(BaseModel, Generic[GenericMessageData]):
         """Set the headers of the message."""
         self._headers = headers
 
-    def set_incoming_message(self, incoming_message: IncomingMessage) -> None:
+    def set_incoming_message(self, incoming_message: AbstractIncomingMessage) -> None:
         """Set the incoming message."""
         self._incoming_message = incoming_message
         self.set_headers(headers=incoming_message.headers)

fastapi_factory_utilities/core/plugins/aiopika/queue.py

@@ -49,6 +49,7 @@ class Queue(AbstractAiopikaResource):
 
     async def _declare(self) -> Self:
         """Declare the queue."""
+        assert self._channel is not None
         try:
             self._queue = await self._channel.declare_queue(  # pyright: ignore
                 name=self._name,
@@ -65,6 +66,7 @@ class Queue(AbstractAiopikaResource):
 
     async def _bind(self) -> Self:
         """Bind the queue to the exchange."""
+        assert self._queue is not None
         try:
             await self._queue.bind(  # pyright: ignore
                 exchange=self._exchange.exchange,

fastapi_factory_utilities/core/plugins/taskiq_plugins/__init__.py

@@ -2,12 +2,14 @@
 
 from importlib.util import find_spec
 
+from .configs import RedisCredentialsConfig
 from .depends import depends_scheduler_component
 from .exceptions import TaskiqPluginBaseError
 from .plugin import TaskiqPlugin
 from .schedulers import SchedulerComponent
 
 __all__: list[str] = [  # pylint: disable=invalid-name
+    "RedisCredentialsConfig",
     "SchedulerComponent",
     "TaskiqPlugin",
     "TaskiqPluginBaseError",

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,45 @@
+"""Provides security-related functions for the API."""
+
+from .configs import JWTBearerAuthenticationConfig
+from .decoders import (
+    JWTBearerTokenDecoder,
+    JWTBearerTokenDecoderAbstract,
+)
+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",
+]

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.")