From 556d02941ad3b97b1d109e9c08d4477d647deb1f Mon Sep 17 00:00:00 2001 From: bflatastic Date: Sun, 15 Nov 2026 14:49:24 -0500 Subject: [PATCH] Extract bounded USD Crate LZ4 decoding from TextureCraft Source: storytold/texturecraft bdbb52c9b66b221a55b370105b42f485a76e6fc7. Preserve chunk framing and output cap policy, with fallible allocation and checked offsets. --- Cargo.lock | 14 +++++++ Cargo.toml | 1 + crates/usd/Cargo.toml | 15 +++++++ crates/usd/README.md | 7 ++++ crates/usd/src/lib.rs | 95 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 132 insertions(+) create mode 100644 crates/usd/Cargo.toml create mode 100644 crates/usd/README.md create mode 100644 crates/usd/src/lib.rs diff --git a/Cargo.lock b/Cargo.lock index b3325f790..d1f177658 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2855,6 +2855,14 @@ dependencies = [ "zip", ] +[[package]] +name = "craft-usd" +version = "0.1.0" +dependencies = [ + "lz4_flex", + "thiserror 2.0.21", +] + [[package]] name = "craft-vcard" version = "0.1.0" @@ -6054,6 +6062,12 @@ version = "0.1.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f" +[[package]] +name = "lz4_flex" +version = "0.11.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "373f5eceeeab7925e0c1098212f2fbc4d416adec9d35051a6ab251e824c1854a" + [[package]] name = "maybe-owned" version = "0.3.4" diff --git a/Cargo.toml b/Cargo.toml index 0c9729e00..db3902687 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-usd = { path = "crates/usd" } craft-smime = { path = "crates/smime" } craft-ber = { path = "crates/ber" } craft-proto = { path = "crates/proto" } diff --git a/crates/usd/Cargo.toml b/crates/usd/Cargo.toml new file mode 100644 index 000000000..ac1c64d0c --- /dev/null +++ b/crates/usd/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "craft-usd" +description = "Bounded USD Crate wire primitives, independent of scene and material policy" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +lz4_flex = { version = "0.11", default-features = false, features = ["safe-decode", "safe-encode"] } +thiserror.workspace = true diff --git a/crates/usd/README.md b/crates/usd/README.md new file mode 100644 index 000000000..606b5b250 --- /dev/null +++ b/crates/usd/README.md @@ -0,0 +1,7 @@ +# craft-usd + +Bounded wire primitives for USD Crate, independent of application scene and material models. + +Currently provides Crate-framed LZ4 decompression only: a single unprefixed block or up to 127 length-prefixed blocks, under a caller-provided output-byte cap with fallible output allocation. Trailing bytes after counted chunks retain the original reader's ignored-tail policy. This is not a complete USD reader/writer; scene interpretation, integer packing and export remain outside this first extraction. + +Adapted from TextureCraft `crates/formats/src/mesh_import/usd/codec.rs`, introduced by bflatastic in `bdbb52c9b66b221a55b370105b42f485a76e6fc7`. The LZ4 backend is MIT-licensed `lz4_flex`. diff --git a/crates/usd/src/lib.rs b/crates/usd/src/lib.rs new file mode 100644 index 000000000..943bf1d4d --- /dev/null +++ b/crates/usd/src/lib.rs @@ -0,0 +1,95 @@ +//! Bounded USD Crate wire primitives. Not a complete USD scene reader or writer. +//! +//! The framing decoder is adapted from TextureCraft's `usd/codec.rs`, originally +//! bflatastic, commit bdbb52c9b66b221a55b370105b42f485a76e6fc7. +#![forbid(unsafe_code)] +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +/// Failure to read a bounded Crate LZ4 frame. +#[derive(Debug, thiserror::Error)] +pub enum Error { + /// Invalid or incomplete chunk framing. + #[error("invalid USD Crate LZ4 framing: {0}")] + Framing(&'static str), + /// Invalid compressed data or output exceeding the supplied capacity. + #[error("USD Crate LZ4 data: {0}")] + Lz4(#[from] lz4_flex::block::DecompressError), + /// The bounded output allocation could not be reserved. + #[error("cannot allocate USD Crate LZ4 output")] + Allocation, +} + +/// Decode Crate's chunk-count byte and LZ4 blocks to at most `max_output` bytes. +/// +/// A zero count means a single unprefixed block; 1..=127 means that many blocks, +/// each preceded by a signed little-endian 32-bit length. As in the original reader, +/// bytes following the declared chunks are ignored. The output allocation is fallible +/// and capped by both the caller's budget and the input's maximum LZ4 expansion. +/// This bounds the returned plane, not backend internal scratch memory. +pub fn decompress(input: &[u8], max_output: usize) -> Result, Error> { + let (&chunks, mut rest) = input.split_first().ok_or(Error::Framing("empty block"))?; + if chunks > 127 { + return Err(Error::Framing("chunk count exceeds 127")); + } + let capacity = max_output.min(input.len().saturating_mul(256).saturating_add(64)); + let mut output = Vec::new(); + output.try_reserve_exact(capacity).map_err(|_| Error::Allocation)?; + output.resize(capacity, 0); + let written = if chunks == 0 { + lz4_flex::block::decompress_into(rest, &mut output)? + } else { + let mut total = 0usize; + for _ in 0..chunks { + let length = rest.get(..4).and_then(|b| b.try_into().ok()).map(i32::from_le_bytes).ok_or(Error::Framing("missing chunk length"))?; + let length = usize::try_from(length).map_err(|_| Error::Framing("negative chunk length"))?; + let end = 4usize.checked_add(length).ok_or(Error::Framing("chunk length overflow"))?; + let chunk = rest.get(4..end).ok_or(Error::Framing("truncated chunk"))?; + rest = rest.get(end..).unwrap_or_default(); + let tail = output.get_mut(total..).ok_or(Error::Framing("output offset overflow"))?; + let count = lz4_flex::block::decompress_into(chunk, tail)?; + total = total.checked_add(count).ok_or(Error::Framing("output length overflow"))?; + } + total + }; + output.truncate(written); + Ok(output) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used)] +mod tests { + use super::*; + + #[test] + fn single_block_matches_original_wire() { + for n in [0, 1, 15, 16, 255, 4096] { + let raw: Vec = (0..n).map(|i| (i % 251) as u8).collect(); + let mut frame = vec![0]; + frame.extend(lz4_flex::block::compress(&raw)); + assert_eq!(decompress(&frame, raw.len()).unwrap(), raw); + if n > 0 { + assert!(decompress(&frame, n - 1).is_err()); + } + } + } + + #[test] + fn counted_blocks_and_trailing_bytes_keep_existing_policy() { + let mut frame = vec![2]; + for raw in [b"first".as_slice(), b"second".as_slice()] { + let block = lz4_flex::block::compress(raw); + frame.extend((block.len() as i32).to_le_bytes()); + frame.extend(block); + } + frame.extend(b"ignored"); + assert_eq!(decompress(&frame, 11).unwrap(), b"firstsecond"); + assert!(decompress(&frame, 10).is_err()); + } + + #[test] + fn malformed_frames_fail_within_budget() { + for data in [vec![], vec![128], vec![1], vec![1, 255, 255, 255, 255], vec![1, 5, 0, 0, 0, 1]] { + assert!(decompress(&data, 32).is_err()); + } + } +}