Add WASM parser and Vue dissector UI.

Ship a working HexPigeon: typed binary parsing in Rust/WASM, a three-pane frontend, and unit tests covering the field types.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-09-03 16:26:52 +00:00
co-authored by Cursor
parent f4b19e87b1
commit 71974f5107
35 changed files with 4719 additions and 0 deletions
+263
View File
@@ -0,0 +1,263 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
[[package]]
name = "bumpalo"
version = "3.20.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
[[package]]
name = "cfg-if"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
[[package]]
name = "crc"
version = "3.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5eb8a2a1cd12ab0d987a5d5e825195d372001a4094a0376319d5a0ad71c1ba0d"
dependencies = [
"crc-catalog",
]
[[package]]
name = "crc-catalog"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "217698eaf96b4a3f0bc4f3662aaa55bdf913cd54d7204591faa790070c6d0853"
[[package]]
name = "futures-core"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
[[package]]
name = "futures-task"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
[[package]]
name = "futures-util"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
dependencies = [
"futures-core",
"futures-task",
"pin-project-lite",
"slab",
]
[[package]]
name = "hex-pigeon-parser"
version = "0.1.0"
dependencies = [
"crc",
"serde",
"serde-wasm-bindgen",
"serde_json",
"wasm-bindgen",
]
[[package]]
name = "itoa"
version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "js-sys"
version = "0.3.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
dependencies = [
"cfg-if",
"futures-util",
"wasm-bindgen",
]
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "once_cell"
version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "pin-project-lite"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
"unicode-ident",
]
[[package]]
name = "quote"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
"proc-macro2",
]
[[package]]
name = "rustversion"
version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
[[package]]
name = "serde"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
name = "serde-wasm-bindgen"
version = "0.6.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8302e169f0eddcc139c70f139d19d6467353af16f9fce27e8c30158036a1e16b"
dependencies = [
"js-sys",
"serde",
"wasm-bindgen",
]
[[package]]
name = "serde_core"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.4",
]
[[package]]
name = "serde_json"
version = "1.0.151"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
dependencies = [
"itoa",
"memchr",
"serde",
"serde_core",
"zmij",
]
[[package]]
name = "slab"
version = "0.4.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
[[package]]
name = "syn"
version = "2.0.119"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "syn"
version = "3.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6275cddf4610d1775e6d1fe9469b2e77d0f39fd98fb7450901b821e0c53649f"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "unicode-ident"
version = "1.0.24"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
[[package]]
name = "wasm-bindgen"
version = "0.2.127"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
dependencies = [
"cfg-if",
"once_cell",
"rustversion",
"wasm-bindgen-macro",
"wasm-bindgen-shared",
]
[[package]]
name = "wasm-bindgen-macro"
version = "0.2.127"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
dependencies = [
"quote",
"wasm-bindgen-macro-support",
]
[[package]]
name = "wasm-bindgen-macro-support"
version = "0.2.127"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
dependencies = [
"bumpalo",
"proc-macro2",
"quote",
"syn 2.0.119",
"wasm-bindgen-shared",
]
[[package]]
name = "wasm-bindgen-shared"
version = "0.2.127"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
dependencies = [
"unicode-ident",
]
[[package]]
name = "zmij"
version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+18
View File
@@ -0,0 +1,18 @@
[package]
name = "hex-pigeon-parser"
version = "0.1.0"
edition = "2021"
[lib]
crate-type = ["cdylib", "rlib"]
[dependencies]
wasm-bindgen = "0.2"
serde = { version = "1.0", features = ["derive"] }
serde-wasm-bindgen = "0.6"
serde_json = "1.0"
crc = "3.2"
[profile.release]
opt-level = "s"
lto = true
+37
View File
@@ -0,0 +1,37 @@
use crc::{Crc, CRC_16_IBM_SDLC, CRC_32_ISO_HDLC};
pub fn compute_crc16(data: &[u8]) -> u16 {
let crc = Crc::<u16>::new(&CRC_16_IBM_SDLC);
crc.checksum(data)
}
pub fn compute_crc32(data: &[u8]) -> u32 {
let crc = Crc::<u32>::new(&CRC_32_ISO_HDLC);
crc.checksum(data)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn crc16_is_deterministic() {
let a = compute_crc16(b"123456789");
let b = compute_crc16(b"123456789");
assert_eq!(a, b);
assert_ne!(a, compute_crc16(b"123456788"));
}
#[test]
fn crc32_is_deterministic() {
let a = compute_crc32(b"123456789");
let b = compute_crc32(b"123456789");
assert_eq!(a, b);
assert_ne!(a, compute_crc32(b"123456788"));
}
#[test]
fn empty_input_has_known_crc32() {
assert_eq!(compute_crc32(&[]), 0x0000_0000);
}
}
+67
View File
@@ -0,0 +1,67 @@
use wasm_bindgen::prelude::*;
mod parser;
mod schema;
pub mod checksum;
pub use parser::*;
pub use schema::*;
/// Entry point: parse `hex_input` against `schema_json`.
/// Returns a JSON string of `ParseResult`.
#[wasm_bindgen]
pub fn parse(hex_input: &str, schema_json: &str) -> Result<JsValue, JsValue> {
let schema: schema::Schema = serde_json::from_str(schema_json)
.map_err(|e| JsValue::from_str(&format!("Schema error: {e}")))?;
let bytes = hex_to_bytes(hex_input)
.map_err(|e| JsValue::from_str(&e))?;
let result = parser::parse_fields(&bytes, &schema.fields)
.map_err(|e| JsValue::from_str(&e))?;
serde_wasm_bindgen::to_value(&result).map_err(|e| JsValue::from_str(&e.to_string()))
}
/// Convert hex string (with optional spaces/newlines) to bytes.
#[wasm_bindgen]
pub fn hex_to_bytes_js(hex: &str) -> Result<Vec<u8>, JsValue> {
hex_to_bytes(hex).map_err(|e| JsValue::from_str(&e))
}
pub fn hex_to_bytes(hex: &str) -> Result<Vec<u8>, String> {
let clean: String = hex.chars().filter(|c| !c.is_whitespace()).collect();
if clean.len() % 2 != 0 {
return Err(format!("Hex string has odd length: {}", clean.len()));
}
(0..clean.len())
.step_by(2)
.map(|i| {
u8::from_str_radix(&clean[i..i + 2], 16)
.map_err(|_| format!("Invalid hex byte at position {i}: '{}'", &clean[i..i + 2]))
})
.collect()
}
#[cfg(test)]
mod tests {
use super::hex_to_bytes;
#[test]
fn hex_to_bytes_accepts_whitespace() {
let bytes = hex_to_bytes("FF 05\n48 65").expect("parse hex");
assert_eq!(bytes, vec![0xFF, 0x05, 0x48, 0x65]);
}
#[test]
fn hex_to_bytes_rejects_odd_length() {
let err = hex_to_bytes("ABC").unwrap_err();
assert!(err.contains("odd length"));
}
#[test]
fn hex_to_bytes_rejects_invalid_digits() {
let err = hex_to_bytes("GG").unwrap_err();
assert!(err.contains("Invalid hex byte"));
}
}
+309
View File
@@ -0,0 +1,309 @@
use std::collections::HashMap;
use serde::{Deserialize, Serialize};
use crate::schema::{CountSpec, Endian, FieldDef, FieldKind};
use crate::checksum::{compute_crc16, compute_crc32};
/// The result of parsing a full frame.
#[derive(Debug, Serialize, Deserialize)]
pub struct ParseResult {
pub fields: Vec<ParsedField>,
pub total_bytes: usize,
pub consumed_bytes: usize,
}
/// A parsed field with its byte span for highlighting.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ParsedField {
pub name: String,
pub kind: String,
/// Byte offset where this field starts.
pub offset: usize,
/// Number of bytes consumed.
pub size: usize,
/// Human-readable value.
pub value: ParsedValue,
pub description: Option<String>,
/// For repeated/compound fields.
pub children: Option<Vec<ParsedField>>,
/// For checksum fields: whether it matches the computed value.
pub checksum_valid: Option<bool>,
}
#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(untagged)]
pub enum ParsedValue {
Uint(u64),
Int(i64),
Float(f64),
Bytes(Vec<u8>),
Str(String),
Flags(Vec<FlagValue>),
None,
}
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct FlagValue {
pub bit: u8,
pub name: String,
pub set: bool,
}
struct Cursor<'a> {
data: &'a [u8],
pos: usize,
}
impl<'a> Cursor<'a> {
fn new(data: &'a [u8]) -> Self {
Self { data, pos: 0 }
}
fn remaining(&self) -> usize {
self.data.len().saturating_sub(self.pos)
}
fn read_bytes(&mut self, n: usize) -> Result<&[u8], String> {
if self.pos + n > self.data.len() {
return Err(format!(
"Not enough bytes at offset {}: need {n}, have {}",
self.pos,
self.remaining()
));
}
let start = self.pos;
self.pos += n;
Ok(&self.data[start..start + n])
}
fn read_u8(&mut self) -> Result<u8, String> {
Ok(self.read_bytes(1)?[0])
}
fn read_u16(&mut self, endian: &Endian) -> Result<u16, String> {
let b = self.read_bytes(2)?;
Ok(match endian {
Endian::Big => u16::from_be_bytes([b[0], b[1]]),
Endian::Little => u16::from_le_bytes([b[0], b[1]]),
})
}
fn read_u32(&mut self, endian: &Endian) -> Result<u32, String> {
let b = self.read_bytes(4)?;
Ok(match endian {
Endian::Big => u32::from_be_bytes([b[0], b[1], b[2], b[3]]),
Endian::Little => u32::from_le_bytes([b[0], b[1], b[2], b[3]]),
})
}
fn read_u64(&mut self, endian: &Endian) -> Result<u64, String> {
let b = self.read_bytes(8)?;
let arr: [u8; 8] = b.try_into().unwrap();
Ok(match endian {
Endian::Big => u64::from_be_bytes(arr),
Endian::Little => u64::from_le_bytes(arr),
})
}
}
pub fn parse_fields(data: &[u8], fields: &[FieldDef]) -> Result<ParseResult, String> {
let mut cursor = Cursor::new(data);
let mut parsed = Vec::new();
// Track named uint fields for dynamic count resolution.
let mut named_uints: HashMap<String, usize> = HashMap::new();
parse_fields_inner(data, &mut cursor, fields, &mut parsed, &mut named_uints)?;
Ok(ParseResult {
fields: parsed,
total_bytes: data.len(),
consumed_bytes: cursor.pos,
})
}
fn parse_fields_inner(
full_data: &[u8],
cursor: &mut Cursor,
fields: &[FieldDef],
out: &mut Vec<ParsedField>,
named_uints: &mut HashMap<String, usize>,
) -> Result<(), String> {
// Default endian if not specified in field.
let global_endian = Endian::Big;
for field in fields {
let endian = field.endian.as_ref().unwrap_or(&global_endian);
let offset = cursor.pos;
let (value, size, children, checksum_valid) = match &field.kind {
FieldKind::Uint8 => {
let v = cursor.read_u8()? as u64;
named_uints.insert(field.name.clone(), v as usize);
(ParsedValue::Uint(v), 1, None, None)
}
FieldKind::Uint16 => {
let v = cursor.read_u16(endian)? as u64;
named_uints.insert(field.name.clone(), v as usize);
(ParsedValue::Uint(v), 2, None, None)
}
FieldKind::Uint32 => {
let v = cursor.read_u32(endian)? as u64;
named_uints.insert(field.name.clone(), v as usize);
(ParsedValue::Uint(v), 4, None, None)
}
FieldKind::Uint64 => {
let v = cursor.read_u64(endian)?;
(ParsedValue::Uint(v), 8, None, None)
}
FieldKind::Int8 => {
let v = cursor.read_u8()? as i8;
(ParsedValue::Int(v as i64), 1, None, None)
}
FieldKind::Int16 => {
let raw = cursor.read_u16(endian)?;
let v = raw as i16;
(ParsedValue::Int(v as i64), 2, None, None)
}
FieldKind::Int32 => {
let raw = cursor.read_u32(endian)?;
let v = raw as i32;
(ParsedValue::Int(v as i64), 4, None, None)
}
FieldKind::Float32 => {
let raw = cursor.read_u32(endian)?;
let v = f32::from_bits(raw) as f64;
(ParsedValue::Float(v), 4, None, None)
}
FieldKind::Float64 => {
let raw = cursor.read_u64(endian)?;
let v = f64::from_bits(raw);
(ParsedValue::Float(v), 8, None, None)
}
FieldKind::Bitflags8 => {
let byte = cursor.read_u8()?;
let flags = resolve_flags(byte as u64, field.flags.as_deref().unwrap_or(&[]));
(ParsedValue::Flags(flags), 1, None, None)
}
FieldKind::Bitflags16 => {
let raw = cursor.read_u16(endian)? as u64;
let flags = resolve_flags(raw, field.flags.as_deref().unwrap_or(&[]));
(ParsedValue::Flags(flags), 2, None, None)
}
FieldKind::Bytes => {
let len = field.length.ok_or_else(|| {
format!("Field '{}': 'bytes' type requires 'length'", field.name)
})?;
let b = cursor.read_bytes(len)?.to_vec();
(ParsedValue::Bytes(b), len, None, None)
}
FieldKind::Padding => {
let len = field.length.unwrap_or(1);
cursor.read_bytes(len)?;
(ParsedValue::None, len, None, None)
}
FieldKind::StringFixed => {
let len = field.length.ok_or_else(|| {
format!("Field '{}': 'string_fixed' requires 'length'", field.name)
})?;
let raw = cursor.read_bytes(len)?.to_vec();
let s = String::from_utf8_lossy(&raw)
.trim_end_matches('\0')
.to_string();
(ParsedValue::Str(s), len, None, None)
}
FieldKind::StringLp8 => {
let len = cursor.read_u8()? as usize;
let raw = cursor.read_bytes(len)?.to_vec();
let s = String::from_utf8_lossy(&raw).into_owned();
(ParsedValue::Str(s), 1 + len, None, None)
}
FieldKind::StringLp16 => {
let len = cursor.read_u16(endian)? as usize;
let raw = cursor.read_bytes(len)?.to_vec();
let s = String::from_utf8_lossy(&raw).into_owned();
(ParsedValue::Str(s), 2 + len, None, None)
}
FieldKind::Crc16 => {
let stored = cursor.read_u16(endian)?;
let valid = if let Some(range) = field.checksum_range {
let slice = full_data
.get(range[0]..range[1])
.ok_or_else(|| format!("CRC range {:?} out of bounds", range))?;
let computed = compute_crc16(slice);
Some(computed == stored)
} else {
None
};
(ParsedValue::Uint(stored as u64), 2, None, valid)
}
FieldKind::Crc32 => {
let stored = cursor.read_u32(endian)?;
let valid = if let Some(range) = field.checksum_range {
let slice = full_data
.get(range[0]..range[1])
.ok_or_else(|| format!("CRC range {:?} out of bounds", range))?;
let computed = compute_crc32(slice);
Some(computed == stored)
} else {
None
};
(ParsedValue::Uint(stored as u64), 4, None, valid)
}
FieldKind::Repeated => {
let inner_fields = field.fields.as_deref().ok_or_else(|| {
format!("Field '{}': 'repeated' requires 'fields'", field.name)
})?;
let count = match field.count.as_ref() {
Some(CountSpec::Fixed(n)) => *n,
Some(CountSpec::Field(name)) => *named_uints
.get(name)
.ok_or_else(|| format!("Count field '{}' not found", name))?,
None => {
return Err(format!(
"Field '{}': 'repeated' requires 'count'",
field.name
))
}
};
let start = cursor.pos;
let mut children_out = Vec::new();
let mut child_named = named_uints.clone();
for _ in 0..count {
let mut iteration = Vec::new();
parse_fields_inner(
full_data,
cursor,
inner_fields,
&mut iteration,
&mut child_named,
)?;
children_out.extend(iteration);
}
let size = cursor.pos - start;
(ParsedValue::None, size, Some(children_out), None)
}
};
out.push(ParsedField {
name: field.name.clone(),
kind: format!("{:?}", field.kind),
offset,
size,
value,
description: field.description.clone(),
children,
checksum_valid,
});
}
Ok(())
}
fn resolve_flags(raw: u64, defs: &[crate::schema::FlagDef]) -> Vec<FlagValue> {
defs.iter()
.map(|f| FlagValue {
bit: f.bit,
name: f.name.clone(),
set: (raw >> f.bit) & 1 == 1,
})
.collect()
}
+110
View File
@@ -0,0 +1,110 @@
use serde::{Deserialize, Serialize};
/// A full schema describing a binary frame layout.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Schema {
/// Human-readable name for this schema.
pub name: Option<String>,
/// Endianness applied globally unless overridden per field.
#[serde(default = "default_endian")]
pub endian: Endian,
/// Ordered list of fields to parse.
pub fields: Vec<FieldDef>,
}
fn default_endian() -> Endian {
Endian::Big
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum Endian {
Big,
Little,
}
/// A single field definition.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FieldDef {
/// Display name.
pub name: String,
/// Field type.
#[serde(rename = "type")]
pub kind: FieldKind,
/// Override global endianness for this field.
pub endian: Option<Endian>,
/// Description / comment shown in the tree.
pub description: Option<String>,
/// For bitflags: the flag definitions.
pub flags: Option<Vec<FlagDef>>,
/// For `bytes` type: number of bytes (required).
/// For `string_lp8` / `string_lp16`: omit (length is read from data).
/// For other types: derived from type width.
pub length: Option<usize>,
/// For `crc16` / `crc32`: byte range to checksum [start, end) relative to frame start.
pub checksum_range: Option<[usize; 2]>,
/// For `repeated`: how many repetitions (constant or from a previously parsed field name).
pub count: Option<CountSpec>,
/// For `repeated`: the inner fields to repeat.
pub fields: Option<Vec<FieldDef>>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum FieldKind {
/// 1 byte unsigned.
Uint8,
/// 2 bytes unsigned.
Uint16,
/// 4 bytes unsigned.
Uint32,
/// 8 bytes unsigned.
Uint64,
/// 1 byte signed.
Int8,
/// 2 bytes signed.
Int16,
/// 4 bytes signed.
Int32,
/// 4 bytes float.
Float32,
/// 8 bytes float.
Float64,
/// 1-byte bitfield with named flags.
Bitflags8,
/// 2-byte bitfield with named flags.
Bitflags16,
/// Raw bytes of `length`.
Bytes,
/// Null-terminated string of `length` bytes.
StringFixed,
/// Pascal-style: 1-byte length prefix, then UTF-8 bytes.
StringLp8,
/// Pascal-style: 2-byte length prefix (respects endian), then UTF-8 bytes.
StringLp16,
/// CRC-16/CCITT checksum (2 bytes).
Crc16,
/// CRC-32 checksum (4 bytes).
Crc32,
/// Repeat inner `fields` `count` times.
Repeated,
/// Skip / padding bytes.
Padding,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlagDef {
/// Bit index (0 = LSB).
pub bit: u8,
pub name: String,
pub description: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum CountSpec {
/// Literal count.
Fixed(usize),
/// Name of a previously parsed uint field holding the count.
Field(String),
}
+297
View File
@@ -0,0 +1,297 @@
use hex_pigeon_parser::checksum::{compute_crc16, compute_crc32};
use hex_pigeon_parser::{
parse_fields, CountSpec, Endian, FieldDef, FieldKind, FlagDef, ParsedValue, Schema,
};
fn field(name: &str, kind: FieldKind) -> FieldDef {
FieldDef {
name: name.to_string(),
kind,
endian: None,
description: None,
flags: None,
length: None,
checksum_range: None,
count: None,
fields: None,
}
}
fn field_len(name: &str, kind: FieldKind, length: usize) -> FieldDef {
let mut f = field(name, kind);
f.length = Some(length);
f
}
#[test]
fn schema_deserializes_from_json() {
let json = r#"{
"name": "Test",
"endian": "little",
"fields": [{ "name": "id", "type": "uint8" }]
}"#;
let schema: Schema = serde_json::from_str(json).expect("schema JSON");
assert_eq!(schema.name.as_deref(), Some("Test"));
assert_eq!(schema.endian, Endian::Little);
assert_eq!(schema.fields.len(), 1);
assert_eq!(schema.fields[0].kind, FieldKind::Uint8);
}
#[test]
fn parses_integer_types_big_endian() {
let data = [
0x12,
0x12, 0x34,
0x12, 0x34, 0x56, 0x78,
0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0,
0xFE,
0xFF, 0xF0,
0x80, 0x00, 0x00, 0x01,
];
let fields = vec![
field("u8", FieldKind::Uint8),
field("u16", FieldKind::Uint16),
field("u32", FieldKind::Uint32),
field("u64", FieldKind::Uint64),
field("i8", FieldKind::Int8),
field("i16", FieldKind::Int16),
field("i32", FieldKind::Int32),
];
let result = parse_fields(&data, &fields).expect("parse");
assert_eq!(result.consumed_bytes, 22);
assert!(matches!(result.fields[0].value, ParsedValue::Uint(0x12)));
assert!(matches!(result.fields[1].value, ParsedValue::Uint(0x1234)));
assert!(matches!(result.fields[2].value, ParsedValue::Uint(0x12345678)));
assert!(matches!(result.fields[3].value, ParsedValue::Uint(0x123456789ABCDEF0)));
assert!(matches!(result.fields[4].value, ParsedValue::Int(-2)));
assert!(matches!(result.fields[5].value, ParsedValue::Int(-16)));
assert!(matches!(result.fields[6].value, ParsedValue::Int(-2147483647)));
}
#[test]
fn parses_integer_types_little_endian() {
let data = [0x34, 0x12];
let mut f = field("u16", FieldKind::Uint16);
f.endian = Some(Endian::Little);
let result = parse_fields(&data, &[f]).expect("parse");
assert!(matches!(result.fields[0].value, ParsedValue::Uint(0x1234)));
}
#[test]
fn parses_float_types() {
let f32_bits = 1.0f32.to_bits();
let f64_bits = 2.5f64.to_bits();
let mut data = Vec::new();
data.extend_from_slice(&f32_bits.to_be_bytes());
data.extend_from_slice(&f64_bits.to_be_bytes());
let fields = vec![field("f32", FieldKind::Float32), field("f64", FieldKind::Float64)];
let result = parse_fields(&data, &fields).expect("parse");
match &result.fields[0].value {
ParsedValue::Float(v) => assert!((v - 1.0).abs() < f64::EPSILON),
other => panic!("expected float32, got {other:?}"),
}
match &result.fields[1].value {
ParsedValue::Float(v) => assert!((v - 2.5).abs() < f64::EPSILON),
other => panic!("expected float64, got {other:?}"),
}
}
#[test]
fn parses_bitflags() {
let mut f8 = field("flags8", FieldKind::Bitflags8);
f8.flags = Some(vec![
FlagDef {
bit: 0,
name: "A".into(),
description: None,
},
FlagDef {
bit: 3,
name: "D".into(),
description: None,
},
]);
let mut f16 = field("flags16", FieldKind::Bitflags16);
f16.flags = Some(vec![FlagDef {
bit: 1,
name: "B".into(),
description: None,
}]);
let result = parse_fields(&[0b0000_0101, 0x00, 0b0000_0010], &[f8, f16]).expect("parse");
match &result.fields[0].value {
ParsedValue::Flags(flags) => {
assert!(flags.iter().find(|f| f.name == "A").unwrap().set);
assert!(!flags.iter().find(|f| f.name == "D").unwrap().set);
}
other => panic!("expected flags8, got {other:?}"),
}
match &result.fields[1].value {
ParsedValue::Flags(flags) => assert!(flags[0].set),
other => panic!("expected flags16, got {other:?}"),
}
}
#[test]
fn parses_bytes_padding_and_strings() {
let data = [
0xAA, 0xBB, 0xCC, // bytes[3]
0x00, 0x00, // padding[2]
b'H', b'i', 0x00, 0x00, // string_fixed[4] -> "Hi"
0x03, b'F', b'O', b'O', // string_lp8
0x00, 0x02, b'B', b'R', // string_lp16 big-endian length
];
let fields = vec![
field_len("raw", FieldKind::Bytes, 3),
field_len("pad", FieldKind::Padding, 2),
field_len("fixed", FieldKind::StringFixed, 4),
field("lp8", FieldKind::StringLp8),
field("lp16", FieldKind::StringLp16),
];
let result = parse_fields(&data, &fields).expect("parse");
assert!(matches!(&result.fields[0].value, ParsedValue::Bytes(v) if v == &[0xAA, 0xBB, 0xCC]));
assert!(matches!(result.fields[1].value, ParsedValue::None));
assert!(matches!(&result.fields[2].value, ParsedValue::Str(s) if s == "Hi"));
assert!(matches!(&result.fields[3].value, ParsedValue::Str(s) if s == "FOO"));
assert!(matches!(&result.fields[4].value, ParsedValue::Str(s) if s == "BR"));
}
#[test]
fn validates_crc16_and_crc32() {
let payload = [0x01, 0x02, 0x03, 0x04];
let crc16 = compute_crc16(&payload);
let crc32 = compute_crc32(&payload);
let mut data = payload.to_vec();
data.extend_from_slice(&crc16.to_be_bytes());
data.extend_from_slice(&crc32.to_be_bytes());
let mut crc16_field = field("c16", FieldKind::Crc16);
crc16_field.checksum_range = Some([0, 4]);
let mut crc32_field = field("c32", FieldKind::Crc32);
crc32_field.checksum_range = Some([0, 4]);
let fields = vec![
field_len("payload", FieldKind::Bytes, 4),
crc16_field,
crc32_field,
];
let result = parse_fields(&data, &fields).expect("parse");
assert_eq!(result.fields[1].checksum_valid, Some(true));
assert_eq!(result.fields[2].checksum_valid, Some(true));
let mut bad = data.clone();
bad[6] ^= 0xFF;
let mut crc32_bad = field("c32", FieldKind::Crc32);
crc32_bad.checksum_range = Some([0, 4]);
let fields = vec![
field_len("payload", FieldKind::Bytes, 4),
crc32_bad,
];
let result = parse_fields(&bad, &fields).expect("parse");
assert_eq!(result.fields[1].checksum_valid, Some(false));
}
#[test]
fn parses_repeated_fixed_and_dynamic_count() {
let data = [0x02, 0x10, 0x20, 0x11, 0x21];
let repeated_fixed = FieldDef {
name: "items".into(),
kind: FieldKind::Repeated,
endian: None,
description: None,
flags: None,
length: None,
checksum_range: None,
count: Some(CountSpec::Fixed(2)),
fields: Some(vec![field("val", FieldKind::Uint8)]),
};
let result = parse_fields(&[0x10, 0x20, 0x11, 0x21], &[repeated_fixed]).expect("parse");
let children = result.fields[0].children.as_ref().expect("children");
assert_eq!(children.len(), 2);
assert!(matches!(children[0].value, ParsedValue::Uint(0x10)));
assert!(matches!(children[1].value, ParsedValue::Uint(0x20)));
let repeated_dynamic = FieldDef {
name: "list".into(),
kind: FieldKind::Repeated,
endian: None,
description: None,
flags: None,
length: None,
checksum_range: None,
count: Some(CountSpec::Field("count".into())),
fields: Some(vec![field("val", FieldKind::Uint8)]),
};
let result = parse_fields(&data, &[field("count", FieldKind::Uint8), repeated_dynamic]).expect("parse");
let children = result.fields[1].children.as_ref().expect("children");
assert_eq!(children.len(), 2);
}
#[test]
fn errors_on_truncated_buffer() {
let result = parse_fields(&[0x01], &[field("u16", FieldKind::Uint16)]);
assert!(result.is_err());
assert!(result.unwrap_err().contains("Not enough bytes"));
}
#[test]
fn errors_on_missing_required_field_options() {
let err = parse_fields(&[0x01], &[field("raw", FieldKind::Bytes)]).unwrap_err();
assert!(err.contains("requires 'length'"));
let repeated = FieldDef {
name: "r".into(),
kind: FieldKind::Repeated,
endian: None,
description: None,
flags: None,
length: None,
checksum_range: None,
count: Some(CountSpec::Fixed(1)),
fields: None,
};
let err = parse_fields(&[0x01], &[repeated]).unwrap_err();
assert!(err.contains("requires 'fields'"));
}
#[test]
fn parses_example_protocol_frame() {
let header = [
0xFF, 0x05, b'H', b'e', b'l', b'l', b'o', 0x00, 0x01, 0x02, 0x03, b'A', b'B', b'C',
b'D',
];
let crc32 = compute_crc32(&header[..11]);
let mut data = header.to_vec();
data.extend_from_slice(&crc32.to_be_bytes());
data.extend_from_slice(&[0x00, 0x03]); // flags: ACK + SYN
let schema_json = include_str!("../../frontend/src/fixtures/example-schema.json");
let schema: Schema = serde_json::from_str(schema_json).expect("example schema");
let result = parse_fields(&data, &schema.fields).expect("example frame");
assert_eq!(result.total_bytes, data.len());
assert_eq!(result.consumed_bytes, data.len());
assert_eq!(result.fields.len(), 7);
assert!(matches!(result.fields[0].value, ParsedValue::Uint(0xFF)));
assert!(matches!(&result.fields[2].value, ParsedValue::Str(s) if s == "Hello"));
assert!(matches!(&result.fields[4].value, ParsedValue::Str(s) if s == "ABCD"));
assert_eq!(result.fields[5].checksum_valid, Some(true));
match &result.fields[6].value {
ParsedValue::Flags(flags) => {
assert!(flags.iter().find(|f| f.name == "ACK").unwrap().set);
assert!(flags.iter().find(|f| f.name == "SYN").unwrap().set);
assert!(!flags.iter().find(|f| f.name == "FIN").unwrap().set);
}
other => panic!("expected flags, got {other:?}"),
}
}