fastapi-fullstack 0.1.2__py3-none-any.whl

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/exceptions.py

@@ -0,0 +1,122 @@
+"""Application exceptions.
+
+Domain exceptions with HTTP status codes for the hybrid approach.
+These exceptions are caught by exception handlers and converted to proper HTTP responses.
+"""
+
+from typing import Any
+
+
+class AppException(Exception):
+    """Base exception for all application errors.
+
+    Attributes:
+        message: Human-readable error message.
+        code: Machine-readable error code for clients.
+        status_code: HTTP status code to return.
+        details: Additional error details (e.g., field names, IDs).
+    """
+
+    message: str = "An error occurred"
+    code: str = "APP_ERROR"
+    status_code: int = 500
+
+    def __init__(
+        self,
+        message: str | None = None,
+        code: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        self.message = message or self.__class__.message
+        self.code = code or self.__class__.code
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={self.message!r}, code={self.code!r})"
+
+
+# === 4xx Client Errors ===
+
+
+class NotFoundError(AppException):
+    """Resource not found (404)."""
+
+    message = "Resource not found"
+    code = "NOT_FOUND"
+    status_code = 404
+
+
+class AlreadyExistsError(AppException):
+    """Resource already exists (409)."""
+
+    message = "Resource already exists"
+    code = "ALREADY_EXISTS"
+    status_code = 409
+
+
+class ValidationError(AppException):
+    """Validation error (422)."""
+
+    message = "Validation error"
+    code = "VALIDATION_ERROR"
+    status_code = 422
+
+
+class AuthenticationError(AppException):
+    """Authentication failed (401)."""
+
+    message = "Authentication failed"
+    code = "AUTHENTICATION_ERROR"
+    status_code = 401
+
+
+class AuthorizationError(AppException):
+    """Authorization failed - insufficient permissions (403)."""
+
+    message = "Insufficient permissions"
+    code = "AUTHORIZATION_ERROR"
+    status_code = 403
+
+
+class RateLimitError(AppException):
+    """Rate limit exceeded (429)."""
+
+    message = "Rate limit exceeded"
+    code = "RATE_LIMIT_EXCEEDED"
+    status_code = 429
+
+
+class BadRequestError(AppException):
+    """Bad request (400)."""
+
+    message = "Bad request"
+    code = "BAD_REQUEST"
+    status_code = 400
+
+
+# === 5xx Server Errors ===
+
+
+class ExternalServiceError(AppException):
+    """External service unavailable (503)."""
+
+    message = "External service unavailable"
+    code = "EXTERNAL_SERVICE_ERROR"
+    status_code = 503
+
+
+class DatabaseError(AppException):
+    """Database error (500)."""
+
+    message = "Database error"
+    code = "DATABASE_ERROR"
+    status_code = 500
+
+
+class InternalError(AppException):
+    """Internal server error (500)."""
+
+    message = "Internal server error"
+    code = "INTERNAL_ERROR"
+    status_code = 500

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/logfire_setup.py

@@ -0,0 +1,101 @@
+{%- if cookiecutter.enable_logfire %}
+"""Logfire observability configuration."""
+
+import logfire
+
+from app.core.config import settings
+
+
+def setup_logfire() -> None:
+    """Configure Logfire instrumentation."""
+    logfire.configure(
+        token=settings.LOGFIRE_TOKEN,
+        service_name=settings.LOGFIRE_SERVICE_NAME,
+        environment=settings.LOGFIRE_ENVIRONMENT,
+        send_to_logfire="if-token-present",
+    )
+
+
+def instrument_app(app):
+    """Instrument FastAPI app with Logfire."""
+{%- if cookiecutter.logfire_fastapi %}
+    logfire.instrument_fastapi(app)
+{%- else %}
+    pass
+{%- endif %}
+
+
+{%- if cookiecutter.use_postgresql and cookiecutter.logfire_database %}
+
+
+def instrument_asyncpg():
+    """Instrument asyncpg for PostgreSQL."""
+    logfire.instrument_asyncpg()
+{%- endif %}
+
+
+{%- if cookiecutter.use_mongodb and cookiecutter.logfire_database %}
+
+
+def instrument_pymongo():
+    """Instrument PyMongo/Motor for MongoDB."""
+    logfire.instrument_pymongo(capture_statement=settings.DEBUG)
+{%- endif %}
+
+
+{%- if cookiecutter.use_sqlite and cookiecutter.logfire_database %}
+
+
+def instrument_sqlalchemy(engine):
+    """Instrument SQLAlchemy for SQLite."""
+    logfire.instrument_sqlalchemy(engine=engine)
+{%- endif %}
+
+
+{%- if cookiecutter.enable_redis and cookiecutter.logfire_redis %}
+
+
+def instrument_redis():
+    """Instrument Redis."""
+    logfire.instrument_redis()
+{%- endif %}
+
+
+{%- if cookiecutter.use_celery and cookiecutter.logfire_celery %}
+
+
+def instrument_celery():
+    """Instrument Celery."""
+    logfire.instrument_celery()
+{%- endif %}
+
+
+{%- if cookiecutter.logfire_httpx %}
+
+
+def instrument_httpx():
+    """Instrument HTTPX for outgoing HTTP requests."""
+    logfire.instrument_httpx()
+{%- endif %}
+
+
+{%- if cookiecutter.enable_ai_agent %}
+
+
+def instrument_pydantic_ai():
+    """Instrument PydanticAI for AI agent observability."""
+    logfire.instrument_pydantic_ai()
+{%- endif %}
+{%- else %}
+"""Logfire is disabled for this project."""
+
+
+def setup_logfire() -> None:
+    """No-op when Logfire is disabled."""
+    pass
+
+
+def instrument_app(app):
+    """No-op when Logfire is disabled."""
+    pass
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/middleware.py

