Actix-web Core Knowledge

Full Reference: See advanced.md for custom timing middleware, authentication middleware, custom error types, WebSocket actors, and graceful shutdown patterns.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: actix-web for comprehensive documentation.

Basic Setup

# Cargo.toml
[dependencies]
actix-web = "4"
actix-rt = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }

use actix_web::{web, App, HttpServer, HttpResponse, Responder};

async fn hello() -> impl Responder {
    HttpResponse::Ok().body("Hello, World!")
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .route("/", web::get().to(hello))
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

Route Macros

use actix_web::{get, post, web, HttpResponse, Responder};

#[get("/users/{id}")]
async fn get_user(path: web::Path<u32>) -> impl Responder {
    let id = path.into_inner();
    HttpResponse::Ok().json(serde_json::json!({ "id": id }))
}

#[post("/users")]
async fn create_user(body: web::Json<CreateUser>) -> impl Responder {
    HttpResponse::Created().json(body.into_inner())
}

// Register with App
App::new()
    .service(get_user)
    .service(create_user)

Extractors

| Extractor | Purpose | |-----------|---------| | web::Path<T> | URL path parameters | | web::Query<T> | Query string | | web::Json<T> | JSON body | | web::Form<T> | Form data | | web::Data<T> | Application state |

Application State

struct AppState {
    db_pool: Pool<Postgres>,
}

#[get("/users")]
async fn list_users(data: web::Data<AppState>) -> impl Responder {
    let users = sqlx::query_as!(User, "SELECT * FROM users")
        .fetch_all(&data.db_pool)
        .await?;
    HttpResponse::Ok().json(users)
}

HttpServer::new(move || {
    App::new()
        .app_data(web::Data::new(state.clone()))
        .service(list_users)
})

Built-in Middleware

use actix_web::middleware::{Logger, Compress, NormalizePath};

App::new()
    .wrap(Logger::default())
    .wrap(Compress::default())
    .wrap(NormalizePath::trim())

Health Checks

#[get("/health")]
async fn health() -> impl Responder {
    HttpResponse::Ok().json(serde_json::json!({ "status": "healthy" }))
}

#[get("/ready")]
async fn ready(data: web::Data<AppState>) -> impl Responder {
    match data.db_pool.acquire().await {
        Ok(_) => HttpResponse::Ok().json(serde_json::json!({
            "status": "ready",
            "database": "connected"
        })),
        Err(_) => HttpResponse::ServiceUnavailable().json(serde_json::json!({
            "status": "not ready"
        })),
    }
}

When NOT to Use This Skill

• Axum projects - Axum is more ergonomic with Tower ecosystem
• Rocket projects - Rocket has better compile-time guarantees
• Warp projects - Warp uses filters for composition
• Simple CLI tools - No web server needed
• Embedded systems - Too heavy for resource-constrained devices

Anti-Patterns

| Anti-Pattern | Why It's Bad | Solution | |--------------|--------------|----------| | .clone() on every request | Performance overhead | Use web::Data<Arc<T>> for shared state | | Blocking I/O in async handlers | Blocks executor threads | Use web::block() for blocking operations | | Not using extractors | Manual parsing is error-prone | Use Json, Path, Query extractors | | Missing #[actix_web::main] | Manual runtime setup | Use macro for simple setup | | Global mutable state | Data races | Use Mutex or RwLock with web::Data | | No custom error types | Generic error messages | Implement ResponseError trait |

Quick Troubleshooting

| Problem | Diagnosis | Fix | |---------|-----------|-----| | "Cannot move out of borrowed content" | Ownership issue | Clone data or use web::Data<Arc<T>> | | Handler not found (404) | Route not registered | Check .service() or .route() calls | | JSON parsing fails | Wrong content-type | Ensure client sends Content-Type: application/json | | Slow performance | Blocking I/O | Wrap blocking code in web::block() | | WebSocket connection closes | Missing ping/pong | Implement heartbeat mechanism | | State not accessible | Not added to app | Use .app_data() when building app |

Checklist

• [ ] CORS properly configured
• [ ] Authentication middleware
• [ ] Custom error handling
• [ ] Request logging (Logger middleware)
• [ ] Health/readiness endpoints
• [ ] Graceful shutdown
• [ ] Connection pooling for database
• [ ] Input validation
• [ ] Rate limiting (actix-ratelimit)

Reference Documentation

• Extractors
• Middleware