Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Crate: kinetic-dns

Stage: 10

Reading Time: 120 mins

Depends On: kinetic-core, kinetic-daemon (running)

What Is This?

kinetic-dns is the bridge that makes .kin domains work inside a standard web browser or any application that performs DNS lookups. It runs as a background service on the local machine, binding to a UDP socket and acting as the local DNS resolver.

When the user’s OS asks “what is the IP address of saif.kin?”, this process answers by querying the running Kinetic daemon’s HTTP API, which triggers a full DHT lookup through the Kinetic peer-to-peer network.

For all standard internet domains (.com, .org, .io), it transparently passes the query to the operating system’s configured DNS server or falls back to Cloudflare 1.1.1.1 if the system configuration is unavailable.

Key Pieces

  1. bin/kinetic-dns.rs: The binary entrypoint. Contains the CLI (install, uninstall, start, stop, run), the OS DNS configuration injection, and the server boot loop.
  2. lib.rs and KineticDnsHandler: The central struct that holds all shared state — the HTTP client, the Moka cache, the upstream resolvers, and the Atlas TLD set.
  3. handler.rs: The request router. Checks if the query suffix is .kin and dispatches to either resolve_kinetic() or resolve_upstream().
  4. kinetic_records.rs: The heavy-lifting resolution pipeline. Handles cache misses, daemon API calls, record signature verification, KID end-to-end authentication, SSRF filtering, and DNS packet construction.
  5. upstream.rs: Creates and manages the standard upstream resolver (system DNS or Cloudflare DoH fallback) and the kinetic-atlas resolver.
  6. cache.rs: Asymmetric TTL Moka cache. Positive hits survive 5 minutes, NXDOMAIN hits expire in 30 seconds.

How to Read This Stage

  • Start with 02_bin_main.md to understand how the service installs and boots.
  • Read 04_handler_upstream_cache.md to understand the router that dispatches queries.
  • Finish with 03_kinetic_records.md to understand the deepest part — how a .kin domain name becomes a real IP address via the DHT.