Advanced

use axum::{
    async_trait,
    extract::{FromRequestParts, State},
    http::{request::Parts, StatusCode},
    RequestPartsExt,  // => Extension trait adding .extract() to Parts
};
use std::sync::Arc;

// Custom extractor: extracts a validated API key from headers
struct ApiKey(String);  // => Newtype wrapping the validated key string

// AppState is needed to validate API keys against a known set
#[derive(Clone)]
struct AppState {
    valid_keys: Vec<String>,  // => List of valid API keys (use a HashSet in production)
}

#[async_trait]
impl<S> FromRequestParts<S> for ApiKey
where
    S: Send + Sync,  // => S is the state type; must be Send + Sync for async
    Arc<AppState>: axum::extract::FromRef<S>,  // => State must contain Arc<AppState>
                                                // => FromRef enables extracting sub-state
{
    type Rejection = StatusCode;  // => Return type on extraction failure

    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
        // Extract the AppState from the state parameter
        let State(app_state): State<Arc<AppState>> = parts
            .extract_with_state(state)  // => Use state-aware extraction
            .await
            .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

        // Extract the X-API-Key header
        let key = parts
            .headers
            .get("X-API-Key")                       // => Look for header
            .and_then(|v| v.to_str().ok())           // => Convert to &str
            .ok_or(StatusCode::UNAUTHORIZED)?;       // => 401 if missing

        // Validate the key
        if !app_state.valid_keys.iter().any(|k| k == key) {
            return Err(StatusCode::FORBIDDEN);       // => 403 if key not in valid set
        }

        Ok(ApiKey(key.to_string()))                  // => Extraction succeeded
    }
}

// Handler uses the custom extractor directly
async fn api_handler(
    ApiKey(key): ApiKey,  // => Extracts and validates in one step
) -> String {
    format!("Authenticated with key: {}...", &key[..4])
    // => "Authenticated with key: sk-l..."
}

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState {
        valid_keys: vec!["sk-live-abc123".to_string(), "sk-live-def456".to_string()],
    });

    let app = axum::Router::new()
        .route("/api/data", axum::routing::get(api_handler))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{
    async_trait,
    body::Bytes,
    extract::{FromRequest, Request},
    http::{header, StatusCode},
    response::{IntoResponse, Response},
};
use serde::de::DeserializeOwned;

// Custom extractor: validates Content-Type before parsing JSON
struct StrictJson<T>(T);  // => Wraps the deserialized value

// Custom rejection type with structured error
struct StrictJsonRejection {
    message: String,
    status: StatusCode,
}

impl IntoResponse for StrictJsonRejection {
    fn into_response(self) -> Response {
        (self.status, self.message).into_response()
    }
}

#[async_trait]
impl<T, S> FromRequest<S> for StrictJson<T>
where
    T: DeserializeOwned,  // => T must be deserializable from JSON
    S: Send + Sync,
{
    type Rejection = StrictJsonRejection;

    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
        // Step 1: Validate Content-Type header explicitly
        let content_type = req
            .headers()
            .get(header::CONTENT_TYPE)
            .and_then(|v| v.to_str().ok())
            .unwrap_or("");
        // => Check before reading body (cheap operation)

        if !content_type.contains("application/json") {
            return Err(StrictJsonRejection {
                message: format!("Expected application/json, got: {}", content_type),
                status: StatusCode::UNSUPPORTED_MEDIA_TYPE,  // => 415
            });
        }

        // Step 2: Read the entire request body
        let bytes = Bytes::from_request(req, state)
            .await
            .map_err(|_| StrictJsonRejection {
                message: "Failed to read body".to_string(),
                status: StatusCode::BAD_REQUEST,
            })?;
        // => bytes contains the raw request body

        // Step 3: Deserialize JSON
        serde_json::from_slice::<T>(&bytes)
            .map(StrictJson)         // => Wrap in StrictJson on success
            .map_err(|e| StrictJsonRejection {
                message: format!("JSON parse error: {}", e),
                status: StatusCode::UNPROCESSABLE_ENTITY,  // => 422
            })
    }
}

// Handler uses StrictJson - enforces application/json Content-Type
async fn create_item(
    StrictJson(data): StrictJson<serde_json::Value>,  // => Custom extractor
) -> String {
    format!("Received: {}", data)  // => "Received: {\"name\":\"widget\"}"
}

