feat: add production-ready configurations, distributed locking, storage backends, and metrics

- Added `.env.prod.example` for production environment configuration
- Introduced distributed locking layer (Redis and file-based implementations)
- Added abstraction for storage backends (local, S3, MinIO support)
- Implemented Prometheus metrics for monitoring performance
- Added database indexes to optimize paste queries
- Enhanced exception handling with new custom exception classes

Author: Pdzly

.env.example

@@ -1,12 +1,21 @@
 # DevBin Backend Environment Configuration
 
+# Environment (dev, staging, prod)
+APP_ENVIRONMENT=dev
+
 # Server Configuration
 APP_PORT=8000
 APP_HOST=0.0.0.0
 APP_WORKERS=1
 APP_RELOAD=false
 APP_DEBUG=false
 
+# Logging Configuration
+# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+APP_LOG_LEVEL=INFO
+# Log format: text (human-readable) or json (structured, for log aggregation)
+APP_LOG_FORMAT=text
+
 # Database Configuration
 APP_DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/devbin
 
@@ -34,22 +43,61 @@ APP_BASE_FOLDER_PATH=./files
 APP_MIN_STORAGE_MB=1024
 APP_KEEP_DELETED_PASTES_TIME_HOURS=336
 
+# Storage Configuration
+# Storage backend: local, s3, or minio (default: local)
+APP_STORAGE_TYPE=local
+
+# S3 Configuration (when STORAGE_TYPE=s3)
+# APP_S3_BUCKET_NAME=devbin-pastes
+# APP_S3_REGION=us-east-1
+# APP_S3_ACCESS_KEY=your_access_key
+# APP_S3_SECRET_KEY=your_secret_key
+# APP_S3_ENDPOINT_URL=  # Optional: custom S3 endpoint URL
+
+# MinIO Configuration (when STORAGE_TYPE=minio)
+# APP_S3_BUCKET_NAME=devbin-pastes
+# APP_MINIO_ENDPOINT=minio:9000
+# APP_MINIO_ACCESS_KEY=minioadmin
+# APP_MINIO_SECRET_KEY=minioadmin
+# APP_MINIO_SECURE=true
+
 # Compression settings
+# Compression is most effective for content >= 2KB (achieves 30-40% compression ratio)
+# Smaller content compresses poorly and wastes CPU cycles
 APP_COMPRESSION_ENABLED=true
-APP_COMPRESSION_THRESHOLD_BYTES=512
+APP_COMPRESSION_THRESHOLD_BYTES=2048
 APP_COMPRESSION_LEVEL=6
 
 # Caching
+# Cache backend: memory (default) or redis
+APP_CACHE_TYPE=memory
 APP_CACHE_SIZE_LIMIT=1000
 APP_CACHE_TTL=300
 
+# Redis Configuration (when CACHE_TYPE=redis or LOCK_TYPE=redis)
+# APP_REDIS_HOST=localhost
+# APP_REDIS_PORT=6379
+# APP_REDIS_DB=0
+# APP_REDIS_PASSWORD=  # Optional password
+
+# Distributed Locking
+# Lock backend: file (default) or redis
+APP_LOCK_TYPE=file
+
 # Privacy Settings
 APP_SAVE_USER_AGENT=false
 APP_SAVE_IP_ADDRESS=false
 
 # Optional: Rate limit bypass token for trusted apps
 # APP_BYPASS_TOKEN=your_secret_bypass_token_here
 
+# Metrics Authentication
+# Optional: Secure the Prometheus /metrics endpoint with Bearer token authentication
+# If not set, metrics endpoint remains publicly accessible
+# Production deployments should set this to a strong random token
+# APP_METRICS_TOKEN=your_secure_random_token_here
+# Example generation: openssl rand -hex 32
+
 # Frontend configurations
 API_BASE_URL=http://devbin:8000
 PORT=3000

backend/.env.example

@@ -1,12 +1,21 @@
 # DevBin Backend Environment Configuration
 
+# Environment (dev, staging, prod)
+APP_ENVIRONMENT=dev
+
 # Server Configuration
 APP_PORT=8000
 APP_HOST=0.0.0.0
 APP_WORKERS=1
 APP_RELOAD=false
 APP_DEBUG=false
 
+# Logging Configuration
+# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+APP_LOG_LEVEL=INFO
+# Log format: text (human-readable) or json (structured, for log aggregation)
+APP_LOG_FORMAT=text
+
 # Database Configuration
 APP_DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/devbin
 
@@ -34,18 +43,57 @@ APP_BASE_FOLDER_PATH=./files
 APP_MIN_STORAGE_MB=1024
 APP_KEEP_DELETED_PASTES_TIME_HOURS=336
 
