API Gateway #

# Production API Gateway Configuration
api.example.com {
    # ── Global Middleware & Logging ───────────────────────────────
    log {
        output file /var/log/caddy/api-gateway.log {
            roll_size 50mb
            roll_keep 10
            roll_keep_days 7
        }
        format json
    }
    
    # Dynamic response compression
    encode gzip zstd
    
    # ── Centralized CORS (Cross-Origin Resource Sharing) ──────────
    # Handle OPTIONS (preflight) requests from browsers centrally
    @options method OPTIONS
    handle @options {
        header Access-Control-Allow-Origin      "https://app.example.com"
        header Access-Control-Allow-Methods     "GET, POST, PUT, DELETE, PATCH, OPTIONS"
        header Access-Control-Allow-Headers     "Content-Type, Authorization, X-API-Key, X-Request-ID"
        header Access-Control-Expose-Headers    "X-Request-ID, X-Gateway-Response-Time"
        header Access-Control-Allow-Credentials "true"
        header Access-Control-Max-Age           "86400"
        respond "" 204
    }
    
    # CORS headers for regular requests (non-preflight)
    header Access-Control-Allow-Origin      "https://app.example.com"
    header Access-Control-Allow-Credentials "true"
    header Vary "Origin"
    
    # ── Security Hardening ────────────────────────────────────────
    header {
        # Hide the edge server identity
        -Server
        -X-Powered-By
        # Client browser protection
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
        X-XSS-Protection "1; mode=block"
        Referrer-Policy "strict-origin-when-cross-origin"
    }
    
    # ── Service Routing ────────────────────────────────────────
    
    # User Service Route
    handle /api/v1/users* {
        # ANTI-PATTERN: Sending the request along with the gateway prefix to the backend
        # reverse_proxy user-service:3001
        
        # CORRECT: Remove the /api/v1 prefix so the backend receives the clean /users path
        uri strip_prefix /api/v1
        reverse_proxy user-service:3001 {
            # Inject the real client IP tracking
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-Proto {scheme}
        }
    }
    
    # Product Service Route
    handle /api/v1/products* {
        uri strip_prefix /api/v1
        reverse_proxy product-service:3002 {
            # Connection pool optimization for the product catalog
            transport http {
                dial_timeout 2s
                keepalive_interval 30s
            }
        }
    }
    
    # Order Service Route
    handle /api/v1/orders* {
        uri strip_prefix /api/v1
        reverse_proxy order-service:3003
    }
    
    # Search Service Route (Heavy search with looser timeout)
    handle /api/v1/search* {
        uri strip_prefix /api/v1
        reverse_proxy search-service:3005 {
            transport http {
                # Give the search engine extra time to respond
                response_header_timeout 15s
                read_buffer_size 8192
            }
        }
    }
    
    # ── Default Path Handling (Fallback 404) ──────────────────
    handle {
        header Content-Type "application/json"
        respond `{"error": "Resource Not Found", "code": 404}` 404
    }
}