#[tokio::main]
async fn main() {
    let app = axum::Router::new()
        .route("/items", axum::routing::post(create_item));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{routing::get, Router};
use std::{
    pin::Pin,
    future::Future,
    task::{Context, Poll},
};
use tower::{Layer, Service};  // => Core Tower traits
use axum::http::Request;
use axum::response::Response;
use axum::body::Body;

// Step 1: Define the Layer (factory that wraps services)
#[derive(Clone)]
struct RequestIdLayer;  // => Adds X-Request-ID to every request

impl<S> Layer<S> for RequestIdLayer {
    type Service = RequestIdService<S>;  // => The service this layer creates

    fn layer(&self, inner: S) -> Self::Service {
        RequestIdService { inner }       // => Wrap the inner service
    }
}

// Step 2: Define the Service (the actual middleware logic)
#[derive(Clone)]
struct RequestIdService<S> {
    inner: S,  // => The wrapped (inner) service/handler
}

impl<S> Service<Request<Body>> for RequestIdService<S>
where
    S: Service<Request<Body>, Response = Response> + Clone + Send + 'static,
    S::Future: Send + 'static,
{
    type Response = Response;
    type Error = S::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Response, S::Error>> + Send>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)  // => Delegate readiness to inner service
                                    // => Ready when inner is ready to accept requests
    }

    fn call(&mut self, mut req: Request<Body>) -> Self::Future {
        let inner = self.inner.clone();  // => Clone inner for the async block
        Box::pin(async move {
            // Generate a unique request ID
            let id = format!("{}", rand_id());  // => Unique ID per request
            req.headers_mut().insert(
                "x-request-id",
                id.parse().unwrap(),   // => Inject into request headers
            );
            // => Inner handlers can read X-Request-ID from headers

            let mut inner = inner;
            let response = inner.call(req).await?;  // => Call the inner service
            Ok(response)  // => Return response unchanged (or modify here)
        })
    }
}

fn rand_id() -> u64 {
    // In production: use uuid::Uuid::new_v4().to_string()
    42  // => Simplified for example
}