+# Storage Configuration
+# Storage backend: local, s3, or minio (default: local)
+APP_STORAGE_TYPE=local
+
+# S3 Configuration (when STORAGE_TYPE=s3)
+# APP_S3_BUCKET_NAME=devbin-pastes
+# APP_S3_REGION=us-east-1
+# APP_S3_ACCESS_KEY=your_access_key
+# APP_S3_SECRET_KEY=your_secret_key
+# APP_S3_ENDPOINT_URL=  # Optional: custom S3 endpoint URL
+
+# MinIO Configuration (when STORAGE_TYPE=minio)
+# APP_S3_BUCKET_NAME=devbin-pastes
+# APP_MINIO_ENDPOINT=minio:9000
+# APP_MINIO_ACCESS_KEY=minioadmin
+# APP_MINIO_SECRET_KEY=minioadmin
+# APP_MINIO_SECURE=true
+
 # Compression settings
+# Compression is most effective for content >= 2KB (achieves 30-40% compression ratio)
+# Smaller content compresses poorly and wastes CPU cycles
 APP_COMPRESSION_ENABLED=true
-APP_COMPRESSION_THRESHOLD_BYTES=512
+APP_COMPRESSION_THRESHOLD_BYTES=2048
 APP_COMPRESSION_LEVEL=6
 
 # Caching
+# Cache backend: memory (default) or redis
+APP_CACHE_TYPE=memory
 APP_CACHE_SIZE_LIMIT=1000
 APP_CACHE_TTL=300
 
+# Redis Configuration (when CACHE_TYPE=redis or LOCK_TYPE=redis)
+# APP_REDIS_HOST=localhost
+# APP_REDIS_PORT=6379
+# APP_REDIS_DB=0
+# APP_REDIS_PASSWORD=  # Optional password
+
+# Distributed Locking
+# Lock backend: file (default) or redis
+APP_LOCK_TYPE=file
+
 # Privacy Settings
 APP_SAVE_USER_AGENT=false
 APP_SAVE_IP_ADDRESS=false
 
 # Optional: Rate limit bypass token for trusted apps
 # APP_BYPASS_TOKEN=your_secret_bypass_token_here
+
+# Metrics Authentication
+# Optional: Secure the Prometheus /metrics endpoint with Bearer token authentication
+# If not set, metrics endpoint remains publicly accessible
+# Production deployments should set this to a strong random token
+# APP_METRICS_TOKEN=your_secure_random_token_here
+# Example generation: openssl rand -hex 32

backend/.env.prod.example

@@ -0,0 +1,92 @@
+# DevBin Backend - Production Environment Configuration
+# Copy this file to .env and configure with your production values
+
+# Environment - MUST be 'prod' for production
+APP_ENVIRONMENT=prod
+
+# Server Configuration
+APP_PORT=8000
+APP_HOST=0.0.0.0
+# Set to auto-scale based on CPU cores (recommended for production)
+APP_WORKERS=true
+# Disable auto-reload in production for stability
+APP_RELOAD=false
+# Disable debug mode in production (REQUIRED)
+APP_DEBUG=false
+
+# Logging Configuration
+# Use INFO or WARNING in production to reduce log volume
+APP_LOG_LEVEL=INFO
+# Use JSON format for structured logging in production (RECOMMENDED)
+APP_LOG_FORMAT=json
+
+# Database Configuration
+# Use strong credentials and restrict network access
+APP_DATABASE_URL=postgresql+asyncpg://devbin_user:CHANGE_ME_STRONG_PASSWORD@db-server:5432/devbin_prod
+
+# Security - HTTPS
+# Enable HTTPS redirect if SSL is terminated at the application level
+# Keep false if using reverse proxy (nginx, traefik, caddy, etc.)
+APP_ENFORCE_HTTPS=false
+
+# Security - CORS
+# Specify exact allowed domains (REQUIRED in production)
+APP_CORS_DOMAINS=["https://devbin.example.com","https://app.devbin.example.com"]
+# Wildcard MUST be disabled in production
+APP_ALLOW_CORS_WILDCARD=false
+
+# Trusted Hosts (for X-Forwarded-For header)
+# Add your load balancer/proxy IPs
+APP_TRUSTED_HOSTS=["10.0.0.0/8","172.16.0.0/12"]
+
+# Paste Configuration
+APP_MAX_CONTENT_LENGTH=10000
+APP_BASE_FOLDER_PATH=/var/lib/devbin/files
+# Higher threshold for production storage
+APP_MIN_STORAGE_MB=10240
+# Retention policy: 336 hours = 14 days
+APP_KEEP_DELETED_PASTES_TIME_HOURS=336
+
+# Storage Configuration
+# Options: local, s3, minio (s3/minio recommended for production)
+APP_STORAGE_TYPE=s3
+
+# S3 Configuration (when STORAGE_TYPE=s3)
+APP_S3_BUCKET_NAME=devbin-prod-pastes
+APP_S3_REGION=us-east-1
+APP_S3_ACCESS_KEY=AKIAXXXXXXXXXXXXXXXX
+APP_S3_SECRET_KEY=CHANGE_ME_SECRET_KEY
+# APP_S3_ENDPOINT_URL=  # Optional: custom S3 endpoint URL
+
+# MinIO Configuration (when STORAGE_TYPE=minio)
+# APP_S3_BUCKET_NAME=devbin-prod-pastes
+# APP_MINIO_ENDPOINT=minio.internal:9000
+# APP_MINIO_ACCESS_KEY=CHANGE_ME_ACCESS_KEY
+# APP_MINIO_SECRET_KEY=CHANGE_ME_SECRET_KEY
+# APP_MINIO_SECURE=true
+
+# Compression settings (optimized for production)
+APP_COMPRESSION_ENABLED=true
+APP_COMPRESSION_THRESHOLD_BYTES=2048
+APP_COMPRESSION_LEVEL=6
+
+# Caching (Redis recommended for production)
+APP_CACHE_TYPE=redis
+APP_CACHE_SIZE_LIMIT=10000
+APP_CACHE_TTL=300
+
+# Redis Configuration (for cache and distributed locking)
+APP_REDIS_HOST=redis.internal
+APP_REDIS_PORT=6379
+APP_REDIS_DB=0
+APP_REDIS_PASSWORD=CHANGE_ME_REDIS_PASSWORD
+
+# Distributed Locking (Redis recommended for multi-instance deployments)
+APP_LOCK_TYPE=redis
+
+# Privacy Settings (configure based on your privacy policy)
+APP_SAVE_USER_AGENT=false
+APP_SAVE_IP_ADDRESS=false
+
+# Optional: Rate limit bypass token for trusted apps/monitoring
+# APP_BYPASS_TOKEN=CHANGE_ME_SECURE_RANDOM_TOKEN_HERE

