fastapi-forge-cli 0.1.0__py3-none-any.whl

fastapi_forge/templates/with_rbac/app/core/exceptions.py

@@ -0,0 +1,162 @@
+from typing import Any, Optional
+from fastapi import Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from app.core.logging import get_logger
+from app.core.responses import error_response
+
+logger = get_logger(__name__)
+
+
+# ── Custom Exception Base ────────────────────────────────────────
+class AppException(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: int = status.HTTP_500_INTERNAL_SERVER_ERROR,
+        error_code: Optional[str] = None,
+        details: Optional[Any] = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code or f"ERR_{status_code}"
+        self.details = details
+        super().__init__(message)
+
+
+# ── Domain-specific Exceptions ───────────────────────────────────
+class NotFoundException(AppException):
+    def __init__(self, resource: str = "Resource", resource_id: Any = None):
+        msg = f"{resource} not found"
+        if resource_id:
+            msg = f"{resource} with id '{resource_id}' not found"
+        super().__init__(msg, status.HTTP_404_NOT_FOUND, "NOT_FOUND")
+
+
+class UnauthorizedException(AppException):
+    def __init__(self, message: str = "Authentication required"):
+        super().__init__(message, status.HTTP_401_UNAUTHORIZED, "UNAUTHORIZED")
+
+
+class ForbiddenException(AppException):
+    def __init__(self, message: str = "Permission denied"):
+        super().__init__(message, status.HTTP_403_FORBIDDEN, "FORBIDDEN")
+
+
+class ConflictException(AppException):
+    def __init__(self, message: str = "Resource already exists"):
+        super().__init__(message, status.HTTP_409_CONFLICT, "CONFLICT")
+
+
+class ValidationException(AppException):
+    def __init__(self, message: str = "Validation failed", details: Any = None):
+        super().__init__(
+            message, status.HTTP_422_UNPROCESSABLE_ENTITY, "VALIDATION_ERROR", details
+        )
+
+
+class RateLimitException(AppException):
+    def __init__(self, message: str = "Too many requests"):
+        super().__init__(
+            message, status.HTTP_429_TOO_MANY_REQUESTS, "RATE_LIMIT_EXCEEDED"
+        )
+
+
+class ServiceUnavailableException(AppException):
+    def __init__(self, message: str = "Service temporarily unavailable"):
+        super().__init__(
+            message, status.HTTP_503_SERVICE_UNAVAILABLE, "SERVICE_UNAVAILABLE"
+        )
+
+
+# ── Exception Handlers ───────────────────────────────────────────
+async def app_exception_handler(request: Request, exc: AppException) -> JSONResponse:
+    logger.error(
+        "Application exception",
+        error_code=exc.error_code,
+        message=exc.message,
+        status_code=exc.status_code,
+        path=str(request.url),
+    )
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response(
+            message=exc.message,
+            error_code=exc.error_code,
+            details=exc.details,
+            request_id=getattr(request.state, "request_id", None),
+        ).model_dump(by_alias=True),
+    )
+
+
+async def http_exception_handler(
+    request: Request, exc: StarletteHTTPException
+) -> JSONResponse:
+    logger.warning(
+        "HTTP exception",
+        status_code=exc.status_code,
+        detail=exc.detail,
+        path=str(request.url),
+    )
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response(
+            message=str(exc.detail),
+            error_code=f"HTTP_{exc.status_code}",
+            request_id=getattr(request.state, "request_id", None),
+        ).model_dump(by_alias=True),
+    )
+
+
+async def validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    errors = []
+    for error in exc.errors():
+        errors.append(
+            {
+                "field": " -> ".join(str(loc) for loc in error["loc"]),
+                "message": error["msg"],
+                "type": error["type"],
+            }
+        )
+
+    logger.warning(
+        "Request validation failed",
+        errors=errors,
+        path=str(request.url),
+    )
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content=error_response(
+            message="Request validation failed",
+            error_code="VALIDATION_ERROR",
+            details=errors,
+            request_id=getattr(request.state, "request_id", None),
+        ).model_dump(by_alias=True),
+    )
+
+
+async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    logger.exception(
+        "Unhandled exception",
+        exc_info=exc,
+        path=str(request.url),
+    )
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content=error_response(
+            message="An unexpected error occurred",
+            error_code="INTERNAL_SERVER_ERROR",
+            request_id=getattr(request.state, "request_id", None),
+        ).model_dump(by_alias=True),
+    )
+
+
+def register_exception_handlers(app) -> None:
+    app.add_exception_handler(AppException, app_exception_handler)
+    app.add_exception_handler(StarletteHTTPException, http_exception_handler)
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+    app.add_exception_handler(Exception, unhandled_exception_handler)

