Mohammadreza Khani
3a5c0d2aba
- Axum HTTP server with /dns-query endpoint (GET + POST per RFC 8484) - DNS wire-format parsing via hickory-proto - Upstream DoH client with round-robin selection - TOML config file with resolver definitions - SERVFAIL fallback when upstream is unreachable - /health endpoint - Unit tests (7) and integration tests (5) - Zero warnings, clippy clean, fmt clean
114 lines
3.5 KiB
Markdown
114 lines
3.5 KiB
Markdown
# DEVELOP.md — Development Rules & Tracking
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Prerequisites
|
|
rustup show # Rust 1.80+
|
|
cargo install cargo-watch
|
|
|
|
# Run locally
|
|
cargo run -- --config config/default.toml
|
|
|
|
# Run with auto-reload
|
|
cargo watch -x run
|
|
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Lint
|
|
cargo clippy -- -D warnings
|
|
cargo fmt --check
|
|
```
|
|
|
|
## Development Rules
|
|
|
|
### Code Quality
|
|
|
|
1. **No warnings.** All code must compile with zero warnings. CI treats warnings as errors (`-D warnings`).
|
|
2. **Format before commit.** Run `cargo fmt` — CI checks formatting.
|
|
3. **Clippy clean.** Run `cargo clippy -- -D warnings` — CI checks lints.
|
|
4. **Tests required.** Every new module/function must have unit tests. Public API changes require integration tests.
|
|
5. **Doc comments.** All public items (`pub fn`, `pub struct`, `pub enum`) must have `///` doc comments.
|
|
|
|
### Git Workflow
|
|
|
|
1. **Branch naming**: `<type>/<short-description>`
|
|
- `feat/dns-cache`, `fix/ttl-overflow`, `docs/readme`, `chore/ci-update`
|
|
2. **Commit messages**: Conventional Commits format
|
|
- `feat: add DNS response cache`
|
|
- `fix: handle truncated UDP responses`
|
|
- `docs: update plan.md`
|
|
3. **PR required.** All changes go through a pull request. No direct pushes to `main`.
|
|
4. **Squash merge.** PRs are squash-merged into `main`.
|
|
5. **CI must pass.** Lint, test, and build must succeed before merge.
|
|
|
|
### Architecture Rules
|
|
|
|
1. **No panics in production code.** Use `Result<T, E>` everywhere. `unwrap()` only in tests.
|
|
2. **Structured errors.** Define error types per module using `thiserror`. Use `anyhow` only in `main.rs`.
|
|
3. **Async everywhere.** All I/O is async (Tokio). No blocking calls in async context.
|
|
4. **Config-driven.** No hardcoded values. All tunables come from config file or env vars.
|
|
5. **Dependency injection.** Accept traits, not concrete types. Makes testing easy.
|
|
|
|
### Testing Rules
|
|
|
|
1. **Unit tests** in the same file (`#[cfg(test)] mod tests { ... }`).
|
|
2. **Integration tests** in `tests/` directory.
|
|
3. **Test naming**: `test_<what>_<condition>_<expected>` — e.g., `test_cache_expired_entry_returns_miss`.
|
|
4. **No external dependencies in unit tests.** Mock upstream resolvers.
|
|
5. **Integration tests** may spin up the full server on a random port.
|
|
|
|
### Security Rules
|
|
|
|
1. **No secrets in code.** Use env vars or config files (gitignored).
|
|
2. **Validate all input.** DNS queries from the network are untrusted — validate lengths, offsets, labels.
|
|
3. **Timeouts on all upstream calls.** Never hang indefinitely.
|
|
4. **Rate limiting.** Protect against abuse from a single IP.
|
|
5. **Dependency audit.** Run `cargo audit` in CI.
|
|
|
|
### Commit Checklist
|
|
|
|
Before pushing, verify:
|
|
|
|
- [ ] `cargo fmt --check` passes
|
|
- [ ] `cargo clippy -- -D warnings` passes
|
|
- [ ] `cargo test` passes
|
|
- [ ] New code has tests
|
|
- [ ] Public items have doc comments
|
|
- [ ] No `unwrap()` outside of tests
|
|
- [ ] Config values are externalized (not hardcoded)
|
|
|
|
## Milestone Tracking
|
|
|
|
See [docs/plan.md](docs/plan.md) for the full project plan and milestone checklist.
|
|
|
|
| Milestone | Status |
|
|
|-----------|--------|
|
|
| M1 — Core Forwarding | ✅ Done |
|
|
| M2 — Multiple Upstreams & Config | 🔲 Not started |
|
|
| M3 — Caching | 🔲 Not started |
|
|
| M4 — Observability | 🔲 Not started |
|
|
| M5 — Blocking & Filtering | 🔲 Not started |
|
|
| M6 — Production Hardening | 🔲 Not started |
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
# Build release binary
|
|
cargo build --release
|
|
|
|
# Run with specific log level
|
|
RUST_LOG=debug cargo run
|
|
|
|
# Generate and open docs
|
|
cargo doc --open
|
|
|
|
# Dependency audit
|
|
cargo install cargo-audit
|
|
cargo audit
|
|
|
|
# Watch tests
|
|
cargo watch -x test
|
|
```
|