DDNS/docs/en/dev/rust.md

Rust V5 client development

ddns-rs is the Rust implementation for DDNS V5, integrated on the v5 branch. Python maintenance continues on master / v4; Rust feature PRs should target v5. The current development version is 5.0.0-alpha1. It supports one-shot updates and Web/MCP services, is not published, and does not replace the stable Python ddns command or default installer.

Current support

Capability	Status
All Python DNS providers and documented compatibility aliases (Cloudflare, AliDNS/ESA, DNSPod, EdgeOne, ClouDNS, DNS.COM, HE.net, Huawei DNS, NameSilo, No-IP, Callback, West.cn, and Debug)	Supported
IPv4/IPv6 and every existing address rule type	Supported; regex: uses Rust syntax
CLI, DDNS_*, local/remote/multiple configs, v4.1 providers	Supported
JSON comments and restricted Python data literals	Supported
Cache, proxy fallback, retries, TLS, and custom CA files	Supported
Linux amd64/arm64 Docker image	Build and offline smoke coverage; preparation saves an OCI artifact without registry publication; web provides in-process scheduling
Linux x64/arm64, macOS x64/arm64, Windows x64 binaries	Preparation saves ddns-rs-* and .sha256 Actions artifacts; Linux uses static musl targets
Web dashboard, configuration management, and in-process scheduling	Supported; one local config, interval 1..1440 minutes
MCP stdio, standalone HTTP, and Web /mcp	Supported; modern protocol and legacy stdio compatibility
task and OS task detection/takeover	Not ported; manually disable old Python/host tasks

V5 branch and release preparation

Keep the rust/ layout, ddns-rs command, and existing configuration boundaries; do not remove Python yet. The versions in rust/Cargo.toml and rust/Cargo.lock must match. Changes to the version files, preparation workflow, embedded Web assets/field model, or Rust Dockerfile on v5 automatically run Prepare Rust V5 without requiring a tag. It also accepts manual preparation on v5 or canonical v5.* tags matching Cargo, then produces verified native and two-platform OCI artifacts. It does not create Releases, upload release assets, or push images. Preparation accepts only V5 prereleases with an alpha, beta, or rc suffix, not stable versions. V5 documentation builds do not deploy over the stable site. The Python publisher retained on this branch rejects v5.* inputs; stable-branch publishing configuration is unchanged.

There is no installable V5 release yet; use source or CI artifacts. Before the first public V5 tag, isolate Python/Rust version selection in installers and the download service, and separately confirm the Rust publication workflow. Do not use repository-wide latest / beta downloads as V5 install channels yet.

Build and run

Use the current stable Rust toolchain:

cargo build --manifest-path rust/Cargo.toml --release --locked
rust/target/release/ddns-rs --help
rust/target/release/ddns-rs -c config.json

The Windows artifact is rust\target\release\ddns-rs.exe.

The experimental install-rust.sh runs --version on the temporary binary before moving it into place. An artifact that cannot run leaves the existing ddns-rs untouched, even with --force.

Web and MCP

ddns-rs web -c config.json --host 127.0.0.1 --port 8000 --interval 5 --open
ddns-rs mcp -c config.json
ddns-rs mcp -c config.json --transport http --host 127.0.0.1 --port 8001

web accepts -c FILE, --host HOST, --port PORT, --http-token TOKEN, repeatable --http-origin ORIGIN, --interval MINUTES, and --open (open the browser). Without an explicit subcommand, top-level --interval or a root configuration interval selects Web mode. The in-process scheduler accepts 1..1440 minutes and runs only while the process is alive.

The dashboard reads, validates, and saves the full configuration, manages backups/restores, reports status, and triggers synchronization. Web and MCP use the same service. They require a single local configuration file, not remote or multiple configuration sources. Web validation uses the compatible Rust runtime; it does not promise full Python runtime parity.

mcp defaults to newline-delimited stdio. --transport http serves standalone Streamable HTTP at /mcp; Web exposes the same endpoint on its own listener. Modern MCP uses protocol 2026-07-28; legacy 2025-11-25 is supported over stdio only. Both expose the Python tool names get_ddns_status and update_dns_records.

HTTP listeners default to loopback. A non-loopback bind requires --http-token TOKEN; clients authenticate with Authorization: Bearer TOKEN. Use repeated --http-origin ORIGIN flags for additional allowed browser origins. Origin checks and authentication apply to both Web and MCP HTTP. Do not expose plain HTTP on an untrusted network; use a trusted TLS reverse proxy or tunnel. Status responses exclude credentials, but the authenticated configuration API intentionally returns the full configuration, including provider credentials. Treat listener tokens, configuration files, and backups as secrets. With no listener token on loopback, local access is still a trust boundary. The listener token grants sensitive configuration access and DNS update authority, not read-only monitoring. Web updates execute cmd:/shell: rules from the authenticated local configuration with the process user's permissions; grant access only to trusted administrators.

The binary embeds the existing web/ dashboard assets and ddns/config/field-model.json at compile time; no frontend server or Python runtime is needed to serve them. Rebuild after changing these inputs. Source builds require the repository layout, not an isolated copy of rust/.

