rustfs/.cursorrules

# RustFS Project Cursor Rules

## Project Overview
RustFS is a high-performance distributed object storage system written in Rust, compatible with S3 API. The project adopts a modular architecture, supporting erasure coding storage, multi-tenant management, observability, and other enterprise-level features.

## Core Architecture Principles

### 1. Modular Design
- Project uses Cargo workspace structure, containing multiple independent crates
- Core modules: `rustfs` (main service), `ecstore` (erasure coding storage), `common` (shared components)
- Functional modules: `iam` (identity management), `madmin` (management interface), `crypto` (encryption), etc.
- Tool modules: `cli` (command line tool), `crates/*` (utility libraries)

### 2. Asynchronous Programming Pattern
- Comprehensive use of `tokio` async runtime
- Prioritize `async/await` syntax
- Use `async-trait` for async methods in traits
- Avoid blocking operations, use `spawn_blocking` when necessary

### 3. Error Handling Strategy
- Use unified error type `common::error::Error`
- Support error chains and context information
- Use `thiserror` to define specific error types
- Error conversion uses `downcast_ref` for type checking

## Code Style Guidelines

### 1. Formatting Configuration
```toml
max_width = 130
fn_call_width = 90
single_line_let_else_max_width = 100
```

### 2. Naming Conventions
- Use `snake_case` for functions, variables, modules
- Use `PascalCase` for types, traits, enums
- Constants use `SCREAMING_SNAKE_CASE`
- Global variables prefix `GLOBAL_`, e.g., `GLOBAL_Endpoints`
- Use meaningful and descriptive names for variables, functions, and methods
- Avoid meaningless names like `temp`, `data`, `foo`, `bar`, `test123`
- Choose names that clearly express the purpose and intent

### 3. Documentation Comments
- Public APIs must have documentation comments
- Use `///` for documentation comments
- Complex functions add `# Examples` and `# Parameters` descriptions
- Error cases use `# Errors` descriptions
- Always use English for all comments and documentation
- Avoid meaningless comments like "debug 111" or placeholder text

### 4. Import Guidelines
- Standard library imports first
- Third-party crate imports in the middle
- Project internal imports last
- Group `use` statements with blank lines between groups

## Asynchronous Programming Guidelines

### 1. Trait Definition
```rust
#[async_trait::async_trait]
pub trait StorageAPI: Send + Sync {
    async fn get_object(&self, bucket: &str, object: &str) -> Result<ObjectInfo>;
}
```

### 2. Error Handling
```rust
// Use ? operator to propagate errors
async fn example_function() -> Result<()> {
    let data = read_file("path").await?;
    process_data(data).await?;
    Ok(())
}
```

### 3. Concurrency Control
- Use `Arc` and `Mutex`/`RwLock` for shared state management
- Prioritize async locks from `tokio::sync`
- Avoid holding locks for long periods

## Logging and Tracing Guidelines

### 1. Tracing Usage
```rust
#[tracing::instrument(skip(self, data))]
async fn process_data(&self, data: &[u8]) -> Result<()> {
    info!("Processing {} bytes", data.len());
    // Implementation logic
}
```

### 2. Log Levels
- `error!`: System errors requiring immediate attention
- `warn!`: Warning information that may affect functionality
- `info!`: Important business information
- `debug!`: Debug information for development use
- `trace!`: Detailed execution paths

### 3. Structured Logging
```rust
info!(
    counter.rustfs_api_requests_total = 1_u64,
    key_request_method = %request.method(),
    key_request_uri_path = %request.uri().path(),
    "API request processed"
);
```

## Error Handling Guidelines

### 1. Error Type Definition
```rust
#[derive(Debug, thiserror::Error)]
pub enum MyError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("Custom error: {message}")]
    Custom { message: String },
}
```

### 2. Error Conversion
```rust
pub fn to_s3_error(err: Error) -> S3Error {
    if let Some(storage_err) = err.downcast_ref::<StorageError>() {
        match storage_err {
            StorageError::ObjectNotFound(bucket, object) => {
                s3_error!(NoSuchKey, "{}/{}", bucket, object)
            }
            // Other error types...
        }
    }
    // Default error handling
}
```

### 3. Error Context
```rust
// Add error context
.map_err(|e| Error::from_string(format!("Failed to process {}: {}", path, e)))?
```

## Performance Optimization Guidelines

