/scaffold-rust-axum

allowed-tools: Write, Bash(cargo:*), Bash(mkdir:*), Bash(cd:*), Bash(gdate:*), Bash(jq:*), Bash(pwd:*), Bash(eza:*), Bash(fd:*)
name: "Scaffold Rust Axum"
description: "Scaffold production-ready Rust Axum web server with modern async patterns, dependency injection, and comprehensive testing setup"
author: "wcygan"
tags: ["scaffold","rust"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

Context

• Session ID: !`gdate +%s%N 2>/dev/null || date +%s%N 2>/dev/null || echo "$(date +%s)$(jot -r 1 100000 999999 2>/dev/null || shuf -i 100000-999999 -n 1 2>/dev/null || echo $RANDOM$RANDOM)"`
• Target project name: $ARGUMENTS
• Current directory: !`pwd`
• Rust toolchain: !`rustc --version 2>/dev/null || echo "Rust not installed - install via rustup"`
• Cargo version: !`cargo --version 2>/dev/null || echo "Cargo not available"`
• Available disk space: !`df -h . | tail -1 | awk '{print $4}' 2>/dev/null || echo "Unknown"`
• Directory contents: !`eza -la . 2>/dev/null | head -5 || ls -la . | head -5`

Your Task

STEP 1: Initialize session state and validate prerequisites

• CREATE session state file: `/tmp/scaffold-rust-axum-$SESSION_ID.json`
• VALIDATE Rust toolchain installation
• CHECK project name validity (alphanumeric, hyphens, underscores only)
• ENSURE target directory doesn't already exist
• VERIFY sufficient disk space for project creation

# Initialize scaffold session state
echo '{
  "sessionId": "'$SESSION_ID'",
  "projectName": "'$ARGUMENTS'",
  "timestamp": "'$(gdate -Iseconds 2>/dev/null || date -Iseconds)'",
  "phase": "initialization",
  "components": [],
  "dependencies": {}
}' > /tmp/scaffold-rust-axum-$SESSION_ID.json

STEP 2: Project structure creation with modern Rust patterns

TRY:

• CREATE project directory with proper ownership
• INITIALIZE Cargo project with workspace configuration
• SET UP modern project structure following Rust best practices
• CONFIGURE development environment optimizations

**Modern Rust Axum Project Structure:**

$ARGUMENTS/
├── Cargo.toml              # Workspace configuration
├── .gitignore              # Comprehensive Rust gitignore
├── README.md               # Concise project documentation
├── docker-compose.yml      # Development services (Postgres, DragonflyDB)
├── src/
│   ├── main.rs            # Application entry point
│   ├── lib.rs             # Library interface
│   ├── config/            # Configuration management
│   │   ├── mod.rs
│   │   └── database.rs
│   ├── handlers/          # HTTP request handlers
│   │   ├── mod.rs
│   │   ├── health.rs
│   │   └── api/
│   ├── models/            # Data models and types
│   │   └── mod.rs
│   ├── services/          # Business logic layer
│   │   └── mod.rs
│   ├── middleware/        # Custom middleware
│   │   └── mod.rs
│   └── utils/             # Utility functions
│       └── mod.rs
├── tests/                 # Integration tests
│   ├── common/
│   │   └── mod.rs
│   └── integration_test.rs
└── benches/               # Performance benchmarks
    └── api_bench.rs

**Cargo.toml with Modern Dependencies:**

[package]
name = "$ARGUMENTS"
version = "0.1.0"
edition = "2021"
rust-version = "1.70"
authors = ["Your Name <your.email@example.com>"]
description = "Production-ready Axum web server"
license = "MIT OR Apache-2.0"
repository = "https://github.com/yourusername/$ARGUMENTS"
keywords = ["axum", "web", "api", "async"]
categories = ["web-programming::http-server"]

[dependencies]
# Core web framework
axum = { version = "0.7", features = ["macros", "json", "query", "form"] }
tokio = { version = "1.0", features = ["full"] }
tower = { version = "0.4", features = ["util", "timeout", "load-shed", "limit"] }
tower-http = { version = "0.5", features = ["add-extension", "cors", "compression-gzip", "trace"] }
hyper = { version = "1.0", features = ["full"] }

# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

# Database (Postgres focus)
sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres", "uuid", "chrono", "json"] }
uuid = { version = "1.0", features = ["v4", "serde"] }

# Configuration
config = "0.14"
envconfig = "0.10"

# Observability
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
tracing-opentelemetry = "0.22"
opentelemetry = "0.21"

# Error handling
anyhow = "1.0"
thiserror = "1.0"

# Security
argon2 = "0.5"
jsonwebtoken = "9.0"

# Time
chrono = { version = "0.4", features = ["serde"] }

[dev-dependencies]
# Testing
tokio-test = "0.4"
axum-test = "14.0"
httpc-test = "0.1"

# Benchmarking
criterion = { version = "0.5", features = ["html_reports"] }

[[bench]]
name = "api_bench"
harness = false

[profile.dev]
opt-level = 0
debug = true

[profile.release]
opt-level = 3
lto = true
codegen-units = 1
panic = "abort"

[profile.test]
opt-level = 1

STEP 3: Core application implementation with dependency injection

**Main Application (src/main.rs):**

//! Production-ready Axum web server with modern async patterns

use axum::{
    extract::State,
    response::Html,
    routing::{get, post},
    Json, Router,
};
use std::net::SocketAddr;
use tower::ServiceBuilder;
use tower_http::{
    cors::CorsLayer,
    compression::CompressionLayer,
    trace::TraceLayer,
};
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

mod config;
mod handlers;
mod middleware;
mod models;
mod services;
mod utils;

use config::AppConfig;

#[derive(Clone)]
pub struct AppState {
    config: AppConfig,
    // Add database pool, redis client, etc.
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialize tracing
    tracing_subscriber::registry()
        .with(
            tracing_subscriber::EnvFilter::try_from_default_env()
                .unwrap_or_else(|_| "$ARGUMENTS=debug,tower_http=debug".into()),
        )
        .with(tracing_subscriber::fmt::layer())
        .init();

    // Load configuration