autoworkflow 3.1.5 → 3.6.0

package/.claude/skills/axum.md

@@ -0,0 +1,386 @@
+# Axum Skill
+
+## Application Setup
+\`\`\`rust
+use axum::{
+    Router,
+    routing::{get, post, put, delete},
+    middleware,
+};
+use tower_http::{cors::CorsLayer, trace::TraceLayer, compression::CompressionLayer};
+use std::net::SocketAddr;
+
+#[tokio::main]
+async fn main() {
+    // Initialize tracing
+    tracing_subscriber::init();
+
+    // Create shared state
+    let db_pool = create_pool().await.expect("Failed to create pool");
+    let state = AppState { db: db_pool };
+
+    // Build router
+    let app = Router::new()
+        .nest("/api/v1", api_routes())
+        .layer(TraceLayer::new_for_http())
+        .layer(CompressionLayer::new())
+        .layer(CorsLayer::permissive())
+        .with_state(state);
+
+    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
+    tracing::info!("Listening on {}", addr);
+
+    let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
+    axum::serve(listener, app).await.unwrap();
+}
+
+fn api_routes() -> Router<AppState> {
+    Router::new()
+        .nest("/auth", auth_routes())
+        .nest("/users", user_routes())
+        .nest("/posts", post_routes())
+}
+
+fn auth_routes() -> Router<AppState> {
+    Router::new()
+        .route("/login", post(login))
+        .route("/register", post(register))
+}
+
+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))
+        .layer(middleware::from_fn(auth_middleware))
+}
+\`\`\`
+
+## Shared State
+\`\`\`rust
+use axum::extract::State;
+use sqlx::PgPool;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub db: PgPool,
+}
+
+// Access in handlers
+async fn get_user(
+    State(state): State<AppState>,
+    Path(id): Path<String>,
+) -> Result<Json<User>, AppError> {
+    let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
+        .fetch_optional(&state.db)
+        .await?
+        .ok_or(AppError::NotFound)?;
+
+    Ok(Json(user))
+}
+\`\`\`
+
+## Extractors
+\`\`\`rust
+use axum::{
+    extract::{Path, Query, State, Json},
+    http::HeaderMap,
+};
+use serde::Deserialize;
+
+// JSON body with validation
+#[derive(Deserialize)]
+pub struct CreateUserRequest {
+    pub email: String,
+    pub name: String,
+    pub password: String,
+}
+
+async fn create_user(
+    State(state): State<AppState>,
+    Json(body): Json<CreateUserRequest>,
+) -> Result<(StatusCode, Json<User>), AppError> {
+    // Validate
+    if body.email.is_empty() {
+        return Err(AppError::Validation("Email is required".into()));
+    }
+
+    let user = User::new(body.email, body.name, &body.password)?;
+    // ... save user
+
+    Ok((StatusCode::CREATED, Json(user)))
+}
+
+// Query parameters
+#[derive(Deserialize)]
+pub struct PaginationQuery {
+    #[serde(default = "default_page")]
+    pub page: u32,
+    #[serde(default = "default_per_page")]
+    pub per_page: u32,
+}
+
+fn default_page() -> u32 { 1 }
+fn default_per_page() -> u32 { 20 }
+
+async fn list_users(
+    State(state): State<AppState>,
+    Query(query): Query<PaginationQuery>,
+) -> Result<Json<Vec<User>>, AppError> {
+    let offset = (query.page - 1) * query.per_page;
+    let users = sqlx::query_as!(User,
+        "SELECT * FROM users LIMIT $1 OFFSET $2",
+        query.per_page as i64,
+        offset as i64
+    )
+    .fetch_all(&state.db)
+    .await?;
+
+    Ok(Json(users))
+}
+
+// Multiple path parameters
+async fn get_post_comment(
+    Path((post_id, comment_id)): Path<(String, String)>,
+) -> Result<Json<Comment>, AppError> {
+    // ...
+}
+
+// Headers
+async fn with_headers(headers: HeaderMap) -> impl IntoResponse {
+    let user_agent = headers
+        .get("user-agent")
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("unknown");
+    format!("User-Agent: {}", user_agent)
+}
+\`\`\`
+
+## Custom Extractors
+\`\`\`rust
+use axum::{
+    async_trait,
+    extract::FromRequestParts,
+    http::{request::Parts, StatusCode},
+    RequestPartsExt,
+};
+use axum_extra::{
+    headers::{authorization::Bearer, Authorization},
+    TypedHeader,
+};
+
+pub struct AuthUser {
+    pub user_id: String,
+    pub role: String,
+}
+
+#[async_trait]
+impl<S> FromRequestParts<S> for AuthUser
+where
+    S: Send + Sync,
+{
+    type Rejection = AppError;
+
+    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
+        // Extract Authorization header
+        let TypedHeader(Authorization(bearer)) = parts
+            .extract::<TypedHeader<Authorization<Bearer>>>()
+            .await
+            .map_err(|_| AppError::Unauthorized)?;
+
+        // Validate token
+        let claims = validate_token(bearer.token())
+            .map_err(|_| AppError::Unauthorized)?;
+
+        Ok(AuthUser {
+            user_id: claims.sub,
+            role: claims.role,
+        })
+    }
+}
+
+// Use in handler
+async fn protected_handler(auth: AuthUser) -> impl IntoResponse {
+    format!("Hello, user {}", auth.user_id)
+}
+\`\`\`
+
+## Middleware
+\`\`\`rust
+use axum::{
+    middleware::Next,
+    http::Request,
+    response::Response,
+};
+
+// Function-based middleware
+async fn auth_middleware(
+    request: Request<axum::body::Body>,
+    next: Next,
+) -> Result<Response, AppError> {
+    let auth_header = request
+        .headers()
+        .get("Authorization")
+        .and_then(|v| v.to_str().ok());
+
+    let token = match auth_header {
+        Some(h) if h.starts_with("Bearer ") => &h[7..],
+        _ => return Err(AppError::Unauthorized),
+    };
+
+    validate_token(token).map_err(|_| AppError::Unauthorized)?;
+
+    Ok(next.run(request).await)
+}
+
+// Apply to routes
+fn protected_routes() -> Router<AppState> {
+    Router::new()
+        .route("/profile", get(get_profile))
+        .layer(middleware::from_fn(auth_middleware))
+}
+
+// Request timing middleware
+async fn timing_middleware(
+    request: Request<axum::body::Body>,
+    next: Next,
+) -> Response {
+    let start = std::time::Instant::now();
+    let method = request.method().clone();
+    let uri = request.uri().clone();
+
+    let response = next.run(request).await;
+
+    let duration = start.elapsed();
+    tracing::info!("{} {} - {:?}", method, uri, duration);
+
+    response
+}
+\`\`\`
+
+## Error Handling
+\`\`\`rust
+use axum::{
+    response::{IntoResponse, Response},
+    http::StatusCode,
+    Json,
+};
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum AppError {
+    #[error("Resource not found")]
+    NotFound,
+
+    #[error("Unauthorized")]
+    Unauthorized,
+
+    #[error("Validation error: {0}")]
+    Validation(String),
+
+    #[error("Database error")]
+    Database(#[from] sqlx::Error),
+}
+
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        let (status, message) = match &self {
+            AppError::NotFound => (StatusCode::NOT_FOUND, self.to_string()),
+            AppError::Unauthorized => (StatusCode::UNAUTHORIZED, self.to_string()),
+            AppError::Validation(_) => (StatusCode::BAD_REQUEST, self.to_string()),
+            AppError::Database(e) => {
+                tracing::error!("Database error: {:?}", e);
+                (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error".into())
+            }
+        };
+
+        let body = Json(serde_json::json!({
+            "error": message
+        }));
+
+        (status, body).into_response()
+    }
+}
+
+// Handler returning Result
+async fn get_user(
+    State(state): State<AppState>,
+    Path(id): Path<String>,
+) -> Result<Json<User>, AppError> {
+    let user = find_user(&state.db, &id)
+        .await?
+        .ok_or(AppError::NotFound)?;
+
+    Ok(Json(user))
+}
+\`\`\`
+
+## Testing
+\`\`\`rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use axum::{
+        body::Body,
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt;  // for oneshot
+
+    async fn create_test_app() -> Router {
+        let state = AppState {
+            db: create_test_pool().await,
+        };
+        Router::new()
+            .nest("/api/v1", api_routes())
+            .with_state(state)
+    }
+
+    #[tokio::test]
+    async fn test_create_user() {
+        let app = create_test_app().await;
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/v1/users")
+                    .header("Content-Type", "application/json")
+                    .body(Body::from(r#"{"email":"test@example.com","name":"Test","password":"password123"}"#))
+                    .unwrap()
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(response.status(), StatusCode::CREATED);
+    }
+
+    #[tokio::test]
+    async fn test_get_user_not_found() {
+        let app = create_test_app().await;
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .uri("/api/v1/users/nonexistent")
+                    .body(Body::empty())
+                    .unwrap()
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(response.status(), StatusCode::NOT_FOUND);
+    }
+}
+\`\`\`
+
+## ✅ DO
+- Use \`Router::nest\` for modular route organization
+- Implement \`IntoResponse\` for custom error types
+- Use \`tower\` layers for cross-cutting concerns
+- Use custom extractors for auth/validation
+- Clone state only when needed (it should be \`Arc\` internally)
+
+## ❌ DON'T
+- Don't block async runtime with sync operations
+- Don't forget to derive \`Clone\` for \`AppState\`
+- Don't expose internal errors to clients
+- Don't use \`.unwrap()\` in handlers - return \`Result\`