### 1. Memory Management
- Use `Bytes` instead of `Vec<u8>` for zero-copy operations
- Avoid unnecessary cloning, use reference passing
- Use `Arc` for sharing large objects

### 2. Concurrency Optimization
```rust
// Use join_all for concurrent operations
let futures = disks.iter().map(|disk| disk.operation());
let results = join_all(futures).await;
```

### 3. Caching Strategy
- Use `lazy_static` or `OnceCell` for global caching
- Implement LRU cache to avoid memory leaks

## Testing Guidelines

### 1. Unit Tests
```rust
#[cfg(test)]
mod tests {
    use super::*;
    use test_case::test_case;

    #[tokio::test]
    async fn test_async_function() {
        let result = async_function().await;
        assert!(result.is_ok());
    }

    #[test_case("input1", "expected1")]
    #[test_case("input2", "expected2")]
    fn test_with_cases(input: &str, expected: &str) {
        assert_eq!(function(input), expected);
    }
}
```

### 2. Integration Tests
- Use `e2e_test` module for end-to-end testing
- Simulate real storage environments

### 3. Test Quality Standards
- Write meaningful test cases that verify actual functionality
- Avoid placeholder or debug content like "debug 111", "test test", etc.
- Use descriptive test names that clearly indicate what is being tested
- Each test should have a clear purpose and verify specific behavior
- Test data should be realistic and representative of actual use cases

## Cross-Platform Compatibility Guidelines

### 1. CPU Architecture Compatibility
- **Always consider multi-platform and different CPU architecture compatibility** when writing code
- Support major architectures: x86_64, aarch64 (ARM64), and other target platforms
- Use conditional compilation for architecture-specific code:
```rust
#[cfg(target_arch = "x86_64")]
fn optimized_x86_64_function() { /* x86_64 specific implementation */ }

#[cfg(target_arch = "aarch64")]
fn optimized_aarch64_function() { /* ARM64 specific implementation */ }

#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
fn generic_function() { /* Generic fallback implementation */ }
```

### 2. Platform-Specific Dependencies
- Use feature flags for platform-specific dependencies
- Provide fallback implementations for unsupported platforms
- Test on multiple architectures in CI/CD pipeline

### 3. Endianness Considerations
- Use explicit byte order conversion when dealing with binary data
- Prefer `to_le_bytes()`, `from_le_bytes()` for consistent little-endian format
- Use `byteorder` crate for complex binary format handling

### 4. SIMD and Performance Optimizations
- Use portable SIMD libraries like `wide` or `packed_simd`
- Provide fallback implementations for non-SIMD architectures
- Use runtime feature detection when appropriate

## Security Guidelines

### 1. Memory Safety
- Disable `unsafe` code (workspace.lints.rust.unsafe_code = "deny")
- Use `rustls` instead of `openssl`

### 2. Authentication and Authorization
```rust
// Use IAM system for permission checks
let identity = iam.authenticate(&access_key, &secret_key).await?;
iam.authorize(&identity, &action, &resource).await?;
```

## Configuration Management Guidelines

### 1. Environment Variables
- Use `RUSTFS_` prefix
- Support both configuration files and environment variables
- Provide reasonable default values

### 2. Configuration Structure
```rust
#[derive(Debug, Deserialize, Clone)]
pub struct Config {
    pub address: String,
    pub volumes: String,
    #[serde(default)]
    pub console_enable: bool,
}
```

## Dependency Management Guidelines

### 1. Workspace Dependencies
- Manage versions uniformly at workspace level
- Use `workspace = true` to inherit configuration

### 2. Feature Flags
```rust
[features]
default = ["file"]
gpu = ["dep:nvml-wrapper"]
kafka = ["dep:rdkafka"]
```

## Deployment and Operations Guidelines

### 1. Containerization
- Provide Dockerfile and docker-compose configuration
- Support multi-stage builds to optimize image size

### 2. Observability
- Integrate OpenTelemetry for distributed tracing
- Support Prometheus metrics collection
- Provide Grafana dashboards

### 3. Health Checks
```rust
// Implement health check endpoint
async fn health_check() -> Result<HealthStatus> {
    // Check component status
}
```

## Code Review Checklist

### 1. Functionality
- [ ] Are all error cases properly handled?
- [ ] Is there appropriate logging?
- [ ] Is there necessary test coverage?

### 2. Performance
- [ ] Are unnecessary memory allocations avoided?
- [ ] Are async operations used correctly?
- [ ] Are there potential deadlock risks?

