fastapi-fullstack 0.1.7__py3-none-any.whl

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/api/routes/v1/health.py

@@ -0,0 +1,227 @@
+"""Health check endpoints.
+
+Provides Kubernetes-compatible health check endpoints:
+- /health - Simple liveness check
+- /health/live - Detailed liveness probe
+- /health/ready - Readiness probe with dependency checks
+"""
+{%- if cookiecutter.use_database or cookiecutter.enable_redis %}
+# ruff: noqa: I001 - Imports structured for Jinja2 template conditionals
+{%- endif %}
+
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+from sqlalchemy import text
+{%- endif %}
+
+from app.core.config import settings
+{%- if cookiecutter.use_database or cookiecutter.enable_redis %}
+from app.api.deps import {% if cookiecutter.use_database %}DBSession{% endif %}{% if cookiecutter.use_database and cookiecutter.enable_redis %}, {% endif %}{% if cookiecutter.enable_redis %}Redis{% endif %}
+
+{%- endif %}
+
+router = APIRouter()
+
+
+def _build_health_response(
+    status: str,
+    checks: dict[str, Any] | None = None,
+    details: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a structured health response."""
+    response: dict[str, Any] = {
+        "status": status,
+        "timestamp": datetime.now(UTC).isoformat(),
+        "service": settings.PROJECT_NAME,
+    }
+    if checks is not None:
+        response["checks"] = checks
+    if details is not None:
+        response["details"] = details
+    return response
+
+
+@router.get("/health")
+async def health_check() -> dict[str, str]:
+    """Simple liveness probe - check if application is running.
+
+    This is a lightweight check that should always succeed if the
+    application is running. Use this for basic connectivity tests.
+
+    Returns:
+        {"status": "healthy"}
+    """
+    return {"status": "healthy"}
+
+
+@router.get("/health/live")
+async def liveness_probe() -> dict[str, Any]:
+    """Detailed liveness probe for Kubernetes.
+
+    This endpoint is designed for Kubernetes liveness probes.
+    It checks if the application process is alive and responding.
+    Failure indicates the container should be restarted.
+
+    Returns:
+        Structured response with timestamp and service info.
+    """
+    return _build_health_response(
+        status="alive",
+        details={
+            "version": getattr(settings, "VERSION", "1.0.0"),
+            "environment": settings.ENVIRONMENT,
+        },
+    )
+
+
+@router.get("/health/ready", response_model=None)
+async def readiness_probe(
+{%- if cookiecutter.use_database %}
+    db: DBSession,
+{%- endif %}
+{%- if cookiecutter.enable_redis %}
+    redis: Redis,
+{%- endif %}
+) -> dict[str, Any] | JSONResponse:
+    """Readiness probe for Kubernetes.
+
+    This endpoint checks if all dependencies are ready to handle traffic.
+    It verifies database connections, Redis, and other critical services.
+    Failure indicates traffic should be temporarily diverted.
+
+    Checks performed:
+    {%- if cookiecutter.use_database %}
+    - Database connectivity
+    {%- endif %}
+    {%- if cookiecutter.enable_redis %}
+    - Redis connectivity
+    {%- endif %}
+
+    Returns:
+        Structured response with individual check results.
+        Returns 503 if any critical check fails.
+    """
+    checks: dict[str, dict[str, Any]] = {}
+
+{%- if cookiecutter.use_postgresql %}
+    # Database check
+    try:
+        start = datetime.now(UTC)
+        await db.execute(text("SELECT 1"))
+        latency_ms = (datetime.now(UTC) - start).total_seconds() * 1000
+        checks["database"] = {
+            "status": "healthy",
+            "latency_ms": round(latency_ms, 2),
+            "type": "postgresql",
+        }
+    except Exception as e:
+        checks["database"] = {
+            "status": "unhealthy",
+            "error": str(e),
+            "type": "postgresql",
+        }
+{%- endif %}
+
+{%- if cookiecutter.use_mongodb %}
+    # Database check
+    try:
+        start = datetime.now(UTC)
+        await db.command("ping")
+        latency_ms = (datetime.now(UTC) - start).total_seconds() * 1000
+        checks["database"] = {
+            "status": "healthy",
+            "latency_ms": round(latency_ms, 2),
+            "type": "mongodb",
+        }
+    except Exception as e:
+        checks["database"] = {
+            "status": "unhealthy",
+            "error": str(e),
+            "type": "mongodb",
+        }
+{%- endif %}
+
+{%- if cookiecutter.use_sqlite %}
+    # Database check
+    try:
+        start = datetime.now(UTC)
+        db.execute(text("SELECT 1"))
+        latency_ms = (datetime.now(UTC) - start).total_seconds() * 1000
+        checks["database"] = {
+            "status": "healthy",
+            "latency_ms": round(latency_ms, 2),
+            "type": "sqlite",
+        }
+    except Exception as e:
+        checks["database"] = {
+            "status": "unhealthy",
+            "error": str(e),
+            "type": "sqlite",
+        }
+{%- endif %}
+
+{%- if cookiecutter.enable_redis %}
+    # Redis check
+    try:
+        start = datetime.now(UTC)
+        is_healthy = await redis.ping()
+        latency_ms = (datetime.now(UTC) - start).total_seconds() * 1000
+        if is_healthy:
+            checks["redis"] = {
+                "status": "healthy",
+                "latency_ms": round(latency_ms, 2),
+            }
+        else:
+            checks["redis"] = {
+                "status": "unhealthy",
+                "error": "Ping failed",
+            }
+    except Exception as e:
+        checks["redis"] = {
+            "status": "unhealthy",
+            "error": str(e),
+        }
+{%- endif %}
+
+    # Determine overall health
+    all_healthy = all(
+        check.get("status") == "healthy" for check in checks.values()
+    ) if checks else True
+
+    response_data = _build_health_response(
+        status="ready" if all_healthy else "not_ready",
+        checks=checks,
+    )
+
+    if not all_healthy:
+        return JSONResponse(status_code=503, content=response_data)
+
+    return response_data
+
+
+# Backward compatibility - keep /ready endpoint
+@router.get("/ready", response_model=None)
+async def readiness_check(
+{%- if cookiecutter.use_database %}
+    db: DBSession,
+{%- endif %}
+{%- if cookiecutter.enable_redis %}
+    redis: Redis,
+{%- endif %}
+) -> dict[str, Any] | JSONResponse:
+    """Readiness check (alias for /health/ready).
+
+    Deprecated: Use /health/ready instead.
+    """
+    return await readiness_probe(
+{%- if cookiecutter.use_database %}
+        db=db,
+{%- endif %}
+{%- if cookiecutter.enable_redis %}
+        redis=redis,
+{%- endif %}
+    )

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/api/routes/v1/items.py

@@ -0,0 +1,275 @@
+{%- if cookiecutter.include_example_crud and cookiecutter.use_database %}
+# ruff: noqa: I001 - Imports structured for Jinja2 template conditionals
+"""Item CRUD routes - example API endpoints.
+
+This module demonstrates a complete CRUD API for the Item entity.
+You can use it as a template for creating your own endpoints.
+
+The endpoints are:
+- GET /items - List all items (with pagination if enabled)
+- POST /items - Create a new item
+- GET /items/{item_id} - Get a single item by ID
+- PATCH /items/{item_id} - Update an item
+- DELETE /items/{item_id} - Delete an item
+"""
+{%- if cookiecutter.use_postgresql %}
+
+from uuid import UUID
+{%- endif %}
+
+from fastapi import APIRouter, status
+{%- if cookiecutter.enable_pagination and cookiecutter.use_postgresql %}
+from fastapi_pagination import Page
+from fastapi_pagination.ext.sqlalchemy import paginate
+from sqlalchemy import select
+{%- elif cookiecutter.enable_pagination and cookiecutter.use_sqlite %}
+from fastapi_pagination import Page
+from fastapi_pagination.ext.sqlalchemy import paginate
+from sqlalchemy import select
+{%- endif %}
+
+{%- if cookiecutter.use_mongodb %}
+from app.api.deps import ItemSvc
+{%- elif cookiecutter.enable_pagination %}
+from app.api.deps import DBSession, ItemSvc
+{%- else %}
+from app.api.deps import ItemSvc
+{%- endif %}
+{%- if cookiecutter.enable_pagination and (cookiecutter.use_postgresql or cookiecutter.use_sqlite) %}
+from app.db.models.item import Item
+{%- endif %}
+from app.schemas.item import ItemCreate, ItemRead, ItemUpdate
+
+router = APIRouter()
+
+
+{%- if cookiecutter.use_postgresql %}
+
+{%- if cookiecutter.enable_pagination %}
+
+
+@router.get("", response_model=Page[ItemRead])
+async def list_items(db: DBSession):
+    """List all items with pagination.
+
+    Returns a paginated list of items. Use query parameters
+    `page` and `size` to control pagination.
+    """
+    return await paginate(db, select(Item))
+{%- else %}
+
+
+@router.get("", response_model=list[ItemRead])
+async def list_items(
+    item_service: ItemSvc,
+    skip: int = 0,
+    limit: int = 100,
+):
+    """List all items.
+
+    Returns a list of items with offset-based pagination.
+    """
+    return await item_service.get_multi(skip=skip, limit=limit)
+{%- endif %}
+
+
+@router.post("", response_model=ItemRead, status_code=status.HTTP_201_CREATED)
+async def create_item(
+    item_in: ItemCreate,
+    item_service: ItemSvc,
+):
+    """Create a new item.
+
+    Creates an item with the provided title and optional description.
+    """
+    return await item_service.create(item_in)
+
+
+@router.get("/{item_id}", response_model=ItemRead)
+async def get_item(
+    item_id: UUID,
+    item_service: ItemSvc,
+):
+    """Get a single item by ID.
+
+    Raises 404 if the item does not exist.
+    """
+    return await item_service.get_by_id(item_id)
+
+
+@router.patch("/{item_id}", response_model=ItemRead)
+async def update_item(
+    item_id: UUID,
+    item_in: ItemUpdate,
+    item_service: ItemSvc,
+):
+    """Update an item.
+
+    Supports partial updates - only provided fields are updated.
+    Raises 404 if the item does not exist.
+    """
+    return await item_service.update(item_id, item_in)
+
+
+@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_item(
+    item_id: UUID,
+    item_service: ItemSvc,
+):
+    """Delete an item.
+
+    Raises 404 if the item does not exist.
+    """
+    await item_service.delete(item_id)
+
+
+{%- elif cookiecutter.use_sqlite %}
+
+{%- if cookiecutter.enable_pagination %}
+
+
+@router.get("", response_model=Page[ItemRead])
+def list_items(db: DBSession):
+    """List all items with pagination.
+
+    Returns a paginated list of items. Use query parameters
+    `page` and `size` to control pagination.
+    """
+    return paginate(db, select(Item))
+{%- else %}
+
+
+@router.get("", response_model=list[ItemRead])
+def list_items(
+    item_service: ItemSvc,
+    skip: int = 0,
+    limit: int = 100,
+):
+    """List all items.
+
+    Returns a list of items with offset-based pagination.
+    """
+    return item_service.get_multi(skip=skip, limit=limit)
+{%- endif %}
+
+
+@router.post("", response_model=ItemRead, status_code=status.HTTP_201_CREATED)
+def create_item(
+    item_in: ItemCreate,
+    item_service: ItemSvc,
+):
+    """Create a new item.
+
+    Creates an item with the provided title and optional description.
+    """
+    return item_service.create(item_in)
+
+
+@router.get("/{item_id}", response_model=ItemRead)
+def get_item(
+    item_id: str,
+    item_service: ItemSvc,
+):
+    """Get a single item by ID.
+
+    Raises 404 if the item does not exist.
+    """
+    return item_service.get_by_id(item_id)
+
+
+@router.patch("/{item_id}", response_model=ItemRead)
+def update_item(
+    item_id: str,
+    item_in: ItemUpdate,
+    item_service: ItemSvc,
+):
+    """Update an item.
+
+    Supports partial updates - only provided fields are updated.
+    Raises 404 if the item does not exist.
+    """
+    return item_service.update(item_id, item_in)
+
+
+@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_item(
+    item_id: str,
+    item_service: ItemSvc,
+):
+    """Delete an item.
+
+    Raises 404 if the item does not exist.
+    """
+    item_service.delete(item_id)
+
+
+{%- elif cookiecutter.use_mongodb %}
+
+
+@router.get("", response_model=list[ItemRead])
+async def list_items(
+    item_service: ItemSvc,
+    skip: int = 0,
+    limit: int = 100,
+):
+    """List all items.
+
+    Returns a list of items with offset-based pagination.
+    """
+    return await item_service.get_multi(skip=skip, limit=limit)
+
+
+@router.post("", response_model=ItemRead, status_code=status.HTTP_201_CREATED)
+async def create_item(
+    item_in: ItemCreate,
+    item_service: ItemSvc,
+):
+    """Create a new item.
+
+    Creates an item with the provided title and optional description.
+    """
+    return await item_service.create(item_in)
+
+
+@router.get("/{item_id}", response_model=ItemRead)
+async def get_item(
+    item_id: str,
+    item_service: ItemSvc,
+):
+    """Get a single item by ID.
+
+    Raises 404 if the item does not exist.
+    """
+    return await item_service.get_by_id(item_id)
+
+
+@router.patch("/{item_id}", response_model=ItemRead)
+async def update_item(
+    item_id: str,
+    item_in: ItemUpdate,
+    item_service: ItemSvc,
+):
+    """Update an item.
+
+    Supports partial updates - only provided fields are updated.
+    Raises 404 if the item does not exist.
+    """
+    return await item_service.update(item_id, item_in)
+
+
+@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_item(
+    item_id: str,
+    item_service: ItemSvc,
+):
+    """Delete an item.
+
+    Raises 404 if the item does not exist.
+    """
+    await item_service.delete(item_id)
+
+
+{%- endif %}
+{%- else %}
+"""Item routes - not configured."""
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/api/routes/v1/oauth.py

@@ -0,0 +1,205 @@
+{%- if cookiecutter.enable_oauth %}
+"""OAuth2 authentication routes."""
+
+from urllib.parse import urlencode
+
+from fastapi import APIRouter, Request
+from fastapi.responses import RedirectResponse
+
+from app.api.deps import UserSvc
+from app.core.oauth import oauth
+from app.core.security import create_access_token, create_refresh_token
+
+router = APIRouter()
+
+# Frontend URL for OAuth callback redirect
+FRONTEND_URL = "http://localhost:{{ cookiecutter.frontend_port }}"
+
+{%- if cookiecutter.enable_oauth_google %}
+
+
+@router.get("/google/login")
+async def google_login(request: Request):
+    """Redirect to Google OAuth2 login page."""
+    from app.core.config import settings
+
+    redirect_uri = settings.GOOGLE_REDIRECT_URI
+    return await oauth.google.authorize_redirect(request, redirect_uri)
+
+
+{%- if cookiecutter.use_postgresql %}
+
+
+@router.get("/google/callback")
+async def google_callback(request: Request, user_service: UserSvc):
+    """Handle Google OAuth2 callback.
+
+    Creates a new user if one doesn't exist with the Google email,
+    or returns tokens for existing user. Redirects to frontend with tokens.
+    """
+    try:
+        token = await oauth.google.authorize_access_token(request)
+        user_info = token.get("userinfo")
+
+        if not user_info:
+            params = urlencode({"error": "Failed to get user info from Google"})
+            return RedirectResponse(url=f"{FRONTEND_URL}/login?{params}")
+
+        email = user_info.get("email")
+        google_id = user_info.get("sub")
+        full_name = user_info.get("name")
+
+        # Try to find existing user by OAuth ID
+        user = await user_service.get_by_oauth("google", google_id)
+
+        if not user:
+            # Try to find by email (link existing account)
+            user = await user_service.get_by_email(email)
+            if user:
+                # Link OAuth to existing account
+                user = await user_service.link_oauth(user.id, "google", google_id)
+            else:
+                # Create new user
+                user = await user_service.create_oauth_user(
+                    email=email,
+                    full_name=full_name,
+                    oauth_provider="google",
+                    oauth_id=google_id,
+                )
+
+        access_token = create_access_token(subject=str(user.id))
+        refresh_token = create_refresh_token(subject=str(user.id))
+
+        # Redirect to frontend with tokens
+        params = urlencode({
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+        })
+        return RedirectResponse(url=f"{FRONTEND_URL}/auth/callback?{params}")
+
+    except Exception as e:
+        params = urlencode({"error": str(e)})
+        return RedirectResponse(url=f"{FRONTEND_URL}/login?{params}")
+
+
+{%- elif cookiecutter.use_mongodb %}
+
+
+@router.get("/google/callback")
+async def google_callback(request: Request, user_service: UserSvc):
+    """Handle Google OAuth2 callback.
+
+    Creates a new user if one doesn't exist with the Google email,
+    or returns tokens for existing user. Redirects to frontend with tokens.
+    """
+    try:
+        token = await oauth.google.authorize_access_token(request)
+        user_info = token.get("userinfo")
+
+        if not user_info:
+            params = urlencode({"error": "Failed to get user info from Google"})
+            return RedirectResponse(url=f"{FRONTEND_URL}/login?{params}")
+
+        email = user_info.get("email")
+        google_id = user_info.get("sub")
+        full_name = user_info.get("name")
+
+        # Try to find existing user by OAuth ID
+        user = await user_service.get_by_oauth("google", google_id)
+
+        if not user:
+            # Try to find by email (link existing account)
+            user = await user_service.get_by_email(email)
+            if user:
+                # Link OAuth to existing account
+                user = await user_service.link_oauth(str(user.id), "google", google_id)
+            else:
+                # Create new user
+                user = await user_service.create_oauth_user(
+                    email=email,
+                    full_name=full_name,
+                    oauth_provider="google",
+                    oauth_id=google_id,
+                )
+
+        access_token = create_access_token(subject=str(user.id))
+        refresh_token = create_refresh_token(subject=str(user.id))
+
+        # Redirect to frontend with tokens
+        params = urlencode({
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+        })
+        return RedirectResponse(url=f"{FRONTEND_URL}/auth/callback?{params}")
+
+    except Exception as e:
+        params = urlencode({"error": str(e)})
+        return RedirectResponse(url=f"{FRONTEND_URL}/login?{params}")
+
+
+{%- elif cookiecutter.use_sqlite %}
+
+
+@router.get("/google/callback")
+def google_callback(request: Request, user_service: UserSvc):
+    """Handle Google OAuth2 callback.
+
+    Creates a new user if one doesn't exist with the Google email,
+    or returns tokens for existing user. Redirects to frontend with tokens.
+    """
+    import asyncio
+
+    try:
+        # Run async OAuth in sync context
+        loop = asyncio.new_event_loop()
+        token = loop.run_until_complete(oauth.google.authorize_access_token(request))
+        loop.close()
+
+        user_info = token.get("userinfo")
+
+        if not user_info:
+            params = urlencode({"error": "Failed to get user info from Google"})
+            return RedirectResponse(url=f"{FRONTEND_URL}/login?{params}")
+
+        email = user_info.get("email")
+        google_id = user_info.get("sub")
+        full_name = user_info.get("name")
+
+        # Try to find existing user by OAuth ID
+        user = user_service.get_by_oauth("google", google_id)
+
+        if not user:
+            # Try to find by email (link existing account)
+            user = user_service.get_by_email(email)
+            if user:
+                # Link OAuth to existing account
+                user = user_service.link_oauth(user.id, "google", google_id)
+            else:
+                # Create new user
+                user = user_service.create_oauth_user(
+                    email=email,
+                    full_name=full_name,
+                    oauth_provider="google",
+                    oauth_id=google_id,
+                )
+
+        access_token = create_access_token(subject=user.id)
+        refresh_token = create_refresh_token(subject=user.id)
+
+        # Redirect to frontend with tokens
+        params = urlencode({
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+        })
+        return RedirectResponse(url=f"{FRONTEND_URL}/auth/callback?{params}")
+
+    except Exception as e:
+        params = urlencode({"error": str(e)})
+        return RedirectResponse(url=f"{FRONTEND_URL}/login?{params}")
+
+
+{%- endif %}
+{%- endif %}
+{%- else %}
+"""OAuth routes - not configured."""
+{%- endif %}