tempest-fastapi-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

{tempest_fastapi_sdk-0.2.0 → tempest_fastapi_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk

{tempest_fastapi_sdk-0.2.0 → tempest_fastapi_sdk-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.2.0 → tempest_fastapi_sdk-0.3.0}/tempest_fastapi_sdk/__init__.py

@@ -1,8 +1,20 @@
 """tempest-fastapi-sdk — shared FastAPI/SQLAlchemy/Pydantic primitives."""
 
 from tempest_fastapi_sdk.api import (
+    RequestIDMiddleware,
     app_exception_handler,
+    make_token_dependency,
     register_exception_handlers,
+    require_x_token,
+)
+from tempest_fastapi_sdk.controllers import BaseController
+from tempest_fastapi_sdk.core import (
+    JSONFormatter,
+    clear_request_id,
+    configure_logging,
+    get_request_id,
+    request_id_ctx,
+    set_request_id,
 )
 from tempest_fastapi_sdk.db import (
     NAMING_CONVENTION,
@@ -29,6 +41,7 @@ from tempest_fastapi_sdk.schemas import (
     BaseResponseSchema,
     BaseSchema,
 )
+from tempest_fastapi_sdk.services import BaseService
 from tempest_fastapi_sdk.settings import BaseAppSettings
 from tempest_fastapi_sdk.utils import (
     CNPJ,
@@ -57,7 +70,7 @@ from tempest_fastapi_sdk.utils import (
     utcnow,
 )
 
-__version__: str = "0.2.0"
+__version__: str = "0.3.0"
 
 __all__: list[str] = [
     "CNPJ",
@@ -71,12 +84,14 @@ __all__: list[str] = [
     "AppException",
     "AsyncDatabaseManager",
     "BaseAppSettings",
+    "BaseController",
     "BaseModel",
     "BasePaginationFilterSchema",
     "BasePaginationSchema",
     "BaseRepository",
     "BaseResponseSchema",
     "BaseSchema",
+    "BaseService",
     "CPFOrCNPJ",
     "ConflictException",
     "EmailUtils",
@@ -85,19 +100,25 @@ __all__: list[str] = [
     "ForbiddenException",
     "InvalidFileTypeException",
     "InvalidTokenException",
+    "JSONFormatter",
     "JWTUtils",
     "NotFoundException",
     "PasswordUtils",
     "PhoneBR",
+    "RequestIDMiddleware",
     "UnauthorizedException",
     "UploadUtils",
     "ValidationException",
     "__version__",
     "app_exception_handler",
+    "clear_request_id",
+    "configure_logging",
+    "get_request_id",
     "is_valid_cnpj",
     "is_valid_cpf",
     "is_valid_cpf_cnpj",
     "is_valid_phone_br",
+    "make_token_dependency",
     "modify_dict",
     "normalize_cnpj",
     "normalize_cpf",
@@ -105,6 +126,9 @@ __all__: list[str] = [
     "normalize_phone_br",
     "only_digits",
     "register_exception_handlers",
+    "request_id_ctx",
+    "require_x_token",
+    "set_request_id",
     "to_utc",
     "utcnow",
 ]

{tempest_fastapi_sdk-0.2.0 → tempest_fastapi_sdk-0.3.0}/tempest_fastapi_sdk/api/__init__.py

@@ -1,11 +1,19 @@
 """FastAPI integration primitives exposed at module level."""
 
+from tempest_fastapi_sdk.api.dependencies import (
+    make_token_dependency,
+    require_x_token,
+)
 from tempest_fastapi_sdk.api.handlers import (
     app_exception_handler,
     register_exception_handlers,
 )
+from tempest_fastapi_sdk.api.middlewares import RequestIDMiddleware
 
 __all__: list[str] = [
+    "RequestIDMiddleware",
     "app_exception_handler",
+    "make_token_dependency",
     "register_exception_handlers",
+    "require_x_token",
 ]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/api/dependencies/__init__.py

@@ -0,0 +1,11 @@
+"""FastAPI dependency providers used across SDK consumers."""
+
+from tempest_fastapi_sdk.api.dependencies.auth import (
+    make_token_dependency,
+    require_x_token,
+)
+
+__all__: list[str] = [
+    "make_token_dependency",
+    "require_x_token",
+]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/api/dependencies/auth.py

@@ -0,0 +1,84 @@
+"""Authentication dependencies (shared-secret token validation)."""
+
+from __future__ import annotations
+
+import hmac
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from fastapi import Header
+
+from tempest_fastapi_sdk.exceptions.unauthorized import UnauthorizedException
+
+
+def make_token_dependency(
+    secret: str,
+    *,
+    header_name: str = "X-Token",
+    error_message: str = "Invalid or missing token",
+) -> Callable[..., Coroutine[Any, Any, None]]:
+    """Build a FastAPI dependency that validates a shared-secret header.
+
+    The returned coroutine compares the inbound header value with
+    ``secret`` using :func:`hmac.compare_digest` (constant-time). An
+    empty ``secret`` disables the check entirely — intentional for
+    local development; production deployments should always provide
+    a non-empty value.
+
+    Args:
+        secret (str): The shared secret to compare against. Empty
+            string disables enforcement.
+        header_name (str): The header to read. Defaults to
+            ``"X-Token"``.
+        error_message (str): Message attached to the raised
+            :class:`UnauthorizedException`.
+
+    Returns:
+        Callable[..., Coroutine[Any, Any, None]]: An async FastAPI
+        dependency that raises :class:`UnauthorizedException` on
+        mismatch and returns ``None`` on success.
+    """
+    alias = header_name
+
+    async def _require_token(token: str = Header(default="", alias=alias)) -> None:
+        if not secret:
+            return
+        if not hmac.compare_digest(token, secret):
+            raise UnauthorizedException(message=error_message)
+
+    _require_token.__doc__ = (
+        f"Validate the {alias} header against the configured shared secret."
+    )
+    return _require_token
+
+
+async def require_x_token(
+    secret: str,
+    token: str,
+    *,
+    error_message: str = "Invalid or missing token",
+) -> None:
+    """Imperative variant of :func:`make_token_dependency`.
+
+    Useful when validation happens outside the FastAPI dependency
+    pipeline (e.g. from a websocket handler or background task).
+
+    Args:
+        secret (str): The shared secret.
+        token (str): The token to verify.
+        error_message (str): Message attached on failure.
+
+    Raises:
+        UnauthorizedException: When ``secret`` is non-empty and the
+            tokens do not match in constant time.
+    """
+    if not secret:
+        return
+    if not hmac.compare_digest(token, secret):
+        raise UnauthorizedException(message=error_message)
+
+
+__all__: list[str] = [
+    "make_token_dependency",
+    "require_x_token",
+]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/api/middlewares/__init__.py

@@ -0,0 +1,7 @@
+"""Reusable Starlette middlewares for FastAPI services."""
+
+from tempest_fastapi_sdk.api.middlewares.request_id import RequestIDMiddleware
+
+__all__: list[str] = [
+    "RequestIDMiddleware",
+]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/api/middlewares/request_id.py

@@ -0,0 +1,66 @@
+"""Correlation-ID middleware bridging HTTP headers and log context."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Awaitable, Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.types import ASGIApp
+
+from tempest_fastapi_sdk.core.context import clear_request_id, set_request_id
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    """Bind an ``X-Request-ID`` header to the request-scoped context.
+
+    Reads the inbound header (or generates a fresh UUID v4 when
+    absent), stores it via :func:`set_request_id` so log records
+    written during the request carry the ``request_id`` field, and
+    echoes the same value back on the response so callers can trace
+    end-to-end across services.
+
+    Args:
+        app (ASGIApp): The wrapped ASGI application.
+        header_name (str): The header to read/write. Defaults to
+            ``"X-Request-ID"``.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        header_name: str = "X-Request-ID",
+    ) -> None:
+        super().__init__(app)
+        self.header_name: str = header_name
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        """Run the wrapped handler with a bound request ID.
+
+        Args:
+            request (Request): The inbound request.
+            call_next: The downstream ASGI handler.
+
+        Returns:
+            Response: The handler's response with the request ID
+            echoed in the configured header.
+        """
+        rid = request.headers.get(self.header_name) or str(uuid.uuid4())
+        token = set_request_id(rid)
+        try:
+            response = await call_next(request)
+        finally:
+            clear_request_id(token)
+        response.headers[self.header_name] = rid
+        return response
+
+
+__all__: list[str] = [
+    "RequestIDMiddleware",
+]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/controllers/__init__.py

@@ -0,0 +1,7 @@
+"""Controller layer base classes (router ↔ service orchestrators)."""
+
+from tempest_fastapi_sdk.controllers.base import BaseController
+
+__all__: list[str] = [
+    "BaseController",
+]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/controllers/base.py

@@ -0,0 +1,126 @@
+"""Generic controller skeleton bridging routers and services."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar, cast
+from uuid import UUID
+
+from tempest_fastapi_sdk.services.base import BaseService
+
+ServiceT = TypeVar("ServiceT", bound=BaseService[Any, Any])
+ResponseT = TypeVar("ResponseT")
+
+
+class BaseController(Generic[ServiceT, ResponseT]):
+    """Thin orchestration layer between routers and services.
+
+    Following the SDK layering rules (router → controller → service →
+    repository), controllers are kept present even when no
+    orchestration is required so the import graph stays uniform.
+    Override methods here when a single endpoint needs to call
+    multiple services or apply cross-cutting policy; leave the
+    pass-throughs untouched otherwise.
+
+    Generic parameters:
+        ServiceT: The concrete service class.
+        ResponseT: The response schema returned to the router.
+
+    Attributes:
+        service (ServiceT): The service the controller delegates to.
+    """
+
+    def __init__(self, service: ServiceT) -> None:
+        """Initialize the controller.
+
+        Args:
+            service (ServiceT): The service to delegate to.
+        """
+        self.service: ServiceT = service
+
+    async def get_by_id(self, id: UUID) -> ResponseT:
+        """Pass-through to :meth:`BaseService.get_by_id`.
+
+        Args:
+            id (UUID): The primary key.
+
+        Returns:
+            ResponseT: The mapped response.
+        """
+        return cast("ResponseT", await self.service.get_by_id(id))
+
+    async def list(
+        self,
+        filters: dict[str, Any] | None = None,
+        order_by: Any | None = None,
+        ascending: bool = True,
+    ) -> list[ResponseT]:
+        """Pass-through to :meth:`BaseService.list`.
+
+        Args:
+            filters (dict[str, Any] | None): Filter conditions.
+            order_by: A SQLAlchemy column expression.
+            ascending (bool): Whether to order ascending.
+
+        Returns:
+            list[ResponseT]: The mapped responses.
+        """
+        return cast(
+            "list[ResponseT]",
+            await self.service.list(
+                filters=filters,
+                order_by=order_by,
+                ascending=ascending,
+            ),
+        )
+
+    async def paginate(
+        self,
+        filters: dict[str, Any] | None = None,
+        order_by: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
+        ascending: bool = True,
+    ) -> dict[str, Any]:
+        """Pass-through to :meth:`BaseService.paginate`.
+
+        Args:
+            filters (dict[str, Any] | None): Filter conditions.
+            order_by (str | None): Column name to order by.
+            page (int): 1-indexed page number.
+            page_size (int): Items per page.
+            ascending (bool): Whether to order ascending.
+
+        Returns:
+            dict[str, Any]: The paginated payload.
+        """
+        return await self.service.paginate(
+            filters=filters,
+            order_by=order_by,
+            page=page,
+            page_size=page_size,
+            ascending=ascending,
+        )
+
+    async def count(self, filters: dict[str, Any] | None = None) -> int:
+        """Pass-through to :meth:`BaseService.count`.
+
+        Args:
+            filters (dict[str, Any] | None): The filter conditions.
+
+        Returns:
+            int: The matching row count.
+        """
+        return await self.service.count(filters)
+
+    async def delete(self, id: UUID) -> None:
+        """Pass-through to :meth:`BaseService.delete`.
+
+        Args:
+            id (UUID): The primary key.
+        """
+        await self.service.delete(id)
+
+
+__all__: list[str] = [
+    "BaseController",
+]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/core/__init__.py

@@ -0,0 +1,21 @@
+"""Core cross-cutting primitives: logging, context, configuration."""
+
+from tempest_fastapi_sdk.core.context import (
+    clear_request_id,
+    get_request_id,
+    request_id_ctx,
+    set_request_id,
+)
+from tempest_fastapi_sdk.core.logging import (
+    JSONFormatter,
+    configure_logging,
+)
+
+__all__: list[str] = [
+    "JSONFormatter",
+    "clear_request_id",
+    "configure_logging",
+    "get_request_id",
+    "request_id_ctx",
+    "set_request_id",
+]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/core/context.py

@@ -0,0 +1,55 @@
+"""Context variables propagated across the request lifecycle."""
+
+from contextvars import ContextVar, Token
+
+request_id_ctx: ContextVar[str | None] = ContextVar(
+    "tempest_request_id",
+    default=None,
+)
+"""Per-request correlation identifier.
+
+Set by :class:`tempest_fastapi_sdk.api.middlewares.RequestIDMiddleware`
+on every inbound HTTP request, consumed by
+:class:`tempest_fastapi_sdk.core.logging.JSONFormatter` so every log
+line carries the originating request ID.
+"""
+
+
+def get_request_id() -> str | None:
+    """Return the current request ID, or ``None`` outside a request.
+
+    Returns:
+        str | None: The active correlation ID, or ``None`` when not set.
+    """
+    return request_id_ctx.get()
+
+
+def set_request_id(value: str) -> Token[str | None]:
+    """Bind a request ID for the current async context.
+
+    Args:
+        value (str): The correlation identifier to set.
+
+    Returns:
+        Token[str | None]: A token that can be passed to
+        :func:`clear_request_id` to restore the previous value.
+    """
+    return request_id_ctx.set(value)
+
+
+def clear_request_id(token: Token[str | None]) -> None:
+    """Reset the request ID using the token returned by :func:`set_request_id`.
+
+    Args:
+        token (Token[str | None]): The token obtained from a previous
+            :func:`set_request_id` call.
+    """
+    request_id_ctx.reset(token)
+
+
+__all__: list[str] = [
+    "clear_request_id",
+    "get_request_id",
+    "request_id_ctx",
+    "set_request_id",
+]

tempest_fastapi_sdk-0.3.0/tempest_fastapi_sdk/core/logging.py

@@ -0,0 +1,130 @@
+"""Structured JSON logging with request-ID correlation."""
+
+import json
+import logging
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+from tempest_fastapi_sdk.core.context import get_request_id
+
+_RESERVED_LOG_FIELDS: frozenset[str] = frozenset(
+    {
+        "args",
+        "created",
+        "exc_info",
+        "exc_text",
+        "filename",
+        "funcName",
+        "levelname",
+        "levelno",
+        "lineno",
+        "message",
+        "module",
+        "msecs",
+        "msg",
+        "name",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "stack_info",
+        "taskName",
+        "thread",
+        "threadName",
+    }
+)
+
+
+class JSONFormatter(logging.Formatter):
+    """Render every log record as a single-line JSON object.
+
+    Standard ``LogRecord`` fields are mapped to ``timestamp``,
+    ``level``, ``logger`` and ``message``. The current request ID
+    (when present) is attached as ``request_id``. Any additional
+    keyword passed to the logger via ``extra={...}`` becomes a
+    top-level key in the JSON payload.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Serialize ``record`` to JSON.
+
+        Args:
+            record (logging.LogRecord): The record to format.
+
+        Returns:
+            str: A JSON document as a single line.
+        """
+        timestamp = (
+            datetime.fromtimestamp(record.created, tz=UTC)
+            .isoformat()
+            .replace("+00:00", "Z")
+        )
+        payload: dict[str, Any] = {
+            "timestamp": timestamp,
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        request_id = get_request_id()
+        if request_id is not None:
+            payload["request_id"] = request_id
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        for key, value in record.__dict__.items():
+            if key in _RESERVED_LOG_FIELDS:
+                continue
+            if key.startswith("_"):
+                continue
+            payload[key] = value
+        return json.dumps(payload, default=str, ensure_ascii=False)
+
+
+def configure_logging(
+    level: str | int = "INFO",
+    *,
+    json_output: bool = True,
+    logger_name: str | None = None,
+) -> logging.Logger:
+    """Install a structured stdout handler on the root (or named) logger.
+
+    Replaces existing handlers on the target logger so this can be
+    called safely from ``create_app`` without stacking duplicates.
+
+    Args:
+        level (str | int): The minimum level to emit (e.g. ``"INFO"``,
+            ``logging.DEBUG``).
+        json_output (bool): When ``True`` (default), emit JSON via
+            :class:`JSONFormatter`. When ``False``, fall back to a
+            human-readable text formatter — useful in local dev where
+            JSON noise overwhelms the terminal.
+        logger_name (str | None): The logger to configure. ``None``
+            (default) configures the root logger.
+
+    Returns:
+        logging.Logger: The configured logger instance.
+    """
+    logger = logging.getLogger(logger_name)
+    logger.setLevel(level)
+    for handler in list(logger.handlers):
+        logger.removeHandler(handler)
+
+    handler = logging.StreamHandler(sys.stdout)
+    if json_output:
+        handler.setFormatter(JSONFormatter())
+    else:
+        handler.setFormatter(
+            logging.Formatter(
+                fmt="%(asctime)s %(levelname)s %(name)s %(message)s",
+                datefmt="%Y-%m-%dT%H:%M:%S",
+            )
+        )
+    logger.addHandler(handler)
+    logger.propagate = False
+    return logger
+
+
+__all__: list[str] = [
+    "JSONFormatter",
+    "configure_logging",
+]