Skip to main content

qualia_core_db/net/dns/
lossless.rs

1//! Zero-Heap Lossless DNS Record Chunker & Codec.
2//!
3//! Provides 100% byte-exact (lossless) encoding and decoding for arbitrary-length
4//! DNS resource records (TXT, CERT, DNSKEY, RRSIG, HTTPS, SOA, etc.) across
5//! deterministic 48-byte `NQuin` chunk chains.
6//!
7//! Each chunk stores up to 16 raw payload bytes in `object` and `context`,
8//! indexed by sequence numbers in `metadata`, protected by ECC parity.
9//!
10//! Conforms strictly to QualiaDB Rule 0-A (zero-heap in hot paths) and Rule 0-B (< 500 lines).
11
12#![allow(dead_code)]
13
14use super::wire::DnsType;
15use crate::{q_hash, NQuin, PermissiveRoutingLane};
16
17/// Modality opcode for lossless payload chunk in predicate bits [0..7].
18pub const OP_DNS_CHUNK: u8 = 0x62;
19
20/// Maximum payload bytes stored per Super-Quin chunk.
21pub const CHUNK_CAPACITY: usize = 16;
22
23/// Encode an arbitrary byte slice of DNS RDATA into contiguous, lossless `NQuin` chunks.
24///
25/// Returns the number of quins written into `out_chunk_quins`. Zero heap allocation.
26pub fn encode_lossless_rdata_chunks(
27    domain: &str,
28    rtype: DnsType,
29    ttl: u32,
30    rdata: &[u8],
31    lane: PermissiveRoutingLane,
32    out_chunk_quins: &mut [NQuin],
33) -> Result<usize, &'static str> {
34    if rdata.is_empty() {
35        return Ok(0);
36    }
37
38    let total_chunks = (rdata.len() + CHUNK_CAPACITY - 1) / CHUNK_CAPACITY;
39    if total_chunks > out_chunk_quins.len() {
40        return Err("output quins buffer too small for lossless rdata chunks");
41    }
42    if total_chunks > 0xFFFF {
43        return Err("rdata exceeds maximum chunkable size (1MB)");
44    }
45
46    let subject = q_hash(domain);
47    let pred_base = q_hash("qualia:dns:lossless_chunk") ^ (u16::from(rtype) as u64);
48    let predicate = (pred_base << 8) | (OP_DNS_CHUNK as u64);
49
50    for (chunk_idx, chunk_bytes) in rdata.chunks(CHUNK_CAPACITY).enumerate() {
51        let mut hi_buf = [0u8; 8];
52        let mut lo_buf = [0u8; 8];
53
54        let hi_len = core::cmp::min(chunk_bytes.len(), 8);
55        hi_buf[..hi_len].copy_from_slice(&chunk_bytes[..hi_len]);
56
57        if chunk_bytes.len() > 8 {
58            let lo_len = chunk_bytes.len() - 8;
59            lo_buf[..lo_len].copy_from_slice(&chunk_bytes[8..8 + lo_len]);
60        }
61
62        let object = u64::from_be_bytes(hi_buf);
63        let context = u64::from_be_bytes(lo_buf);
64
65        // Metadata layout:
66        // [61..62]: PermissiveRoutingLane
67        // [32..60]: chunk_idx (29 bits)
68        // [16..31]: total_chunks (16 bits)
69        // [0..15]:  valid bytes in this chunk (1..16) + ttl fold
70        let valid_bytes = chunk_bytes.len() as u64;
71        let metadata = ((lane as u64) << 61)
72            | (((chunk_idx as u64) & 0x1FFF_FFFF) << 32)
73            | (((total_chunks as u64) & 0xFFFF) << 16)
74            | (valid_bytes & 0xFF)
75            | (((ttl as u64) & 0xFF) << 8);
76
77        let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
78        out_chunk_quins[chunk_idx] = NQuin {
79            subject,
80            predicate,
81            object,
82            context,
83            metadata,
84            parity,
85        };
86    }
87
88    Ok(total_chunks)
89}
90
91/// Reassemble an arbitrary-length DNS RDATA payload from an `NQuin` chunk slice.
92///
93/// Returns the total bytes written into `out_rdata`. Zero heap allocation.
94pub fn decode_lossless_rdata_chunks(
95    chunk_quins: &[NQuin],
96    expected_rtype: DnsType,
97    out_rdata: &mut [u8],
98) -> Result<usize, &'static str> {
99    if chunk_quins.is_empty() {
100        return Ok(0);
101    }
102
103    let expected_pred_base =
104        q_hash("qualia:dns:lossless_chunk") ^ (u16::from(expected_rtype) as u64);
105    let expected_predicate = (expected_pred_base << 8) | (OP_DNS_CHUNK as u64);
106
107    let first = &chunk_quins[0];
108    if !first.verify_ecc_parity() || first.predicate != expected_predicate {
109        return Err("invalid chunk parity or rtype mismatch on first chunk");
110    }
111
112    let expected_total_chunks = ((first.metadata >> 16) & 0xFFFF) as usize;
113    if chunk_quins.len() < expected_total_chunks {
114        return Err("missing chunk quins in slice");
115    }
116
117    let mut written = 0;
118
119    for (i, quin) in chunk_quins.iter().take(expected_total_chunks).enumerate() {
120        if !quin.verify_ecc_parity() {
121            return Err("chunk ECC parity verification failed");
122        }
123        if quin.predicate != expected_predicate {
124            return Err("chunk predicate mismatch");
125        }
126
127        let chunk_idx = ((quin.metadata >> 32) & 0x1FFF_FFFF) as usize;
128        if chunk_idx != i {
129            return Err("out-of-order chunk detected");
130        }
131
132        let valid_bytes = (quin.metadata & 0xFF) as usize;
133        if valid_bytes > CHUNK_CAPACITY || valid_bytes == 0 {
134            return Err("invalid chunk payload byte length");
135        }
136        if written + valid_bytes > out_rdata.len() {
137            return Err("output buffer overflow during rdata reassembly");
138        }
139
140        let hi_bytes = quin.object.to_be_bytes();
141        let lo_bytes = quin.context.to_be_bytes();
142
143        let hi_take = core::cmp::min(valid_bytes, 8);
144        out_rdata[written..written + hi_take].copy_from_slice(&hi_bytes[..hi_take]);
145        written += hi_take;
146
147        if valid_bytes > 8 {
148            let lo_take = valid_bytes - 8;
149            out_rdata[written..written + lo_take].copy_from_slice(&lo_bytes[..lo_take]);
150            written += lo_take;
151        }
152    }
153
154    Ok(written)
155}
156
157/// Lossless structured record enum providing zero-copy access to decoded fields.
158#[derive(Debug, Clone, Copy, PartialEq, Eq)]
159pub enum LosslessDnsRecord<'a> {
160    A([u8; 4]),
161    Aaaa([u8; 16]),
162    Cname(&'a str),
163    Ns(&'a str),
164    Ptr(&'a str),
165    Mx {
166        preference: u16,
167        exchange: &'a str,
168    },
169    Srv {
170        priority: u16,
171        weight: u16,
172        port: u16,
173        target: &'a str,
174    },
175    Txt(&'a [u8]),
176    Caa {
177        flags: u8,
178        tag: &'a str,
179        value: &'a [u8],
180    },
181    Tlsa {
182        usage: u8,
183        selector: u8,
184        matching_type: u8,
185        cert_data: &'a [u8],
186    },
187    Https {
188        priority: u16,
189        target: &'a str,
190        params: &'a [u8],
191    },
192    Dnskey {
193        flags: u16,
194        protocol: u8,
195        algorithm: u8,
196        public_key: &'a [u8],
197    },
198    Ds {
199        key_tag: u16,
200        algorithm: u8,
201        digest_type: u8,
202        digest: &'a [u8],
203    },
204    Raw {
205        rtype: DnsType,
206        rdata: &'a [u8],
207    },
208}
209
210#[cfg(test)]
211mod tests {
212    use super::*;
213
214    #[test]
215    fn lossless_chunking_roundtrip_multi_chunk() {
216        // Test with a 38-byte payload (spans 3 chunks: 16 + 16 + 6)
217        let sample_payload = b"qualialabs-lossless-dnskey-payload-12345678";
218        assert_eq!(sample_payload.len(), 43);
219
220        let mut quins = [NQuin::default(); 8];
221        let num_chunks = encode_lossless_rdata_chunks(
222            "node.qualia.net",
223            DnsType::DNSKEY,
224            3600,
225            sample_payload,
226            PermissiveRoutingLane::EnforceBilateralMicroCommons,
227            &mut quins,
228        )
229        .unwrap();
230
231        assert_eq!(num_chunks, 3);
232        for q in &quins[..num_chunks] {
233            assert!(q.verify_ecc_parity());
234            assert_eq!(
235                q.identify_routing_lane(),
236                PermissiveRoutingLane::EnforceBilateralMicroCommons
237            );
238        }
239
240        let mut reassembled = [0u8; 128];
241        let bytes_out =
242            decode_lossless_rdata_chunks(&quins[..num_chunks], DnsType::DNSKEY, &mut reassembled)
243                .unwrap();
244
245        assert_eq!(bytes_out, sample_payload.len());
246        assert_eq!(&reassembled[..bytes_out], sample_payload);
247    }
248
249    #[test]
250    fn lossless_chunking_exact_16_bytes() {
251        // Test boundary condition: exact multiple of CHUNK_CAPACITY (16 bytes)
252        let sample_payload = [0x42u8; 16];
253        let mut quins = [NQuin::default(); 2];
254        let num_chunks = encode_lossless_rdata_chunks(
255            "exact16.qualia.net",
256            DnsType::TXT,
257            300,
258            &sample_payload,
259            PermissiveRoutingLane::PassthroughStandard,
260            &mut quins,
261        )
262        .unwrap();
263
264        assert_eq!(num_chunks, 1);
265        let mut out = [0u8; 32];
266        let n = decode_lossless_rdata_chunks(&quins[..num_chunks], DnsType::TXT, &mut out).unwrap();
267        assert_eq!(n, 16);
268        assert_eq!(&out[..16], &sample_payload);
269    }
270
271    #[test]
272    fn lossless_chunking_parity_tamper_detected() {
273        let sample = b"unaltered-data";
274        let mut quins = [NQuin::default(); 2];
275        let n = encode_lossless_rdata_chunks(
276            "tamper.test",
277            DnsType::TXT,
278            300,
279            sample,
280            PermissiveRoutingLane::PassthroughStandard,
281            &mut quins,
282        )
283        .unwrap();
284
285        // Tamper with object byte
286        quins[0].object ^= 0x01;
287        let mut out = [0u8; 32];
288        assert!(decode_lossless_rdata_chunks(&quins[..n], DnsType::TXT, &mut out).is_err());
289    }
290}