@@ -0,0 +1,99 @@
+"""Application middleware."""
+
+from typing import ClassVar
+from uuid import uuid4
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    """Middleware that adds a unique request ID to each request.
+
+    The request ID is taken from the X-Request-ID header if present,
+    otherwise a new UUID is generated. The ID is added to the response
+    headers and is available in request.state.request_id.
+    """
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        """Add request ID to request state and response headers."""
+        request_id = request.headers.get("X-Request-ID", str(uuid4()))
+        request.state.request_id = request_id
+
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request_id
+        return response
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """Middleware that adds security headers to all responses.
+
+    This includes:
+    - Content-Security-Policy (CSP)
+    - X-Content-Type-Options
+    - X-Frame-Options
+    - X-XSS-Protection
+    - Referrer-Policy
+    - Permissions-Policy
+
+    Usage:
+        app.add_middleware(SecurityHeadersMiddleware)
+
+        # Or with custom CSP:
+        app.add_middleware(
+            SecurityHeadersMiddleware,
+            csp_directives={
+                "default-src": "'self'",
+                "script-src": "'self' 'unsafe-inline'",
+            }
+        )
+    """
+
+    DEFAULT_CSP_DIRECTIVES: ClassVar[dict[str, str]] = {
+        "default-src": "'self'",
+        "script-src": "'self'",
+        "style-src": "'self' 'unsafe-inline'",  # Allow inline styles for some UI libs
+        "img-src": "'self' data: https:",
+        "font-src": "'self' data:",
+        "connect-src": "'self'",
+        "frame-ancestors": "'none'",
+        "base-uri": "'self'",
+        "form-action": "'self'",
+    }
+
+    def __init__(
+        self,
+        app,
+        csp_directives: dict | None = None,
+        exclude_paths: set | None = None,
+    ):
+        super().__init__(app)
+        self.csp_directives = csp_directives or self.DEFAULT_CSP_DIRECTIVES
+        self.exclude_paths = exclude_paths or {"/docs", "/redoc", "/openapi.json"}
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        """Add security headers to the response."""
+        response = await call_next(request)
+
+        # Skip for docs/openapi endpoints which need different CSP
+        if request.url.path in self.exclude_paths:
+            return response
+
+        # Build CSP header
+        csp_value = "; ".join(
+            f"{directive} {value}" for directive, value in self.csp_directives.items()
+        )
+
+        # Add security headers
+        response.headers["Content-Security-Policy"] = csp_value
+        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"
+        response.headers["Permissions-Policy"] = (
+            "accelerometer=(), camera=(), geolocation=(), gyroscope=(), "
+            "magnetometer=(), microphone=(), payment=(), usb=()"
+        )
+
+        return response

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/oauth.py

@@ -0,0 +1,23 @@
+{%- if cookiecutter.enable_oauth %}
+"""OAuth2 client configuration."""
+
+from authlib.integrations.starlette_client import OAuth
+
+from app.core.config import settings
+
+oauth = OAuth()
+
+{%- if cookiecutter.enable_oauth_google %}
+
+# Configure Google OAuth2
+oauth.register(
+    name="google",
+    client_id=settings.GOOGLE_CLIENT_ID,
+    client_secret=settings.GOOGLE_CLIENT_SECRET,
+    server_metadata_url="https://accounts.google.com/.well-known/openid-configuration",
+    client_kwargs={"scope": "openid email profile"},
+)
+{%- endif %}
+{%- else %}
+"""OAuth module - not configured."""
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/rate_limit.py

