add agents
This commit is contained in:
kingecg
parent
0d6f7dad04
commit
3e751c0b07
|
|
@ -0,0 +1,223 @@
|
|||
# AGENTS.md - Rust HTTP Server Project Guide
|
||||
|
||||
This file provides essential information for agentic coding agents working on the rhttpd project.
|
||||
|
||||
## Project Overview
|
||||
|
||||
rhttpd is a high-performance, configurable HTTP server written in Rust that supports:
|
||||
- Multi-site hosting on a single port
|
||||
- Multiple proxy types (reverse, forward, TCP)
|
||||
- JavaScript dynamic configuration
|
||||
- Static file serving with MIME type detection
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
|
||||
### Core Commands
|
||||
```bash
|
||||
# Build the project
|
||||
cargo build
|
||||
|
||||
# Build with optimizations
|
||||
cargo build --release
|
||||
|
||||
# Run the server
|
||||
cargo run
|
||||
|
||||
# Run tests
|
||||
cargo test
|
||||
|
||||
# Run a single test (replace test_name with actual test)
|
||||
cargo test test_name
|
||||
|
||||
# Run tests with output
|
||||
cargo test -- --nocapture
|
||||
|
||||
# Check code without building
|
||||
cargo check
|
||||
|
||||
# Format code
|
||||
cargo fmt
|
||||
|
||||
# Run clippy lints
|
||||
cargo clippy
|
||||
|
||||
# Run clippy with all targets and features
|
||||
cargo clippy --all-targets --all-features
|
||||
|
||||
# Generate documentation
|
||||
cargo doc --open
|
||||
|
||||
# Clean build artifacts
|
||||
cargo clean
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### General Rust Conventions
|
||||
- Use `rustfmt` for formatting (run `cargo fmt` before commits)
|
||||
- Follow Rust 2024 edition standards
|
||||
- Use `cargo clippy` to catch common issues and improve code
|
||||
|
||||
### Imports and Dependencies
|
||||
- Group imports in the following order:
|
||||
1. Standard library imports (`std::*`)
|
||||
2. Third-party crate imports
|
||||
3. Local module imports (`crate::*`)
|
||||
- Use explicit imports rather than glob imports where possible
|
||||
- Prefer `use crate::module::Item;` over `use super::module::Item;`
|
||||
|
||||
### Naming Conventions
|
||||
- **Functions and variables**: `snake_case`
|
||||
- **Types and structs**: `PascalCase`
|
||||
- **Constants**: `SCREAMING_SNAKE_CASE`
|
||||
- **Modules**: `snake_case`
|
||||
- **File names**: `snake_case.rs`
|
||||
|
||||
### Error Handling
|
||||
- Use `Result<T, E>` for functions that can fail
|
||||
- Create custom error types using `thiserror` or `anyhow` when needed
|
||||
- Use `?` operator for error propagation
|
||||
- Handle errors gracefully with proper logging
|
||||
- Avoid using `unwrap()` or `expect()` in production code
|
||||
|
||||
### Async/Await Patterns
|
||||
- Use `async`/`await` for asynchronous operations
|
||||
- Prefer `tokio` runtime for async operations
|
||||
- Use `.await` instead of blocking calls in async contexts
|
||||
- Handle async errors with `Result` types
|
||||
|
||||
### Struct and Enum Design
|
||||
- Use `#[derive(Debug, Clone, PartialEq, Eq)]` where appropriate
|
||||
- Implement `Default` for structs with sensible defaults
|
||||
- Use `serde` derives for configuration structs:
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
```
|
||||
- Use builder pattern for complex configuration
|
||||
|
||||
### Memory Management
|
||||
- Use `Arc<RwLock<T>>` for shared configuration that needs concurrent access
|
||||
- Use `Arc<Mutex<T>>` when exclusive access is needed
|
||||
- Prefer borrowing over cloning when possible
|
||||
- Use `Cow<str>` for string data that might be borrowed or owned
|
||||
|
||||
### Module Organization
|
||||
- Keep modules focused and cohesive
|
||||
- Use `mod.rs` for directory modules
|
||||
- Declare public APIs with `pub` keyword
|
||||
- Use `pub(crate)` for internal APIs shared across modules
|
||||
|
||||
### Testing Guidelines
|
||||
- Write unit tests for all public functions
|
||||
- Use `#[cfg(test)]` for test modules
|
||||
- Use integration tests in `tests/` directory for end-to-end testing
|
||||
- Mock external dependencies in tests
|
||||
- Use `tokio::test` for async tests
|
||||
|
||||
### Documentation
|
||||
- Document all public APIs with `///` doc comments
|
||||
- Use `#[doc]` attributes for module-level documentation
|
||||
- Include examples in doc comments where helpful
|
||||
- Use `cargo doc` to verify documentation builds correctly
|
||||
|
||||
### Performance Considerations
|
||||
- Use `Vec<T>` for collections when size is known
|
||||
- Use `String` for owned string data
|
||||
- Avoid unnecessary allocations
|
||||
- Use `&str` for string references when possible
|
||||
- Profile with `cargo flamegraph` for performance optimization
|
||||
|
||||
### Security Best Practices
|
||||
- Validate all external inputs
|
||||
- Use type-safe configurations
|
||||
- Avoid unsafe code unless absolutely necessary
|
||||
- Sanitize file paths to prevent directory traversal
|
||||
- Implement rate limiting for proxy endpoints
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
rhttpd/
|
||||
├── src/
|
||||
│ ├── main.rs # Application entry point
|
||||
│ ├── lib.rs # Library root (if applicable)
|
||||
│ ├── server/ # Server implementation
|
||||
│ ├── config/ # Configuration management
|
||||
│ ├── proxy/ # Proxy implementations
|
||||
│ └── js_engine/ # JavaScript integration
|
||||
├── tests/ # Integration tests
|
||||
├── doc/ # Documentation and requirements
|
||||
├── Cargo.toml # Project configuration
|
||||
└── AGENTS.md # This file
|
||||
```
|
||||
|
||||
## Key Dependencies (as specified in requirements)
|
||||
|
||||
### Core Runtime
|
||||
- `tokio` - Async runtime
|
||||
- `hyper` or `axum` - HTTP server framework
|
||||
- `tower` - Middleware and service abstractions
|
||||
|
||||
### Configuration
|
||||
- `serde` - Serialization/deserialization
|
||||
- `serde_json` - JSON support
|
||||
- `toml` - TOML configuration support
|
||||
|
||||
### Static Files
|
||||
- `tower-http` - HTTP service utilities
|
||||
- `mime_guess` - MIME type detection
|
||||
|
||||
### Proxy Support
|
||||
- `reqwest` - HTTP client for reverse proxy
|
||||
- `tokio-util` - Utilities for async I/O
|
||||
- `tokio-native-tls` - TLS support
|
||||
|
||||
### JavaScript Engine
|
||||
- Choose one: `deno_core`, `rquickjs`, or `boa_engine`
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. Run `cargo check` to verify code compiles
|
||||
2. Run `cargo clippy` to catch issues
|
||||
3. Run `cargo fmt` to format code
|
||||
4. Run `cargo test` to verify tests pass
|
||||
5. Commit changes with descriptive messages
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- Unit tests for individual components
|
||||
- Integration tests for end-to-end functionality
|
||||
- Performance tests for proxy operations
|
||||
- Configuration validation tests
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Configuration Loading
|
||||
```rust
|
||||
#[derive(Debug, Deserialize)]
|
||||
struct ServerConfig {
|
||||
port: u16,
|
||||
sites: HashMap<String, SiteConfig>,
|
||||
}
|
||||
```
|
||||
|
||||
### Error Types
|
||||
```rust
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
enum ServerError {
|
||||
#[error("Configuration error: {0}")]
|
||||
Config(#[from] ConfigError),
|
||||
#[error("IO error: {0}")]
|
||||
Io(#[from] std::io::Error),
|
||||
}
|
||||
```
|
||||
|
||||
### Async Service Pattern
|
||||
```rust
|
||||
#[async_trait]
|
||||
trait ProxyService {
|
||||
async fn handle_request(&self, req: Request<Body>) -> Result<Response<Body>, ServerError>;
|
||||
}
|
||||
```
|
||||
|
||||
Remember to run `cargo fmt` and `cargo clippy` before committing changes!
|
||||
Loading…
Reference in New Issue