diff --git a/Cargo.toml b/Cargo.toml index d6900e31..f1c1a760 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -43,3 +43,16 @@ codegen-units = 1 # the compiler crate alone exceed it. [profile.dev.package."*"] debug = false + +# The client's native codec is exercised on multi-MiB frames in `cargo test`; +# unoptimized it costs minutes of the acceptance budget. +[profile.dev.package.uorc] +opt-level = 3 + +# The exported reference code is what the differential tests run; unoptimized +# it is ~6x slower than at opt-level 1, which costs more than it compiles. +[profile.dev.package.uorc_compress] +opt-level = 1 + +[profile.dev.package.uorc_decompress] +opt-level = 1 diff --git a/crates/uorc-wasm/src/lib.rs b/crates/uorc-wasm/src/lib.rs index 015489a3..5b577b75 100644 --- a/crates/uorc-wasm/src/lib.rs +++ b/crates/uorc-wasm/src/lib.rs @@ -3,6 +3,11 @@ //! The page asks for an input buffer of a given size, writes the bytes into //! wasm memory at the returned offset, calls an operation, then reads the //! result back through `output_ptr`/`output_len`. +//! +//! Large files stream through the frame operations: the page slices the file +//! into [`frame_size`] pieces (or, to decompress, into the archives that +//! [`frame_length`] delimits) and converts one at a time, so wasm memory stays +//! bounded by one frame whatever the file size. use std::cell::RefCell; @@ -79,13 +84,57 @@ pub extern "C" fn decompress() -> i32 { finish(INPUT.with(|input| uorc::decompress(&input.borrow(), uorc::DEFAULT_DECODE_WORK))) } -/// Read the input archive's frame header and integrity seal without decoding; -/// the output is the description as JSON. +/// Compress the input buffer as a single frame (at most [`frame_size`] bytes). +#[no_mangle] +pub extern "C" fn compress_frame(steps: u64) -> i32 { + finish(INPUT.with(|input| uorc::compress_frame(&input.borrow(), steps))) +} + +/// Decompress the input buffer as a single archive. +#[no_mangle] +pub extern "C" fn decompress_frame() -> i32 { + finish(INPUT.with(|input| uorc::decompress_frame(&input.borrow(), uorc::DEFAULT_DECODE_WORK))) +} + +/// Input bytes per frame. +#[no_mangle] +pub extern "C" fn frame_size() -> usize { + uorc::FRAME +} + +/// Bytes of header the page should read before a first [`frame_length`]. +#[no_mangle] +pub extern "C" fn header_size() -> usize { + uorc::HEADER_HINT +} + +/// Total length of the archive whose first bytes are in the input buffer; +/// -2 when more bytes are needed to see its header, -1 when they are not a +/// UORC archive header. +#[no_mangle] +pub extern "C" fn frame_length() -> f64 { + INPUT.with(|input| match uorc::frame_length(&input.borrow()) { + Ok(Some(n)) => n as f64, + Ok(None) => -2.0, + Err(_) => -1.0, + }) +} + +/// Read the frame header and integrity seal of every archive in the input +/// stream without decoding; the output is a JSON array of descriptions. #[no_mangle] pub extern "C" fn inspect() -> i32 { - finish( - INPUT.with(|input| uorc::inspect(&input.borrow()).map(|info| info.to_json().into_bytes())), - ) + finish(INPUT.with(|input| { + let input = input.borrow(); + let all = uorc::frames(&input)? + .into_iter() + .map(|a| uorc::inspect(a).map(|info| info.to_json())) + .collect::, _>>()?; + if all.is_empty() { + return Err(uorc::Error::Decode); + } + Ok(format!("[{}]", all.join(",")).into_bytes()) + })) } /// Decode the input (one archive or several back to back) in memory and check diff --git a/crates/uorc/src/archive.rs b/crates/uorc/src/archive.rs new file mode 100644 index 00000000..a6e63e7e --- /dev/null +++ b/crates/uorc/src/archive.rs @@ -0,0 +1,303 @@ +//! Native UORC archive framing: the wire header, the UORC-SHA256-CHAIN-v1 +//! seal, and the two archive shapes the client writes, mirroring +//! `Uorc.Codec.Archive` (client/src/Uorc/Codec/Archive.lex.tex) byte for byte. +//! +//! An archive is `preimage || seal(preimage)` where the preimage is +//! `"UORC" 02 01 scope kind count lengths.. bodyLength [basis32] body`, every +//! number a shortest ULEB128. Because the body length is in the header, an +//! archive is self-delimiting, so a stream of archives laid end to end needs no +//! container: [`crate::frame_length`] finds where each one ends. + +use sha2::{Digest, Sha256}; + +const PREFIX_HEX: &str = include_str!("kernel-prefix.hex"); +const SUFFIX_HEX: &str = include_str!("kernel-suffix.hex"); +const PREFIX: [u8; hex_len(PREFIX_HEX)] = hex_literal(PREFIX_HEX); +const SUFFIX: [u8; hex_len(SUFFIX_HEX)] = hex_literal(SUFFIX_HEX); +/// The ulz decoder kernel program (`Archive.kernelPrefix`), before the payload length. +pub const KERNEL_PREFIX: &[u8] = &PREFIX; +/// The ulz decoder kernel program (`Archive.kernelSuffix`), after the payload. +pub const KERNEL_SUFFIX: &[u8] = &SUFFIX; + +const CHAIN_TAG: &[u8] = b"UORC-SHA256-CHAIN-v1\0"; +const MAGIC: &[u8] = b"UORC\x02\x01"; +const MAGIC_SELF_CONTAINED: &[u8] = b"UORC\x02\x01\x00"; +/// Length of the integrity seal at the end of every archive. +pub const SEAL: usize = 32; + +const fn hex_value(c: u8) -> u8 { + match c { + b'0'..=b'9' => c - b'0', + b'a'..=b'f' => c - b'a' + 10, + _ => panic!("kernel hex"), + } +} + +const fn hex_len(text: &str) -> usize { + let b = text.as_bytes(); + let mut n = 0; + let mut i = 0; + while i < b.len() { + if b[i] != b'\n' { + n += 1; + } + i += 1; + } + n / 2 +} + +const fn hex_literal(text: &str) -> [u8; N] { + let b = text.as_bytes(); + let mut out = [0u8; N]; + let (mut i, mut k) = (0, 0); + while i < b.len() { + if b[i] == b'\n' { + i += 1; + continue; + } + out[k] = hex_value(b[i]) * 16 + hex_value(b[i + 1]); + k += 1; + i += 2; + } + assert!(k == N, "kernel hex length"); + out +} + +pub(crate) fn push_uleb(out: &mut Vec, mut n: u64) { + while n >= 0x80 { + out.push((n as u8 & 0x7F) | 0x80); + n >>= 7; + } + out.push(n as u8); +} + +/// Length of the shortest ULEB128 encoding of `n`. +pub fn uleb_len(mut n: u64) -> usize { + let mut len = 1; + while n >= 0x80 { + n >>= 7; + len += 1; + } + len +} + +/// Read a ULEB128 number at `at`: the value and the offset after it. +pub(crate) fn read_uleb(data: &[u8], mut at: usize) -> Option<(u64, usize)> { + let mut value = 0u64; + for shift in (0..64).step_by(7) { + let byte = *data.get(at)?; + at += 1; + let part = u64::from(byte & 0x7F); + if shift == 63 && part > 1 { + return None; + } + value |= part << shift; + if byte < 0x80 { + return Some((value, at)); + } + } + None +} + +/// The UORC-SHA256-CHAIN-v1 digest of `preimage`. +pub fn chain(preimage: &[u8]) -> [u8; 32] { + let mut c: [u8; 32] = Sha256::new() + .chain_update(CHAIN_TAG) + .chain_update([0u8]) + .finalize() + .into(); + let mut blocks = preimage.chunks_exact(64); + for block in &mut blocks { + c = Sha256::new() + .chain_update(CHAIN_TAG) + .chain_update([1u8]) + .chain_update(c) + .chain_update(block) + .finalize() + .into(); + } + let tail = blocks.remainder(); + Sha256::new() + .chain_update(CHAIN_TAG) + .chain_update([2u8]) + .chain_update(c) + .chain_update([tail.len() as u8]) + .chain_update(tail) + .finalize() + .into() +} + +fn sealed(mut preimage: Vec) -> Vec { + let digest = chain(&preimage); + preimage.extend_from_slice(&digest); + preimage +} + +fn header(kind: u8, lengths: &[u64], body_len: u64) -> Vec { + let mut out = Vec::with_capacity(16 + 2 * lengths.len()); + out.extend_from_slice(MAGIC); + out.push(0); + out.push(kind); + push_uleb(&mut out, lengths.len() as u64); + for &n in lengths { + push_uleb(&mut out, n); + } + push_uleb(&mut out, body_len); + out +} + +/// `Archive.rawArchive input`: the input stored raw, as one object. +pub fn raw_archive(input: &[u8]) -> Vec { + raw_objects(input, &[input.len() as u64]) +} + +/// The raw archive of `input` split into objects of `lengths` (which must sum +/// to its length); with one length this is [`raw_archive`]. +pub fn raw_objects(input: &[u8], lengths: &[u64]) -> Vec { + let mut pre = header(0, lengths, input.len() as u64); + pre.reserve(input.len() + SEAL); + pre.extend_from_slice(input); + sealed(pre) +} + +/// Exact length of [`raw_objects`] for objects of `lengths`. +pub fn raw_length(lengths: &[u64]) -> u64 { + let n: u64 = lengths.iter().sum(); + let fields: u64 = lengths.iter().map(|&l| uleb_len(l) as u64).sum(); + 8 + uleb_len(lengths.len() as u64) as u64 + fields + uleb_len(n) as u64 + n + SEAL as u64 +} + +/// `Archive.programArchive n payload`: the ulz kernel graph with `payload` as +/// its sequence constant, reconstructing objects of `lengths` (one object of +/// `n` bytes in the model; several when the client relabels its output). +pub fn program_archive(lengths: &[u64], payload: &[u8]) -> Vec { + let p = payload.len() as u64; + let body_len = KERNEL_PREFIX.len() as u64 + uleb_len(p) as u64 + p + KERNEL_SUFFIX.len() as u64; + let mut pre = header(1, lengths, body_len); + pre.reserve(body_len as usize + SEAL); + pre.extend_from_slice(KERNEL_PREFIX); + push_uleb(&mut pre, p); + pre.extend_from_slice(payload); + pre.extend_from_slice(KERNEL_SUFFIX); + sealed(pre) +} + +/// `Archive.fastDecode`, natively: the output of an archive this client wrote +/// (raw, or ulz kernel with a payload the native decoder vouches for), sealed +/// and laid out exactly as the client writes it, with any object lengths. `None` sends the archive to +/// the exported reference decoder. +pub fn fast_decode(data: &[u8]) -> Option> { + if data.len() < 8 + SEAL || data[..7] != MAGIC_SELF_CONTAINED[..] || data[7] > 1 { + return None; + } + let (count, mut at) = read_uleb(data, 8)?; + // Each length takes a byte, which bounds the allocation. + if count > data.len() as u64 { + return None; + } + let mut lengths = Vec::with_capacity(count as usize); + for _ in 0..count { + let (n, next) = read_uleb(data, at)?; + lengths.push(n); + at = next; + } + let n = lengths.iter().try_fold(0u64, |a, &l| a.checked_add(l))?; + let (body_len, at) = read_uleb(data, at)?; + let body_len = usize::try_from(body_len).ok()?; + if data.len() != at.checked_add(body_len)?.checked_add(SEAL)? { + return None; + } + let (pre, seal) = data.split_at(data.len() - SEAL); + // The header must be the shortest encoding the client writes. + if pre[..at] != header(data[7], &lengths, body_len as u64)[..] || seal != chain(pre) { + return None; + } + let body = &pre[at..]; + if data[7] == 0 { + return (n == body_len as u64).then(|| body.to_vec()); + } + let rest = body.strip_prefix(KERNEL_PREFIX)?; + let (p, after) = read_uleb(rest, 0)?; + let p = usize::try_from(p).ok()?; + if after != uleb_len(p as u64) || rest.len() != after.checked_add(p)? + KERNEL_SUFFIX.len() { + return None; + } + let (payload, suffix) = rest[after..].split_at(p); + if suffix != KERNEL_SUFFIX { + return None; + } + crate::ulz::decode(payload, n) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn raw_archive_is_the_model_layout() { + let a = raw_archive(b"abc"); + assert_eq!(a.len() as u64, raw_length(&[3])); + assert_eq!(&a[..14], b"UORC\x02\x01\x00\x00\x01\x03\x03abc"); + assert_eq!(crate::frame_length(&a), Ok(Some(a.len()))); + assert_eq!(fast_decode(&a).as_deref(), Some(&b"abc"[..])); + } + + #[test] + fn program_archive_round_trips() { + let input = b"abcabcabcabcabcabcabcabc".repeat(40); + let a = program_archive(&[input.len() as u64], &crate::ulz::encode(&input)); + assert_eq!(crate::frame_length(&a), Ok(Some(a.len()))); + assert_eq!(fast_decode(&a), Some(input)); + } + + #[test] + fn object_lengths_are_relabels() { + let input = b"abcabcabcabcabcabcabcabc".repeat(40); + let payload = crate::ulz::encode(&input); + let lengths = [0, 100, 0, input.len() as u64 - 100]; + for (one, many) in [ + (raw_archive(&input), raw_objects(&input, &lengths)), + ( + program_archive(&[input.len() as u64], &payload), + program_archive(&lengths, &payload), + ), + ] { + assert_eq!( + many, + crate::frame::relabel(&one, &lengths).expect("relabel") + ); + assert_eq!(fast_decode(&many).as_ref(), Some(&input)); + } + assert_eq!( + raw_objects(&input, &lengths).len() as u64, + raw_length(&lengths) + ); + } + + #[test] + fn seal_is_checked() { + let mut a = raw_archive(b"hello"); + let last = a.len() - 1; + a[last] ^= 1; + assert_eq!(fast_decode(&a), None); + } + + /// The kernel bytes here are the ones the codec source defines. + #[test] + fn kernel_is_the_model_kernel() { + let source = include_str!("../../../client/src/Uorc/Codec/Archive.lex.tex"); + for (name, bytes) in [ + ("kernelPrefix", KERNEL_PREFIX), + ("kernelSuffix", KERNEL_SUFFIX), + ] { + let text = source + .split(&format!("name: {name},")) + .nth(1) + .and_then(|d| d.split("body: 0x").nth(1)) + .expect(name); + let hex: String = text.chars().take_while(char::is_ascii_hexdigit).collect(); + let expected: String = bytes.iter().map(|b| format!("{b:02x}")).collect(); + assert_eq!(hex.to_ascii_lowercase(), expected, "{name}"); + } + } +} diff --git a/crates/uorc/src/bin/uorc.rs b/crates/uorc/src/bin/uorc.rs index 96376e4b..56a0dc10 100644 --- a/crates/uorc/src/bin/uorc.rs +++ b/crates/uorc/src/bin/uorc.rs @@ -1,22 +1,24 @@ //! `uorc`: the command-line client. use std::fs::{self, File, OpenOptions}; -use std::io::{self, Read, Write}; +use std::io::{self, BufReader, BufWriter, Read, Write}; use std::path::{Path, PathBuf}; use std::process::ExitCode; use std::time::Instant; const USAGE: &str = "usage: - uorc compress [--steps N] [--force] [--stats] [-o ] + uorc compress [--steps N] [--threads N] [--force] [--stats] [-o ] uorc compress [--steps N] [--force] [--stats] ... -o - uorc decompress [--work N] [--force|--resume] [--stats] [-o ] + uorc decompress [--work N] [--threads N] [--force|--resume] [--stats] [-o ] uorc inspect [--json] uorc verify [--work N] [--json] [original] uorc --version Compress writes the smaller of the ulz kernel archive and the raw archive; --steps N also runs the program search for N steps and keeps the smallest. -Without -o, compress writes .uorc and decompress strips a .uorc suffix +Input of any size streams through 8 MiB frames, --threads N at a time +(default: every core); each frame is one self-contained archive, written +back to back. Without -o, compress writes .uorc and decompress strips a .uorc suffix (or writes .out). '-' reads stdin or writes stdout. Given a directory or several paths, compress stores them as one archive of @@ -84,6 +86,7 @@ struct Options { force: bool, resume: bool, json: bool, + threads: Option, paths: Vec, output: Option, } @@ -105,6 +108,16 @@ fn parse(mut args: impl Iterator) -> Result { .map_err(|_| usage(format!("{arg}: not a number: {value}")))?, ); } + "--threads" => { + let value = args + .next() + .ok_or_else(|| usage("--threads needs a number"))?; + options.threads = Some( + value + .parse::() + .map_err(|_| usage(format!("--threads: not a number: {value}")))?, + ); + } "--stats" => options.stats = true, "--force" | "-f" => options.force = true, "--json" => options.json = true, @@ -159,11 +172,19 @@ impl Pending { } unreachable!("the attempt loop returns") } +} + +impl Write for Pending { + fn write(&mut self, bytes: &[u8]) -> io::Result { + self.file.as_mut().expect("open").write(bytes) + } - fn write_all(&mut self, bytes: &[u8]) -> io::Result<()> { - self.file.as_mut().expect("open").write_all(bytes) + fn flush(&mut self) -> io::Result<()> { + self.file.as_mut().expect("open").flush() } +} +impl Pending { /// Flush to disk and move into place: atomically, and without replacing /// an existing `dest` unless `force`. fn commit(mut self, dest: &Path, force: bool) -> io::Result<()> { @@ -388,6 +409,61 @@ fn restore( Ok(written) } +fn open_input(path: &str) -> Result, Failure> { + Ok(if path == "-" { + Box::new(io::stdin().lock()) + } else { + Box::new(BufReader::with_capacity( + 1 << 20, + File::open(path).map_err(|e| io_failure(path, e))?, + )) + }) +} + +/// Read enough of a stream to see its first archive header, and whether that +/// archive holds several objects (a tree). The bytes read are handed back in +/// front of the rest of the stream. +fn peek_tree(mut input: Box) -> io::Result<(bool, Box)> { + let mut prefix = Vec::new(); + let mut want = uorc::HEADER_HINT; + loop { + (&mut input) + .take((want - prefix.len()) as u64) + .read_to_end(&mut prefix)?; + match uorc::frame_length(&prefix) { + Ok(None) if prefix.len() == want => want *= 2, + _ => break, + } + } + let tree = uorc::object_lengths(&prefix).is_ok_and(|lengths| lengths.len() != 1); + Ok((tree, Box::new(io::Cursor::new(prefix).chain(input)))) +} + +fn decompress_tree(options: &Options, mut input: Box, path: &str) -> Result<(), Failure> { + if path == "-" { + return Err(usage( + "a multi-object archive restores to a directory; give -o ", + )); + } + let mut stream = Vec::new(); + input + .read_to_end(&mut stream) + .map_err(|e| io_failure(&options.paths[0], e))?; + let started = Instant::now(); + let entries = + uorc::decompress_tree(&stream, options.budget.unwrap_or(uorc::DEFAULT_DECODE_WORK))?; + let written = restore(&entries, Path::new(path), options)?; + if options.stats { + eprintln!( + "{{\"command\":\"decompress\",\"entries\":{},\"written\":{written},\"input_bytes\":{},\"seconds\":{:.6}}}", + entries.len(), + stream.len(), + started.elapsed().as_secs_f64() + ); + } + Ok(()) +} + fn transform(options: &Options) -> Result<(), Failure> { let compress = options.command == "compress"; if compress && is_tree_request(options) { @@ -402,43 +478,51 @@ fn transform(options: &Options) -> Result<(), Failure> { .strip_suffix(".uorc") .map_or_else(|| format!("{input_path}.out"), str::to_owned), }; - let input = read(input_path)?; - if !compress && uorc::inspect(&input).is_ok_and(|info| info.object_lengths.len() != 1) { - if path == "-" { - return Err(usage( - "a multi-object archive restores to a directory; give -o ", - )); - } - let started = Instant::now(); - let entries = - uorc::decompress_tree(&input, options.budget.unwrap_or(uorc::DEFAULT_DECODE_WORK))?; - let written = restore(&entries, Path::new(&path), options)?; - if options.stats { - eprintln!( - "{{\"command\":\"decompress\",\"entries\":{},\"written\":{written},\"input_bytes\":{},\"seconds\":{:.6}}}", - entries.len(), - input.len(), - started.elapsed().as_secs_f64() - ); + let mut input = open_input(input_path)?; + if !compress { + let (tree, rest) = peek_tree(input).map_err(|e| io_failure(input_path, e))?; + if tree { + return decompress_tree(options, rest, &path); } - return Ok(()); + input = rest; } check_free(&path, options.force)?; + let threads = options.threads.unwrap_or_else(uorc::default_threads); + let run = |output: &mut dyn Write| { + if compress { + let steps = options.budget.unwrap_or(uorc::DEFAULT_STEPS); + uorc::compress_stream(input, output, steps, threads) + } else { + let work = options.budget.unwrap_or(uorc::DEFAULT_DECODE_WORK); + uorc::decompress_stream(input, output, work, threads) + } + }; + let failed = |e: io::Error| match uorc::Error::of(&e) { + Some(error) => Failure::from(error), + None => io_failure(&format!("{input_path} -> {path}"), e), + }; let started = Instant::now(); - let output = if compress { - uorc::compress(&input, options.budget.unwrap_or(uorc::DEFAULT_STEPS))? + let totals = if path == "-" { + run(&mut BufWriter::with_capacity(1 << 20, io::stdout().lock())).map_err(failed)? } else { - uorc::decompress(&input, options.budget.unwrap_or(uorc::DEFAULT_DECODE_WORK))? + let dest = Path::new(&path); + let mut pending = Pending::create(dest).map_err(|e| io_failure(&path, e))?; + let mut output = BufWriter::with_capacity(1 << 20, &mut pending); + let totals = run(&mut output).map_err(failed)?; + drop(output); + pending + .commit(dest, options.force) + .map_err(|e| io_failure(&path, e))?; + totals }; - let elapsed = started.elapsed(); - write(&path, &output, options.force)?; if options.stats { eprintln!( - "{{\"command\":\"{}\",\"input_bytes\":{},\"output_bytes\":{},\"seconds\":{:.6}}}", + "{{\"command\":\"{}\",\"input_bytes\":{},\"output_bytes\":{},\"frames\":{},\"seconds\":{:.6}}}", options.command, - input.len(), - output.len(), - elapsed.as_secs_f64() + totals.read, + totals.written, + totals.frames, + started.elapsed().as_secs_f64() ); } Ok(()) diff --git a/crates/uorc/src/frame.rs b/crates/uorc/src/frame.rs index 78b8468e..e9dd765c 100644 --- a/crates/uorc/src/frame.rs +++ b/crates/uorc/src/frame.rs @@ -13,16 +13,13 @@ //! //! Numbers are shortest-form ULEB128. A raw body's length equals the sum of //! the object lengths. This module only reads that framing; the body is -//! decoded and checked by the certified decoder in [`crate::decompress`]. - -use sha2::{Digest, Sha256}; +//! decoded and checked in [`crate::decompress_frame`]. +use crate::archive::{chain, push_uleb, KERNEL_PREFIX, SEAL as DIGEST_LEN}; use crate::Error; const MAGIC: &[u8; 4] = b"UORC"; -const DIGEST_LEN: usize = 32; const BASIS_LEN: usize = 32; -const CHAIN_TAG: &[u8] = b"UORC-SHA256-CHAIN-v1\0"; /// How an archive's body produces its output. #[derive(Debug, Clone, Copy, PartialEq, Eq)] @@ -113,18 +110,34 @@ fn hex(bytes: &[u8]) -> String { struct Reader<'a> { data: &'a [u8], at: usize, + /// Set when a read ran past the end of `data`: more bytes might parse. + short: bool, } impl<'a> Reader<'a> { + fn new(data: &'a [u8]) -> Self { + Reader { + data, + at: 0, + short: false, + } + } + fn byte(&mut self) -> Result { - let b = *self.data.get(self.at).ok_or(Error::Decode)?; + let Some(&b) = self.data.get(self.at) else { + self.short = true; + return Err(Error::Decode); + }; self.at += 1; Ok(b) } fn take(&mut self, n: usize) -> Result<&'a [u8], Error> { let end = self.at.checked_add(n).ok_or(Error::Decode)?; - let s = self.data.get(self.at..end).ok_or(Error::Decode)?; + let Some(s) = self.data.get(self.at..end) else { + self.short = true; + return Err(Error::Decode); + }; self.at = end; Ok(s) } @@ -150,59 +163,6 @@ impl<'a> Reader<'a> { } } -/// The ulz kernel graph's bytes before its payload length, taken from the -/// codec source so this check follows any regeneration of the kernel. -fn kernel_prefix() -> &'static [u8] { - use std::sync::OnceLock; - static PREFIX: OnceLock> = OnceLock::new(); - PREFIX.get_or_init(|| { - let source = include_str!("../../../client/src/Uorc/Codec/Archive.lex.tex"); - let def = source - .split("name: kernelPrefix,") - .nth(1) - .expect("kernelPrefix in Archive.lex.tex"); - let text = def - .split("body: 0x") - .nth(1) - .expect("kernelPrefix body") - .split(|c: char| !c.is_ascii_hexdigit()) - .next() - .expect("hex literal"); - (0..text.len()) - .step_by(2) - .map(|i| u8::from_str_radix(&text[i..i + 2], 16).expect("hex")) - .collect() - }) -} - -/// The UORC-SHA256-CHAIN-v1 digest of `preimage`. -pub(crate) fn chain_digest(preimage: &[u8]) -> [u8; DIGEST_LEN] { - let mut c: [u8; DIGEST_LEN] = Sha256::new() - .chain_update(CHAIN_TAG) - .chain_update([0u8]) - .finalize() - .into(); - let mut blocks = preimage.chunks_exact(64); - for block in &mut blocks { - c = Sha256::new() - .chain_update(CHAIN_TAG) - .chain_update([1u8]) - .chain_update(c) - .chain_update(block) - .finalize() - .into(); - } - let tail = blocks.remainder(); - Sha256::new() - .chain_update(CHAIN_TAG) - .chain_update([2u8]) - .chain_update(c) - .chain_update([tail.len() as u8]) - .chain_update(tail) - .finalize() - .into() -} - /// Where an archive's fields sit, from [`parse`]. pub(crate) struct Layout { /// Offset of the body-length field (just after the object lengths). @@ -213,9 +173,19 @@ pub(crate) struct Layout { end: usize, } -/// Parse one archive at the start of `data`, which may continue past it. -fn parse(data: &[u8]) -> Result<(Info, Layout), Error> { - let mut r = Reader { data, at: 0 }; +/// An archive header: everything before the body. +struct Head { + format: u8, + profile: u8, + program: bool, + basis: Option<[u8; BASIS_LEN]>, + object_lengths: Vec, + output_len: u64, + body_len_at: usize, + body_len: u64, +} + +fn head(r: &mut Reader<'_>) -> Result { if r.take(4)? != MAGIC { return Err(Error::Decode); } @@ -233,7 +203,8 @@ fn parse(data: &[u8]) -> Result<(Info, Layout), Error> { }; let count = r.uleb()?; // Each length takes at least one byte, which bounds the allocation. - if count > data.len() as u64 { + if count > (r.data.len() - r.at) as u64 { + r.short = true; return Err(Error::Decode); } let mut object_lengths = Vec::with_capacity(count as usize); @@ -253,39 +224,79 @@ fn parse(data: &[u8]) -> Result<(Info, Layout), Error> { } else { None }; - let body = r.take(usize::try_from(body_len).map_err(|_| Error::Decode)?)?; + Ok(Head { + format, + profile, + program, + basis, + object_lengths, + output_len, + body_len_at, + body_len, + }) +} + +/// Total length of the archive that starts at `data[0]`, read from its header +/// alone: `Ok(None)` when `data` ends before the header does. +pub fn frame_length(data: &[u8]) -> Result, Error> { + let mut r = Reader::new(data); + match head(&mut r) { + Ok(h) => usize::try_from(h.body_len) + .ok() + .and_then(|b| r.at.checked_add(b)?.checked_add(DIGEST_LEN)) + .map(Some) + .ok_or(Error::Decode), + Err(_) if r.short => Ok(None), + Err(e) => Err(e), + } +} + +/// Bytes of header worth reading before a first [`frame_length`] attempt: a +/// one-object header always fits. +pub const HEADER_HINT: usize = 8 + 10 * 3; + +/// Parse one archive at the start of `data`, which may continue past it. +fn parse(data: &[u8]) -> Result<(Info, Layout), Error> { + let mut r = Reader::new(data); + let h = head(&mut r)?; + let body = r.take(usize::try_from(h.body_len).map_err(|_| Error::Decode)?)?; let sealed = r.at; let digest: [u8; DIGEST_LEN] = r.take(DIGEST_LEN)?.try_into().expect("32 bytes"); let end = r.at; - let representation = if !program { + let representation = if !h.program { Representation::Raw - } else if body.starts_with(kernel_prefix()) { + } else if body.starts_with(KERNEL_PREFIX) { Representation::UlzKernel } else { Representation::Program }; let info = Info { - format, - profile, - basis, + format: h.format, + profile: h.profile, + basis: h.basis, representation, - object_lengths, - output_len, - body_len, + object_lengths: h.object_lengths, + output_len: h.output_len, + body_len: h.body_len, archive_len: end as u64, digest, - integrity_ok: chain_digest(&data[..sealed]) == digest, + integrity_ok: chain(&data[..sealed]) == digest, }; Ok(( info, Layout { - body_len_at, + body_len_at: h.body_len_at, sealed, end, }, )) } +/// The object lengths an archive's header declares, from the header alone. +pub fn object_lengths(archive: &[u8]) -> Result, Error> { + Ok(head(&mut Reader::new(archive))?.object_lengths) +} + /// Read one archive's frame header and check its integrity seal, without /// decoding. The bytes must be exactly one archive. pub fn inspect(archive: &[u8]) -> Result { @@ -302,8 +313,10 @@ pub fn frames(stream: &[u8]) -> Result, Error> { let mut out = Vec::new(); let mut rest = stream; while !rest.is_empty() { - let (_, layout) = parse(rest)?; - let (frame, tail) = rest.split_at(layout.end); + let end = frame_length(rest)? + .filter(|&end| end <= rest.len()) + .ok_or(Error::Decode)?; + let (frame, tail) = rest.split_at(end); out.push(frame); rest = tail; } @@ -329,19 +342,7 @@ pub(crate) fn relabel(archive: &[u8], lengths: &[u64]) -> Result, Error> push_uleb(&mut out, n); } out.extend_from_slice(&archive[layout.body_len_at..layout.sealed]); - let digest = chain_digest(&out); + let digest = chain(&out); out.extend_from_slice(&digest); Ok(out) } - -fn push_uleb(out: &mut Vec, mut n: u64) { - loop { - let byte = (n & 0x7f) as u8; - n >>= 7; - if n == 0 { - out.push(byte); - return; - } - out.push(byte | 0x80); - } -} diff --git a/crates/uorc/src/kernel-prefix.hex b/crates/uorc/src/kernel-prefix.hex new file mode 100644 index 00000000..5d9a43c6 --- /dev/null +++ b/crates/uorc/src/kernel-prefix.hex @@ -0,0 +1,52 @@ +340400000400000600800206010404030620050114010404010103040000000200002502010102040301050004000000 +040b0001050201050107000806010204080a0e080200ff010902011301210e0501010404000000040125010401030302 +010102000000031001022201020305040101020400000400808080808080400401022004011401010300040304040080 +808080808040040104190305210502010102040000030000000225010207020403010304000004020002250104060303 +020101020400000300000004250102090204030103040000040200042501040803030201010204000003000000082501 +020b0204030103040000040200082501040a030302010102000404100008230202020100002304020401008002060102 +2303030704010004230402020106050123080204090402012303030605010001040d01230103030f0101010404070000 +230502020100808080081002010001220201052501070100010204000424000206010200800104020123080206010080 +080b020100002306020a0100042306020c01008010070401060107100401230b0207022202030122030a04230b020801 +230b02080d0020070201041001071103230b021201220b03012305031c130a2305030112090b0317230703021a010001 +221118011301004b21050102230101010102000404130000230702020100042307020401000207040110030123060308 +070222020803230c02060123060303080100502305020201060901000122090f01040301230403070601230201010103 +000400040b0048230a02030104030123020205010002060104004b2004011401040401230903070a010103040000040a +00010048230a03050102250401010105230b02010300010d01070503010060230603060102010300040004140048230c +02030100582308020501005023080207010407052304020901004b2002011401000206010b040103230b03070e010605 +0c040b01230703030d0106070f2307030211010103040000040a00010048230c03050102005800012308030302010050 +0000230803030201250a0101010b0102040004090010230a020301008080400401021305210702010001040601230903 +030801010104000b0010230b0202010028230b0204010001040201231202050100808040040102200a01140101040004 +00000420000705010500482310020601004a200801140100010f02010e0a080901030404010080020602010410010401 +0c04120d220902012308021501004b20020114010002060114040103230f030717010f05101613010000220216011301 +21061b01010200040432002020020114010010230d02050100000f02010001231402040100808040040102200c011401 +2207080107010e00800606010200480401020028230d021501100111230201172202011200012310031a080100071019 +01220117151301004a21060102000825010201020f0a2311020111008002231402020123030204010004102501000a10 +27010003231402290100062314022b012205030122082a011301210c31010103000400040a0002040201000323070305 +02010060230e02020100000401020068230d030601020103000400040a001204020100032308030502010060230f0202 +0100080401020068230e030601020103000400040a002204020100082309030502010060231002020100100401020068 +230f030601020103000400040d0001040201230d020401004b20020114010f0106150100002202090125010802010b22 +050b0325010201010d01020400040c230e020201004b200201140100000f020100012202010325010804010915042201 +040625010301010c01050004000000040900c832040102050105230a0307010500502313020201040701007023120305 +01020105000400000004100004050301000000502313030801022504010f00231402010300bb33230b03030108001006 +0104040c0123140204090402010070231303070102010204000422000310020122010302004006020100c83004010200 +06230e030a0201006023150202010004100201007023140306010400020706010001231c020201080904040501000022 +0a01040d0301150c000e10100116030122010b0725010f0203130b06101405150122010f0b2501040103170f0a010200 +040402230b0101230c020201010200040409001023170202010018231702040110030100010000220302012501090100 +01020004041e00cb33230602020100682318020201230302030100702318020201002823180204010030231802060100 +38231802080100402317030a0102231703010405231703010708231703010a0b002020020114010007100201000a2202 +03011301210908010002041901250103010001020004041100ed37230702020100682319020201002020040114010007 +1002010008000b220302011301210c09010002040c01250103020001020004040c00202002011401230f010423100205 +0100071004010009000b22030201130121070b0101020004040c0028231b0202010030231b0204010038231b02060100 +40231b020801231a03090805231a030107080001250102020001020004040d0028231c0202010030231c020401003823 +1c0206010040231c020801231b03090803231b03010708231b030106070001250102030001020004040e0028231d0202 +010030231d0204010038231d0206010040231d020801231c03090801231c03010708231c03010607231c030105060001 +25010204000102000404020001250102050001020004041100202002011401003c040102231b020601004b2002011401 +00010f020115010000220204012501090500220506032501020100010200040411002020020114010030040102231c02 +0601004b200201140100010f020115010000220204012501090400220506032501020300010200040411002020020114 +010024040102231d020601004b200201140100010f020115010000220204012501090600220506032501020100010200 +040411002020020114010018040102231e020601004b200201140100010f020115010000220204012501090300220506 +03250102010001020004041100202002011401000c040102231f020601004b200201140100010f020115010000220204 +012501090b0022050603250102010001020004040f002020020114012320020401004b200201140100010f0201150100 +002202040125010917002205060325010201000102000404090010232502020100182325020401100301000100002203 +02012501090100010300000400060080020601030007050106232c020501040401010200040103008080400401032003 +010100032903 diff --git a/crates/uorc/src/kernel-suffix.hex b/crates/uorc/src/kernel-suffix.hex new file mode 100644 index 00000000..b9916466 --- /dev/null +++ b/crates/uorc/src/kernel-suffix.hex @@ -0,0 +1,3 @@ +180101001f012503012d01040000000825010202010300000080020601020009232e020801040301060501000a232e02 +0c01040301060901000b232e021001040301060d01000c232e021401040301000000ffffffff0f232903180201000423 +2903020105000d232703021a01001823270302011b0001041d0125010303000010232802020124010101030133 diff --git a/crates/uorc/src/lib.rs b/crates/uorc/src/lib.rs index 816321af..0447bd7e 100644 --- a/crates/uorc/src/lib.rs +++ b/crates/uorc/src/lib.rs @@ -1,22 +1,47 @@ //! The uorc client library. //! -//! Every operation here is the certified Rust that `lexlean production build` -//! exports from `client/src/Uorc/Client.lex.tex` (see `scripts/client-export.mjs`). -//! This crate only moves bytes across that boundary and names its failures. +//! A uorc stream is a sequence of standard self-contained UORC archives laid +//! end to end, one per frame of at most [`FRAME`] input bytes. Each archive is +//! self-delimiting, so a stream needs no container, and a one-frame stream is +//! exactly the archive the LexLean model (`client/src/Uorc/Client.lex.tex`) +//! writes for that input. +//! +//! Frames are compressed and decompressed in parallel and independently, so +//! memory is bounded by the frame size and the worker count, never by the input. +//! +//! The hot paths are native Rust ports of the model: the ulz codec +//! ([`ulz`]), the archive layout and the UORC-SHA256-CHAIN-v1 seal +//! ([`archive`]). They write byte-identical archives, and the decoder only +//! accepts what it can vouch for. Everything else (archives the native path +//! declines, and the program search behind `steps > 0`) runs the certified +//! Rust that `lexlean production build` exports from the model +//! (`generated/rust/uorc_{compress,decompress}`, see `scripts/client-export.mjs`). +//! +//! Ordered objects (and so file trees, see [`tree`]) are the same stream: each +//! frame's header lists the pieces of objects it holds, and the first piece of +//! every frame after the first continues the last object of the frame before +//! (an object that ends exactly at a frame boundary is continued by an empty +//! piece). A plain byte stream is the one-object case. use std::fmt; +use std::io::{self, Read, Write}; +pub mod archive; mod frame; pub mod tree; +pub mod ulz; -pub use frame::{frames, inspect, Info, Representation}; +pub use frame::{frame_length, frames, inspect, object_lengths, Info, Representation, HEADER_HINT}; + +/// Input bytes per frame. Each frame becomes one self-contained archive. +pub const FRAME: usize = 8 << 20; /// Search steps spent by [`compress`] when the caller names no budget. With /// none, compress takes the smaller of the ulz kernel archive and the raw one; /// a positive budget also runs the program search and keeps the smallest. pub const DEFAULT_STEPS: u64 = 0; -/// Decoder work allowed by [`decompress`]; decoding stops on its own when done. +/// Decoder work allowed per archive the reference decoder reconstructs. pub const DEFAULT_DECODE_WORK: u64 = 1 << 40; /// A failed client operation. @@ -26,7 +51,7 @@ pub enum Error { Budget, /// A 64-bit natural-number operation in the exported code overflowed. Overflow, - /// The bytes are not a self-contained UORC archive this client decodes. + /// The bytes are not a stream of self-contained UORC archives this client decodes. Decode, /// The archive decodes, but not to the original it was checked against. Mismatch, @@ -37,7 +62,7 @@ impl fmt::Display for Error { f.write_str(match self { Error::Budget => "no checked archive was found within the step budget", Error::Overflow => "a natural-number operation overflowed 64 bits", - Error::Decode => "input is not a decodable self-contained UORC archive", + Error::Decode => "input is not a decodable stream of self-contained UORC archives", Error::Mismatch => "the archive does not decode to the given original", }) } @@ -45,39 +70,82 @@ impl fmt::Display for Error { impl std::error::Error for Error {} -/// Stack reserved for the exported code on native targets. It recurses -/// structurally over archives and byte ropes, so depth grows with the input; -/// the reservation is virtual and only the pages actually touched are committed. +impl From for io::Error { + fn from(e: Error) -> Self { + io::Error::new(io::ErrorKind::InvalidData, e) + } +} + +impl Error { + /// The client error an I/O error from a streaming operation carries, if any. + pub fn of(error: &io::Error) -> Option { + error.get_ref()?.downcast_ref::().copied() + } +} + +/// Stack reserved for the exported reference code, which recurses structurally +/// over archives and byte ropes. Only the pages actually touched are committed, +/// and native paths never run on it. #[cfg(not(target_family = "wasm"))] -const STACK_BYTES: usize = 1 << 30; +const REFERENCE_STACK: usize = 1 << 30; #[cfg(not(target_family = "wasm"))] -fn on_stack(work: impl FnOnce() -> T + Send) -> T { +fn on_reference_stack(work: impl FnOnce() -> T + Send) -> T { std::thread::scope(|scope| { std::thread::Builder::new() - .name("uorc".to_owned()) - .stack_size(STACK_BYTES) + .name("uorc-reference".to_owned()) + .stack_size(REFERENCE_STACK) .spawn_scoped(scope, work) - .expect("spawn the uorc worker thread") + .expect("spawn the uorc reference thread") .join() .unwrap_or_else(|panic| std::panic::resume_unwind(panic)) }) } #[cfg(target_family = "wasm")] -fn on_stack(work: impl FnOnce() -> T) -> T { +fn on_reference_stack(work: impl FnOnce() -> T) -> T { work() } -/// Compress `input` into the smallest checked archive: the ulz kernel archive -/// (an LZ/range-coder decoder program plus its payload), the raw archive, and, -/// when `steps` is positive, the best archive the search finds within `steps`. -/// Every candidate is verified against `input` before it is returned. -pub fn compress(input: &[u8], steps: u64) -> Result, Error> { - on_stack(|| compress_here(input, steps)) +/// Worker threads used when the caller does not say. +pub fn default_threads() -> usize { + std::thread::available_parallelism().map_or(1, usize::from) +} + +/// Compress one frame into its archive: the smaller of the ulz kernel archive +/// and the raw archive, exactly as the model's `compress input 0`; with +/// `steps > 0`, the exported model also searches and keeps the smallest. +pub fn compress_frame(frame: &[u8], steps: u64) -> Result, Error> { + compress_pieces(frame, &[frame.len() as u64], steps) +} + +/// [`compress_frame`] with the output split into objects of `lengths`, which +/// sum to the frame's length. Only the header differs from the one-object +/// archive, so the choice between kernel and raw is the same. +fn compress_pieces(frame: &[u8], lengths: &[u64], steps: u64) -> Result, Error> { + if steps > 0 { + let archive = on_reference_stack(|| reference_compress(frame, steps))?; + return if lengths.len() == 1 { + Ok(archive) + } else { + frame::relabel(&archive, lengths) + }; + } + let n = frame.len() as u64; + let payload = ulz::encode(frame); + // The model writes the coder output into a table of the next power of two + // at or above 2n + 64 bytes and falls back to raw if it would not fit. + let fits = (payload.len() as u64 - 8) <= (2 * n + 64).next_power_of_two(); + if fits && ulz::decode(&payload, n).as_deref() == Some(frame) { + let kernel = archive::program_archive(lengths, &payload); + if (kernel.len() as u64) < archive::raw_length(lengths) { + return Ok(kernel); + } + } + Ok(archive::raw_objects(frame, lengths)) } -fn compress_here(input: &[u8], steps: u64) -> Result, Error> { +fn reference_compress(input: &[u8], steps: u64) -> Result, Error> { match uorc_compress::run(uorc_compress::Bytes::lit(input), steps) { Ok(Some(archive)) => Ok(archive.octets().to_vec()), Ok(None) => Err(Error::Budget), @@ -85,27 +153,130 @@ fn compress_here(input: &[u8], steps: u64) -> Result, Error> { } } -/// Reconstruct the original bytes of a self-contained archive. An archive -/// whose program is the ulz kernel, with a payload the ulz encoder writes, -/// runs the certified decoder directly; every other archive is reconstructed -/// by the reference semantics. -/// -/// An archive of several ordered objects decodes to their concatenation (see -/// [`decompress_objects`] to get them apart). -pub fn decompress(archive: &[u8], work: u64) -> Result, Error> { +/// Reconstruct the bytes of one self-contained archive (all its objects, in +/// order). Archives the native path vouches for (raw, and ulz kernel archives +/// this client writes) decode natively; every other archive is reconstructed +/// by the exported reference decoder within `work`. +pub fn decompress_frame(archive: &[u8], work: u64) -> Result, Error> { + if let Some(output) = archive::fast_decode(archive) { + return Ok(output); + } let info = inspect(archive)?; if info.object_lengths.len() == 1 { - return on_stack(|| decompress_here(archive, work)); + return on_reference_stack(|| reference_decompress(archive, work)); } - // The certified fast path reads one-object frames. The same body under - // the single total length produces the same bytes; the seal of the - // archive as given is checked before it is relabelled. + // The certified decoder reads one-object frames. The same body under the + // single total length produces the same bytes; the seal of the archive as + // given is checked before it is relabelled. let single = frame::relabel(archive, &[info.output_len])?; - on_stack(|| decompress_here(&single, work)) + on_reference_stack(|| reference_decompress(&single, work)) +} + +fn reference_decompress(archive: &[u8], work: u64) -> Result, Error> { + match uorc_decompress::run(uorc_decompress::Bytes::lit(archive), work) { + Ok(Some(output)) => Ok(output.octets().to_vec()), + Ok(None) => Err(Error::Decode), + Err(_) => Err(Error::Overflow), + } +} + +/// Apply `f` to every item on up to `threads` workers, keeping order. +fn parallel(items: &[T], threads: usize, f: impl Fn(&T) -> U + Sync) -> Vec { + if threads <= 1 || items.len() <= 1 { + return items.iter().map(f).collect(); + } + let next = std::sync::atomic::AtomicUsize::new(0); + let mut slots: Vec> = std::iter::repeat_with(|| None).take(items.len()).collect(); + let results = std::sync::Mutex::new(&mut slots); + std::thread::scope(|scope| { + for _ in 0..threads.min(items.len()) { + scope.spawn(|| loop { + let i = next.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + let Some(item) = items.get(i) else { break }; + let value = f(item); + results + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner)[i] = Some(value); + }); + } + }); + slots.into_iter().flatten().collect() +} + +/// Where each frame of a stream of `lengths` objects ends and the pieces of +/// objects it holds (see the crate documentation). +fn plan(lengths: &[u64]) -> Vec> { + let frame = FRAME as u64; + let mut plan = vec![Vec::new()]; + let mut used = 0u64; + for &n in lengths { + if used == frame { + plan.push(vec![0]); + used = 0; + } + let mut left = n; + loop { + let take = left.min(frame - used); + plan.last_mut().expect("a frame").push(take); + used += take; + left -= take; + if left == 0 { + break; + } + plan.push(Vec::new()); + used = 0; + } + } + plan +} + +/// Compress the concatenation `joined` of objects with the given frame plan. +fn compress_planned(joined: &[u8], plan: &[Vec], steps: u64) -> Result, Error> { + let mut at = 0usize; + let jobs: Vec<(&[u8], &[u64])> = plan + .iter() + .map(|pieces| { + let len = pieces.iter().sum::() as usize; + let job = (&joined[at..at + len], pieces.as_slice()); + at += len; + job + }) + .collect(); + let mut out = Vec::new(); + for archive in parallel(&jobs, default_threads(), |(f, l)| { + compress_pieces(f, l, steps) + }) { + out.extend_from_slice(&archive?); + } + Ok(out) +} + +/// Compress `input` into a uorc stream (one archive per [`FRAME`] bytes), +/// using every available core. Every archive is checked against its input +/// before it is returned. +pub fn compress(input: &[u8], steps: u64) -> Result, Error> { + compress_planned(input, &plan(&[input.len() as u64]), steps) +} + +/// Reconstruct the original bytes of a uorc stream, using every available +/// core. A stream of several objects decodes to their concatenation (see +/// [`decompress_objects`] to get them apart). +pub fn decompress(stream: &[u8], work: u64) -> Result, Error> { + Ok(decode_frames(stream, work)?.concat()) +} + +fn decode_frames(stream: &[u8], work: u64) -> Result>, Error> { + let frames = frames(stream)?; + if frames.is_empty() { + return Err(Error::Decode); + } + parallel(&frames, default_threads(), |a| decompress_frame(a, work)) + .into_iter() + .collect() } -/// Compress an ordered collection of byte objects into one archive whose -/// header records each object's length. The body codes the objects' +/// Compress an ordered collection of byte objects into one stream whose +/// headers record each object's length. The body codes the objects' /// concatenation, so similar objects compress together. Any number of objects /// is allowed, including none and empty ones. pub fn compress_objects>(objects: &[T], steps: u64) -> Result, Error> { @@ -114,85 +285,217 @@ pub fn compress_objects>(objects: &[T], steps: u64) -> Result Result>, Error> { - let lengths = inspect(archive)?.object_lengths; - let mut output = decompress(archive, work)?.into_iter(); - let objects: Vec> = lengths - .iter() - .map(|&n| output.by_ref().take(n as usize).collect()) - .collect(); - if objects.iter().map(Vec::len).sum::() as u64 != lengths.iter().sum::() - || output.next().is_some() - { +/// Reconstruct the ordered objects of a stream, split at the lengths its +/// headers record. +pub fn decompress_objects(stream: &[u8], work: u64) -> Result>, Error> { + let frames = frames(stream)?; + if frames.is_empty() { return Err(Error::Decode); } + let decoded = parallel(&frames, default_threads(), |a| { + let lengths = object_lengths(a)?; + let output = decompress_frame(a, work)?; + Ok::<_, Error>((lengths, output)) + }); + let mut objects: Vec> = Vec::new(); + for (k, part) in decoded.into_iter().enumerate() { + let (lengths, output) = part?; + if lengths.iter().sum::() != output.len() as u64 { + return Err(Error::Decode); + } + let mut rest = output.as_slice(); + for (i, &n) in lengths.iter().enumerate() { + let (piece, tail) = rest.split_at(n as usize); + rest = tail; + match objects.last_mut() { + Some(last) if k > 0 && i == 0 => last.extend_from_slice(piece), + _ if k > 0 && i == 0 => return Err(Error::Decode), + _ => objects.push(piece.to_vec()), + } + } + if k > 0 && lengths.is_empty() { + return Err(Error::Decode); + } + } Ok(objects) } -/// Compress a file tree (see [`tree`]) into one archive. +/// Compress a file tree (see [`tree`]) into one stream. pub fn compress_tree(entries: &[tree::Entry], steps: u64) -> Result, Error> { compress_objects(&tree::to_objects(entries)?, steps) } -/// Reconstruct the file tree an archive from [`compress_tree`] stores. Every +/// Reconstruct the file tree a stream from [`compress_tree`] stores. Every /// path is checked to be relative and free of `..`. -pub fn decompress_tree(archive: &[u8], work: u64) -> Result, Error> { - tree::from_objects(decompress_objects(archive, work)?) +pub fn decompress_tree(stream: &[u8], work: u64) -> Result, Error> { + tree::from_objects(decompress_objects(stream, work)?) } -fn decompress_here(archive: &[u8], work: u64) -> Result, Error> { - match uorc_decompress::run(uorc_decompress::Bytes::lit(archive), work) { - Ok(Some(output)) => Ok(output.octets().to_vec()), - Ok(None) => Err(Error::Decode), - Err(_) => Err(Error::Overflow), - } -} - -/// Check an archive end to end without keeping its output: the frame and the -/// integrity seal must be intact, it must decode, its output must have the -/// lengths the header declares and, when `original` is given, equal it. -/// -/// `stream` may be several archives written back to back; each is checked and -/// `original` is compared with their concatenated output. +/// Check a stream end to end without keeping its output: every archive's +/// frame and integrity seal must be intact, it must decode, its output must +/// have the lengths its header declares and, when `original` is given, the +/// concatenated output must equal it. Archives are checked in parallel. pub fn verify(stream: &[u8], original: Option<&[u8]>, work: u64) -> Result, Error> { - let mut infos = Vec::new(); - let mut at = 0usize; - for archive in frames(stream)? { + let frames = frames(stream)?; + if frames.is_empty() { + return Err(Error::Decode); + } + let mut jobs = Vec::with_capacity(frames.len()); + let mut at = 0u64; + for archive in frames { let info = inspect(archive)?; + let start = at; + at = at.checked_add(info.output_len).ok_or(Error::Mismatch)?; + jobs.push((archive, info, start)); + } + if original.is_some_and(|o| o.len() as u64 != at) { + return Err(Error::Mismatch); + } + let checked = parallel(&jobs, default_threads(), |(archive, info, start)| { if !info.integrity_ok { return Err(Error::Decode); } - let output = decompress(archive, work)?; + let output = decompress_frame(archive, work)?; if output.len() as u64 != info.output_len { return Err(Error::Decode); } if let Some(original) = original { - let end = at.checked_add(output.len()).ok_or(Error::Mismatch)?; - if original.get(at..end) != Some(output.as_slice()) { + let start = *start as usize; + if original[start..start + output.len()] != output[..] { return Err(Error::Mismatch); } - at = end; } - infos.push(info); + Ok(info.clone()) + }); + checked.into_iter().collect() +} + +/// Totals of a streaming operation. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct Totals { + /// Bytes read. + pub read: u64, + /// Bytes written. + pub written: u64, + /// Archives (frames) read or written. + pub frames: u64, +} + +fn read_full(reader: &mut impl Read, buf: &mut Vec, want: usize) -> io::Result<()> { + let have = buf.len(); + if have >= want { + return Ok(()); } - if original.is_some_and(|original| original.len() != at) || infos.is_empty() { - return Err(if infos.is_empty() { - Error::Decode - } else { - Error::Mismatch - }); + reader.take((want - have) as u64).read_to_end(buf)?; + Ok(()) +} + +/// Compress everything `reader` yields into a uorc stream on `writer`, one +/// [`FRAME`] at a time with `threads` frames in flight. Memory stays bounded by +/// `threads` frames whatever the input size. +pub fn compress_stream( + mut reader: impl Read, + mut writer: impl Write, + steps: u64, + threads: usize, +) -> io::Result { + let threads = threads.max(1); + let mut totals = Totals::default(); + loop { + let mut batch = Vec::with_capacity(threads); + let mut end = false; + while batch.len() < threads && !end { + let mut frame = Vec::new(); + read_full(&mut reader, &mut frame, FRAME)?; + end = frame.len() < FRAME; + // Empty input still becomes one (empty) archive. + if !frame.is_empty() || (totals.frames == 0 && batch.is_empty()) { + batch.push(frame); + } + } + for (frame, archive) in batch + .iter() + .zip(parallel(&batch, threads, |f| compress_frame(f, steps))) + { + let archive = archive?; + writer.write_all(&archive)?; + totals.read += frame.len() as u64; + totals.written += archive.len() as u64; + totals.frames += 1; + } + if end { + writer.flush()?; + return Ok(totals); + } + } +} + +/// Read the next archive of a stream, or `None` at a clean end of input. +fn next_archive(reader: &mut impl Read, carry: &mut Vec) -> io::Result>> { + let mut frame = std::mem::take(carry); + let mut want = HEADER_HINT; + let len = loop { + read_full(reader, &mut frame, want)?; + if frame.is_empty() { + return Ok(None); + } + match frame_length(&frame)? { + Some(len) => break len, + None if frame.len() < want => return Err(Error::Decode.into()), + None => want *= 2, + } + }; + if len < frame.len() { + // The header read ran into the next archive: keep those bytes. + *carry = frame.split_off(len); + } + read_full(reader, &mut frame, len)?; + if frame.len() < len { + return Err(Error::Decode.into()); + } + Ok(Some(frame)) +} + +/// Decompress the uorc stream `reader` yields onto `writer`, archive by +/// archive with `threads` archives in flight. +pub fn decompress_stream( + mut reader: impl Read, + mut writer: impl Write, + work: u64, + threads: usize, +) -> io::Result { + let threads = threads.max(1); + let mut totals = Totals::default(); + let mut carry = Vec::new(); + loop { + let mut batch = Vec::with_capacity(threads); + while batch.len() < threads { + match next_archive(&mut reader, &mut carry)? { + Some(a) => batch.push(a), + None => break, + } + } + if batch.is_empty() { + if totals.frames == 0 { + return Err(Error::Decode.into()); + } + writer.flush()?; + return Ok(totals); + } + for (archive, output) in batch + .iter() + .zip(parallel(&batch, threads, |a| decompress_frame(a, work))) + { + let output = output?; + writer.write_all(&output)?; + totals.read += archive.len() as u64; + totals.written += output.len() as u64; + totals.frames += 1; + } } - Ok(infos) } #[cfg(test)] @@ -356,4 +659,171 @@ mod tests { Err(Error::Decode) ); } + + fn text(n: usize, seed: u64) -> Vec { + let mut x = seed; + let words: [&[u8]; 7] = [ + b"frame ", + b"archive ", + b"kernel ", + b"the ", + b"of ", + b"\n", + b"uorc ", + ]; + let mut out = Vec::new(); + while out.len() < n { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + if x.is_multiple_of(7) { + out.push((x >> 32) as u8); + } else { + out.extend_from_slice(words[(x % 7) as usize]); + } + } + out.truncate(n); + out + } + + /// The native compressor writes exactly the archive the exported model + /// writes, and the native decoder accepts it. + #[test] + fn native_archives_are_the_model_archives() { + let mut inputs = vec![Vec::new(), b"a".to_vec(), b"abc".to_vec(), vec![0; 3000]]; + inputs.extend([(64, 1), (777, 2), (4096, 3)].map(|(n, s)| text(n, s))); + inputs.push((0..=255u8).cycle().take(2000).collect()); + // The exported model is slow unoptimized; release runs add a larger input. + if !cfg!(debug_assertions) { + inputs.push(text(20_000, 4)); + } + for input in inputs { + let native = compress_frame(&input, 0).expect("native"); + let model = on_reference_stack(|| reference_compress(&input, 0)).expect("model"); + assert_eq!(native, model, "{} bytes", input.len()); + assert_eq!(archive::fast_decode(&native), Some(input)); + } + } + + /// Wherever the native decoder accepts a kernel archive, it reconstructs + /// what the exported reference decoder reconstructs. The payloads here are + /// damaged encoder output, resealed, so most leave the encoder's language. + #[test] + fn native_decoder_agrees_with_the_reference_where_it_accepts() { + let input = text(64, 11); + let payload = ulz::encode(&input); + let (mut accepted, mut declined) = (0, 0); + let mut x = 0x9e37_79b9_7f4a_7c15u64; + for round in 0..48 { + let mut p = payload.clone(); + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + let at = 13 + (x as usize % (p.len() - 13)); + match round % 3 { + 0 => p[at] ^= 1 << ((x >> 40) % 8), + 1 => p[at] = (x >> 24) as u8, + _ => p.truncate(at), + } + let archive = archive::program_archive(&[input.len() as u64], &p); + match archive::fast_decode(&archive) { + Some(native) => { + accepted += 1; + let reference = + on_reference_stack(|| reference_decompress(&archive, DEFAULT_DECODE_WORK)); + assert_eq!(Ok(native), reference, "round {round}"); + } + None => declined += 1, + } + // Each accepted case runs the graph by the reference semantics, + // which is slow; two of them make the point. + let enough = if cfg!(debug_assertions) { 1 } else { 2 }; + if accepted >= enough && declined >= enough { + break; + } + } + assert!( + accepted > 0 && declined > 0, + "{accepted} accepted, {declined} declined" + ); + } + + #[test] + fn streams_are_frames_end_to_end() { + let input = text(2 * FRAME + 12_345, 5); + let mut stream = Vec::new(); + let totals = compress_stream(&input[..], &mut stream, 0, 3).expect("compress"); + assert_eq!(totals.frames, 3); + assert_eq!(totals.read, input.len() as u64); + assert_eq!(frames(&stream).expect("frames").len(), 3); + assert_eq!(stream, compress(&input, 0).expect("in memory")); + let mut back = Vec::new(); + let totals = + decompress_stream(&stream[..], &mut back, DEFAULT_DECODE_WORK, 2).expect("decompress"); + assert_eq!(totals.frames, 3); + assert!(back == input); + assert!(decompress(&stream, DEFAULT_DECODE_WORK).expect("in memory") == input); + } + + #[test] + fn empty_and_exact_frame_streams() { + let mut stream = Vec::new(); + compress_stream(&b""[..], &mut stream, 0, 4).expect("empty"); + assert_eq!(frames(&stream).expect("one").len(), 1); + assert_eq!(decompress(&stream, DEFAULT_DECODE_WORK), Ok(Vec::new())); + let input = vec![7u8; FRAME]; + let mut stream = Vec::new(); + assert_eq!( + compress_stream(&input[..], &mut stream, 0, 1) + .expect("one frame") + .frames, + 1 + ); + assert!(decompress(&stream, DEFAULT_DECODE_WORK).expect("decodes") == input); + assert_eq!( + decompress(&stream[..stream.len() - 1], DEFAULT_DECODE_WORK), + Err(Error::Decode) + ); + } + + #[test] + fn frame_plans_continue_objects_across_frames() { + let f = FRAME as u64; + assert_eq!(plan(&[]), vec![Vec::::new()]); + assert_eq!(plan(&[0]), vec![vec![0]]); + assert_eq!(plan(&[f]), vec![vec![f]]); + assert_eq!(plan(&[2 * f + 1]), vec![vec![f], vec![f], vec![1]]); + assert_eq!(plan(&[f, 0, 3]), vec![vec![f], vec![0, 0, 3]]); + assert_eq!(plan(&[5, f]), vec![vec![5, f - 5], vec![5]]); + } + + #[test] + fn objects_stream_across_frames() { + let big = text(FRAME + 5_000, 7); + for objects in [ + vec![big.clone(), Vec::new(), b"tail".to_vec()], + vec![big[..FRAME].to_vec(), Vec::new(), big[FRAME..].to_vec()], + vec![b"head".to_vec(), big.clone()], + ] { + let stream = compress_objects(&objects, 0).expect("stream"); + assert_eq!(frames(&stream).expect("frames").len(), 2); + assert_eq!( + decompress_objects(&stream, DEFAULT_DECODE_WORK).expect("objects"), + objects + ); + let joined = objects.concat(); + assert!(decompress(&stream, DEFAULT_DECODE_WORK).expect("bytes") == joined); + assert_eq!( + verify(&stream, Some(&joined), DEFAULT_DECODE_WORK) + .expect("verifies") + .len(), + 2 + ); + } + // One object is a plain stream. + assert_eq!( + compress_objects(&[&big], 0).expect("one"), + compress(&big, 0).expect("plain") + ); + } } diff --git a/crates/uorc/src/tree.rs b/crates/uorc/src/tree.rs index 254b3b8f..65791d18 100644 --- a/crates/uorc/src/tree.rs +++ b/crates/uorc/src/tree.rs @@ -2,7 +2,7 @@ //! //! A tree of `n > 0` entries is stored as the objects //! `[manifest, file₁, …, fileₖ]`, one object per regular file in manifest -//! order. An empty tree is the archive of zero objects. A one-object archive is +//! order; a tree of directories only is `[manifest, empty]`. An empty tree is the archive of zero objects. A one-object archive is //! always a single plain byte stream, never a tree, so the two never collide. //! //! The manifest is: @@ -106,6 +106,11 @@ pub fn to_objects(entries: &[Entry]) -> Result>, Error> { } } objects[0] = manifest; + if objects.len() == 1 { + // A tree of directories only: an empty end object keeps it from + // reading as a one-object plain stream. + objects.push(Vec::new()); + } Ok(objects) } @@ -145,6 +150,11 @@ pub fn from_objects(mut objects: Vec>) -> Result, Error> { }; entries.push(Entry { path, kind, data }); } + let mut files = files.peekable(); + if !entries.iter().any(|e| e.kind != Kind::Directory) && files.peek().is_some_and(Vec::is_empty) + { + files.next(); + } if at != rest.len() || files.next().is_some() { return Err(Error::Decode); } @@ -196,6 +206,14 @@ mod tests { assert_eq!(objects.len(), 3); assert_eq!(from_objects(objects).unwrap(), entries); assert!(to_objects(&[]).unwrap().is_empty()); + let dirs = vec![Entry { + path: "d".into(), + kind: Kind::Directory, + data: vec![], + }]; + let objects = to_objects(&dirs).unwrap(); + assert_eq!(objects.len(), 2); + assert_eq!(from_objects(objects).unwrap(), dirs); assert!(from_objects(vec![]).unwrap().is_empty()); } diff --git a/crates/uorc/src/ulz.rs b/crates/uorc/src/ulz.rs new file mode 100644 index 00000000..65ea590b --- /dev/null +++ b/crates/uorc/src/ulz.rs @@ -0,0 +1,734 @@ +//! Native ulz codec: the LZ + adaptive range coder of `Uorc.Codec.LzEncode` +//! and `Uorc.Codec.LzDecode` (client/src/Uorc/Codec), ported operation for +//! operation so that [`encode`] writes exactly the payload the LexLean encoder +//! writes, and [`decode`] reconstructs exactly what the LexLean decoder (and the +//! ulz kernel graph) reconstructs. +//! +//! The decoder is deliberately partial. It accepts only payloads on which every +//! reading of the bitstream agrees: the range coder keeps `code < range`, every +//! match source lies inside the output, no match runs past the declared length, +//! and the coder consumes the payload exactly. Any other payload is declined +//! with `None`, and the caller hands the archive to the exported reference +//! decoder, which applies the model's semantics to it. Every payload [`encode`] +//! writes is accepted (checked in the tests). + +/// Probability model size (`Table::fill 2 13 1024`). +const PROBS: usize = 1 << 13; +const TOP: u32 = 1 << 24; +type Probs = [u16; PROBS]; +const IS_REP: usize = 12; +const IS_REP_G0: usize = 24; +const IS_REP_G1: usize = 36; +const IS_REP_G2: usize = 48; +const IS_REP0_LONG: usize = 60; +const LITERAL: usize = 72; +const SLOT: usize = 6216; +const SPEC: usize = 6472; +const ALIGN: usize = 6587; +const LEN: usize = 6603; +const REP_LEN: usize = 7149; +const MAX_MATCH: usize = 273; +const NICE: usize = 64; +const DEPTH: usize = 48; +const HASH_BITS: u32 = 16; + +fn after_literal(s: usize) -> usize { + if s < 4 { + 0 + } else if s < 10 { + s - 3 + } else { + s - 6 + } +} + +fn after_match(s: usize) -> usize { + if s < 7 { + 7 + } else { + 10 + } +} + +fn after_rep(s: usize) -> usize { + if s < 7 { + 8 + } else { + 11 + } +} + +fn after_short(s: usize) -> usize { + if s < 7 { + 9 + } else { + 11 + } +} + +fn literal_base(prev: u8) -> usize { + LITERAL + 768 * usize::from(prev >> 5) +} + +// ---------------------------------------------------------------- encoder + +struct RangeEncoder { + low: u64, + range: u32, + cache: u8, + pending: u64, + out: Vec, +} + +impl RangeEncoder { + fn new(capacity: usize) -> Self { + RangeEncoder { + low: 0, + range: u32::MAX, + cache: 0, + pending: 1, + out: Vec::with_capacity(capacity), + } + } + + fn shift_low(&mut self) { + if self.low < 0xFF00_0000 || self.low >= 1 << 32 { + let carry = (self.low >> 32) as u8; + self.out.push(self.cache.wrapping_add(carry)); + for _ in 1..self.pending { + self.out.push(0xFFu8.wrapping_add(carry)); + } + self.cache = (self.low >> 24) as u8; + self.pending = 1; + } else { + self.pending += 1; + } + self.low = (self.low & 0x00FF_FFFF) << 8; + } + + #[inline(always)] + fn normalize(&mut self) { + if self.range < TOP { + self.range <<= 8; + self.shift_low(); + } + } + + #[inline(always)] + fn bit(&mut self, probs: &mut [u16], at: usize, bit: u32) { + let v = u32::from(probs[at]); + let bound = (self.range >> 11) * v; + if bit == 0 { + self.range = bound; + probs[at] = (v + ((2048 - v) >> 5)) as u16; + } else { + self.low += u64::from(bound); + self.range -= bound; + probs[at] = (v - (v >> 5)) as u16; + } + self.normalize(); + } + + fn direct(&mut self, value: u32, bits: u32) { + for k in (0..bits).rev() { + let half = self.range >> 1; + if (value >> k) & 1 == 1 { + self.low += u64::from(half); + } + self.range = half; + self.normalize(); + } + } + + fn tree(&mut self, probs: &mut [u16], base: usize, bits: u32, value: u32) { + let mut m = 1usize; + for k in (0..bits).rev() { + let b = (value >> k) & 1; + self.bit(probs, base + m, b); + m = (m << 1) | b as usize; + } + } + + fn reverse(&mut self, probs: &mut [u16], base: usize, bits: u32, mut value: u32) { + let mut m = 1usize; + for _ in 0..bits { + let b = value & 1; + value >>= 1; + self.bit(probs, base + m, b); + m = (m << 1) | b as usize; + } + } + + fn length(&mut self, probs: &mut [u16], base: usize, v: u32) { + if v < 8 { + self.bit(probs, base, 0); + self.tree(probs, base + 2, 3, v); + } else if v < 16 { + self.bit(probs, base, 1); + self.bit(probs, base + 1, 0); + self.tree(probs, base + 18, 3, v - 8); + } else { + self.bit(probs, base, 1); + self.bit(probs, base + 1, 1); + self.tree(probs, base + 34, 8, v - 16); + } + } + + fn distance(&mut self, probs: &mut [u16], dist: u32, len_code: u32) { + let ls = len_code.min(3) as usize; + let slot = if dist < 4 { + dist + } else { + let top = 31 - dist.leading_zeros(); + 2 * top + ((dist >> (top - 1)) & 1) + }; + self.tree(probs, SLOT + 64 * ls, 6, slot); + if slot >= 4 { + let fb = (slot >> 1) - 1; + let base = (2 + (slot & 1)) << fb; + let reduced = dist - base; + if slot < 14 { + self.reverse(probs, SPEC + base as usize - slot as usize, fb, reduced); + } else { + self.direct(reduced >> 4, fb - 4); + self.reverse(probs, ALIGN, 4, reduced & 15); + } + } + } + + fn literal(&mut self, probs: &mut [u16], base: usize, value: u8, match_byte: Option) { + let value = u32::from(value); + let Some(mb) = match_byte else { + self.tree(probs, base, 8, value); + return; + }; + let mb = u32::from(mb); + let mut sym = 1usize; + for k in (0..8).rev() { + let mbit = (mb >> k) & 1; + let b = (value >> k) & 1; + self.bit(probs, base + 256 * (1 + mbit as usize) + sym, b); + sym = (sym << 1) | b as usize; + if b != mbit { + for j in (0..k).rev() { + let b = (value >> j) & 1; + self.bit(probs, base + sym, b); + sym = (sym << 1) | b as usize; + } + return; + } + } + } + + fn finish(mut self) -> Vec { + for _ in 0..5 { + self.shift_low(); + } + self.out + } +} + +struct Finder<'a> { + data: &'a [u8], + head: Vec, + chain: Vec, +} + +impl Finder<'_> { + #[inline(always)] + fn at(&self, i: usize) -> u8 { + self.data.get(i).copied().unwrap_or(0) + } + + #[inline(always)] + fn hash(&self, i: usize) -> usize { + let x = (u64::from(self.data[i]) << 16) + | (u64::from(self.data[i + 1]) << 8) + | u64::from(self.data[i + 2]); + ((x * 2_654_435_761) >> 16) as usize & ((1 << HASH_BITS) - 1) + } + + #[inline(always)] + fn insert(&mut self, i: usize) { + if i + 2 < self.data.len() { + let k = self.hash(i); + self.chain[i] = self.head[k]; + self.head[k] = i as u32 + 1; + } + } + + /// Length of the common run of `a..` and `b..` (a < b), at most `limit`. + #[inline(always)] + fn common(&self, a: usize, b: usize, limit: usize) -> usize { + let x = &self.data[a..a + limit]; + let y = &self.data[b..b + limit]; + let mut l = 0; + while l + 8 <= limit { + let diff = u64::from_le_bytes(x[l..l + 8].try_into().unwrap_or([0; 8])) + ^ u64::from_le_bytes(y[l..l + 8].try_into().unwrap_or([0; 8])); + if diff != 0 { + return l + (diff.trailing_zeros() / 8) as usize; + } + l += 8; + } + while l < limit && x[l] == y[l] { + l += 1; + } + l + } + + fn find(&self, i: usize) -> (usize, usize) { + let n = self.data.len(); + if n <= i + 2 { + return (0, 0); + } + let limit = (n - i).min(MAX_MATCH); + let (mut best, mut dist) = (0usize, 0usize); + let mut candidate = self.head[self.hash(i)]; + for _ in 0..DEPTH { + if candidate == 0 { + break; + } + let j = candidate as usize - 1; + let next = self.chain[j]; + if self.at(j + best) == self.at(i + best) { + let l = self.common(j, i, limit); + if best < l { + best = l; + dist = i - (j + 1); + } + if l >= NICE { + return (best, dist); + } + } + candidate = next; + } + (best, dist) + } +} + +/// The ulz payload of `data`, byte for byte `Uorc.Codec.LzEncode::encode data`. +pub fn encode(data: &[u8]) -> Vec { + encode_with(&[], data) +} + +/// The ulz payload of `input` against a `history` window it may copy from: +/// the encoder runs over `history ++ input` with the match finder already +/// holding every history position, and emits only `input`. With an empty +/// history this is [`encode`]. +pub fn encode_with(history: &[u8], input: &[u8]) -> Vec { + let joined; + let data: &[u8] = if history.is_empty() { + input + } else { + joined = [history, input].concat(); + &joined + }; + let n = data.len(); + let start = history.len(); + let mut rc = RangeEncoder::new(input.len() / 2 + 64); + let mut probs = vec![1024u16; PROBS]; + let mut f = Finder { + data, + head: vec![0; 1 << HASH_BITS], + chain: vec![0; n], + }; + for j in 0..start { + f.insert(j); + } + let (mut state, mut reps, mut i) = (0usize, [0usize; 4], start); + while i < n { + let limit = (n - i).min(MAX_MATCH); + let (mut rl, mut ri) = (0usize, 0usize); + for (k, &r) in reps.iter().enumerate() { + let l = if i < r + 1 { + 0 + } else { + f.common(i - (r + 1), i, limit) + }; + if rl < l { + rl = l; + ri = k; + } + } + let (fl, fd) = f.find(i); + let ml1 = if fl == 2 && fd >= 128 { 0 } else { fl }; + f.insert(i); + let ml = if ml1 >= 2 && rl + 1 < ml1 && i + 1 < n { + let (gl, gd) = f.find(i + 1); + if ml1 + 1 < gl || (gl == ml1 + 1 && gd < 4 * fd) { + 0 + } else { + ml1 + } + } else { + ml1 + }; + let s = state; + if rl >= 2 && ml <= rl + 1 { + rc.bit(&mut probs, s, 1); + rc.bit(&mut probs, IS_REP + s, 1); + if ri == 0 { + rc.bit(&mut probs, IS_REP_G0 + s, 0); + rc.bit(&mut probs, IS_REP0_LONG + s, 1); + } else { + rc.bit(&mut probs, IS_REP_G0 + s, 1); + if ri == 1 { + rc.bit(&mut probs, IS_REP_G1 + s, 0); + } else { + rc.bit(&mut probs, IS_REP_G1 + s, 1); + rc.bit(&mut probs, IS_REP_G2 + s, ri as u32 - 2); + } + } + rc.length(&mut probs, REP_LEN, rl as u32 - 2); + let d = reps[ri]; + reps.copy_within(0..ri, 1); + reps[0] = d; + for k in 1..rl { + f.insert(i + k); + } + state = after_rep(s); + i += rl; + } else if ml >= 2 { + rc.bit(&mut probs, s, 1); + rc.bit(&mut probs, IS_REP + s, 0); + rc.length(&mut probs, LEN, ml as u32 - 2); + rc.distance(&mut probs, fd as u32, ml as u32 - 2); + for k in 1..ml { + f.insert(i + k); + } + reps = [fd, reps[0], reps[1], reps[2]]; + state = after_match(s); + i += ml; + } else { + rc.bit(&mut probs, s, 0); + let prev = if i == 0 { 0 } else { data[i - 1] }; + let match_byte = (s >= 7).then(|| { + if i < reps[0] + 1 { + 0 + } else { + data[i - (reps[0] + 1)] + } + }); + rc.literal(&mut probs, literal_base(prev), data[i], match_byte); + state = after_literal(s); + i += 1; + } + } + let body = rc.finish(); + let mut payload = Vec::with_capacity(8 + body.len()); + payload.extend_from_slice(&(input.len() as u64).to_le_bytes()); + payload.extend_from_slice(&body); + payload +} + +// ---------------------------------------------------------------- decoder + +struct RangeDecoder<'a> { + input: &'a [u8], + pos: usize, + range: u32, + code: u32, +} + +impl RangeDecoder<'_> { + #[inline(always)] + fn next(&mut self) -> u32 { + let b = self.input.get(self.pos).copied().unwrap_or(0); + self.pos += 1; + u32::from(b) + } + + #[inline(always)] + fn normalize(&mut self) { + if self.range < TOP { + self.range <<= 8; + self.code = (self.code << 8) | self.next(); + } + } + + #[inline(always)] + fn bit(&mut self, probs: &mut Probs, at: usize) -> u32 { + let p = &mut probs[at & (PROBS - 1)]; + let v = u32::from(*p); + let bound = (self.range >> 11) * v; + let b = if self.code < bound { + self.range = bound; + *p = (v + ((2048 - v) >> 5)) as u16; + 0 + } else { + self.code -= bound; + self.range -= bound; + *p = (v - (v >> 5)) as u16; + 1 + }; + self.normalize(); + b + } + + /// Direct bits; `None` when the stream leaves `code < range`. + fn direct(&mut self, bits: u32) -> Option { + let mut acc = 0u32; + for _ in 0..bits { + let half = self.range >> 1; + self.range = half; + if self.code < half { + acc <<= 1; + } else { + self.code -= half; + if self.code >= half { + return None; + } + acc = (acc << 1) | 1; + } + self.normalize(); + } + Some(acc) + } + + #[inline(always)] + fn tree(&mut self, probs: &mut Probs, base: usize, bits: u32) -> u32 { + let mut m = 1usize; + for _ in 0..bits { + m = (m << 1) | self.bit(probs, base + m) as usize; + } + (m - (1 << bits)) as u32 + } + + fn reverse(&mut self, probs: &mut Probs, base: usize, bits: u32) -> u32 { + let (mut m, mut acc) = (1usize, 0u32); + for k in 0..bits { + let b = self.bit(probs, base + m); + m = (m << 1) | b as usize; + acc |= b << k; + } + acc + } + + fn length(&mut self, probs: &mut Probs, base: usize) -> u32 { + if self.bit(probs, base) == 0 { + self.tree(probs, base + 2, 3) + } else if self.bit(probs, base + 1) == 0 { + 8 + self.tree(probs, base + 18, 3) + } else { + 16 + self.tree(probs, base + 34, 8) + } + } + + fn distance(&mut self, probs: &mut Probs, len_code: u32) -> Option { + let ls = len_code.min(3) as usize; + let slot = self.tree(probs, SLOT + 64 * ls, 6); + if slot < 4 { + return Some(u64::from(slot)); + } + let fb = (slot >> 1) - 1; + let base = u64::from(2 + (slot & 1)) << fb; + if slot < 14 { + let r = self.reverse(probs, SPEC + base as usize - slot as usize, fb); + Some(base + u64::from(r)) + } else { + let hi = self.direct(fb - 4)?; + let lo = self.reverse(probs, ALIGN, 4); + Some(base + 16 * u64::from(hi) + u64::from(lo)) + } + } +} + +/// Reconstruct the input of a ulz payload whose header declares `expected` +/// bytes. `None` declines the payload (see the module documentation); it never +/// means the payload is invalid under the model, only that the native decoder +/// does not vouch for it. +pub fn decode(payload: &[u8], expected: u64) -> Option> { + decode_with(&[], payload, expected) +} + +/// [`decode`] against the `history` window the payload was encoded with +/// ([`encode_with`]): the output starts as `history`, matches may reach into +/// it, and only the bytes after it are returned. +pub fn decode_with(history: &[u8], payload: &[u8], expected: u64) -> Option> { + if payload.len() < 13 { + return None; + } + let total = u64::from_le_bytes(payload[..8].try_into().ok()?); + if total != expected { + return None; + } + let h = history.len(); + let total = usize::try_from(total).ok()?.checked_add(h)?; + let code = u32::from_be_bytes(payload[9..13].try_into().ok()?); + if code == u32::MAX { + return None; + } + let mut rc = RangeDecoder { + input: payload, + pos: 13, + range: u32::MAX, + code, + }; + let mut probs: Box = Box::new([1024u16; PROBS]); + // A hostile header cannot make this allocate more than the payload could + // possibly describe up front; the vector grows as output is produced. + let mut out: Vec = Vec::with_capacity(total.min(h + payload.len().saturating_mul(64))); + out.extend_from_slice(history); + let (mut state, mut reps) = (0usize, [0u64; 4]); + while out.len() < total { + let s = state; + let size = out.len(); + if rc.bit(&mut probs, s) == 0 { + let prev = out.last().copied().unwrap_or(0); + let base = literal_base(prev); + let sym = if s < 7 { + rc.tree(&mut probs, base, 8) + } else { + let rep0 = reps[0]; + let mb = if rep0 < size as u64 { + u32::from(out[size - rep0 as usize - 1]) + } else { + 0 + }; + let mut sym = 1usize; + let mut k = 8u32; + while k > 0 { + k -= 1; + let mbit = (mb >> k) & 1; + let b = rc.bit(&mut probs, base + 256 * (1 + mbit as usize) + sym); + sym = (sym << 1) | b as usize; + if b != mbit { + break; + } + } + while sym < 0x100 { + sym = (sym << 1) | rc.bit(&mut probs, base + sym) as usize; + } + (sym - 0x100) as u32 + }; + out.push(sym as u8); + state = after_literal(s); + continue; + } + let len = if rc.bit(&mut probs, IS_REP + s) == 0 { + let len_code = rc.length(&mut probs, LEN); + let dist = rc.distance(&mut probs, len_code)?; + reps = [dist, reps[0], reps[1], reps[2]]; + state = after_match(s); + len_code as usize + 2 + } else { + if rc.bit(&mut probs, IS_REP_G0 + s) == 0 { + if rc.bit(&mut probs, IS_REP0_LONG + s) == 0 { + let rep0 = reps[0]; + if rep0 >= size as u64 { + return None; + } + out.push(out[size - rep0 as usize - 1]); + state = after_short(s); + continue; + } + } else { + let ri = if rc.bit(&mut probs, IS_REP_G1 + s) == 0 { + 1 + } else { + 2 + rc.bit(&mut probs, IS_REP_G2 + s) as usize + }; + let d = reps[ri]; + reps.copy_within(0..ri, 1); + reps[0] = d; + } + let len_code = rc.length(&mut probs, REP_LEN); + state = after_rep(s); + len_code as usize + 2 + }; + let rep0 = reps[0]; + if rep0 >= size as u64 || size + len > total { + return None; + } + let distance = rep0 as usize + 1; + let from = size - distance; + if distance >= len { + out.extend_from_within(from..from + len); + } else { + for k in 0..len { + let b = out[from + k]; + out.push(b); + } + } + } + if rc.pos != payload.len() { + return None; + } + out.drain(..h); + Some(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn sample(n: usize, seed: u64) -> Vec { + let mut x = seed; + let words: [&[u8]; 6] = [b"lorem ", b"ipsum ", b"dolor ", b"sit ", b"amet, ", b"\n"]; + let mut out = Vec::with_capacity(n); + while out.len() < n { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + if x.is_multiple_of(5) { + out.push((x >> 24) as u8); + } else { + out.extend_from_slice(words[(x % 6) as usize]); + } + } + out.truncate(n); + out + } + + #[test] + fn round_trips_and_is_accepted() { + for (n, seed) in [ + (0, 1), + (1, 2), + (2, 3), + (3, 4), + (100, 5), + (5000, 6), + (200_000, 7), + ] { + let data = sample(n, seed); + let payload = encode(&data); + assert_eq!(decode(&payload, n as u64), Some(data), "n = {n}"); + } + let zeros = vec![0u8; 100_000]; + assert_eq!(decode(&encode(&zeros), 100_000), Some(zeros)); + let all: Vec = (0..=255u8).cycle().take(70_000).collect(); + assert_eq!(decode(&encode(&all), 70_000), Some(all)); + } + + #[test] + fn history_window_round_trips_and_helps() { + let history = sample(50_000, 21); + let mut input = history[10_000..30_000].to_vec(); + input.extend(sample(5_000, 22)); + let alone = encode(&input); + let with = encode_with(&history, &input); + assert!( + with.len() * 3 < alone.len(), + "{} vs {}", + with.len(), + alone.len() + ); + assert_eq!( + decode_with(&history, &with, input.len() as u64), + Some(input.clone()) + ); + assert_eq!(encode_with(&[], &input), alone); + assert_eq!(decode_with(&[], &alone, input.len() as u64), Some(input)); + } + + #[test] + fn declines_what_it_does_not_vouch_for() { + let data = sample(3000, 9); + let mut payload = encode(&data); + assert_eq!(decode(&payload, 2999), None); + payload.push(0); + assert_eq!(decode(&payload, 3000), None); + } +} diff --git a/web/app.js b/web/app.js index 69db8e1d..c643182c 100644 --- a/web/app.js +++ b/web/app.js @@ -9,11 +9,11 @@ const examples = [ ["Empty input", () => new Uint8Array(0)], ]; -function offer(bytes, name) { +function offer(blob, name) { const link = document.createElement("a"); - link.href = URL.createObjectURL(new Blob([bytes])); + link.href = URL.createObjectURL(blob); link.download = name; - link.textContent = `Download ${name} (${bytes.length} bytes)`; + link.textContent = `Download ${name} (${blob.size} bytes)`; $("download").replaceChildren(link); } @@ -52,10 +52,11 @@ try { const tree = files.length > 1 || $("folder").files.length > 0; await timed(`Compressing ${files.length} file(s)`, async () => { if (!tree) { - const input = await bytesOf(files[0]); - const output = uorc.compress(input, steps()); - offer(output, `${files[0].name}.uorc`); - return `${input.length} → ${output.length} bytes`; + const file = files[0]; + const progress = (done, total) => { status.textContent = `Compressing ${file.name}: ${done} of ${total} bytes…`; }; + const output = await uorc.compressBlob(file, steps(), progress); + offer(output, `${file.name}.uorc`); + return `${file.size} → ${output.size} bytes`; } const entries = []; const dirs = new Set(); @@ -68,7 +69,7 @@ try { const all = [...[...dirs].sort().map((path) => ({ path, kind: "directory" })), ...entries]; const output = uorc.compressFiles(all, steps()); const root = files[0].webkitRelativePath ? files[0].webkitRelativePath.split("/")[0] : "files"; - offer(output, `${root}.uorc`); + offer(new Blob([output]), `${root}.uorc`); return `${entries.length} files, ${entries.reduce((n, e) => n + e.data.length, 0)} → ${output.length} bytes`; }); }); @@ -77,12 +78,16 @@ try { const file = $("file").files[0]; if (!file) { status.textContent = "Choose an archive first."; return; } await timed(`Decompressing ${file.name}`, async () => { - const archive = await bytesOf(file); - if (uorc.inspect(archive).objects === 1) { - const output = uorc.decompress(archive); + // A tree's first archive holds several objects; a plain stream's hold one. + const first = new Uint8Array(await file.slice(0, 64).arrayBuffer()); + const objects = first.length > 8 ? first[8] : 1; + if (objects === 1) { + const progress = (done, total) => { status.textContent = `Decompressing ${file.name}: ${done} of ${total} bytes…`; }; + const output = await uorc.decompressBlob(file, progress); offer(output, file.name.replace(/\.uorc$/, "") || "output"); - return `${archive.length} → ${output.length} bytes`; + return `${file.size} → ${output.size} bytes`; } + const archive = await bytesOf(file); const entries = uorc.decompressFiles(archive); const links = entries.filter((e) => e.kind !== "directory").map((e) => { const link = document.createElement("a"); @@ -104,9 +109,10 @@ try { const file = $("file").files[0]; if (!file) { status.textContent = "Choose an archive first."; return; } await timed(`Inspecting ${file.name}`, async () => { - const info = uorc.inspect(await bytesOf(file)); - report(JSON.stringify(info, null, 2)); - return info.integrity_ok ? "Header read, integrity ok" : "Header read, integrity MISMATCH"; + const infos = uorc.inspect(await bytesOf(file)); + report(JSON.stringify(infos, null, 2)); + const ok = infos.every((info) => info.integrity_ok); + return `${infos.length} archive(s) read, integrity ${ok ? "ok" : "MISMATCH"}`; }); }); diff --git a/web/index.html b/web/index.html index 78a90e10..3a2976c5 100644 --- a/web/index.html +++ b/web/index.html @@ -65,7 +65,8 @@

