gh-physics91-claude-vibe/skills/rust-api-reviewer/SKILL.md

name, description

name	description
rust-api-reviewer	WHEN: Rust API review with Actix-web/Axum/Rocket, async patterns, extractors, middleware WHAT: Async handlers + Extractors + State management + Error responses + Tower middleware WHEN NOT: General Rust → rust-reviewer, Go API → go-api-reviewer

Rust API Reviewer Skill

Purpose

Reviews Rust web API projects using Actix-web, Axum, or Rocket for async patterns and API design.

When to Use

• Rust REST API code review
• Actix-web/Axum/Rocket project review
• Async handler patterns
• Middleware and extractors
• State management review

Project Detection

• actix-web in Cargo.toml
• axum in Cargo.toml
• rocket in Cargo.toml
• handlers/, routes/ directories
• tower middleware usage

Workflow

Step 1: Analyze Project

**Framework**: Axum 0.7+
**Runtime**: Tokio
**Database**: SQLx / SeaORM / Diesel
**Validation**: validator crate
**Auth**: JWT / OAuth2

Step 2: Select Review Areas

AskUserQuestion:

"Which areas to review?"
Options:
- Full API review (recommended)
- Async handlers and patterns
- Extractors and validation
- State and dependency injection
- Error handling and responses
multiSelect: true

Detection Rules

Axum Patterns

Handler Organization

Check	Recommendation	Severity
All routes in main	Use Router::nest	MEDIUM
No route grouping	Group by resource	MEDIUM
Missing method routing	Use method_router	LOW

// BAD: All routes in main
#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/users", get(list_users).post(create_user))
        .route("/users/:id", get(get_user).put(update_user))
        .route("/products", get(list_products))
        // ... 50 more routes
        .with_state(state);
}

// GOOD: Organized with nest
fn user_routes() -> Router<AppState> {
    Router::new()
        .route("/", get(list_users).post(create_user))
        .route("/:id", get(get_user).put(update_user).delete(delete_user))
}

fn product_routes() -> Router<AppState> {
    Router::new()
        .route("/", get(list_products).post(create_product))
        .route("/:id", get(get_product))
}

fn api_routes() -> Router<AppState> {
    Router::new()
        .nest("/users", user_routes())
        .nest("/products", product_routes())
}

#[tokio::main]
async fn main() {
    let state = AppState::new().await;

    let app = Router::new()
        .nest("/api/v1", api_routes())
        .layer(TraceLayer::new_for_http())
        .with_state(state);

    // ...
}

Extractors

Check	Recommendation	Severity
Manual JSON parsing	Use Json extractor	HIGH
No validation	Use ValidatedJson	HIGH
Order of extractors	Body extractors last	HIGH

// BAD: Manual parsing
async fn create_user(body: String) -> Result<Json<User>, AppError> {
    let req: CreateUserRequest = serde_json::from_str(&body)?;
    // ...
}

// GOOD: Json extractor
async fn create_user(
    Json(req): Json<CreateUserRequest>,
) -> Result<Json<User>, AppError> {
    // req is already deserialized
}

// GOOD: With validation (using validator crate)
#[derive(Debug, Deserialize, Validate)]
struct CreateUserRequest {
    #[validate(length(min = 1, max = 100))]
    name: String,
    #[validate(email)]
    email: String,
}

async fn create_user(
    State(state): State<AppState>,
    ValidatedJson(req): ValidatedJson<CreateUserRequest>,
) -> Result<Json<User>, AppError> {
    // req is validated
}

// IMPORTANT: Extractor order matters!
// Body-consuming extractors must be last
async fn handler(
    State(state): State<AppState>,    // First: doesn't consume
    Path(id): Path<i32>,              // Second: from URL
    Query(params): Query<Params>,     // Third: from query
    Json(body): Json<Request>,        // LAST: consumes body
) -> Response {
    // ...
}

State Management

Check	Recommendation	Severity
Global static state	Use State extractor	HIGH
No connection pool	Use shared pool	HIGH
Mutex in async	Use tokio::sync::Mutex	CRITICAL

// BAD: Global static
static DB: OnceCell<Database> = OnceCell::new();

async fn get_user(Path(id): Path<i32>) -> Json<User> {
    let db = DB.get().unwrap();  // Bad pattern
    // ...
}

// GOOD: State extractor
#[derive(Clone)]
struct AppState {
    db: PgPool,
    cache: Arc<Cache>,
    config: Arc<Config>,
}

async fn get_user(
    State(state): State<AppState>,
    Path(id): Path<i32>,
) -> Result<Json<User>, AppError> {
    let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
        .fetch_one(&state.db)
        .await?;
    Ok(Json(user))
}

// BAD: std::sync::Mutex in async
struct AppState {
    cache: std::sync::Mutex<HashMap<String, Value>>,  // Blocks!
}

// GOOD: tokio Mutex or RwLock
struct AppState {
    cache: tokio::sync::RwLock<HashMap<String, Value>>,
}