async fn handler(headers: axum::http::HeaderMap) -> String {
    let id = headers.get("x-request-id")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("none");
    format!("Request ID: {}", id)  // => "Request ID: 42"
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/", get(handler))
        .layer(RequestIdLayer);  // => Apply custom Tower layer
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// Cargo.toml:
// tower-http = { version = "0.6", features = ["compression-full"] }

use axum::{routing::get, Router};
use tower_http::compression::CompressionLayer;  // => Automatic response compression

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/data", get(large_response))
        .layer(
            CompressionLayer::new()
                // => Compresses responses based on Accept-Encoding header
                // => Supports: gzip, deflate, brotli, zstd (with feature flags)
                // => Skips compression for small responses (< ~1KB, configurable)
                // => Does NOT compress already-compressed formats (JPEG, PNG, zip)
        );

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

async fn large_response() -> String {
    // Simulated large JSON response (real: query 1000 rows from DB)
    let data: Vec<String> = (1..=100)
        .map(|i| format!("{{\"id\":{},\"name\":\"Item {}\",\"description\":\"Long description for item {}\"}}", i, i, i))
        .collect();
    format!("[{}]", data.join(","))
    // => Uncompressed: ~8KB
    // => With gzip: ~0.4KB (95% reduction for repetitive JSON)
    // => Content-Encoding: gzip header added automatically
}

// Cargo.toml:
// sqlx = { version = "0.8", features = ["postgres", "runtime-tokio"] }

use axum::{extract::State, routing::get, Json, Router};
use sqlx::{postgres::PgPoolOptions, PgPool};
use std::sync::Arc;
use std::time::Duration;

// AppState with separate read-write and read-only pools
#[derive(Clone)]
struct AppState {
    primary: PgPool,   // => Read-write: INSERT, UPDATE, DELETE
    replica: PgPool,   // => Read-only: SELECT queries (load balanced to replicas)
}

async fn get_user(State(state): State<Arc<AppState>>) -> Json<String> {
    // Use replica pool for read queries
    let name = sqlx::query_scalar::<_, String>("SELECT name FROM users WHERE id = 1")
        .fetch_one(&state.replica)  // => Routes to read replica
        .await
        .unwrap_or_else(|_| "unknown".to_string());
    Json(name)
}

async fn update_user(State(state): State<Arc<AppState>>) -> axum::http::StatusCode {
    // Use primary pool for write queries
    sqlx::query("UPDATE users SET last_seen = NOW() WHERE id = 1")
        .execute(&state.primary)    // => Routes to primary (read-write)
        .await
        .ok();
    axum::http::StatusCode::OK
}

#[tokio::main]
async fn main() {
    // Primary: smaller pool, handles writes
    let primary = PgPoolOptions::new()
        .max_connections(5)          // => Writes are less frequent; smaller pool
        .min_connections(1)          // => Keep at least 1 warm
        .acquire_timeout(Duration::from_secs(5))   // => Fail fast if pool exhausted
        .idle_timeout(Duration::from_secs(600))    // => Close idle connections after 10 min
        .max_lifetime(Duration::from_secs(1800))   // => Refresh connections every 30 min
                                                    // => Prevents stale connections after DB failover
        .connect("postgres://primary-host/mydb").await.unwrap();

    // Replica: larger pool for high-read workloads
    let replica = PgPoolOptions::new()
        .max_connections(20)         // => Reads dominate; larger pool
        .min_connections(3)
        .acquire_timeout(Duration::from_secs(3))
        .connect("postgres://replica-host/mydb").await.unwrap();

    let state = Arc::new(AppState { primary, replica });

    let app = Router::new()
        .route("/users/1", get(get_user))
        .route("/users/1/touch", axum::routing::post(update_user))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{
    body::Body,
    http::{header, StatusCode},
    response::Response,
    routing::get,
    Router,
};
use tokio::io::AsyncReadExt;
use tokio_util::io::ReaderStream;  // => Convert AsyncRead into Stream

#[tokio::main]
async fn main() {
    let app = Router::new().route("/download/:filename", get(download_file));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

async fn download_file(
    axum::extract::Path(filename): axum::extract::Path<String>,
) -> Result<Response, StatusCode> {
    // Security: prevent path traversal attacks
    if filename.contains("..") || filename.contains('/') {
        return Err(StatusCode::BAD_REQUEST);  // => Reject path traversal attempts
    }

    let path = format!("./files/{}", filename);
    // => Only serve files from the ./files/ directory

    // Open the file (returns error if not found)
    let file = tokio::fs::File::open(&path)
        .await
        .map_err(|e| match e.kind() {
            std::io::ErrorKind::NotFound => StatusCode::NOT_FOUND,       // => 404
            _ => StatusCode::INTERNAL_SERVER_ERROR,                       // => 500
        })?;

    // Get file size for Content-Length header
    let metadata = file.metadata().await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
    let file_size = metadata.len();  // => File size in bytes

    // Convert file into a stream of byte chunks
    let stream = ReaderStream::new(file);
    // => Reads 8KB chunks from disk as client reads them
    // => Memory usage: O(8KB) regardless of file size

    Ok(Response::builder()
        .status(StatusCode::OK)
        .header(header::CONTENT_TYPE, "application/octet-stream")
        .header(header::CONTENT_LENGTH, file_size)  // => Enable progress bars
        .header(
            header::CONTENT_DISPOSITION,
            format!("attachment; filename=\"{}\"", filename),
            // => Forces browser download instead of display
        )
        .body(Body::from_stream(stream))  // => Stream file bytes to client
        .unwrap())
}

// Cargo.toml:
// axum-prometheus = "0.7"
// axum = "0.8"

use axum::{routing::get, Router};
use axum_prometheus::PrometheusMetricLayer;  // => Auto-tracks HTTP metrics

#[tokio::main]
async fn main() {
    // Initialize the Prometheus layer and metrics handle
    let (prometheus_layer, metrics_handle) = PrometheusMetricLayer::pair();
    // => prometheus_layer: middleware that records metrics
    // => metrics_handle: used to render metrics in the /metrics endpoint

    let app = Router::new()
        // Business routes
        .route("/api/items", get(items_handler))
        .route("/api/users", get(users_handler))
        // Metrics endpoint (typically restricted to internal network)
        .route("/metrics", get(move || async move {
            metrics_handle.render()  // => Renders metrics in Prometheus text format
            // => Output: # HELP axum_http_requests_total...
            // => axum_http_requests_total{method="GET",path="/api/items",status="200"} 42
        }))
        .layer(prometheus_layer);  // => Wraps all routes to record metrics
        // => Automatically tracks:
        // => axum_http_requests_total (counter, by method/path/status)
        // => axum_http_request_duration_seconds (histogram, by method/path/status)
        // => axum_http_requests_in_flight (gauge)

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

async fn items_handler() -> &'static str { "items" }
async fn users_handler() -> &'static str { "users" }

// Cargo.toml:
// metrics = "0.23"
// metrics-exporter-prometheus = "0.15"
// axum = "0.8"

use axum::{extract::Json, routing::post, Router};
use metrics::{counter, gauge, histogram};  // => Metrics macros
use serde::Deserialize;
use std::time::Instant;

#[derive(Deserialize)]
struct OrderRequest {
    product_id: u64,
    quantity: u32,
    total_cents: i64,
}

async fn create_order(Json(order): Json<OrderRequest>) -> axum::http::StatusCode {
    let start = Instant::now();

    // Business logic (simulated)
    let success = order.total_cents > 0 && order.quantity > 0;

    // Record business metrics
    if success {
        counter!("orders.created.total",            // => Counter: monotonically increasing
            "product" => order.product_id.to_string()  // => Label for breakdown by product
        ).increment(1);
        // => Prometheus: orders_created_total{product="42"} 7

        counter!("revenue.total_cents").increment(order.total_cents as u64);
        // => Total revenue in cents (derive dollars in Grafana)
    } else {
        counter!("orders.failed.total").increment(1);
        // => Track failure rate
    }

    // Record order processing latency
    histogram!("order.processing_duration_seconds").record(
        start.elapsed().as_secs_f64()  // => Processing time as float seconds
    );
    // => Prometheus: order_processing_duration_seconds{quantile="0.99"} 0.003

    // Track pending orders (gauge: can go up or down)
    gauge!("orders.in_processing").set(42.0);
    // => Prometheus: orders_in_processing 42

    if success {
        axum::http::StatusCode::CREATED
    } else {
        axum::http::StatusCode::UNPROCESSABLE_ENTITY
    }
}

#[tokio::main]
async fn main() {
    // Install Prometheus exporter (exports at /metrics if using metrics-exporter-prometheus)
    metrics_exporter_prometheus::PrometheusBuilder::new()
        .install()
        .expect("Failed to install Prometheus exporter");

    let app = Router::new().route("/orders", post(create_order));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// Cargo.toml:
// opentelemetry = "0.27"
// opentelemetry_sdk = { version = "0.27", features = ["rt-tokio"] }
// opentelemetry-otlp = { version = "0.27", features = ["tonic"] }
// tracing-opentelemetry = "0.28"
// axum = "0.8"
// tracing = "0.1"

use axum::{extract::Path, routing::get, Router};
use opentelemetry::global;
use opentelemetry_sdk::trace::SdkTracerProvider;
use tracing::{info_span, instrument};
use tracing_opentelemetry::OpenTelemetrySpanExt;

fn init_tracer() -> SdkTracerProvider {
    // Configure OTLP exporter (sends to Jaeger, Honeycomb, etc.)
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()                               // => gRPC transport
        .build()
        .expect("Failed to create OTLP exporter");
        // => Reads OTEL_EXPORTER_OTLP_ENDPOINT env var (default: http://localhost:4317)

    SdkTracerProvider::builder()
        .with_batch_exporter(exporter, opentelemetry_sdk::runtime::Tokio)
        // => Batch exporter: buffers spans and sends periodically (efficient)
        .build()
}

// Handler with manual span creation and propagation
#[instrument(                           // => Creates tracing span for this function
    name = "get_product",               // => Span name in Jaeger UI
    fields(product.id = %id, otel.kind = "SERVER")  // => OTel semantic conventions
)]
async fn get_product(Path(id): Path<u64>) -> String {
    // Add business context to the current span
    let span = tracing::Span::current();
    span.set_attribute("product.type", "widget");  // => Custom span attribute

    // Simulate downstream call (would propagate context to microservice)
    let data = fetch_product_data(id).await;

    info!(product.id = id, "Product fetched");  // => Logged within this span
    data
}

#[instrument(name = "fetch_product_data")]  // => Child span for DB/service call
async fn fetch_product_data(id: u64) -> String {
    // In real code: propagate trace context to downstream HTTP call
    // via W3C Trace-Context headers (traceparent, tracestate)
    tokio::time::sleep(std::time::Duration::from_millis(5)).await;
    format!("Product {}", id)
    // => Span duration recorded: ~5ms (visible in Jaeger)
}

#[tokio::main]
async fn main() {
    let provider = init_tracer();
    global::set_tracer_provider(provider.clone());  // => Install as global tracer

    // tracing-opentelemetry bridges tracing spans → OTel spans automatically
    let otel_layer = tracing_opentelemetry::layer();
    use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
    tracing_subscriber::registry()
        .with(tracing_subscriber::fmt::layer())
        .with(otel_layer)                            // => Forward spans to OTel
        .init();

    let app = Router::new().route("/products/:id", get(get_product));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();

    // Flush remaining spans on shutdown
    provider.shutdown().ok();
}

// Cargo.toml:
// moka = { version = "0.12", features = ["future"] }
// axum = "0.8"

use axum::{extract::{Path, State}, routing::get, Json, Router};
use moka::future::Cache;  // => Async-aware concurrent cache
use serde::Serialize;
use std::sync::Arc;
use std::time::Duration;

#[derive(Serialize, Clone)]
struct Product {
    id: u64,
    name: String,
    price_cents: u64,
}

#[derive(Clone)]
struct AppState {
    // Cache: key=product_id (u64), value=Product, max 1000 entries
    product_cache: Cache<u64, Product>,  // => Thread-safe, no Arc needed (already Arc inside)
}

async fn get_product(
    Path(id): Path<u64>,
    State(state): State<Arc<AppState>>,
) -> Json<Product> {
    // Check cache first (O(1) concurrent lookup, lock-free in common case)
    if let Some(product) = state.product_cache.get(&id).await {
        return Json(product);               // => Cache hit: return immediately
        // => No database query required
    }

    // Cache miss: fetch from database (simulated)
    let product = fetch_from_db(id).await;  // => Simulated DB call

    // Store in cache with TTL
    state.product_cache.insert(id, product.clone()).await;
    // => Expires after 5 minutes (configured at cache creation)
    // => Evicted if cache exceeds 1000 entries (LRU policy)

    Json(product)
}

async fn fetch_from_db(id: u64) -> Product {
    // Simulate database latency
    tokio::time::sleep(Duration::from_millis(20)).await;
    Product {
        id,
        name: format!("Product {}", id),
        price_cents: 999,
    }
}

#[tokio::main]
async fn main() {
    let product_cache = Cache::builder()
        .max_capacity(1000)              // => LRU eviction when > 1000 entries
        .time_to_live(Duration::from_secs(300))   // => Entries expire after 5 minutes
        .time_to_idle(Duration::from_secs(60))    // => Evict if not accessed for 1 minute
        .build();

    let state = Arc::new(AppState { product_cache });

    let app = Router::new()
        .route("/products/:id", get(get_product))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{routing::get, Router, Json};
use serde::Serialize;

// V1 response: original format
#[derive(Serialize)]
struct UserV1 {
    id: u64,
    name: String,  // => V1: single name field
}

// V2 response: expanded format (breaking change from V1)
#[derive(Serialize)]
struct UserV2 {
    id: u64,
    first_name: String,   // => V2: split into first/last
    last_name: String,
    email: String,        // => V2: added email field
}

// V1 handlers
async fn get_user_v1() -> Json<UserV1> {
    Json(UserV1 { id: 1, name: "Alice Smith".to_string() })
    // => {"id":1,"name":"Alice Smith"}
}

// V2 handlers (different response structure)
async fn get_user_v2() -> Json<UserV2> {
    Json(UserV2 {
        id: 1,
        first_name: "Alice".to_string(),
        last_name: "Smith".to_string(),
        email: "alice@example.com".to_string(),
    })
    // => {"id":1,"first_name":"Alice","last_name":"Smith","email":"alice@example.com"}
}

// Build V1 router - all V1 routes in one function
fn v1_router() -> Router {
    Router::new()
        .route("/users/:id", get(get_user_v1))
        // => GET /api/v1/users/:id
        // Add more V1 routes here as needed
}

// Build V2 router - V2 adds and modifies routes
fn v2_router() -> Router {
    Router::new()
        .route("/users/:id", get(get_user_v2))
        // => GET /api/v2/users/:id (breaking change)
        // Routes that didn't change can call v1 handlers directly
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .nest("/api/v1", v1_router())  // => All v1 routes under /api/v1
        .nest("/api/v2", v2_router())  // => All v2 routes under /api/v2
        .route("/api/latest", get(|| async { "Redirect to v2" }));
        // => Optional: /api/latest as alias for current stable version

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// Cargo.toml:
// tokio = { version = "1", features = ["full"] }
// axum = "0.8"

use axum::{extract::State, routing::get, Router};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

// Circuit breaker states
#[derive(Debug, PartialEq)]
enum CircuitState {
    Closed,    // => Normal operation: requests pass through
    Open,      // => Failing: requests rejected immediately (no external calls)
    HalfOpen,  // => Recovering: allow one probe request
}

struct CircuitBreaker {
    state: CircuitState,
    failure_count: u32,
    last_failure: Option<Instant>,
    failure_threshold: u32,     // => Open circuit after this many failures
    recovery_timeout: Duration, // => Wait this long before trying HalfOpen
}

impl CircuitBreaker {
    fn new(failure_threshold: u32, recovery_timeout: Duration) -> Self {
        Self {
            state: CircuitState::Closed,
            failure_count: 0,
            last_failure: None,
            failure_threshold,
            recovery_timeout,
        }
    }

    // Returns true if the request should be allowed through
    fn allow_request(&mut self) -> bool {
        match self.state {
            CircuitState::Closed => true,  // => Allow: normal operation
            CircuitState::Open => {
                // Check if recovery timeout has elapsed
                if let Some(last) = self.last_failure {
                    if last.elapsed() > self.recovery_timeout {
                        self.state = CircuitState::HalfOpen;  // => Try recovery
                        return true;  // => Allow probe request
                    }
                }
                false  // => Still within timeout: reject request
            }
            CircuitState::HalfOpen => true,  // => Allow one probe request
        }
    }

    fn record_success(&mut self) {
        self.failure_count = 0;
        self.state = CircuitState::Closed;  // => Recovery confirmed: close circuit
    }

    fn record_failure(&mut self) {
        self.failure_count += 1;
        self.last_failure = Some(Instant::now());

        if self.failure_count >= self.failure_threshold {
            self.state = CircuitState::Open;  // => Too many failures: open circuit
        }
    }
}

#[derive(Clone)]
struct AppState {
    breaker: Arc<Mutex<CircuitBreaker>>,
}

async fn proxy_request(State(state): State<Arc<AppState>>) -> axum::http::StatusCode {
    // Check if circuit allows this request
    {
        let mut breaker = state.breaker.lock().unwrap();
        if !breaker.allow_request() {
            return axum::http::StatusCode::SERVICE_UNAVAILABLE;
            // => 503: circuit is open, external service bypassed
        }
    }

    // Call external service (simulated; 50% failure rate)
    let success = rand_bool();

    // Update circuit breaker based on outcome
    let mut breaker = state.breaker.lock().unwrap();
    if success {
        breaker.record_success();   // => Healthy: reset failure count
        axum::http::StatusCode::OK
    } else {
        breaker.record_failure();   // => Failed: increment failure count
        axum::http::StatusCode::BAD_GATEWAY  // => 502: upstream error
    }
}

fn rand_bool() -> bool { true } // Simplified; use random in real code

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState {
        breaker: Arc::new(Mutex::new(CircuitBreaker::new(
            5,                            // => Open after 5 failures
            Duration::from_secs(30),     // => Try recovery after 30 seconds
        ))),
    });
    let app = Router::new()
        .route("/proxy", get(proxy_request))
        .with_state(state);
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

# Dockerfile for Axum application
# Stage 1: Build
FROM rust:1.83-slim AS builder
# => rust:1.83-slim: official Rust image, slim variant for smaller base

WORKDIR /app

# Copy dependency files first (layer caching optimization)
COPY Cargo.toml Cargo.lock ./
# => Copying these first enables Docker layer caching:
# => If source code changes but dependencies don't, Cargo.toml layer is cached
# => Next RUN only re-downloads if Cargo.toml/Cargo.lock changes

# Build dependencies with a dummy main (enables caching of dependency compilation)
RUN mkdir src && echo "fn main() {}" > src/main.rs
RUN cargo build --release
# => Compiles all dependencies (slow: 2-5 minutes first time)
# => Subsequent builds with unchanged deps skip this layer (seconds)
RUN rm -rf src

# Copy actual source code and build
COPY src ./src
RUN touch src/main.rs  # => Ensure cargo detects changed source
RUN cargo build --release
# => Final binary at: /app/target/release/my_axum_app
# => Statically linked (no runtime dependencies needed)

# Stage 2: Runtime (minimal image)
FROM debian:bookworm-slim AS runtime
# => debian:bookworm-slim: ~80MB vs rust:1.83-slim ~700MB

# Install minimal runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates \   # => Required for HTTPS outbound calls
    libpq5 \            # => PostgreSQL client library (if using sqlx postgres)
    && rm -rf /var/lib/apt/lists/*  # => Clean up to reduce image size

WORKDIR /app

# Copy only the compiled binary from builder
COPY --from=builder /app/target/release/my_axum_app .
# => ~10MB binary vs ~700MB full Rust toolchain

# Non-root user for security
RUN useradd -r -s /bin/false app_user
USER app_user

EXPOSE 3000                        # => Document the port (does not actually open it)
ENV RUST_LOG="info"               # => Default log level

CMD ["./my_axum_app"]             # => Start the binary

# Build and run
docker build -t my-axum-app .
docker run -p 3000:3000 \
  -e DATABASE_URL="postgres://user:pass@host/db" \
  -e AUTH__JWT_SECRET="production-secret-from-vault" \
  my-axum-app
# => Passes secrets via environment variables (not baked into image)

use axum::{
    extract::State,
    http::StatusCode,
    routing::get,
    Json, Router,
};
use serde::Serialize;
use sqlx::PgPool;
use std::sync::{Arc, atomic::{AtomicBool, Ordering}};

#[derive(Clone)]
struct AppState {
    db: PgPool,
    ready: Arc<AtomicBool>,  // => Readiness flag (can be flipped by shutdown logic)
}

#[derive(Serialize)]
struct HealthJson {
    status: &'static str,
    version: &'static str,
}

// Kubernetes liveness probe: /healthz
// Returns 200 if process is alive (not deadlocked)
// Kubernetes restarts pod if this returns non-200
async fn liveness() -> Json<HealthJson> {
    Json(HealthJson {
        status: "alive",
        version: env!("CARGO_PKG_VERSION"),  // => From Cargo.toml at compile time
    })
    // => Always returns 200 while process is running
    // => Kubernetes kubectl: livenessProbe.httpGet.path = /healthz
}

// Kubernetes readiness probe: /readyz
// Returns 200 if instance can serve traffic
// Kubernetes removes pod from Service endpoints if this returns non-200
async fn readiness(State(state): State<Arc<AppState>>) -> (StatusCode, Json<serde_json::Value>) {
    // Check if the app is in the ready state (set to false during shutdown)
    if !state.ready.load(Ordering::Relaxed) {
        return (StatusCode::SERVICE_UNAVAILABLE,
            Json(serde_json::json!({"status": "not ready", "reason": "shutting down"})));
        // => 503 during graceful shutdown: Kubernetes stops routing traffic here
    }

    // Verify database connectivity
    match sqlx::query("SELECT 1").execute(&state.db).await {
        Ok(_) => (StatusCode::OK, Json(serde_json::json!({"status": "ready", "db": "ok"}))),
        Err(e) => (StatusCode::SERVICE_UNAVAILABLE,
            Json(serde_json::json!({"status": "not ready", "db": format!("error: {}", e)}))),
    }
}

#[tokio::main]
async fn main() {
    let pool = PgPool::connect("postgres://user:pass@localhost/mydb").await.unwrap();
    let ready = Arc::new(AtomicBool::new(true));

    let state = Arc::new(AppState { db: pool, ready: ready.clone() });

    let app = Router::new()
        .route("/healthz", get(liveness))   // => Kubernetes liveness probe
        .route("/readyz", get(readiness))   // => Kubernetes readiness probe
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app)
        .with_graceful_shutdown(async move {
            // On shutdown signal: mark not ready before draining
            tokio::signal::ctrl_c().await.ok();
            ready.store(false, Ordering::Relaxed);  // => Tell K8s to stop routing here
            tokio::time::sleep(std::time::Duration::from_secs(5)).await;
            // => Wait 5 seconds for K8s to stop routing (propagation delay)
        })
        .await
        .unwrap();
}