08_dns_proxy_cdn.md

Crate: kinetic-types Stage: 1 Reading Time: 15 minutes Depends On: vdf.rs, name_record.rs

What Is This?

This document extensively covers three highly interconnected modules: dns.rs, proxy.rs, and cdn.rs. Together, they fundamentally define how the Kinetic network translates .kin human-readable names into actual underlying network primitives. They also define exactly how those translations are safely, reliably, and efficiently routed across isolated processes and caching layers. At a high, conceptual level, this document is examining the structural foundation for decentralized naming within the Kinetic ecosystem. It forms the bedrock of identity resolution. It also serves as the core infrastructure for content delivery. By establishing the exact memory layout for network records, it guarantees uniformity across the network. Furthermore, by providing zero-copy message structures, it ensures that the user-facing browser extension can talk to the background core node at blazing fast speeds.

Why Kinetic Needs This

If the Kinetic network only resolved .kin names to standard, traditional IP addresses, it would fail its core mission. It would not be a true peer-to-peer network. Instead, it would essentially just operate as an alternative version of ICANN, heavily reliant on central points of failure. The network absolutely requires a highly flexible way to link names directly to cryptographic identities. This is achieved using Key Identifiers (KID). It also requires the ability to link names to distributed decentralized storage. This is achieved using InterPlanetary File System (IPFS) content identifiers. Finally, it must link names directly to libp2p network nodes using PeerIds. All of this must happen without ever relying on centralized servers or authorities.

Furthermore, the architectural design of Kinetic places the user-facing browser extension and the underlying Kinetic network node in completely separate operating system processes. Because they are isolated for security reasons, they desperately need a blisteringly fast way to communicate with one another. Without specialized, zero-copy Inter-Process Communication (IPC) structures (like those carefully designed in proxy.rs and cdn.rs), the system would grind to a halt.

Warning

Every single network request would incur massive, unnecessary memory overhead. Constantly allocating new memory and deeply copying request strings across process boundaries is computationally expensive.

Similarly, deeply copying heavy response payloads (like large images or video buffers) across boundaries would cripple overall network performance. It would immediately spike CPU and memory usage, making the extension unusable for end users.

How It Works

DNS Resolution Pipeline

When a user attempts to resolve a decentralized domain, such as mysite.kin, a complex process begins. The Kinetic network initiates a traversal of the Distributed Hash Table (DHT). Its goal is to locate a NameRecord mathematically corresponding to that specific domain. Once the network successfully finds this record, it extracts the raw byte payload embedded within it. This raw payload is fundamentally a serialized DnsZone structure.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/dns.rs — Lines 11 to 15
}

The DnsZone struct is designed to hold a standard HashMap. This HashMap actively maps subdomain labels (for example, “www”, “api”, or simply “@” for the root domain) to a dynamically sized list of DnsRecords. The network node looks up the user’s requested subdomain in this exact map. This lookup directly determines where the network traffic should actually be routed.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/dns.rs — Lines 17 to 27
}

The DnsRecord enum is where the core decentralization magic actually happens in the codebase. It fully supports standard internet routing mechanisms. For example, it supports A and AAAA records for traditional IP addresses. It also supports CNAME for standard domain aliases. But more importantly, it introduces custom, Kinetic-specific variants meticulously tailored for Web3 interactions:

• PeerId(String): This critical variant routes traffic directly to a specific libp2p peer. Instead of resolving to a fragile IP address that might change dynamically or sit invisibly behind a strict NAT firewall, it resolves to a permanent, persistent network identity. This directly enables true decentralized peer discovery without requiring a central matchmaking server.
• KID(String): This points directly to a Key Identifier document on the network. This allows anyone traversing the network to rigorously and cryptographically verify the exact identity and public keys of the name owner.
• IPFS(String): This variant links directly to an IPFS content identifier (often called a CID). By utilizing this, users can seamlessly host fully decentralized, static websites that are linked directly to a .kin name.

High-Performance IPC (Inter-Process Communication)

The browser extension cannot read the DHT directly. This is because it runs inside a highly restricted, isolated browser sandbox environment. Instead, to fetch data, it must send an HTTP-like request to the local background Kinetic node using IPC.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/proxy.rs — Lines 15 to 22
}

The ProxyRequest struct mathematically bridges this process gap. It captures all the standard elements of an HTTP request: the method, the path, the headers, and the body. Crucially, the various string components inside this request exclusively use Arc<str>.

Note

Consider a scenario where 1,000 concurrent proxy worker threads are handling rapid requests. If they all share the exact same standard “User-Agent” header string, Arc<str> ensures a massive optimization. It guarantees the string is only actually allocated in system memory a single time.

The worker threads simply pass around ultra-lightweight reference counts instead of duplicating the exact same string 1,000 times on the heap.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/proxy.rs — Lines 25 to 33
}

Similarly, the ProxyResponse structure encapsulates all returning data. To intelligently avoid copying massive web assets (like uncompressed images, heavy video files, or large WASM executable bundles) across operating system process boundaries, it employs a trick. It mandates the use of the bytes::Bytes type for the payload body. This functions practically as a zero-copy byte buffer. When the massive response body needs to be rapidly sent to multiple different parts of the system, it is cloned extremely cheaply. It does this simply by incrementing an atomic reference counter, outright avoiding the need to deeply copy every individual byte. Additionally, a custom serialization wrapper called serde_bytes_wrapper is utilized.

Important

This explicitly ensures these bytes are encoded efficiently as raw binary over the wire. If we relied on standard Rust serialization, it would encode the bytes as a highly inefficient sequence of JSON numbers, drastically increasing the network serialization overhead.

