Skip to main content

qualia_core_db/net/qdnf/harness/
oracle.rs

1//! Independent header parser. Does not call the production encoder or decoder.
2
3use crate::net::qdnf::errors::QdnfError;
4
5/// Minimum bytes needed to read magic, type and hop_limit (wire table ยง2).
6const MAGIC_LEN: usize = 4;
7const HOP_OFFSET: usize = 12;
8const TYPE_OFFSET: usize = 5;
9const HEADER_LEN_OFFSET: usize = 8;
10const PAYLOAD_LEN_OFFSET: usize = 10;
11const BASE_HEADER_BYTES: usize = 80;
12
13/// Oracle view of the QFrame base header.
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub struct OracleHeader {
16    pub magic_ok: bool,
17    pub version: u8,
18    pub frame_type: u8,
19    pub header_len: u16,
20    pub payload_len: u16,
21    pub hop_limit: u8,
22}
23
24/// Independent magic check. Does not call `decode_frame`.
25#[inline]
26pub fn independent_magic_ok(src: &[u8]) -> bool {
27    src.len() >= MAGIC_LEN && src[0] == b'Q' && src[1] == b'D' && src[2] == b'N' && src[3] == b'F'
28}
29
30/// Wire-table link-only type codes (not forwarded). Independent of `FrameType`.
31#[inline]
32const fn link_only_type(frame_type: u8) -> bool {
33    matches!(frame_type, 1 | 2 | 3 | 4)
34}
35
36/// Independent hop_limit check. Does not call `decode_frame`.
37pub fn independent_hop_limit(src: &[u8]) -> Result<u8, QdnfError> {
38    if src.len() <= HOP_OFFSET {
39        return Err(QdnfError::Truncated);
40    }
41    if !independent_magic_ok(src) {
42        return Err(QdnfError::Malformed);
43    }
44    let hop = src[HOP_OFFSET];
45    if link_only_type(src[TYPE_OFFSET]) && hop != 0 {
46        return Err(QdnfError::HopLimit);
47    }
48    Ok(hop)
49}
50
51/// Byte-at-a-time parse used as an independent check of golden vectors.
52pub fn independent_decode_header(src: &[u8]) -> Result<OracleHeader, QdnfError> {
53    if src.len() < BASE_HEADER_BYTES {
54        return Err(QdnfError::Truncated);
55    }
56    let magic_ok = independent_magic_ok(src);
57    if !magic_ok {
58        return Err(QdnfError::Malformed);
59    }
60    let hop_limit = independent_hop_limit(src)?;
61    let header_len = ((src[HEADER_LEN_OFFSET] as u16) << 8) | src[HEADER_LEN_OFFSET + 1] as u16;
62    let payload_len = ((src[PAYLOAD_LEN_OFFSET] as u16) << 8) | src[PAYLOAD_LEN_OFFSET + 1] as u16;
63    Ok(OracleHeader {
64        magic_ok,
65        version: src[4],
66        frame_type: src[TYPE_OFFSET],
67        header_len,
68        payload_len,
69        hop_limit,
70    })
71}
72
73#[cfg(test)]
74mod tests {
75    use super::*;
76    use crate::net::qdnf::frame::{encode_frame, FrameHeader};
77    use crate::net::qdnf::registries::{FrameType, NextProtocol};
78
79    fn hand_header(frame_type: u8, hop: u8) -> [u8; BASE_HEADER_BYTES] {
80        let mut src = [0u8; BASE_HEADER_BYTES];
81        src[0] = b'Q';
82        src[1] = b'D';
83        src[2] = b'N';
84        src[3] = b'F';
85        src[4] = 1;
86        src[5] = frame_type;
87        src[8] = 0;
88        src[9] = 80;
89        src[12] = hop;
90        src
91    }
92
93    #[test]
94    fn oracle_matches_encoder_lengths() {
95        let mut header = FrameHeader::new(FrameType::LinkChallenge, NextProtocol::QLink);
96        header.payload_len = 3;
97        let mut wire = [0u8; 128];
98        let n = encode_frame(&header, &[1, 2, 3], &mut wire).unwrap();
99        let oracle = independent_decode_header(&wire[..n]).unwrap();
100        assert_eq!(oracle.version, 1);
101        assert_eq!(oracle.frame_type, FrameType::LinkChallenge as u8);
102        assert_eq!(oracle.payload_len, 3);
103        assert_eq!(oracle.header_len, 80);
104        assert_eq!(oracle.hop_limit, 0);
105        assert!(oracle.magic_ok);
106    }
107
108    #[test]
109    fn magic_reject_does_not_call_decode_frame() {
110        let mut src = hand_header(1, 0);
111        src[0] = b'X';
112        assert!(!independent_magic_ok(&src));
113        assert_eq!(independent_hop_limit(&src), Err(QdnfError::Malformed));
114        assert_eq!(independent_decode_header(&src), Err(QdnfError::Malformed));
115    }
116
117    #[test]
118    fn hop_limit_rejects_link_only_nonzero() {
119        let src = hand_header(2, 16);
120        assert!(independent_magic_ok(&src));
121        assert_eq!(independent_hop_limit(&src), Err(QdnfError::HopLimit));
122    }
123
124    #[test]
125    fn hop_limit_allows_forwarded_nonzero() {
126        let src = hand_header(64, 16);
127        assert_eq!(independent_hop_limit(&src), Ok(16));
128        let oracle = independent_decode_header(&src).unwrap();
129        assert_eq!(oracle.hop_limit, 16);
130        assert_eq!(oracle.frame_type, 64);
131    }
132
133    #[test]
134    fn hop_limit_truncated() {
135        assert_eq!(
136            independent_hop_limit(&[b'Q', b'D', b'N']),
137            Err(QdnfError::Truncated)
138        );
139    }
140}