FastAPI Deployment — Docker, Uvicorn and Gunicorn

# gunicorn.conf.py — version-control this alongside your application code
# Reference: https://docs.gunicorn.org/en/stable/settings.html

import multiprocessing

# -----------------------------------------------------------------
# Server socket
# -----------------------------------------------------------------
bind = "0.0.0.0:8000"

# -----------------------------------------------------------------
# Worker processes
# For async FastAPI: start low (2-4) and benchmark.
# The (2*CPU)+1 formula is for sync WSGI workers, not async ASGI.
# Each UvicornWorker runs a full asyncio event loop — concurrency
# comes from the event loop, not from worker count.
# -----------------------------------------------------------------
workers = 2  # tune based on load testing, not the formula
worker_class = "uvicorn.workers.UvicornWorker"

# -----------------------------------------------------------------
# Timeouts
# timeout: kill and restart a worker that hasn't responded in N seconds.
# graceful_timeout: time allowed for in-flight requests to complete
#                   after SIGTERM before workers are force-killed.
# Set timeout to at least 2x your slowest endpoint's p99 latency.
# -----------------------------------------------------------------
timeout = 60
graceful_timeout = 30
keepalive = 5

# -----------------------------------------------------------------
# Worker recycling — critical for long-running services
# max_requests: restart each worker after this many requests.
#               Mitigates slow memory leaks without a full redeploy.
# max_requests_jitter: randomises the restart point per worker.
#                      Without jitter, all workers restart simultaneously
#                      (thundering herd) causing a brief availability dip.
# -----------------------------------------------------------------
max_requests = 1000
max_requests_jitter = 100

# -----------------------------------------------------------------
# Logging — always route to stdout/stderr in containers
# accesslog "-" and errorlog "-" send to stdout/stderr so your
# container runtime (Docker, Kubernetes) captures them.
# -----------------------------------------------------------------
accesslog = "-"
errorlog = "-"
loglevel = "info"
# Structured access log format for JSON log aggregators (Datadog, Loki, CloudWatch)
# Fields: remote_addr, request_time, status, response_length, referer, user_agent
access_log_format = '{"remote": "%({X-Forwarded-For}i)s", "method": "%(m)s", "path": "%(U)s", "status": %(s)s, "duration_ms": %(D)s}'

# -----------------------------------------------------------------
# Process naming — visible in ps aux, htop, and monitoring dashboards
# -----------------------------------------------------------------
proc_name = "thecodeforge-api"

# =================================================================
# STAGE 1: Builder
# Installs dependencies and compiles C extensions.
# This stage is discarded — nothing from it ships to production
# except the installed packages we explicitly copy.
# =================================================================
FROM python:3.12-slim AS builder

# Install build tools needed for compiled extensions (psycopg2, cryptography)
# These are NOT copied to the runtime stage
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /build

# Copy only requirements first — layer cache means pip only re-runs
# when requirements.txt changes, not on every code change
COPY requirements.txt .

# Install into an isolated prefix so we can copy the exact set of
# installed packages to the runtime stage cleanly
RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir --prefix=/install -r requirements.txt

# =================================================================
# STAGE 2: Runtime
# Clean slim image — no build tools, no compiler, no pip cache.
# Only the application code and the installed packages.
# Typical size reduction: 60-80% vs naive single-stage build.
# =================================================================
FROM python:3.12-slim AS runtime

# Prevents Python from writing .pyc files to disk
# (not useful in containers — the filesystem is ephemeral)
ENV PYTHONDONTWRITEBYTECODE=1

# Forces Python stdout/stderr to be unbuffered.
# Without this, logs may be lost on crash because they're sitting
# in Python's internal buffer when the process exits.
# Critical for CloudWatch, Stackdriver, and Loki log capture.
ENV PYTHONUNBUFFERED=1

# Add the installed packages from the builder stage to the Python path
ENV PYTHONPATH=/install/lib/python3.12/site-packages

# Install only the runtime system libraries (not build tools)
# libpq is the PostgreSQL client library — needed at runtime for psycopg2
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq5 \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Create a non-privileged user BEFORE copying application code.
# Reason: adduser is layer-cached independently of app code.
# If adduser runs after COPY, a code change invalidates the adduser
# layer and Docker re-runs user creation on every build.
RUN addgroup --system forgegroup \
    && adduser --system --ingroup forgegroup --no-create-home forgeuser

WORKDIR /app

# Copy installed packages from builder stage
COPY --from=builder /install /usr/local

# Copy application code — changes here do NOT invalidate earlier layers
COPY --chown=forgeuser:forgegroup . .

# Switch to non-privileged user
# Running as root in a container is a container escape risk:
# a vulnerability in your app or a dependency could give an attacker
# root access to the host if the container runtime is misconfigured.
USER forgeuser

# Document the port — this is metadata for tooling and humans.
# EXPOSE does NOT control network access. The -p flag in docker run
# or the containerPort in Kubernetes does that.
EXPOSE 8000