CDN Caching Layer

Fetching a NameRecord directly from the DHT every single time is far too slow for a seamless web browsing experience. Kinetic nodes actively mitigate this frustrating latency by caching records locally in memory. The CDN module elegantly provides the IPC structures needed for this direct, rapid cache access layer.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/cdn.rs — Lines 14 to 21
}

The CdnRequest struct simply queries a domain name using a hyper-efficient, zero-copy Arc<str>. The CdnResponse responds dynamically with an Option<Vec<u8>>. The use of the Option type is absolutely crucial and intentional here. Returning None clearly and unambiguously signals a “cache miss” to the system. This immediately prompts the system to confidently fall back to a full, standard DHT lookup. Returning Some(bytes) explicitly means the cache was successfully hit. It instantly provides the fully serialized NameRecord without network delay.

Dynamic Host Routing

Sometimes, a peer’s physical network location or public IP address changes rapidly due to network topography. However, their logical, overarching host_id stays exactly the same.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/dns.rs — Lines 30 to 45
}

The HostRoutingRecord struct exists explicitly to handle this dynamic mapping problem gracefully. Unlike a rigid, static DnsZone which maps subdomains to addresses in a fairly permanent, unmoving way, the HostRoutingRecord is fluid. It maps a constant, logical host_id directly to a current, potentially ephemeral libp2p current_peer_id. To guarantee security, this record is actively and securely signed by the owner. This cryptographic proof is securely stored in the signature field. It is also mathematically tied directly to the current verifiable drand round. This specific round number is stored securely in the drand_kyn field. This powerful cryptographic combination directly prevents dangerous replay attacks. It ensures that network routing stays fresh and accurate.

Important

A malicious attacker cannot successfully broadcast an old, outdated routing record. The cryptographic signature inextricably binds the record to a specific, unalterable point in time.

Key Pieces

• DnsZone (dns.rs:11) The structural root of any .kin network payload. It acts as a primary collection logically mapping string subdomains directly to decentralized network records. This is precisely what you receive when you successfully decode the raw payload of a NameRecord.
• DnsRecord (dns.rs:17) The absolute core routing primitive within the network. It bridges legacy internet protocols (like A and AAAA records) with Web3 specific protocols (like IPFS and PeerId).
• HostRoutingRecord (dns.rs:30) A dynamic, cryptographically signed mapping system. It continuously tracks roaming peers across the global network, ensuring you can always successfully find a host even if their underlying ISP dynamically changes their IP address.
• ProxyRequest (proxy.rs:15) A heavily optimized, zero-copy IPC payload. It allows the sandboxed browser extension to completely and accurately describe an HTTP request to the underlying node without ever allocating massive amounts of unnecessary memory.
• ProxyResponse (proxy.rs:25) The direct structural counterpart to ProxyRequest. It acts as the vehicle for returning HTTP status codes, parsed headers, and efficient zero-copy byte buffers (bytes::Bytes) back to the client cleanly and swiftly.
• CdnRequest (cdn.rs:14) A lightweight, ultra-efficient, zero-copy query payload. It is specifically used to ask the local node’s caching layer if it has a specific domain name securely recorded in memory.
• CdnResponse (cdn.rs:18) An elegant wrapper type explicitly leveraging Rust’s powerful Option enum. It allows the system to gracefully handle unexpected cache misses without relying on expensive exceptions or throwing heavy system errors.

How This Connects to the Rest of Kinetic

• CROSS-CRATE: NameRecord This is fundamentally defined and thoroughly explained in the dedicated documentation for name_record.rs. The physical byte payload of a NameRecord is strictly stored within the network DHT, but it is seamlessly and logically decoded into a readable DnsZone exclusively by this module.
• FORWARD DEPENDENCY: kinetic-kid The specific KID(String) variant located inside the DnsRecord enum actively relies heavily on the kinetic-kid crate. It needs this forward dependency to actually resolve Key Identifier documents efficiently across the network.
• FORWARD DEPENDENCY: kinetic-verify The signature field meticulously found within the HostRoutingRecord is rigorously and securely validated by specific cryptographic functions. These highly complex functions will be extensively explained in the upcoming kinetic-verify crate documentation.
• FORWARD DEPENDENCY: kinetic-drand The critical drand_kyn field explicitly ties active routing records to verifiable randomness beacons. This connection is fundamental for explicitly ensuring strict, mathematically sound time-bound validity for all network paths.

Quick Reference

Open Questions / Things to Revisit

• The HostRoutingRecord signature method actively requires a mysterious network_id for proper signing. How exactly is this network_id securely distributed and flawlessly agreed upon by all clients without accidentally introducing a highly vulnerable centralization vector?
• HostRoutingRecord inherently and permanently ties its entire validity to the drand_kyn field. If the local system clock drifts severely, or the external drand synchronization gets heavily delayed, could perfectly valid routing updates be erroneously rejected by the network node?
• Both ProxyRequest and ProxyResponse serialize active HTTP headers as a completely flat Vec<(Arc<str>, Arc<str>)>. Searching for a specific HTTP header therefore always requires a potentially slow linear scan (O(N)). If application header lists get particularly large, this architectural choice might become a noticeably painful performance bottleneck compared to using a traditional HashMap.
• The #[serde(other)] attribute currently silently and implicitly absorbs unrecognized DNS record types directly into the generic Other variant. Because it carelessly throws away the actual incoming type value, we permanently lose the critical ability to log or safely inspect what the unrecognized type string actually was. Should this implementation be modified immediately to actively capture unknown types for much better network telemetry?