docs: add project plan and development rules

- docs/plan.md: project overview, architecture, milestones, directory structure - DEVELOP.md: dev rules, code quality standards, git workflow, testing rules, milestone tracking
2026-07-06 16:00:48 +03:30
commit b11d042732
2 changed files with 231 additions and 0 deletions
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -0,0 +1,118 @@
+# DoH Forwarder — Project Plan
+
+## Overview
+
+A lightweight DNS-over-HTTPS (DoH) forwarder that accepts DNS queries over HTTPS (RFC 8484) and forwards them to upstream DoH resolvers, with caching, logging, and optional blocking.
+
+## Goals
+
+- Accept DoH queries (GET and POST per RFC 8484)
+- Forward to configurable upstream DoH resolvers (Cloudflare, Google, Quad9, custom)
+- In-memory DNS response cache with configurable TTL
+- Query logging (stdout/file)
+- Optional domain blocklist (ad-blocking / parental control)
+- Health-check endpoint
+- Low resource footprint, single binary
+
+## Architecture
+
+```
+┌─────────────┐      ┌──────────────────┐      ┌─────────────────┐
+│  DNS Client  │─────▶│  DoH Forwarder   │─────▶│  Upstream DoH   │
+│  (browser,   │ HTTPS│  (this project)  │ HTTPS│  (1.1.1.1,      │
+│   OS, app)   │◀─────│                  │◀─────│   8.8.8.8, …)   │
+└─────────────┘      └──────────────────┘      └─────────────────┘
+```
+
+## Tech Stack
+
+- **Language**: Rust
+- **HTTP server**: Axum
+- **DNS wire-format**: hickory-proto (formerly trust-dns-proto)
+- **Async runtime**: Tokio
+- **Config**: TOML (config file) + env vars
+- **Logging**: tracing + tracing-subscriber
+
+## Milestones
+
+### M1 — Core Forwarding
+
+- [ ] Project scaffold (Cargo workspace, CI)
+- [ ] HTTP server with `/dns-query` endpoint (GET + POST)
+- [ ] Parse incoming DNS wire-format queries
+- [ ] Forward to a single upstream DoH resolver
+- [ ] Return DNS wire-format response
+- [ ] Basic integration test
+
+### M2 — Multiple Upstreams & Config
+
+- [ ] TOML config file support
+- [ ] Multiple upstream resolver support
+- [ ] Upstream selection strategy (round-robin / failover)
+- [ ] Environment variable overrides
+- [ ] Graceful shutdown
+
+### M3 — Caching
+
+- [ ] In-memory DNS response cache
+- [ ] Cache key = (query name, query type)
+- [ ] Respect DNS response TTL (with configurable max)
+- [ ] Cache eviction (TTL-based + LRU size cap)
+- [ ] Cache stats endpoint (`/cache/stats`)
+
+### M4 — Observability
+
+- [ ] Structured logging (tracing)
+- [ ] Request logging middleware (query name, type, latency, upstream used)
+- [ ] Health endpoint (`/health`)
+- [ ] Metrics endpoint (optional, Prometheus format)
+
+### M5 — Blocking & Filtering
+
+- [ ] Domain blocklist (file-based, one domain per line)
+- [ ] Wildcard / suffix matching
+- [ ] Return NXDOMAIN for blocked queries
+- [ ] Hot-reload blocklist on SIGHUP
+
+### M6 — Production Hardening
+
+- [ ] Rate limiting (per-IP)
+- [ ] Request timeout for upstream queries
+- [ ] Dockerfile (multi-stage, distroless)
+- [ ] Helm chart
+- [ ] CI pipeline (lint, test, build, image push)
+
+## Directory Structure (target)
+
+```
+doh-forwarder/
+├── Cargo.toml
+├── src/
+│   ├── main.rs            # entrypoint, server setup
+│   ├── config.rs          # config parsing
+│   ├── dns/
+│   │   ├── mod.rs
+│   │   ├── query.rs       # parse incoming DNS queries
+│   │   └── response.rs    # build/parse DNS responses
+│   ├── upstream/
+│   │   ├── mod.rs
+│   │   └── doh_client.rs  # DoH forwarding client
+│   ├── cache.rs           # DNS cache
+│   ├── blocklist.rs       # domain blocking
+│   ├── routes.rs          # HTTP route handlers
+│   └── middleware.rs       # logging, rate-limit
+├── config/
+│   └── default.toml
+├── docs/
+│   └── plan.md
+├── DEVELOP.md
+└── tests/
+    └── integration.rs
+```
+
+## Non-Goals (for now)
+
+- DNS-over-TLS (DoT) listener
+- DNSSEC validation
+- Persistent cache (Redis / disk)
+- Web UI / dashboard