Zero-Copy Data Processing

Zero-copy data processing parses binary network packets or structured text records by borrowing slices (&'a [u8], &'a str) directly from the caller's input buffer without allocating intermediate String or Vec<u8> copies on the heap. Lifetimes (PacketFrame<'a>, LogView<'a>) statically guarantee that no parsed view outlives the backing byte buffer.

Zero-Copy Borrowing Layout

Backing Input Buffer: `&'a [u8]` (owned once on stack or in reusable I/O ring)
+--------+--------+------------+------------------------------------+--------+
| Magic  | Ver/Fl | PayloadLen | Payload Bytes (UTF-8 / Binary)     | CRC16  |
| 2 B    | 2 B    | 4 B (BE)   | N bytes                            | 2 B    |
+--------+--------+------------+------------------------------------+--------+
                               ^                                    ^
                               |--- PacketView<'a>::payload: &'a [u8] ---|
                                    (Zero heap allocations per frame!)

Complete Zero-Copy Binary Frame and CSV Record Parser

use std::borrow::Cow;

#[derive(Debug, PartialEq, Eq)]
pub struct TelemetryFrame<'a> {
    pub version: u8,
    pub flags: u8,
    pub sensor_id: &'a str,
    pub payload: &'a [u8],
    pub checksum: u16,
}

#[derive(Debug, PartialEq, Eq)]
pub enum FrameError {
    UnexpectedEof,
    BadMagic,
    InvalidUtf8,
    ChecksumMismatch { expected: u16, actual: u16 },
}

pub fn crc16_ccitt(bytes: &[u8]) -> u16 {
    let mut crc: u16 = 0xFFFF;
    for &b in bytes {
        crc ^= (b as u16) << 8;
        for _ in 0..8 {
            if (crc & 0x8000) != 0 {
                crc = (crc << 1) ^ 0x1021;
            } else {
                crc <<= 1;
            }
        }
    }
    crc
}

pub struct FrameStream<'a> {
    remaining: &'a [u8],
}

impl<'a> FrameStream<'a> {
    pub fn new(buffer: &'a [u8]) -> Self {
        Self { remaining: buffer }
    }

    pub fn parse_next(&mut self) -> Option<Result<TelemetryFrame<'a>, FrameError>> {
        if self.remaining.is_empty() {
            return None;
        }
        // Header layout:
        // [0..2]: Magic 0x52, 0x53 ("RS")
        // [2]:    version (u8)
        // [3]:    flags (u8)
        // [4]:    sensor_id_len (u8)
        // [5..7]: payload_len (u16 big-endian)
        if self.remaining.len() < 7 {
            self.remaining = &[];
            return Some(Err(FrameError::UnexpectedEof));
        }
        if &self.remaining[0..2] != b"RS" {
            self.remaining = &[];
            return Some(Err(FrameError::BadMagic));
        }

        let version = self.remaining[2];
        let flags = self.remaining[3];
        let id_len = self.remaining[4] as usize;
        let payload_len = u16::from_be_bytes([self.remaining[5], self.remaining[6]]) as usize;

        let total_frame_len = 7 + id_len + payload_len + 2;
        if self.remaining.len() < total_frame_len {
            self.remaining = &[];
            return Some(Err(FrameError::UnexpectedEof));
        }

        let frame_bytes = &self.remaining[..total_frame_len];
        self.remaining = &self.remaining[total_frame_len..];

        let body_end = 7 + id_len + payload_len;
        let expected_crc = crc16_ccitt(&frame_bytes[..body_end]);
        let actual_crc = u16::from_be_bytes([frame_bytes[body_end], frame_bytes[body_end + 1]]);
        if expected_crc != actual_crc {
            return Some(Err(FrameError::ChecksumMismatch {
                expected: expected_crc,
                actual: actual_crc,
            }));
        }

        let Ok(sensor_id) = std::str::from_utf8(&frame_bytes[7..7 + id_len]) else {
            return Some(Err(FrameError::InvalidUtf8));
        };
        let payload = &frame_bytes[7 + id_len..body_end];

        Some(Ok(TelemetryFrame {
            version,
            flags,
            sensor_id,
            payload,
            checksum: actual_crc,
        }))
    }
}

impl<'a> Iterator for FrameStream<'a> {
    type Item = Result<TelemetryFrame<'a>, FrameError>;

    fn next(&mut self) -> Option<Self::Item> {
        self.parse_next()
    }
}

pub fn encode_frame(out: &mut Vec<u8>, version: u8, flags: u8, sensor_id: &str, payload: &[u8]) {
    let start = out.len();
    out.extend_from_slice(b"RS");
    out.push(version);
    out.push(flags);
    out.push(sensor_id.len() as u8);
    out.extend_from_slice(&(payload.len() as u16).to_be_bytes());
    out.extend_from_slice(sensor_id.as_bytes());
    out.extend_from_slice(payload);
    let crc = crc16_ccitt(&out[start..]);
    out.extend_from_slice(&crc.to_be_bytes());
}

/// Zero-copy unescaping with `Cow<'a, str>`: borrows the input slice directly
/// when no escape sequence is present, and allocates a `String` only when needed.
pub fn unescape_field<'a>(raw: &'a str) -> Cow<'a, str> {
    if !raw.contains('\\') {
        Cow::Borrowed(raw)
    } else {
        Cow::Owned(raw.replace("\\n", "\n").replace("\\t", "\t"))
    }
}

fn main() {
    let mut wire_buffer = Vec::new();
    encode_frame(&mut wire_buffer, 1, 0b01, "turbine-north-01", &[0x00, 0xFA, 0x12]);
    encode_frame(&mut wire_buffer, 1, 0b11, "turbine-south-04", &[0x01, 0x20, 0x99, 0xFF]);

    println!("Wire buffer size: {} bytes", wire_buffer.len());
    for frame_res in FrameStream::new(&wire_buffer) {
        let frame = frame_res.unwrap();
        println!(
            "Parsed frame (zero-copy): id='{}', v={}, flags=0b{:02b}, payload={:02X?}, crc=0x{:04X}",
            frame.sensor_id, frame.version, frame.flags, frame.payload, frame.checksum
        );
    }

    let fast_field = unescape_field("normal_identifier_value");
    let escaped_field = unescape_field("line1\\nline2");
    println!(
        "fast_field borrowed? {}, escaped_field borrowed? {}",
        matches!(fast_field, Cow::Borrowed(_)),
        matches!(escaped_field, Cow::Borrowed(_))
    );
}

Wire buffer size: 57 bytes
Parsed frame (zero-copy): id='turbine-north-01', v=1, flags=0b01, payload=[00, FA, 12], crc=0x6A22
Parsed frame (zero-copy): id='turbine-south-04', v=1, flags=0b11, payload=[01, 20, 99, FF], crc=0x4F27
fast_field borrowed? true, escaped_field borrowed? false