Use it

Command line

uorc compress --stats notes.txt      # writes notes.txt.uorc
 uorc decompress notes.txt.uorc -o notes.restored.txt
-cat data.bin | uorc compress - > data.uorc
+cat data.bin | uorc compress - > data.uorc   # any size: streams through 8 MiB frames
+uorc compress --threads 4 big.tar     # frames compress in parallel
 uorc compress photos/                 # writes photos.uorc (a whole tree)
 uorc decompress photos.uorc -o restore/   # --resume finishes an interrupted restore
 uorc inspect notes.txt.uorc           # header and integrity, no decoding
@@ -81,16 +82,20 @@ 

Rust library

let info = uorc::inspect(&archive)?; // header + integrity, no decode uorc::verify(&archive, Some(&bytes), uorc::DEFAULT_DECODE_WORK)?; let many = uorc::compress_objects(&[a, b, c], uorc::DEFAULT_STEPS)?; -let parts = uorc::decompress_objects(&many, uorc::DEFAULT_DECODE_WORK)?;
+let parts = uorc::decompress_objects(&many, uorc::DEFAULT_DECODE_WORK)?; +// Or stream between any reader and writer, with bounded memory: +uorc::compress_stream(reader, writer, uorc::DEFAULT_STEPS, uorc::default_threads())?;