api.example.com {
    encode gzip zstd
    
    # ── API Version 1 Route (Stable - Deprecated) ────────────────────
    handle /api/v1/* {
        # Insert a warning header that this version will soon be discontinued
        header Deprecation "true"
        header Sunset "Thu, 31 Dec 2026 23:59:59 GMT"
        header Link "</api/v2/>; rel=\"successor-version\""
        
        # Forward to the old service cluster
        uri strip_prefix /api/v1
        reverse_proxy user-service-v1:3001
    }
    
    # ── API Version 2 Route (Newest - Active) ────────────────────────
    handle /api/v2/* {
        uri strip_prefix /api/v2
        reverse_proxy user-service-v2:3011 {
            # Passive error detection for the new version
            fail_duration 10s
            max_fails 3
        }
    }
    
    # ── Alias API Route (/api/latest/) ─────────────────────────────
    # Requests to /api/latest/users are internally changed to /api/v2/users
    # without changing the URL in the browser/client
    handle /api/latest/* {
        # Rewrite the path dynamically
        uri replace /api/latest/ /api/v2/
        
        # Re-run matching after the rewrite to route to the v2 handle
        # or directly proxy to the v2 backend here
        uri strip_prefix /api/v2
        reverse_proxy user-service-v2:3011
    }
    
    # Default fallback
    handle {
        header Content-Type "application/json"
        respond `{"error": "Unsupported API Version", "code": 400}` 400
    }
}

api.example.com {
    encode gzip zstd
    
    # ── Scenario 1: API Key Validation with Map (For Third Parties) ──
    # We map the Authorization 'Bearer <key>' header to the client/app name.
    # If the key doesn't match, the {client_identity} variable is empty ("").
    map {header.Authorization} {client_identity} {
        "Bearer key_prod_9a8b7c" "Client-Frontend-App"
        "Bearer key_partner_3x2y1z" "Partner-Logistics-Corp"
        default ""
    }
    
    # Public endpoint (no API Key needed)
    handle /api/v1/public/* {
        uri strip_prefix /api/v1
        reverse_proxy public-service:3006
    }
    
    # Partner API routes requiring a valid API Key
    handle /api/v1/partners* {
        # ANTI-PATTERN: Letting empty requests through and letting the backend crash
        # reverse_proxy partner-service:3009
        
        # CORRECT: Reject the request at the gateway level if client_identity is empty
        @invalid_key expression `{client_identity} == ""`
        handle @invalid_key {
            header Content-Type "application/json"
            respond `{"error": "Invalid or missing API Key", "code": 401}` 401
        }
        
        # If it passes, forward the request and attach the client identity for backend audit
        uri strip_prefix /api/v1
        reverse_proxy partner-service:3009 {
            header_up X-Client-Name {client_identity}
        }
    }
    
    # ── Scenario 2: Centralized JWT Validation (Simulation Using the Security Module) ──
    # Note: Requires the 'caddy-security' / 'caddy-jwt' plugin
    # In this configuration, we assume the plugin is installed and secures the /api/v2/* path
    
    # Here we conceptually simulate JWT token detection.
    # The Gateway checks the presence of the Authorization header and validates it.
    # For the backend, we inject the user ID and role data extracted by the JWT module.
    handle /api/v2/secure/* {
        # JWT authentication is done here (conceptual):
        # jwt {
        #     primary_key "our-jwt-signing-secret"
        # }
        
        uri strip_prefix /api/v2
        reverse_proxy backend-secure:3022 {
            # Forward the decrypted JWT claims to the downstream service
            # The backend no longer needs to query the database just to validate users
            header_up X-User-ID {http.auth.user.id}
            header_up X-User-Email {http.auth.user.email}
            header_up X-User-Role {http.auth.user.role}
            header_up X-Auth-Method "gateway-jwt"
        }
    }
}

api.example.com {
    # ── Centralized Rate Limit Configuration ───────────────────────────
    # Note: Requires the 'caddy-ratelimit' module compiled via xcaddy
    
    # Define Named Matchers
    @expensive_ops path /api/v1/reports* /api/v1/export*
    @general_api   path /api/v1/*
    
    # 1. Limits for Heavy Endpoints (Maximum 5 requests per minute)
    rate_limit @expensive_ops {
        zone reports_limit {
            # Identify clients by the real public IP
            key    {remote_host}
            window 1m
            events 5
        }
    }
    
    # 2. Limits for General APIs (Maximum 120 requests per minute)
    rate_limit @general_api {
        zone general_limit {
            key    {remote_host}
            window 1m
            events 120
        }
    }
    
    # ── Rate Limit Exceptions (Bypass for Dev / Trusted IPs) ──
    # We use the expression block to skip rate limits if the IP comes from the office LAN
    @trusted_office remote_ip 192.168.10.0/24 10.0.0.0/8
    
    # ── Service Routing ───────────────────────────────────────────
    handle @expensive_ops {
        uri strip_prefix /api/v1
        reverse_proxy report-service:3007
    }
    
    handle @general_api {
        uri strip_prefix /api/v1
        reverse_proxy main-backend:3000
    }
    
    # Handling when a rate limit occurs (HTTP 429 Too Many Requests)
    # The caddy-ratelimit module automatically returns the 429 status to clients
    # with the appropriate Retry-After header.
}

api.example.com {
    encode gzip zstd
    
    handle /api/v1/* {
        uri strip_prefix /api/v1
        
        reverse_proxy app-server:3000 {
            # 1. Request Transformation to the Backend (Upstream)
            # Inject the real client IP for backend logging
            header_up X-Real-IP         {remote_host}
            header_up X-Forwarded-Proto {scheme}
            
            # Inject the unified tracking ID (Correlation ID / Trace ID)
            header_up X-Request-ID      {http.request.uuid}
            
            # Tell the backend the request passed through the Caddy Gateway
            header_up X-Gateway-Server  "Caddy-Edge"
            
            # Remove dangerous headers malicious clients try to inject
            header_up -X-Admin-Override
            
            # 2. Response Transformation to the Client (Downstream)
            # Remove internal backend framework identities for security
            header_down -X-Powered-By
            header_down -Server
            header_down -X-Source-Branch
            
            # Attach the tracking ID to the client so clients can reference
            # this ID when contacting support teams during errors
            header_down X-Request-ID      {http.request.uuid}
            
            # Attach the downstream latency metric (reverse proxy execution duration)
            header_down X-Gateway-Execution-Time "{duration}s"
        }
    }
}

api.example.com {
    encode gzip zstd
    
    handle /api/v1/checkout* {
        uri strip_prefix /api/v1
        
        # Route mainly to payment-prod, and backup to payment-backup
        reverse_proxy payment-prod:3008 payment-backup:3018 {
            # ── Load Balancing Policy ──
            # Always use the first server (prod). Only use the second server
            # (backup) if the first server is declared unhealthy by the health checker.
            lb_policy first
            
            # ── Passive Health Check (Circuit Breaker) ──
            # If the main server fails to respond 3 times in a row,
            # Caddy opens the circuit (isolation) and bypasses that server for 30 seconds.
            max_fails 3
            fail_duration 30s
            
            # ── Active Health Check (Circuit Recovery) ──
            # Actively check server health status every 10 seconds.
            health_uri /api/healthz
            health_interval 10s
            health_timeout 3s
            
            # Only consider healthy if returning HTTP status 200
            health_status 200
            
            # Upstream dial timeout settings
            transport http {
                dial_timeout 2s
                response_header_timeout 5s
            }
        }
    }
}

#!/bin/bash
# update-gateway.sh — Caddy backend update automation script
set -e

REGISTRY_FILE="/etc/caddy/services.json"
TEMPLATE_FILE="/etc/caddy/Caddyfile.template"
OUTPUT_FILE="/etc/caddy/Caddyfile"

# Simulate the dynamic registry file (/etc/caddy/services.json) if it doesn't exist
if [ ! -f "$REGISTRY_FILE" ]; then
    cat << 'EOF' > "$REGISTRY_FILE"
{
  "user-service": "10.0.1.50:3001",
  "product-service": "10.0.1.60:3002",
  "order-service": "10.0.1.70:3003"
}
EOF
fi

echo "[+] Reading the service registry and building the Caddyfile..."

python3 << 'EOF'
import json

with open('/etc/caddy/services.json') as f:
    services = json.load(f)

# Read the basic Caddyfile template
# The template contains global, logging, and CORS configuration
try:
    with open('/etc/caddy/Caddyfile.template', 'r') as t:
        template = t.read()
except FileNotFoundError:
    # Fallback template if the template file doesn't exist
    template = """# Global Options & Base Site
api.example.com {
    encode gzip zstd
    
    # DYNAMIC_ROUTES_PLACEHOLDER
    
    handle {
        respond "Gateway: Target Not Found" 404
    }
}"""

routes = ""
for name, addr in services.items():
    # Change "user-service" to the "/api/v1/users/*" path
    path_key = name.replace('-service', '')
    routes += f"""
    # Dynamic Release for {name}
    handle /api/v1/{path_key}* {{
        uri strip_prefix /api/v1
        reverse_proxy {addr} {{
            header_up X-Gateway-Autodiscovery "true"
        }}
    }}
"""

# Replace the placeholder with the newly created dynamic routes
new_config = template.replace("# DYNAMIC_ROUTES_PLACEHOLDER", routes)

with open('/etc/caddy/Caddyfile', 'w') as out:
    out.write(new_config)

print("[+] The Caddyfile configuration was successfully updated in the file memory.")
EOF

# Validate the configuration before applying to prevent production crashes
echo "[+] Validating the Caddy configuration..."
caddy validate --config "$OUTPUT_FILE"

# Send a safe reload signal (zero-downtime atomic swap)
echo "[+] Reloading the Caddy configuration..."
caddy reload --config "$OUTPUT_FILE"

echo "[✓] The API Gateway was successfully synchronized with the service registry!"

# ── Enabling Prometheus Metrics in Global Options ──────────────────
{
    # Enable the admin endpoint on localhost port 2019
    admin localhost:2019
    
    # Enable internal metric collection
    prometheus
}

api.example.com {
    log {
        output file /var/log/caddy/api-access.log {
            roll_size 100mb
        }
        format json
    }
    
    encode gzip zstd
    
    handle /api/v1/* {
        uri strip_prefix /api/v1
        reverse_proxy backend:3000
    }
}

#!/bin/bash
# analyze-gateway-logs.sh — Quick API Gateway performance analysis from JSON logs
LOG_FILE="/var/log/caddy/api-access.log"

if [ ! -f "$LOG_FILE" ]; then
    echo "[-] Log file not found at $LOG_FILE"
    exit 1
fi

echo "=== API GATEWAY PERFORMANCE DIAGNOSTICS ==="
echo "Analyzing the last 1000 request lines..."
echo ""

# 1. Total Requests & Status Code Detection
tail -n 1000 "$LOG_FILE" | jq -s '
    {
        total_requests: length,
        success_2xx: [ .[] | select(.status >= 200 and .status < 300) ] | length,
        redirect_3xx: [ .[] | select(.status >= 300 and .status < 400) ] | length,
        client_error_4xx: [ .[] | select(.status >= 400 and .status < 500) ] | length,
        server_error_5xx: [ .[] | select(.status >= 500) ] | length
    }
'

echo ""
echo "--- 5 SLOWEST ENDPOINTS (Latency > 1.5 Seconds) ---"
# Sort requests by the longest execution duration
tail -n 1000 "$LOG_FILE" | \
    jq -r 'select(.duration > 1.5) | "\(.duration)s \t \(.request.method) \t \(.request.uri) \t (Status: \(.status))"' | \
    sort -rn | head -5

echo ""
echo "--- 5 CLIENT IPs WITH THE HIGHEST TRAFFIC ---"
# Identify the most aggressive client IPs making requests
tail -n 1000 "$LOG_FILE" | \
    jq -r '.request.remote_ip' | \
    sort | uniq -c | sort -rn | head -5