refactor(firmware): centralize configuration and diagnostics

firmware/libs/kaptan-mavlink/src/receiver.rs

@@ -2,58 +2,28 @@
 
 use crate::{MavlinkFrame, message};
 
-/// Bounded MAVLink 2 receiver for a board's serial-byte interrupt.
-///
-/// Boards pass UART bytes to [`Self::receive_byte`] and take complete frames
-/// from [`Self::take_received`]. Production has no signing verifier or replay
-/// state, so it never exposes an inbound MAVLink frame as an authority record.
-pub struct MavlinkReceiver<const N: usize> {
+struct IntegrityFramer {
     frame: MavlinkFrame,
     received: usize,
     expected: usize,
-    frames: [Option<MavlinkFrame>; N],
-    front: usize,
-    length: usize,
 }
 
-impl<const N: usize> Default for MavlinkReceiver<N> {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl<const N: usize> MavlinkReceiver<N> {
-    /// Creates a production receiver with space for `N` complete frames.
-    ///
-    /// TODO(signing): accept a frame only after verified MAVLink-v2 signing,
-    /// configured sender/target binding, persistent anti-replay state, and
-    /// provisioning/rotation policy exist together. A V2 CRC only detects
-    /// corruption; it is not authentication.
-    pub const fn new() -> Self {
+impl IntegrityFramer {
+    const fn new() -> Self {
         Self {
             frame: MavlinkFrame::new(),
             received: 0,
             expected: 0,
-            frames: [None; N],
-            front: 0,
-            length: 0,
         }
     }
 
-    /// Receives one UART byte and returns whether it queued a complete frame.
-    ///
-    /// Bytes outside MAVLink 2 frames and frames with invalid CRCs are
-    /// discarded. Signed frames are also discarded because this receiver has
-    /// no verifier or replay state. Until the TODO(signing) work is complete,
-    /// unsigned frames are deliberately not promoted to received records
-    /// either.
-    pub fn receive_byte(&mut self, byte: u8) -> bool {
+    fn receive_byte(&mut self, byte: u8) -> Option<MavlinkFrame> {
         if self.received == 0 {
             if byte == 0xfd {
                 self.frame.as_mut_slice()[0] = byte;
                 self.received = 1;
             }
-            return false;
+            return None;
         }
 
         self.frame.as_mut_slice()[self.received] = byte;
@@ -61,43 +31,80 @@ impl<const N: usize> MavlinkReceiver<N> {
 
         if self.received == 10 {
             let header = self.frame.as_slice();
-            // MAVLink's bit 0 means the packet carries a signature. Reject all
-            // nonzero incompatibility flags until a reviewed signature verifier
-            // and persistent replay policy exist.
+            // MAVLink incompatibility bit zero adds a signature. This framer
+            // has neither a signing verifier nor persistent replay state, so
+            // every nonzero incompatibility flag is rejected at the header.
             if header[2] != 0 {
                 self.reset();
-                return false;
+                return None;
             }
             self.expected = 1 + 9 + usize::from(header[1]) + 2;
         }
 
-        if self.expected != 0 && self.received == self.expected {
-            let frame = core::mem::replace(&mut self.frame, MavlinkFrame::new());
-            self.received = 0;
-            self.expected = 0;
-            // The production receiver still drops every inbound frame until
-            // signing/replay verification exists. Validate either known
-            // dialect here so a future verifier receives no CRC-corrupt
-            // custom configuration message.
-            if !has_valid_known_crc(&frame) {
-                return false;
-            }
+        if self.expected == 0 || self.received != self.expected {
+            return None;
         }
 
-        false
+        let frame = core::mem::replace(&mut self.frame, MavlinkFrame::new());
+        self.received = 0;
+        self.expected = 0;
+        has_valid_known_crc(&frame).then_some(frame)
     }
 
-    /// Discards the in-progress frame after a UART transport fault.
-    pub fn reset(&mut self) {
+    fn reset(&mut self) {
         self.frame = MavlinkFrame::new();
         self.received = 0;
         self.expected = 0;
     }
+}
 
-    /// Takes the oldest complete received frame, if one is available.
-    ///
-    /// The production receiver returns no frame until signing verification is
-    /// implemented, but retaining this API keeps dispatch ownership explicit.
+/// Bounded integrity-only MAVLink 2 receiver.
+///
+/// It rejects signed, incompatible, corrupt, and MAVLink 1 frames, but an
+/// accepted frame is still unauthenticated. The composition decides whether
+/// and how a received command may be admitted.
+pub struct IntegrityMavlinkReceiver<const N: usize> {
+    framer: IntegrityFramer,
+    frames: [Option<MavlinkFrame>; N],
+    front: usize,
+    length: usize,
+}
+
+impl<const N: usize> IntegrityMavlinkReceiver<N> {
+    /// Creates an empty integrity-only receiver.
+    pub const fn new() -> Self {
+        assert!(N != 0, "integrity receiver capacity must be nonzero");
+        Self {
+            framer: IntegrityFramer::new(),
+            frames: [None; N],
+            front: 0,
+            length: 0,
+        }
+    }
+
+    /// Queues one complete CRC-valid unsigned frame when capacity remains.
+    pub fn receive_byte(&mut self, byte: u8) -> bool {
+        let Some(frame) = self.framer.receive_byte(byte) else {
+            return false;
+        };
+        if self.length == N {
+            return false;
+        }
+        let index = (self.front + self.length) % N;
+        self.frames[index] = Some(frame);
+        self.length += 1;
+        true
+    }
+
+    /// Discards partial framing state and all queued unauthenticated frames.
+    pub fn reset(&mut self) {
+        self.framer.reset();
+        self.frames = [None; N];
+        self.front = 0;
+        self.length = 0;
+    }
+
+    /// Takes the oldest integrity-checked frame.
     pub fn take_received(&mut self) -> Option<MavlinkFrame> {
         if self.length == 0 {
             return None;
@@ -107,10 +114,11 @@ impl<const N: usize> MavlinkReceiver<N> {
         self.length -= 1;
         frame
     }
+}
 
-    /// Returns whether at least one complete frame awaits dispatch.
-    pub const fn has_received(&self) -> bool {
-        self.length != 0
+impl<const N: usize> Default for IntegrityMavlinkReceiver<N> {
+    fn default() -> Self {
+        Self::new()
     }
 }
 
@@ -128,7 +136,7 @@ fn has_valid_known_crc(frame: &MavlinkFrame) -> bool {
 
 #[cfg(test)]
 mod tests {
-    use super::MavlinkReceiver;
+    use super::IntegrityMavlinkReceiver;
     use crate::{MavlinkFrame, message};
 
     fn heartbeat(sequence: u8) -> MavlinkFrame {
@@ -173,7 +181,7 @@ mod tests {
 
     #[test]
     fn discards_a_crc_valid_mavlink_v1_frame() {
-        let mut receiver = MavlinkReceiver::<1>::new();
+        let mut receiver = IntegrityMavlinkReceiver::<1>::new();
         let v1 = heartbeat_v1(3);
         assert_eq!(v1.raw_bytes()[0], 0xfe);
 
@@ -185,26 +193,26 @@ mod tests {
     }
 
     #[test]
-    fn production_rejects_unsigned_frames_without_a_signing_verifier() {
-        let frame = heartbeat(0);
-        let mut receiver = MavlinkReceiver::<1>::new();
+    fn queues_a_complete_crc_valid_unsigned_frame() {
+        let frame = heartbeat(9);
+        let mut receiver = IntegrityMavlinkReceiver::<1>::new();
         for byte in frame.raw_bytes() {
-            assert!(!receiver.receive_byte(*byte));
+            receiver.receive_byte(*byte);
         }
-        assert!(!receiver.has_received());
+        assert_eq!(receiver.take_received(), Some(frame));
         assert_eq!(receiver.take_received(), None);
     }
 
     #[test]
     fn rejects_signed_v2_before_accepting_any_payload() {
-        let mut receiver = MavlinkReceiver::<1>::new();
+        let mut receiver = IntegrityMavlinkReceiver::<1>::new();
         // The first ten bytes contain the complete MAVLink 2 header. This
         // frame advertises a signature (incompatibility bit 0), so rejection
         // happens before its payload can be considered.
         for byte in [0xfd, 0, 1, 0, 0, 1, 1, 0, 0, 0] {
             assert!(!receiver.receive_byte(byte));
         }
-        assert!(!receiver.has_received());
+        assert_eq!(receiver.take_received(), None);
     }
 
     #[test]
@@ -213,11 +221,11 @@ mod tests {
         let mut bytes = frame.into_inner();
         bytes[10] ^= 1;
         let corrupt = MavlinkFrame::from_bytes_unparsed(bytes);
-        let mut receiver = MavlinkReceiver::<1>::new();
+        let mut receiver = IntegrityMavlinkReceiver::<1>::new();
 
         for byte in corrupt.raw_bytes() {
             assert!(!receiver.receive_byte(*byte));
         }
-        assert!(!receiver.has_received());
+        assert_eq!(receiver.take_received(), None);
     }
 }