DDNS

ddns provides DNS discovery and resolver support for DHTTP applications. It is a single Rust package: the historical ddns-core, gmdns, ddns, and ddns-server crate boundaries now live as modules and feature-gated targets in one published Cargo package named dyns, with a library target kept as ddns for source compatibility.

Crate layout

ddns is endpoint-facing support code for the DHTTP ecosystem. Applications normally reach it through the dhttp endpoint facade; lower-level consumers can depend on package dyns directly (typically renamed locally to ddns) when they need DNS wire types, resolver composition, mDNS, or the DNS-over-H3 server.

ddns = { package = "dyns", version = "0.3.0" }

Features

All optional integrations are feature-gated; the default feature set is empty.

Bootstrap constants

build.rs generates the resolver defaults exposed from ddns::resolvers:

The fallbacks are docs/build placeholders, not operational defaults. Real endpoint, server, and E2E runs should set the DHTTP bootstrap environment before building.

Quick start

Resolver chain

Resolvers queries all configured resolvers and streams endpoint addresses from successful backends. System DNS is always available; mDNS, H3, and HTTP builders appear behind their features.

use ddns::resolvers::Resolvers;
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), ddns::resolvers::DnsErrors> {
    let resolvers = Resolvers::builder().system().build();
    let mut endpoints = resolvers.lookup("demo.example.dhttp.net").await?;

    while let Some((source, endpoint)) = endpoints.next().await {
        println!("{source:?}: {endpoint}");
    }

    Ok(())
}

mDNS discovery

use ddns::{mdns::service::Mdns, resolvers::DHTTP_MDNS_SERVICE};
use futures::StreamExt;

#[tokio::main(flavor = "current_thread")]
async fn main() -> std::io::Result<()> {
    let mdns = Mdns::new(
        DHTTP_MDNS_SERVICE,
        std::net::Ipv4Addr::LOCALHOST.into(),
        "lo0",
    )?;
    let mut discoveries = mdns.discover();

    while let Some((source, packet)) = discoveries.next().await {
        println!("received packet from {source}: {packet}");
    }

    Ok(())
}

Runnable examples live in examples/:

cargo run --example mdns_discover -- --ip 127.0.0.1 --device lo0
cargo run --example mdns_query -- --ip 192.168.5.156 --device en0

DNS-over-H3 examples

cargo run --example query --features h3x-resolver -- \
  --server-ca /path/to/root.crt \
  --host nat.genmeta.net

cargo run --example publish --features h3x-resolver -- \
  --server-ca /path/to/root.crt \
  --client-name demo.example.dhttp.net \
  --client-cert /path/to/demo.example.dhttp.net.pem \
  --client-key /path/to/demo.example.dhttp.net.key \
  --host demo.example.dhttp.net \
  --addr 192.168.1.100:8080,192.168.1.101:8080

See examples/README.md for the example CLI parameters and response decoding notes.

DNS-over-H3 server

Start the server with the server feature:

cargo run --bin ddns-server --features server -- --config server.toml

The server exposes two HTTP/3 routes:

Lookup responses use header x-record-format: multi and the binary body from ddns::core::wire::MultiResponse:

u32 count
repeated count times:
  u32 dns_len | dns packet bytes | u32 cert_len | DER publisher certificate bytes

Server configuration lives in server.toml:

• storage is in-memory by default, or Redis when redis = "redis://..." is set;
• ttl_secs controls dynamic record expiry;
• require_signature controls signed endpoint-record enforcement for Standard domains;
• domain_policies are matched in order, with unlisted domains using the Standard policy;
• seed_records add static bootstrap endpoints to lookup results.

Domain policies:

Public DHTTP identity hostnames should use the canonical DhttpName::SUFFIX (.dhttp.net). Infrastructure names such as nat.genmeta.net can remain under Genmeta infrastructure domains.

Endpoint E records

Custom DNS record type E (QTYPE = 266) carries DHTTP endpoint addresses. The current wire format is:

flags(u8)
[sequence(varint) if CLUSTERED]
primary address: port(u16) + IPv4/IPv6 bytes
[agent address if NAT]
[load(f32) if LOAD]
[signature: scheme(u16) + len(varint) + bytes if SIGNED]

Flag bits:

For DHTTP endpoint publishing, MAIN and sequence are derived from the publisher certificate's DHTTP subject key identifier. Operators do not choose these fields manually: primary certificates publish MAIN = true, secondary certificates publish MAIN = false, and the certificate-chain sequence becomes the normalized endpoint-record sequence. An omitted sequence field means sequence 0.

Signed records encode the signature scheme in the record; the no-scheme signed format is not accepted. Legacy unsigned fixed-length endpoint address records are still parsed by length for address-only compatibility.

Project structure

src/core.rs                  DNS core module root
src/core/parser/             DNS packet, name, question, record, varint, and signature parsers
src/core/parser/record/      A/AAAA/SRV/TXT/PTR/CNAME/E record parsing and encoding
src/core/wire.rs             HTTP multi-record response wire format
src/mdns.rs                  mDNS module root
src/mdns/protocol.rs         UDP multicast socket and packet routing
src/mdns/service.rs          High-level mDNS service API
src/mdns/resolvers/          mDNS resolver integration
src/resolvers.rs             Resolver chain and resolver defaults
src/resolvers/h3.rs          DNS-over-H3 resolver/publisher
src/resolvers/http.rs        DNS-over-HTTP resolver/publisher
src/resolvers/deferred.rs    Deferred resolver initialization helper
src/publisher.rs             Endpoint record signer and publication loop
src/publisher/               Address selection, publish dispatch, packet signing
src/bin/ddns-server/         DNS-over-H3 server implementation
examples/                    mDNS and DNS-over-H3 example programs
server.toml                  Example server configuration