JavaScript (this page's module)

import { load } from "./uorc.js";
 const uorc = await load("./uorc.wasm");
 const archive = uorc.compress(new TextEncoder().encode("hello hello hello"));
 const original = uorc.decompress(archive);
-uorc.inspect(archive);                 // { representation, object_lengths, integrity_ok, ... }
+uorc.inspect(archive);                 // [{ representation, object_lengths, integrity_ok, ... }]
 uorc.verify(archive, original);        // throws if it does not reproduce original
 const bundle = uorc.compressFiles([{ path: "a.txt", data }, { path: "d", kind: "directory" }]);
-const files = uorc.decompressFiles(bundle); // [{ path, kind, data }]
+const files = uorc.decompressFiles(bundle); // [{ path, kind, data }] +// Files of any size, one frame in memory at a time: +const blob = await uorc.compressBlob(file);

Binaries, the library source bundle and this WebAssembly module are attached to each GitHub release. Benchmark results for the release are on the benchmarks page.

diff --git a/web/uorc.js b/web/uorc.js index 765d757f..78ecd567 100644 --- a/web/uorc.js +++ b/web/uorc.js @@ -1,6 +1,6 @@ // Thin loader for the uorc WebAssembly client (crates/uorc-wasm). const ERRORS = ["", "no checked archive was found within the step budget", - "a natural-number operation overflowed 64 bits", "input is not a decodable self-contained UORC archive", + "a natural-number operation overflowed 64 bits", "input is not a decodable stream of self-contained UORC archives", "the archive does not decode to the given original"]; const KINDS = ["file", "executable", "directory"]; @@ -54,11 +54,46 @@ export async function load(url) { return new Uint8Array(x.memory.buffer, x.output_ptr(), x.output_len()).slice(); }; const json = (bytes) => JSON.parse(new TextDecoder().decode(bytes)); + const frame = Number(x.frame_size()); + const bytesOf = async (blob) => new Uint8Array(await blob.arrayBuffer()); + // Length of the archive starting at `at` in `blob`, read from its header. + const archiveLength = async (blob, at) => { + for (let want = Number(x.header_size()); ; want *= 2) { + const head = await bytesOf(blob.slice(at, at + want)); + put(x.input_buffer, head); + const length = x.frame_length(); + if (length >= 0 && at + length <= blob.size) return length; + if (length === -1 || head.length < want) throw new Error(ERRORS[3]); + } + }; return { compress: (bytes, steps = 0n) => call(bytes, () => x.compress(BigInt(steps))), decompress: (archive) => call(archive, () => x.decompress()), - // Frame header and integrity seal of one archive, without decoding. + // Frame header and integrity seal of every archive in a stream, without + // decoding: one description per archive. inspect: (archive) => json(call(archive, () => x.inspect())), + // Stream a File or Blob of any size through frames, one in wasm memory at + // a time; the result is a Blob of the concatenated outputs. + async compressBlob(blob, steps = 0n, progress = () => {}) { + const parts = []; + for (let at = 0; at < blob.size || at === 0; at += frame) { + const piece = await bytesOf(blob.slice(at, at + frame)); + parts.push(call(piece, () => x.compress_frame(BigInt(steps)))); + progress(Math.min(at + frame, blob.size), blob.size); + if (blob.size === 0) break; + } + return new Blob(parts); + }, + async decompressBlob(blob, progress = () => {}) { + const parts = []; + for (let at = 0; at < blob.size || parts.length === 0;) { + const length = await archiveLength(blob, at); + parts.push(call(await bytesOf(blob.slice(at, at + length)), () => x.decompress_frame())); + at += length; + progress(at, blob.size); + } + return new Blob(parts); + }, // Decode in memory and check; with an original, also compare. Returns one // description per archive in the stream; throws on any failure. verify: (archive, original) => json(call(archive, () => {