initial commit

2025-12-26 18:42:04 +01:00
commit d8d9ddfc53
52 changed files with 16863 additions and 0 deletions
@@ -0,0 +1,122 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+nxdns is a DNS sinkhole written in Zig. It denies ads/trackers/malware by returning 0.0.0.0 for denied domains and forwards allowed queries to upstream DoH/DoT servers.
+
+## Build Commands
+
+```bash
+zig build              # Build the project
+zig build run          # Run nxdns
+zig build test         # Run all tests
+zig fmt src/           # Format code
+```
+
+Validate config without running:
+```bash
+NXDNS_CONFIG=./config.example.toml ./zig-out/bin/nxdns check
+```
+
+## Architecture
+
+```
+src/
+├── main.zig           # Entry point, CLI, server orchestration
+├── events.zig         # Event signaling (denylist reload via eventfd)
+├── util.zig           # Utility functions
+├── dns/               # DNS protocol (RFC 1035)
+│   ├── packet.zig     # Full packet parse/encode
+│   ├── header.zig     # 12-byte DNS header
+│   ├── name.zig       # Domain name with compression
+│   ├── question.zig   # Query section
+│   ├── record.zig     # Resource records (A, AAAA, CNAME, etc.)
+│   ├── edns.zig       # EDNS (OPT record) support
+│   └── types.zig      # Enums: QType, QClass, RCode
+├── server/
+│   ├── udp.zig        # UDP listener (port 53)
+│   ├── tcp.zig        # TCP listener (length-prefixed)
+│   ├── handler.zig    # Core logic: deny check → cache → upstream
+│   ├── shutdown.zig   # Graceful shutdown coordination
+│   └── rate_limiter.zig # Per-client rate limiting
+├── upstream/
+│   ├── doh.zig        # DNS-over-HTTPS client
+│   ├── dot.zig        # DNS-over-TLS client
+│   ├── pool.zig       # Failover across upstreams
+│   └── connection_pool.zig # Connection pooling
+├── filter/
+│   ├── denylist.zig   # HashMap with parent-walking lookup
+│   ├── fetcher.zig    # Download and parse denylist URLs
+│   └── safe_search.zig # Rewrite domains to force safe search
+├── cache/
+│   └── dns_cache.zig  # TTL-based response cache
+├── storage/
+│   ├── db.zig         # SQLite wrapper
+│   ├── schema.zig     # Tables and migrations
+│   └── logger.zig     # Async batched query logging
+├── config/
+│   ├── config.zig     # TOML config loading
+│   ├── toml.zig       # TOML parser
+│   └── watcher.zig    # inotify + signalfd for hot reload
+├── logging/
+│   └── logger.zig     # Structured logging
+└── web/
+    ├── server.zig     # HTTP server
+    ├── response.zig   # HTTP response helpers
+    ├── json.zig       # JSON serialization
+    ├── auth.zig       # Session-based authentication
+    └── api/           # REST API handlers
+        ├── stats.zig
+        ├── queries.zig
+        ├── clients.zig
+        ├── groups.zig
+        ├── denylists.zig
+        ├── rules.zig
+        └── settings.zig
+```
+
+## Key Data Flow
+
+1. Query arrives (UDP/TCP) → `handler.handle()`
+2. Check denylist (parent-walking: `ads.google.com` → `google.com` → `com`)
+3. If denied: return 0.0.0.0 response
+4. If allowed: check cache → query upstream (DoH/DoT) → cache response
+5. Log query to SQLite asynchronously
+
+## Code Patterns
+
+**Database transactions** - Use RAII pattern for safety:
+```zig
+var tx = try db.begin();
+defer tx.deinit();  // Auto-rollback if not committed
+// ... do work ...
+try tx.commit();
+```
+
+## Design Principles
+
+- **Lean**: No bloat, only what's needed
+- **Pragmatic**: Real-world patterns that work
+- **Simple**: Easy to understand and extend
+
+## Implementation Status
+
+See PLAN.md for the full spec. Current state:
+- ✅ DNS protocol parsing/encoding (with EDNS)
+- ✅ UDP/TCP servers
+- ✅ Denylist with parent-walking
+- ✅ DNS cache
+- ✅ DoH client
+- ✅ DoT client (with connection pooling)
+- ✅ Web UI with REST API
+- ✅ Config hot reload (inotify + signalfd)
+- ✅ Denylist fetching and auto-reload
+- ✅ Safe search enforcement
+- ✅ Log retention enforcement (startup + daily cleanup)
+- ✅ Integration tests
+
+## Reference
+
+Zig 0.15.2 stdlib source is at `.ignore/zig/` for API verification.