@@ -0,0 +1,58 @@
+{%- if cookiecutter.enable_rate_limiting %}
+"""Rate limiting configuration using slowapi.
+
+Default rate limit: {{ cookiecutter.rate_limit_requests }} requests per {{ cookiecutter.rate_limit_period }} seconds.
+Override with RATE_LIMIT_REQUESTS and RATE_LIMIT_PERIOD environment variables.
+"""
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from app.core.config import settings
+
+
+def get_default_rate_limit() -> str:
+    """Get default rate limit string from settings.
+
+    Returns a rate limit string like "100/minute" or "60/second".
+    """
+    requests = settings.RATE_LIMIT_REQUESTS
+    period = settings.RATE_LIMIT_PERIOD
+
+    # Convert period to a human-readable format
+    period_map = {
+        60: "minute",
+        3600: "hour",
+        86400: "day",
+    }
+
+    if period in period_map:
+        return f"{requests}/{period_map[period]}"
+    # For custom periods, use "per X seconds"
+    return f"{requests}/{period} seconds"
+
+
+# Rate limiter instance with configurable default
+limiter = Limiter(
+    key_func=get_remote_address,
+    default_limits=[get_default_rate_limit()],
+)
+
+# Common rate limit decorators for convenience
+# Usage: @rate_limit_low, @rate_limit_medium, @rate_limit_high
+def rate_limit_low(limit: str = "10/minute"):
+    """Low rate limit for expensive operations."""
+    return limiter.limit(limit)
+
+
+def rate_limit_medium(limit: str = "30/minute"):
+    """Medium rate limit for standard operations."""
+    return limiter.limit(limit)
+
+
+def rate_limit_high(limit: str = "100/minute"):
+    """High rate limit for lightweight operations."""
+    return limiter.limit(limit)
+{%- else %}
+"""Rate limiting - not configured."""
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/sanitize.py

