Initial commit
This commit is contained in:
Zhongwei Li
247
commands/tokio-scaffold.md
Normal file
247
commands/tokio-scaffold.md
Normal file
@@ -0,0 +1,247 @@
|
||||
---
|
||||
name: tokio-scaffold
|
||||
description: Scaffold new Tokio projects with proper structure and best practices
|
||||
---
|
||||
|
||||
# Tokio Scaffold Command
|
||||
|
||||
This command scaffolds new Tokio-based Rust projects with modern structure, proper dependencies, error handling patterns, tracing infrastructure, and testing setup.
|
||||
|
||||
## Arguments
|
||||
|
||||
- `$1` - Project name (required)
|
||||
- `$2` - Project type: `http-server`, `grpc-server`, `tcp-server`, `cli`, or `library` (optional, defaults to `library`)
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/rust-tokio-expert:tokio-scaffold my-service http-server
|
||||
/rust-tokio-expert:tokio-scaffold my-cli cli
|
||||
/rust-tokio-expert:tokio-scaffold my-lib library
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Validate Arguments**
|
||||
- Check that project name is provided
|
||||
- Validate project type if provided
|
||||
- Ensure target directory doesn't already exist
|
||||
|
||||
2. **Invoke Agent**
|
||||
- Use Task tool with `subagent_type="rust-tokio-expert:tokio-pro"`
|
||||
- Pass project name and type to the agent
|
||||
|
||||
3. **Agent Instructions**
|
||||
|
||||
The agent should create a complete project structure based on the type:
|
||||
|
||||
### For HTTP Server Projects
|
||||
|
||||
Create:
|
||||
- `Cargo.toml` with dependencies:
|
||||
- tokio with full features
|
||||
- axum for HTTP framework
|
||||
- tower and tower-http for middleware
|
||||
- serde and serde_json for serialization
|
||||
- tracing and tracing-subscriber for logging
|
||||
- anyhow and thiserror for error handling
|
||||
- sqlx (optional) for database
|
||||
- config for configuration management
|
||||
|
||||
- `src/main.rs` with:
|
||||
- Runtime setup with tracing
|
||||
- Router configuration
|
||||
- Graceful shutdown handling
|
||||
- Health check endpoints
|
||||
|
||||
- `src/handlers/mod.rs` with example HTTP handlers
|
||||
- `src/error.rs` with custom error types
|
||||
- `src/config.rs` with configuration loading
|
||||
- `src/telemetry.rs` with tracing setup
|
||||
|
||||
- `tests/integration_test.rs` with API integration tests
|
||||
- `.env.example` with configuration template
|
||||
- `README.md` with usage instructions
|
||||
|
||||
### For gRPC Server Projects
|
||||
|
||||
Create:
|
||||
- `Cargo.toml` with:
|
||||
- tokio with full features
|
||||
- tonic and tonic-build
|
||||
- prost for protobuf
|
||||
- tower for middleware
|
||||
- tracing infrastructure
|
||||
- error handling crates
|
||||
|
||||
- `proto/service.proto` with example service definition
|
||||
- `build.rs` for proto compilation
|
||||
- `src/main.rs` with gRPC server setup
|
||||
- `src/service.rs` with service implementation
|
||||
- `src/error.rs` with error types
|
||||
- `tests/integration_test.rs`
|
||||
|
||||
### For TCP Server Projects
|
||||
|
||||
Create:
|
||||
- `Cargo.toml` with:
|
||||
- tokio with io-util, net features
|
||||
- tokio-util with codec
|
||||
- bytes for buffer management
|
||||
- tracing infrastructure
|
||||
|
||||
- `src/main.rs` with TCP server setup
|
||||
- `src/protocol.rs` with protocol definition
|
||||
- `src/handler.rs` with connection handler
|
||||
- `tests/integration_test.rs`
|
||||
|
||||
### For CLI Projects
|
||||
|
||||
Create:
|
||||
- `Cargo.toml` with:
|
||||
- tokio with full features
|
||||
- clap for argument parsing
|
||||
- anyhow for error handling
|
||||
- tracing-subscriber for logging
|
||||
|
||||
- `src/main.rs` with CLI setup
|
||||
- `src/commands/mod.rs` with command structure
|
||||
- `src/config.rs` with configuration
|
||||
- `tests/cli_test.rs`
|
||||
|
||||
### For Library Projects
|
||||
|
||||
Create:
|
||||
- `Cargo.toml` with:
|
||||
- tokio as optional dependency
|
||||
- async-trait
|
||||
- thiserror for errors
|
||||
|
||||
- `src/lib.rs` with library structure
|
||||
- `tests/lib_test.rs` with comprehensive tests
|
||||
- `examples/basic.rs` with usage example
|
||||
- `README.md` with API documentation
|
||||
|
||||
4. **Common Files for All Types**
|
||||
|
||||
- `.gitignore` with Rust-specific ignores
|
||||
- `Cargo.toml` with proper metadata
|
||||
- `rustfmt.toml` with formatting rules
|
||||
- `clippy.toml` with linting configuration (if needed)
|
||||
|
||||
5. **Initialize Testing**
|
||||
|
||||
For all project types:
|
||||
- Add `#[tokio::test]` examples
|
||||
- Include timeout tests
|
||||
- Add mock/test utilities
|
||||
- Set up test helpers
|
||||
|
||||
6. **Documentation**
|
||||
|
||||
Generate `README.md` with:
|
||||
- Project description
|
||||
- Requirements
|
||||
- Installation instructions
|
||||
- Usage examples
|
||||
- Development setup
|
||||
- Testing instructions
|
||||
- Contributing guidelines
|
||||
|
||||
7. **Verification**
|
||||
|
||||
After scaffolding:
|
||||
- Run `cargo check` to verify compilation
|
||||
- Run `cargo test` to verify tests
|
||||
- Report any issues found
|
||||
|
||||
## Example Cargo.toml Template (HTTP Server)
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "{{project_name}}"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
tokio = { version = "1", features = ["full"] }
|
||||
axum = "0.7"
|
||||
tower = "0.4"
|
||||
tower-http = { version = "0.5", features = ["trace", "compression-gzip"] }
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
tracing = "0.1"
|
||||
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
|
||||
anyhow = "1"
|
||||
thiserror = "1"
|
||||
config = "0.14"
|
||||
|
||||
[dev-dependencies]
|
||||
tokio-test = "0.4"
|
||||
```
|
||||
|
||||
## Example Main Template (HTTP Server)
|
||||
|
||||
```rust
|
||||
use axum::{Router, routing::get};
|
||||
use std::net::SocketAddr;
|
||||
use tower_http::trace::TraceLayer;
|
||||
|
||||
mod handlers;
|
||||
mod error;
|
||||
mod config;
|
||||
mod telemetry;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> anyhow::Result<()> {
|
||||
// Initialize telemetry
|
||||
telemetry::init()?;
|
||||
|
||||
// Load configuration
|
||||
let config = config::load()?;
|
||||
|
||||
// Create router
|
||||
let app = Router::new()
|
||||
.route("/health", get(handlers::health_check))
|
||||
.route("/api/v1/users", get(handlers::list_users))
|
||||
.layer(TraceLayer::new_for_http());
|
||||
|
||||
// Start server
|
||||
let addr = SocketAddr::from(([0, 0, 0, 0], config.port));
|
||||
tracing::info!("Starting server on {}", addr);
|
||||
|
||||
let listener = tokio::net::TcpListener::bind(addr).await?;
|
||||
axum::serve(listener, app)
|
||||
.with_graceful_shutdown(shutdown_signal())
|
||||
.await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn shutdown_signal() {
|
||||
tokio::signal::ctrl_c()
|
||||
.await
|
||||
.expect("failed to install CTRL+C signal handler");
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
The scaffolded project should follow these best practices:
|
||||
|
||||
1. **Error Handling**: Use `thiserror` for domain errors, `anyhow` for application errors
|
||||
2. **Configuration**: Use environment variables with sensible defaults
|
||||
3. **Logging**: Use `tracing` with structured logging
|
||||
4. **Testing**: Include both unit and integration tests
|
||||
5. **Documentation**: Generate comprehensive README with examples
|
||||
6. **Security**: Include basic security headers and validation
|
||||
7. **Performance**: Configure runtime appropriately for workload type
|
||||
8. **Observability**: Include metrics and health check endpoints
|
||||
|
||||
## Notes
|
||||
|
||||
- Always use the latest stable versions of dependencies
|
||||
- Include comments explaining key architectural decisions
|
||||
- Provide both simple and advanced usage examples
|
||||
- Generate projects that compile and pass tests out of the box
|
||||
- Follow Rust API guidelines and naming conventions
|
||||
Reference in New Issue
Block a user