docs: sync docs with current code and trim crates.io package

Author: lazywalker

Cargo.toml

@@ -12,6 +12,21 @@ license = "GPL-3.0-or-later"
 readme = "README.md"
 keywords = ["dns", "smartdns", "doh", "dot", "doq"]
 categories = ["network-programming"]
+exclude = [
+    ".github/",
+    ".dockerignore",
+    ".gitignore",
+    "Makefile",
+    "benches/",
+    "config.yaml",
+    "docker/",
+    "docs/",
+    "etc/",
+    "examples/",
+    "scripts/",
+    "tests/",
+    "webui/",
+]
 
 [dependencies]
 tokio = { version = "1.49", default-features = false, features = [

README.md

@@ -17,7 +17,6 @@
 - **[Docs Home](docs/README.md)** - Main documentation index
 - **[Installation Guide](docs/en/03_INSTALLATION.md)** - Installation methods
 - **[Configuration Guide](docs/en/04_CONFIGURATION.md)** - Configuration file reference
-- **[Implementation](docs/IMPLEMENTATION.md)** - Phased implementation roadmap
 
 ## Current Status:
 

build.rs

@@ -8,6 +8,9 @@ fn main() {
     if Path::new("webui/dist").exists() {
         println!("cargo:rustc-cfg=webui_dist");
     } else {
-        println!("cargo:warning=webui/dist not found; building without embedded webui assets");
+        println!(
+            "cargo:warning=webui/dist not found, web-embed feature will have no embedded assets. \
+             Run `cd webui && npm run build` first."
+        );
     }
 }

docs/IMPLEMENTATION.md

@@ -1,107 +1,148 @@
 # Implementation status vs upstream mosdns
 
-This document summarizes the current implementation status of the Rust `lazydns` project against the upstream `mosdns` feature list (see `upstream-features.md`). It lists implemented features, partial implementations, and known gaps. Paths reference current source files where applicable.
+Compares lazydns (Rust) against the upstream mosdns feature list (see `UPSTREAM_FEATURES.md`).
 
 ## Summary
 
-- Overall status: large portion of core features and many plugins implemented in Rust with the goal of parity.
-- Focus so far: plugin architecture, forward/cache/hosts, control-flow plugins, and executable plugins including `reverse_lookup`, `ipset`, and `nftset`.
+Core DNS functionality, plugin system, all five transports, cache with persistence and lazy refresh, and a WebUI dashboard are implemented. Gaps are in native netlink integration and some upstream plugin parity.
 
-## 1. Core DNS functionality
+## 1. Core DNS
 
-- DNS parsing & serialization: Implemented. See `src/dns/*` (message, wire, record, rdata, types).
-- Supported record types: implemented for the common set (A, AAAA, CNAME, MX, NS, PTR, SOA, TXT, SRV). SVCB/HTTPS and CAA are present in `RecordType` definitions (`src/dns/types.rs`).
+Wire-format parse/serialize is built on `hickory-proto` 0.24. See `src/dns/`:
 
-Status: IMPLEMENTED (core parsing and record support).
+- `message.rs` - DNS message (header + 4 sections); `records()` / `records_mut()` iterate all RRs; DNSSEC bits (AD, CD)
+- `question.rs` - Question struct (qname, qtype, qclass)
+- `record.rs` - ResourceRecord (name, type, class, ttl, rdata)
+- `rdata.rs` - RData enum (A, AAAA, CNAME, NS, PTR, MX, TXT, SOA, SRV, OPT, CAA, DS, RRSIG, NSEC, DNSKEY, etc.)
+- `types.rs` - RecordType, RecordClass, OpCode, ResponseCode
+- `wire.rs` - parse_message / serialize_message
 
-## 2. Transport & server features
+Record types: A, AAAA, CNAME, MX, NS, PTR, SOA, TXT, SRV fully supported. OPT (EDNS0), DS, RRSIG, NSEC, DNSKEY, SVCB, HTTPS, CAA defined in the enum.
 
-- UDP and TCP servers: Implemented (`src/server/udp.rs`, `src/server/tcp.rs`).
-- DoT (DNS over TLS): Implemented (`src/server/dot.rs`, `src/server/tls.rs`).
-- DoH (DNS over HTTPS): Implemented (`src/server/doh.rs`).
-- DoQ (DNS over QUIC): implemented (`src/server/doq.rs`).
-- Multi-listen, concurrency, connection handling: Implemented via `tokio`-based servers (`src/server/*`).
+Status: IMPLEMENTED.
 
-Status: PARTIAL: UDP/TCP/DoH/DoT/DoQ present, not all features.
+## 2. Transports and servers
+
+All five transports via the `Server` trait (`src/server/mod.rs`):
+
+| Transport | File | Feature |
+|-----------|------|---------|
+| UDP | `udp.rs` | always |
+| TCP | `tcp.rs` | always |
+| DoT | `dot.rs` | `dot` |
+| DoH | `doh.rs` | `doh` |
+| DoQ | `doq.rs` | `doq` |
+| Admin API | `admin.rs` | `admin` |
+| Monitoring | `monitoring.rs` | `metrics` |
+
+`ServerLauncher` (`launcher.rs`) spawns servers from plugin config. A shared `spawn_server` helper handles the oneshot + spawn + error-log pattern for all transport types.
+
+`RequestHandler` trait and `DefaultHandler` (`handler.rs`) wire requests to the plugin entry point, with `RequestContext` carrying client IP and protocol.
+
+Status: IMPLEMENTED.
 
 ## 3. Plugin system
 
-- Plugin architecture: Implemented (`src/plugin/*`, `src/plugins/mod.rs`).
-- Execution flow, context, and conditional execution: Implemented (`src/plugin/context.rs`, `src/plugins/advanced.rs`, `src/plugin/builder.rs`).
+Core traits in `src/plugin/`:
+
+- `traits.rs` - `Plugin` (execute, init, aliases, as_any, as_shutdown, spawn_background_task), `ExecPlugin` (quick_setup), `Shutdown`, `BackgroundTask`, `Matcher`
+- `context.rs` - `Context` holds request/response Messages and typed metadata; `set_refused()` builds a REFUSED response echoing the request
+- `builder.rs` - `PluginBuilder` resolves `$tag` references and builds plugin instances from `PluginConfig`
+- `factory.rs` - auto-registration via `#[derive(RegisterPlugin)]` + `linkme::distributed_slice`
+- `registry.rs` - runtime lookup by name/tag
+- `condition/` - condition builders (qname, qname_neg, qtype, qclass, rcode, has_cname, has_resp, resp_ip, resp_ip_neg)
+
+`PluginHandler` (`mod.rs`) runs the entry plugin, handles control-flow metadata (`goto_label`, `jump_target`, `RETURN_FLAG`), and does post-processing: cache store, reverse-lookup IP save, and audit query logging.
+
+Status: IMPLEMENTED.
+
+## 4. Plugins
+
+### Server-facing
+
+| Plugin | Path | Notes |
+|--------|------|-------|
+| `forward` | `forward/{mod,engine,builder,types}.rs` | UDP multiplexing (qid demux), DoH (reqwest), concurrent racing, health tracking, load balancing (round-robin/random/fastest) |
+| `cache` | `cache/{mod,entry,persistence,stats}.rs` | LRU + LazyCache (pre-expiry background refresh) + stale-serving + binary persistence (`dump_file`/`dump_interval`); cache key includes DNSSEC flags (DO/AD/CD) |
+| `hosts` | `dataset/hosts.rs` | HashMap O(1), multiple IPs/domain, file-watch auto-reload |
+| `acl` | `acl.rs` | IP-based allow/deny |
+| `geoip` | `geoip.rs` | Country-code matching |
+| `geosite` | `geosite.rs` | Category/domain matching |
+| `domain_validator` | `domain_validator.rs` | RFC 1035/1123 name validation, rejects malformed queries early |
+| `rate_limit` | `executable/ratelimit.rs` | Per-IP token-bucket / window limiting |
+| `redirect` | `executable/redirect.rs` | Query name rewriting (wildcard, multi-rule, first-match-wins) |
+| `ecs` | `executable/ecs.rs` | EDNS Client Subnet |
+| `cron` | `cron.rs` | Scheduled tasks (`cronexpr`); drives downloader |
+
+### Executable (inline `exec:` in sequences)
+
+`ttl`, `black_hole`, `arbitrary`, `query_summary`, `debug_print`, `drop_resp`, `sleep`, `dual_selector`, `edns0opt`, `mark`, `reverse_lookup`, `downloader`, `collector` (Prometheus variant under `metrics` feature).
+
+All in `src/plugins/executable/`.
+
+### Datasets
+
+`domain_set` (full/domain/regexp/keyword match types), `ip_set` (CIDR), `arbitrary`. All in `src/plugins/dataset/`.
 
-### Core plugin coverage (select)
+### Flow control
 
-- `forward`: Implemented (`src/plugins/forward.rs`); supports multiple upstreams and concurrent queries. Transport feature parity (DoH/DoT/DoQ upstream) is partial on transport side.
-- `cache`: Implemented (`src/plugins/cache/mod.rs`). - TODO: `lazy_cache_ttl`
-- `hosts`: Implemented (`src/plugins/hosts.rs`). Parser supports both ip-first and hostname-first lines, multiple IPs per line, and mixed ordering across files; unit tests verify A/AAAA behavior and hostname-first parsing.
-- `domain_set` / `geosite`: Implemented (`src/plugins/domain_matcher.rs`, `src/plugins/geosite.rs`).
-- `ip_set` / IP matching: Implemented (`src/plugins/ip_matcher.rs`, `src/plugins/data_provider.rs`).
-- `geoip`: Implemented (`src/plugins/geoip.rs`); GeoIP integration present; check for data loader details.
+`sequence`, `goto`, `jump`, `accept`, `reject`, `return`, `prefer_ipv4`, `prefer_ipv6`. In `src/plugins/executable/sequence.rs` and `src/plugins/flow/`.
 
-### Executable & control plugins
+### Linux integration
 
-- `sequence`, `parallel`, `if`, `goto`, `return`, `drop_resp`: Implemented (`src/plugins/advanced.rs`, `src/plugins/control_flow.rs`).
-- `ttl`: Implemented (`src/plugins/executable/ttl.rs`).
-- `query_summary`: Implemented (`src/plugins/executable/query_summary.rs`).
-- `reverse_lookup`: Implemented with in-memory cache and save hook (`src/plugins/executable/reverse_lookup.rs`). Integration: `PluginHandler` calls `save_ips_after` after response population.
-- `arbitrary`, `black_hole`, `drop_resp`: Implemented in `src/plugins/executable/*.rs`.
+`ipset` (`executable/ipset.rs`) and `nftset` (`executable/nftset.rs`) compute CIDR prefixes from A/AAAA answers and invoke `ipset` / `nft` binaries on Linux; record metadata on other platforms.
 
-### ipset / nftset integration
+Status: IMPLEMENTED (CLI-based, not native netlink).
 
-- `ipset`: Implemented (`src/plugins/executable/ipset.rs`). Behavior:
+## 5. Cache subsystem
 
-  - Computes CIDR prefixes from A/AAAA answers.
-  - QuickSetup parser present.
-  - On Linux, invokes system `ipset` binary via `std::process::Command` (guarded with `cfg(target_os = "linux")`).
-  - On other platforms records metadata (`ipset_added`) for tests/visibility.
+- LRU eviction with periodic cleanup (60s interval, 0.8 pressure threshold)
+- LazyCache: proactively refreshes entries when remaining TTL drops below 5%
+- Stale-serving via `cache_ttl`: serves stale at TTL=0 while refreshing
+- Negative caching with configurable `negative_ttl`
+- Persistence: binary dump (`LZDNSCv1` format, atomic temp+rename) to `dump_file` every N changes; loaded on startup and on shutdown
 
-- `nftset`: Implemented (`src/plugins/executable/nftset.rs`). Behavior mirrors `ipset`:
-  - Computes prefixes, QuickSetup parser.
-  - On Linux uses `nft` binary; otherwise records metadata (`nftset_added_v4`, `nftset_added_v6`).
+Status: IMPLEMENTED.
 
-Status: IMPLEMENTED (CLI-based integration). Note: upstream native netlink integration is not used; a native implementation could be added later.
+## 6. Audit and WebUI
 
-## 4. Configuration system
+Audit is part of the `web` feature (no standalone plugin). When enabled:
 
-- YAML config loader and validation: Implemented (`src/config/*`) with `PluginBuilder` and `PluginConfig` parsing. Example configs included in `examples/etc/config.yaml`.
-- Hot reload: partial; `ConfigReloader` exists, verify runtime hot-reload semantics for production.
+- `PluginHandler` auto-logs every query via `log_query_for_context`
+- Plugins emit security events (ACL deny, rate-limit, malformed query) via `AUDIT_LOGGER`
+- Event bus (`audit/event_bus.rs`) fans out to SSE stream and alert engine
+- WebUI (`src/web/`): real-time dashboard, audit SSE stream, config viewer, admin ops, WebSocket metrics
 
-Status: PARTIAL: YAML loading and validation implemented; hot-reload present as a reloader component.
+Status: IMPLEMENTED (feature `web`).
 
-## 5. Advanced features
+## 7. Metrics
 
-- Performance: designed for async `tokio` concurrency; memory pools and advanced tuning are incremental work (some pool utilities exist in project).
-- Observability: metrics and monitoring modules exist (`src/server/monitoring.rs`, `src/metrics` planned). Prometheus-style exposure may be partial.
-- Security: TLS support for DoT/DoH implemented. Certificate handling present in `src/server/tls.rs`.
+Prometheus gauges/counters in `src/metrics/mod.rs` (cache hits/misses, DNS queries, upstream stats, domain validation). Process memory metrics (RSS/VMS/cgroup) in `src/metrics/memory/`. Exposed via monitoring server (feature `metrics`).
 
-Status: PARTIAL: basic observability and TLS present; more integrations possible.
+Status: IMPLEMENTED.
 
-## 6. Deployment & management
+## 8. Configuration
 
-- Standalone binary and Docker artifacts: project includes `Dockerfile` and `docker-compose.yml` in workspace root.
-- CLI flags and signal handling: implemented in `src/main.rs` (config path, working dir, log level, graceful shutdown via ctrl-c).
+YAML config with serde, env var substitution, `!include`, and hot-reload via file watcher (`config/reload.rs`). Validation in `config/validation.rs` checks ranges and required keys for known plugins. Plugin args are free-form YAML parsed by each plugin's `init()`.
 
-Status: IMPLEMENTED (basic deployment support present).
+Feature flags (`Cargo.toml`): `cron`, `log`, `log-ansi`, `log-file`, `dot`, `doh`, `doq`, `admin`, `metrics`, `web`, `web-embed`. The `full` feature enables everything except `web-embed`.
 
-## 7. Testing coverage
+Status: IMPLEMENTED.
 
-- Unit tests: extensive unit tests across DNS, plugin, and executable modules (run via `cargo test`).
-- Integration tests: added integration tests for the reverse-lookup save hook and ipset/nftset metadata behavior under `tests/`.
+## 9. Testing
 
-Status: IMPLEMENTED: good test coverage; integration tests added for key behaviors.
+Unit tests across all modules (950+ tests). Integration tests in `tests/`:
 
-## Gaps and recommended next steps
+- `integration_cache.rs`, `integration_ratelimit.rs`, `integration_doq.rs`
+- `integration_ipset_nftset.rs`, `integration_save_hook.rs`
+- `integration_tls_doh_dot.rs`, `integration_test.rs` (wire format)
+- `server_test.rs` (real UDP queries), `web_api_test.rs`
 
-1. DoQ (DNS over QUIC): implement DoQ server and transport support to match upstream feature set.
-2. Replace CLI-based ipset/nft manipulation with native netlink integration (via a Rust netlink crate) for more robust system integration and error handling.
-3. Expand documentation per-plugin (config examples and QuickSetup documentation) and add README snippets linking `examples/etc/config.yaml` to plugin behaviors.
-4. Add further integration tests for multi-plugin sequences (such as forward->ipset->ros_addrlist flow) and permissioned system behaviors.
-5. Verify Prometheus metrics coverage and add exporter where missing.
+Status: IMPLEMENTED.
 
-## File references (key files)
+## Gaps and next steps
 
-- Core DNS: `src/dns/*` (types.rs, message.rs, record.rs, wire.rs)
-- Server: `src/server/*` (`udp.rs`, `tcp.rs`, `doh.rs`, `dot.rs`)
-- Plugin system: `src/plugin/*`, `src/plugins/*`
-- Executable plugins: `src/plugins/executable/*` (includes `ipset.rs`, `nftset.rs`, `reverse_lookup.rs`, `ttl.rs`, `query_summary.rs`)
-- Config and examples: `src/config/*`, `examples/etc/config.yaml`
+1. Replace CLI-based ipset/nftset with native netlink integration.
+2. Add more per-plugin validation coverage (only 5 plugin types validated today).
+3. Expand integration tests for multi-plugin sequences.
+4. DoH/DoT upstream transport in forward (currently UDP + DoH upstream only).

docs/README.md

@@ -60,7 +60,7 @@ Use the site sidebar (`en/SUMMARY.md`) or the quick links below to jump to commo
     - [Reject](en/05_09_04_PLUGIN_REJECT.md)
     - [Return](en/05_09_05_PLUGIN_RETURN.md)
     - [Prefer_IPv4](en/05_09_06_PLUGIN_PREFER_IPV4.md)
-    - [Prefer_IPv6](05_09_07_PLUGIN_PREFER_IPV6.md)
+    - [Prefer_IPv6](en/05_09_07_PLUGIN_PREFER_IPV6.md)
 * [Writing Plugins (Developer)](en/06_WRITING_PLUGINS.md)
 * [Datasets & Formats](en/07_DATASETS.md)
 * [Changelog](en/16_CHANGELOG.md)

docs/en/03_INSTALLATION.md

@@ -10,26 +10,20 @@ Installs the latest published crate to your Cargo bin directory:
 cargo install lazydns
 ```
 
-### 2.1 Debian / Ubuntu (.deb via APT repo)
-Add the repository key and source, then install with `apt`:
-```bash
-sudo curl -fsSL https://raw.githubusercontent.com/lazywalker/apt/refs/heads/master/debian/key.asc -o /etc/apt/trusted.gpg.d/lazywalker.asc
-
-echo "deb https://raw.githubusercontent.com/lazywalker/apt/refs/heads/master/debian/ stable main" | sudo tee /etc/apt/sources.list.d/lazywalker.list
+> **Note on the WebUI**: `cargo install` builds the server core only. For a binary with the WebUI bundled in, use the pre-built release binaries.
 
-sudo apt update
-sudo apt install lazydns
+### 2.1 Debian / Ubuntu (amd64)
+Download the `.deb` from [GitHub Releases](https://github.com/lazywalker/lazydns/releases) and install with `dpkg`:
+```bash
+curl -LO https://github.com/lazywalker/lazydns/releases/latest/download/lazydns_<version>-1_amd64.deb
+sudo dpkg -i lazydns_<version>-1_amd64.deb
 ```
 
-### 2.2 Raspberry Pi OS (Trixie, arm64)
-Use the same repo but restrict to `arm64` architecture in the sources.list entry:
+### 2.2 Raspberry Pi OS / arm64
+Download the `arm64` `.deb` and install with `dpkg`:
 ```bash
-sudo curl -fsSL https://raw.githubusercontent.com/lazywalker/apt/refs/heads/master/debian/key.asc -o /etc/apt/trusted.gpg.d/lazywalker.asc
-
-echo "deb [arch=arm64] https://raw.githubusercontent.com/lazywalker/apt/refs/heads/master/debian/ stable main" | sudo tee /etc/apt/sources.list.d/lazywalker.list
-
-sudo apt update
-sudo apt install lazydns
+curl -LO https://github.com/lazywalker/lazydns/releases/latest/download/lazydns_<version>-1_arm64.deb
+sudo dpkg -i lazydns_<version>-1_arm64.deb
 ```
 
 ### 2.3 Install on Arch Linux
@@ -38,7 +32,7 @@ You can install lazydns from the Arch User Repository (AUR) using an AUR helper
 yay -S lazydns-bin
 ```
 
-### 3. Systemd Service Setup (via apt & systemd Linux)
+### 3. Systemd Service Setup (Debian / Ubuntu / Raspberry Pi OS)
 after installation, modify the config file at `/etc/lazydns/lazydns.yaml` as needed, then start the service:
 ```bash
 sudo systemctl start lazydns
@@ -79,7 +73,7 @@ docker run -d \
 
 ## Upgrading
 - From `cargo install`: `cargo install --force lazydns`
-- From APT: `sudo apt update && sudo apt upgrade` (package upgrades coming from the repo)
+- From `.deb`: download the new `.deb` and run `sudo dpkg -i` again
 - From Docker: pull the new image and recreate the container:
 ```bash
 docker pull lazywalker/lazydns:latest

docs/en/04_CONFIGURATION.md

@@ -91,7 +91,7 @@ Example:
     - `exec`: a plugin tag or quick-setup (such as `accept`, `drop_resp`)
     - `matches`: a condition (such as `qname $domain_list`, `has_resp`, `qtype 1`)
     - `jump`: jump to another sequence tag
-  - `fallback` plugin accepts `primary`, `secondary`, `threshold`, `always_standby`.
+  - `fallback` plugin accepts `primary` and `secondary`.
 
 - Server plugins (udp_server, tcp_server, doh_server, dot_server, doq_server)
   - `entry`: the sequence tag to use as the processing entry point