# Use gunicorn.conf.py for all configuration — cleaner than
# a long flag string and versionable alongside the application.
# Workers and timeout are set in gunicorn.conf.py, not hardcoded here.
CMD ["gunicorn", "-c", "gunicorn.conf.py", "io.thecodeforge.main:app"]

from contextlib import asynccontextmanager
from typing import AsyncGenerator

from fastapi import FastAPI
from fastapi.responses import JSONResponse
import databases

from io.thecodeforge.config import settings

# -----------------------------------------------------------------
# Database setup
# Using the 'databases' library for async PostgreSQL.
# The connection pool is created inside lifespan, NOT at module level.
# Creating it at module level breaks --preload and causes
# 'Future attached to a different loop' errors after fork().
# -----------------------------------------------------------------
database = databases.Database(
    str(settings.database_url),
    min_size=2,
    max_size=10  # align with your PostgreSQL max_connections / (workers * pods)
)


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
    """
    Manages the full application lifecycle.
    Replaces the deprecated @app.on_event('startup') and @app.on_event('shutdown').

    Startup (before yield):
      - Connect to the database and verify connectivity
      - Warm any caches
      - Register with service discovery if applicable

    Shutdown (after yield):
      - Disconnect from the database (returns connections to the pool,
        then closes pool connections to PostgreSQL)
      - Flush metrics buffers
      - Deregister from service discovery

    Gunicorn's graceful_timeout controls how long workers have to reach
    the shutdown section before being force-killed.
    """
    # --- STARTUP ---
    await database.connect()

    # Verify the database is actually reachable before accepting traffic.
    # This prevents a Kubernetes pod from passing its readiness check
    # before the connection pool is healthy.
    try:
        await database.execute("SELECT 1")
    except Exception as exc:
        # Log and re-raise — the app should not start if the DB is unreachable
        # Gunicorn will log the exception and the worker will exit
        raise RuntimeError(f"Database connectivity check failed at startup: {exc}") from exc

    yield  # Application is live and accepting traffic here

    # --- SHUTDOWN ---
    # This runs when Gunicorn receives SIGTERM and graceful_timeout elapses,
    # or when the container receives SIGTERM directly (Kubernetes rolling update).
    # Closing the pool here prevents connection leak on every deployment.
    await database.disconnect()


app = FastAPI(
    title="TheCodeForge API",
    lifespan=lifespan
)


# -----------------------------------------------------------------
# Liveness probe: is the process alive and the event loop running?
# Kubernetes restarts the pod if this returns non-200 or times out.
# Keep this lightweight — no database calls. If the event loop is
# blocked, this endpoint won't respond and Kubernetes will act.
# -----------------------------------------------------------------
@app.get("/health", tags=["observability"])
async def health() -> dict:
    return {"status": "healthy"}


# -----------------------------------------------------------------
# Readiness probe: is this pod ready to receive traffic?
# Kubernetes stops sending traffic to this pod if this returns non-200.
# Unlike /health, this SHOULD check dependencies — a pod that has
# started but cannot reach its database should not receive traffic.
# -----------------------------------------------------------------
@app.get("/ready", tags=["observability"])
async def ready() -> JSONResponse:
    try:
        await database.execute("SELECT 1")
        return JSONResponse(status_code=200, content={"status": "ready"})
    except Exception as exc:
        # Return 503 — Kubernetes will remove this pod from the load balancer
        # rotation until the database becomes reachable again
        return JSONResponse(
            status_code=503,
            content={"status": "not_ready", "detail": str(exc)}
        )

from functools import lru_cache
from typing import Literal

from pydantic import Field, PostgresDsn, SecretStr, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict


class ForgeSettings(BaseSettings):
    """
    Application configuration loaded from environment variables.

    All fields with FORGE_ prefix are read from the environment.
    In local development, values are loaded from a .env file.
    In production (Kubernetes, ECS), they come from the orchestrator's
    secret injection — never from a file committed to version control.

    Validation happens at instantiation time. If any required field
    is missing or malformed, the app raises ValidationError immediately
    and refuses to start — which is the correct behaviour.
    """

    # PostgresDsn validates the full URL format including scheme, host, port, dbname.
    # An empty string or a URL without 'postgresql://' raises ValidationError.
    # Plain str would accept '' and let your app start, then crash on first DB call.
    database_url: PostgresDsn

    # SecretStr prevents the value from appearing in logs, repr(), or tracebacks.
    # settings.secret_key returns SecretStr — call .get_secret_value() to use the raw string.
    secret_key: SecretStr = Field(min_length=32)

    # Literal type restricts valid values — 'development', 'staging', 'production'.
    # Passing FORGE_ENVIRONMENT=prod (typo) raises ValidationError at startup.
    environment: Literal["development", "staging", "production"] = "production"

    debug: bool = False

    # Database pool sizing — align with (gunicorn workers × pods × this value)
    # to stay under PostgreSQL's max_connections limit
    db_pool_min_size: int = Field(default=2, ge=1, le=10)
    db_pool_max_size: int = Field(default=10, ge=1, le=50)

    # Worker configuration — read by gunicorn.conf.py if you want
    # dynamic worker count based on container CPU allocation
    workers: int = Field(default=2, ge=1, le=16)

    @field_validator("debug", mode="before")
    @classmethod
    def debug_must_be_false_in_production(cls, v, info):
        """Prevent debug mode from running in production accidentally."""
        # info.data may not have 'environment' yet during validation order
        # so we validate this in a post-model validator instead
        return v

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_prefix="FORGE_",
        # Raise an error if any extra environment variables with FORGE_ prefix
        # exist but are not defined in this model — catches typos in var names
        extra="ignore",
        case_sensitive=False,
    )


