lazydns

Upstream mosdns — Feature Summary

This document summarizes the feature set and implementation notes of the upstream mosdns project (source: IrineSistiana/mosdns). It highlights core capabilities, transport features, plugins, operational behaviors, and recommended improvements that are relevant when maintaining parity or planning feature work in lazydns.

---

1. Core DNS functionality

• DNS message parsing and serialization (wire format).
• Support for common record types (A, AAAA, CNAME, MX, NS, PTR, SOA, TXT, SRV) and several less-common types (e.g. SVCB/HTTPS, CAA in type lists).
• Asynchronous, highly concurrent server model (uses goroutines in upstream; lazydns maps to tokio).

2. Transports & Servers

• UDP server (standard DNS over UDP).
• TCP server (DNS over TCP for large responses).
• DoH (DNS over HTTPS) — HTTP POST application/dns-message.
• DoT (DNS over TLS) — TLS-protected DNS (RFC 7858).
• DoQ (DNS over QUIC) — planned/experimental in upstream.
• Multi-listen, concurrent handling, and tunable timeouts and limits.

3. Plugins & Extensions (select)

The upstream project exposes a plugin architecture with numerous built-in plugins. Key executable and core plugins include:

• forward: Forward queries to upstream resolvers (supports DoH upstreams). Includes health checks, load-balancing strategies (round-robin, random, fastest), concurrent queries (race mode), failover, and per-upstream metrics.
• cache: Caching layer for query responses.
• hosts: Local hosts file parsing and matching (supports ip-first and hostname-first formats, multiple IP entries per line).
• ip_set / nftset: System integration plugins that export IPs to ipset or nft (CLI) on Linux; they compute prefixes and optionally aggregate CIDRs.
• ros_addrlist: RouterOS (MikroTik) integration for managing address-lists; supports dry-run and aggregation.
• reverse_lookup: Generates reverse PTR records and supports save hooks.
• rate_limiter: Per-client or global query limiting.
• ttl: TTL rewrite/clamping plugin (fixed TTL or min/max range).
• query_summary, metrics_collector: Observability and stats gathering components.
• control & flow: sequence/parallel/if/goto/return/drop_resp — plugins to build control-flow logic.
• executable helpers: arbitrary, sleep, debug_print, drop_resp, etc.

Note: Many plugins have a QuickSetup parsing style and both mnemonic and tag-based config options used by the plugin builder.

4. Data Providers & File-based Resources

• domain_set, ip_set, and hosts support a set of files or inline data.
• Optional auto_reload configuration: when enabled and files: [...] are provided, a FileWatcher monitors the underlying files and triggers rebuilds on changes.

5. FileWatcher / Auto-reload behavior

Key features and improvements in upstream:

• Centralized FileWatcher implementation that handles fsnotify events with debouncing and robust handling of REMOVE/RENAME/CREATE scenarios.
• Debounce to avoid duplicate reloads (default ~500ms).
• Re-add and retry logic for REMOVE/RENAME situations (exponential backoff retries) to handle atomic editor saves and rediscovery.
• Scheduled reload after CREATE to avoid missing atomic replace patterns (configurable short delay, default ~250ms).

6. Configuration & Environment Overrides

• Uses viper to load YAML configuration, with AutomaticEnv() enabled and a key replacer mapping . -> _. This allows environment-based overrides like:

  • PLUGINS_HOSTS_ARGS_AUTO_RELOAD
  • PLUGINS_ADD_GFWLIST_ARGS_PASSWD

• There is an applyPluginEnvOverrides helper that maps PLUGINS_<IDENT>_ARGS_<KEY> into plugin Args maps. It supports boolean / numeric parsing where appropriate.

7. Observability & Logging

• Metrics: Prometheus-style metrics and plugin-level counters (queries, successes, failures, response durations). Plugins optionally expose these metrics when health checks are enabled.
• Logging: time_format configurable in LogConfig with values like timestamp, iso8601, rfc3339, custom:<layout>.
• Tests and docs encourage using readable timestamps and consistent encoding for production vs development.

8. Security & Secrets

• Recommendations and docs for secret management (docs/SECURE_SECRETS.md) — Docker secrets, Kubernetes secrets, Vault, etc.
• Some plugins and helpers are designed to avoid leaking secrets to logs; the env override helper is conscious of secrets handling.

9. Testing & CI Practices

• Unit tests for FileWatcher, ros_addrlist synchronization logic, and time-format and logger behavior.
• Integration tests should avoid modifying repository example files; use outputDir or ./tmp/ for test outputs.
• CI should run go test ./... and ensure tests do not mutate tracked sample files.

10. Deployment & Operations

• Official Docker images are published; prebuilt binaries are available.
• Configurable CLI and flags for working directories and log levels.
• Router/OS integration (ros_addrlist) supports dry-run and multiple sync strategies (replace, append, diff-sync).

11. Known suggestions / proposed enhancements (from upstream notes)

• Add outputDir and dry_run to various writing functions for safer tests and more predictable behavior.
• Consider replacing CLI-based ipset / nft invocation with native netlink-based implementations for robustness.
• Continue hardening FileWatcher behavior for edge-case filesystems/editors and add tests for the edge cases.
• Improve plugin args decoding after env overrides (map → typed struct conversion) for better ergonomics.

---

Appendix: Where to look in upstream repo

• Core: coremain/, server/, pkg/, plugin/
• Docs & recommendations: docs/UPSTREAM_CHANGES.md, docs/SECURE_SECRETS.md, README.md
• Plugin implementations: plugin/executable/, plugin/data_provider/

---

(from reading upstream repository source and docs; useful as a checklist when porting features to lazydns.)

This site is open source. Improve this page.