Skip to main content

qualia_core_db/net/dns/
resolver.rs

1//! Pure-Rust native DNS resolver client with zero heap in hot paths.
2//!
3//! Replaces 3rd-party dependencies (`trust-dns-resolver`, `hickory-proto`)
4//! and external system commands (`dig`). Directly produces QualiaDB `NQuin`
5//! records and feeds them into the Q42 zero-heap ring-buffer cache.
6//!
7//! Conforms to QualiaDB Rule 0-A (zero-heap in hot paths) and Rule 0-B.
8
9#![allow(dead_code, unused_imports)]
10
11use super::cache_ring::DnsCacheRing;
12use super::quin_records::{
13    decode_a_record, decode_aaaa_record, decode_cname_record, wire_record_view_to_quin,
14};
15use super::sdn::{parse_front_door_txt, SdnFrontDoorView};
16use super::wire::{build_query_packet, parse_records, DnsHeader, DnsType};
17use crate::{q_hash, NQuin, PermissiveRoutingLane};
18
19/// Standard well-known recursive resolvers (IPv4).
20pub const RESOLVER_CLOUDFLARE: &str = "1.1.1.1:53";
21pub const RESOLVER_QUAD9: &str = "9.9.9.9:53";
22pub const RESOLVER_GOOGLE: &str = "8.8.8.8:53";
23
24/// Standard well-known recursive resolvers (IPv6).
25pub const RESOLVER_CLOUDFLARE_V6: &str = "[2606:4700:4700::1111]:53";
26pub const RESOLVER_QUAD9_V6: &str = "[2620:fe::fe]:53";
27pub const RESOLVER_GOOGLE_V6: &str = "[2001:4860:4860::8888]:53";
28
29/// Query configuration parameters.
30#[derive(Debug, Clone, Copy)]
31pub struct ResolverConfig<'a> {
32    pub nameserver: &'a str,
33    pub timeout_ms: u64,
34    pub recursion_desired: bool,
35    pub routing_lane: PermissiveRoutingLane,
36}
37
38impl<'a> Default for ResolverConfig<'a> {
39    fn default() -> Self {
40        Self {
41            nameserver: RESOLVER_CLOUDFLARE,
42            timeout_ms: 3000,
43            recursion_desired: true,
44            routing_lane: PermissiveRoutingLane::PassthroughStandard,
45        }
46    }
47}
48
49/// Helper to bind a UDP socket appropriate for IPv4 or IPv6 nameservers.
50#[cfg(not(target_arch = "wasm32"))]
51fn bind_socket_for_nameserver(
52    nameserver: &str,
53    timeout_ms: u64,
54) -> Result<std::net::UdpSocket, &'static str> {
55    use std::net::UdpSocket;
56    use std::time::Duration;
57
58    let is_v6 = nameserver.starts_with('[') || nameserver.matches(':').count() > 1;
59    let socket = if is_v6 {
60        UdpSocket::bind("[::]:0").or_else(|_| UdpSocket::bind("0.0.0.0:0"))
61    } else {
62        UdpSocket::bind("0.0.0.0:0")
63    }
64    .map_err(|_| "failed to bind local UDP socket")?;
65
66    socket
67        .set_read_timeout(Some(Duration::from_millis(timeout_ms)))
68        .map_err(|_| "failed to set UDP read timeout")?;
69
70    Ok(socket)
71}
72
73/// Zero-heap DNS resolver executing over raw UDP sockets on native platforms.
74pub struct QualiaDnsResolver<'a> {
75    pub config: ResolverConfig<'a>,
76}
77
78impl<'a> QualiaDnsResolver<'a> {
79    /// Creates a default `QualiaDnsResolver`.
80    pub fn new(config: ResolverConfig<'a>) -> Self {
81        Self { config }
82    }
83
84    #[cfg(not(target_arch = "wasm32"))]
85    /// Perform a raw UDP DNS query and parse the responses directly into `out_quins`.
86    ///
87    /// Returns the number of quins written into `out_quins`. Zero heap allocation.
88    pub fn query_into(
89        &self,
90        domain: &str,
91        qtype: DnsType,
92        out_quins: &mut [NQuin],
93    ) -> Result<usize, &'static str> {
94        let socket = bind_socket_for_nameserver(self.config.nameserver, self.config.timeout_ms)?;
95
96        let mut tx_buf = [0u8; 512];
97        let query_id = (q_hash(domain) & 0xFFFF) as u16;
98        let tx_len = build_query_packet(
99            query_id,
100            domain,
101            qtype,
102            self.config.recursion_desired,
103            &mut tx_buf,
104        )?;
105
106        socket
107            .send_to(&tx_buf[..tx_len], self.config.nameserver)
108            .map_err(|_| "failed to send DNS query packet")?;
109
110        let mut rx_buf = [0u8; 4096];
111        let (rx_len, _) = socket
112            .recv_from(&mut rx_buf)
113            .map_err(|_| "DNS query timed out or failed to receive response")?;
114
115        self.parse_response_into(&rx_buf[..rx_len], query_id, out_quins)
116    }
117
118    /// Parse a raw DNS response packet into caller-supplied `out_quins`.
119    /// Zero heap allocation.
120    pub fn parse_response_into(
121        &self,
122        packet: &[u8],
123        expected_id: u16,
124        out_quins: &mut [NQuin],
125    ) -> Result<usize, &'static str> {
126        let header = DnsHeader::decode(packet)?;
127        if header.id != expected_id {
128            return Err("DNS transaction ID mismatch");
129        }
130        if !header.is_response() {
131            return Err("received DNS packet is not a response");
132        }
133        if header.rcode() != 0 {
134            return Err("DNS server returned error rcode");
135        }
136
137        let mut offset = DnsHeader::SIZE;
138
139        // Skip question section
140        let mut dummy_name = [0u8; 256];
141        for _ in 0..header.qdcount {
142            let (new_offset, _) = super::wire::decode_domain_name(packet, offset, &mut dummy_name)?;
143            offset = new_offset + 4; // skip qtype (2) and qclass (2)
144            if offset > packet.len() {
145                return Err("truncated question section");
146            }
147        }
148
149        let mut quin_count = 0;
150        let lane = self.config.routing_lane;
151
152        // Parse answers with compression-aware view mapper
153        parse_records(packet, offset, header.ancount as usize, |name, rec| {
154            if quin_count < out_quins.len() {
155                if let Some(q) = wire_record_view_to_quin(name, &rec, lane) {
156                    out_quins[quin_count] = q;
157                    quin_count += 1;
158                }
159            }
160            Ok(())
161        })?;
162
163        Ok(quin_count)
164    }
165
166    #[cfg(not(target_arch = "wasm32"))]
167    /// Resolve an IPv4 `A` record directly.
168    pub fn resolve_ipv4(&self, domain: &str) -> Result<[u8; 4], &'static str> {
169        let mut quins = [NQuin::default(); 4];
170        let count = self.query_into(domain, DnsType::A, &mut quins)?;
171        for q in &quins[..count] {
172            if let Some((ip, _, _)) = decode_a_record(q) {
173                return Ok(ip);
174            }
175        }
176        Err("no A record found")
177    }
178
179    #[cfg(not(target_arch = "wasm32"))]
180    /// Resolve an IPv6 `AAAA` record directly.
181    pub fn resolve_ipv6(&self, domain: &str) -> Result<[u8; 16], &'static str> {
182        let mut quins = [NQuin::default(); 4];
183        let count = self.query_into(domain, DnsType::AAAA, &mut quins)?;
184        for q in &quins[..count] {
185            if let Some((ip, _, _)) = decode_aaaa_record(q) {
186                return Ok(ip);
187            }
188        }
189        Err("no AAAA record found")
190    }
191
192    #[cfg(not(target_arch = "wasm32"))]
193    /// Dual-stack IP resolution: queries AAAA first, falls back to A.
194    pub fn resolve_ip(&self, domain: &str) -> Result<std::net::IpAddr, &'static str> {
195        if let Ok(v6) = self.resolve_ipv6(domain) {
196            return Ok(std::net::IpAddr::V6(std::net::Ipv6Addr::from(v6)));
197        }
198        let v4 = self.resolve_ipv4(domain)?;
199        Ok(std::net::IpAddr::V4(std::net::Ipv4Addr::from(v4)))
200    }
201
202    #[cfg(not(target_arch = "wasm32"))]
203    /// Resolve a `CNAME` record returning target hash and TTL.
204    pub fn resolve_cname(&self, domain: &str) -> Result<(u64, u32), &'static str> {
205        let mut quins = [NQuin::default(); 4];
206        let count = self.query_into(domain, DnsType::CNAME, &mut quins)?;
207        for q in &quins[..count] {
208            if let Some((target_hash, ttl, _)) = decode_cname_record(q) {
209                return Ok((target_hash, ttl));
210            }
211        }
212        Err("no CNAME record found")
213    }
214
215    #[cfg(not(target_arch = "wasm32"))]
216    /// Resolve and populate into a zero-heap cache ring buffer.
217    pub fn query_and_cache<const N: usize>(
218        &self,
219        domain: &str,
220        qtype: DnsType,
221        ring: &mut DnsCacheRing<N>,
222        current_clock: u32,
223    ) -> Result<usize, &'static str> {
224        let mut quins = [NQuin::default(); 8];
225        let n = self.query_into(domain, qtype, &mut quins)?;
226        for q in quins.iter().take(n) {
227            ring.insert(*q, current_clock);
228        }
229        Ok(n)
230    }
231
232    #[cfg(not(target_arch = "wasm32"))]
233    /// Resolve a `_qdp.<domain>` Front-Door record into a borrowed view.
234    pub fn resolve_sdn_front_door<'b>(
235        &self,
236        domain: &'b str,
237        txt_storage: &'b mut [u8; 512],
238    ) -> Result<SdnFrontDoorView<'b>, &'static str> {
239        let mut qdp_domain = [0u8; 128];
240        const PREFIX: &[u8] = b"_qdp.";
241        if PREFIX.len() + domain.len() > qdp_domain.len() {
242            return Err("domain name too long for front-door query");
243        }
244        qdp_domain[..PREFIX.len()].copy_from_slice(PREFIX);
245        qdp_domain[PREFIX.len()..PREFIX.len() + domain.len()].copy_from_slice(domain.as_bytes());
246        let qdp_name = std::str::from_utf8(&qdp_domain[..PREFIX.len() + domain.len()])
247            .map_err(|_| "invalid UTF-8 domain")?;
248
249        let socket = bind_socket_for_nameserver(self.config.nameserver, self.config.timeout_ms)?;
250
251        let mut tx_buf = [0u8; 512];
252        let qid = 0x4242;
253        let tx_len = build_query_packet(qid, qdp_name, DnsType::TXT, true, &mut tx_buf)?;
254        socket
255            .send_to(&tx_buf[..tx_len], self.config.nameserver)
256            .map_err(|_| "send failed")?;
257
258        let mut rx_buf = [0u8; 4096];
259        let (rx_len, _) = socket.recv_from(&mut rx_buf).map_err(|_| "recv failed")?;
260
261        let header = DnsHeader::decode(&rx_buf[..rx_len])?;
262        if header.rcode() != 0 || header.ancount == 0 {
263            return Err("front door TXT not found");
264        }
265
266        let mut offset = DnsHeader::SIZE;
267        let mut dummy = [0u8; 256];
268        for _ in 0..header.qdcount {
269            let (new_off, _) =
270                super::wire::decode_domain_name(&rx_buf[..rx_len], offset, &mut dummy)?;
271            offset = new_off + 4;
272        }
273
274        let mut txt_len = 0;
275        parse_records(
276            &rx_buf[..rx_len],
277            offset,
278            header.ancount as usize,
279            |_name, rec| {
280                if rec.rtype == DnsType::TXT && txt_len == 0 {
281                    let mut cursor = 0;
282                    while cursor < rec.rdata.len() {
283                        let seg_len = rec.rdata[cursor] as usize;
284                        cursor += 1;
285                        if cursor + seg_len > rec.rdata.len() {
286                            break;
287                        }
288                        let cp = core::cmp::min(seg_len, txt_storage.len() - txt_len);
289                        txt_storage[txt_len..txt_len + cp]
290                            .copy_from_slice(&rec.rdata[cursor..cursor + cp]);
291                        txt_len += cp;
292                        cursor += seg_len;
293                    }
294                }
295                Ok(())
296            },
297        )?;
298
299        if txt_len == 0 {
300            return Err("empty front-door TXT rdata");
301        }
302
303        let txt_str =
304            std::str::from_utf8(&txt_storage[..txt_len]).map_err(|_| "invalid UTF-8 in TXT")?;
305        parse_front_door_txt(domain, txt_str)
306    }
307}
308
309#[cfg(test)]
310mod tests {
311    use super::*;
312
313    #[test]
314    fn parse_response_synthetic_a() {
315        // Build a query, then craft a synthetic IPv4 response
316        let mut packet = [0u8; 512];
317        let qlen = build_query_packet(0x1337, "test.local", DnsType::A, true, &mut packet).unwrap();
318
319        let mut resp_header = DnsHeader::new_query(0x1337, true);
320        resp_header.flags |=
321            super::super::wire::FLAG_QR_RESPONSE | super::super::wire::FLAG_AA_AUTHORITATIVE;
322        resp_header.ancount = 1;
323        resp_header.encode(&mut packet[0..12]).unwrap();
324
325        let mut offset = qlen;
326        // Answer name: pointer to 12
327        packet[offset] = 0xC0;
328        packet[offset + 1] = 0x0C;
329        offset += 2;
330        // Type A (1), Class IN (1), TTL 300, RDLen 4, IP 127.0.0.1
331        packet[offset..offset + 2].copy_from_slice(&1u16.to_be_bytes());
332        packet[offset + 2..offset + 4].copy_from_slice(&1u16.to_be_bytes());
333        packet[offset + 4..offset + 8].copy_from_slice(&300u32.to_be_bytes());
334        packet[offset + 8..offset + 10].copy_from_slice(&4u16.to_be_bytes());
335        packet[offset + 10..offset + 14].copy_from_slice(&[127, 0, 0, 1]);
336        offset += 14;
337
338        let resolver = QualiaDnsResolver::new(ResolverConfig::default());
339        let mut quins = [NQuin::default(); 4];
340        let n = resolver
341            .parse_response_into(&packet[..offset], 0x1337, &mut quins)
342            .unwrap();
343        assert_eq!(n, 1);
344
345        let (ip, ttl, _) = decode_a_record(&quins[0]).unwrap();
346        assert_eq!(ip, [127, 0, 0, 1]);
347        assert_eq!(ttl, 300);
348    }
349
350    #[test]
351    fn parse_response_synthetic_aaaa() {
352        // Build a query, then craft a synthetic IPv6 response
353        let mut packet = [0u8; 512];
354        let qlen =
355            build_query_packet(0x2442, "v6.test.local", DnsType::AAAA, true, &mut packet).unwrap();
356
357        let mut resp_header = DnsHeader::new_query(0x2442, true);
358        resp_header.flags |=
359            super::super::wire::FLAG_QR_RESPONSE | super::super::wire::FLAG_AA_AUTHORITATIVE;
360        resp_header.ancount = 1;
361        resp_header.encode(&mut packet[0..12]).unwrap();
362
363        let mut offset = qlen;
364        packet[offset] = 0xC0;
365        packet[offset + 1] = 0x0C;
366        offset += 2;
367        // Type AAAA (28), Class IN (1), TTL 7200, RDLen 16
368        packet[offset..offset + 2].copy_from_slice(&28u16.to_be_bytes());
369        packet[offset + 2..offset + 4].copy_from_slice(&1u16.to_be_bytes());
370        packet[offset + 4..offset + 8].copy_from_slice(&7200u32.to_be_bytes());
371        packet[offset + 8..offset + 10].copy_from_slice(&16u16.to_be_bytes());
372        let expected_ip: [u8; 16] = [
373            0x20, 0x01, 0x0d, 0xb8, 0x85, 0xa3, 0x00, 0x00, 0x00, 0x00, 0x8a, 0x2e, 0x03, 0x70,
374            0x73, 0x34,
375        ];
376        packet[offset + 10..offset + 26].copy_from_slice(&expected_ip);
377        offset += 26;
378
379        let resolver = QualiaDnsResolver::new(ResolverConfig::default());
380        let mut quins = [NQuin::default(); 4];
381        let n = resolver
382            .parse_response_into(&packet[..offset], 0x2442, &mut quins)
383            .unwrap();
384        assert_eq!(n, 1);
385
386        let (ip, ttl, _) = decode_aaaa_record(&quins[0]).unwrap();
387        assert_eq!(ip, expected_ip);
388        assert_eq!(ttl, 7200);
389    }
390}