backend/alembic/versions/4e57d32ab2ac_add_paste_indexes.py

@@ -0,0 +1,34 @@
+"""add_paste_indexes
+
+Revision ID: 4e57d32ab2ac
+Revises: 6c5a2c764fb8
+Create Date: 2025-12-25 20:15:09.567249
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '4e57d32ab2ac'
+down_revision: Union[str, Sequence[str], None] = '6c5a2c764fb8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # Add indexes to optimize paste queries
+    op.create_index('idx_pastes_expires_at', 'pastes', ['expires_at'])
+    op.create_index('idx_pastes_deleted_at', 'pastes', ['deleted_at'])
+    op.create_index('idx_pastes_created_at', 'pastes', ['created_at'])
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # Remove indexes
+    op.drop_index('idx_pastes_created_at', 'pastes')
+    op.drop_index('idx_pastes_deleted_at', 'pastes')
+    op.drop_index('idx_pastes_expires_at', 'pastes')

backend/app/api/routes.py

@@ -2,16 +2,50 @@
 
 from dependency_injector.wiring import Provide, inject
 from fastapi import APIRouter, Depends
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
 from starlette.requests import Request
+from starlette.responses import Response
 
 from app.api.subroutes.pastes import pastes_route
+from app.config import config
 from app.containers import Container
+from app.exceptions import UnauthorizedError
 from app.ratelimit import limiter
 from app.services.health_service import HealthService
 
 router = APIRouter()
 
 
+# Metrics authentication
+metrics_security = HTTPBearer(auto_error=False, description="Metrics access token")
+
+
+def verify_metrics_token(
+    credentials: HTTPAuthorizationCredentials | None = Depends(metrics_security)
+) -> None:
+    """
+    Verify Bearer token for metrics endpoint.
+
+    If METRICS_TOKEN is not configured, endpoint is publicly accessible.
+    If configured, valid Bearer token is required.
+
+    Raises:
+        UnauthorizedError: If token is missing or invalid when authentication is required
+    """
+    # If no token configured, allow public access
+    if not config.METRICS_TOKEN:
+        return
+
+    # Token is configured, authentication required
+    if not credentials:
+        raise UnauthorizedError("Bearer token required for metrics access")
+
+    # Validate token (plain string comparison)
+    if credentials.credentials != config.METRICS_TOKEN:
+        raise UnauthorizedError("Invalid metrics token")
+
+
 @router.get("/health")
 @limiter.limit("60/minute")
 @inject
@@ -22,4 +56,30 @@ async def health(
     return await health_service.check()
 
 
+@router.get("/ready")
+@limiter.limit("60/minute")
+@inject
+async def ready(
+        request: Request,
+        health_service: HealthService = Depends(Provide[Container.health_service]),
+):
+    """Readiness endpoint for load balancers."""
+    return await health_service.ready()
+
+
+@router.get("/metrics")
+async def metrics(
+    _: None = Depends(verify_metrics_token)
+):
+    """
+    Prometheus metrics endpoint.
+
+    Requires Bearer token authentication if APP_METRICS_TOKEN is configured.
+    """
+    return Response(
+        content=generate_latest(),
+        media_type=CONTENT_TYPE_LATEST,
+    )
+
+
 router.include_router(pastes_route)