# Development Guide
Guide for developers who want to contribute to or modify V-Queue.
## Project Structure
```
v-queue/
├── src/ # Core library
│ ├── lib.rs # Library entry point
│ ├── queue.rs # Queue implementation
│ ├── consumer.rs # Consumer tracking
│ ├── record.rs # Message format
│ └── test.rs # Core tests
│
├── v-queue-server/ # HTTP server
│ ├── src/
│ │ ├── main.rs # Server entry point
│ │ ├── lib.rs # Library exports
│ │ ├── api.rs # HTTP handlers
│ │ ├── auth.rs # Authentication
│ │ ├── config.rs # Configuration
│ │ ├── error.rs # Error types
│ │ ├── queue_manager.rs # Queue management
│ │ └── utils.rs # Utilities
│ │
│ ├── tests/
│ │ ├── integration_tests.rs # API tests
│ │ └── auth_integration_tests.rs # Auth tests
│ │
│ └── examples/ # Client examples
│ ├── python_client.py
│ ├── nodejs_client.js
│ └── rust_client.rs
│
├── java/ # Java bindings
│ ├── libjvqueue/ # JNI wrapper
│ └── vqueue-binding/ # Java API
│
└── doc/ # Documentation
├── README.md
└── *.md
```
## Development Setup
### Prerequisites
```bash
# Install Rust
# Install development tools
sudo apt install build-essential pkg-config
# Install clippy and rustfmt
rustup component add clippy rustfmt
```
### Clone and Build
```bash
git clone https://github.com/semantic-machines/v-queue.git
cd v-queue
# Build core library
cargo build
# Build server
cd v-queue-server
cargo build
# Run tests
cargo test
```
## Building
### Debug Build
```bash
cargo build
```
Output: `target/debug/v-queue-server`
### Release Build
```bash
cargo build --release
```
Output: `target/release/v-queue-server`
Release builds are ~10x faster but take longer to compile.
### Build with Specific Features
```bash
# Core library only
cargo build -p v_queue
# Server only
cargo build -p v-queue-server
```
## Testing
### Run All Tests
```bash
# Core library tests
cargo test
# Server tests
cd v-queue-server
cargo test
```
### Run Specific Test
```bash
cargo test test_name
# With output
cargo test test_name -- --nocapture
# Integration tests only
cargo test --test integration_tests
```
### Run with Coverage (requires tarpaulin)
```bash
cargo install cargo-tarpaulin
cargo tarpaulin --out Html
```
## Code Quality
### Format Code
```bash
cargo fmt
```
Check formatting without changing:
```bash
cargo fmt -- --check
```
### Lint Code
```bash
cargo clippy
# Strict mode
cargo clippy -- -D warnings
```
### Check Without Building
```bash
cargo check
```
Faster than full build, good for quick validation.
## Running Tests
### Unit Tests
Located in source files:
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_something() {
assert_eq!(2 + 2, 4);
}
}
```
Run:
```bash
cargo test
```
### Integration Tests
Located in `v-queue-server/tests/`:
```bash
cargo test --test integration_tests
cargo test --test auth_integration_tests
```
### Manual Testing
Start test server:
```bash
cargo run -- --bind 127.0.0.1:9999 --data-dir /tmp/vqueue-test --no-auth
```
Test with curl:
```bash
curl http://127.0.0.1:9999/health
```
## Debugging
### Debug Logging
```bash
RUST_LOG=debug cargo run
```
Log levels: `error`, `warn`, `info`, `debug`, `trace`
### Run with Debugger
Using lldb:
```bash
rust-lldb target/debug/v-queue-server
(lldb) run --bind 127.0.0.1:9093
```
Using gdb:
```bash
rust-gdb target/debug/v-queue-server
(gdb) run --bind 127.0.0.1:9093
```
### Memory Debugging (Valgrind)
```bash
cargo build
valgrind --leak-check=full target/debug/v-queue-server
```
## Performance Profiling
### Using perf (Linux)
```bash
# Build with debug symbols
cargo build --release
# Record
sudo perf record -g target/release/v-queue-server
# Report
sudo perf report
```
### Using flamegraph
```bash
cargo install flamegraph
# Generate flamegraph
cargo flamegraph --bin v-queue-server
```
### Benchmarking
Create benchmark:
```rust
// benches/queue_bench.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};
fn queue_push_benchmark(c: &mut Criterion) {
c.bench_function("queue push", |b| {
b.iter(|| {
// Benchmark code
});
});
}
criterion_group!(benches, queue_push_benchmark);
criterion_main!(benches);
```
Run:
```bash
cargo bench
```
## Adding Features
### 1. Core Library Feature
Example: Add new message type
**Step 1**: Update `record.rs`:
```rust
pub enum MsgType {
String = 0,
Object = 1,
NewType = 2, // Add new type
}
```
**Step 2**: Update serialization/deserialization
**Step 3**: Add tests:
```rust
#[test]
fn test_new_type() {
// Test code
}
```
**Step 4**: Update documentation
### 2. Server API Feature
Example: Add new endpoint
**Step 1**: Add handler in `api.rs`:
```rust
pub async fn new_endpoint(
State(state): State<AppState>,
) -> Result<Json<Response>, ApiError> {
// Handler implementation
Ok(Json(Response { /* ... */ }))
}
```
**Step 2**: Add route in `main.rs`:
```rust
.route("/api/v1/new-endpoint", get(new_endpoint))
```
**Step 3**: Add integration test:
```rust
#[tokio::test]
async fn test_new_endpoint() {
// Test code
}
```
**Step 4**: Update API documentation
## Dependencies
### Adding Dependencies
Edit `Cargo.toml`:
```toml
[dependencies]
new_crate = "1.0"
```
Then:
```bash
cargo build
```
### Updating Dependencies
```bash
# Check for updates
cargo outdated
# Update all
cargo update
# Update specific crate
cargo update -p crate_name
```
### Audit Dependencies
```bash
cargo install cargo-audit
cargo audit
```
## Contributing Guidelines
### Code Style
Follow Rust conventions:
- Use `snake_case` for functions and variables
- Use `CamelCase` for types
- Format with `rustfmt`
- Lint with `clippy`
- Add documentation comments for public API
Example:
```rust
/// Consume messages from the queue.
///
/// # Arguments
///
/// * `timeout` - Timeout in seconds
/// * `max_messages` - Maximum messages to return
///
/// # Returns
///
/// Vector of messages
pub fn consume(&self, timeout: u64, max_messages: usize) -> Vec<Message> {
// Implementation
}
```
### Commit Messages
Follow conventional commits:
```
feat: add new feature
fix: fix bug
docs: update documentation
test: add tests
refactor: refactor code
perf: improve performance
chore: maintenance tasks
```
Example:
```
feat: add support for message filtering
- Add filter parameter to consume endpoint
- Implement regex-based filtering
- Add tests for filter functionality
```
### Pull Request Process
1. Fork repository
2. Create feature branch: `git checkout -b feature/my-feature`
3. Make changes
4. Run tests: `cargo test`
5. Format code: `cargo fmt`
6. Lint code: `cargo clippy`
7. Commit changes
8. Push to fork
9. Create pull request
## Release Process
### Version Update
Update version in `Cargo.toml`:
```toml
[package]
version = "0.2.0" # Increment version
```
### Changelog
Update CHANGELOG.md:
```markdown
## [0.2.0] - 2025-01-15
### Added
- New feature X
### Fixed
- Bug Y
### Changed
- Improved Z
```
### Tag Release
```bash
git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0
```
### Build Release Artifacts
```bash
cargo build --release
# Create archive
tar -czf v-queue-server-v0.2.0-linux-x86_64.tar.gz \
-C target/release v-queue-server
```
## Documentation
### Code Documentation
Generate docs:
```bash
cargo doc --open
```
Add documentation:
```rust
/// Brief description.
///
/// Detailed description with examples.
///
/// # Examples
///
/// ```
/// let queue = Queue::new("./data", "test", Mode::ReadWrite)?;
/// queue.push(b"message", MsgType::String)?;
/// ```
pub fn example() {
// Code
}
```
### User Documentation
Located in `doc/` directory:
- Write in Markdown
- Include code examples
- Add screenshots if applicable
- Cross-reference other docs
## Common Development Tasks
### Clean Build Artifacts
```bash
cargo clean
```
### Check Dependencies Tree
```bash
cargo tree
```
### View Binary Size
```bash
cargo bloat --release
```
### Expand Macros
```bash
cargo expand
```
### Check for Unused Dependencies
```bash
cargo install cargo-udeps
cargo +nightly udeps
```
## Troubleshooting Development Issues
### Compilation Errors
1. Clean and rebuild:
```bash
cargo clean
cargo build
```
2. Update dependencies:
```bash
cargo update
```
3. Check Rust version:
```bash
rustc --version
rustup update
```
### Test Failures
1. Run single test with output:
```bash
cargo test test_name -- --nocapture
```
2. Check for race conditions:
```bash
cargo test -- --test-threads=1
```
### IDE Issues
#### VS Code Setup
Install extensions:
- rust-analyzer
- CodeLLDB (debugging)
- Better TOML
`.vscode/settings.json`:
```json
{
"rust-analyzer.checkOnSave.command": "clippy"
}
```
#### IntelliJ IDEA Setup
Install Rust plugin from marketplace.
## Useful Resources
### Documentation
- [Rust Book](https://doc.rust-lang.org/book/)
- [Rust by Example](https://doc.rust-lang.org/rust-by-example/)
- [Axum Documentation](https://docs.rs/axum/)
- [Tokio Documentation](https://tokio.rs/)
### Tools
- [Clippy Lints](https://rust-lang.github.io/rust-clippy/)
- [Rustfmt Configuration](https://rust-lang.github.io/rustfmt/)
- [Cargo Book](https://doc.rust-lang.org/cargo/)
## Next Steps
- [Architecture Documentation](02-architecture.md)
- [API Reference](05-api-reference.md)
- [Testing Guide](../v-queue-server/tests/README.md)