@@ -0,0 +1,271 @@
+"""Input sanitization utilities.
+
+This module provides security-focused input sanitization functions:
+- HTML sanitization to prevent XSS attacks
+- Path traversal prevention for file operations
+- Common input cleaning utilities
+
+Note: SQL injection is prevented by using SQLAlchemy ORM with parameterized queries.
+"""
+
+import html
+import os
+import re
+import unicodedata
+from pathlib import Path
+from typing import TypeVar
+
+# Default allowed HTML tags for rich text content
+DEFAULT_ALLOWED_TAGS = frozenset({
+    "a", "abbr", "acronym", "b", "blockquote", "br", "code",
+    "em", "i", "li", "ol", "p", "pre", "strong", "ul",
+})
+
+# Default allowed HTML attributes
+DEFAULT_ALLOWED_ATTRIBUTES = {
+    "a": frozenset({"href", "title", "rel"}),
+    "abbr": frozenset({"title"}),
+    "acronym": frozenset({"title"}),
+}
+
+
+def sanitize_html(
+    content: str,
+    allowed_tags: frozenset[str] | None = None,
+    strip: bool = True,
+) -> str:
+    """Sanitize HTML content to prevent XSS attacks.
+
+    This is a simple implementation that escapes all HTML.
+    For rich text support, consider using the `bleach` library.
+
+    Args:
+        content: The HTML content to sanitize.
+        allowed_tags: Not used in simple mode (for bleach compatibility).
+        strip: Not used in simple mode (for bleach compatibility).
+
+    Returns:
+        Escaped HTML-safe string.
+
+    Example:
+        >>> sanitize_html("<script>alert('xss')</script>")
+        "&lt;script&gt;alert('xss')&lt;/script&gt;"
+    """
+    if not content:
+        return ""
+
+    return html.escape(content)
+
+
+def sanitize_filename(filename: str, allow_unicode: bool = False) -> str:
+    """Sanitize a filename to prevent path traversal and unsafe characters.
+
+    Args:
+        filename: The filename to sanitize.
+        allow_unicode: Whether to allow unicode characters.
+
+    Returns:
+        A safe filename string.
+
+    Example:
+        >>> sanitize_filename("../../../etc/passwd")
+        "etc_passwd"
+        >>> sanitize_filename("hello world.txt")
+        "hello_world.txt"
+    """
+    if not filename:
+        return ""
+
+    # Normalize unicode
+    if allow_unicode:
+        filename = unicodedata.normalize("NFKC", filename)
+    else:
+        filename = (
+            unicodedata.normalize("NFKD", filename)
+            .encode("ascii", "ignore")
+            .decode("ascii")
+        )
+
+    # Get just the filename (remove any path components)
+    filename = os.path.basename(filename)
+
+    # Remove null bytes
+    filename = filename.replace("\x00", "")
+
+    # Replace path separators and special characters
+    filename = re.sub(r"[/\\:*?\"<>|]", "_", filename)
+
+    # Replace multiple underscores/spaces with single underscore
+    filename = re.sub(r"[\s_]+", "_", filename)
+
+    # Remove leading/trailing underscores and dots
+    filename = filename.strip("._")
+
+    # Ensure we have a valid filename
+    if not filename:
+        return "unnamed"
+
+    return filename
+
+
+def validate_safe_path(
+    base_dir: Path | str,
+    user_path: str,
+) -> Path:
+    """Validate that a user-provided path is within the allowed base directory.
+
+    Prevents path traversal attacks by ensuring the resolved path
+    is within the expected directory.
+
+    Args:
+        base_dir: The base directory that all paths must be within.
+        user_path: The user-provided path to validate.
+
+    Returns:
+        The resolved, safe path.
+
+    Raises:
+        ValueError: If the path would escape the base directory.
+
+    Example:
+        >>> validate_safe_path("/uploads", "../../../etc/passwd")
+        Raises ValueError
+        >>> validate_safe_path("/uploads", "images/photo.jpg")
+        Path("/uploads/images/photo.jpg")
+    """
+    base_path = Path(base_dir).resolve()
+    user_path_sanitized = sanitize_filename(user_path.lstrip("/\\"))
+
+    # Resolve the full path
+    full_path = (base_path / user_path_sanitized).resolve()
+
+    # Check if the resolved path is within the base directory
+    try:
+        full_path.relative_to(base_path)
+    except ValueError as err:
+        raise ValueError(
+            f"Path traversal detected: {user_path!r} would escape {base_dir!r}"
+        ) from err
+
+    return full_path
+
+
+def sanitize_string(
+    value: str,
+    max_length: int | None = None,
+    allow_newlines: bool = True,
+    strip_whitespace: bool = True,
+) -> str:
+    """Sanitize a string input with various options.
+
+    Args:
+        value: The string to sanitize.
+        max_length: Maximum allowed length (truncates if exceeded).
+        allow_newlines: Whether to preserve newlines.
+        strip_whitespace: Whether to strip leading/trailing whitespace.
+
+    Returns:
+        Sanitized string.
+    """
+    if not value:
+        return ""
+
+    # Strip null bytes and other control characters (except newlines if allowed)
+    if allow_newlines:
+        value = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", "", value)
+    else:
+        value = re.sub(r"[\x00-\x1f\x7f]", "", value)
+
+    # Strip whitespace if requested
+    if strip_whitespace:
+        value = value.strip()
+
+    # Truncate if needed
+    if max_length is not None and len(value) > max_length:
+        value = value[:max_length]
+
+    return value
+
+
+def sanitize_email(email: str) -> str:
+    """Basic email sanitization.
+
+    Note: For proper email validation, use Pydantic's EmailStr type.
+    This function only performs basic cleaning.
+
+    Args:
+        email: The email address to sanitize.
+
+    Returns:
+        Lowercased, stripped email.
+    """
+    if not email:
+        return ""
+
+    return email.strip().lower()
+
+
+T = TypeVar("T", int, float)
+
+
+def sanitize_numeric(
+    value: str | int | float,
+    value_type: type[T],
+    min_value: T | None = None,
+    max_value: T | None = None,
+    default: T | None = None,
+) -> T | None:
+    """Sanitize and validate a numeric value.
+
+    Args:
+        value: The value to sanitize (can be string or numeric).
+        value_type: The expected type (int or float).
+        min_value: Minimum allowed value.
+        max_value: Maximum allowed value.
+        default: Default value if conversion fails.
+
+    Returns:
+        The sanitized numeric value, or default if invalid.
+
+    Example:
+        >>> sanitize_numeric("100", int, min_value=0, max_value=1000)
+        100
+        >>> sanitize_numeric("abc", int, default=0)
+        0
+    """
+    try:
+        result = value_type(value)
+
+        if min_value is not None and result < min_value:
+            result = min_value
+        if max_value is not None and result > max_value:
+            result = max_value
+
+        return result
+    except (ValueError, TypeError):
+        return default
+
+
+def escape_sql_like(pattern: str, escape_char: str = "\\") -> str:
+    """Escape special characters in a LIKE pattern.
+
+    Use this when building LIKE queries with user input.
+
+    Args:
+        pattern: The pattern to escape.
+        escape_char: The escape character to use.
+
+    Returns:
+        Escaped pattern safe for use in LIKE queries.
+
+    Example:
+        >>> escape_sql_like("100%")
+        "100\\%"
+        >>> escape_sql_like("under_score")
+        "under\\_score"
+    """
+    # Escape the escape character first, then special chars
+    pattern = pattern.replace(escape_char, escape_char + escape_char)
+    pattern = pattern.replace("%", escape_char + "%")
+    pattern = pattern.replace("_", escape_char + "_")
+    return pattern