@lru_cache(maxsize=1)
def get_settings() -> ForgeSettings:
    """
    Returns a cached singleton of the application settings.

    lru_cache ensures the .env file is read and validated exactly once
    at startup, regardless of how many modules call get_settings().

    In tests, override this with:
        app.dependency_overrides[get_settings] = lambda: ForgeSettings(
            database_url='postgresql://test:test@localhost/testdb',
            secret_key='a' * 32,
        )
    """
    return ForgeSettings()


# Module-level singleton for use outside FastAPI's DI system
# (e.g., in gunicorn.conf.py or CLI scripts)
settings = get_settings()

# .env.example — commit this to version control
# Copy to .env and fill in real values for local development
# NEVER commit .env — it is in .gitignore
#
# In production (Kubernetes), these come from Kubernetes Secrets
# mounted as environment variables via secretKeyRef in the pod spec.
# In ECS, they come from AWS Secrets Manager referenced in the task definition.
# On bare VMs, they come from HashiCorp Vault injected at startup.

# PostgreSQL connection string
# Format: postgresql+asyncpg://user:password@host:port/database
FORGE_DATABASE_URL=postgresql+asyncpg://forge_user:change_me@localhost:5432/forge_db

# Must be at least 32 characters — used for JWT signing and session encryption
# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
FORGE_SECRET_KEY=change-me-to-a-64-character-random-string-generated-with-secrets-module

# Environment tag — controls logging level, error detail exposure, and feature flags
# Valid values: development | staging | production
FORGE_ENVIRONMENT=development

# Debug mode — NEVER set to true in staging or production
FORGE_DEBUG=false

# Database connection pool sizing
# Max connections consumed = FORGE_DB_POOL_MAX_SIZE × gunicorn_workers × pod_count
# Must be less than PostgreSQL's max_connections (default: 100)
FORGE_DB_POOL_MIN_SIZE=2
FORGE_DB_POOL_MAX_SIZE=5

# This file shows the complete main.py — combining lifespan, health,
# and readiness into the single application entry point.
# The lifespan implementation from the previous section is included
# here in full context.

from contextlib import asynccontextmanager
from typing import AsyncGenerator

import databases
from fastapi import FastAPI
from fastapi.responses import JSONResponse

from io.thecodeforge.config import get_settings

settings = get_settings()

database = databases.Database(
    str(settings.database_url),
    min_size=settings.db_pool_min_size,
    max_size=settings.db_pool_max_size,
)


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
    # STARTUP
    await database.connect()
    try:
        await database.execute("SELECT 1")
    except Exception as exc:
        raise RuntimeError(f"Database unreachable at startup: {exc}") from exc

    yield  # serving traffic

    # SHUTDOWN — runs on SIGTERM via Gunicorn graceful_timeout
    await database.disconnect()


app = FastAPI(title="TheCodeForge API", lifespan=lifespan)


@app.get("/health", tags=["observability"])
async def health() -> dict:
    """
    Liveness probe — is this process alive and the event loop running?

    Kubernetes action on failure: RESTART the pod.
    Keep this dependency-free. If this endpoint calls the database
    and the DB goes down, Kubernetes will restart all pods — turning
    a DB outage into a total availability incident.

    A blocked event loop will prevent this endpoint from responding,
    which is exactly the signal Kubernetes needs to restart the pod.
    """
    return {"status": "healthy"}


@app.get("/ready", tags=["observability"])
async def ready() -> JSONResponse:
    """
    Readiness probe — can this pod receive traffic?

    Kubernetes action on failure: REMOVE from load balancer (no restart).
    This SHOULD check actual dependencies. A pod that's alive but
    disconnected from its database should not receive traffic.

    Return 503 to signal 'alive but not ready' — Kubernetes stops
    routing traffic to this pod without restarting it.
    """
    try:
        await database.execute("SELECT 1")
        return JSONResponse(status_code=200, content={"status": "ready"})
    except Exception as exc:
        return JSONResponse(
            status_code=503,
            content={
                "status": "not_ready",
                "detail": "database unreachable",
                # Do not expose exc details in production — log them instead
            }
        )