test: add fuzzing (cargo-fuzz targets + stable robustness suite)

libFuzzer targets + a stable 300k-iteration robustness suite; nightly fuzz CI.

Author: ajsb85

.github/workflows/fuzz.yml

@@ -0,0 +1,32 @@
+name: Fuzz
+
+# Short fuzzing bursts on every push to main, plus a longer weekly run. The
+# stable `cargo test` suite (tests/robustness.rs) already smoke-fuzzes the
+# decoders; this runs the libFuzzer targets under the nightly toolchain.
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  fuzz:
+    name: cargo-fuzz ${{ matrix.target }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [decode_total, roundtrip, sentinel]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@nightly
+      - name: Install cargo-fuzz
+        run: cargo install cargo-fuzz --locked
+      - name: Fuzz ${{ matrix.target }}
+        run: |
+          time=$([ "${{ github.event_name }}" = "schedule" ] && echo 300 || echo 60)
+          cargo fuzz run ${{ matrix.target }} -- -max_total_time=$time

Cargo.toml

@@ -12,6 +12,9 @@ documentation = "https://docs.rs/cobs_codec_rs"
 readme = "README.md"
 keywords = ["cobs", "serial", "framing", "no-std", "embedded"]
 categories = ["encoding", "embedded", "no-std"]
+# The fuzz crate is a dev-only nested cargo-fuzz workspace; keep it out of the
+# published crate.
+exclude = ["/fuzz"]
 
 [package.metadata.docs.rs]
 # Document every feature, and load KaTeX so the overhead math renders. KaTeX is

fuzz/.gitignore

@@ -0,0 +1,5 @@
+/target
+/corpus
+/artifacts
+/coverage
+Cargo.lock

fuzz/Cargo.toml

@@ -0,0 +1,39 @@
+[package]
+name = "cobs_codec_rs-fuzz"
+version = "0.0.0"
+publish = false
+edition = "2021"
+
+[package.metadata]
+cargo-fuzz = true
+
+[dependencies]
+libfuzzer-sys = "0.4"
+
+[dependencies.cobs_codec_rs]
+path = ".."
+
+# Detach from the parent crate so `cargo build`/`cargo test` on the library never
+# tries to build the fuzz targets (which require the nightly toolchain).
+[workspace]
+
+[[bin]]
+name = "decode_total"
+path = "fuzz_targets/decode_total.rs"
+test = false
+doc = false
+bench = false
+
+[[bin]]
+name = "roundtrip"
+path = "fuzz_targets/roundtrip.rs"
+test = false
+doc = false
+bench = false
+
+[[bin]]
+name = "sentinel"
+path = "fuzz_targets/sentinel.rs"
+test = false
+doc = false
+bench = false

fuzz/fuzz_targets/decode_total.rs

@@ -0,0 +1,23 @@
+#![no_main]
+//! Decoding arbitrary bytes must never panic, and the slice decoder must agree
+//! with the in-place decoder on both the accept/reject decision and the output.
+
+use cobs_codec_rs::cobs;
+use libfuzzer_sys::fuzz_target;
+
+fuzz_target!(|data: &[u8]| {
+    let mut out = vec![0u8; data.len() + 1];
+    let slice = cobs::decode(data, &mut out);
+
+    let mut buf = data.to_vec();
+    let in_place = cobs::decode_in_place(&mut buf);
+
+    match (slice, in_place) {
+        (Ok(m), Ok(n)) => {
+            assert_eq!(m, n, "length mismatch");
+            assert_eq!(&out[..m], &buf[..n], "byte mismatch");
+        }
+        (Err(_), Err(_)) => {}
+        (a, b) => panic!("slice/in-place disagree: {a:?} vs {b:?}"),
+    }
+});

fuzz/fuzz_targets/roundtrip.rs

@@ -0,0 +1,16 @@
+#![no_main]
+//! Any payload must round-trip through encode -> decode for both COBS and
+//! COBS/R, and the encoding must never contain a `0x00` byte.
+
+use cobs_codec_rs::{cobs, cobsr};
+use libfuzzer_sys::fuzz_target;
+
+fuzz_target!(|data: &[u8]| {
+    let encoded = cobs::encode_to_vec(data);
+    assert!(!encoded.contains(&0), "COBS output contains 0x00");
+    assert_eq!(cobs::decode_to_vec(&encoded).unwrap(), data);
+
+    let encoded = cobsr::encode_to_vec(data);
+    assert!(!encoded.contains(&0), "COBS/R output contains 0x00");
+    assert_eq!(cobsr::decode_to_vec(&encoded).unwrap(), data);
+});

fuzz/fuzz_targets/sentinel.rs

@@ -0,0 +1,22 @@
+#![no_main]
+//! The configurable-sentinel codec must round-trip any payload, and the
+//! encoding must never contain the chosen sentinel byte.
+
+use cobs_codec_rs::cobs;
+use libfuzzer_sys::fuzz_target;
+
+fuzz_target!(|data: &[u8]| {
+    // Use the first byte as the sentinel, the rest as the payload.
+    let Some((&sentinel, payload)) = data.split_first() else {
+        return;
+    };
+
+    let encoded = cobs::encode_to_vec_with_sentinel(payload, sentinel);
+    if sentinel != 0 {
+        assert!(!encoded.contains(&sentinel), "sentinel byte in output");
+    }
+    assert_eq!(
+        cobs::decode_to_vec_with_sentinel(&encoded, sentinel).unwrap(),
+        payload,
+    );
+});

tests/robustness.rs

@@ -0,0 +1,102 @@
+// Robustness / smoke-fuzz suite that runs under plain `cargo test` (no nightly).
+// It hammers the decoders with arbitrary, mostly-malformed input to prove they
+// are *total* (never panic, only Ok/Err) and that the decode variants agree.
+// Deeper coverage lives in `fuzz/` (cargo-fuzz).
+#![allow(clippy::pedantic, missing_docs)]
+
+use cobs_codec_rs::{cobs, cobsr};
+
+/// Tiny deterministic xorshift PRNG (keeps the crate dependency-free).
+struct Rng(u64);
+impl Rng {
+    fn new(seed: u64) -> Self {
+        Self(seed)
+    }
+    fn next(&mut self) -> u64 {
+        let mut x = self.0;
+        x ^= x << 13;
+        x ^= x >> 7;
+        x ^= x << 17;
+        self.0 = x;
+        x
+    }
+    fn byte(&mut self) -> u8 {
+        (self.next() & 0xFF) as u8
+    }
+    // A byte biased toward the values that stress COBS code bytes: 0x00, 0xFF,
+    // and small counts, with the occasional fully-random byte.
+    fn stress_byte(&mut self) -> u8 {
+        match self.next() % 4 {
+            0 => 0x00,
+            1 => 0xFF,
+            2 => (self.next() % 6) as u8,
+            _ => self.byte(),
+        }
+    }
+    fn stress_bytes(&mut self, len: usize) -> Vec<u8> {
+        (0..len).map(|_| self.stress_byte()).collect()
+    }
+}
+
+#[test]
+fn decode_is_total_on_arbitrary_input() {
+    // Arbitrary (mostly invalid) bytes must never panic, and basic-COBS decode
+    // must agree with in-place decode on both the accept/reject decision and the
+    // decoded bytes.
+    let mut rng = Rng::new(0xF0FA_D00D_1111_2222);
+    let mut scratch = vec![0u8; 1024];
+    for _ in 0..200_000 {
+        let len = (rng.next() as usize) % 512;
+        let input = rng.stress_bytes(len);
+
+        // COBS/R decode must also never panic.
+        let _ = cobsr::decode(&input, &mut scratch);
+        // A custom sentinel decode path must never panic either.
+        let s = rng.byte();
+        let _ = cobs::decode_with_sentinel(&input, &mut scratch, s);
+
+        // Slice decode vs in-place decode must always agree.
+        let slice = cobs::decode(&input, &mut scratch);
+        let mut buf = input.clone();
+        let in_place = cobs::decode_in_place(&mut buf);
+        match (slice, in_place) {
+            (Ok(m), Ok(n)) => {
+                assert_eq!(m, n, "length mismatch on {input:02x?}");
+                assert_eq!(&scratch[..m], &buf[..n], "byte mismatch on {input:02x?}");
+            }
+            (Err(_), Err(_)) => {}
+            (a, b) => panic!("slice/in-place disagree on {input:02x?}: {a:?} vs {b:?}"),
+        }
+    }
+}
+
+#[test]
+fn encode_decode_round_trips_arbitrary_payloads() {
+    // Any payload round-trips through encode -> decode for COBS, COBS/R, and the
+    // sentinel variants; the encoding never contains the (sentinel) delimiter.
+    let mut rng = Rng::new(0xC0FF_EE00_3333_4444);
+    let mut enc = vec![0u8; 8192];
+    let mut dec = vec![0u8; 8192];
+    for _ in 0..100_000 {
+        let len = (rng.next() as usize) % 700;
+        let src = rng.stress_bytes(len);
+
+        let n = cobs::encode(&src, &mut enc);
+        assert!(!enc[..n].contains(&0), "COBS output contains 0x00");
+        let m = cobs::decode(&enc[..n], &mut dec).unwrap();
+        assert_eq!(&dec[..m], &src[..]);
+
+        let n = cobsr::encode(&src, &mut enc);
+        assert!(!enc[..n].contains(&0), "COBS/R output contains 0x00");
+        let m = cobsr::decode(&enc[..n], &mut dec).unwrap();
+        assert_eq!(&dec[..m], &src[..]);
+
+        let s = rng.byte();
+        let n = cobs::encode_with_sentinel(&src, &mut enc, s);
+        if s != 0 {
+            assert!(!enc[..n].contains(&s), "sentinel byte {s:#04x} in output");
+        }
+        let m = cobs::decode_with_sentinel(&enc[..n], &mut dec, s).unwrap();
+        assert_eq!(&dec[..m], &src[..]);
+    }
+}