fastapi_forge/templates/with_rbac/app/core/logging.py

@@ -0,0 +1,231 @@
+import logging
+import logging.handlers
+import sys
+import uuid
+from contextvars import ContextVar
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+import structlog
+from app.core.config import settings
+
+# ── Context var to carry request-id across async tasks ──────────
+request_id_ctx: ContextVar[Optional[str]] = ContextVar("request_id", default=None)
+
+
+def get_request_id() -> str:
+    return request_id_ctx.get() or str(uuid.uuid4())
+
+
+def set_request_id(request_id: str) -> None:
+    request_id_ctx.set(request_id)
+
+
+# ── Add request_id to every log record automatically ────────────
+def add_request_id(logger, method, event_dict):
+    event_dict["request_id"] = get_request_id()
+    return event_dict
+
+
+def add_app_info(logger, method, event_dict):
+    event_dict["app"] = settings.APP_NAME
+    event_dict["env"] = settings.APP_ENV
+    return event_dict
+
+
+# ── Log level filter ───────────────────────────────────────────
+def level_filter(levels: list[int]):
+    """Return a logging filter function that passes only specified log levels."""
+    allowed_levels = set(levels)
+
+    def filter_record(record: logging.LogRecord) -> bool:
+        return record.levelno in allowed_levels
+
+    return filter_record
+
+
+# ── Build daily rotating file handler ─────────────────────────
+def _build_file_handler(
+    log_dir: str, level: int, label: str, formatter: logging.Formatter
+) -> logging.Handler:
+    """
+    TimedRotatingFileHandler that writes to  <log_dir>/YYYY-MM-DD_<label>.log.
+    The date prefix is embedded in the *base* filename so every day's file
+    carries the date as a prefix rather than a suffix.
+    """
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+    # Create date-wise log directory.
+    date_dir = Path(log_dir) / today
+    date_dir.mkdir(parents=True, exist_ok=True)
+
+    # Example:
+    # logs/2026-07-29/error.log
+    path = date_dir / f"{label}.log"
+
+    handler = logging.handlers.TimedRotatingFileHandler(
+        filename=str(path),
+        when="midnight",
+        interval=1,
+        backupCount=30,
+        utc=True,
+        encoding="utf-8",
+    )
+
+    handler.suffix = "%Y-%m-%d"
+    handler.setLevel(level)
+    handler.setFormatter(formatter)
+    return handler
+
+
+# ── Configure per-level file logging ──────────────────────────
+def _setup_file_logging(
+    log_dir: str, root_level: int, formatter: logging.Formatter
+) -> None:
+    """Attach per-level file handlers to the root stdlib logger."""
+
+    Path(log_dir).mkdir(parents=True, exist_ok=True)
+
+    root = logging.getLogger()
+
+    # Remove previously configured application file handlers.
+    # This prevents duplicate logs when configure_logging() is
+    # called more than once, which can happen with reloaders.
+    for handler in root.handlers[:]:
+        if getattr(handler, "_app_file_handler", False):
+            root.removeHandler(handler)
+            handler.close()
+
+    level_map = [
+        (logging.DEBUG, [logging.DEBUG], "debug"),
+        (logging.INFO, [logging.INFO], "info"),
+        (logging.WARNING, [logging.WARNING], "warn"),
+        (logging.ERROR, [logging.ERROR, logging.CRITICAL], "error"),
+    ]
+
+    for min_level, filter_levels, label in level_map:
+        # Do not create files below the configured log level.
+        if min_level < root_level:
+            continue
+
+        handler = _build_file_handler(
+            log_dir=log_dir, level=min_level, label=label, formatter=formatter
+        )
+
+        # Mark handler so it can be identified and removed later.
+        handler._app_file_handler = True
+
+        # Only allow the exact levels assigned to this file.
+        handler.addFilter(level_filter(filter_levels))
+        root.addHandler(handler)
+
+
+# ── Logging configuration ─────────────────────────────────────
+def configure_logging() -> None:
+    """
+    Configure Structlog, console logging, file logging,
+    and third-party library logging.
+    """
+
+    log_level = logging.DEBUG if settings.APP_DEBUG else logging.INFO
+
+    common_shared_processors = [
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+    ]
+
+    shared_processors = common_shared_processors + [
+        structlog.contextvars.merge_contextvars,
+        add_request_id,
+        add_app_info,
+    ]
+
+    # ── Console formatter ──────────────────────────────────────
+    # Pretty console output for development.
+    # Colors are disabled automatically outside development.
+    console_formatter = structlog.stdlib.ProcessorFormatter(
+        processor=structlog.dev.ConsoleRenderer(
+            colors=settings.is_development,
+            exception_formatter=structlog.dev.plain_traceback,
+        ),
+        foreign_pre_chain=shared_processors,
+    )
+
+    # ── JSON file formatter ────────────────────────────────────
+    # Structured JSON output for log aggregators and production
+    # log analysis.
+    json_formatter = structlog.stdlib.ProcessorFormatter(
+        processor=structlog.processors.JSONRenderer(),
+        foreign_pre_chain=shared_processors,
+    )
+
+    # ── Configure Structlog ────────────────────────────────────
+
+    structlog.configure(
+        processors=common_shared_processors
+        + [
+            structlog.stdlib.filter_by_level,
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    # ── Root logger ────────────────────────────────────────────
+
+    root = logging.getLogger()
+    root.setLevel(log_level)
+
+    # Remove existing handlers to avoid:
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+        handler.close()
+
+    # ── Console handler ────────────────────────────────────────
+
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(log_level)
+    console_handler.setFormatter(console_formatter)
+
+    root.addHandler(console_handler)
+
+    # ── File handlers ──────────────────────────────────────────
+    if settings.log_to_files:
+        _setup_file_logging(
+            log_dir=settings.log_dir,
+            root_level=log_level,
+            formatter=json_formatter,
+        )
+
+    # ── Third-party libraries ──────────────────────────────────
+
+    # FastAPI application logs.
+    logging.getLogger("fastapi").setLevel(log_level)
+
+    # Uvicorn access logs
+    logging.getLogger("uvicorn.access").setLevel(logging.INFO)
+
+    # Uvicorn server errors.
+    logging.getLogger("uvicorn.error").setLevel(logging.ERROR)
+
+    # APScheduler:
+    logging.getLogger("apscheduler").setLevel(logging.WARNING)
+
+    # SQLAlchemy SQL logging:
+    #
+    # Keep disabled unless explicitly debugging SQL.
+    logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+
+    # SQLAlchemy connection pool logging.
+    logging.getLogger("sqlalchemy.pool").setLevel(logging.WARNING)
+
+
+# ── Logger factory ─────────────────────────────────────────────
+def get_logger(name: str = __name__):
+    return structlog.get_logger(name)

fastapi_forge/templates/with_rbac/app/core/middleware.py

@@ -0,0 +1,188 @@
+import re
+import time
+import uuid
+from typing import Callable
+
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from app.core.config import settings
+from app.core.logging import get_logger, set_request_id
+
+logger = get_logger(__name__)
+
+# ── Rate limiter (slowapi + Redis) ───────────────────────────────
+is_redis_store = settings.use_redis and bool(settings.redis_url)
+limiter = Limiter(
+    key_func=get_remote_address,
+    storage_uri=settings.redis_url if is_redis_store else None,
+    default_limits=[f"{settings.rate_limit_per_minute}/minute"],
+)
+
+
+# ── Request-ID / Correlation-ID middleware ───────────────────────
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    """
+    Attaches a unique X-Request-ID to every request.
+    Respects an existing header if the upstream proxy already set one.
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        supplied_id = request.headers.get("X-Request-ID") or request.headers.get(
+            "X-Correlation-ID"
+        )
+        request_id = (
+            supplied_id
+            if supplied_id and re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", supplied_id)
+            else str(uuid.uuid4())
+        )
+        request.state.request_id = request_id
+        set_request_id(request_id)
+
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request_id
+        return response
+
+
+# ── Structured request / response logging middleware ─────────────
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """
+    Logs every HTTP request and response with timing, status, and IDs.
+    Skips health-check and metrics endpoints to avoid log noise.
+    """
+
+    SKIP_PATHS = {"/health", "/metrics", "/favicon.ico"}
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        if request.url.path in self.SKIP_PATHS:
+            return await call_next(request)
+
+        start = time.perf_counter()
+        request_id = getattr(request.state, "request_id", "")
+
+        # ── Log incoming request ──────────────────────────────
+        logger.info(
+            "Incoming request",
+            method=request.method,
+            path=request.url.path,
+            client_ip=request.client.host if request.client else "unknown",
+            user_agent=request.headers.get("user-agent", ""),
+            request_id=request_id,
+        )
+
+        response: Response = await call_next(request)
+
+        elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+
+        # ── Log outgoing response ─────────────────────────────
+        log_fn = logger.error if response.status_code >= 400 else logger.info
+        log_fn(
+            "Request completed",
+            method=request.method,
+            path=request.url.path,
+            status_code=response.status_code,
+            duration_ms=elapsed_ms,
+            request_id=request_id,
+        )
+
+        response.headers["X-Process-Time-Ms"] = str(elapsed_ms)
+        return response
+
+
+# ── Security headers middleware ──────────────────────────────────
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        if settings.is_production:
+            response.headers["Strict-Transport-Security"] = (
+                "max-age=31536000; includeSubDomains"
+            )
+        return response
+
+
+class AuditMiddleware(BaseHTTPMiddleware):
+    """Persist an audit entry for every successful state-changing API request."""
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        response = await call_next(request)
+        if (
+            request.method not in {"POST", "PUT", "PATCH", "DELETE"}
+            or not request.url.path.startswith("/api/")
+            or response.status_code >= 400
+        ):
+            return response
+
+        user_id = None
+        authorization = request.headers.get("authorization", "")
+        if authorization.lower().startswith("bearer "):
+            try:
+                from app.core.security import decode_token
+
+                user_id = decode_token(
+                    authorization.split(" ", 1)[1], expected_type="access"
+                ).get("sub")
+            except Exception:
+                user_id = None
+
+        try:
+            from app.db.session import AsyncSessionLocal
+            from app.services.audit import AuditService
+
+            async with AsyncSessionLocal() as session:
+                await AuditService(session).log(
+                    action=request.method.lower(),
+                    resource=request.url.path,
+                    user_id=user_id,
+                    metadata={"status_code": response.status_code},
+                    ip_address=request.client.host if request.client else None,
+                    user_agent=request.headers.get("user-agent"),
+                    request_id=getattr(request.state, "request_id", None),
+                )
+                await session.commit()
+        except Exception as exc:
+            logger.error("Request audit logging failed", error=str(exc))
+
+        return response
+
+
+# ── Registration helper ──────────────────────────────────────────
+def register_middleware(app: FastAPI) -> None:
+    # Order matters: outermost middleware runs first on request, last on response.
+
+    # CORS (must be early so preflight OPTIONS pass)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.ALLOWED_ORIGINS,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+        expose_headers=["X-Request-ID", "X-Process-Time-Ms"],
+    )
+
+    # Trusted hosts
+    if settings.is_production:
+        app.add_middleware(
+            TrustedHostMiddleware,
+            allowed_hosts=settings.ALLOWED_HOSTS,
+        )
+
+    # Security headers
+    app.add_middleware(SecurityHeadersMiddleware)
+
+    # Record successful state-changing API requests.
+    app.add_middleware(AuditMiddleware)
+
+    # Starlette runs the last added middleware first on incoming requests.
+    # Logging is added before Request-ID so it runs after the ID is set.
+    app.add_middleware(RequestLoggingMiddleware)
+
+    # Request-ID runs before logging so the logger can read the ID.
+    app.add_middleware(RequestIDMiddleware)

fastapi_forge/templates/with_rbac/app/core/responses.py

@@ -0,0 +1,108 @@
+from typing import Any, Dict, Generic, List, Optional, TypeVar
+from datetime import datetime, timezone
+
+from app.core.logging import get_request_id
+from app.utils.casing import CamelModel, keys_to_camel
+
+T = TypeVar("T")
+
+
+# ── Pagination metadata ──────────────────────────────────────────
+class PaginationMeta(CamelModel):
+    page: int
+    page_size: int
+    total_items: int
+    total_pages: int
+    has_next: bool
+    has_prev: bool
+
+
+# ── Standard envelope models ─────────────────────────────────────
+class APIResponse(CamelModel, Generic[T]):
+    success: bool
+    message: str
+    data: Optional[T] = None
+    meta: Optional[Dict[str, Any]] = None
+    error_code: Optional[str] = None
+    details: Any = None
+    timestamp: str = ""
+    request_id: Optional[str] = None
+
+
+class PaginatedResponse(CamelModel, Generic[T]):
+    success: bool
+    message: str
+    data: List[T]
+    pagination: PaginationMeta
+    meta: Optional[Dict[str, Any]] = None
+    timestamp: str = ""
+    request_id: Optional[str] = None
+
+
+# ── Builder helpers ──────────────────────────────────────────────
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _request_id_or_current(request_id: Optional[str]) -> str:
+    return request_id or get_request_id()
+
+
+def success_response(
+    data: Any = None,
+    message: str = "Success",
+    meta: Optional[Dict[str, Any]] = None,
+    request_id: Optional[str] = None,
+) -> APIResponse:
+    return APIResponse(
+        success=True,
+        message=message,
+        data=keys_to_camel(data),
+        meta=keys_to_camel(meta),
+        timestamp=_now(),
+        request_id=_request_id_or_current(request_id),
+    )
+
+
+def error_response(
+    message: str = "An error occurred",
+    error_code: str = "ERROR",
+    details: Any = None,
+    request_id: Optional[str] = None,
+) -> APIResponse:
+    return APIResponse(
+        success=False,
+        message=message,
+        error_code=error_code,
+        details=keys_to_camel(details),
+        timestamp=_now(),
+        request_id=_request_id_or_current(request_id),
+    )
+
+
+def paginated_response(
+    data: List[Any],
+    total_items: int,
+    page: int,
+    page_size: int,
+    message: str = "Success",
+    meta: Optional[Dict[str, Any]] = None,
+    request_id: Optional[str] = None,
+) -> PaginatedResponse:
+    total_pages = (total_items + page_size - 1) // page_size if page_size > 0 else 0
+    return PaginatedResponse(
+        success=True,
+        message=message,
+        data=keys_to_camel(data),
+        pagination=PaginationMeta(
+            page=page,
+            page_size=page_size,
+            total_items=total_items,
+            total_pages=total_pages,
+            has_next=page < total_pages,
+            has_prev=page > 1,
+        ),
+        meta=keys_to_camel(meta),
+        timestamp=_now(),
+        request_id=_request_id_or_current(request_id),
+    )