### 3. Security
- [ ] Are input parameters properly validated?
- [ ] Are there appropriate permission checks?
- [ ] Is information leakage avoided?

### 4. Cross-Platform Compatibility
- [ ] Does the code work on different CPU architectures (x86_64, aarch64)?
- [ ] Are platform-specific features properly gated with conditional compilation?
- [ ] Is byte order handling correct for binary data?
- [ ] Are there appropriate fallback implementations for unsupported platforms?

### 5. Maintainability
- [ ] Is the code clear and understandable?
- [ ] Does it follow the project's architectural patterns?
- [ ] Is there appropriate documentation?

### 6. Code Commits and Documentation
- [ ] Does it comply with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)?
- [ ] Are commit messages concise and under 72 characters for the title line?
- [ ] Commit titles should be concise and in English, avoid Chinese
- [ ] Is PR description provided in copyable markdown format for easy copying?

## Common Patterns and Best Practices

### 1. Resource Management
```rust
// Use RAII pattern for resource management
pub struct ResourceGuard {
    resource: Resource,
}

impl Drop for ResourceGuard {
    fn drop(&mut self) {
        // Clean up resources
    }
}
```

### 2. Dependency Injection
```rust
// Use dependency injection pattern
pub struct Service {
    config: Arc<Config>,
    storage: Arc<dyn StorageAPI>,
}
```

### 3. Graceful Shutdown
```rust
// Implement graceful shutdown
async fn shutdown_gracefully(shutdown_rx: &mut Receiver<()>) {
    tokio::select! {
        _ = shutdown_rx.recv() => {
            info!("Received shutdown signal");
            // Perform cleanup operations
        }
        _ = tokio::time::sleep(SHUTDOWN_TIMEOUT) => {
            warn!("Shutdown timeout reached");
        }
    }
}
```

## Domain-Specific Guidelines

### 1. Storage Operations
- All storage operations must support erasure coding
- Implement read/write quorum mechanisms
- Support data integrity verification

### 2. Network Communication
- Use gRPC for internal service communication
- HTTP/HTTPS support for S3-compatible API
- Implement connection pooling and retry mechanisms

### 3. Metadata Management
- Use FlatBuffers for serialization
- Support version control and migration
- Implement metadata caching

These rules should serve as guiding principles when developing the RustFS project, ensuring code quality, performance, and maintainability.

### 4. Code Operations

#### Branch Management
 - **NEVER modify code directly on main or master branch**
 - Always check the .cursorrules file before starting to ensure you understand the project guidelines
 - Before starting any change or requirement development, first git checkout to main branch, then git pull to get the latest code
 - For each feature or change to be developed, first create a branch, then git checkout to that branch
 - Use descriptive branch names following the pattern: `feat/feature-name`, `fix/issue-name`, `refactor/component-name`, etc.
 - Ensure all changes are made on feature branches and merged through pull requests

#### Development Workflow
 - Use English for all code comments, documentation, and variable names
 - Write meaningful and descriptive names for variables, functions, and methods
 - Avoid meaningless test content like "debug 111" or placeholder values
 - Before each change, carefully read the existing code to ensure you understand the code structure and implementation, do not break existing logic implementation, do not introduce new issues
 - Ensure each change provides sufficient test cases to guarantee code correctness
 - Do not arbitrarily modify numbers and constants in test cases, carefully analyze their meaning to ensure test case correctness
 - When writing or modifying tests, check existing test cases to ensure they have scientific naming and rigorous logic testing, if not compliant, modify test cases to ensure scientific and rigorous testing
 - **Before committing any changes, run `cargo clippy --all-targets --all-features -- -D warnings` to ensure all code passes Clippy checks**
 - After each development completion, first git add . then git commit -m "feat: feature description" or "fix: issue description", ensure compliance with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
 - **Keep commit messages concise and under 72 characters** for the title line, use body for detailed explanations if needed
 - After each development completion, first git push to remote repository
 - After each change completion, summarize the changes, do not create summary files, provide a brief change description, ensure compliance with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
 - Provide change descriptions needed for PR in the conversation, ensure compliance with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
 - **Always provide PR descriptions in English** after completing any changes, including:
   - Clear and concise title following Conventional Commits format
   - Detailed description of what was changed and why
   - List of key changes and improvements
   - Any breaking changes or migration notes if applicable
   - Testing information and verification steps
 - **Provide PR descriptions in copyable markdown format** enclosed in code blocks for easy one-click copying