async fn get_cached(
    State(state): State<AppState>,
    Path(key): Path<String>,
) -> Result<Json<Value>, AppError> {
    let cache = state.cache.read().await;
    cache.get(&key).cloned().ok_or(AppError::NotFound)
}

Error Handling

Check	Recommendation	Severity
Panic in handler	Return Result	CRITICAL
No IntoResponse impl	Implement for errors	HIGH
Leaking internal errors	Map to HTTP errors	HIGH

// GOOD: Custom error type with IntoResponse
#[derive(Debug)]
enum AppError {
    NotFound,
    Unauthorized,
    Validation(String),
    Internal(anyhow::Error),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::NotFound => (StatusCode::NOT_FOUND, "Not found"),
            AppError::Unauthorized => (StatusCode::UNAUTHORIZED, "Unauthorized"),
            AppError::Validation(msg) => {
                return (StatusCode::BAD_REQUEST, Json(json!({
                    "error": "validation_error",
                    "message": msg,
                }))).into_response();
            }
            AppError::Internal(err) => {
                tracing::error!("Internal error: {:?}", err);
                (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error")
            }
        };

        (status, Json(json!({ "error": message }))).into_response()
    }
}

// Implement From for automatic conversion
impl From<sqlx::Error> for AppError {
    fn from(err: sqlx::Error) -> Self {
        match err {
            sqlx::Error::RowNotFound => AppError::NotFound,
            _ => AppError::Internal(err.into()),
        }
    }
}

Middleware (Tower)

Check	Recommendation	Severity
No tracing	Add TraceLayer	MEDIUM
No timeout	Add TimeoutLayer	MEDIUM
Auth in handler	Use middleware	MEDIUM

use tower::ServiceBuilder;
use tower_http::{
    trace::TraceLayer,
    timeout::TimeoutLayer,
    cors::CorsLayer,
};

fn app(state: AppState) -> Router {
    Router::new()
        .nest("/api", api_routes())
        .layer(
            ServiceBuilder::new()
                .layer(TraceLayer::new_for_http())
                .layer(TimeoutLayer::new(Duration::from_secs(30)))
                .layer(CorsLayer::permissive())
        )
        .with_state(state)
}

// GOOD: Auth middleware
async fn auth_middleware(
    State(state): State<AppState>,
    mut req: Request,
    next: Next,
) -> Result<Response, AppError> {
    let token = req
        .headers()
        .get(AUTHORIZATION)
        .and_then(|v| v.to_str().ok())
        .and_then(|v| v.strip_prefix("Bearer "))
        .ok_or(AppError::Unauthorized)?;

    let claims = validate_token(token, &state.jwt_secret)?;

    req.extensions_mut().insert(claims);
    Ok(next.run(req).await)
}

// Apply to routes
let protected = Router::new()
    .route("/me", get(get_me))
    .route_layer(middleware::from_fn_with_state(state.clone(), auth_middleware));

Actix-web Patterns

// Actix-web equivalent
use actix_web::{web, App, HttpServer, HttpResponse};

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let pool = create_pool().await;

    HttpServer::new(move || {
        App::new()
            .app_data(web::Data::new(pool.clone()))
            .service(
                web::scope("/api/v1")
                    .service(
                        web::scope("/users")
                            .route("", web::get().to(list_users))
                            .route("", web::post().to(create_user))
                            .route("/{id}", web::get().to(get_user))
                    )
            )
            .wrap(actix_web::middleware::Logger::default())
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

// Actix handler
async fn create_user(
    pool: web::Data<PgPool>,
    req: web::Json<CreateUserRequest>,
) -> Result<HttpResponse, actix_web::Error> {
    let user = User::create(&pool, req.into_inner()).await?;
    Ok(HttpResponse::Created().json(user))
}

Response Template

## Rust API Code Review Results

**Project**: [name]
**Framework**: Axum 0.7 | **Runtime**: Tokio

### Handler Organization
| Status | File | Issue |
|--------|------|-------|
| MEDIUM | main.rs | 30+ routes without nesting |

### Extractors
| Status | File | Issue |
|--------|------|-------|
| HIGH | handlers/user.rs:23 | Manual JSON parsing |

### State Management
| Status | File | Issue |
|--------|------|-------|
| CRITICAL | state.rs | std::sync::Mutex in async context |

### Error Handling
| Status | File | Issue |
|--------|------|-------|
| HIGH | handlers/product.rs | No IntoResponse for errors |

### Recommended Actions
1. [ ] Organize routes with Router::nest
2. [ ] Use Json extractor with validation
3. [ ] Replace std Mutex with tokio Mutex
4. [ ] Implement IntoResponse for AppError

Best Practices

1. Extractors: Use typed extractors, body last
2. State: Clone-friendly, async-safe
3. Errors: Custom type with IntoResponse
4. Middleware: Tower layers for cross-cutting
5. Tracing: Use tracing crate for observability

Integration

• rust-reviewer: General Rust patterns
• security-scanner: API security audit
• perf-analyzer: Async performance