Migration limitation: task, OS scheduler detection, and automatic takeover are not implemented. Manually disable old Python/host systemd, cron, launchd, or schtasks jobs before enabling Rust scheduled updates to avoid duplicate runs. The Web scheduler does not install or replace a host service. Existing Rust regex: and separate-cache limits still apply. log_format and log_datefmt are accepted for configuration compatibility, not Python formatting parity.

Architecture

• cli.rs: compatible options, aliases, and list rules without a CLI framework.
• config/: environment, JSONC, restricted Python literals, v4.1 expansion, and precedence.
• http.rs: synchronous ureq/rustls transport, proxies, retries, TLS, and redaction.
• ip.rs: IPv4/IPv6 discovery and rule fallback.
• cache.rs: a versioned cache independent from the Python cache.
• provider/: shared CRUD orchestration and all DNS providers.
• update.rs: deterministic execution with continued attempts and aggregated failures.

Compatibility handling stays at the CLI and configuration boundary. Inside the core, providers use the ProviderId enum and aliases are parsed once. Providers use trait objects only for runtime dispatch and borrow the synchronous HTTP client; each update request borrows its domain, address, and provider extras instead of copying the full configuration per domain. Provider-specific extra values remain dynamic JSON because their fields are defined by each DNS API. The configuration layer rejects only empty domain entries, allowing debug and callback to use single labels such as localhost. Provider-specific domain constraints are handled by each provider. Integer log levels support both --log-level -5 and --log-level=-5.

Cloudflare and Tencent Cloud lookups use Result<Option<_>> to distinguish absence from request failure. Only valid empty lists or known lookup-miss error codes permit further lookup or creation. Cloudflare and Tencent Cloud mutation responses must contain a valid result identifier; malformed responses are not cached as successful updates. An enum selects the service and API version for Tencent DNSPod, EdgeOne acceleration, and EdgeOne DNS instead of freely combining strings and booleans.

NameSilo and ClouDNS try the next candidate zone only for documented zone-lookup misses. Authentication, permission, HTTP, and malformed-response errors propagate instead of becoming "zone not found". ClouDNS, Huawei, and NameSilo record lookups reject malformed collections and records missing matching fields to avoid duplicate creation; ClouDNS still accepts both {} and [] as empty collections. Huawei signing and requests use the same RFC3986 query string, encoding spaces as %20 rather than + without a second form-encoding pass. Form encoding for other providers is unchanged.

AliDNS and ESA send updates when extra is supplied even if the address and TTL are unchanged. The existing unchanged-record shortcut remains when no extras are supplied.

Both DNSPod endpoints merge extra after standard mutation parameters, preserving its override priority. IP extraction validates complete addresses with the standard-library IpAddr type and supports compact labels such as IP:2001:db8::1 and address:192.0.2.1; malformed IPv6 literals are not truncated into usable fragments. regex: matches from the start of the extracted original address, preserving IPv6 zero padding, case, and compression for matching. For example, ^2001:0db8: matches 2001:0db8::1; the returned value remains a validated IpAddr. local and numeric indices exclude loopback and unspecified addresses within the requested family before indexing from 0 in the original order. No usable address or an out-of-range index returns an error; private and link-local addresses remain selectable.

Production code forbids unsafe code and does not use an async runtime, a generic error framework, or a mock framework. Provider tests inject an HTTP client, and integration tests only access local fixtures.

Validation

cargo fmt --manifest-path rust/Cargo.toml --check
cargo clippy --manifest-path rust/Cargo.toml --locked --all-targets --all-features -- -D warnings
cargo test --manifest-path rust/Cargo.toml --locked

CI also builds, tests, and packages binaries on Linux x64/arm64, Windows x64, and macOS x64/arm64; it builds and smoke-tests the Docker image offline on Linux x64/arm64.

Security boundaries

• ssl=auto warns and retries once without certificate verification only after a classified certificate-validation error. Prefer ssl=true in production.
• cmd: and shell: in remote configurations execute local commands. Load only trusted configuration URLs.
• regex: uses Rust regex syntax and does not support Python look-around or backreferences. Incompatible patterns return an explicit error.
• A reused custom cache path writes Rust data to the sibling <path>.ddns-rs file and never overwrites the Python cache.
• The Python-literal parser accepts only dictionaries, lists/tuples, strings, numbers, True, False, and None; it cannot execute expressions.
• Logs and errors replace registered IDs, tokens, and their percent-encoded and form-encoded forms with the constant *** marker, without retaining credential prefixes or suffixes. Cache files contain no credentials.
• DNS.COM signed request bodies are not logged, echoed current signatures are redacted from API error messages, and JSON errors omit the raw response. HTTP errors for sensitive requests retain only the status code.
• URL diagnostics hide userinfo, non-root paths, query values, and fragments to protect credentials embedded in callback or remote-configuration paths. The actual request URL is unchanged.

Parity roadmap

1. Port systemd, cron, launchd, and schtasks support.
2. Validate Web/MCP compatibility in long-running deployments and platform migrations.
3. Consider renaming the binary to ddns only after complete parity and a separate stability period.