Merge remote-tracking branch 'origin/main' into codex/flac-main-reconcile

# Conflicts:
#	crates/audio/Cargo.toml
#	crates/audio/src/lib.rs
This commit is contained in:
Dylan M. Taylor
2026-11-15 17:52:06 +00:00
119 changed files with 13337 additions and 90 deletions
+5
View File
@@ -6,6 +6,7 @@ author, source and license. Library code and original assets are under the repos
| File | Author | Source | License |
|---|---|---|---|
| `licenses/jpeg-encoder-0.6.1/`, `crates/image-codecs/NOTICE` | jpeg-encoder contributors and the IJG, libjpeg-turbo and SIMD authors named in the retained notices | [jpeg-encoder 0.6.1](https://crates.io/crates/jpeg-encoder/0.6.1), used unmodified; source checksums in `SOURCE.json` | (MIT OR Apache-2.0) AND IJG |
| `crates/smime/testdata/` | MailCraft contributors; RFC 9216 example certificates | [MailCraft at 240d1d42](https://github.com/UCS-Care-Group/mailcraft/tree/240d1d42fe394cf3274402b180663ba9b43ca180/crates/smime/testdata), restored unmodified; provenance in the directory README | MIT OR Apache-2.0 (source repository) |
| `licenses/dwg/acadrust-MPL-2.0.txt`, `licenses/dwg/acadrust-THIRD_PARTY_NOTICES.md` | `acadrust` contributors; ACadSharp authors for the noted ported routines | [acadrust 0.6.6](https://github.com/hakanaktt/acadrust), used unmodified as `craft-dwg`'s optional native dependency | MPL-2.0; embedded ACadSharp notice is MIT; see both retained files |
| `crates/cms/profiles/photocraft-coated-cmyk.icc` | PhotoCraft contributors; generated by `craft_cms::synth::coated_cmyk` | [PhotoCraft `crates/cms`](https://github.com/storytold/photocraft/tree/b3222ee8e7e6bcb4799c37f904c595f20f9baf5e/crates/cms) | CC0-1.0 |
@@ -95,3 +96,7 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso
| `crates/raw/docs/raf-corpus.sha256` (hashes only; the files are not bundled) | The photographers who contributed each file to raw.pixls.us | [raw.pixls.us](https://raw.pixls.us/) | CC0-1.0 |
| `crates/drawingml/src/preset_text.txt` | DeckCraft contributors (Nikita Rakitin); generated by `crates/drawingml/tests/fixtures/make_preset_guides.py` from the guide formulas of ECMA-376 Part 1 `presetShapeDefinitions.xml` | [storytold/deckcraft#650](https://github.com/storytold/deckcraft/pull/650) | MIT OR Apache-2.0 (the formulas are the format's definition in ECMA-376) |
| `crates/drawingml/tests/fixtures/preset_table.txt` | DeckCraft contributors (Nikita Rakitin); generated by `crates/drawingml/tests/fixtures/make_preset_table.py` from ECMA-376 Part 1 `presetShapeDefinitions.xml` | [storytold/deckcraft#650](https://github.com/storytold/deckcraft/pull/650) | MIT OR Apache-2.0 (the formulas are the format's definition in ECMA-376) |
## Binary Apple property lists
`crates/plist` is extracted from `storytold/craft-anything` (`crates/formats/src/plist.rs` and checked byte reads), at source main `88d1d9cac852aec1c7fd97886db451e005e49d2a`. MIT OR Apache-2.0; source license texts are retained in the crate. Primary import Git authors preserve Brandon Thomas, BFlat, RRFZ and Afloat. Regression imports preserve BFlat. XML, JSON projection, calendar formatting and app policy were not imported into the public API.
Generated
+55
View File
@@ -1425,6 +1425,7 @@ version = "0.1.0"
name = "craft-captions"
version = "0.1.0"
dependencies = [
"craft-media-testkit",
"craft-timeline",
"craft-xml",
"proptest",
@@ -1843,6 +1844,13 @@ dependencies = [
"image",
]
[[package]]
name = "craft-gzip"
version = "0.1.0"
dependencies = [
"flate2",
]
[[package]]
name = "craft-hdr"
version = "0.1.0"
@@ -1919,7 +1927,9 @@ dependencies = [
"avif-serialize",
"craft-heif",
"craft-jpeg",
"craft-media-testkit",
"craft-metadata",
"craft-video",
"crc32fast",
"exr",
"flate2",
@@ -1969,6 +1979,13 @@ dependencies = [
"zune-jpeg",
]
[[package]]
name = "craft-jsonrpc"
version = "0.1.0"
dependencies = [
"serde_json",
]
[[package]]
name = "craft-jxl"
version = "0.1.0"
@@ -2057,6 +2074,24 @@ dependencies = [
"serde_json",
]
[[package]]
name = "craft-mcmat"
version = "0.1.0"
dependencies = [
"craft-zip",
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-mcp"
version = "0.1.0"
dependencies = [
"craft-jsonrpc",
"serde_json",
]
[[package]]
name = "craft-media"
version = "0.1.0"
@@ -2244,6 +2279,7 @@ dependencies = [
name = "craft-pcraft-format"
version = "0.1.0"
dependencies = [
"flate2",
"serde",
"serde_json",
"thiserror 2.0.21",
@@ -2373,6 +2409,13 @@ dependencies = [
"zbus",
]
[[package]]
name = "craft-plist"
version = "0.1.0"
dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-plotter"
version = "0.1.0"
@@ -2670,6 +2713,7 @@ dependencies = [
"data-url",
"flate2",
"kurbo 0.13.1",
"quick-xml 0.41.0",
"resvg 0.48.1",
"roxmltree 0.21.2",
"thiserror 2.0.21",
@@ -2686,6 +2730,16 @@ dependencies = [
"kurbo 0.13.1",
]
[[package]]
name = "craft-tcraft"
version = "0.1.0"
dependencies = [
"craft-zip",
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-text"
version = "0.1.0"
@@ -2815,6 +2869,7 @@ name = "craft-vectorcraft-format"
version = "0.1.0"
dependencies = [
"flate2",
"proptest",
"serde",
"serde_json",
"thiserror 2.0.21",
+6
View File
@@ -17,6 +17,7 @@ craft-proto = { path = "crates/proto" }
acadrust = "=0.6.6"
log = "0.4"
# internal: add each crate here as `craft-<name> = { path = "crates/<name>" }`
craft-plist = { path = "crates/plist" }
craft-platform = { path = "crates/platform" }
craft-aep = { path = "crates/aep" }
craft-affinity = { path = "crates/affinity" }
@@ -37,6 +38,7 @@ hayro-syntax = { version = "=0.7.2", default-features = false, features = ["std"
bytemuck = "1"
kurbo = "0.13"
thiserror = "2"
craft-gzip = { path = "crates/gzip" }
craft-aaf = { path = "crates/aaf" }
craft-atomic = { path = "crates/atomic" }
craft-captions = { path = "crates/captions" }
@@ -51,6 +53,7 @@ craft-dialogs = { path = "crates/dialogs" }
craft-doc-binary = { path = "crates/doc-binary" }
craft-docx = { path = "crates/docx" }
craft-document-bundle = { path = "crates/document-bundle" }
craft-mcmat = { path = "crates/mcmat" }
craft-designcraft-format = { path = "crates/designcraft-format" }
craft-dxf = { path = "crates/dxf" }
craft-drawingml = { path = "crates/drawingml" }
@@ -88,6 +91,8 @@ craft-indd = { path = "crates/indd" }
craft-jmap = { path = "crates/jmap" }
craft-ical = { path = "crates/ical" }
craft-jpeg = { path = "crates/jpeg" }
craft-jsonrpc = { path = "crates/jsonrpc" }
craft-mcp = { path = "crates/mcp" }
craft-jxl = { path = "crates/jxl" }
craft-kiwi = { path = "crates/kiwi" }
craft-keymap = { path = "crates/keymap" }
@@ -142,6 +147,7 @@ craft-stencilcraft-document = { path = "crates/stencilcraft-document" }
craft-svg-paths = { path = "crates/svg-paths" }
craft-stream-codecs = { path = "crates/stream-codecs" }
craft-text = { path = "crates/text" }
craft-tcraft = { path = "crates/tcraft" }
craft-texture = { path = "crates/texture" }
craft-tga = { path = "crates/tga" }
craft-timeline = { path = "crates/timeline" }
+123
View File
@@ -296,3 +296,126 @@ implementation, https://github.com/macosforge/alac at c38887c5c5e64a4b31108733bd
(LICENSE-APACHE). The files are modified: translated to Rust, with bounds checks on hostile input,
wrapping integer arithmetic, the unrolled predictor and per-width matrix routines folded into one,
and the average bit rate filled in. Those files are Apache-2.0 only.
JPEG encoding dependency: jpeg-encoder 0.6.1
Source: https://crates.io/crates/jpeg-encoder/0.6.1
Declared license: (MIT OR Apache-2.0) AND IJG.
This software is based in part on the work of the Independent JPEG Group.
The MIT license and unaltered upstream IJG and SIMD notices follow. The Apache-2.0
alternative is also retained in licenses/jpeg-encoder-0.6.1 at the repository root.
The dependency is used unmodified; no encoder implementation is vendored here.
LICENSE-MIT
Copyright (c) 2021 Volker Ströbel <volkerstroebel@mysurdity.de>
Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the
Software without restriction, including without
limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
Original src/fdct.rs opening notice
/*
* Ported from mozjpeg to rust
*
* This file was part of the Independent JPEG Group's software:
* Copyright (C) 1991-1996, Thomas G. Lane.
* libjpeg-turbo Modifications:
* Copyright (C) 2015, 2020, D. R. Commander.
*
* Conditions of distribution and use:
* In plain English:
*
* 1. We don't promise that this software works. (But if you find any bugs,
* please let us know!)
* 2. You can use this software for whatever you want. You don't have to pay us.
* 3. You may not pretend that you wrote this software. If you use it in a
* program, you must acknowledge somewhere in your documentation that
* you've used the IJG code.
*
* In legalese:
*
* The authors make NO WARRANTY or representation, either express or implied,
* with respect to this software, its quality, accuracy, merchantability, or
* fitness for a particular purpose. This software is provided "AS IS", and you,
* its user, assume the entire risk as to its quality and accuracy.
*
* This software is copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding.
* All Rights Reserved except as specified below.
*
* Permission is hereby granted to use, copy, modify, and distribute this
* software (or portions thereof) for any purpose, without fee, subject to these
* conditions:
* (1) If any part of the source code for this software is distributed, then this
* README file must be included, with this copyright and no-warranty notice
* unaltered; and any additions, deletions, or changes to the original files
* must be clearly indicated in accompanying documentation.
* (2) If only executable code is distributed, then the accompanying
* documentation must state that "this software is based in part on the work of
* the Independent JPEG Group".
* (3) Permission for use of this software is granted only if the user accepts
* full responsibility for any undesirable consequences; the authors accept
* NO LIABILITY for damages of any kind.
*
* These conditions apply to any software derived from or based on the IJG code,
* not just to the unmodified library. If you use our work, you ought to
* acknowledge us.
*
* Permission is NOT granted for the use of any IJG author's name or company name
* in advertising or publicity relating to this software or products derived from
* it. This software may be referred to only as "the Independent JPEG Group's
* software".
*
* We specifically permit and encourage the use of this software as the basis of
* commercial products, provided that all warranty or liability claims are
* assumed by the product vendor.
*
* This file contains a slower but more accurate integer implementation of the
* forward DCT (Discrete Cosine Transform).
*
* A 2-D DCT can be done by 1-D DCT on each row followed by 1-D DCT
* on each column. Direct algorithms are also available, but they are
* much more complex and seem not to be any faster when reduced to code.
*
* This implementation is based on an algorithm described in
* C. Loeffler, A. Ligtenberg and G. Moschytz, "Practical Fast 1-D DCT
* Algorithms with 11 Multiplications", Proc. Int'l. Conf. on Acoustics,
* Speech, and Signal Processing 1989 (ICASSP '89), pp. 988-991.
* The primary algorithm described there uses 11 multiplies and 29 adds.
* We use their alternate method with 12 multiplies and 32 adds.
* The advantage of this method is that no data path contains more than one
* multiplication; this allows a very simple and accurate implementation in
* scaled fixed-point arithmetic, with a minimal number of shifts.
*/
Original src/avx2/fdct.rs opening notice
/*
* Ported from mozjpeg / jfdctint-avx2.asm to rust
* Copyright 2009 Pierre Ossman <ossman@cendio.se> for Cendio AB
* Copyright (C) 2009, 2016, 2018, 2020, D. R. Commander.
*
* Based on the x86 SIMD extension for IJG JPEG library
* Copyright (C) 1999-2006, MIYASAKA Masaru.
*/
+16
View File
@@ -108,3 +108,19 @@ fn objects_nested_too_deeply_are_an_error() {
let e = store::read(&chain(250)).unwrap_err();
assert!(e.contains("nested too deeply"), "{e}");
}
/// Many distinct property IDs still reject a duplicate without quadratic scanning.
#[test]
fn duplicate_after_many_distinct_properties_is_rejected() {
let mut props = vec![0x4C, 0x20];
props.extend_from_slice(&8193u16.to_le_bytes());
for id in (0..8192u16).chain(std::iter::once(7)) {
props.extend_from_slice(&id.to_le_bytes());
props.extend_from_slice(&0x82u16.to_le_bytes());
props.extend_from_slice(&0u16.to_le_bytes());
}
let mut writer = Writer::new(Version::V3);
writer.stream(Writer::ROOT, "properties", props).unwrap();
let e = store::read(&writer.finish()).unwrap_err();
assert!(e.contains("duplicate property id"), "{e}");
}
+3 -1
View File
@@ -461,11 +461,13 @@ impl R<'_> {
if at > props.len() {
return Err(bad("truncated property index"));
}
// A properties stream can name tens of thousands of ids: do not rescan all earlier ids.
let mut seen = std::collections::HashSet::with_capacity(n);
for i in 0..n {
let (Some(pid), Some(sf), Some(len)) = (rd_u16(&props, 4 + i * 6), rd_u16(&props, 6 + i * 6), rd_u16(&props, 8 + i * 6)) else {
return Err(bad("truncated property index"));
};
if o.props.iter().any(|(previous, _)| *previous == pid) {
if !seen.insert(pid) {
return Err(bad("duplicate property id"));
}
let v = props.get(at..at + len as usize).ok_or_else(|| bad("truncated property value"))?;
+8
View File
@@ -40,6 +40,10 @@ aac-decode = ["craft-media/bitstream"]
# The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`.
aac-encode = ["craft-media/bitstream", "craft-media/isobmff"]
opus-decode = []
# QOA (Quite OK Audio) files: decoder and encoder in the `qoa` module, each on its own.
qoa = ["qoa-decode", "qoa-encode"]
qoa-decode = []
qoa-encode = []
opus-encode = []
ac3-decode = ["craft-media/bitstream"]
mpa-decode = ["craft-media/bitstream"]
@@ -90,6 +94,10 @@ required-features = ["decode", "encode"]
name = "flac_decode"
required-features = ["flac-decode", "flac-encode"]
[[test]]
name = "qoa_oracle"
required-features = ["qoa"]
[[example]]
name = "info"
required-features = ["decode"]
+7 -1
View File
@@ -27,7 +27,8 @@
//! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`,
//! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and
//! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`]
//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-decode`: the frame and file decoder; `flac-encode`: the packet encoder).
//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-decode`: the frame and file decoder;
//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files).
//!
//! The shared types below build with no features.
@@ -49,6 +50,8 @@ pub mod opus;
mod pcm;
#[cfg(feature = "peaks")]
pub mod peaks;
#[cfg(any(feature = "qoa-decode", feature = "qoa-encode"))]
pub mod qoa;
#[cfg(feature = "decode-native")]
mod read;
#[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))]
@@ -66,6 +69,9 @@ mod wav;
feature = "vorbis-encode"
))]
mod write;
/// Range-backed PCM WAVE access and a 16-bit PCM writer.
pub mod wav_range;
#[cfg(feature = "vorbis-encode")]
pub use write::{OGG_BITRATES, encode_ogg};
+411
View File
@@ -0,0 +1,411 @@
//! QOA ("Quite OK Audio"): a decoder (feature `qoa-decode`) and an encoder (feature `qoa-encode`)
//! for whole `.qoa` files, 16-bit, 1 to 8 channels.
//!
//! Written from the published QOA specification (qoaformat.org). A file is an 8-byte header (the
//! magic `qoaf` and the number of samples per channel) followed by frames of up to 5120 samples
//! per channel. Each frame starts with its channel count, sample rate, sample count and size, then
//! the state of one 4-tap sign-sign LMS predictor per channel, then 64-bit slices of 20 samples:
//! a 4-bit scale factor and twenty 3-bit quantised residuals, the channels interleaved slice by
//! slice.
//!
//! Streaming files (a sample count of 0 in the header) are not supported.
//! Samples are `i16`, one `Vec` per channel.
#[cfg(feature = "qoa-decode")]
const MAX_FRAME_SAMPLES: usize = 5120;
const SLICE_SAMPLES: usize = 20;
const LMS_LEN: usize = 4;
const MAGIC: &[u8; 4] = b"qoaf";
/// The most channels a file may have.
pub const MAX_CHANNELS: usize = 8;
/// `dequant[scale factor][quantised residual]`: `round(round((sf + 1)^2.75) * [0.75, -0.75, 2.5,
/// -2.5, 4.5, -4.5, 7, -7])`.
const DEQUANT: [[i32; 8]; 16] = [
[1, -1, 3, -3, 5, -5, 7, -7],
[5, -5, 18, -18, 32, -32, 49, -49],
[16, -16, 53, -53, 95, -95, 147, -147],
[34, -34, 113, -113, 203, -203, 315, -315],
[63, -63, 210, -210, 378, -378, 588, -588],
[104, -104, 345, -345, 621, -621, 966, -966],
[158, -158, 528, -528, 950, -950, 1477, -1477],
[228, -228, 760, -760, 1368, -1368, 2128, -2128],
[316, -316, 1053, -1053, 1895, -1895, 2947, -2947],
[422, -422, 1405, -1405, 2529, -2529, 3934, -3934],
[548, -548, 1828, -1828, 3290, -3290, 5117, -5117],
[696, -696, 2320, -2320, 4176, -4176, 6496, -6496],
[868, -868, 2893, -2893, 5207, -5207, 8099, -8099],
[1064, -1064, 3548, -3548, 6386, -6386, 9933, -9933],
[1286, -1286, 4288, -4288, 7718, -7718, 12005, -12005],
[1536, -1536, 5120, -5120, 9216, -9216, 14336, -14336],
];
/// What went wrong reading or writing a QOA file.
#[non_exhaustive]
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum Error {
/// The input is not a QOA file, or is damaged or truncated.
#[error("malformed QOA: {0}")]
Malformed(&'static str),
/// A valid file this module does not handle (a streaming file).
#[error("unsupported QOA: {0}")]
Unsupported(&'static str),
/// The samples or settings given to the encoder cannot be written as QOA.
#[error("QOA cannot encode: {0}")]
InvalidInput(&'static str),
}
/// A decoded file.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Audio {
/// Sample rate in Hz (1 to 16 777 215).
pub sample_rate: u32,
/// One `Vec` of samples per channel, all the same length.
pub channels: Vec<Vec<i16>>,
}
/// The predictor: the last four samples and four weights.
#[derive(Clone, Copy)]
struct Lms {
history: [i32; LMS_LEN],
weights: [i32; LMS_LEN],
}
impl Lms {
fn new() -> Self {
Lms { history: [0; LMS_LEN], weights: [0, 0, -(1 << 13), 1 << 14] }
}
fn predict(&self) -> i32 {
let mut p = 0i32;
for i in 0..LMS_LEN {
p = p.wrapping_add(self.weights[i].wrapping_mul(self.history[i]));
}
p >> 13
}
fn update(&mut self, sample: i32, residual: i32) {
let delta = residual >> 4;
for i in 0..LMS_LEN {
self.weights[i] += if self.history[i] < 0 { -delta } else { delta };
}
self.history.copy_within(1.., 0);
self.history[LMS_LEN - 1] = sample;
}
}
fn clamp16(v: i32) -> i32 {
v.clamp(-32768, 32767)
}
#[cfg(feature = "qoa-decode")]
mod decode {
use super::{Audio, DEQUANT, Error, LMS_LEN, Lms, MAGIC, MAX_CHANNELS, MAX_FRAME_SAMPLES, SLICE_SAMPLES, clamp16};
fn be16(b: &[u8], i: usize) -> u16 {
u16::from_be_bytes([b[i], b[i + 1]])
}
/// Decode a whole `.qoa` file.
///
/// The declared length is checked against the input before anything is allocated: a slice of
/// 8 bytes holds at most 20 samples, so a file cannot declare more samples than that.
pub fn decode(bytes: &[u8]) -> Result<Audio, Error> {
if bytes.len() < 8 || &bytes[..4] != MAGIC {
return Err(Error::Malformed("missing the qoaf magic"));
}
let total = u32::from_be_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]) as usize;
if total == 0 {
return Err(Error::Unsupported("streaming files (a sample count of 0)"));
}
if bytes.len() < 16 {
return Err(Error::Malformed("truncated frame header"));
}
let channels = usize::from(bytes[8]);
let sample_rate = u32::from_be_bytes([0, bytes[9], bytes[10], bytes[11]]);
if channels == 0 || channels > MAX_CHANNELS || sample_rate == 0 {
return Err(Error::Malformed("bad channel count or sample rate"));
}
// 8 bytes (20 samples) per channel at the very least, plus the frame headers.
let room = (bytes.len() - 8) / (8 * channels) * SLICE_SAMPLES;
if total > room {
return Err(Error::Malformed("the file is too short for its declared length"));
}
let mut out: Vec<Vec<i16>> = Vec::new();
for _ in 0..channels {
let mut v = Vec::new();
v.try_reserve_exact(total).map_err(|_| Error::Malformed("too many samples"))?;
out.push(v);
}
let mut pos = 8;
let mut done = 0usize;
while done < total {
let head = bytes.get(pos..pos + 8).ok_or(Error::Malformed("truncated frame header"))?;
let rate = u32::from_be_bytes([0, head[1], head[2], head[3]]);
if usize::from(head[0]) != channels || rate != sample_rate {
return Err(Error::Malformed("the channel count or sample rate changes between frames"));
}
let samples = usize::from(be16(head, 4));
let size = usize::from(be16(head, 6));
let slices = samples.div_ceil(SLICE_SAMPLES);
if samples == 0 || samples > MAX_FRAME_SAMPLES || samples > total - done {
return Err(Error::Malformed("bad frame sample count"));
}
if size != 8 + 16 * channels + 8 * slices * channels {
return Err(Error::Malformed("frame size does not match its sample count"));
}
let frame = bytes.get(pos..pos + size).ok_or(Error::Malformed("truncated frame"))?;
let mut lms = [Lms::new(); MAX_CHANNELS];
for (c, state) in lms.iter_mut().take(channels).enumerate() {
let at = 8 + c * 16;
for i in 0..LMS_LEN {
state.history[i] = i32::from(be16(frame, at + 2 * i) as i16);
state.weights[i] = i32::from(be16(frame, at + 8 + 2 * i) as i16);
}
}
let mut at = 8 + 16 * channels;
for s in 0..slices {
let n = (samples - s * SLICE_SAMPLES).min(SLICE_SAMPLES);
for (c, state) in lms.iter_mut().take(channels).enumerate() {
let mut slice = u64::from_be_bytes([
frame[at],
frame[at + 1],
frame[at + 2],
frame[at + 3],
frame[at + 4],
frame[at + 5],
frame[at + 6],
frame[at + 7],
]);
at += 8;
let table = &DEQUANT[(slice >> 60) as usize & 15];
for _ in 0..n {
let dequantised = table[(slice >> 57) as usize & 7];
slice <<= 3;
let sample = clamp16(state.predict() + dequantised);
out[c].push(sample as i16);
state.update(sample, dequantised);
}
}
}
pos += size;
done += samples;
}
Ok(Audio { sample_rate, channels: out })
}
}
#[cfg(feature = "qoa-decode")]
pub use decode::decode;
#[cfg(feature = "qoa-encode")]
mod encode {
use super::{DEQUANT, Error, Lms, MAGIC, MAX_CHANNELS, SLICE_SAMPLES, clamp16};
/// The quantised residual (0..8) whose dequantised value is nearest `residual`.
fn quantise(table: &[i32; 8], residual: i32) -> usize {
let mut best = 0;
let mut best_err = i64::MAX;
for (q, &d) in table.iter().enumerate() {
let e = i64::from(residual - d).pow(2);
if e < best_err {
best = q;
best_err = e;
}
}
best
}
/// Encode one slice of one channel with every scale factor and keep the one with the least
/// squared error. Returns the 64-bit slice; `lms` is advanced to the chosen result.
fn encode_slice(lms: &mut Lms, samples: &[i16]) -> u64 {
let mut best: Option<(i64, u64, Lms)> = None;
for (sf, table) in DEQUANT.iter().enumerate() {
let mut trial = *lms;
let mut slice = sf as u64;
let mut err = 0i64;
for k in 0..SLICE_SAMPLES {
let mut q = 0;
if let Some(&s) = samples.get(k) {
let predicted = trial.predict();
q = quantise(table, i32::from(s) - predicted);
let sample = clamp16(predicted + table[q]);
err += i64::from(i32::from(s) - sample).pow(2);
trial.update(sample, table[q]);
}
slice = slice << 3 | q as u64;
}
// 4 + 60 bits are in `slice`; the scale factor belongs on top.
let slice = slice & ((1 << 60) - 1) | (sf as u64) << 60;
if best.as_ref().is_none_or(|b| err < b.0) {
best = Some((err, slice, trial));
}
}
match best {
Some((_, slice, state)) => {
*lms = state;
slice
}
None => 0,
}
}
/// Encode `channels` (one `Vec` of samples per channel, all the same length) as a `.qoa` file.
pub fn encode(sample_rate: u32, channels: &[Vec<i16>]) -> Result<Vec<u8>, Error> {
let n = channels.len();
if n == 0 || n > MAX_CHANNELS {
return Err(Error::InvalidInput("QOA stores 1 to 8 channels"));
}
if sample_rate == 0 || sample_rate > 0x00ff_ffff {
return Err(Error::InvalidInput("the sample rate must be 1 to 16777215 Hz"));
}
let total = channels[0].len();
if channels.iter().any(|c| c.len() != total) {
return Err(Error::InvalidInput("the channels differ in length"));
}
let total32 = u32::try_from(total).map_err(|_| Error::InvalidInput("too many samples"))?;
if total == 0 {
return Err(Error::InvalidInput("QOA cannot store an empty file"));
}
let mut out = Vec::with_capacity(8 + total * n / 2);
out.extend_from_slice(MAGIC);
out.extend_from_slice(&total32.to_be_bytes());
let mut lms = [Lms::new(); MAX_CHANNELS];
let mut start = 0;
while start < total {
let len = (total - start).min(5120);
let slices = len.div_ceil(SLICE_SAMPLES);
let size = 8 + 16 * n + 8 * slices * n;
out.push(n as u8);
out.extend_from_slice(&sample_rate.to_be_bytes()[1..]);
out.extend_from_slice(&(len as u16).to_be_bytes());
out.extend_from_slice(&(size as u16).to_be_bytes());
// The state a frame starts from is written as 16-bit values, so the predictor
// continues from exactly what a decoder reads.
for state in lms.iter_mut().take(n) {
for v in state.history.iter_mut().chain(state.weights.iter_mut()) {
*v = i32::from(*v as i16);
out.extend_from_slice(&(*v as i16).to_be_bytes());
}
}
for s in 0..slices {
let from = start + s * SLICE_SAMPLES;
let to = (from + SLICE_SAMPLES).min(start + len);
for (c, state) in lms.iter_mut().take(n).enumerate() {
out.extend_from_slice(&encode_slice(state, &channels[c][from..to]).to_be_bytes());
}
}
start += len;
}
Ok(out)
}
}
#[cfg(feature = "qoa-encode")]
pub use encode::encode;
#[cfg(all(test, feature = "qoa-decode", feature = "qoa-encode"))]
mod tests {
use super::*;
fn tone(frames: usize, ch: usize) -> Vec<Vec<i16>> {
(0..ch)
.map(|c| (0..frames).map(|i| (((i as f64) * (0.03 + 0.01 * c as f64)).sin() * 12000.0 + ((i * 7919) % 200) as f64) as i16).collect())
.collect()
}
fn snr(a: &[i16], b: &[i16]) -> f64 {
let (mut s, mut e) = (0f64, 0f64);
for (&x, &y) in a.iter().zip(b) {
s += f64::from(x).powi(2);
e += (f64::from(x) - f64::from(y)).powi(2);
}
10.0 * (s / e.max(1.0)).log10()
}
#[test]
fn dequant_table_matches_its_formula() {
for (sf, row) in DEQUANT.iter().enumerate() {
let scale = ((sf as f64 + 1.0).powf(2.75)).round();
for (q, base) in [0.75, -0.75, 2.5, -2.5, 4.5, -4.5, 7.0, -7.0].into_iter().enumerate() {
assert_eq!(f64::from(row[q]), (scale * base).round(), "sf {sf} q {q}");
}
}
}
#[test]
fn round_trips_with_a_good_signal_to_noise_ratio() {
for (frames, ch) in [(1, 1), (19, 2), (20, 1), (21, 2), (5120, 1), (5121, 2), (12_345, 8)] {
let src = tone(frames, ch);
let bytes = encode(44_100, &src).unwrap();
let back = decode(&bytes).unwrap();
assert_eq!((back.sample_rate, back.channels.len(), back.channels[0].len()), (44_100, ch, frames));
if frames > 1000 {
for (c, (a, b)) in src.iter().zip(&back.channels).enumerate() {
assert!(snr(a, b) > 25.0, "{frames}x{ch} channel {c}");
}
}
}
}
#[test]
fn silence_and_full_scale_extremes_survive() {
let silent = vec![vec![0i16; 3000]];
// No residual value is zero, so silence decodes to a tiny residue, never exactly 0.
let quiet = decode(&encode(8000, &silent).unwrap()).unwrap();
assert!(quiet.channels[0].iter().all(|&s| s.abs() <= 2), "silence stays within 2 LSB");
let square: Vec<i16> = (0..4000).map(|i| if (i / 50) % 2 == 0 { i16::MAX } else { i16::MIN }).collect();
let back = decode(&encode(48_000, std::slice::from_ref(&square)).unwrap()).unwrap();
assert_eq!(back.channels[0].len(), square.len());
}
#[test]
fn the_file_has_the_documented_layout() {
let bytes = encode(48_000, &tone(100, 2)).unwrap();
assert_eq!(&bytes[..4], b"qoaf");
assert_eq!(u32::from_be_bytes(bytes[4..8].try_into().unwrap()), 100);
assert_eq!(bytes[8], 2);
assert_eq!(&bytes[9..12], &48_000u32.to_be_bytes()[1..]);
assert_eq!(u16::from_be_bytes([bytes[12], bytes[13]]), 100);
// 8 header + 2 channels * 16 state + 5 slices * 2 channels * 8
assert_eq!(usize::from(u16::from_be_bytes([bytes[14], bytes[15]])), 8 + 32 + 80);
assert_eq!(bytes.len(), 8 + 8 + 32 + 80);
// The first frame starts from the specified predictor state.
assert_eq!(&bytes[16 + 8..16 + 16], &[0, 0, 0, 0, 0xe0, 0, 0x40, 0]);
}
#[test]
fn invalid_input_to_the_encoder_is_refused() {
assert!(encode(44_100, &[]).is_err());
assert!(encode(0, &[vec![0; 10]]).is_err());
assert!(encode(1 << 24, &[vec![0; 10]]).is_err());
assert!(encode(44_100, &[vec![0; 10], vec![0; 9]]).is_err());
assert!(encode(44_100, &[vec![]]).is_err());
assert!(encode(44_100, &vec![vec![0; 10]; 9]).is_err());
}
#[test]
fn hostile_input_is_an_error_not_a_panic() {
let good = encode(44_100, &tone(6000, 2)).unwrap();
for len in 0..good.len().min(600) {
let _ = decode(&good[..len]);
}
assert!(decode(&good[..good.len() - 1]).is_err());
// A header that declares more samples than the bytes can hold.
let mut huge = good.clone();
huge[4..8].copy_from_slice(&u32::MAX.to_be_bytes());
assert!(decode(&huge).is_err());
// A streaming file, and a frame whose size field lies.
let mut streaming = good.clone();
streaming[4..8].fill(0);
assert_eq!(decode(&streaming), Err(Error::Unsupported("streaming files (a sample count of 0)")));
let mut lying = good.clone();
lying[14] ^= 1;
assert!(decode(&lying).is_err());
let mut zero_rate = good.clone();
zero_rate[9..12].fill(0);
assert!(decode(&zero_rate).is_err());
let mut changed = good;
let second = 8 + usize::from(u16::from_be_bytes([changed[14], changed[15]]));
changed[second] = 1;
assert!(decode(&changed).is_err());
}
}
+223
View File
@@ -0,0 +1,223 @@
//! Range-backed PCM WAVE reader and canonical 16-bit writer.
//!
//! Reads chunk headers and only the requested sample range; it never loads a whole file.
use crate::{AudioError, Result};
use craft_media::ByteSource;
/// Whether a prefix identifies a RIFF or RF64 WAVE file.
pub fn sniff(b: &[u8]) -> bool {
b.len() >= 12 && (&b[0..4] == b"RIFF" || &b[0..4] == b"RF64") && &b[8..12] == b"WAVE"
}
const MAX_CHUNKS: usize = 1 << 16;
const IXML_MAX: u64 = 1 << 20;
/// Maximum sample data returned by a single range read.
pub const MAX_RANGE_BYTES: u64 = 4 << 20;
fn le16(b: &[u8], o: usize) -> u16 {
b.get(o..o.saturating_add(2)).and_then(|s| s.try_into().ok()).map_or(0, u16::from_le_bytes)
}
fn le32(b: &[u8], o: usize) -> u32 {
b.get(o..o.saturating_add(4)).and_then(|s| s.try_into().ok()).map_or(0, u32::from_le_bytes)
}
fn read_range(source: &impl ByteSource, off: u64, len: usize) -> Result<Vec<u8>> {
let mut bytes = vec![0; len];
source.read_at(off, &mut bytes)?;
Ok(bytes)
}
/// A PCM WAVE file held by an arbitrary random-access source.
pub struct WavRange<S> {
source: S,
/// Number of complete sample frames.
pub frames: u64,
/// Channel count.
pub channels: u16,
/// Sample rate in Hz.
pub rate: u32,
/// Container bits per sample.
pub bits: u16,
/// Whether samples are floating point.
pub float: bool,
/// BWF time reference in samples, from bext or iXML.
pub time_reference: Option<u64>,
data_off: u64,
}
impl<S: ByteSource> WavRange<S> {
/// Open with caller-selected bounds on channel count and sample rate.
pub fn open(source: S, max_channels: u32, max_rate: u32) -> Result<Self> {
let len = source.len();
let mut pos: u64 = 12;
let mut fmt = None;
let mut data = None;
let mut bext_tr = None;
let mut ixml_tr = None;
let mut ds64_data = None;
for _ in 0..MAX_CHUNKS {
let Some(body) = pos.checked_add(8).filter(|&b| b <= len) else { break };
let mut hdr = [0u8; 8];
source.read_at(pos, &mut hdr)?;
let id = &hdr[0..4];
let mut clen = u64::from(le32(&hdr, 4));
let rest = len - body;
if id == b"data" {
if clen == 0xFFFF_FFFF {
clen = ds64_data.unwrap_or(rest);
}
clen = clen.min(rest);
}
if clen > rest {
break;
}
match id {
b"fmt " if clen >= 16 => {
let b = read_range(&source, body, clen.min(40) as usize)?;
let mut tag = le16(&b, 0);
if tag == 0xFFFE && clen >= 40 {
tag = le16(&b, 24);
}
fmt = Some((tag, le16(&b, 2), le32(&b, 4), le16(&b, 14)));
}
b"ds64" if clen >= 16 => {
let b = read_range(&source, body + 8, 8)?;
ds64_data = Some(u64::from(le32(&b, 0)) | u64::from(le32(&b, 4)) << 32);
}
b"data" => data = Some((body, clen)),
b"bext" if clen >= 346 => {
let b = read_range(&source, body + 338, 8)?;
bext_tr = Some(u64::from(le32(&b, 0)) | u64::from(le32(&b, 4)) << 32);
}
b"iXML" => {
let b = read_range(&source, body, clen.min(IXML_MAX) as usize)?;
ixml_tr = ixml_time_reference(&b);
}
_ => {}
}
pos = body.saturating_add(clen).saturating_add(clen & 1);
}
let (tag, channels, rate, bits) = fmt.ok_or_else(|| AudioError::Malformed("missing fmt chunk".into()))?;
let (data_off, dlen) = data.ok_or_else(|| AudioError::Malformed("missing data chunk".into()))?;
let float = tag == 3;
if !(tag == 1 || float)
|| channels == 0
|| rate == 0
|| u32::from(channels) > max_channels
|| rate > max_rate
|| !matches!(bits, 8 | 16 | 24 | 32 | 64)
{
return Err(AudioError::Unsupported(format!("WAV format tag {tag}, {bits} bits")));
}
let frames = dlen / (u64::from(channels) * u64::from(bits / 8));
Ok(Self { source, frames, channels, rate, bits, float, time_reference: bext_tr.or(ixml_tr), data_off })
}
/// Bytes in one whole frame.
pub fn frame_bytes(&self) -> usize {
usize::from(self.channels) * usize::from(self.bits / 8)
}
/// Read the inclusive range of frames, capped to prevent unbounded allocation.
pub fn read_frames(&self, first: u64, last: u64) -> Result<Vec<u8>> {
if first > last || last >= self.frames {
return Err(AudioError::Malformed("WAV frame range outside data".into()));
}
let n = (last - first + 1).saturating_mul(self.frame_bytes() as u64);
if n > MAX_RANGE_BYTES {
return Err(AudioError::TooLarge("WAV frame range".into()));
}
let off = self.data_off.saturating_add(first.saturating_mul(self.frame_bytes() as u64));
read_range(&self.source, off, n as usize)
}
/// Decode a channel from a buffer returned by `read_frames`.
pub fn sample(&self, block: &[u8], frame: usize, ch: usize) -> f32 {
if ch >= usize::from(self.channels) {
return 0.0;
}
let bps = usize::from(self.bits / 8);
let Some(o) = frame.checked_mul(usize::from(self.channels)).and_then(|v| v.checked_add(ch)).and_then(|v| v.checked_mul(bps)) else {
return 0.0;
};
let Some(b) = block.get(o..o.saturating_add(bps)) else { return 0.0 };
match (self.bits, self.float, b) {
(8, _, &[a]) => (a as f32 - 128.0) / 128.0,
(16, _, &[a, b]) => i16::from_le_bytes([a, b]) as f32 / 32768.0,
(24, _, &[a, b, c]) => (i32::from_le_bytes([0, a, b, c]) >> 8) as f32 / 8_388_608.0,
(32, false, &[a, b, c, d]) => i32::from_le_bytes([a, b, c, d]) as f32 / 2_147_483_648.0,
(32, true, &[a, b, c, d]) => f32::from_le_bytes([a, b, c, d]),
(64, true, b) => f64::from_le_bytes(b.try_into().unwrap_or([0; 8])) as f32,
_ => 0.0,
}
}
}
fn ixml_time_reference(x: &[u8]) -> Option<u64> {
let text = String::from_utf8_lossy(x);
let field = |tag: &str| -> Option<u64> {
let open = format!("<{tag}>");
let a = text.find(&open)? + open.len();
let b = a + text[a..].find('<')?;
text[a..b].trim().parse().ok()
};
let low = field("BWF_TIME_REFERENCE_LOW")?;
Some(low | field("BWF_TIME_REFERENCE_HIGH").unwrap_or(0) << 32)
}
/// Write interleaved samples as 16-bit PCM WAVE, using symmetric 32767 scaling.
#[cfg(feature = "pcm-encode")]
pub fn write_wav16(samples: &[f32], channels: u16, rate: u32) -> Vec<u8> {
let data_len = samples.len().saturating_mul(2);
let mut v = crate::pcm_wav_header(u32::try_from(data_len).unwrap_or(u32::MAX), channels, rate, 16);
v.reserve(data_len);
for s in samples {
v.extend_from_slice(&((s.clamp(-1.0, 1.0) * 32767.0).round() as i16).to_le_bytes());
}
v
}
#[cfg(all(test, feature = "pcm-encode"))]
mod tests {
use super::*;
use std::sync::{Arc, Mutex};
struct Source {
bytes: Vec<u8>,
reads: Arc<Mutex<Vec<(u64, usize)>>>,
}
impl ByteSource for Source {
fn len(&self) -> u64 {
self.bytes.len() as u64
}
fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> {
self.reads.lock().unwrap_or_else(std::sync::PoisonError::into_inner).push((offset, buf.len()));
self.bytes.read_at(offset, buf)
}
}
#[test]
fn bounded_reads_and_pcm_values() {
let bytes = write_wav16(&[-1.0, -0.5, 0.0, 0.5, 1.0], 1, 48_000);
let reads = Arc::new(Mutex::new(Vec::new()));
let wav = WavRange::open(Source { bytes, reads: reads.clone() }, 64, 384_000).unwrap();
assert_eq!((wav.frames, wav.channels, wav.rate, wav.bits), (5, 1, 48_000, 16));
assert!(reads.lock().unwrap().iter().all(|(_, n)| *n <= 40));
let data = wav.read_frames(1, 3).unwrap();
assert_eq!(wav.sample(&data, 0, 0), -0.5);
assert_eq!(wav.sample(&data, 2, 0), 0.5);
assert!(wav.read_frames(0, 5).is_err());
assert!(wav.read_frames(3, 1).is_err());
assert_eq!(reads.lock().unwrap().last(), Some(&(46, 6)));
}
#[test]
fn ixml_fallback_accepts_flat_fields() {
let base = write_wav16(&[0.0], 1, 48_000);
let mut bytes = base[..36].to_vec();
let xml = b"<BWF_TIME_REFERENCE_LOW>5</BWF_TIME_REFERENCE_LOW><BWF_TIME_REFERENCE_HIGH>1</BWF_TIME_REFERENCE_HIGH>";
bytes.extend_from_slice(b"iXML");
bytes.extend_from_slice(&(xml.len() as u32).to_le_bytes());
bytes.extend_from_slice(xml);
if xml.len() & 1 != 0 {
bytes.push(0);
}
bytes.extend_from_slice(&base[36..]);
assert_eq!(WavRange::open(bytes.as_slice(), 64, 384_000).unwrap().time_reference, Some((1 << 32) + 5));
}
}
+62
View File
@@ -0,0 +1,62 @@
//! QOA against ffmpeg's decoder as the reference (oracle; skipped when ffmpeg is absent, a failure
//! with `CRAFT_MEDIA_REQUIRE_ORACLES=1`): ffmpeg decodes the files our encoder writes to exactly
//! the samples our decoder returns for them, over several sizes (partial slices, partial frames,
//! several frames), channel counts and rates.
use craft_audio::qoa::{decode, encode};
use std::process::Command;
fn signal(channels: usize, frames: usize) -> Vec<Vec<i16>> {
let mut seed = 0x2545_F491u32;
(0..channels)
.map(|c| {
(0..frames)
.map(|i| {
seed ^= seed << 13;
seed ^= seed >> 17;
seed ^= seed << 5;
let tone = ((i as f64) * (0.02 + 0.013 * c as f64)).sin() * 9000.0;
// Tones, noise bursts, silence and full-scale peaks.
match (i / 700) % 4 {
0 => tone as i16,
1 => (tone + f64::from(seed % 6000) - 3000.0) as i16,
2 => 0,
_ => {
if i % 2 == 0 {
i16::MAX
} else {
i16::MIN
}
}
}
})
.collect()
})
.collect()
}
#[test]
fn ffmpeg_decodes_our_files_to_the_same_samples() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("qoa");
for (rate, channels, frames) in
[(44_100u32, 1usize, 1usize), (8_000, 1, 19), (48_000, 2, 5_121), (22_050, 2, 12_345), (96_000, 1, 20_000), (44_100, 4, 6_000)]
{
let src = signal(channels, frames);
let bytes = encode(rate, &src).expect("encode");
let ours = decode(&bytes).expect("decode");
let file = dir.join(format!("ours_{rate}_{channels}_{frames}.qoa"));
std::fs::write(&file, &bytes).expect("write fixture");
let out = Command::new(&ffmpeg)
.args(["-v", "error", "-y", "-i"])
.arg(&file)
.args(["-f", "s16le", "-acodec", "pcm_s16le", "-"])
.output()
.expect("run ffmpeg");
assert!(out.status.success(), "ffmpeg failed on {}: {}", file.display(), String::from_utf8_lossy(&out.stderr));
let theirs: Vec<i16> = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect();
let interleaved: Vec<i16> = (0..frames).flat_map(|i| ours.channels.iter().map(move |ch| ch[i])).collect();
assert_eq!(theirs.len(), interleaved.len(), "{rate} Hz, {channels} ch, {frames} frames: sample count");
assert!(theirs == interleaved, "{rate} Hz, {channels} ch, {frames} frames: samples differ");
}
}
+2
View File
@@ -19,3 +19,5 @@ thiserror = { workspace = true }
proptest = { workspace = true }
# A second XML reader for the tests: checks of written TTML, and the comparison in tests/it/ttml_xml_views.rs.
roxmltree = "0.21"
# ffmpeg as the reference for the ASS tests (tests/it/ass.rs).
craft-media-testkit = { workspace = true }
+1
View File
@@ -55,6 +55,7 @@ lists at most 20 characters per stream.
| EBU STL `.stl` | yes | yes | EBU Tech 3264-E: GSI block + 128-byte TTI blocks, `STL25.01` (25 fps) or `STL30.01` (read/written as 29.97 fps, non-drop labels), ISO/IEC 6937 Latin text (accents as diacritic + letter), italics / underline codes as `<i>` / `<u>`, extension blocks for long subtitles, start-of-programme (TCP) subtracted. |
| TTML `.ttml` (IMSC1) | yes | yes | Writes the IMSC1 Text profile (TTML2 namespaces) with the document's language as `xml:lang` (read back on import): `<p>` per cue, `<br/>`, styled `<span>`s for `<i>` / `<b>` / `<u>`, `ttm:agent` speakers, exact frame times (`123f`) at the sequence rate. Reads any TTML (TTML1, TTML2, the 2006 `ttaf1` drafts): clock / frame / offset / tick times, `dur`, nested time containers (`body` / `div` begins offset and ends clip their contents; `seq` containers are read as `par` with a warning), timed spans, referenced styles. |
| DFXP `.dfxp` | yes | yes | TTML1 with the DFXP presentation profile; clock times in milliseconds (frame-exact after `snap_to_frames`). |
| ASS / SSA `.ass`, `.ssa` | yes | yes (ASS v4+) | The `[Events]` section: `Dialogue:` lines through the file's `Format:` line, `Name` as the speaker, `\N`, `\n`, `\h` and the `\i`, `\b`, `\u` override tags kept (as `<i>`, `<b>`, `<u>`); other override tags and drawing lines are dropped. Times are centiseconds. Written files have one `Default` style. |
All cue times are exact `Tick`s. Milliseconds convert exactly (1 ms = 254 016 000 ticks); SCC
frames map through `FrameRate::FPS_29_97`. `Document::snap_to_frames` snaps cues to a frame grid and
+244
View File
@@ -0,0 +1,244 @@
//! Advanced SubStation Alpha and SubStation Alpha (`.ass`, `.ssa`).
//!
//! Reading takes the `[Events]` section: its `Format:` line gives the field order (ASS v4+ and SSA
//! v4 differ in the first field only), each `Dialogue:` line becomes a cue; `Comment:` lines and
//! the other sections are skipped. A cue gets the `Name` field as its speaker. The text keeps what
//! the neutral model can show: `\N` and `\n` become a line break and a space, `\h` a no-break
//! space, and the override tags `\i`, `\b` and `\u` become `<i>`, `<b>` and `<u>`. Every other
//! override tag (colours, fonts, positions, karaoke, animation) is dropped, and a line that draws
//! vector shapes (`\p1`) is skipped with a warning.
//!
//! Writing gives a minimal ASS v4+ file: one `Default` style, one `Dialogue:` line per cue with
//! times to the centisecond. Braces in the text, which ASS reads as override blocks, are written
//! as the full-width `{` and `}`.
use crate::time::{TICKS_PER_SECOND, Tick};
use crate::{Cue, Document, Error, Result};
const TICKS_PER_CS: i64 = TICKS_PER_SECOND / 100;
/// `H:MM:SS.cc`, the form SSA and ASS use (any number of fraction digits is read).
fn parse_time(s: &str) -> Option<Tick> {
let s = s.trim();
let (hms, frac) = s.split_once('.').unwrap_or((s, ""));
let mut parts = hms.split(':');
let (h, m, sec) = (parts.next()?, parts.next()?, parts.next()?);
if parts.next().is_some() {
return None;
}
let num = |p: &str| -> Option<i64> { (!p.is_empty() && p.len() <= 9 && p.bytes().all(|b| b.is_ascii_digit())).then(|| p.parse().ok()).flatten() };
let (h, m, sec) = (num(h)?, num(m)?, num(sec)?);
if m >= 60 || sec >= 60 || h > 9999 {
return None;
}
let mut ticks = ((h * 60 + m) * 60 + sec) * TICKS_PER_SECOND;
if !frac.is_empty() {
if frac.len() > 9 || !frac.bytes().all(|b| b.is_ascii_digit()) {
return None;
}
let d: i64 = frac.parse().ok()?;
ticks += (i128::from(d) * i128::from(TICKS_PER_SECOND) / 10i128.pow(frac.len() as u32)) as i64;
}
Some(Tick(ticks))
}
fn format_time(t: Tick) -> String {
let cs = (i128::from(t.0.max(0)) + i128::from(TICKS_PER_CS) / 2) / i128::from(TICKS_PER_CS);
let (h, m, s, c) = (cs / 360_000, (cs / 6000) % 60, (cs / 100) % 60, cs % 100);
format!("{h}:{m:02}:{s:02}.{c:02}")
}
/// The Text field of a Dialogue line as cue text; `None` when the line draws shapes.
fn convert_text(raw: &str) -> Option<String> {
let mut out = String::new();
// Open `<i>`, `<b>`, `<u>` in the order they were opened.
let mut open: Vec<char> = Vec::new();
let mut chars = raw.chars().peekable();
let mut drawing = false;
let mut dropped_drawing = false;
while let Some(c) = chars.next() {
match c {
'{' => {
let mut block = String::new();
let mut closed = false;
for b in chars.by_ref() {
if b == '}' {
closed = true;
break;
}
block.push(b);
}
if !closed {
// An unterminated block is literal text.
out.push('{');
out.push_str(&block);
continue;
}
for tag in block.split('\\').skip(1) {
let tag = tag.trim_end();
let (name, val) = tag.split_at(tag.find(|c: char| !c.is_ascii_alphabetic()).unwrap_or(tag.len()));
match name {
"i" | "b" | "u" => {
let letter = name.chars().next().unwrap_or('i');
let on = val.trim() != "0";
if on && !open.contains(&letter) {
open.push(letter);
out.push_str(&format!("<{letter}>"));
} else if !on && open.contains(&letter) {
// Close back to it, reopening what was opened after.
let at = open.iter().position(|&o| o == letter).unwrap_or(0);
let after: Vec<char> = open.split_off(at + 1);
for o in after.iter().rev() {
out.push_str(&format!("</{o}>"));
}
open.pop();
out.push_str(&format!("</{letter}>"));
for o in after {
open.push(o);
out.push_str(&format!("<{o}>"));
}
}
}
"p" => drawing = val.trim().parse::<u32>().unwrap_or(0) != 0,
_ => {}
}
}
}
'\\' => match chars.peek() {
Some('N') => {
chars.next();
out.push('\n');
}
Some('n') => {
chars.next();
out.push(' ');
}
Some('h') => {
chars.next();
out.push('\u{a0}');
}
_ => out.push('\\'),
},
c => {
if drawing {
dropped_drawing = true;
} else {
out.push(c);
}
}
}
}
if dropped_drawing && out.trim().is_empty() {
return None;
}
while let Some(o) = open.pop() {
out.push_str(&format!("</{o}>"));
}
Some(out)
}
pub fn parse(text: &str) -> Result<Document> {
let text = text.strip_prefix('\u{feff}').unwrap_or(text);
let mut doc = Document::default();
let mut in_events = false;
let mut saw_events = false;
// Column of each field in a Dialogue line.
let mut cols: Vec<String> =
["layer", "start", "end", "style", "name", "marginl", "marginr", "marginv", "effect", "text"].map(String::from).to_vec();
let mut drawings = 0usize;
for (n, line) in text.lines().enumerate() {
let line = line.trim();
if line.starts_with('[') && line.ends_with(']') {
in_events = line.eq_ignore_ascii_case("[events]");
saw_events |= in_events;
continue;
}
if !in_events {
continue;
}
let Some((key, rest)) = line.split_once(':') else { continue };
let rest = rest.trim_start();
match key.trim().to_ascii_lowercase().as_str() {
"format" => cols = rest.split(',').map(|f| f.trim().to_ascii_lowercase()).collect(),
"dialogue" => {
// The last column (Text) keeps its commas.
let fields: Vec<&str> = rest.splitn(cols.len(), ',').collect();
let get = |name: &str| cols.iter().position(|c| c == name).and_then(|i| fields.get(i)).copied();
let (Some(start), Some(end), Some(raw)) = (get("start").and_then(parse_time), get("end").and_then(parse_time), get("text")) else {
doc.warnings.push(format!("line {}: not a Dialogue line this reader understands", n + 1));
continue;
};
let Some(text) = convert_text(raw) else {
drawings += 1;
continue;
};
let name = get("name").map(str::trim).filter(|s| !s.is_empty());
doc.cues.push(Cue { start, end, text, speaker: name.map(str::to_string), ..Default::default() });
}
_ => {}
}
}
if !saw_events {
return Err(Error::NotFormat("ASS"));
}
if drawings > 0 {
doc.warnings.push(format!("{drawings} vector drawing line(s) were skipped"));
}
Ok(doc)
}
fn escape(text: &str) -> String {
let mut out = String::with_capacity(text.len() + 8);
let mut rest = text;
while !rest.is_empty() {
if let Some(r) = rest.strip_prefix("\r\n") {
out.push_str("\\N");
rest = r;
} else if let Some(r) = rest.strip_prefix("<i>") {
out.push_str("{\\i1}");
rest = r;
} else if let Some(r) = rest.strip_prefix("</i>") {
out.push_str("{\\i0}");
rest = r;
} else if let Some(r) = rest.strip_prefix("<b>") {
out.push_str("{\\b1}");
rest = r;
} else if let Some(r) = rest.strip_prefix("</b>") {
out.push_str("{\\b0}");
rest = r;
} else if let Some(r) = rest.strip_prefix("<u>") {
out.push_str("{\\u1}");
rest = r;
} else if let Some(r) = rest.strip_prefix("</u>") {
out.push_str("{\\u0}");
rest = r;
} else if let Some(c) = rest.chars().next() {
match c {
'\n' | '\r' => out.push_str("\\N"),
// Empty override block separates a literal slash from N/n/h.
'\\' => out.push_str("\\{}"),
'{' => out.push('\u{ff5b}'),
'}' => out.push('\u{ff5d}'),
'\u{a0}' => out.push_str("\\h"),
c => out.push(c),
}
rest = &rest[c.len_utf8()..];
}
}
out
}
pub fn write(doc: &Document) -> String {
let mut out = String::from(
"[Script Info]\n; Written by craft-captions\nScriptType: v4.00+\nWrapStyle: 0\nScaledBorderAndShadow: yes\nPlayResX: 384\nPlayResY: 288\n\n\
[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\n\
Style: Default,Arial,16,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,2,10,10,10,1\n\n\
[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n",
);
for c in &doc.cues {
// A comma in the Name field would shift the columns; the other fields are fixed text.
let name = c.speaker.as_deref().unwrap_or("").replace([',', '\n', '\r'], " ");
out.push_str(&format!("Dialogue: 0,{},{},Default,{},0,0,0,,{}\n", format_time(c.start), format_time(c.end), name, escape(&c.text)));
}
out
}
+14 -3
View File
@@ -4,7 +4,7 @@
//! - **Files:** [SubRip](srt) (`.srt`), [WebVTT](vtt) (`.vtt`), [Scenarist SCC](scc) (`.scc`,
//! CEA-608 pop-on, roll-up and paint-on on read; pop-on on write), [MacCaption MCC](mcc)
//! (`.mcc`, SMPTE ST 334-2 packets with CEA-608 and CEA-708), [EBU STL](stl) (`.stl`, EBU
//! Tech 3264) and [TTML](ttml) (`.ttml` IMSC1 Text profile, `.dfxp` DFXP) parse into a
//! Tech 3264), [ASS/SSA](ass) (`.ass`, `.ssa`) and [TTML](ttml) (`.ttml` IMSC1 Text profile, `.dfxp` DFXP) parse into a
//! [`Document`] of [`Cue`]s and write back. Readers are forgiving (BOM, UTF-16, Windows-1252
//! fallback, CRLF/CR, missing SRT indexes, `,` or `.` milliseconds, missing hours, no blank
//! line between cues); writers are strict. WebVTT cue identifiers, cue settings, `<v Speaker>`
@@ -32,6 +32,7 @@
#[doc = include_str!("../README.md")]
struct ReadmeExamples;
pub mod ass;
pub mod cea608;
pub mod mcc;
pub mod scc;
@@ -69,10 +70,12 @@ pub enum Format {
Ttml,
/// DFXP (TTML1).
Dfxp,
/// Advanced SubStation Alpha (also reads SubStation Alpha).
Ass,
}
impl Format {
pub const ALL: [Format; 7] = [Format::Srt, Format::WebVtt, Format::Scc, Format::Mcc, Format::Stl, Format::Ttml, Format::Dfxp];
pub const ALL: [Format; 8] = [Format::Srt, Format::WebVtt, Format::Scc, Format::Mcc, Format::Stl, Format::Ttml, Format::Dfxp, Format::Ass];
pub fn name(self) -> &'static str {
match self {
Format::Srt => "SubRip (SRT)",
@@ -82,6 +85,7 @@ impl Format {
Format::Stl => "EBU STL",
Format::Ttml => "TTML (IMSC1)",
Format::Dfxp => "DFXP (TTML1)",
Format::Ass => "Advanced SubStation Alpha (ASS)",
}
}
pub fn extension(self) -> &'static str {
@@ -93,6 +97,7 @@ impl Format {
Format::Stl => "stl",
Format::Ttml => "ttml",
Format::Dfxp => "dfxp",
Format::Ass => "ass",
}
}
pub fn from_name(s: &str) -> Option<Format> {
@@ -104,6 +109,7 @@ impl Format {
"stl" | "ebu-stl" | "ebustl" | "ebu" => Some(Format::Stl),
"ttml" | "imsc" | "imsc1" | "xml" => Some(Format::Ttml),
"dfxp" => Some(Format::Dfxp),
"ass" | "ssa" => Some(Format::Ass),
_ => None,
}
}
@@ -251,6 +257,9 @@ pub fn detect(bytes: &[u8], ext: Option<&str>) -> Option<Format> {
if head.starts_with("File Format=MacCaption_MCC") {
return Some(Format::Mcc);
}
if head.starts_with("[Script Info]") {
return Some(Format::Ass);
}
let ext = ext.map(|e| e.trim_start_matches('.').to_ascii_lowercase());
if (head.starts_with('<') && (head.contains("<tt ") || head.contains("<tt>") || head.contains(":tt ")))
&& (head.contains("ns/ttml") || head.contains("ttaf1"))
@@ -262,7 +271,7 @@ pub fn detect(bytes: &[u8], ext: Option<&str>) -> Option<Format> {
match ext.as_deref() {
Some("srt") if has_arrow_timing || head.is_empty() => Some(Format::Srt),
Some("vtt") if has_arrow_timing => Some(Format::WebVtt),
Some("srt" | "vtt" | "scc" | "mcc" | "stl" | "ttml" | "dfxp" | "xml") => None,
Some("srt" | "vtt" | "scc" | "mcc" | "stl" | "ttml" | "dfxp" | "xml" | "ass" | "ssa") => None,
_ if has_arrow_timing => Some(Format::Srt),
_ => None,
}
@@ -296,6 +305,7 @@ fn parse_unbounded(bytes: &[u8], format: Format) -> Result<Document> {
Format::Scc => scc::parse(&text),
Format::Mcc => mcc::parse(&text),
Format::Ttml | Format::Dfxp => ttml::parse(&text),
Format::Ass => ass::parse(&text),
Format::Stl => stl::parse(bytes),
}
}
@@ -333,6 +343,7 @@ pub fn write(doc: &Document, format: Format, opts: WriteOptions) -> Vec<u8> {
Format::Stl => stl::write(doc, opts.rate, opts.program),
Format::Ttml => ttml::write(doc, ttml::Flavor::Imsc1, opts.rate, doc.language.as_deref().unwrap_or("")).into_bytes(),
Format::Dfxp => ttml::write(doc, ttml::Flavor::Dfxp, opts.rate, doc.language.as_deref().unwrap_or("")).into_bytes(),
Format::Ass => ass::write(doc).into_bytes(),
}
}
+142
View File
@@ -0,0 +1,142 @@
//! SubStation Alpha / Advanced SubStation Alpha: reading, writing, and ffmpeg as the reference
//! (oracle; skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`).
use craft_captions::{Cue, Document, Format, Tick, WriteOptions, detect, parse, write};
use std::process::Command;
const T: i64 = craft_captions::TICKS_PER_SECOND;
fn cs(n: i64) -> Tick {
Tick(n * (T / 100))
}
const SAMPLE: &str = "\u{feff}[Script Info]\n; a comment\nTitle: Test\nScriptType: v4.00+\n\n[V4+ Styles]\nFormat: Name, Fontname\nStyle: Default,Arial\n\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nComment: 0,0:00:00.00,0:00:01.00,Default,,0,0,0,,not a cue\nDialogue: 0,0:00:01.50,0:00:03.25,Default,Bob,0,0,0,,Hello, {\\i1}world{\\i0}\\Nsecond {\\b1}line{\\b0}\nDialogue: 0,1:02:03.04,1:02:04.5,Default,,0,0,0,,{\\pos(10,20)\\c&H0000FF&}Red\\hspace\\nsoft\nDialogue: 0,0:00:09.00,0:00:10.00,Default,,0,0,0,,{\\p1}m 0 0 l 100 0 100 100{\\p0}\n";
#[test]
fn reads_dialogue_lines_with_commas_overrides_and_line_breaks() {
let doc = parse(SAMPLE.as_bytes(), Format::Ass).unwrap();
assert_eq!(doc.cues.len(), 2);
assert_eq!(doc.cues[0].start, cs(150));
assert_eq!(doc.cues[0].end, cs(325));
assert_eq!(doc.cues[0].text, "Hello, <i>world</i>\nsecond <b>line</b>");
assert_eq!(doc.cues[0].speaker.as_deref(), Some("Bob"));
// 1:02:03.04, a one-digit fraction, an override block dropped, \h and \n.
assert_eq!(doc.cues[1].start, Tick((3600 + 120 + 3) * T + 4 * (T / 100)));
assert_eq!(doc.cues[1].end, Tick((3600 + 120 + 4) * T + T / 2));
assert_eq!(doc.cues[1].text, "Red\u{a0}space soft");
assert!(doc.warnings.iter().any(|w| w.contains("vector drawing")), "{:?}", doc.warnings);
}
#[test]
fn ssa_v4_files_read_through_their_own_format_line() {
let ssa = "[Script Info]\nScriptType: v4.00\n\n[V4 Styles]\nFormat: Name\n\n[Events]\nFormat: Marked, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nDialogue: Marked=0,0:00:01.00,0:00:02.00,*Default,,0000,0000,0000,,Old style\n";
let doc = parse(ssa.as_bytes(), Format::Ass).unwrap();
assert_eq!((doc.cues[0].start, doc.cues[0].end, doc.cues[0].text.as_str()), (cs(100), cs(200), "Old style"));
}
#[test]
fn write_then_read_keeps_times_text_and_speaker() {
let cues = vec![
Cue { start: cs(100), end: cs(250), text: "Line one\n<i>line two</i>".into(), speaker: Some("Ann".into()), ..Default::default() },
Cue {
start: Tick(7200 * T + 99 * (T / 100)),
end: Tick(7203 * T),
text: "<b>bold</b> and <u>under</u> {braces}".into(),
..Default::default()
},
];
let doc = Document { cues, ..Default::default() };
let bytes = write(&doc, Format::Ass, WriteOptions::default());
assert_eq!(detect(&bytes, Some("ass")), Some(Format::Ass));
let back = parse(&bytes, Format::Ass).unwrap();
assert_eq!(back.cues[0], doc.cues[0]);
assert_eq!(back.cues[1].start, doc.cues[1].start);
// Braces are written full-width, as ASS reads `{` as the start of an override block.
assert_eq!(back.cues[1].text, "<b>bold</b> and <u>under</u> \u{ff5b}braces\u{ff5d}");
}
#[test]
fn files_without_an_events_section_are_not_ass() {
assert!(parse(b"[Script Info]\nTitle: x\n", Format::Ass).is_err());
assert!(parse(b"hello", Format::Ass).is_err());
assert_eq!(detect(b"hello", Some("ass")), None);
}
#[test]
fn bad_lines_are_skipped_with_a_warning() {
let text = "[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nDialogue: 0,garbage,0:00:02.00,Default,,0,0,0,,x\nDialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,ok\n";
let doc = parse(text.as_bytes(), Format::Ass).unwrap();
assert_eq!(doc.cues.len(), 1);
assert_eq!(doc.warnings.len(), 1);
}
fn ffmpeg_run(ff: &std::path::Path, args: &[&str]) {
let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg");
assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr));
}
const SRT: &str = "1\n00:00:01,500 --> 00:00:03,250\nHello, <i>world</i>\nsecond <b>line</b>\n\n2\n00:00:04,000 --> 00:00:05,990\nPlain, with a comma\n\n3\n01:00:00,010 --> 01:00:02,999\n<u>Under</u> and <i>italic <b>both</b></i>\n";
#[test]
fn we_read_what_ffmpeg_writes() {
let Some(ff) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("captions_ass");
let (srt, ass) = (dir.join("in.srt"), dir.join("ffmpeg.ass"));
std::fs::write(&srt, SRT).expect("write");
ffmpeg_run(&ff, &["-i", srt.to_str().expect("path"), ass.to_str().expect("path")]);
let from_ass = parse(&std::fs::read(&ass).expect("read"), Format::Ass).expect("parse ass");
let from_srt = parse(SRT.as_bytes(), Format::Srt).expect("parse srt");
assert_eq!(from_ass.cues.len(), from_srt.cues.len());
for (a, s) in from_ass.cues.iter().zip(&from_srt.cues) {
// ASS times are centiseconds; the SRT ones round to them.
assert_eq!(a.start, cs((s.start.0 + T / 200) / (T / 100)), "start of {:?}", s.text);
assert_eq!(a.end, cs((s.end.0 + T / 200) / (T / 100)), "end of {:?}", s.text);
assert_eq!(a.text, s.text);
}
}
#[test]
fn ffmpeg_reads_what_we_write() {
let Some(ff) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("captions_ass");
let mut doc = parse(SRT.as_bytes(), Format::Srt).expect("parse srt");
doc.cues.push(Cue { start: cs(400_000), end: cs(400_100), text: r"C:\New\notes\hello and \N \n \h".into(), ..Default::default() });
let (ass, srt) = (dir.join("ours.ass"), dir.join("back.srt"));
std::fs::write(&ass, write(&doc, Format::Ass, WriteOptions::default())).expect("write");
ffmpeg_run(&ff, &["-i", ass.to_str().expect("path"), srt.to_str().expect("path")]);
let theirs = parse(&std::fs::read(&srt).expect("read"), Format::Srt).expect("parse back");
assert_eq!(theirs.cues.len(), doc.cues.len());
for (t, d) in theirs.cues.iter().zip(&doc.cues) {
assert_eq!(t.start, cs((d.start.0 + T / 200) / (T / 100)));
assert_eq!(t.end, cs((d.end.0 + T / 200) / (T / 100)));
assert_eq!(t.text, d.text, "text of the cue at {:?}", d.start);
}
}
#[test]
fn literal_backslashes_survive_ass_round_trip() {
let text = r"C:\New\notes\hello and \N \n \h";
let doc = Document { cues: vec![Cue { start: cs(100), end: cs(200), text: text.into(), ..Default::default() }], ..Default::default() };
let bytes = write(&doc, Format::Ass, WriteOptions::default());
assert_eq!(parse(&bytes, Format::Ass).unwrap().cues[0].text, text);
}
#[test]
fn carriage_returns_cannot_create_dialogue_records() {
let doc = Document {
cues: vec![Cue {
start: cs(100),
end: cs(200),
text: "first\rsecond\r\nthird".into(),
speaker: Some("Ann\rOther".into()),
..Default::default()
}],
..Default::default()
};
let bytes = write(&doc, Format::Ass, WriteOptions::default());
assert!(!bytes.contains(&b'\r'));
let back = parse(&bytes, Format::Ass).unwrap();
assert_eq!(back.cues.len(), 1);
assert_eq!(back.cues[0].text, "first\nsecond\nthird");
assert_eq!(back.cues[0].speaker.as_deref(), Some("Ann Other"));
}
+1
View File
@@ -1,3 +1,4 @@
mod ass;
mod limits;
mod literal_roundtrips;
mod mcc_708_timing;
+12
View File
@@ -424,6 +424,18 @@ fn shipped_cmyk(bytes: &[u8], b: Builtin) -> Profile {
})
}
/// Generates the compact ICC v2.1 sRGB matrix/TRC profile used by PDFCraft.
///
/// Unlike [`Builtin::Srgb`]'s v4 profile, this uses a 1024-sample tone curve and
/// v2 `desc`/`text` tags for consumers that require a v2 output intent. The legacy
/// description `sRGB (PdfCraft)` is retained to preserve existing document bytes.
/// The generated profile contains no external assets; callers choose where it is
/// appropriate (including their own PDF/A conformance policy).
/// All sizes are fixed; no input-controlled allocation or recursion is involved.
pub fn srgb_v2() -> Vec<u8> {
crate::builtin_v2::srgb()
}
#[cfg(test)]
mod tests {
use super::*;
+143
View File
@@ -0,0 +1,143 @@
//! A small sRGB ICC profile (version 2, display class, matrix/TRC), written from the published
//! sRGB primaries (IEC 61966-2-1) adapted to D50, with the sRGB tone curve sampled at 1024
//! points. Used as the PDF/A output intent's destination profile.
fn s15f16(v: f64) -> [u8; 4] {
((v * 65536.0).round() as i32).to_be_bytes()
}
fn xyz(x: f64, y: f64, z: f64) -> Vec<u8> {
let mut t = b"XYZ \0\0\0\0".to_vec();
t.extend(s15f16(x));
t.extend(s15f16(y));
t.extend(s15f16(z));
t
}
fn desc(text: &str) -> Vec<u8> {
let mut t = b"desc\0\0\0\0".to_vec();
let ascii: Vec<u8> = text.bytes().chain(std::iter::once(0)).collect();
t.extend((ascii.len() as u32).to_be_bytes());
t.extend(&ascii);
// No Unicode or ScriptCode descriptions.
t.extend([0u8; 4 + 4]);
t.extend([0u8; 2 + 1 + 67]);
t
}
fn text(text: &str) -> Vec<u8> {
let mut t = b"text\0\0\0\0".to_vec();
t.extend(text.bytes());
t.push(0);
t
}
fn curve() -> Vec<u8> {
const N: usize = 1024;
let mut t = b"curv\0\0\0\0".to_vec();
t.extend((N as u32).to_be_bytes());
for i in 0..N {
let v = i as f64 / (N - 1) as f64;
let lin = if v <= 0.04045 { v / 12.92 } else { ((v + 0.055) / 1.055).powf(2.4) };
t.extend(((lin * 65535.0).round() as u16).to_be_bytes());
}
t
}
/// Fixed-size profile bytes; all tag sizes and loop counts are constants.
pub fn srgb() -> Vec<u8> {
// sRGB primaries, Bradford-adapted to the D50 profile connection space.
let tags: Vec<(&[u8; 4], Vec<u8>)> = vec![
(b"desc", desc("sRGB (PdfCraft)")),
(b"cprt", text("No copyright, use freely")),
(b"wtpt", xyz(0.9642, 1.0, 0.8249)),
(b"rXYZ", xyz(0.4361, 0.2225, 0.0139)),
(b"gXYZ", xyz(0.3851, 0.7169, 0.0971)),
(b"bXYZ", xyz(0.1431, 0.0606, 0.7141)),
(b"rTRC", curve()),
];
// gTRC and bTRC share rTRC's data.
let count = tags.len() + 2;
let table_len = 4 + count * 12;
let mut offset = 128 + table_len;
let mut table = (count as u32).to_be_bytes().to_vec();
let mut data = Vec::new();
let mut trc = (0, 0);
for (sig, body) in &tags {
let len = body.len();
table.extend(*sig);
table.extend((offset as u32).to_be_bytes());
table.extend((len as u32).to_be_bytes());
if *sig == b"rTRC" {
trc = (offset, len);
}
data.extend(body);
// Tags start on 4-byte boundaries.
let pad = (4 - len % 4) % 4;
data.extend(std::iter::repeat_n(0u8, pad));
offset += len + pad;
}
for sig in [b"gTRC", b"bTRC"] {
table.extend(sig);
table.extend((trc.0 as u32).to_be_bytes());
table.extend((trc.1 as u32).to_be_bytes());
}
let size = 128 + table.len() + data.len();
let mut h = Vec::with_capacity(size);
h.extend((size as u32).to_be_bytes());
h.extend(b"\0\0\0\0"); // preferred CMM
h.extend([2, 0x10, 0, 0]); // version 2.1
h.extend(b"mntr");
h.extend(b"RGB ");
h.extend(b"XYZ ");
h.extend([0u8; 12]); // date
h.extend(b"acsp");
h.extend(b"\0\0\0\0"); // platform
h.extend([0u8; 4]); // flags
h.extend([0u8; 4]); // manufacturer
h.extend([0u8; 4]); // model
h.extend([0u8; 8]); // attributes
h.extend([0, 0, 0, 0]); // perceptual intent
h.extend(s15f16(0.9642));
h.extend(s15f16(1.0));
h.extend(s15f16(0.8249));
h.extend([0u8; 4]); // creator
h.resize(128, 0);
h.extend(table);
h.extend(data);
h
}
#[cfg(test)]
mod tests {
#[test]
fn parses_as_v2_with_shared_rgb_curves() {
let bytes = super::srgb();
let p = crate::Profile::parse(&bytes).unwrap();
assert_eq!(p.version, (2, 0x10));
assert_eq!(p.color_space, crate::ColorSpace::Rgb);
assert_eq!(p.pcs, crate::Pcs::Xyz);
assert_eq!(p.description, "sRGB (PdfCraft)");
let curves = p.trc.unwrap();
assert_eq!(curves[0], curves[1]);
assert_eq!(curves[1], curves[2]);
assert!(matches!(&curves[0], crate::Curve::Table(v) if v.len() == 1024 && v[0] == 0.0 && v[1023] == 1.0));
assert_eq!(bytes, super::srgb());
}
#[test]
fn profile_is_well_formed() {
let p = super::srgb();
assert_eq!(u32::from_be_bytes(p[0..4].try_into().unwrap()) as usize, p.len());
assert_eq!(&p[36..40], b"acsp");
assert_eq!(&p[12..20], b"mntrRGB ");
let n = u32::from_be_bytes(p[128..132].try_into().unwrap()) as usize;
assert_eq!(n, 9);
for i in 0..n {
let e = 132 + i * 12;
let off = u32::from_be_bytes(p[e + 4..e + 8].try_into().unwrap()) as usize;
let len = u32::from_be_bytes(p[e + 8..e + 12].try_into().unwrap()) as usize;
assert!(off.is_multiple_of(4) && off + len <= p.len(), "tag {i}");
}
}
}
+1
View File
@@ -20,6 +20,7 @@
#![forbid(unsafe_code)]
pub mod builtin;
mod builtin_v2;
pub mod clut;
pub mod curve;
pub mod gamut;
+87 -1
View File
@@ -531,12 +531,52 @@ pub fn write_cube(l: &LutFile) -> String {
s.push_str(&format!("DOMAIN_MAX {} {} {}\n", l.domain_max[0], l.domain_max[1], l.domain_max[2]));
}
s.push_str(&format!("LUT_3D_SIZE {}\n", l.size));
for c in l.data.as_chunks::<3>().0 {
cube_rows(s, l.data.as_chunks::<3>().0.iter().copied())
}
/// Writes a `.cube` file with a creator comment, section comments and an explicit input domain.
///
/// This layout is useful for exported LUTs; [`write_cube`] keeps its compact layout for embedded
/// tables. Values retain six decimal places, and their order and quantisation belong to the
/// caller. A default domain is written as `0.0` and `1.0` for compatibility with export consumers.
pub fn write_cube_commented(l: &LutFile, creator: &str) -> String {
let mut s = format!("#Created by: {creator}\nTITLE \"{}\"\n\n#LUT size\nLUT_3D_SIZE {}\n\n#data domain\n", l.title.replace('"', "'"), l.size);
if l.domain_is_default() {
s.push_str("DOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n");
} else {
s.push_str(&format!("DOMAIN_MIN {} {} {}\n", l.domain_min[0], l.domain_min[1], l.domain_min[2]));
s.push_str(&format!("DOMAIN_MAX {} {} {}\n", l.domain_max[0], l.domain_max[1], l.domain_max[2]));
}
s.push_str("\n#LUT data points\n");
cube_rows(s, l.data.as_chunks::<3>().0.iter().copied())
}
fn cube_rows(mut s: String, rows: impl Iterator<Item = [f32; 3]>) -> String {
for c in rows {
s.push_str(&format!("{:.6} {:.6} {:.6}\n", c[0], c[1], c[2]));
}
s
}
/// Annotated identity-domain CUBE export, streamed in red-fastest order without a table copy.
/// Callers supply exactly `size³` rows for a valid size (2..=[`MAX_SIZE`]), as with [`write_cube`].
/// Integer-depth exports clamp/round to 1/32768 steps; floating exports clamp without rounding.
pub fn write_cube_export(creator: &str, title: &str, size: usize, integer_depth: bool, rows: impl Iterator<Item = [f32; 3]>) -> String {
let s = format!(
"#Created by: {creator}\nTITLE \"{}\"\n\n#LUT size\nLUT_3D_SIZE {size}\n\n#data domain\nDOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n\n#LUT data points\n",
title.replace('"', "'")
);
cube_rows(
s,
rows.map(|c| {
c.map(|v| {
let v = v.clamp(0.0, 1.0);
if integer_depth { (v * 32768.0).round() / 32768.0 } else { v }
})
}),
)
}
fn luma(c: [f32; 3]) -> f32 {
0.299 * c[0] + 0.587 * c[1] + 0.114 * c[2]
}
@@ -602,6 +642,30 @@ pub fn builtin(id: &str) -> Option<LutFile> {
mod tests {
use super::*;
#[test]
fn commented_cube_preserves_export_header_and_rows() {
let mut lut = super::LutFile::identity(2).unwrap();
lut.title = "A \"look\"".into();
let text = super::write_cube_commented(&lut, "ExampleCraft");
assert!(text.starts_with("#Created by: ExampleCraft\nTITLE \"A 'look'\"\n\n#LUT size\nLUT_3D_SIZE 2\n\n#data domain\nDOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n\n#LUT data points\n"));
let parsed = super::parse_cube(&text).unwrap();
assert_eq!(parsed.data, lut.data);
assert_eq!(parsed.title, "A 'look'");
assert_eq!(text.lines().count(), 11 + 8);
let rows = |s: &str| s.lines().filter(|line| line.starts_with(|c: char| c.is_ascii_digit())).map(str::to_owned).collect::<Vec<_>>();
assert_eq!(rows(&text), rows(&super::write_cube(&lut)));
}
#[test]
fn commented_cube_keeps_nondefault_domain_and_sample_precision() {
let mut lut = super::LutFile::identity(2).unwrap();
lut.domain_min = [0.125, 0.25, 0.375];
lut.domain_max = [0.625, 0.75, 0.875];
lut.data[0] = 0.833344;
let parsed = super::parse_cube(&super::write_cube_commented(&lut, "ExampleCraft")).unwrap();
assert_eq!(parsed, lut);
}
#[test]
fn cube_title_hashes_and_comment_quotes_are_distinct() {
let rows = "LUT_1D_SIZE 2\n0 0 0 # low\n1 1 1 # high\n";
@@ -1299,4 +1363,26 @@ LUT_3D_SIZE 2
assert_eq!(back.domain_min, l.domain_min, "the written table must mean the same");
assert_eq!(back.domain_max, l.domain_max);
}
#[test]
fn annotated_cube_export_preserves_header_and_integer_precision() {
let mut lut = LutFile::identity(2).unwrap();
lut.title = "My \"Look\"".into();
lut.data[..3].copy_from_slice(&[1.0 / 6.0, 5.0 / 6.0, 160.0 / 255.0]);
let output = write_cube_export("PhotoCraft", &lut.title, lut.size, true, lut.data.as_chunks::<3>().0.iter().copied());
assert!(output.starts_with("#Created by: PhotoCraft\nTITLE \"My 'Look'\"\n\n#LUT size\nLUT_3D_SIZE 2\n\n#data domain\nDOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n\n#LUT data points\n0.166656 0.833344 0.627441\n"));
assert_eq!(output.lines().count(), 11 + 8);
let parsed = parse_cube(&output).unwrap();
assert_eq!(parsed.size, 2);
assert_eq!(&parsed.data[3..], &lut.data[3..]);
let float = write_cube_export("PhotoCraft", &lut.title, lut.size, false, lut.data.as_chunks::<3>().0.iter().copied());
assert!(float.contains("0.166667 0.833333 0.627451\n"));
}
#[test]
fn annotated_empty_title_and_float_clamping() {
let text = write_cube_export("Exporter", "", 2, false, std::iter::repeat_n([-0.5, 0.25, 1.5], 8));
assert!(text.contains("TITLE \"\"\n"));
let back = parse_cube(&text).unwrap();
assert_eq!(back.data, [0.0, 0.25, 1.0].repeat(8));
}
}
+1
View File
@@ -11,6 +11,7 @@
use std::io::Write as _;
pub mod model;
pub mod mtext;
pub mod paths;
mod version;
pub use version::Version;
+103
View File
@@ -0,0 +1,103 @@
//! MTEXT inline-escape handling independent of drawing and text layout.
//!
//! Unicode and MIF escapes are decoded to literal characters, with markup-significant
//! characters re-escaped so subsequent MTEXT parsers cannot treat them as commands.
/// Whether an inline command takes an argument terminated by `;`.
pub fn takes_arg(code: char) -> bool {
matches!(code, 'f' | 'F' | 'H' | 'W' | 'Q' | 'T' | 'A' | 'C' | 'c' | 'p')
}
/// Four hex digits at `chars[at..at + 4]`.
fn hex4(chars: &[char], at: usize) -> Option<u32> {
let digits = chars.get(at..at.checked_add(4)?)?;
digits.iter().try_fold(0u32, |acc, c| Some(acc * 16 + c.to_digit(16)?))
}
/// Push a decoded character so that the tokenizers read it as text, never as markup.
fn push_literal(out: &mut String, c: char) {
if matches!(c, '\\' | '{' | '}') {
out.push('\\');
}
out.push(c);
}
/// Decode `\U+hhhh` (one UTF-16 unit; a surrogate pair gives one character, a lone surrogate
/// U+FFFD) and `\M+nhhhh` (double-byte East Asian characters) to the characters they stand
/// for. Malformed escapes remain unchanged for the caller to interpret.
/// An escaped backslash (`\\U+0041`) is not an escape.
pub fn unescape_codes(s: &str) -> std::borrow::Cow<'_, str> {
if !s.contains("\\U+") && !s.contains("\\M+") {
return std::borrow::Cow::Borrowed(s);
}
let chars: Vec<char> = s.chars().collect();
let mut out = String::with_capacity(s.len());
let mut i = 0;
while let Some(&c) = chars.get(i) {
if c != '\\' {
out.push(c);
i += 1;
continue;
}
let (n, plus) = (chars.get(i + 1).copied(), chars.get(i + 2).copied());
if n == Some('U') && plus == Some('+') {
if let Some(unit) = hex4(&chars, i + 3) {
i += 7;
let low = |at: usize| {
(chars.get(at) == Some(&'\\') && chars.get(at + 1) == Some(&'U') && chars.get(at + 2) == Some(&'+'))
.then(|| hex4(&chars, at + 3))
.flatten()
.filter(|u| (0xDC00..0xE000).contains(u))
};
let ch = if (0xD800..0xDC00).contains(&unit) {
match low(i) {
Some(lo) => {
i += 7;
char::from_u32(0x10000 + ((unit - 0xD800) << 10) + (lo - 0xDC00))
}
None => None,
}
} else {
char::from_u32(unit)
};
push_literal(&mut out, ch.unwrap_or('\u{fffd}'));
continue;
}
} else if n == Some('M') && plus == Some('+') && chars.get(i + 3).is_some_and(char::is_ascii_digit) && hex4(&chars, i + 4).is_some() {
push_literal(&mut out, crate::mif_escape_at(&chars, i).unwrap_or('\u{fffd}'));
i += 8;
continue;
}
// Any other backslash pair stays as it is (and an escaped backslash stays one).
out.push('\\');
i += 1;
if let Some(&next) = chars.get(i) {
out.push(next);
i += 1;
}
}
std::borrow::Cow::Owned(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn unicode_and_mif_escapes_remain_literal_markup() {
assert_eq!(unescape_codes(r"a\U+0041\U+D83D\U+DE00"), "aA😀");
assert_eq!(unescape_codes(r"\M+5BCFE"), "件");
assert_eq!(unescape_codes(r"\U+005C\U+007B\U+007D"), r"\\\{\}");
assert_eq!(unescape_codes(r"\\U+0041"), r"\\U+0041");
assert_eq!(unescape_codes(r"\U+12"), r"\U+12");
assert_eq!(unescape_codes(r"\U+D800"), "�");
}
#[test]
fn parameterized_commands_are_classified_without_relaxing_others() {
for c in "fFHWQTACcp".chars() {
assert!(takes_arg(c));
}
for c in ['S', 'P', 'Z', '\\'] {
assert!(!takes_arg(c));
}
}
}
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "craft-gzip"
description = "Streaming gzip writer with stored and compressed segments"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
flate2 = { version = "1", default-features = false, features = ["rust_backend"] }
+119
View File
@@ -0,0 +1,119 @@
//! Streaming gzip output with optional stored segments.
//!
//! Copyright (c) 2026 ArtCraft Team and the VectorCraft contributors.
//! Extracted from VectorCraft, licensed under MIT OR Apache-2.0.
//!
//! `flush` does not emit a deflate block; call [`Gz::finish`] to complete and flush the
//! stream. After an I/O error, discard the writer: the output may be incomplete.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
use flate2::{Compress, Compression, Crc, FlushCompress, Status};
use std::io::{self, Write};
/// Bytes of compressed output gathered before they go to the writer.
const OUT_CHUNK: usize = 64 << 10;
/// A gzip stream, written as [`flate2::write::GzEncoder`] at the default level writes it (the
/// same header and the same data; the deflate blocks are the same too where flate2 deflates with
/// miniz_oxide, not with zlib-rs, which writes them by how the data is fed), except that data which
/// is compressed already ([`Gz::packed`]) is stored as it is: the default level spends a second
/// or more per photo on it for next to nothing, and makes it slower to unpack. Where the level
/// changes the deflate blocks so far end with a sync flush and a fresh compressor writes on,
/// which makes one valid deflate stream that every reader unpacks.
pub struct Gz<W: Write> {
out: W,
deflate: Compress,
/// What `deflate` writes: stored blocks (packed data), else the default level.
stored: bool,
crc: Crc,
buf: Vec<u8>,
/// Bytes written (unpacked).
total: u64,
}
impl<W: Write> Gz<W> {
/// Write a gzip header and construct a writer.
pub fn new(mut out: W) -> io::Result<Self> {
// flate2's header for the default level: no name, no time, unknown OS.
out.write_all(&[0x1f, 0x8b, 8, 0, 0, 0, 0, 0, 0, 255])?;
Ok(Self {
out,
deflate: Compress::new(Compression::default(), false),
stored: false,
crc: Crc::new(),
buf: Vec::with_capacity(OUT_CHUNK),
total: 0,
})
}
/// Run the compressor over `input` with `flush` until it has taken it all (and, flushing,
/// written everything out).
fn deflate(&mut self, mut input: &[u8], flush: FlushCompress) -> io::Result<()> {
loop {
if self.buf.len() == self.buf.capacity() {
self.out.write_all(&self.buf)?;
self.buf.clear();
}
let (before_in, before_out) = (self.deflate.total_in(), self.deflate.total_out());
let status = self.deflate.compress_vec(input, &mut self.buf, flush).map_err(io::Error::other)?;
let taken = usize::try_from(self.deflate.total_in() - before_in).unwrap_or(input.len()).min(input.len());
input = input.get(taken..).unwrap_or_default();
let made = self.deflate.total_out() - before_out;
let full = self.buf.len() == self.buf.capacity();
match flush {
FlushCompress::None if input.is_empty() => return Ok(()),
FlushCompress::Finish if status == Status::StreamEnd => return Ok(()),
// A flush is done once it left room in the output.
FlushCompress::Sync if input.is_empty() && !full => return Ok(()),
_ => {}
}
if taken == 0 && made == 0 && !full {
return Err(io::Error::other("the compressor made no progress"));
}
}
}
/// Return the number of uncompressed bytes supplied.
pub fn written(&self) -> u64 {
self.total
}
/// What is written next is compressed already (stored as it is), or not (compressed at the
/// default level).
pub fn packed(&mut self, packed: bool) -> io::Result<()> {
if packed == self.stored {
return Ok(());
}
self.deflate(&[], FlushCompress::Sync)?;
self.deflate = Compress::new(if packed { Compression::none() } else { Compression::default() }, false);
self.stored = packed;
Ok(())
}
/// Complete the gzip trailer and flush the underlying writer.
pub fn finish(mut self) -> io::Result<()> {
self.deflate(&[], FlushCompress::Finish)?;
self.out.write_all(&self.buf)?;
self.out.write_all(&self.crc.sum().to_le_bytes())?;
self.out.write_all(&self.crc.amount().to_le_bytes())?;
self.out.flush()
}
}
impl<W: Write> Write for Gz<W> {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
self.write_all(buf)?;
Ok(buf.len())
}
fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
self.total = self.total.checked_add(buf.len() as u64).ok_or_else(|| io::Error::other("uncompressed byte count overflow"))?;
self.crc.update(buf);
self.deflate(buf, FlushCompress::None)
}
fn flush(&mut self) -> io::Result<()> {
// Flushing would end a deflate block: the stream is flushed when it is finished.
Ok(())
}
}
+77
View File
@@ -0,0 +1,77 @@
use std::io::{self, Read, Write};
use craft_gzip::Gz;
use flate2::{Compression, read::GzDecoder, write::GzEncoder};
fn decode(bytes: &[u8]) -> Vec<u8> {
let mut result = Vec::new();
GzDecoder::new(bytes).read_to_end(&mut result).unwrap();
result
}
#[test]
fn matches_flate2_without_mode_changes() {
let data = b"The quick brown fox jumps over the lazy dog. ".repeat(10000);
let mut expected = GzEncoder::new(Vec::new(), Compression::default());
let mut actual = Vec::new();
{
let mut gz = Gz::new(&mut actual).unwrap();
for chunk in data.chunks(131) {
expected.write_all(chunk).unwrap();
gz.write_all(chunk).unwrap();
}
assert_eq!(gz.written(), data.len() as u64);
gz.finish().unwrap();
}
assert_eq!(actual, expected.finish().unwrap());
assert_eq!(decode(&actual), data);
}
#[test]
fn mixed_segments_round_trip_and_stored_bytes_remain_uncompressed() {
let plain = b"repeat me ".repeat(20000);
let packed: Vec<u8> = (0..200_000).map(|i| (i * 31) as u8).collect();
let mut bytes = Vec::new();
{
let mut gz = Gz::new(&mut bytes).unwrap();
gz.write_all(&plain).unwrap();
gz.packed(true).unwrap();
gz.packed(true).unwrap();
gz.write_all(&packed).unwrap();
gz.packed(false).unwrap();
gz.write_all(&plain).unwrap();
assert_eq!(gz.written(), (plain.len() * 2 + packed.len()) as u64);
gz.finish().unwrap();
}
let expected = [plain.as_slice(), packed.as_slice(), plain.as_slice()].concat();
assert_eq!(decode(&bytes), expected);
assert!(bytes.windows(1024).any(|window| window == &packed[..1024]));
assert!(bytes.len() < expected.len());
}
struct FailAfter {
remaining: usize,
}
impl Write for FailAfter {
fn write(&mut self, data: &[u8]) -> io::Result<usize> {
if self.remaining == 0 {
return Err(io::Error::other("injected failure"));
}
let n = self.remaining.min(data.len());
self.remaining -= n;
Ok(n)
}
fn flush(&mut self) -> io::Result<()> {
Err(io::Error::other("injected flush failure"))
}
}
#[test]
fn propagates_header_body_and_flush_failures() {
assert!(Gz::new(FailAfter { remaining: 0 }).is_err());
let mut body = Gz::new(FailAfter { remaining: 10 }).unwrap();
body.packed(true).unwrap();
assert!(body.write_all(&vec![42; 200_000]).is_err());
let empty = Gz::new(FailAfter { remaining: usize::MAX }).unwrap();
assert_eq!(empty.finish().unwrap_err().to_string(), "injected flush failure");
}
+2
View File
@@ -47,6 +47,8 @@ exr = { version = "1.73", default-features = false, features = ["rayon"] }
proptest = { workspace = true }
image = { version = "0.25", default-features = false, features = ["png", "jpeg", "tiff"] }
sha2 = { version = "0.10", default-features = false, features = ["std"] }
craft-media-testkit = { workspace = true }
[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
craft-video = { workspace = true, features = ["av1-decode"] }
jxl-oxide = { version = "=0.12.6", default-features = false, features = ["rayon"] }
+123
View File
@@ -0,0 +1,123 @@
JPEG encoding dependency: jpeg-encoder 0.6.1
Source: https://crates.io/crates/jpeg-encoder/0.6.1
Declared license: (MIT OR Apache-2.0) AND IJG.
This software is based in part on the work of the Independent JPEG Group.
The MIT license and unaltered upstream IJG and SIMD notices follow. The Apache-2.0
alternative is also retained in licenses/jpeg-encoder-0.6.1 at the repository root
(https://github.com/storytold/craft-libs/tree/main/licenses/jpeg-encoder-0.6.1).
The dependency is used unmodified; no encoder implementation is vendored here.
LICENSE-MIT
Copyright (c) 2021 Volker Ströbel <volkerstroebel@mysurdity.de>
Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the
Software without restriction, including without
limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
Original src/fdct.rs opening notice
/*
* Ported from mozjpeg to rust
*
* This file was part of the Independent JPEG Group's software:
* Copyright (C) 1991-1996, Thomas G. Lane.
* libjpeg-turbo Modifications:
* Copyright (C) 2015, 2020, D. R. Commander.
*
* Conditions of distribution and use:
* In plain English:
*
* 1. We don't promise that this software works. (But if you find any bugs,
* please let us know!)
* 2. You can use this software for whatever you want. You don't have to pay us.
* 3. You may not pretend that you wrote this software. If you use it in a
* program, you must acknowledge somewhere in your documentation that
* you've used the IJG code.
*
* In legalese:
*
* The authors make NO WARRANTY or representation, either express or implied,
* with respect to this software, its quality, accuracy, merchantability, or
* fitness for a particular purpose. This software is provided "AS IS", and you,
* its user, assume the entire risk as to its quality and accuracy.
*
* This software is copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding.
* All Rights Reserved except as specified below.
*
* Permission is hereby granted to use, copy, modify, and distribute this
* software (or portions thereof) for any purpose, without fee, subject to these
* conditions:
* (1) If any part of the source code for this software is distributed, then this
* README file must be included, with this copyright and no-warranty notice
* unaltered; and any additions, deletions, or changes to the original files
* must be clearly indicated in accompanying documentation.
* (2) If only executable code is distributed, then the accompanying
* documentation must state that "this software is based in part on the work of
* the Independent JPEG Group".
* (3) Permission for use of this software is granted only if the user accepts
* full responsibility for any undesirable consequences; the authors accept
* NO LIABILITY for damages of any kind.
*
* These conditions apply to any software derived from or based on the IJG code,
* not just to the unmodified library. If you use our work, you ought to
* acknowledge us.
*
* Permission is NOT granted for the use of any IJG author's name or company name
* in advertising or publicity relating to this software or products derived from
* it. This software may be referred to only as "the Independent JPEG Group's
* software".
*
* We specifically permit and encourage the use of this software as the basis of
* commercial products, provided that all warranty or liability claims are
* assumed by the product vendor.
*
* This file contains a slower but more accurate integer implementation of the
* forward DCT (Discrete Cosine Transform).
*
* A 2-D DCT can be done by 1-D DCT on each row followed by 1-D DCT
* on each column. Direct algorithms are also available, but they are
* much more complex and seem not to be any faster when reduced to code.
*
* This implementation is based on an algorithm described in
* C. Loeffler, A. Ligtenberg and G. Moschytz, "Practical Fast 1-D DCT
* Algorithms with 11 Multiplications", Proc. Int'l. Conf. on Acoustics,
* Speech, and Signal Processing 1989 (ICASSP '89), pp. 988-991.
* The primary algorithm described there uses 11 multiplies and 29 adds.
* We use their alternate method with 12 multiplies and 32 adds.
* The advantage of this method is that no data path contains more than one
* multiplication; this allows a very simple and accurate implementation in
* scaled fixed-point arithmetic, with a minimal number of shifts.
*/
Original src/avx2/fdct.rs opening notice
/*
* Ported from mozjpeg / jfdctint-avx2.asm to rust
* Copyright 2009 Pierre Ossman <ossman@cendio.se> for Cendio AB
* Copyright (C) 2009, 2016, 2018, 2020, D. R. Commander.
*
* Based on the x86 SIMD extension for IJG JPEG library
* Copyright (C) 1999-2006, MIYASAKA Masaru.
*/
+10
View File
@@ -56,6 +56,7 @@ craft-image-codecs = { git = "https://github.com/storytold/craft-libs", rev = "<
| Cineon | yes | yes | U16 (10-bit code values read and written exactly through U16) | Gray, RGB | no | no | no | no | no | no | no | built in |
| DICOM | yes | **no** | U8, U16 | Gray, RGB | no | no | no | no | no | no | n/a | built in |
| Amiga IFF (ILBM/PBM) | yes | yes (24-bit ILBM) | U8 | RGB, RGBA | yes (1-bit mask plane on write) | no | no | no | no | no | no | built in |
| JPEG-LS (`.jls`) | yes (any NEAR; one scan per component) | yes (lossless) | U8, U16 | Gray, RGB | no | no | no | no | no | no | no | built in |
| AVIF | **no** | only with feature `avif` | U8 | RGB, RGBA | yes | no | no | no | no | no | yes | `image` + `ravif` |
| HEIF/HEIC | with feature `heif` | **no** | U8, U16 (10/12-bit decodes to U16) | RGB, RGBA | yes (auxiliary alpha) | yes (`colr` prof) | yes | yes | no | no | n/a | `heic-rs` |
@@ -339,3 +340,12 @@ folder, copy the five files from that commit into `corpus/exr/`, or run
at commit `74330157cb601573ae4523a95bb9132822fc3918` and copy its `corpus/exr/` here, as CI does.
The images are not committed here; OpenEXR distributes them under its
[license](https://github.com/AcademySoftwareFoundation/openexr/blob/69b2604fc76e370615438bdc8d2cd95b9349c12e/LICENSE.md).
## Redistribution notices
JPEG encoding uses `jpeg-encoder` 0.6.1, including work from the Independent JPEG Group.
Retain this crate's [NOTICE](NOTICE) with binary distributions using that encoder. It includes
its MIT license, the IJG acknowledgement and original IJG/SIMD notices. Both upstream license
alternatives and source checksums are retained in
[`licenses/jpeg-encoder-0.6.1`](https://github.com/storytold/craft-libs/tree/main/licenses/jpeg-encoder-0.6.1)
at the repository root.
+145
View File
@@ -0,0 +1,145 @@
//! Header-only BMP dimensions and pixel-data coverage, without allocating a canvas.
/// Coverage of the declared pixel array. Row byte counts include row padding; RLE coverage
/// counts the pixels drawn by commands and may be smaller than the canvas.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Coverage {
pub pixels: u64,
pub row_bytes: Option<(u64, u64)>,
}
/// Inspect pixel data for the given dimensions without decoding a bitmap. The row tuple is
/// `(available, needed)`; callers choose their own sparse-canvas and allocation policy.
pub fn coverage(bytes: &[u8], w: u32, h: u32) -> Coverage {
match bmp_layout(bytes) {
BmpLayout::Rle { offset, rle4 } => Coverage { pixels: bmp_rle_pixels(bytes, offset, rle4, w, h), row_bytes: None },
BmpLayout::Rows { offset, bits } => {
let needed = u64::from(w).saturating_mul(u64::from(bits)).div_ceil(32).saturating_mul(4).saturating_mul(u64::from(h));
let held = bytes.len().saturating_sub(offset) as u64;
Coverage { pixels: u64::from(w) * u64::from(h), row_bytes: Some((held, needed)) }
}
}
}
enum BmpLayout {
/// RLE8 or RLE4 commands.
Rle { offset: usize, rle4: bool },
/// Rows of `bits` per pixel, each padded to 4 bytes.
Rows { offset: usize, bits: u16 },
}
/// The layout the decoder reads, from the file header and the bitmap header: a 12-byte core header
/// (bits per pixel at 24, never compressed) or a 40-byte or larger one (bits at 28, compression at
/// 30). Fields the decoder would have refused are read as 1 bit per pixel at offset 0, the most
/// lenient layout.
fn bmp_layout(bytes: &[u8]) -> BmpLayout {
let u16_at = |i: usize| bytes.get(i..i.checked_add(2)?).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes);
let u32_at = |i: usize| bytes.get(i..i.checked_add(4)?).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes);
let offset = u32_at(10).and_then(|o| usize::try_from(o).ok()).unwrap_or(0);
let (bits, compression) = match u32_at(14) {
Some(12) => (u16_at(24), Some(0)),
_ => (u16_at(28), u32_at(30)),
};
match compression {
Some(1) => BmpLayout::Rle { offset, rle4: false },
Some(2) => BmpLayout::Rle { offset, rle4: true },
_ => BmpLayout::Rows { offset, bits: bits.filter(|&b| b > 0).unwrap_or(1) },
}
}
/// The pixels an RLE8 or RLE4 BMP's commands draw on a `w` × `h` canvas, read the way the decoder
/// paints them: a run is clipped at the end of its row, an end-of-row code moves to the next row, a
/// delta skips pixels (left blank), and an end-of-bitmap code, a truncated command or the last row
/// ends the picture. Every command takes at least 2 bytes, so the walk is linear in the file.
fn bmp_rle_pixels(bytes: &[u8], offset: usize, rle4: bool, w: u32, h: u32) -> u64 {
let (w, h) = (u64::from(w), u64::from(h));
let (mut pos, mut x, mut y, mut covered) = (offset, 0u64, 0u64, 0u64);
while y < h {
let (Some(&count), Some(&value)) = (bytes.get(pos), bytes.get(pos.saturating_add(1))) else {
break;
};
pos = pos.saturating_add(2);
match (count, value) {
// end of row
(0, 0) => (x, y) = (0, y.saturating_add(1)),
// end of bitmap
(0, 1) => break,
// delta: right and down
(0, 2) => {
let (Some(&dx), Some(&dy)) = (bytes.get(pos), bytes.get(pos.saturating_add(1))) else {
break;
};
pos = pos.saturating_add(2);
(x, y) = (x.saturating_add(u64::from(dx)), y.saturating_add(u64::from(dy)));
}
// absolute: `value` pixels stored one per byte (RLE8) or nibble (RLE4), padded to 2 bytes
(0, n) => {
let len = if rle4 { usize::from(n).div_ceil(2) } else { usize::from(n) };
pos = pos.saturating_add(len + (len & 1));
if pos > bytes.len() {
break;
}
covered = covered.saturating_add(u64::from(n).min(w.saturating_sub(x)));
x = x.saturating_add(u64::from(n));
}
// a run of `count` pixels
(n, _) => {
covered = covered.saturating_add(u64::from(n).min(w.saturating_sub(x)));
x = x.saturating_add(u64::from(n));
}
}
}
covered
}
/// Reads BMP `(width, height)` from the DIB header without allocating.
pub fn dimensions(bytes: &[u8]) -> Option<(u32, u32)> {
if bytes.get(0..2) != Some(b"BM") {
return None;
}
let dib = u32::from_le_bytes(bytes.get(14..18)?.try_into().ok()?);
let (w, h) = if dib == 12 {
(u16::from_le_bytes(bytes.get(18..20)?.try_into().ok()?) as u32, u16::from_le_bytes(bytes.get(20..22)?.try_into().ok()?) as u32)
} else {
let w = i32::from_le_bytes(bytes.get(18..22)?.try_into().ok()?);
let h = i32::from_le_bytes(bytes.get(22..26)?.try_into().ok()?);
(u32::try_from(w).ok()?, h.unsigned_abs())
};
Some((w, h))
}
#[cfg(test)]
mod tests {
use super::*;
fn bmp(compression: u32, pixels: &[u8]) -> Vec<u8> {
let mut b = vec![0; 54];
b[..2].copy_from_slice(b"BM");
b[10..14].copy_from_slice(&54u32.to_le_bytes());
b[14..18].copy_from_slice(&40u32.to_le_bytes());
b[18..22].copy_from_slice(&4i32.to_le_bytes());
b[22..26].copy_from_slice(&2i32.to_le_bytes());
b[28..30].copy_from_slice(&8u16.to_le_bytes());
b[30..34].copy_from_slice(&compression.to_le_bytes());
b.extend_from_slice(pixels);
b
}
#[test]
fn dimensions_and_padded_rows() {
let b = bmp(0, &[0; 7]);
assert_eq!(dimensions(&b), Some((4, 2)));
assert_eq!(coverage(&b, 4, 2), Coverage { pixels: 8, row_bytes: Some((7, 8)) });
assert_eq!(dimensions(&b[..20]), None);
}
#[test]
fn rle_counts_clipped_runs_deltas_and_complete_absolute_blocks() {
let b = bmp(1, &[3, 7, 0, 0, 0, 2, 1, 0, 0, 3, 1, 2, 3, 0, 0, 1]);
assert_eq!(coverage(&b, 4, 2).pixels, 6);
let truncated = bmp(1, &[0, 4, 1, 2]);
assert_eq!(coverage(&truncated, 4, 2).pixels, 0);
let nibble = bmp(2, &[0, 3, 0x12, 0x30, 0, 1]);
assert_eq!(coverage(&nibble, 4, 2).pixels, 3);
}
}
+1
View File
@@ -13,6 +13,7 @@ pub(crate) mod heif;
pub(crate) mod iff;
pub(crate) mod jp2;
pub(crate) mod jpeg;
pub(crate) mod jpegls;
pub(crate) mod jxl;
pub(crate) mod pcx;
pub(crate) mod png;
+107 -5
View File
@@ -25,12 +25,17 @@ fn pq_encode(nits: f32) -> f32 {
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
fn hlg_signal(rgb: [f32; 3]) -> [f32; 3] {
const K: [f32; 3] = [0.2627, 0.6780, 0.0593];
const GAMMA: f32 = 1.2;
const A: f32 = 0.17883277;
const B: f32 = 0.28466892;
const C: f32 = 0.559_910_7;
rgb.map(|v| {
let s = if v.is_finite() { v.clamp(0.0, 12.0) / 12.0 } else { 0.0 };
if s <= 1.0 / 12.0 { (3.0 * s).sqrt() } else { A * (12.0 * s - B).ln() + C }
let display = rgb.map(|v| (if v.is_finite() { v.max(0.0) } else { 0.0 }) * (HDR_REFERENCE_WHITE_NITS / crate::cicp::HLG_PEAK_NITS));
let y = K[0] * display[0] + K[1] * display[1] + K[2] * display[2];
let inverse_ootf = if y > 0.0 { y.powf((1.0 - GAMMA) / GAMMA) } else { 0.0 };
display.map(|v| {
let scene = (v * inverse_ootf).clamp(0.0, 1.0);
if scene <= 1.0 / 12.0 { (3.0 * scene).sqrt() } else { A * (12.0 * scene - B).ln() + C }
})
}
@@ -39,8 +44,14 @@ fn hlg_signal(rgb: [f32; 3]) -> [f32; 3] {
pub fn encode_avif_with_speed(img: &Image, quality: u8, speed: u8) -> Result<Vec<u8>, CodecError> {
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
{
let mut enc =
ravif::Encoder::new().with_quality(f32::from(quality.clamp(1, 100))).with_speed(speed.clamp(1, 10)).with_bit_depth(ravif::BitDepth::Ten);
let mut enc = ravif::Encoder::new()
.with_quality(f32::from(quality.clamp(1, 100)))
.with_alpha_quality(f32::from(quality.clamp(1, 100)))
.with_speed(speed.clamp(1, 10))
.with_bit_depth(ravif::BitDepth::Ten);
if let Some(exif) = img.meta.exif.as_deref() {
enc = enc.with_exif(exif);
}
let alpha_mode = if img.layout().has_alpha() { ravif::AlphaColorMode::UnassociatedClean } else { ravif::AlphaColorMode::UnassociatedDirty };
enc = enc.with_alpha_color_mode(alpha_mode);
let w = img.width() as usize;
@@ -209,3 +220,94 @@ pub fn encode_avif_hdr(
Err(CodecError::unsupported(Format::Avif, "AVIF encoding is not available in this build"))
}
}
#[cfg(test)]
mod tests {
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
#[test]
fn sdr_avif_uses_requested_alpha_quality() {
use crate::{ChannelLayout, Image};
let pixels: Vec<ravif::RGBA8> = (0..1024).map(|i| ravif::RGBA8::new(100, 120, 140, ((i * 37) % 256) as u8)).collect();
let samples: Vec<u8> = pixels.iter().flat_map(|p| [p.r, p.g, p.b, p.a]).collect();
let image = Image::from_u8(32, 32, ChannelLayout::Rgba, samples).unwrap();
let actual = super::encode_avif_with_speed(&image, 20, 10).unwrap();
let expected = ravif::Encoder::new()
.with_quality(20.0)
.with_alpha_quality(20.0)
.with_speed(10)
.with_bit_depth(ravif::BitDepth::Ten)
.with_alpha_color_mode(ravif::AlphaColorMode::UnassociatedClean)
.encode_rgba(ravif::Img::new(&pixels, 32, 32))
.unwrap()
.avif_file;
assert!(actual == expected, "encoded alpha must use the requested quality");
}
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
#[test]
fn sdr_avif_keeps_exif_metadata() {
use crate::{ChannelLayout, Image};
let exif = b"II*\0shared-avif-exif".to_vec();
let mut image = Image::from_u8(2, 1, ChannelLayout::Rgb, vec![20, 40, 60, 80, 100, 120]).unwrap();
image.meta.exif = Some(exif.clone());
let avif = super::encode_avif_with_speed(&image, 80, 8).unwrap();
assert!(avif.windows(exif.len()).any(|window| window == exif.as_slice()));
}
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
#[test]
fn hlg_mapping_matches_reference_white_and_peak() {
let white = super::hlg_signal([1.0; 3]);
assert!(white.iter().all(|&value| (value - 0.75).abs() < 0.005), "{white:?}");
let peak = super::hlg_signal([crate::cicp::HLG_PEAK_NITS / super::HDR_REFERENCE_WHITE_NITS; 3]);
assert!(peak.iter().all(|&value| (value - 1.0).abs() < 0.005), "{peak:?}");
let invalid = super::hlg_signal([f32::NAN, -1.0, f32::INFINITY]);
assert_eq!(invalid, [0.0; 3]);
}
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
#[test]
fn hlg_encoded_output_signals_bt2020_hlg() {
let avif = super::encode_avif_hdr(1, 1, &[1.0; 3], 100, 10, None, super::HdrTransfer::Hlg).unwrap();
let nclx = avif.windows(4).position(|window| window == b"nclx").expect("the AVIF has nclx color metadata");
let color = avif.get(nclx + 4..nclx + 11).expect("complete nclx color metadata");
assert_eq!(&color[..2], &[0, 9], "BT.2020 primaries");
assert_eq!(&color[2..4], &[0, 18], "BT.2100 HLG transfer");
assert_eq!(&color[4..6], &[0, 9], "BT.2020 non-constant luminance matrix");
assert!(!avif.windows(4).any(|window| window == b"clli"), "HLG does not signal PQ content-light metadata");
}
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
#[test]
fn hlg_encoded_pixels_preserve_reference_white_and_peak() {
let mut rgb = Vec::new();
for _ in 0..32 {
for x in 0..64 {
let level = if x < 32 { 1.0 } else { crate::cicp::HLG_PEAK_NITS / super::HDR_REFERENCE_WHITE_NITS };
rgb.extend_from_slice(&[level; 3]);
}
}
let avif = super::encode_avif_hdr(64, 32, &rgb, 100, 10, None, super::HdrTransfer::Hlg).unwrap();
let mut offset = 0;
let payload = loop {
let header = avif.get(offset..offset + 8).expect("complete AVIF box header");
let size = u32::from_be_bytes(header[..4].try_into().unwrap()) as usize;
assert!(size >= 8 && offset + size <= avif.len(), "valid AVIF box size");
if &header[4..] == b"mdat" {
break &avif[offset + 8..offset + size];
}
offset += size;
};
let mut decoder = craft_video::av1::decode::Decoder::new();
let mut frames = decoder.decode(payload).unwrap();
frames.extend(decoder.flush_result().unwrap());
let luma = &frames.first().expect("encoded AV1 frame").planes[0];
assert!((i32::from(luma[16 * 64 + 16]) - 767).abs() <= 5, "diffuse white");
assert!((i32::from(luma[16 * 64 + 48]) - 1023).abs() <= 5, "peak white");
}
}
+870
View File
@@ -0,0 +1,870 @@
//! JPEG-LS (ITU-T T.87 | ISO/IEC 14495-1, "LOCO-I"): lossless and near-lossless gray and RGB
//! images, 2 to 16 bits per sample.
//!
//! Read: baseline JPEG-LS with the default or `LSE`-preset coding parameters, any `NEAR`, and
//! scans that code one component each (`ILV` 0), which is also how this module writes. Line- and
//! sample-interleaved scans, colour transforms and mapping tables are reported as unsupported.
//! Write: lossless (`NEAR` 0), 8 or 16 bits, gray or RGB, one scan per component.
//!
//! Samples of 9 to 15 bits are scaled to 16 bits on read (the top bits are repeated into the low
//! ones), so a decoded image always spans the full range of its sample type.
use crate::error::CodecError;
use crate::fidelity::Plan;
use crate::format::Format;
use crate::image::{ChannelLayout, Image, SampleType};
use crate::options::Limits;
const F: Format = Format::JpegLs;
const SOF55: u8 = 0xF7;
const LSE: u8 = 0xF8;
const RESET_DEFAULT: i32 = 64;
const MIN_C: i32 = -128;
const MAX_C: i32 = 127;
/// `J[RUNindex]`: the log2 of the run length a run-index step codes.
const J: [u32; 32] = [0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 9, 10, 11, 12, 13, 14, 15];
/// Context slots: the regular contexts (365 of the 405 slots the index below can reach), then the two
/// run-interruption contexts.
const RI_BASE: usize = 405;
const CONTEXTS: usize = RI_BASE + 2;
fn bad(reason: impl std::fmt::Display) -> CodecError {
CodecError::malformed(F, reason)
}
/// Whether `b` is a JPEG-LS file: an SOI followed by marker segments up to an SOF55 frame header.
pub(crate) fn looks_like_jpegls(b: &[u8]) -> bool {
if !b.starts_with(&[0xFF, 0xD8]) {
return false;
}
let mut pos = 2;
for _ in 0..64 {
let (Some(&0xFF), Some(&marker)) = (b.get(pos), b.get(pos + 1)) else { return false };
match marker {
SOF55 => return true,
0xDA | 0xD9 => return false,
0xC0..=0xCF | 0xDB..=0xDF => return false,
0x01 | 0xD0..=0xD7 | 0xFF => pos += if marker == 0xFF { 1 } else { 2 },
_ => {
let Some(len) = b.get(pos + 2..pos + 4).map(|l| usize::from(u16::from_be_bytes([l[0], l[1]]))) else { return false };
pos += 2 + len;
}
}
}
false
}
/// The coding parameters of one scan, derived as T.87 section C.2 specifies.
#[derive(Clone, Copy)]
struct Params {
maxval: i32,
near: i32,
range: i32,
qbpp: u32,
limit: u32,
t1: i32,
t2: i32,
t3: i32,
reset: i32,
}
fn ceil_log2(v: i32) -> u32 {
let mut n = 0;
while (1i64 << n) < i64::from(v) {
n += 1;
}
n
}
impl Params {
/// `preset` holds the `LSE` values (`maxval`, `t1`, `t2`, `t3`, `reset`), 0 where absent.
fn new(precision: u32, near: i32, preset: [i32; 5]) -> Result<Params, CodecError> {
let default_max = (1i32 << precision) - 1;
let maxval = if preset[0] == 0 { default_max } else { preset[0] };
if maxval < 1 || maxval > default_max || near < 0 || near > (maxval / 2).min(255) {
return Err(bad("invalid MAXVAL or NEAR"));
}
let clamp = |v: i32, lo: i32, hi: i32| if v > hi || v < lo { lo } else { v };
let (d1, d2, d3) = if maxval >= 128 {
let factor = (maxval.min(4095) + 128) / 256;
let t1 = clamp(factor + 2 + 3 * near, near + 1, maxval);
let t2 = clamp(factor * 4 + 3 + 5 * near, t1, maxval);
let t3 = clamp(factor * 17 + 4 + 7 * near, t2, maxval);
(t1, t2, t3)
} else {
let factor = 256 / (maxval + 1);
let t1 = clamp((3 / factor + 3 * near).max(2), near + 1, maxval);
let t2 = clamp((7 / factor + 5 * near).max(3), t1, maxval);
let t3 = clamp((21 / factor + 7 * near).max(4), t2, maxval);
(t1, t2, t3)
};
let t1 = if preset[1] == 0 { d1 } else { preset[1] };
let t2 = if preset[2] == 0 { d2 } else { preset[2] };
let t3 = if preset[3] == 0 { d3 } else { preset[3] };
let reset = if preset[4] == 0 { RESET_DEFAULT } else { preset[4] };
if !(near < t1 && t1 <= t2 && t2 <= t3 && t3 <= maxval) || !(3..=255).contains(&reset) {
return Err(bad("invalid threshold or RESET preset"));
}
let range = (maxval + 2 * near) / (2 * near + 1) + 1;
let bpp = ceil_log2(maxval + 1).max(2);
Ok(Params { maxval, near, range, qbpp: ceil_log2(range), limit: 2 * (bpp + bpp.max(8)), t1, t2, t3, reset })
}
}
/// Adaptive state of one scan: contexts, bias and the run index.
struct State {
a: [i32; CONTEXTS],
b: [i32; CONTEXTS],
c: [i32; CONTEXTS],
n: [i32; CONTEXTS],
nn: [i32; 2],
run_index: usize,
}
impl State {
fn new(p: &Params) -> State {
let a0 = ((p.range + 32) / 64).max(2);
State { a: [a0; CONTEXTS], b: [0; CONTEXTS], c: [0; CONTEXTS], n: [1; CONTEXTS], nn: [0; 2], run_index: 0 }
}
}
fn quantise_gradient(d: i32, p: &Params) -> i32 {
if d <= -p.t3 {
-4
} else if d <= -p.t2 {
-3
} else if d <= -p.t1 {
-2
} else if d < -p.near {
-1
} else if d <= p.near {
0
} else if d < p.t1 {
1
} else if d < p.t2 {
2
} else if d < p.t3 {
3
} else {
4
}
}
fn predict(ra: i32, rb: i32, rc: i32) -> i32 {
if rc >= ra.max(rb) {
ra.min(rb)
} else if rc <= ra.min(rb) {
ra.max(rb)
} else {
ra + rb - rc
}
}
/// The error quantised for `NEAR` and reduced into the modulo range, as the encoder codes it.
fn reduce(mut e: i32, p: &Params) -> i32 {
if p.near > 0 {
e = if e > 0 { (e + p.near) / (2 * p.near + 1) } else { -(p.near - e) / (2 * p.near + 1) };
}
if e < 0 {
e += p.range;
}
if e >= (p.range + 1) / 2 {
e -= p.range;
}
e
}
/// The reconstructed sample for a decoded (sign-adjusted) error.
fn reconstruct(px: i32, sign: i32, e: i32, p: &Params) -> i32 {
let mut r = px + sign * e * (2 * p.near + 1);
if r < -p.near {
r += p.range * (2 * p.near + 1);
} else if r > p.maxval + p.near {
r -= p.range * (2 * p.near + 1);
}
r.clamp(0, p.maxval)
}
fn golomb_k(n: i32, a: i32) -> u32 {
let mut k = 0;
while (i64::from(n) << k) < i64::from(a) {
k += 1;
}
k
}
/// Bits of the entropy-coded segment, with T.87's stuffing: after an `0xFF` byte the next byte
/// carries only 7 bits.
struct BitReader<'a> {
data: &'a [u8],
pos: usize,
cur: u32,
left: u32,
prev_ff: bool,
}
impl<'a> BitReader<'a> {
fn new(data: &'a [u8]) -> Self {
BitReader { data, pos: 0, cur: 0, left: 0, prev_ff: false }
}
fn bit(&mut self) -> Result<u32, CodecError> {
if self.left == 0 {
let byte = *self.data.get(self.pos).ok_or_else(|| bad("the entropy-coded data ends early"))?;
self.pos += 1;
if self.prev_ff {
if byte & 0x80 != 0 {
return Err(bad("a marker inside entropy-coded data"));
}
self.cur = u32::from(byte);
self.left = 7;
} else {
self.cur = u32::from(byte);
self.left = 8;
}
self.prev_ff = byte == 0xFF;
}
self.left -= 1;
Ok((self.cur >> self.left) & 1)
}
fn bits(&mut self, n: u32) -> Result<u32, CodecError> {
let mut v = 0;
for _ in 0..n {
v = v << 1 | self.bit()?;
}
Ok(v)
}
/// A limited-length Golomb code: the mapped error.
fn golomb(&mut self, k: u32, limit: u32, qbpp: u32) -> Result<i32, CodecError> {
let max_zeros = limit.checked_sub(qbpp + 1).ok_or_else(|| bad("invalid LIMIT"))?;
let mut zeros = 0;
while self.bit()? == 0 {
zeros += 1;
if zeros > max_zeros {
return Err(bad("a Golomb code is longer than LIMIT"));
}
}
let v = if zeros < max_zeros { (zeros << k) + self.bits(k)? } else { self.bits(qbpp)? + 1 };
i32::try_from(v).map_err(|_| bad("mapped error out of range"))
}
}
/// Decode one component scan of `w` x `h` samples into `out` (row-major).
fn decode_scan(data: &[u8], w: usize, h: usize, p: &Params, out: &mut [u16]) -> Result<(), CodecError> {
let mut r = BitReader::new(data);
let mut st = State::new(p);
let mut prev = vec![0i32; w + 2];
let mut cur = vec![0i32; w + 2];
for y in 0..h {
// Ra at the first sample is Rb; the slot at index 0 is Rc there, left over from the line above.
cur[0] = prev[1];
if y > 0 {
prev[w + 1] = prev[w];
}
let mut x = 0usize;
while x < w {
let (ra, rb, rc, rd) = (cur[x], prev[x + 1], prev[x], if y == 0 { 0 } else { prev[x + 2] });
let (q1, q2, q3) = (quantise_gradient(rd - rb, p), quantise_gradient(rb - rc, p), quantise_gradient(rc - ra, p));
if q1 == 0 && q2 == 0 && q3 == 0 {
x = decode_run(&mut r, &mut st, p, &prev, &mut cur, ra, x, w)?;
continue;
}
let (sign, q1, q2, q3) = if q1 < 0 || (q1 == 0 && (q2 < 0 || (q2 == 0 && q3 < 0))) { (-1, -q1, -q2, -q3) } else { (1, q1, q2, q3) };
let q = (q1 * 81 + (q2 + 4) * 9 + (q3 + 4)) as usize;
let k = golomb_k(st.n[q], st.a[q]);
let m = r.golomb(k, p.limit, p.qbpp)?;
let swap = p.near == 0 && k == 0 && 2 * st.b[q] <= -st.n[q];
let e = if swap {
if m & 1 == 1 { (m - 1) >> 1 } else { -(m >> 1) - 1 }
} else if m & 1 == 0 {
m >> 1
} else {
-((m + 1) >> 1)
};
let px = (predict(ra, rb, rc) + sign * st.c[q]).clamp(0, p.maxval);
let rx = reconstruct(px, sign, e, p);
update_regular(&mut st, q, e, p);
cur[x + 1] = rx;
x += 1;
}
let row = &mut out[y * w..(y + 1) * w];
for (o, &v) in row.iter_mut().zip(&cur[1..=w]) {
*o = v as u16;
}
// The line just decoded becomes the line above; its slot 0 is the Rc of the next line's first sample.
std::mem::swap(&mut prev, &mut cur);
}
Ok(())
}
fn update_regular(st: &mut State, q: usize, e: i32, p: &Params) {
st.b[q] += e * (2 * p.near + 1);
st.a[q] += e.abs();
if st.n[q] == p.reset {
st.a[q] >>= 1;
st.b[q] = if st.b[q] >= 0 { st.b[q] >> 1 } else { -((1 - st.b[q]) >> 1) };
st.n[q] >>= 1;
}
st.n[q] += 1;
if st.b[q] <= -st.n[q] {
if st.c[q] > MIN_C {
st.c[q] -= 1;
}
st.b[q] += st.n[q];
if st.b[q] <= -st.n[q] {
st.b[q] = -st.n[q] + 1;
}
} else if st.b[q] > 0 {
if st.c[q] < MAX_C {
st.c[q] += 1;
}
st.b[q] -= st.n[q];
if st.b[q] > 0 {
st.b[q] = 0;
}
}
}
/// Run-interruption variables update shared by both directions.
fn update_run(st: &mut State, q: usize, e: i32, em: i32, ri_type: i32, p: &Params) {
let i = q - RI_BASE;
if e < 0 {
st.nn[i] += 1;
}
st.a[q] += (em + 1 - ri_type) >> 1;
if st.n[q] == p.reset {
st.a[q] >>= 1;
st.n[q] >>= 1;
st.nn[i] >>= 1;
}
st.n[q] += 1;
}
/// The run-interruption Golomb parameter and the mapping flag of an error.
fn run_k(st: &State, q: usize, ri_type: i32) -> u32 {
let temp = if ri_type == 1 { st.a[q] + (st.n[q] >> 1) } else { st.a[q] };
golomb_k(st.n[q], temp)
}
#[allow(clippy::too_many_arguments)]
fn decode_run(
r: &mut BitReader,
st: &mut State,
p: &Params,
prev: &[i32],
cur: &mut [i32],
ra: i32,
x: usize,
w: usize,
) -> Result<usize, CodecError> {
let remaining = w - x;
let mut run = 0usize;
while r.bit()? == 1 {
let step = 1usize << J[st.run_index];
let count = step.min(remaining - run);
run += count;
if count == step && st.run_index < 31 {
st.run_index += 1;
}
if run == remaining {
break;
}
}
if run < remaining {
let rest = r.bits(J[st.run_index])? as usize;
run += rest;
if run > remaining {
return Err(bad("a run passes the end of the line"));
}
}
for v in &mut cur[x + 1..x + 1 + run] {
*v = ra;
}
if run == remaining {
return Ok(w);
}
// The sample that ended the run: its own Rb, the sample above it.
let rb = prev[x + run + 1];
let ri_type = i32::from((ra - rb).abs() <= p.near);
let q = RI_BASE + ri_type as usize;
let k = run_k(st, q, ri_type);
let limit = p.limit - J[st.run_index] - 1;
let em = r.golomb(k, limit, p.qbpp)?;
let tmp = em + ri_type;
let cond = k == 0 && 2 * st.nn[ri_type as usize] < st.n[q];
let map = tmp & 1;
let mag = (tmp + map) / 2;
let e = if (cond && map == 1) || (!cond && map == 0) { mag } else { -mag };
let (px, sign) = if ri_type == 1 { (ra, 1) } else { (rb, if ra > rb { -1 } else { 1 }) };
// The decoder holds the sign-adjusted error; the sign flips the reconstruction.
let rx = reconstruct(px, sign, e, p);
update_run(st, q, e, em, ri_type, p);
if st.run_index > 0 {
st.run_index -= 1;
}
cur[x + run + 1] = rx;
Ok(x + run + 1)
}
// ---- encoder ----
struct BitWriter {
out: Vec<u8>,
cur: u32,
used: u32,
cap: u32,
}
impl BitWriter {
fn new() -> Self {
BitWriter { out: Vec::new(), cur: 0, used: 0, cap: 8 }
}
fn put(&mut self, value: u32, n: u32) {
for i in (0..n).rev() {
// A run of more than 32 zero bits (a long escape code) has no bits of `value` to shift out.
let bit = if i < 32 { (value >> i) & 1 } else { 0 };
self.cur = self.cur << 1 | bit;
self.used += 1;
if self.used == self.cap {
let byte = self.cur as u8;
self.out.push(byte);
self.cap = if byte == 0xFF { 7 } else { 8 };
self.cur = 0;
self.used = 0;
}
}
}
/// Pad the last byte with zero bits; a closing 0xFF is followed by a zero byte.
fn finish(mut self) -> Vec<u8> {
if self.used > 0 {
let pad = self.cap - self.used;
self.put(0, pad);
}
if self.out.last() == Some(&0xFF) {
self.out.push(0);
}
self.out
}
fn golomb(&mut self, m: i32, k: u32, limit: u32, qbpp: u32) {
let m = m as u32;
let max_zeros = limit - qbpp - 1;
let q = m >> k;
if q < max_zeros {
self.put(0, q);
self.put(1, 1);
self.put(m & ((1 << k) - 1), k);
} else {
self.put(0, max_zeros);
self.put(1, 1);
self.put(m - 1, qbpp);
}
}
}
fn encode_scan(plane: &[u16], w: usize, h: usize, p: &Params) -> Vec<u8> {
let mut wr = BitWriter::new();
let mut st = State::new(p);
let mut prev = vec![0i32; w + 2];
let mut cur = vec![0i32; w + 2];
for y in 0..h {
cur[0] = prev[1];
if y > 0 {
prev[w + 1] = prev[w];
}
let line = &plane[y * w..(y + 1) * w];
let mut x = 0usize;
while x < w {
let (ra, rb, rc, rd) = (cur[x], prev[x + 1], prev[x], if y == 0 { 0 } else { prev[x + 2] });
let ix = i32::from(line[x]);
let (q1, q2, q3) = (quantise_gradient(rd - rb, p), quantise_gradient(rb - rc, p), quantise_gradient(rc - ra, p));
if q1 == 0 && q2 == 0 && q3 == 0 {
x = encode_run(&mut wr, &mut st, p, line, &prev, &mut cur, ra, x);
continue;
}
let (sign, q1, q2, q3) = if q1 < 0 || (q1 == 0 && (q2 < 0 || (q2 == 0 && q3 < 0))) { (-1, -q1, -q2, -q3) } else { (1, q1, q2, q3) };
let q = (q1 * 81 + (q2 + 4) * 9 + (q3 + 4)) as usize;
let px = (predict(ra, rb, rc) + sign * st.c[q]).clamp(0, p.maxval);
let e = reduce(sign * (ix - px), p);
let k = golomb_k(st.n[q], st.a[q]);
let swap = p.near == 0 && k == 0 && 2 * st.b[q] <= -st.n[q];
let m = if swap {
if e >= 0 { 2 * e + 1 } else { -2 * (e + 1) }
} else if e >= 0 {
2 * e
} else {
-2 * e - 1
};
wr.golomb(m, k, p.limit, p.qbpp);
cur[x + 1] = reconstruct(px, sign, e, p);
update_regular(&mut st, q, e, p);
x += 1;
}
std::mem::swap(&mut prev, &mut cur);
}
wr.finish()
}
#[allow(clippy::too_many_arguments)]
fn encode_run(wr: &mut BitWriter, st: &mut State, p: &Params, line: &[u16], prev: &[i32], cur: &mut [i32], ra: i32, x: usize) -> usize {
let w = line.len();
let mut run = 0usize;
while x + run < w && (i32::from(line[x + run]) - ra).abs() <= p.near {
cur[x + run + 1] = ra;
run += 1;
}
let mut count = run;
while count >= 1usize << J[st.run_index] {
wr.put(1, 1);
count -= 1usize << J[st.run_index];
if st.run_index < 31 {
st.run_index += 1;
}
}
if x + run == w {
if count > 0 {
wr.put(1, 1);
}
return w;
}
wr.put(0, 1);
wr.put(count as u32, J[st.run_index]);
let ix = i32::from(line[x + run]);
let rb = prev[x + run + 1];
let ri_type = i32::from((ra - rb).abs() <= p.near);
let q = RI_BASE + ri_type as usize;
let (px, sign) = if ri_type == 1 { (ra, 1) } else { (rb, if ra > rb { -1 } else { 1 }) };
let e = reduce(sign * (ix - px), p);
let k = run_k(st, q, ri_type);
let n_neg = st.nn[ri_type as usize];
let map = i32::from((k == 0 && e > 0 && 2 * n_neg < st.n[q]) || (e < 0 && 2 * n_neg >= st.n[q]) || (e < 0 && k != 0));
let em = 2 * e.abs() - ri_type - map;
wr.golomb(em, k, p.limit - J[st.run_index] - 1, p.qbpp);
cur[x + run + 1] = reconstruct(px, sign, e, p);
update_run(st, q, e, em, ri_type, p);
if st.run_index > 0 {
st.run_index -= 1;
}
x + run + 1
}
/// Writes a lossless JPEG-LS file: 8 or 16 bits, gray or RGB, one scan per component.
pub(crate) fn encode(src: &Image, plan: Plan) -> Result<Vec<u8>, CodecError> {
let enc = |msg: String| CodecError::encode(F, msg);
let img = src.converted(plan.layout, plan.sample);
let nc = match img.layout() {
ChannelLayout::Gray => 1,
ChannelLayout::Rgb => 3,
l => return Err(enc(format!("no JPEG-LS layout for {l:?}"))),
};
let precision: u32 = match img.sample_type() {
SampleType::U8 => 8,
SampleType::U16 => 16,
s => return Err(enc(format!("JPEG-LS stores 8 or 16 bits per sample, not {s:?}"))),
};
let (w, h) = img.dimensions();
let (Ok(w16), Ok(h16)) = (u16::try_from(w), u16::try_from(h)) else {
return Err(enc(format!("dimensions exceed 65535x65535: {w}x{h}")));
};
let (wu, hu) = (w as usize, h as usize);
let data = img.data();
if data.len() != wu * hu * nc * (precision as usize / 8) {
return Err(enc("the image has the wrong number of samples".into()));
}
let params = Params::new(precision, 0, [0; 5]).map_err(|_| enc("invalid coding parameters".into()))?;
let mut out = vec![0xFF, 0xD8, 0xFF, SOF55];
out.extend_from_slice(&((8 + 3 * nc) as u16).to_be_bytes());
out.push(precision as u8);
out.extend_from_slice(&h16.to_be_bytes());
out.extend_from_slice(&w16.to_be_bytes());
out.push(nc as u8);
for c in 0..nc {
out.extend_from_slice(&[c as u8 + 1, 0x11, 0]);
}
let mut plane = vec![0u16; wu * hu];
for c in 0..nc {
for (i, v) in plane.iter_mut().enumerate() {
let at = i * nc + c;
*v = if precision == 8 { u16::from(data[at]) } else { u16::from_ne_bytes([data[2 * at], data[2 * at + 1]]) };
}
out.extend_from_slice(&[0xFF, 0xDA, 0, 8, 1, c as u8 + 1, 0, 0, 0, 0]);
out.extend_from_slice(&encode_scan(&plane, wu, hu, &params));
}
out.extend_from_slice(&[0xFF, 0xD9]);
Ok(out)
}
struct Frame {
precision: u32,
width: usize,
height: usize,
components: Vec<u8>,
}
fn be16(b: &[u8], i: usize) -> Result<usize, CodecError> {
b.get(i..i + 2).map(|s| usize::from(u16::from_be_bytes([s[0], s[1]]))).ok_or_else(|| bad("truncated header"))
}
pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if !looks_like_jpegls(b) {
return Err(bad("not a JPEG-LS file"));
}
let mut pos = 2;
let mut frame: Option<Frame> = None;
let mut preset = [0i32; 5];
let mut planes: Vec<Vec<u16>> = Vec::new();
let mut scans_done = 0;
loop {
// Find the next marker.
while b.get(pos) != Some(&0xFF) {
if pos >= b.len() {
return finish(frame, planes, scans_done);
}
pos += 1;
}
while b.get(pos + 1) == Some(&0xFF) {
pos += 1;
}
let Some(&marker) = b.get(pos + 1) else { return finish(frame, planes, scans_done) };
if marker == 0xD9 {
return finish(frame, planes, scans_done);
}
if marker == 0x00 || (0xD0..=0xD7).contains(&marker) || marker == 0x01 {
pos += 2;
continue;
}
let len = be16(b, pos + 2)?;
let seg = b.get(pos + 4..pos + 2 + len).ok_or_else(|| bad("truncated marker segment"))?;
match marker {
SOF55 => {
if frame.is_some() || seg.len() < 6 {
return Err(bad("bad or repeated frame header"));
}
let (precision, height, width, nf) = (u32::from(seg[0]), be16(seg, 1)?, be16(seg, 3)?, usize::from(seg[5]));
if !(2..=16).contains(&precision) || width == 0 || height == 0 || !matches!(nf, 1 | 3) || seg.len() < 6 + 3 * nf {
return Err(bad("unsupported frame header"));
}
if height == 0 {
return Err(CodecError::unsupported(F, "a frame height set later by a DNL marker"));
}
let layout = if nf == 1 { ChannelLayout::Gray } else { ChannelLayout::Rgb };
let sample = if precision <= 8 { SampleType::U8 } else { SampleType::U16 };
limits.check(width as u32, height as u32, layout, sample)?;
let components = (0..nf).map(|i| seg[6 + 3 * i]).collect();
frame = Some(Frame { precision, width, height, components });
}
LSE => {
if seg.first() == Some(&1) && seg.len() >= 11 {
for (i, p) in preset.iter_mut().enumerate() {
*p = be16(seg, 1 + 2 * i)? as i32;
}
} else if seg.first() != Some(&1) {
return Err(CodecError::unsupported(F, "mapping tables and colour transforms (LSE)"));
}
}
0xDA => {
let f = frame.as_ref().ok_or_else(|| bad("a scan before the frame header"))?;
let ns = usize::from(*seg.first().ok_or_else(|| bad("empty scan header"))?);
if seg.len() < 1 + 2 * ns + 3 || ns != 1 {
return Err(CodecError::unsupported(F, "interleaved scans (ILV 1 and 2)"));
}
let (cs, tm, near, ilv) = (seg[1], seg[2], i32::from(seg[3]), seg[4]);
if tm != 0 {
return Err(CodecError::unsupported(F, "mapping tables"));
}
if ilv != 0 && f.components.len() > 1 {
return Err(CodecError::unsupported(F, "interleaved scans (ILV 1 and 2)"));
}
if seg[5] & 0x0f != 0 {
return Err(CodecError::unsupported(F, "a point transform"));
}
let idx = f.components.iter().position(|&c| c == cs).ok_or_else(|| bad("a scan names an unknown component"))?;
if planes.len() <= idx {
planes.resize(f.components.len(), Vec::new());
}
if !planes[idx].is_empty() {
return Err(bad("a component is coded twice"));
}
let params = Params::new(f.precision, near, preset)?;
let start = pos + 2 + len;
// The scan ends at the next real marker: an 0xFF followed by a byte with its top bit set.
let mut end = start;
while end < b.len() {
if b[end] == 0xFF && b.get(end + 1).is_none_or(|&n| n & 0x80 != 0) {
break;
}
end += 1;
}
let mut samples = Vec::new();
samples.try_reserve_exact(f.width * f.height).map_err(|_| bad("pixel buffer is too large"))?;
samples.resize(f.width * f.height, 0u16);
decode_scan(&b[start..end], f.width, f.height, &params, &mut samples)?;
planes[idx] = samples;
scans_done += 1;
pos = end;
continue;
}
_ => {}
}
pos += 2 + len;
}
}
fn finish(frame: Option<Frame>, planes: Vec<Vec<u16>>, scans: usize) -> Result<Image, CodecError> {
let f = frame.ok_or_else(|| bad("no frame header"))?;
if scans != f.components.len() || planes.iter().any(Vec::is_empty) || planes.len() != f.components.len() {
return Err(bad("the file ends before every component is coded"));
}
let (w, h, nc) = (f.width, f.height, f.components.len());
let layout = if nc == 1 { ChannelLayout::Gray } else { ChannelLayout::Rgb };
let p = f.precision;
let scale = |v: u16| -> u16 {
if p == 16 {
v
} else {
let v = u32::from(v);
((v << (16 - p)) | (v >> (2 * p).saturating_sub(16).min(15))) as u16
}
};
if p <= 8 {
let to8 = |v: u16| -> u8 { if p == 8 { v as u8 } else { (scale(v) >> 8) as u8 } };
let mut data = Vec::with_capacity(w * h * nc);
for i in 0..w * h {
for plane in &planes {
data.push(to8(plane[i]));
}
}
Image::from_u8(w as u32, h as u32, layout, data)
} else {
let mut data = Vec::with_capacity(w * h * nc);
for i in 0..w * h {
for plane in &planes {
data.push(scale(plane[i]));
}
}
Image::from_u16(w as u32, h as u32, layout, &data)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn noise_u16(n: usize, seed: &mut u32, mask: u32) -> Vec<u16> {
(0..n)
.map(|_| {
*seed ^= *seed << 13;
*seed ^= *seed >> 17;
*seed ^= *seed << 5;
(*seed & mask) as u16
})
.collect()
}
fn image(w: u32, h: u32, layout: ChannelLayout, wide: bool, kind: u8) -> Image {
let n = w as usize * h as usize * layout.channels();
let mut seed = 0x1234_5679u32;
let samples: Vec<u16> = match kind {
0 => noise_u16(n, &mut seed, if wide { 0xFFFF } else { 0xFF }),
1 => vec![if wide { 40_000 } else { 100 }; n],
_ => (0..n).map(|i| if wide { ((i / 3) * 37 % 65_536) as u16 } else { ((i / 3) % 251) as u16 }).collect(),
};
if wide {
Image::from_u16(w, h, layout, &samples).unwrap()
} else {
Image::from_u8(w, h, layout, samples.iter().map(|&v| v as u8).collect()).unwrap()
}
}
fn plan(img: &Image) -> Plan {
Plan { layout: img.layout(), sample: img.sample_type() }
}
#[test]
fn round_trips_noise_flat_and_smooth_images() {
for layout in [ChannelLayout::Gray, ChannelLayout::Rgb] {
for wide in [false, true] {
for kind in 0..3 {
// Widths around the run-length steps, and single-pixel dimensions.
for (w, h) in [(1, 1), (1, 9), (2, 3), (7, 5), (33, 4), (300, 3), (1025, 2)] {
let img = image(w, h, layout, wide, kind);
let bytes = encode(&img, plan(&img)).unwrap();
assert!(looks_like_jpegls(&bytes));
let back = decode(&bytes, &Limits::default()).unwrap_or_else(|e| panic!("{layout:?} wide={wide} kind={kind} {w}x{h}: {e}"));
assert_eq!(back.data(), img.data(), "{layout:?} wide={wide} kind={kind} {w}x{h}");
}
}
}
}
}
#[test]
fn default_parameters_follow_the_standard() {
let p = Params::new(8, 0, [0; 5]).unwrap();
assert_eq!((p.maxval, p.range, p.qbpp, p.limit, p.t1, p.t2, p.t3, p.reset), (255, 256, 8, 32, 3, 7, 21, 64));
let p = Params::new(16, 0, [0; 5]).unwrap();
assert_eq!((p.maxval, p.range, p.qbpp, p.limit, p.t1, p.t2, p.t3), (65535, 65536, 16, 64, 18, 67, 276));
let p = Params::new(8, 3, [0; 5]).unwrap();
assert_eq!((p.range, p.t1), (38, 12)); // RANGE = floor((255 + 2 * 3) / 7) + 1
assert!(Params::new(8, 200, [0; 5]).is_err());
}
#[test]
fn detection_tells_jpeg_ls_from_jpeg() {
let img = image(4, 4, ChannelLayout::Gray, false, 0);
let ls = encode(&img, plan(&img)).unwrap();
assert!(looks_like_jpegls(&ls));
// A baseline JPEG starts SOI, APP0 / DQT, ... SOF0: not JPEG-LS.
assert!(!looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0, 0xFF, 0xC0, 0, 11]));
assert!(!looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 11]));
// SOF55 after an application segment still is.
assert!(looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xE8, 0, 4, 0, 0, 0xFF, 0xF7, 0, 11]));
assert!(!looks_like_jpegls(&[0xFF, 0xD8]));
}
#[test]
fn interleaved_scans_and_tables_are_unsupported() {
let img = image(8, 4, ChannelLayout::Rgb, false, 2);
let good = encode(&img, plan(&img)).unwrap();
// The scan header body is Ns, Cs, Tm, NEAR, ILV, point transform, after the marker and length.
let sos = good.windows(2).position(|w| w == [0xFF, 0xDA]).unwrap() + 4;
let mut line = good.clone();
line[sos + 4] = 1;
assert!(matches!(decode(&line, &Limits::default()), Err(CodecError::Unsupported { .. })));
let mut mapped = good.clone();
mapped[sos + 2] = 1;
assert!(matches!(decode(&mapped, &Limits::default()), Err(CodecError::Unsupported { .. })));
let mut transform = good;
transform[sos + 5] = 1;
assert!(matches!(decode(&transform, &Limits::default()), Err(CodecError::Unsupported { .. })));
}
#[test]
fn hostile_input_is_an_error_not_a_panic() {
for (w, h, layout, wide) in [(23, 9, ChannelLayout::Gray, false), (11, 7, ChannelLayout::Rgb, true)] {
let img = image(w, h, layout, wide, 0);
let good = encode(&img, plan(&img)).unwrap();
for len in 0..good.len() {
let _ = decode(&good[..len], &Limits::default());
}
// Flip every bit of the entropy-coded data and of the headers, one at a time.
for i in 0..good.len() {
for bit in 0..8 {
let mut c = good.clone();
c[i] ^= 1 << bit;
let _ = decode(&c, &Limits::default());
}
}
}
// A huge frame is stopped by the limits or the length check before any allocation.
let img = image(4, 4, ChannelLayout::Gray, false, 0);
let mut huge = encode(&img, plan(&img)).unwrap();
let sof = huge.windows(2).position(|w| w == [0xFF, 0xF7]).unwrap();
huge[sof + 5..sof + 9].copy_from_slice(&[0xFF, 0xFF, 0xFF, 0xFF]);
assert!(decode(&huge, &Limits::default()).is_err());
}
}
+58 -7
View File
@@ -141,12 +141,12 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
/// Reads the header and refuses what [`decode`] refuses before any pixel is decoded: sizes
/// past `limits`, and a file too small for the image it declares.
pub fn new(bytes: B, limits: &Limits) -> Result<Self, CodecError> {
Self::open(bytes, limits, true)
Self::open(bytes, limits, true, false)
}
/// [`PngDecodeRows::new`], optionally without reserving the whole image: a caller that hands
/// the rows on as they come ([`decode_rows`]) never holds them all.
fn open(bytes: B, limits: &Limits, reserve: bool) -> Result<Self, CodecError> {
fn open(bytes: B, limits: &Limits, reserve: bool, bounded_stream: bool) -> Result<Self, CodecError> {
let at = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0));
let bytes = SharedInput(std::sync::Arc::new(bytes));
let input = Tracked { cursor: Cursor::new(bytes.clone()), at: at.clone() };
@@ -187,7 +187,14 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
let (width, height) = info.frame_control.map_or_else(|| info.size(), |f| (f.width, f.height));
let line = reader.output_line_size(width).ok_or_else(|| err("image too large"))?;
// The output layout is known: charge its real bytes per pixel, not RGBA16's worst case.
limits.check(width, height, layout, sample)?;
if bounded_stream {
limits.check_size(width, height)?;
if line > limits.alloc_usize() {
return Err(CodecError::LimitExceeded("one PNG row exceeds max_alloc".into()));
}
} else {
limits.check(width, height, layout, sample)?;
}
let height = usize::try_from(height).map_err(|_| err("image too large"))?;
if width == 0 || height == 0 {
return Err(err("the image is empty"));
@@ -234,11 +241,35 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
/// decode the whole image after all (an interlaced file) calls
/// [`PngDecodeRows::reserve_output`] before [`PngDecodeRows::step`].
pub fn new_streaming(bytes: B, limits: &Limits) -> Result<Self, CodecError> {
Self::open(bytes, limits, false)
Self::open(bytes, limits, false, false)
}
/// Opens a bounded row stream without charging a full image that is never retained.
/// Dimension, pixel-count, plausibility, decoder and metadata limits remain unchanged;
/// `max_alloc` also bounds each row group. It is not a total process-memory limit.
/// Unlike [`Self::new_streaming`], a streamable image may exceed the full-image budget.
/// Non-streamable images still require that budget, as do [`Self::step`] and
/// [`Self::reserve_output`]. The caller must bound any output it retains in its sink.
pub fn new_bounded_streaming(bytes: B, limits: &Limits) -> Result<Self, CodecError> {
let decoder = Self::open(bytes, limits, false, true)?;
if !decoder.streamable() {
decoder.check_full_output()?;
}
Ok(decoder)
}
fn check_full_output(&self) -> Result<(), CodecError> {
let height = u32::try_from(self.height).map_err(|_| err("image too large"))?;
self.limits.check(self.width, height, self.layout, self.sample)?;
if self.size > self.limits.alloc_usize() {
return Err(CodecError::LimitExceeded("PNG output exceeds max_alloc".into()));
}
Ok(())
}
/// Reserves the buffer [`PngDecodeRows::step`] decodes the whole image into.
pub fn reserve_output(&mut self) -> Result<(), CodecError> {
self.check_full_output()?;
let size = self.size;
self.buf.try_reserve_exact(size).map_err(|_| CodecError::LimitExceeded(format!("cannot allocate {size} bytes for the image")))
}
@@ -271,6 +302,7 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
/// Decodes at least one row (the whole image if it is interlaced), then goes on while `more()`
/// returns true. `Some` once the image is complete, after which the decoder is spent.
pub fn step(&mut self, more: &mut dyn FnMut() -> bool) -> Result<Option<Image>, CodecError> {
self.check_full_output()?;
if self.done {
return Err(err("the image was already decoded"));
}
@@ -338,7 +370,9 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
/// `more()` returns true; `Some` with the extras once the file is read to its end, with the
/// resolution a format that lacks one takes from its EXIF or XMP. A damaged file fails with
/// the error [`decode`] gives, after however many rows were delivered. An orientation (an
/// `eXIf` after the image data may set one) is for the caller to apply.
/// `eXIf` after the image data may set one) is for the caller to apply. A new group size
/// must exceed any partial group retained from an earlier yield; otherwise this returns
/// an error without consuming another row.
pub fn step_stream<E: From<CodecError>>(
&mut self,
group: u32,
@@ -348,12 +382,29 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
if self.done {
return Err(err("the image was already decoded").into());
}
let group = usize::try_from(group.max(1)).unwrap_or(usize::MAX);
// Tail EXIF may report an orientation after rows have already been delivered;
// that belongs in the returned extras, not a rejection of metadata continuation.
if self.rows == 0 && !self.tail && !self.streamable() {
return Err(err("this PNG requires whole-image decoding").into());
}
let group = usize::try_from(group.max(1)).unwrap_or(usize::MAX).min(self.height);
if self.rows - self.group_start >= group {
return Err(err("PNG row group is smaller than rows held from the previous step").into());
}
let group_bytes = group.checked_mul(self.line).ok_or_else(|| err("PNG row group is too large"))?;
if group_bytes > self.limits.alloc_usize() {
return Err(CodecError::LimitExceeded("PNG row group exceeds max_alloc".into()).into());
}
if !self.tail {
while self.rows < self.height {
let held = self.rows - self.group_start;
let at = held.checked_mul(self.line).ok_or_else(|| err("image too large"))?;
let end = at.checked_add(self.line).ok_or_else(|| err("image too large"))?;
// A caller may change its group size between yields. Bound the actual held
// bytes as well as the requested group before growing the row buffer.
if end > self.limits.alloc_usize() {
return Err(CodecError::LimitExceeded("PNG row group exceeds max_alloc".into()).into());
}
if self.buf.len() < end {
self.buf
.try_reserve_exact(end - self.buf.len())
@@ -368,7 +419,7 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
to_native_endian(row);
}
self.rows += 1;
if self.rows - self.group_start == group || self.rows == self.height {
if self.rows - self.group_start >= group || self.rows == self.height {
let data = self.buf.get(..end).ok_or_else(|| err("invalid PNG row group"))?;
sink(u32::try_from(self.group_start).map_err(|_| err("image too large"))?, data)?;
self.group_start = self.rows;
+12 -2
View File
@@ -44,6 +44,8 @@ pub enum Format {
Iff,
/// JPEG 2000 (JP2 container or raw J2K codestream): read-only; see [`ASYMMETRIC_EXCEPTIONS`].
Jp2,
/// JPEG-LS (`.jls`): lossless and near-lossless gray and RGB.
JpegLs,
}
/// What a format can hold **and** what this crate reads/writes for it.
@@ -113,7 +115,7 @@ const TIFF_LAYOUTS: &[ChannelLayout] = &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::
impl Format {
/// Every format known to the crate (enabled or not).
pub const ALL: [Format; 24] = [
pub const ALL: [Format; 25] = [
Format::Png,
Format::Jpeg,
Format::Jp2,
@@ -138,6 +140,7 @@ impl Format {
Format::Cineon,
Format::Dicom,
Format::Iff,
Format::JpegLs,
];
pub fn caps(self) -> FormatCaps {
@@ -176,6 +179,7 @@ impl Format {
Format::Dicom => "DICOM",
Format::Iff => "Amiga IFF",
Format::Jp2 => "JPEG 2000",
Format::JpegLs => "JPEG-LS",
}
}
@@ -207,6 +211,7 @@ impl Format {
Format::Dicom => &["dcm", "dicom", "dc3"],
Format::Iff => &["iff", "lbm", "ilbm"],
Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"],
Format::JpegLs => &["jls"],
}
}
@@ -236,13 +241,14 @@ impl Format {
Format::Dicom => "application/dicom",
Format::Iff => "image/x-iff",
Format::Jp2 => "image/jp2",
Format::JpegLs => "image/jls",
}
}
/// Maximum encodable dimensions, if the format has a hard limit.
pub fn max_dimensions(self) -> Option<(u32, u32)> {
match self {
Format::Jpeg | Format::Gif | Format::Iff => Some((65535, 65535)),
Format::Jpeg | Format::Gif | Format::Iff | Format::JpegLs => Some((65535, 65535)),
Format::WebP => Some((16384, 16384)),
Format::Ico => Some((256, 256)),
_ => None,
@@ -310,6 +316,7 @@ pub fn caps(format: Format) -> FormatCaps {
Format::Cineon => FormatCaps { depths: &[S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Dicom => FormatCaps { read: true, write: false, depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Iff => FormatCaps { depths: &[S::U8], layouts: &[L::Rgb, L::Rgba], alpha: true, ..base },
Format::JpegLs => FormatCaps { depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base },
}
}
@@ -321,6 +328,9 @@ pub fn detect(bytes: &[u8]) -> Option<Format> {
if b.starts_with(b"\x89PNG\r\n\x1a\n") {
return Some(Format::Png);
}
if crate::codecs::jpegls::looks_like_jpegls(b) {
return Some(Format::JpegLs);
}
if b.starts_with(&[0xFF, 0xD8, 0xFF]) {
return Some(Format::Jpeg);
}
+5 -1
View File
@@ -16,6 +16,7 @@
mod allocation;
pub mod apng;
pub mod bmp_probe;
pub mod cicp;
mod codecs;
mod error;
@@ -28,6 +29,7 @@ mod inspection;
mod lab;
mod options;
pub mod orientation;
pub mod png_probe;
pub mod resolution;
pub mod source_settings;
pub mod web;
@@ -63,7 +65,7 @@ pub use crate::resolution::{exif_resolution, export_exif, export_xmp, photoshop_
pub use crate::source_settings::{WebpEncoding, jpeg_quality, webp_encoding};
pub use half::f16;
use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, tiff, via_image, webp, xpm};
use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jpegls, jxl, pcx, png, pnm, tiff, via_image, webp, xpm};
/// Detect the format and decode with default [`Limits`].
pub fn decode(bytes: &[u8]) -> Result<Image, CodecError> {
@@ -102,6 +104,7 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res
Format::Cineon => dpx::decode_cineon(bytes, l),
Format::Dicom => dicom::decode(bytes, l),
Format::Iff => iff::decode(bytes, l),
Format::JpegLs => jpegls::decode(bytes, l),
Format::OpenExr => exr::decode(bytes, l),
Format::Heif => heif::decode(bytes, l, opts.keep_orientation),
Format::Jp2 => jp2::decode(bytes, l),
@@ -458,6 +461,7 @@ pub fn encode(image: &Image, format: Format, opts: &EncodeOptions) -> Result<Vec
Format::Cineon => dpx::encode_cineon(image, plan),
Format::Dicom => Err(CodecError::unsupported(format, "DICOM is import-only; save as TIFF or PNG instead")),
Format::Iff => iff::encode(image, plan),
Format::JpegLs => jpegls::encode(image, plan),
Format::OpenExr => exr::encode(image, plan, opts),
Format::Heif => Err(CodecError::unsupported(format, "encoding is not available in this build")),
Format::Jp2 => Err(CodecError::unsupported(format, "JPEG 2000 is import-only; save as PNG or TIFF instead")),
+190
View File
@@ -0,0 +1,190 @@
//! Header-only PNG inspection without inflating image data.
use crate::{CodecError, Format};
fn err(message: &str) -> CodecError {
CodecError::malformed(Format::Png, message)
}
/// Dimensions declared in a PNG IHDR prefix, without checking the rest of the file.
/// Useful only for an early allocation limit; use [`header`] for structural inspection.
pub fn declared_dimensions(b: &[u8]) -> Option<(u32, u32)> {
if !b.starts_with(b"\x89PNG\r\n\x1a\n") || b.get(12..16) != Some(b"IHDR") {
return None;
}
let w = u32::from_be_bytes(b.get(16..20)?.try_into().ok()?);
let h = u32::from_be_bytes(b.get(20..24)?.try_into().ok()?);
Some((w, h))
}
/// Stored dimensions and EXIF orientation. This does not validate CRCs or compressed pixels.
pub fn header(b: &[u8]) -> Result<(u32, u32, u16), CodecError> {
header_with_max_pixels(b, u64::MAX)
}
/// As [`header`], refusing images over `max_pixels` before scanning their chunks.
pub fn header_with_max_pixels(b: &[u8], max_pixels: u64) -> Result<(u32, u32, u16), CodecError> {
if !b.starts_with(b"\x89PNG\r\n\x1a\n") {
return Err(err("bad signature"));
}
let be32 = |p: usize| b.get(p..p.checked_add(4)?).map(|v| u32::from_be_bytes([v[0], v[1], v[2], v[3]]));
if be32(8) != Some(13) || b.get(12..16) != Some(b"IHDR") {
return Err(err("missing IHDR"));
}
let ihdr = b.get(16..29).ok_or_else(|| err("truncated IHDR"))?;
let (w, h) = (u32::from_be_bytes([ihdr[0], ihdr[1], ihdr[2], ihdr[3]]), u32::from_be_bytes([ihdr[4], ihdr[5], ihdr[6], ihdr[7]]));
let (depth, color, compression, filter, interlace) = (ihdr[8], ihdr[9], ihdr[10], ihdr[11], ihdr[12]);
if w > i32::MAX as u32 || h > i32::MAX as u32 {
return Err(err("dimensions out of range"));
}
if w == 0 || h == 0 {
return Err(err("zero dimension"));
}
if u64::from(w) * u64::from(h) > max_pixels {
return Err(CodecError::LimitExceeded("PNG pixel count".into()));
}
let depth_ok = match color {
0 => matches!(depth, 1 | 2 | 4 | 8 | 16),
3 => matches!(depth, 1 | 2 | 4 | 8),
2 | 4 | 6 => matches!(depth, 8 | 16),
_ => false,
};
if !depth_ok || compression != 0 || filter != 0 || interlace > 1 {
return Err(err("invalid IHDR"));
}
let (mut p, mut palette, mut idat, mut after_idat, mut exif) = (8usize, false, false, false, None);
while let Some(len) = be32(p) {
let Some(kind) = p.checked_add(4).and_then(|k| b.get(k..k.checked_add(4)?)) else { break };
if idat && kind != b"IDAT" {
// a chunk follows the image data: the IDAT run is complete
after_idat = true;
}
if kind == b"IEND" {
break;
}
let start = p.saturating_add(8);
let data = (len <= i32::MAX as u32).then(|| start.checked_add(len as usize).and_then(|end| b.get(start..end))).flatten();
let Some(data) = data else {
if after_idat {
break; // a damaged chunk after the image data: a decode ignores it too
}
return Err(err("truncated"));
};
match kind {
b"PLTE" => palette = true,
b"IDAT" if after_idat => {} // a stray IDAT after other chunks: the first run is the image
b"IDAT" => {
if color == 3 && !palette {
return Err(err("indexed image without a palette"));
}
idat = true;
}
b"eXIf" if exif.is_none() => exif = Some(data.strip_prefix(b"Exif\0\0").unwrap_or(data)),
_ => {}
}
p = start.saturating_add(data.len()).saturating_add(4);
}
if !idat {
return Err(err("no image data"));
}
if !after_idat {
return Err(err("truncated image data"));
}
Ok((w, h, exif.map_or(1, crate::exif_orientation)))
}
/// Container color declarations preceding image data. Raw values leave color policy to callers.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct ColorChunks {
pub srgb: bool,
pub gamma: Option<f32>,
pub chromaticities: Option<[f64; 8]>,
}
/// Read bounded color chunks before image data; malformed tails are ignored.
pub fn color_chunks(b: &[u8]) -> Option<ColorChunks> {
if !b.starts_with(b"\x89PNG\r\n\x1a\n") {
return None;
}
let mut result = ColorChunks::default();
let mut p = 8usize;
while let Some(length) = b.get(p..p.checked_add(4)?) {
let len = u32::from_be_bytes(length.try_into().ok()?) as usize;
let start = p.checked_add(8)?;
let Some(kind) = b.get(p.checked_add(4)?..start) else { break };
let Some(payload) = start.checked_add(len).and_then(|end| b.get(start..end)) else { break };
match kind {
b"sRGB" => result.srgb = true,
b"gAMA" if payload.len() == 4 => {
let v = u32::from_be_bytes(payload.try_into().ok()?) as f32 / 100_000.0;
if v > 0.0 && v.is_finite() {
result.gamma = Some(v);
}
}
b"cHRM" if payload.len() == 32 => {
let mut vals = [0.0; 8];
for (i, dst) in vals.iter_mut().enumerate() {
let raw = i32::from_be_bytes(payload[i * 4..i * 4 + 4].try_into().ok()?);
*dst = f64::from(raw) / 100_000.0;
}
result.chromaticities = Some(vals);
}
b"IDAT" | b"IEND" => break,
_ => {}
}
let Some(next) = start.checked_add(len).and_then(|end| end.checked_add(4)) else { break };
p = next;
}
Some(result)
}
#[cfg(test)]
mod tests {
use super::*;
fn chunk(out: &mut Vec<u8>, kind: &[u8; 4], data: &[u8]) {
out.extend_from_slice(&(data.len() as u32).to_be_bytes());
out.extend_from_slice(kind);
out.extend_from_slice(data);
out.extend_from_slice(&[0; 4]); // Header inspection deliberately does not validate CRCs.
}
fn png(color: u8) -> Vec<u8> {
let mut bytes = b"\x89PNG\r\n\x1a\n".to_vec();
let mut ihdr = Vec::new();
ihdr.extend_from_slice(&2u32.to_be_bytes());
ihdr.extend_from_slice(&3u32.to_be_bytes());
ihdr.extend_from_slice(&[8, color, 0, 0, 0]);
chunk(&mut bytes, b"IHDR", &ihdr);
bytes
}
#[test]
fn header_checks_structure_and_reads_late_orientation_without_crc_validation() {
let mut bytes = png(2);
chunk(&mut bytes, b"IDAT", &[1]);
let exif = b"II\x2a\x00\x08\x00\x00\x00\x01\x00\x12\x01\x03\x00\x01\x00\x00\x00\x06\x00\x00\x00\x00\x00\x00\x00";
chunk(&mut bytes, b"eXIf", exif);
chunk(&mut bytes, b"IEND", &[]);
assert_eq!(header(&bytes).ok(), Some((2, 3, 6)));
assert!(matches!(header_with_max_pixels(&bytes, 5), Err(CodecError::LimitExceeded(_))));
assert_eq!(declared_dimensions(&bytes), Some((2, 3)));
assert!(header(&bytes[..34]).is_err());
let mut indexed = png(3);
chunk(&mut indexed, b"IDAT", &[1]);
chunk(&mut indexed, b"IEND", &[]);
assert!(header(&indexed).is_err());
indexed[25] = 7;
assert!(header(&indexed).is_err());
}
#[test]
fn reads_color_chunks_only_before_image_data() {
let mut bytes = png(2);
chunk(&mut bytes, b"gAMA", &45455u32.to_be_bytes());
chunk(&mut bytes, b"IDAT", &[1]);
chunk(&mut bytes, b"sRGB", &[0]);
let color = color_chunks(&bytes).unwrap();
assert_eq!(color.gamma, Some(0.45455));
assert!(!color.srgb);
assert!(color_chunks(b"not png").is_none());
}
}
@@ -62,6 +62,7 @@ fn default_build_formats_all_symmetric() {
Format::Dpx,
Format::Cineon,
Format::Iff,
Format::JpegLs,
];
for f in expected {
assert!(caps(f).read && caps(f).write, "{f:?}");
@@ -218,6 +219,21 @@ fn detect_magic_iff() {
assert_eq!(detect(b"FORM\0\0\0\x14AIFF"), None);
assert!(decode_as(Format::Iff, b"FORM\0\0\0\x14ILBM").is_err());
}
#[test]
fn detect_magic_jpeg_ls() {
use craft_image_codecs::{ChannelLayout, EncodeOptions, Image, encode};
let img = Image::from_u8(5, 3, ChannelLayout::Gray, (0..15).collect()).unwrap();
let bytes = encode(&img, Format::JpegLs, &EncodeOptions::default()).unwrap();
assert_eq!(detect(&bytes), Some(Format::JpegLs));
assert_eq!(from_extension("scan.JLS"), Some(Format::JpegLs));
assert_eq!(decode(&bytes).unwrap().data(), img.data());
assert!(!ASYMMETRIC_EXCEPTIONS.iter().any(|(f, _)| *f == Format::JpegLs));
assert_eq!(Format::JpegLs.max_dimensions(), Some((65535, 65535)));
// Plain JPEG still is JPEG: SOI, then a baseline frame header.
assert_eq!(detect(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 11]), Some(Format::Jpeg));
assert!(decode_as(Format::JpegLs, &[0xFF, 0xD8, 0xFF, 0xF7]).is_err());
}
#[test]
fn detect_magic_avif() {
assert_eq!(detect(b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf"), Some(Format::Avif));
@@ -0,0 +1,103 @@
//! JPEG-LS against ffmpeg as the reference (oracle; skipped when ffmpeg is absent, a failure with
//! `CRAFT_MEDIA_REQUIRE_ORACLES=1`):
//! - files ffmpeg's encoder writes (8- and 16-bit gray: smooth, noisy and flat images, which
//! exercise the regular, run and escape-coded paths) decode to the pixels ffmpeg decodes;
//! - files our encoder writes (gray 8 and 16 bits, RGB 8 bits) decode in ffmpeg to our pixels (ffmpeg
//! cannot decode 16-bit RGB JPEG-LS, so that case is only round-tripped through our own decoder);
//! - ffmpeg writes RGB line-interleaved, which is reported as unsupported.
use craft_image_codecs::{ChannelLayout, CodecError, EncodeOptions, Format, Image, SampleType, decode, encode};
use std::path::Path;
use std::process::Command;
const W: u32 = 66;
const H: u32 = 40;
fn run(ffmpeg: &Path, args: &[&str]) -> Vec<u8> {
let out = Command::new(ffmpeg).args(["-v", "error", "-y"]).args(args).output().expect("run ffmpeg");
assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr));
out.stdout
}
/// `(name, lavfi source)`: smooth, noisy and flat pictures of W x H.
fn sources() -> Vec<(&'static str, String)> {
let s = format!("{W}x{H}");
vec![
("testsrc", format!("testsrc2=size={s}:rate=1")),
("noise", format!("nullsrc=size={s}:rate=1,geq=lum='random(1)*255':cb=128:cr=128")),
("flat", format!("color=c=0x336699:size={s}:rate=1")),
("gradient", format!("gradients=size={s}:rate=1:seed=7")),
]
}
#[test]
fn ffmpeg_files_decode_to_ffmpegs_pixels() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("jpegls");
for (name, src) in sources() {
for (fmt, ext_bits) in [("gray", 8), ("gray16le", 16)] {
let file = dir.join(format!("ffmpeg_{name}_{ext_bits}.jls"));
let f = file.to_str().expect("path");
run(&ffmpeg, &["-f", "lavfi", "-i", &src, "-frames:v", "1", "-pix_fmt", fmt, f]);
let theirs = run(&ffmpeg, &["-i", f, "-f", "rawvideo", "-pix_fmt", fmt, "-"]);
let ours = decode(&std::fs::read(&file).expect("read")).unwrap_or_else(|e| panic!("{name} {fmt}: {e}"));
assert_eq!((ours.width(), ours.height(), ours.layout()), (W, H, ChannelLayout::Gray), "{name} {fmt}");
let want_sample = if ext_bits == 8 { SampleType::U8 } else { SampleType::U16 };
assert_eq!(ours.sample_type(), want_sample);
let ours_bytes: Vec<u8> = if ext_bits == 8 {
ours.data().to_vec()
} else {
ours.data().as_chunks::<2>().0.iter().flat_map(|b| u16::from_ne_bytes(*b).to_le_bytes()).collect()
};
assert!(ours_bytes == theirs, "{name} {fmt}: pixels differ from ffmpeg's decode");
}
}
}
#[test]
fn ffmpegs_rgb_is_line_interleaved_and_unsupported() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("jpegls");
let file = dir.join("ffmpeg_rgb.jls");
run(
&ffmpeg,
&["-f", "lavfi", "-i", &format!("testsrc2=size={W}x{H}:rate=1"), "-frames:v", "1", "-pix_fmt", "rgb24", file.to_str().expect("path")],
);
assert!(matches!(decode(&std::fs::read(&file).expect("read")), Err(CodecError::Unsupported { .. })));
}
#[test]
fn ffmpeg_decodes_our_files_to_our_pixels() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("jpegls");
for (name, src) in sources() {
for (layout, fmt8, fmt16) in [(ChannelLayout::Gray, "gray", "gray16le"), (ChannelLayout::Rgb, "rgb24", "rgb48le")] {
for bits in [8, 16] {
let fmt = if bits == 8 { fmt8 } else { fmt16 };
// Source pixels from ffmpeg, so the test image is realistic.
let raw = run(&ffmpeg, &["-f", "lavfi", "-i", &src, "-frames:v", "1", "-pix_fmt", fmt, "-f", "rawvideo", "-"]);
let img = if bits == 8 {
Image::from_u8(W, H, layout, raw).expect("image")
} else {
let samples: Vec<u16> = raw.as_chunks::<2>().0.iter().map(|b| u16::from_le_bytes(*b)).collect();
Image::from_u16(W, H, layout, &samples).expect("image")
};
let bytes = encode(&img, Format::JpegLs, &EncodeOptions::default()).expect("encode");
assert_eq!(decode(&bytes).expect("our own file decodes").data(), img.data(), "{name} {fmt}: round trip");
let file = dir.join(format!("ours_{name}_{fmt}.jls"));
std::fs::write(&file, &bytes).expect("write");
// ffmpeg's decoder does not implement 16-bit colour ("Not yet implemented").
if layout == ChannelLayout::Rgb && bits == 16 {
continue;
}
let theirs = run(&ffmpeg, &["-i", file.to_str().expect("path"), "-f", "rawvideo", "-pix_fmt", fmt, "-"]);
let ours_bytes: Vec<u8> = if bits == 8 {
img.data().to_vec()
} else {
img.data().as_chunks::<2>().0.iter().flat_map(|b| u16::from_ne_bytes(*b).to_le_bytes()).collect()
};
assert!(theirs == ours_bytes, "{name} {fmt}: ffmpeg decodes our file to other pixels");
}
}
}
}
+1
View File
@@ -14,6 +14,7 @@ mod exr_stream;
mod fidelity;
mod gif_frames;
mod heif;
mod jpegls_oracle;
mod limits;
mod malformed;
mod metadata;
+94
View File
@@ -665,3 +665,97 @@ fn step_stream_gives_the_pixels_and_extras_of_decode() {
fn dec_line(w: u32, layout: ChannelLayout, sample: SampleType) -> usize {
w as usize * layout.channels() * sample.bytes()
}
#[test]
fn bounded_png_stream_does_not_charge_unretained_full_frame() {
let image = synth(256, 1024, ChannelLayout::Rgba, SampleType::U16, 77, 0.5);
let bytes = encode(&image, Format::Png, &EncodeOptions::default()).unwrap();
let limits = Limits { max_alloc: 512 * 1024, ..Limits::default() };
assert!(image.data().len() > limits.max_alloc as usize);
assert!(PngDecodeRows::new(bytes.as_slice(), &limits).is_err());
assert!(PngDecodeRows::new_streaming(bytes.as_slice(), &limits).is_err());
let mut decoder = PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &limits).unwrap();
assert!(decoder.streamable());
// Opening a stream must not become a way to bypass whole-image allocation guards.
assert!(decoder.reserve_output().is_err());
assert!(decoder.step(&mut || true).is_err());
let mut next = 0;
let mut sink = |first: u32, rows: &[u8]| -> Result<(), CodecError> {
assert_eq!(first as usize, next);
assert!(rows.len() <= 3 * 256 * 8);
let start = next * 256 * 8;
assert_eq!(rows, &image.data()[start..start + rows.len()]);
next += rows.len() / (256 * 8);
Ok(())
};
while decoder.step_stream(3, &mut || false, &mut sink).unwrap().is_none() {}
assert_eq!(next, 1024);
}
#[test]
fn bounded_png_stream_keeps_group_dimension_and_fallback_limits() {
let image = synth(256, 1024, ChannelLayout::Rgba, SampleType::U16, 81, 0.5);
let bytes = encode(&image, Format::Png, &EncodeOptions::default()).unwrap();
let limits = Limits { max_alloc: 512 * 1024, ..Limits::default() };
let mut decoder = PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &limits).unwrap();
assert!(decoder.step_stream::<CodecError>(1024, &mut || true, &mut |_, _| panic!("oversized group reached sink")).is_err());
for strict in [
Limits { max_width: 255, ..limits },
Limits { max_height: 1023, ..limits },
Limits { max_pixels: 256 * 1024 - 1, ..limits },
Limits { max_alloc: 1024, ..limits },
] {
assert!(PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &strict).is_err());
}
let adam7 = interlaced(&image);
assert!(PngDecodeRows::new_bounded_streaming(adam7.as_slice(), &limits).is_err());
}
#[test]
fn bounded_png_stream_rejects_shrinking_below_buffered_rows() {
let image = synth(16, 8, ChannelLayout::Rgba, SampleType::U16, 83, 0.5);
let bytes = encode(&image, Format::Png, &EncodeOptions::default()).unwrap();
let mut decoder = PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &Limits::default()).unwrap();
for _ in 0..3 {
assert!(decoder.step_stream::<CodecError>(4, &mut || false, &mut |_, _| panic!("group is incomplete")).unwrap().is_none());
}
assert!(decoder.step_stream::<CodecError>(1, &mut || true, &mut |_, _| panic!("changed group reached sink")).is_err());
let mut output = Vec::new();
decoder
.step_stream::<CodecError>(4, &mut || true, &mut |_, rows| {
output.extend_from_slice(rows);
Ok(())
})
.unwrap();
assert_eq!(output, image.data());
}
#[test]
fn bounded_png_stream_preserves_late_exif_across_metadata_yields() {
let image = synth(16, 8, ChannelLayout::Rgba, SampleType::U16, 89, 0.5);
let bytes = encode(&image, Format::Png, &EncodeOptions::default()).unwrap();
let mut exif = sample_exif();
exif[18..22].copy_from_slice(&6u32.to_le_bytes());
let mut chunks = vec![png_chunk(b"eXIf", &exif)];
for i in 0..150 {
chunks.push(png_chunk(b"tEXt", format!("key{i}\0value").as_bytes()));
}
let bytes = with_chunks_before_iend(&bytes, &chunks);
let mut decoder = PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &Limits::default()).unwrap();
assert!(decoder.streamable());
let mut output = Vec::new();
let extras = loop {
if let Some(extras) = decoder
.step_stream::<CodecError>(2, &mut || false, &mut |_, rows| {
output.extend_from_slice(rows);
Ok(())
})
.unwrap()
{
break extras;
}
};
assert_eq!(output, image.data());
assert_eq!(extras.orientation, 6);
assert_eq!(extras.meta.text.len(), 150);
}
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "craft-jsonrpc"
description = "Bounded JSON-RPC 2.0 server envelopes without transport or application routing"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
serde_json = { workspace = true }
+31
View File
@@ -0,0 +1,31 @@
# craft-jsonrpc
`craft-jsonrpc` provides bounded JSON-RPC 2.0 server envelopes independently of a transport or an
application's method router. It can read a bounded newline-delimited message, parse it from bytes,
check request IDs and batch sizes, dispatch requests and notifications separately, and build
response envelopes. It does not start a server, choose an MCP protocol version, or interpret tool
names and arguments.
`Limits` defaults to 64 MiB per message and 4096 batch entries. `parse_json` checks the byte limit
before deserialization, and `process` rejects an oversized batch before calling any handler.
For newline-delimited transports, `read_line` bounds memory while reading; after an over-limit
line, the caller must close the stream or discard the rest of that line.
`serde_json`'s nesting limit remains in effect. Response sizes are the caller's responsibility.
A valid request receives the handler's result or error with its original string, numeric, or null
ID. The default accepts numeric IDs as required by [JSON-RPC 2.0](https://www.jsonrpc.org/specification#request_object),
which discourages fractional values. Set `integer_ids_only` and clear `allow_null_ids` for
protocols such as MCP that require integer or string IDs. A legacy server can retain its previous
null-ID behavior independently. An omitted ID is a notification: it calls the separate notification
handler and gets no reply.
Malformed batch entries receive an invalid-request error; an empty batch gets one error response;
a batch containing only notifications has no response. Invalid parameter shapes receive an
invalid-params error for requests and no reply for notifications. The handler decides whether
object or array parameters are valid for each method.
The caller may inspect the bounded parsed value before `process` to support an existing legacy
protocol. Parse failures and limit failures are returned explicitly so each transport can choose
its error and connection policy; `parse_error_response` builds the JSON-RPC parse error.
The envelope behavior is extracted from StencilCraft's JSON-lines MCP/control server. App-specific
method routing, legacy control requests, and MCP lifecycle policy stay with the app.
+255
View File
@@ -0,0 +1,255 @@
//! Bounded JSON-RPC 2.0 server envelopes without a transport or application router.
//!
//! Parse a bounded line with [`parse_json`], then pass the value to [`process`]. A host may
//! inspect the parsed value first for a legacy protocol. `process` validates envelopes, dispatches
//! requests and notifications separately, and constructs single or batch replies. The host owns
//! the transport, method semantics and response-size policy.
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
use serde_json::{Value, json};
use std::io::BufRead;
/// Bounds on a single JSON document and on the number of requests in a batch.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Limits {
pub max_message_bytes: usize,
pub max_batch_items: usize,
/// Reject fractional JSON numbers as IDs for protocols that require integer IDs.
pub integer_ids_only: bool,
/// Permit an explicit null request ID, as JSON-RPC does; some protocols prohibit it.
pub allow_null_ids: bool,
}
impl Default for Limits {
fn default() -> Self {
Self { max_message_bytes: 64 * 1024 * 1024, max_batch_items: 4096, integer_ids_only: false, allow_null_ids: true }
}
}
/// Failure before dispatch. An over-limit batch is rejected before any callback is invoked.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ParseError {
MessageTooLarge,
InvalidJson,
BatchTooLarge,
}
impl std::fmt::Display for ParseError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(match self {
Self::MessageTooLarge => "JSON-RPC message exceeds the byte limit",
Self::InvalidJson => "invalid JSON",
Self::BatchTooLarge => "JSON-RPC batch exceeds the item limit",
})
}
}
impl std::error::Error for ParseError {}
/// Error reading a newline-delimited message. After `TooLong`, close or otherwise discard the
/// remaining input line before reading another message.
#[derive(Debug)]
pub enum LineError {
Io(std::io::Error),
TooLong,
}
impl std::fmt::Display for LineError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Io(error) => write!(f, "message read failed: {error}"),
Self::TooLong => f.write_str("message exceeds the byte limit"),
}
}
}
impl std::error::Error for LineError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Io(error) => Some(error),
Self::TooLong => None,
}
}
}
/// Read at most `max_bytes` before a newline, without allocating for an oversized line. The
/// newline is consumed but omitted from the returned bytes. EOF with no bytes returns `None`;
/// an empty line returns `Some(Vec::new())`.
pub fn read_line<R: BufRead>(reader: &mut R, max_bytes: usize) -> Result<Option<Vec<u8>>, LineError> {
let mut line = Vec::new();
loop {
let bytes = reader.fill_buf().map_err(LineError::Io)?;
if bytes.is_empty() {
return Ok((!line.is_empty()).then_some(line));
}
let newline = bytes.iter().position(|&byte| byte == b'\n');
let len = newline.unwrap_or(bytes.len());
if line.len().saturating_add(len) > max_bytes {
return Err(LineError::TooLong);
}
line.extend_from_slice(&bytes[..len]);
reader.consume(len + usize::from(newline.is_some()));
if newline.is_some() {
return Ok(Some(line));
}
}
}
/// Parse JSON after checking its byte length. `serde_json` also bounds nesting depth.
pub fn parse_json(bytes: &[u8], limits: Limits) -> Result<Value, ParseError> {
if bytes.len() > limits.max_message_bytes {
return Err(ParseError::MessageTooLarge);
}
serde_json::from_slice(bytes).map_err(|_| ParseError::InvalidJson)
}
/// A validated request or notification. A present null `id` is distinct from an omitted `id`.
#[derive(Clone, Copy, Debug)]
pub struct Request<'a> {
pub id: Option<&'a Value>,
pub method: &'a str,
pub params: Option<&'a Value>,
}
/// Inspect a single request envelope. This validates its JSON-RPC version, method and ID;
/// [`process`] additionally validates parameter shape before dispatching it.
pub fn request(value: &Value, limits: Limits) -> Option<Request<'_>> {
let object = value.as_object()?;
let id = object.get("id");
let valid_id = id.is_none_or(|v| {
(v.is_null() && limits.allow_null_ids) || v.is_string() || if limits.integer_ids_only { v.is_i64() || v.is_u64() } else { v.is_number() }
});
if object.get("jsonrpc").and_then(Value::as_str) != Some("2.0") || !valid_id {
return None;
}
Some(Request { id, method: object.get("method")?.as_str()?, params: object.get("params") })
}
/// A JSON-RPC error returned by a method handler.
#[derive(Clone, Debug, PartialEq)]
pub struct RpcError {
pub code: i64,
pub message: String,
pub data: Option<Value>,
}
impl RpcError {
pub fn new(code: i64, message: impl Into<String>) -> Self {
Self { code, message: message.into(), data: None }
}
}
/// Build an error response, including optional error data.
pub fn error_response(id: Value, error: RpcError) -> Value {
let mut detail = json!({"code": error.code, "message": error.message});
if let (Some(data), Some(object)) = (error.data, detail.as_object_mut()) {
object.insert("data".into(), data);
}
json!({"jsonrpc": "2.0", "id": id, "error": detail})
}
/// Build the standard parse-error response for input that is not JSON.
pub fn parse_error_response() -> Value {
error_response(Value::Null, RpcError::new(-32700, "Parse error"))
}
fn invalid_request() -> Value {
error_response(Value::Null, RpcError::new(-32600, "Invalid Request"))
}
fn one<F, N>(value: &Value, limits: Limits, on_request: &mut F, on_notification: &mut N) -> Option<Value>
where
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
N: FnMut(Request<'_>),
{
let Some(request) = request(value, limits) else { return Some(invalid_request()) };
let id = request.id;
if request.params.is_some_and(|v| !v.is_object() && !v.is_array()) {
return id.map(|id| error_response(id.clone(), RpcError::new(-32602, "Invalid params")));
}
let Some(id) = id else {
on_notification(request);
return None;
};
Some(match on_request(request) {
Ok(result) => json!({"jsonrpc": "2.0", "id": id, "result": result}),
Err(error) => error_response(id.clone(), error),
})
}
/// Process a parsed JSON-RPC message. Notifications never receive a response. Invalid batch
/// entries produce individual errors; an empty batch produces one invalid-request response.
/// A batch over the limit returns [`ParseError::BatchTooLarge`] without invoking either callback.
pub fn process<F, N>(value: &Value, limits: Limits, mut on_request: F, mut on_notification: N) -> Result<Option<Value>, ParseError>
where
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
N: FnMut(Request<'_>),
{
let Some(batch) = value.as_array() else { return Ok(one(value, limits, &mut on_request, &mut on_notification)) };
if batch.len() > limits.max_batch_items {
return Err(ParseError::BatchTooLarge);
}
if batch.is_empty() {
return Ok(Some(invalid_request()));
}
let responses: Vec<_> = batch.iter().filter_map(|v| one(v, limits, &mut on_request, &mut on_notification)).collect();
Ok((!responses.is_empty()).then_some(Value::Array(responses)))
}
/// Process a permissive legacy JSON-RPC envelope. This mode accepts arbitrary IDs and
/// parameter shapes, ignores response envelopes, and retains legacy diagnostic messages.
/// The caller supplies dispatch and notification callbacks, and should bound transport input.
pub fn process_legacy<F, N>(value: &Value, mut on_request: F, mut on_notification: N) -> Option<Value>
where
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
N: FnMut(Request<'_>),
{
fn one<F, N>(value: &Value, on_request: &mut F, on_notification: &mut N) -> Option<Value>
where
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
N: FnMut(Request<'_>),
{
let Some(object) = value.as_object() else { return Some(error_response(Value::Null, RpcError::new(-32600, "message must be an object"))) };
let id = object.get("id");
let Some(method) = object.get("method").and_then(Value::as_str) else {
if object.contains_key("result") || object.contains_key("error") {
return None;
}
return Some(error_response(id.cloned().unwrap_or(Value::Null), RpcError::new(-32600, "missing `method`")));
};
let request = Request { id, method, params: object.get("params") };
let Some(id) = id else {
on_notification(request);
return None;
};
Some(match on_request(request) {
Ok(result) => json!({"jsonrpc": "2.0", "id": id, "result": result}),
Err(error) => error_response(id.clone(), error),
})
}
if let Some(batch) = value.as_array() {
if batch.is_empty() {
return Some(error_response(Value::Null, RpcError::new(-32600, "empty batch")));
}
let replies: Vec<_> = batch.iter().filter_map(|v| one(v, &mut on_request, &mut on_notification)).collect();
(!replies.is_empty()).then_some(Value::Array(replies))
} else {
one(value, &mut on_request, &mut on_notification)
}
}
#[cfg(test)]
mod legacy_tests {
use super::*;
#[test]
fn preserves_legacy_batch_routing_and_errors() {
let input = json!([{"id": [1], "method":"echo", "params":5}, {"method":"notice"}, {"result":1}, {}, 7]);
let seen = std::cell::Cell::new(false);
let result = process_legacy(&input, |r| Ok(r.params.cloned().unwrap_or(Value::Null)), |_| seen.set(true)).unwrap();
assert!(seen.get());
assert_eq!(
result,
json!([{"jsonrpc":"2.0","id":[1],"result":5}, {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"missing `method`"}}, {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"message must be an object"}}])
);
assert_eq!(process_legacy(&json!([]), |_| Ok(Value::Null), |_| {}).unwrap()["error"]["message"], "empty batch");
}
}
+172
View File
@@ -0,0 +1,172 @@
use craft_jsonrpc::{Limits, ParseError, RpcError, parse_error_response, parse_json, process};
use serde_json::{Value, json};
#[test]
fn batches_preserve_ids_order_and_suppress_notification_replies() {
let input = json!([
{"jsonrpc": "2.0", "method": "notifications/initialized"},
{"jsonrpc": "2.0", "id": "a", "method": "ping"},
{"jsonrpc": "2.0", "id": 2, "method": "unknown"},
17,
{"jsonrpc": "2.0", "id": null, "method": "ping"}
]);
let mut notifications = Vec::new();
let result = process(
&input,
Limits::default(),
|request| match request.method {
"ping" => Ok(json!({})),
_ => Err(RpcError::new(-32601, "Method not found")),
},
|request| notifications.push(request.method.to_owned()),
)
.unwrap()
.unwrap();
assert_eq!(notifications, ["notifications/initialized"]);
assert_eq!(
result,
json!([
{"jsonrpc":"2.0", "id":"a", "result":{}},
{"jsonrpc":"2.0", "id":2, "error":{"code":-32601,"message":"Method not found"}},
{"jsonrpc":"2.0", "id":null, "error":{"code":-32600,"message":"Invalid Request"}},
{"jsonrpc":"2.0", "id":null, "result":{}}
])
);
}
#[test]
fn notifications_never_receive_responses_including_all_notification_batches() {
let input = json!([
{"jsonrpc":"2.0", "method":"tools/call", "params":{"name":"mutating"}},
{"jsonrpc":"2.0", "method":"notifications/initialized"}
]);
let mut requests = 0;
let mut notices = 0;
let result = process(
&input,
Limits::default(),
|_| {
requests += 1;
Ok(Value::Null)
},
|_| notices += 1,
)
.unwrap();
assert!(result.is_none());
assert_eq!(requests, 0);
assert_eq!(notices, 2);
}
#[test]
fn invalid_envelopes_and_params_return_standard_errors() {
for id in [json!(true), json!([]), json!({})] {
let input = json!({"jsonrpc":"2.0", "id":id, "method":"ping"});
let reply = process(&input, Limits::default(), |_| panic!("invalid id dispatched"), |_| panic!("invalid id notified")).unwrap().unwrap();
assert_eq!(reply["id"], Value::Null);
assert_eq!(reply["error"]["code"], -32600);
}
for input in [json!({}), json!({"jsonrpc":"1.0", "id":1, "method":"ping"}), json!({"jsonrpc":"2.0", "id":1}), json!([])] {
let reply =
process(&input, Limits::default(), |_| panic!("invalid request dispatched"), |_| panic!("invalid notification")).unwrap().unwrap();
assert_eq!(reply["error"]["code"], -32600);
}
let input = json!({"jsonrpc":"2.0", "id":4, "method":"ping", "params":17});
let reply = process(&input, Limits::default(), |_| panic!("invalid params dispatched"), |_| {}).unwrap().unwrap();
assert_eq!(reply["id"], 4);
assert_eq!(reply["error"]["code"], -32602);
let notification = json!({"jsonrpc":"2.0", "method":"notice", "params":17});
assert!(process(&notification, Limits::default(), |_| panic!("invalid request"), |_| panic!("invalid notification")).unwrap().is_none());
}
#[test]
fn arrays_are_valid_params_and_errors_can_include_data() {
let input = json!({"jsonrpc":"2.0", "id":-7, "method":"test", "params":[1, 2]});
let reply = process(
&input,
Limits::default(),
|request| {
assert_eq!(request.params, Some(&json!([1, 2])));
let mut error = RpcError::new(-32000, "failure");
error.data = Some(json!({"why":"example"}));
Err(error)
},
|_| {},
)
.unwrap()
.unwrap();
assert_eq!(reply, json!({"jsonrpc":"2.0", "id":-7, "error":{"code":-32000,"message":"failure","data":{"why":"example"}}}));
}
#[test]
fn parse_and_batch_limits_apply_before_dispatch() {
let limits = Limits { max_message_bytes: 3, max_batch_items: 1, ..Limits::default() };
assert_eq!(parse_json(b"null", limits), Err(ParseError::MessageTooLarge));
assert_eq!(parse_json(b"123", limits).unwrap(), json!(123));
assert_eq!(parse_json(b"{", limits), Err(ParseError::InvalidJson));
assert_eq!(parse_error_response()["error"]["code"], -32700);
let input = json!([{"jsonrpc":"2.0", "id":1, "method":"ping"}, {"jsonrpc":"2.0", "method":"notice"}]);
assert_eq!(
process(&input, limits, |_| panic!("over-limit batch dispatched"), |_| panic!("over-limit batch notified")),
Err(ParseError::BatchTooLarge)
);
let one = json!([{"jsonrpc":"2.0", "id":1, "method":"ping"}]);
assert_eq!(process(&one, limits, |_| Ok(json!({})), |_| {}).unwrap().unwrap().as_array().unwrap().len(), 1);
}
#[test]
fn invalid_utf8_and_excessive_nesting_are_rejected() {
assert_eq!(parse_json(&[0xff], Limits::default()), Err(ParseError::InvalidJson));
let nested = format!("{}0{}", "[".repeat(200), "]".repeat(200));
assert_eq!(parse_json(nested.as_bytes(), Limits::default()), Err(ParseError::InvalidJson));
}
#[test]
fn bounded_line_read_handles_chunks_empty_lines_and_eof() {
use std::io::{BufReader, Cursor};
let mut reader = BufReader::with_capacity(2, Cursor::new(b"abc\n\nxy"));
assert_eq!(craft_jsonrpc::read_line(&mut reader, 3).unwrap(), Some(b"abc".to_vec()));
assert_eq!(craft_jsonrpc::read_line(&mut reader, 3).unwrap(), Some(Vec::new()));
assert_eq!(craft_jsonrpc::read_line(&mut reader, 3).unwrap(), Some(b"xy".to_vec()));
assert_eq!(craft_jsonrpc::read_line(&mut reader, 3).unwrap(), None);
let mut too_long = BufReader::with_capacity(2, Cursor::new(b"abcd\n"));
assert!(matches!(craft_jsonrpc::read_line(&mut too_long, 3), Err(craft_jsonrpc::LineError::TooLong)));
}
#[test]
fn bounded_line_read_propagates_io_errors() {
struct Broken;
impl std::io::Read for Broken {
fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
Err(std::io::Error::other("broken"))
}
}
let mut reader = std::io::BufReader::new(Broken);
assert!(matches!(craft_jsonrpc::read_line(&mut reader, 1), Err(craft_jsonrpc::LineError::Io(_))));
}
#[test]
fn inspect_single_request_distinguishes_null_ids_and_invalid_envelopes() {
let request = json!({"jsonrpc":"2.0", "id":null, "method":"ping"});
let parsed = craft_jsonrpc::request(&request, Limits::default()).unwrap();
assert_eq!(parsed.id, Some(&Value::Null));
assert_eq!(parsed.method, "ping");
let notification = json!({"jsonrpc":"2.0", "method":"ping"});
assert!(craft_jsonrpc::request(&notification, Limits::default()).unwrap().id.is_none());
assert!(craft_jsonrpc::request(&json!({"jsonrpc":"2.0", "id":false, "method":"ping"}), Limits::default()).is_none());
assert!(craft_jsonrpc::request(&json!({"method":"ping"}), Limits::default()).is_none());
}
#[test]
fn numeric_ids_follow_the_selected_protocol_policy() {
let input = json!({"jsonrpc":"2.0", "id":1.5, "method":"ping"});
let reply = process(&input, Limits::default(), |_| Ok(json!({})), |_| {}).unwrap().unwrap();
assert_eq!(reply["id"], json!(1.5));
let strict = Limits { integer_ids_only: true, ..Limits::default() };
let reply = process(&input, strict, |_| panic!("fractional ID dispatched"), |_| {}).unwrap().unwrap();
assert_eq!(reply["id"], Value::Null);
assert_eq!(reply["error"]["code"], -32600);
let no_null = Limits { allow_null_ids: false, ..strict };
let null_id = json!({"jsonrpc":"2.0", "id":null, "method":"ping"});
let reply = process(&null_id, no_null, |_| panic!("null ID dispatched"), |_| {}).unwrap().unwrap();
assert_eq!(reply["error"]["code"], -32600);
}
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "craft-mcmat"
description = "Bounded portable material archive interchange for Craft applications"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-zip = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
+17
View File
@@ -0,0 +1,17 @@
# craft-mcmat
A bounded reader and writer for portable MaterialCraft `.mcmat` ZIP packages. A package
contains `material.json`, named texture maps and a source package. Applications interpret
parameter values and cook or render maps themselves; this crate does not depend on an app's
model. It supports callers that read either version 1 or version 2 of the manifest, or both.
`is_material` checks for a manifest with a bounded ZIP index; `Material::open` takes caller-provided version, entry-count, map-count, per-entry and total
expanded-byte limits. Each subsequent `read` and `read_source` shares that budget, including
repeated references to the same ZIP member. Duplicate member names are refused. The manifest
preserves unknown fields at the top level and on maps; parameter, input and preset objects are
kept as JSON values so their unknown fields survive too. `write` preserves the caller's source
entry name and map names, and rejects duplicate archive member names through `craft-zip`.
The source package is opaque. Version 1 commonly names `source.mcraft`; MaterialCraft's version 2
writer names `source.sbs`. Callers that invoke another application must preserve the source's
format and extension rather than infer it from `.mcmat` alone.
+216
View File
@@ -0,0 +1,216 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
//! Bounded interchange for MaterialCraft portable materials (`.mcmat`).
//!
//! The manifest and its version belong to the format, while interpreting parameter values,
//! cooking maps and opening the source package belong to the caller. Unknown fields survive
//! deserialization and serialization, including fields added by later versions.
use std::collections::BTreeMap;
use craft_zip::{Archive, Compression, Writer};
use serde::{Deserialize, Serialize};
use serde_json::Value;
pub const FORMAT: &str = "craft-material";
pub const MANIFEST_ENTRY: &str = "material.json";
/// A portable manifest; typed parameter values remain JSON so applications can adapt their own model.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Manifest {
pub format: String,
pub version: u32,
pub name: String,
pub graph: String,
pub size: [u32; 2],
pub maps: Vec<MapEntry>,
#[serde(default)]
pub parameters: Vec<Value>,
#[serde(default)]
pub inputs: Vec<Value>,
#[serde(default)]
pub presets: Vec<Value>,
pub source: String,
#[serde(flatten)]
pub extra: BTreeMap<String, Value>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MapEntry {
pub usage: String,
pub file: String,
#[serde(flatten)]
pub extra: BTreeMap<String, Value>,
}
/// All limits are supplied by the consumer, including the versions it understands.
#[derive(Clone, Copy, Debug)]
pub struct Limits {
pub min_version: u32,
pub max_version: u32,
pub max_entries: u64,
pub max_maps: usize,
pub max_manifest_bytes: u64,
pub max_entry_bytes: u64,
pub max_total_bytes: u64,
}
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("invalid portable material: {0}")]
Invalid(String),
#[error("unsupported portable material version {0}")]
Version(u32),
#[error("portable material limit: {0}")]
Limit(String),
#[error("portable material archive: {0}")]
Archive(#[from] craft_zip::Error),
}
/// Whether a bounded ZIP index contains a material manifest. This does not validate the manifest.
pub fn is_material(bytes: &[u8], max_entries: u64) -> bool {
Archive::open(bytes, craft_zip::Limits { max_entries, max_total_bytes: 0 })
.is_ok_and(|archive| !archive.has_duplicate_names() && archive.contains(MANIFEST_ENTRY))
}
/// Manifest and original archive, retaining one shared expanded-byte budget across reads.
pub struct Material<'a> {
pub manifest: Manifest,
archive: Archive<'a>,
max_entry_bytes: u64,
}
impl<'a> Material<'a> {
pub fn open(bytes: &'a [u8], limits: Limits) -> Result<Self, Error> {
let mut archive = Archive::open(bytes, craft_zip::Limits { max_entries: limits.max_entries, max_total_bytes: limits.max_total_bytes })?;
if archive.has_duplicate_names() {
return Err(Error::Invalid("duplicate archive entries".into()));
}
let json = archive.read(MANIFEST_ENTRY, limits.max_manifest_bytes)?.ok_or_else(|| Error::Invalid("material.json is missing".into()))?;
let manifest: Manifest = serde_json::from_slice(&json).map_err(|e| Error::Invalid(format!("material.json: {e}")))?;
if manifest.format != FORMAT {
return Err(Error::Invalid(format!("format `{}`", manifest.format)));
}
if !(limits.min_version..=limits.max_version).contains(&manifest.version) {
return Err(Error::Version(manifest.version));
}
if manifest.maps.len() > limits.max_maps {
return Err(Error::Limit(format!("{} maps exceeds {}", manifest.maps.len(), limits.max_maps)));
}
Ok(Self { manifest, archive, max_entry_bytes: limits.max_entry_bytes })
}
/// Read one named member, charging it to the same budget as previous reads.
pub fn read(&mut self, name: &str) -> Result<Vec<u8>, Error> {
self.archive.read(name, self.max_entry_bytes)?.ok_or_else(|| Error::Invalid(format!("{name} is missing")))
}
pub fn read_source(&mut self) -> Result<Vec<u8>, Error> {
self.read(&self.manifest.source.clone())
}
}
/// Write a manifest, its named maps, and the source. Duplicate member names are rejected.
pub fn write(manifest: &Manifest, maps: &[(String, Vec<u8>)], source: &[u8]) -> Result<Vec<u8>, Error> {
// Flattened fields must not serialize a second copy of a known key.
const KNOWN: &[&str] = &["format", "version", "name", "graph", "size", "maps", "parameters", "inputs", "presets", "source"];
if manifest.extra.keys().any(|key| KNOWN.contains(&key.as_str()))
|| manifest.maps.iter().any(|map| map.extra.contains_key("usage") || map.extra.contains_key("file"))
{
return Err(Error::Invalid("an extra field duplicates a known field".into()));
}
let json = serde_json::to_vec_pretty(manifest).map_err(|e| Error::Invalid(format!("material.json: {e}")))?;
let mut writer = Writer::new();
writer.add(MANIFEST_ENTRY, &json, Compression::Deflated)?;
for (name, bytes) in maps {
writer.add(name, bytes, Compression::Stored)?;
}
writer.add(&manifest.source, source, Compression::Stored)?;
Ok(writer.finish()?)
}
#[cfg(test)]
mod tests {
use super::*;
fn limits() -> Limits {
Limits {
min_version: 1,
max_version: 2,
max_entries: 100,
max_maps: 4,
max_manifest_bytes: 4096,
max_entry_bytes: 100,
max_total_bytes: 8192,
}
}
fn sample(version: u32) -> Manifest {
serde_json::from_value(serde_json::json!({
"format": "craft-material", "version": version, "name": "Stone", "graph": "Stone", "size": [64, 64],
"maps": [{"usage": "baseColor", "file": "maps/base.png", "colorSpace": "srgb", "futureMap": true}],
"parameters": [{"id": "rough", "value": {"t": "float", "v": 0.25}, "futureParam": 42}],
"inputs": [{"identifier": "curvature", "kind": "gray"}], "presets": [],
"source": if version == 1 { "source.mcraft" } else { "source.sbs" }, "futureField": {"keep": true}
}))
.unwrap()
}
#[test]
fn both_protocol_versions_keep_unknown_fields_and_payloads() {
for version in [1, 2] {
let manifest = sample(version);
let bytes = write(&manifest, &[("maps/base.png".into(), vec![1, 2, 3])], b"source").unwrap();
assert!(is_material(&bytes, 100));
assert!(!is_material(&bytes, 1));
let mut material = Material::open(&bytes, limits()).unwrap();
assert_eq!(material.manifest, manifest);
assert_eq!(material.read("maps/base.png").unwrap(), [1, 2, 3]);
assert_eq!(material.read_source().unwrap(), b"source");
let json = serde_json::to_value(&material.manifest).unwrap();
assert_eq!(json["futureField"]["keep"], true);
assert_eq!(json["maps"][0]["futureMap"], true);
assert_eq!(json["parameters"][0]["futureParam"], 42);
}
}
#[test]
fn limits_apply_to_the_manifest_maps_and_aggregate_reads() {
let manifest = sample(2);
let bytes = write(&manifest, &[("maps/base.png".into(), vec![1; 8])], &[2; 8]).unwrap();
let mut unsupported = limits();
unsupported.max_version = 1;
assert!(matches!(Material::open(&bytes, unsupported), Err(Error::Version(2))));
let mut no_maps = limits();
no_maps.max_maps = 0;
assert!(matches!(Material::open(&bytes, no_maps), Err(Error::Limit(_))));
let mut tiny_entry = limits();
tiny_entry.max_entry_bytes = 7;
assert!(Material::open(&bytes, tiny_entry).unwrap().read("maps/base.png").is_err());
let json_len = serde_json::to_vec_pretty(&manifest).unwrap().len() as u64;
let mut aggregate = limits();
aggregate.max_total_bytes = json_len + 15;
let mut material = Material::open(&bytes, aggregate).unwrap();
assert_eq!(material.read("maps/base.png").unwrap().len(), 8);
assert!(material.read_source().is_err());
}
#[test]
fn refuses_extra_fields_that_duplicate_known_keys() {
let mut manifest = sample(2);
manifest.extra.insert("version".into(), 3.into());
assert!(write(&manifest, &[], b"source").is_err());
manifest.extra.remove("version");
manifest.maps[0].extra.insert("file".into(), "other".into());
assert!(write(&manifest, &[], b"source").is_err());
}
#[test]
fn refuses_duplicate_names_on_write() {
let manifest = sample(2);
let duplicate = [("maps/base.png".to_string(), vec![1]), ("maps/base.png".to_string(), vec![2])];
assert!(write(&manifest, &duplicate, b"source").is_err());
}
}
+15
View File
@@ -0,0 +1,15 @@
[package]
name = "craft-mcp"
description = "Transport-independent MCP server initialization and tool envelopes"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-jsonrpc = { workspace = true }
serde_json = { workspace = true }
+17
View File
@@ -0,0 +1,17 @@
# craft-mcp
Transport-independent MCP 2025-03-26 server initialization and tool result helpers.
Use one `Session` per client connection with `craft-jsonrpc` for message parsing and
batch dispatch. The caller owns transport, tool definitions and execution, response
size limits, and shutdown. Pass the outer envelope's batch status to `Session::request`.
`Policy::Compatible` retains existing permissive clients: tool calls can precede
initialization, initialization can occur in a batch, and client information needs only
to be an object. `Policy::Strict` requires initialization first (except ping),
rejects batched or repeated initialization, and requires client name and version.
Both respond with the sole supported version, 2025-03-26, even if the client offered
a different version. An initialized notification moves the session to `Ready`.
This crate does not enforce every MCP lifecycle or capability rule; applications
must validate any additional requirements they depend on.
See the [MCP lifecycle specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/lifecycle).
+275
View File
@@ -0,0 +1,275 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! MCP 2025-03-26 server initialization and tool envelopes, independent of transport and tools.
//! The caller owns routing, transport and JSON-RPC batching. Compatibility mode preserves servers
//! that accepted calls before initialization and initialize in a batch; strict mode enforces the
//! initialization ordering and batch prohibition. Create one session per connection.
use craft_jsonrpc::{Request, RpcError};
use serde_json::{Value, json};
pub const PROTOCOL_VERSION: &str = "2025-03-26";
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Policy {
/// Preserve existing permissive servers, including minimal client information.
#[default]
Compatible,
/// Enforce the initialize request and client identity required by MCP.
Strict,
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum State {
#[default]
New,
AwaitingInitialized,
Ready,
}
/// State for one connection. Unknown requests are left to the caller's router.
pub struct Session {
name: String,
version: String,
policy: Policy,
state: State,
capabilities: Value,
versions: Vec<String>,
permissive_initialize: bool,
server_info: Option<Value>,
instructions: Option<String>,
initialized: bool,
}
impl Session {
pub fn new(name: impl Into<String>, version: impl Into<String>, policy: Policy) -> Self {
Self {
name: name.into(),
version: version.into(),
policy,
state: State::New,
capabilities: json!({"tools": {}}),
versions: vec![PROTOCOL_VERSION.into()],
permissive_initialize: false,
server_info: None,
instructions: None,
initialized: false,
}
}
/// Set the server capabilities returned at initialization. The value must be an object.
pub fn with_capabilities(mut self, capabilities: Value) -> Result<Self, RpcError> {
if !capabilities.is_object() {
return Err(RpcError::new(-32602, "Capabilities must be an object"));
}
self.capabilities = capabilities;
Ok(self)
}
/// Configure a permissive legacy server: absent or malformed initialize parameters are
/// accepted, supported client versions are echoed, and unknown versions use the first entry.
pub fn with_legacy_initialize(mut self, versions: &[&str], server_info: Value) -> Self {
if !versions.is_empty() {
self.versions = versions.iter().map(|v| (*v).to_owned()).collect();
}
self.permissive_initialize = true;
self.server_info = Some(server_info);
self
}
/// Update connection-specific instructions returned by subsequent initialize requests.
pub fn set_instructions(&mut self, instructions: String) {
self.instructions = Some(instructions);
}
/// Whether an initialized notification has been observed, including before initialize.
pub fn is_initialized(&self) -> bool {
self.initialized
}
pub fn state(&self) -> State {
self.state
}
/// Handles `initialize` and `ping`. Returns `None` for a request the app should route.
/// `in_batch` must describe the outer JSON-RPC envelope.
pub fn request(&mut self, request: Request<'_>, in_batch: bool) -> Option<Result<Value, RpcError>> {
if request.method == "ping" {
return Some(Ok(json!({})));
}
if request.method == "initialize" {
if self.policy == Policy::Strict && (in_batch || self.state != State::New) {
return Some(Err(RpcError::new(-32600, "Invalid Request")));
}
if self.permissive_initialize {
let asked = request.params.and_then(|p| p.get("protocolVersion")).and_then(Value::as_str);
let version = asked
.filter(|v| self.versions.iter().any(|supported| supported == v))
.unwrap_or_else(|| self.versions.first().map(String::as_str).unwrap_or(PROTOCOL_VERSION));
let mut result = json!({"protocolVersion": version, "capabilities": self.capabilities, "serverInfo": self.server_info});
if let Some(instructions) = &self.instructions {
result["instructions"] = json!(instructions);
}
self.state = State::AwaitingInitialized;
return Some(Ok(result));
}
let Some(params) = request.params.and_then(Value::as_object) else {
return Some(Err(invalid_initialize()));
};
let valid = params.get("protocolVersion").and_then(Value::as_str).is_some()
&& params.get("capabilities").is_some_and(Value::is_object)
&& params.get("clientInfo").is_some_and(Value::is_object);
let identity = params.get("clientInfo").and_then(Value::as_object);
let strict_identity = identity
.is_some_and(|info| info.get("name").and_then(Value::as_str).is_some() && info.get("version").and_then(Value::as_str).is_some());
if !valid || (self.policy == Policy::Strict && !strict_identity) {
return Some(Err(invalid_initialize()));
}
self.state = State::AwaitingInitialized;
return Some(Ok(
json!({"protocolVersion": PROTOCOL_VERSION, "capabilities": self.capabilities, "serverInfo": {"name": self.name, "version": self.version}}),
));
}
if self.policy == Policy::Strict && self.state == State::New {
return Some(Err(RpcError::new(-32600, "Server not initialized")));
}
None
}
/// Observe a JSON-RPC notification; notifications never receive replies.
pub fn notification(&mut self, request: Request<'_>) {
if request.method == "notifications/initialized" {
self.initialized = true;
if self.state == State::AwaitingInitialized {
self.state = State::Ready;
}
}
}
}
fn invalid_initialize() -> RpcError {
RpcError::new(-32602, "Invalid initialize parameters")
}
/// Validate MCP tool-call parameters without owning the application's tool routing.
pub fn tool_call(params: &Value) -> Result<(&str, Value), RpcError> {
let name = params.get("name").and_then(Value::as_str).ok_or_else(|| RpcError::new(-32602, "Missing tool name"))?;
let arguments = params.get("arguments").cloned().unwrap_or_else(|| json!({}));
if !arguments.is_object() {
return Err(RpcError::new(-32602, "Tool arguments must be an object"));
}
Ok((name, arguments))
}
/// Wrap an application-provided tool list in the MCP result envelope.
pub fn tool_list(tools: Value) -> Value {
json!({"tools": tools})
}
/// Construct the text result currently used by Craft's MCP tools.
pub fn text_tool_result(text: &str, is_error: bool) -> Value {
json!({"content": [{"type": "text", "text": text}], "isError": is_error})
}
#[cfg(test)]
mod tests {
use super::*;
fn call<'a>(method: &'a str, params: Option<&'a Value>) -> Request<'a> {
Request { id: None, method, params }
}
#[test]
fn legacy_initialization_negotiates_and_accepts_missing_parameters() {
let mut s = Session::new("test", "1", Policy::Compatible).with_legacy_initialize(&["new", "old"], json!({"name":"custom", "title":"Title"}));
s.notification(call("notifications/initialized", None));
assert!(s.is_initialized());
s.set_instructions("help".into());
for (params, expected) in
[(None, "new"), (Some(json!({"protocolVersion":"old"})), "old"), (Some(json!({"protocolVersion":"unknown"})), "new")]
{
let result = s.request(call("initialize", params.as_ref()), false).unwrap().unwrap();
assert_eq!(result["protocolVersion"], expected);
assert_eq!(result["serverInfo"]["title"], "Title");
assert_eq!(result["instructions"], "help");
}
}
#[test]
fn compatible_negotiation_preserves_existing_clients() {
let mut s = Session::new("test", "1", Policy::Compatible);
assert!(s.request(call("tools/list", None), false).is_none());
let p = json!({"protocolVersion":"old", "capabilities":{}, "clientInfo":{}});
let r = s.request(call("initialize", Some(&p)), true).unwrap().unwrap();
assert_eq!(r["protocolVersion"], PROTOCOL_VERSION);
assert_eq!(r["serverInfo"]["name"], "test");
assert_eq!(s.state(), State::AwaitingInitialized);
s.notification(call("notifications/initialized", None));
assert_eq!(s.state(), State::Ready);
}
#[test]
fn strict_rejects_batch_and_calls_before_initialization() {
let mut s = Session::new("test", "1", Policy::Strict);
assert_eq!(s.request(call("tools/list", None), false).unwrap().unwrap_err().code, -32600);
assert!(s.request(call("ping", None), false).unwrap().is_ok());
let p = json!({"protocolVersion":PROTOCOL_VERSION, "capabilities":{}, "clientInfo":{"name":"client", "version":"1"}});
assert!(s.request(call("initialize", Some(&p)), true).unwrap().is_err());
assert_eq!(s.state(), State::New);
assert!(s.request(call("initialize", Some(&p)), false).unwrap().is_ok());
assert!(s.request(call("initialize", Some(&p)), false).unwrap().is_err());
s.notification(call("notifications/initialized", None));
assert_eq!(s.state(), State::Ready);
}
#[test]
fn capabilities_are_configurable_and_must_be_an_object() {
assert!(Session::new("test", "1", Policy::Compatible).with_capabilities(json!([])).is_err());
let mut session = Session::new("test", "1", Policy::Compatible).with_capabilities(json!({"resources": {"subscribe": true}})).unwrap();
let params = json!({"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {}});
let result = session.request(call("initialize", Some(&params)), false).unwrap().unwrap();
assert_eq!(result["capabilities"], json!({"resources": {"subscribe": true}}));
}
#[test]
fn malformed_initialize_does_not_change_state() {
let mut s = Session::new("test", "1", Policy::Strict);
for p in [json!({}), json!({"protocolVersion":"x", "capabilities":{}, "clientInfo":{}})] {
assert_eq!(s.request(call("initialize", Some(&p)), false).unwrap().unwrap_err().code, -32602);
assert_eq!(s.state(), State::New);
}
}
#[test]
fn tool_envelopes_validate_arguments_and_preserve_results() {
let p = json!({"name":"open"});
assert_eq!(tool_call(&p).unwrap(), ("open", json!({})));
assert_eq!(tool_call(&json!({"name":"open", "arguments":[]})).unwrap_err().code, -32602);
assert_eq!(tool_call(&json!({})).unwrap_err().code, -32602);
assert_eq!(text_tool_result("bad", true), json!({"content":[{"type":"text", "text":"bad"}], "isError":true}));
}
#[test]
fn jsonrpc_batch_preserves_ids_and_skips_notifications() {
use std::cell::RefCell;
let session = RefCell::new(Session::new("test", "1", Policy::Compatible));
let input = json!([
{"jsonrpc":"2.0", "id":1, "method":"initialize", "params":{"protocolVersion":"2025-03-26", "capabilities":{}, "clientInfo":{}}},
{"jsonrpc":"2.0", "method":"notifications/initialized"},
{"jsonrpc":"2.0", "id":"tools", "method":"tools/list"}
]);
let reply = craft_jsonrpc::process(
&input,
craft_jsonrpc::Limits::default(),
|r| session.borrow_mut().request(r, true).unwrap_or_else(|| Ok(tool_list(json!([])))),
|r| session.borrow_mut().notification(r),
)
.unwrap()
.unwrap();
assert_eq!(reply.as_array().unwrap().len(), 2);
assert_eq!(reply[0]["id"], 1);
assert_eq!(reply[1]["id"], "tools");
assert_eq!(reply[1]["result"]["tools"], json!([]));
assert_eq!(session.borrow().state(), State::Ready);
}
}
+445
View File
@@ -0,0 +1,445 @@
//! Unnormalized camera-field EXIF view, reused from PhotoCraft (exposure, aperture,
//! ISO, focal length, camera and lens names). Input is the raw TIFF-structured EXIF payload
//! (`II*\0` / `MM\0*`, as stored in `Document.metadata.exif`); malformed data yields `None`
//! fields, never a panic. Tag numbers are from the EXIF 2.32 specification (CIPA DC-008).
// Semantics originate in PhotoCraft, including Brandon Thomas and Fabio Lussi.
// Unlike read_exif this view does not normalize dates or derive missing fields.
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used, clippy::panic))]
/// Camera settings read from EXIF.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct CameraInfo {
pub make: Option<String>,
pub model: Option<String>,
pub lens: Option<String>,
/// Seconds.
pub exposure_time: Option<f64>,
pub f_number: Option<f64>,
pub iso: Option<f64>,
/// Millimetres.
pub focal_length: Option<f64>,
/// 35 mm-equivalent focal length in millimetres.
pub focal_length_35mm: Option<f64>,
/// DateTimeOriginal as stored (`YYYY:MM:DD HH:MM:SS`).
pub date_taken: Option<String>,
}
impl CameraInfo {
/// Linear exposure factor `t · ISO / N²` (relative brightness of the image for one scene).
pub fn exposure_factor(&self) -> Option<f64> {
let t = self.exposure_time?;
let n = self.f_number.unwrap_or(1.0).max(0.1);
Some(t * self.iso.unwrap_or(100.0) / 100.0 / (n * n))
}
}
/// Text bytes decoded per EXIF read (real Make/Model/Lens/Date strings are a few dozen bytes).
const MAX_TEXT_BYTES: usize = 1 << 20;
struct Tiff<'a> {
b: &'a [u8],
order: craft_tiff::ByteOrder,
/// Text bytes this read may still decode: duplicate tags can share one large blank value.
text_left: std::cell::Cell<usize>,
}
impl Tiff<'_> {
fn u16(&self, o: usize) -> Option<u16> {
self.order.read_u16(self.b, o)
}
fn u32(&self, o: usize) -> Option<u32> {
self.order.read_u32(self.b, o)
}
/// Entries of the IFD at `off`: (tag, type, count, value offset field position).
fn ifd(&self, off: usize) -> Vec<(u16, u16, u32, usize)> {
let Some(n) = self.u16(off) else { return Vec::new() };
(0..n as usize)
.filter_map(|k| {
// Checked: offsets come from the file, and usize is 32 bits on wasm.
let e = off.checked_add(2)?.checked_add(k * 12)?;
Some((self.u16(e)?, self.u16(e.checked_add(2)?)?, self.u32(e.checked_add(4)?)?, e.checked_add(8)?))
})
.collect()
}
fn data_at(&self, typ: u16, _count: u32, field: usize) -> Option<usize> {
// Keep this caller's historical classic-TIFF type policy; shared spans also
// support IFD/BigTIFF types which CameraInfo never accepted.
if !(1..=12).contains(&typ) {
return None;
}
let span = craft_tiff::entry_span(self.b, field.checked_sub(8)?, self.order, false, 0)?;
usize::try_from(span.start).ok()
}
fn number(&self, typ: u16, count: u32, field: usize) -> Option<f64> {
let at = self.data_at(typ, count, field)?;
match typ {
3 => self.u16(at).map(f64::from),
4 => self.u32(at).map(f64::from),
5 => {
let (n, d) = (self.u32(at)?, self.u32(at.checked_add(4)?)?);
(d != 0).then(|| n as f64 / d as f64)
}
10 => {
let (n, d) = (self.u32(at)? as i32, self.u32(at.checked_add(4)?)? as i32);
(d != 0).then(|| n as f64 / d as f64)
}
_ => None,
}
}
fn text(&self, typ: u16, count: u32, field: usize) -> Option<String> {
#[cfg(test)]
TEXT_DECODES.with(|c| c.set(c.get() + 1));
if typ != 2 {
return None;
}
let at = self.data_at(typ, count, field)?;
let n = usize::try_from(count).ok()?;
self.text_left.set(self.text_left.get().checked_sub(n)?);
let s = self.b.get(at..at.checked_add(n)?)?;
let s = String::from_utf8_lossy(s).trim_end_matches('\0').trim().to_string();
(!s.is_empty()).then_some(s)
}
}
#[cfg(test)]
thread_local!(static TEXT_DECODES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) });
/// Reads [`CameraInfo`] from a TIFF-structured EXIF payload (an `Exif\0\0` prefix is skipped).
pub fn read(exif: &[u8]) -> CameraInfo {
let b = exif.strip_prefix(b"Exif\0\0").unwrap_or(exif);
let mut info = CameraInfo::default();
let le = match b.get(..4) {
Some([b'I', b'I', 42, 0]) => true,
Some([b'M', b'M', 0, 42]) => false,
_ => return info,
};
let t = Tiff {
b,
order: if le { craft_tiff::ByteOrder::Little } else { craft_tiff::ByteOrder::Big },
text_left: std::cell::Cell::new(MAX_TEXT_BYTES),
};
let Some(ifd0) = t.u32(4) else { return info };
let mut queue = vec![ifd0 as usize];
let mut seen = Vec::new();
while let Some(off) = queue.pop() {
if seen.contains(&off) || seen.len() > 8 {
continue;
}
seen.push(off);
for (tag, typ, count, field) in t.ifd(off) {
match tag {
// Duplicate TIFF text tags can point at the same large payload. Keep the first
// recognized value and do not repeatedly decode/copy later duplicates.
0x010F if info.make.is_none() => info.make = t.text(typ, count, field),
0x0110 if info.model.is_none() => info.model = t.text(typ, count, field),
0x829A => info.exposure_time = t.number(typ, count, field),
0x829D => info.f_number = t.number(typ, count, field),
0x8827 => info.iso = t.number(typ, count, field),
0x920A => info.focal_length = t.number(typ, count, field),
0xA405 => info.focal_length_35mm = t.number(typ, count, field).filter(|v| *v > 0.0),
0xA434 if info.lens.is_none() => info.lens = t.text(typ, count, field),
0x9003 if info.date_taken.is_none() => info.date_taken = t.text(typ, count, field),
0x8769 => {
if let Some(p) = t.u32(field) {
queue.push(p as usize);
}
}
_ => {}
}
}
}
info
}
/// Build a classic TIFF EXIF block using the shared TIFF writer.
/// Raw date strings and numeric rounding match the camera-field view. Text is
/// bounded to the reader's 1 MiB aggregate budget; oversized inputs return an error.
/// Physical directory placement is not part of this API's contract.
pub fn try_build(info: &CameraInfo) -> craft_tiff::Result<Vec<u8>> {
use craft_tiff::{ByteOrder, IfdBuilder, TiffError, TiffWriter, Value};
let total =
[&info.make, &info.model, &info.lens, &info.date_taken].into_iter().flatten().try_fold(0usize, |n, s| n.checked_add(s.len())?.checked_add(1));
if total.is_none_or(|n| n > MAX_TEXT_BYTES) {
return Err(TiffError::Limit("camera EXIF text"));
}
let mut root = IfdBuilder::new();
let mut exif = IfdBuilder::new();
for (tag, value) in [(0x010f, &info.make), (0x0110, &info.model)] {
if let Some(value) = value {
root.set(tag, Value::Ascii(value.clone()));
}
}
for (tag, value) in [(0x9003, &info.date_taken), (0xa434, &info.lens)] {
if let Some(value) = value {
exif.set(tag, Value::Ascii(value.clone()));
}
}
for (tag, value) in [(0x829a, info.exposure_time), (0x829d, info.f_number), (0x920a, info.focal_length)] {
if let Some(value) = value {
exif.set(tag, Value::Rational(vec![((value * 10000.0).round() as u32, 10000)]));
}
}
for (tag, value) in [(0x8827, info.iso), (0xa405, info.focal_length_35mm)] {
if let Some(value) = value {
exif.set(tag, Value::Short(vec![value as u16]));
}
}
// Empty child IFDs are valid here; the reader yields absent fields.
root.set_child(0x8769, exif);
TiffWriter::new(ByteOrder::Little, false).write(&[root])
}
#[cfg(test)]
fn build(info: &CameraInfo) -> Vec<u8> {
try_build(info).unwrap_or_default()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn round_trips_and_survives_garbage() {
let info = CameraInfo {
make: Some("Generic".into()),
model: Some("Camera 1".into()),
lens: Some("24-70mm".into()),
exposure_time: Some(0.004),
f_number: Some(8.0),
iso: Some(200.0),
focal_length: Some(35.0),
focal_length_35mm: Some(52.0),
date_taken: Some("2024:02:17 12:40:19".into()),
};
let b = build(&info);
let r = read(&b);
assert_eq!(r, info);
assert!((r.exposure_factor().unwrap() - 0.004 * 2.0 / 64.0).abs() < 1e-9);
let mut prefixed = b"Exif\0\0".to_vec();
prefixed.extend_from_slice(&b);
assert_eq!(read(&prefixed), info);
assert_eq!(read(b"nonsense"), CameraInfo::default());
for cut in [5, 12, 30, b.len() - 3] {
let _ = read(&b[..cut]);
}
}
/// Hostile payloads: huge counts, offsets near `u32::MAX`, self-referencing IFDs and random
/// bytes read as `None` fields instead of panicking or overflowing (usize is 32 bits on wasm).
#[test]
fn blank_duplicate_text_tags_share_one_decode_budget() {
// Blank values never fill `make`, so every duplicate would decode the same 1 MiB again;
// the per-read budget stops after the first, so the later real value is not reached.
let blank = MAX_TEXT_BYTES;
let entry = |count: u32, off: u32| {
let mut e = Vec::new();
e.extend_from_slice(&0x010Fu16.to_le_bytes());
e.extend_from_slice(&2u16.to_le_bytes());
e.extend_from_slice(&count.to_le_bytes());
e.extend_from_slice(&off.to_le_bytes());
e
};
let mut b = b"II*\0".to_vec();
b.extend_from_slice(&8u32.to_le_bytes());
b.extend_from_slice(&3u16.to_le_bytes());
b.extend(entry(blank as u32, 50));
b.extend(entry(blank as u32, 50));
b.extend(entry(2, u32::from_le_bytes(*b"M\0\0\0")));
b.extend_from_slice(&0u32.to_le_bytes());
assert_eq!(b.len(), 50);
b.extend(std::iter::repeat_n(b' ', blank));
assert_eq!(read(&b).make, None);
}
#[test]
fn duplicate_text_tags_keep_the_first_value_without_copying_large_duplicates() {
let value = vec![b'X'; 2 * 1024 * 1024];
let mut b = b"II*\0".to_vec();
b.extend_from_slice(&8u32.to_le_bytes());
// IFD0: Make="M", a duplicate Make pointing at a 2 MiB payload, and the Exif IFD link.
b.extend_from_slice(&3u16.to_le_bytes());
b.extend_from_slice(&0x010Fu16.to_le_bytes());
b.extend_from_slice(&2u16.to_le_bytes());
b.extend_from_slice(&2u32.to_le_bytes());
b.extend_from_slice(b"M\0\0\0");
b.extend_from_slice(&0x010Fu16.to_le_bytes());
b.extend_from_slice(&2u16.to_le_bytes());
b.extend_from_slice(&(value.len() as u32).to_le_bytes());
b.extend_from_slice(&80u32.to_le_bytes());
b.extend_from_slice(&0x8769u16.to_le_bytes());
b.extend_from_slice(&4u16.to_le_bytes());
b.extend_from_slice(&1u32.to_le_bytes());
b.extend_from_slice(&50u32.to_le_bytes());
b.extend_from_slice(&0u32.to_le_bytes());
// Exif IFD at 50: DateTimeOriginal="D" and the same large duplicate payload at offset 80.
b.extend_from_slice(&2u16.to_le_bytes());
b.extend_from_slice(&0x9003u16.to_le_bytes());
b.extend_from_slice(&2u16.to_le_bytes());
b.extend_from_slice(&2u32.to_le_bytes());
b.extend_from_slice(b"D\0\0\0");
b.extend_from_slice(&0x9003u16.to_le_bytes());
b.extend_from_slice(&2u16.to_le_bytes());
b.extend_from_slice(&(value.len() as u32).to_le_bytes());
b.extend_from_slice(&80u32.to_le_bytes());
b.extend_from_slice(&0u32.to_le_bytes());
b.extend_from_slice(&value);
TEXT_DECODES.with(|c| c.set(0));
let info = read(&b);
assert_eq!(info.make.as_deref(), Some("M"));
assert_eq!(info.date_taken.as_deref(), Some("D"));
// One decode per tag: duplicates must be skipped before `text` copies their payload.
assert_eq!(TEXT_DECODES.with(|c| c.get()), 2);
}
#[test]
fn hostile_payloads_never_panic() {
let entry = |tag: u16, typ: u16, count: u32, value: u32| {
let mut e = tag.to_le_bytes().to_vec();
e.extend_from_slice(&typ.to_le_bytes());
e.extend_from_slice(&count.to_le_bytes());
e.extend_from_slice(&value.to_le_bytes());
e
};
let mut b = b"II*\0".to_vec();
b.extend_from_slice(&8u32.to_le_bytes());
let entries = [
entry(0x010F, 2, u32::MAX, 8), // Make: count far past the end
entry(0x0110, 2, 16, u32::MAX - 1), // Model: offset at the top of the range
entry(0x829A, 5, u32::MAX, 20), // ExposureTime: count overflows the size
entry(0x829D, 5, 1, u32::MAX - 3), // FNumber: rational straddles u32::MAX
entry(0x9003, 2, 0x4000_0000, 8), // DateTimeOriginal: size overflow on 32 bits
entry(0x8769, 4, 1, 8), // Exif IFD pointing back at IFD0
entry(0x8769, 4, 1, u32::MAX), // ... and past the end
];
b.extend_from_slice(&(entries.len() as u16 + 3).to_le_bytes()); // claims more entries than exist
for e in entries {
b.extend_from_slice(&e);
}
assert_eq!(read(&b), CameraInfo::default());
let mut be = b"MM\0*".to_vec();
be.extend_from_slice(&u32::MAX.to_be_bytes());
assert_eq!(read(&be), CameraInfo::default());
// Deterministic noise behind a valid header, and every truncation of a real payload.
let mut x = 0x2545_F491u32;
for _ in 0..200 {
let mut n = b"II*\0\x08\0\0\0".to_vec();
for _ in 0..96 {
x ^= x << 13;
x ^= x >> 17;
x ^= x << 5;
n.push(x as u8);
}
let _ = read(&n);
}
let good = build(&CameraInfo {
make: Some("Make".into()),
date_taken: Some("2024:02:17 12:40:19".into()),
exposure_time: Some(0.004),
..Default::default()
});
for cut in 0..good.len() {
let _ = read(&good[..cut]);
}
}
}
// Keep the previous byte reader only as a test oracle during the shared-span cutover.
#[cfg(test)]
#[path = "camera_fields_legacy_tests.rs"]
mod legacy;
#[cfg(test)]
mod shared_span_parity {
use super::*;
fn compare(bytes: &[u8]) {
assert_eq!(format!("{:?}", read(bytes)), format!("{:?}", legacy::read(bytes)));
}
#[test]
fn shared_writer_matches_legacy_fields_and_rejects_oversized_text() {
for value in [0.0, -1.0, 0.004, 2.8, 65535.0, f64::INFINITY, f64::NAN] {
let camera = CameraInfo {
exposure_time: Some(value),
f_number: Some(value),
iso: Some(value),
focal_length: Some(value),
focal_length_35mm: Some(value),
date_taken: Some("raw date".into()),
make: Some("M".into()),
model: Some("Model".into()),
lens: Some("Lens".into()),
};
let old = legacy::CameraInfo {
exposure_time: camera.exposure_time,
f_number: camera.f_number,
iso: camera.iso,
focal_length: camera.focal_length,
focal_length_35mm: camera.focal_length_35mm,
date_taken: camera.date_taken.clone(),
make: camera.make.clone(),
model: camera.model.clone(),
lens: camera.lens.clone(),
};
let bytes = try_build(&camera).unwrap();
assert_eq!(format!("{:?}", read(&bytes)), format!("{:?}", legacy::read(&legacy::build(&old))));
}
assert_eq!(read(&try_build(&CameraInfo::default()).unwrap()), CameraInfo::default());
assert!(try_build(&CameraInfo { make: Some("x".repeat(MAX_TEXT_BYTES)), ..Default::default() }).is_err());
assert!(try_build(&CameraInfo { make: Some("x".repeat(MAX_TEXT_BYTES - 1)), ..Default::default() }).is_ok());
}
#[test]
fn preserves_camera_selection_for_valid_truncated_and_mutated_payloads() {
let bytes = build(&CameraInfo {
make: Some("Maker".into()),
model: Some("Camera".into()),
lens: Some("Lens".into()),
exposure_time: Some(0.125),
f_number: Some(2.8),
iso: Some(200.0),
focal_length: Some(50.0),
focal_length_35mm: Some(75.0),
date_taken: Some("not normalized: original date".into()),
});
compare(&bytes);
let mut prefixed = b"Exif\0\0".to_vec();
prefixed.extend_from_slice(&bytes);
compare(&prefixed);
for end in 0..=bytes.len() {
compare(&bytes[..end]);
}
// Exercise offsets, tags, types, counts and payloads independently, not random
// external data. The complete shared span must remain bounded for every edit.
for index in 0..bytes.len() {
for value in [0, 0xff, 0x80] {
let mut changed = bytes.clone();
changed[index] = value;
compare(&changed);
}
}
}
#[test]
fn preserves_partial_entry_and_zero_count_semantics_in_both_orders() {
for little in [true, false] {
let u16b = |v: u16| if little { v.to_le_bytes() } else { v.to_be_bytes() };
let u32b = |v: u32| if little { v.to_le_bytes() } else { v.to_be_bytes() };
for count in [0u32, 1, 2, u32::MAX] {
let mut bytes = if little { b"II".to_vec() } else { b"MM".to_vec() };
bytes.extend(u16b(42));
bytes.extend(u32b(8));
bytes.extend(u16b(1));
bytes.extend(u16b(0x8827));
bytes.extend(u16b(3));
bytes.extend(u32b(count));
bytes.extend(u16b(200));
compare(&bytes); // two inline bytes, no full 12-byte entry/next pointer
bytes.extend(u16b(0));
compare(&bytes);
}
}
}
}
@@ -0,0 +1,237 @@
// Frozen differential oracle: PhotoCraft main abb30dff, exif.rs. Test-only, not a production fallback.
#![allow(dead_code)]
// Minimal EXIF reader for the camera settings the photography commands use (exposure, aperture,
// ISO, focal length, camera and lens names). Input is the raw TIFF-structured EXIF payload
// (`II*\0` / `MM\0*`, as stored in `Document.metadata.exif`); malformed data yields `None`
// fields, never a panic. Tag numbers are from the EXIF 2.32 specification (CIPA DC-008).
/// Camera settings read from EXIF.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct CameraInfo {
pub make: Option<String>,
pub model: Option<String>,
pub lens: Option<String>,
/// Seconds.
pub exposure_time: Option<f64>,
pub f_number: Option<f64>,
pub iso: Option<f64>,
/// Millimetres.
pub focal_length: Option<f64>,
/// 35 mm-equivalent focal length in millimetres.
pub focal_length_35mm: Option<f64>,
/// DateTimeOriginal as stored (`YYYY:MM:DD HH:MM:SS`).
pub date_taken: Option<String>,
}
impl CameraInfo {
/// Linear exposure factor `t · ISO / N²` (relative brightness of the image for one scene).
pub fn exposure_factor(&self) -> Option<f64> {
let t = self.exposure_time?;
let n = self.f_number.unwrap_or(1.0).max(0.1);
Some(t * self.iso.unwrap_or(100.0) / 100.0 / (n * n))
}
}
/// Text bytes decoded per EXIF read (real Make/Model/Lens/Date strings are a few dozen bytes).
const MAX_TEXT_BYTES: usize = 1 << 20;
struct Tiff<'a> {
b: &'a [u8],
le: bool,
/// Text bytes this read may still decode: duplicate tags can share one large blank value.
text_left: std::cell::Cell<usize>,
}
impl Tiff<'_> {
fn u16(&self, o: usize) -> Option<u16> {
let s = self.b.get(o..o.checked_add(2)?)?;
Some(if self.le { u16::from_le_bytes([s[0], s[1]]) } else { u16::from_be_bytes([s[0], s[1]]) })
}
fn u32(&self, o: usize) -> Option<u32> {
let s = self.b.get(o..o.checked_add(4)?)?;
let a = [s[0], s[1], s[2], s[3]];
Some(if self.le { u32::from_le_bytes(a) } else { u32::from_be_bytes(a) })
}
/// Entries of the IFD at `off`: (tag, type, count, value offset field position).
fn ifd(&self, off: usize) -> Vec<(u16, u16, u32, usize)> {
let Some(n) = self.u16(off) else { return Vec::new() };
(0..n as usize)
.filter_map(|k| {
// Checked: offsets come from the file, and usize is 32 bits on wasm.
let e = off.checked_add(2)?.checked_add(k * 12)?;
Some((self.u16(e)?, self.u16(e.checked_add(2)?)?, self.u32(e.checked_add(4)?)?, e.checked_add(8)?))
})
.collect()
}
fn data_at(&self, typ: u16, count: u32, field: usize) -> Option<usize> {
let size = match typ {
1 | 2 | 6 | 7 => 1usize,
3 | 8 => 2,
4 | 9 | 11 => 4,
5 | 10 | 12 => 8,
_ => return None,
}
.checked_mul(usize::try_from(count).ok()?)?;
let at = if size <= 4 { field } else { usize::try_from(self.u32(field)?).ok()? };
// The whole value must lie inside the payload, not just its first element.
self.b.get(at..at.checked_add(size)?)?;
Some(at)
}
fn number(&self, typ: u16, count: u32, field: usize) -> Option<f64> {
let at = self.data_at(typ, count, field)?;
match typ {
3 => self.u16(at).map(f64::from),
4 => self.u32(at).map(f64::from),
5 => {
let (n, d) = (self.u32(at)?, self.u32(at.checked_add(4)?)?);
(d != 0).then(|| n as f64 / d as f64)
}
10 => {
let (n, d) = (self.u32(at)? as i32, self.u32(at.checked_add(4)?)? as i32);
(d != 0).then(|| n as f64 / d as f64)
}
_ => None,
}
}
fn text(&self, typ: u16, count: u32, field: usize) -> Option<String> {
#[cfg(test)]
TEXT_DECODES.with(|c| c.set(c.get() + 1));
if typ != 2 {
return None;
}
let at = self.data_at(typ, count, field)?;
let n = usize::try_from(count).ok()?;
self.text_left.set(self.text_left.get().checked_sub(n)?);
let s = self.b.get(at..at.checked_add(n)?)?;
let s = String::from_utf8_lossy(s).trim_end_matches('\0').trim().to_string();
(!s.is_empty()).then_some(s)
}
}
#[cfg(test)]
thread_local!(static TEXT_DECODES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) });
/// Reads [`CameraInfo`] from a TIFF-structured EXIF payload (an `Exif\0\0` prefix is skipped).
pub fn read(exif: &[u8]) -> CameraInfo {
let b = exif.strip_prefix(b"Exif\0\0").unwrap_or(exif);
let mut info = CameraInfo::default();
let le = match b.get(..4) {
Some([b'I', b'I', 42, 0]) => true,
Some([b'M', b'M', 0, 42]) => false,
_ => return info,
};
let t = Tiff { b, le, text_left: std::cell::Cell::new(MAX_TEXT_BYTES) };
let Some(ifd0) = t.u32(4) else { return info };
let mut queue = vec![ifd0 as usize];
let mut seen = Vec::new();
while let Some(off) = queue.pop() {
if seen.contains(&off) || seen.len() > 8 {
continue;
}
seen.push(off);
for (tag, typ, count, field) in t.ifd(off) {
match tag {
// Duplicate TIFF text tags can point at the same large payload. Keep the first
// recognized value and do not repeatedly decode/copy later duplicates.
0x010F if info.make.is_none() => info.make = t.text(typ, count, field),
0x0110 if info.model.is_none() => info.model = t.text(typ, count, field),
0x829A => info.exposure_time = t.number(typ, count, field),
0x829D => info.f_number = t.number(typ, count, field),
0x8827 => info.iso = t.number(typ, count, field),
0x920A => info.focal_length = t.number(typ, count, field),
0xA405 => info.focal_length_35mm = t.number(typ, count, field).filter(|v| *v > 0.0),
0xA434 if info.lens.is_none() => info.lens = t.text(typ, count, field),
0x9003 if info.date_taken.is_none() => info.date_taken = t.text(typ, count, field),
0x8769 => {
if let Some(p) = t.u32(field) {
queue.push(p as usize);
}
}
_ => {}
}
}
}
info
}
/// Builds a little-endian EXIF payload (used by tests and by synthetic fixtures).
pub fn build(info: &CameraInfo) -> Vec<u8> {
// IFD0: Make, Model, ExifIFD pointer; Exif IFD: the rest. Data area after the IFDs.
let mut ifd0: Vec<(u16, u16, u32, Vec<u8>)> = Vec::new();
let mut exif: Vec<(u16, u16, u32, Vec<u8>)> = Vec::new();
let text = |s: &str| {
let mut v = s.as_bytes().to_vec();
v.push(0);
v
};
let rational = |v: f64| {
let d = 10000u32;
let mut b = ((v * d as f64).round() as u32).to_le_bytes().to_vec();
b.extend_from_slice(&d.to_le_bytes());
b
};
if let Some(s) = &info.make {
ifd0.push((0x010F, 2, s.len() as u32 + 1, text(s)));
}
if let Some(s) = &info.model {
ifd0.push((0x0110, 2, s.len() as u32 + 1, text(s)));
}
if let Some(v) = info.exposure_time {
exif.push((0x829A, 5, 1, rational(v)));
}
if let Some(v) = info.f_number {
exif.push((0x829D, 5, 1, rational(v)));
}
if let Some(v) = info.iso {
exif.push((0x8827, 3, 1, (v as u16).to_le_bytes().to_vec()));
}
if let Some(s) = &info.date_taken {
exif.push((0x9003, 2, s.len() as u32 + 1, text(s)));
}
if let Some(v) = info.focal_length {
exif.push((0x920A, 5, 1, rational(v)));
}
if let Some(v) = info.focal_length_35mm {
exif.push((0xA405, 3, 1, (v as u16).to_le_bytes().to_vec()));
}
if let Some(s) = &info.lens {
exif.push((0xA434, 2, s.len() as u32 + 1, text(s)));
}
let ifd_len = |n: usize| 2 + 12 * n + 4;
let ifd0_off = 8usize;
let n0 = ifd0.len() + 1;
let exif_off = ifd0_off + ifd_len(n0);
let mut data_off = exif_off + ifd_len(exif.len());
let mut out = b"II*\0".to_vec();
out.extend_from_slice(&(ifd0_off as u32).to_le_bytes());
let mut data = Vec::new();
let mut write_ifd = |out: &mut Vec<u8>, entries: &[(u16, u16, u32, Vec<u8>)], extra: Option<u32>| {
let n = entries.len() + usize::from(extra.is_some());
out.extend_from_slice(&(n as u16).to_le_bytes());
for (tag, typ, count, bytes) in entries {
out.extend_from_slice(&tag.to_le_bytes());
out.extend_from_slice(&typ.to_le_bytes());
out.extend_from_slice(&count.to_le_bytes());
if bytes.len() <= 4 {
let mut f = bytes.clone();
f.resize(4, 0);
out.extend_from_slice(&f);
} else {
out.extend_from_slice(&(data_off as u32).to_le_bytes());
data.extend_from_slice(bytes);
data_off += bytes.len();
}
}
if let Some(p) = extra {
out.extend_from_slice(&0x8769u16.to_le_bytes());
out.extend_from_slice(&4u16.to_le_bytes());
out.extend_from_slice(&1u32.to_le_bytes());
out.extend_from_slice(&p.to_le_bytes());
}
out.extend_from_slice(&0u32.to_le_bytes());
};
write_ifd(&mut out, &ifd0, Some(exif_off as u32));
write_ifd(&mut out, &exif, None);
out.extend_from_slice(&data);
out
}
+1
View File
@@ -19,6 +19,7 @@
//! HEIF, PSD and MRW files are read by their own crates. Put the blocks they return into an
//! [`Embedded`] and call [`from_embedded`].
pub mod camera_fields;
mod container;
pub mod cr3;
mod datetime;
+19 -6
View File
@@ -8,8 +8,9 @@
//! counts it; an unpadded one refuses `=`), a length that can be, and the unused bits of the last
//! symbol zero (so every value has one spelling). A caller that reads mail, where line breaks and
//! missing padding are everyday, cleans its input first, as it always has; the strictness is what
//! the signature, key and credential checks want. No input panics, and the output is never longer
//! than three quarters of the input.
//! the signature, key and credential checks want. [`Config::decode_optional_padding`] explicitly
//! permits missing terminal padding without relaxing alphabet, padding placement or unused bits.
//! No input panics, and the output is never longer than three quarters of the input.
use std::fmt;
@@ -108,9 +109,20 @@ impl Config {
/// The bytes of `text`, which must be exactly base64 of this config's kind (see the module).
pub fn decode(self, text: impl AsRef<[u8]>) -> Result<Vec<u8>, DecodeError> {
let text = text.as_ref();
let (symbols, pad) = if self.padded {
if text.len() % 4 != 0 {
self.decode_inner(text.as_ref(), false)
}
/// Decode this alphabet with zero, partial or complete terminal padding, regardless of the
/// config's encoding padding. Whitespace, junk, internal/excess padding and nonzero unused
/// bits still fail. Use this only when the calling format permits missing padding; [`Self::decode`]
/// remains strict for signatures and credentials that require one spelling.
pub fn decode_optional_padding(self, text: impl AsRef<[u8]>) -> Result<Vec<u8>, DecodeError> {
self.decode_inner(text.as_ref(), true)
}
fn decode_inner(self, text: &[u8], optional_padding: bool) -> Result<Vec<u8>, DecodeError> {
let (symbols, pad) = if self.padded || optional_padding {
if !optional_padding && !text.len().is_multiple_of(4) {
return Err(DecodeError);
}
let pad = text.iter().rev().take(2).take_while(|c| **c == b'=').count();
@@ -120,7 +132,8 @@ impl Config {
};
// A last group of one symbol holds under eight bits; with padding, `=` fills it to four.
let rest = symbols.len() % 4;
if rest == 1 || (self.padded && pad != (4 - rest) % 4) {
let needed = (4 - rest) % 4;
if rest == 1 || (optional_padding && pad > needed) || (!optional_padding && self.padded && pad != needed) {
return Err(DecodeError);
}
let mut out = Vec::with_capacity(symbols.len().saturating_mul(3) / 4);
+93
View File
@@ -0,0 +1,93 @@
//! Compatibility decoding for legacy transports that accepted mixed Base64 alphabets and padding.
//!
//! This is deliberately permissive and must not be used for signatures, credentials or other
//! contexts requiring canonical Base64. Use [`crate::base64`] for strict RFC 4648 decoding.
use crate::base64::DecodeError;
/// Decode standard or URL-safe Base64, accepting either alphabet even in the same input.
/// Spaces, CR, LF and `=` are ignored wherever they occur; an incomplete final sextet is
/// discarded. Other bytes are errors. Output allocation is bounded by the input length.
pub fn decode(input: impl AsRef<[u8]>) -> Result<Vec<u8>, DecodeError> {
let input = input.as_ref();
let mut out = Vec::new();
let capacity = (input.len() / 4) * 3 + (input.len() % 4) * 3 / 4;
out.try_reserve(capacity).map_err(|_| DecodeError)?;
let (mut acc, mut bits) = (0u32, 0u32);
for c in input {
let v = match c {
b'A'..=b'Z' => c - b'A',
b'a'..=b'z' => c - b'a' + 26,
b'0'..=b'9' => c - b'0' + 52,
b'+' | b'-' => 62,
b'/' | b'_' => 63,
b'=' | b'\n' | b'\r' | b' ' => continue,
_ => return Err(DecodeError),
};
acc = (acc << 6) | u32::from(v);
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((acc >> bits) as u8);
acc &= (1 << bits) - 1;
}
}
Ok(out)
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
#[test]
fn accepts_mixed_alphabets_and_ignores_padding_anywhere() {
assert_eq!(decode("+_8=").unwrap(), [251, 255]);
assert_eq!(decode("Z=m 9\nv\r").unwrap(), b"foo");
assert_eq!(decode("A").unwrap(), b"");
assert_eq!(decode("AB").unwrap(), [0]);
assert!(decode("Zm9v\t").is_err());
assert!(decode("Zm9v!").is_err());
assert!(crate::base64::STANDARD.decode("Z=m9v").is_err());
}
// Differential against CADCraft's pre-cutover decoder, including malformed legacy inputs.
fn legacy(s: &str) -> Option<Vec<u8>> {
let mut out = Vec::new();
let (mut acc, mut bits) = (0u32, 0u32);
for c in s.bytes() {
let value = match c {
b'A'..=b'Z' => c - b'A',
b'a'..=b'z' => c - b'a' + 26,
b'0'..=b'9' => c - b'0' + 52,
b'+' | b'-' => 62,
b'/' | b'_' => 63,
b'=' | b'\n' | b'\r' | b' ' => continue,
_ => return None,
};
acc = (acc << 6) | u32::from(value);
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((acc >> bits) as u8);
}
}
Some(out)
}
#[test]
fn matches_the_legacy_decoder_on_seeded_mixed_inputs() {
let alphabet = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/-_= \r\n!\t";
let mut seed = 0x1234_5678u32;
for n in 0..50_000 {
let mut text = String::new();
for _ in 0..n % 45 {
seed = seed.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
text.push(char::from(alphabet[(seed as usize) % alphabet.len()]));
}
assert_eq!(decode(&text).ok(), legacy(&text), "{text:?}");
}
}
#[test]
fn round_trip_rfc_vectors_with_the_shared_encoder() {
for data in [&b""[..], b"f", b"fo", b"foo", b"foobar", &[0, 255, 127]] {
assert_eq!(decode(crate::base64::STANDARD.encode(data)).unwrap(), data);
}
}
}
+42
View File
@@ -79,3 +79,45 @@ proptest! {
}
}
}
/// Missing padding is opt-in; other canonical validation stays unchanged.
#[test]
fn optional_padding_keeps_alphabet_placement_and_tail_bit_checks() {
for cfg in CONFIGS {
for (input, expected) in [("", ""), ("Zg", "f"), ("Zg=", "f"), ("Zg==", "f"), ("Zm8", "fo"), ("Zm8=", "fo"), ("Zm9v", "foo")] {
assert_eq!(cfg.decode_optional_padding(input).unwrap(), expected.as_bytes());
}
for bad in ["=", "====", "Z", "Z===", "Zg===", "Zm8==", "Zm9v=", "QQ==QUJD", "Zm=v", "Zh", "Zh=", "Zh==", "Zm9", "Zm9=", "Zg\n", " Zg", "é"]
{
assert!(cfg.decode_optional_padding(bad).is_err(), "{cfg:?}: {bad:?}");
}
}
assert_eq!(STANDARD.decode_optional_padding("+/8").unwrap(), [251, 255]);
assert_eq!(URL_SAFE.decode_optional_padding("-_8=").unwrap(), [251, 255]);
assert!(STANDARD.decode_optional_padding("-_8=").is_err());
assert!(URL_SAFE.decode_optional_padding("+/8=").is_err());
assert!(STANDARD.decode("Zg=").is_err());
assert!(STANDARD_NO_PAD.decode("Zg==").is_err());
}
proptest! {
#[test]
fn optional_padding_accepts_only_a_suffix_of_required_padding(
data in proptest::collection::vec(any::<u8>(), 0..400),
junk in proptest::collection::vec(any::<u8>(), 0..128),
) {
for cfg in [STANDARD, URL_SAFE] {
let encoded = cfg.encode(&data);
let bare = encoded.trim_end_matches('=');
for length in bare.len()..=encoded.len() {
prop_assert_eq!(cfg.decode_optional_padding(&encoded[..length]).ok(), Some(data.clone()));
}
if let Ok(decoded) = cfg.decode_optional_padding(&junk) {
let canonical = cfg.encode(decoded);
let bare = canonical.trim_end_matches('=');
prop_assert!(junk.len() >= bare.len() && junk.len() <= canonical.len());
prop_assert_eq!(canonical.as_bytes().get(..junk.len()), Some(junk.as_slice()));
}
}
}
}
+1
View File
@@ -28,6 +28,7 @@
//! says) is the caller's: this crate has no notion of a mailbox or a document.
pub mod base64;
pub mod base64_compat;
pub mod charset;
#[cfg(feature = "detect")]
pub mod detect;
+3
View File
@@ -16,3 +16,6 @@ serde = { workspace = true }
# the nesting against `Limits::max_depth` before parsing.
serde_json = { workspace = true, features = ["unbounded_depth"] }
thiserror = { workspace = true }
# Same pure-Rust backend as the PhotoCraft source codec. MIT OR Apache-2.0.
flate2 = { version = "1.1.10", default-features = false, features = ["zlib-rs", "runtime_detection"] }
+13 -1
View File
@@ -5,7 +5,7 @@ references, the entry paths, the limits for reading a manifest, and the runner f
migrations. The document model stays in PhotoCraft and is a type parameter here. The crate
does not read ZIP archives, open files or decode tiles. No `unsafe`, no panics on malformed
input, and it builds for `wasm32-unknown-unknown`. The dependencies are `serde`, `serde_json`
and `thiserror`.
`thiserror`, and `flate2`.
```toml
craft-pcraft-format = { git = "https://github.com/storytold/craft-libs", rev = "<commit>" }
@@ -120,3 +120,15 @@ limits.max_manifest_bytes = 16 << 20;
`.github/workflows/pcraft-format.yml` runs fmt, clippy and the tests on Linux and Windows, and
a `wasm32-unknown-unknown` check.
## Brush-tip envelope
`tip::encode`, `tip::decode` and `tip::decode_with_max_side` share PhotoCraft's PCTIP1
brush-tip codec: a six-byte magic, one-byte depth, little-endian width/height and zlib
samples. Eight-bit-compatible samples use 8 bits, otherwise 16-bit little-endian.
Dimensions, sample count, exact inflated length and caller preview side limits are checked.
Preset group schemas, tip hashes and storage policy remain application-owned.
Ported from `storytold/photocraft` commit `19aec5eb44131de44361189d64910e7b3e19e57c`,
`crates/engine/src/preset_store.rs`. Original codec by Brandon Thomas (PhotoCraft #82),
with later bounds/backend/storage changes by David Mann and FinnNk, under MIT OR Apache-2.0.
+3
View File
@@ -36,6 +36,9 @@ mod limits;
mod migrate;
mod read;
/// Lossless brush-tip envelope used by PhotoCraft preset libraries.
pub mod tip;
use serde::{Deserialize, Serialize};
pub use limits::{
+102
View File
@@ -0,0 +1,102 @@
//! PhotoCraft's PCTIP1 brush-tip envelope and lossless grayscale sample serialization.
//!
//! Extracted from PhotoCraft preset_store.rs at 19aec5eb44131de44361189d64910e7b3e19e57c.
//! Original implementation: Brandon Thomas; subsequent codec changes: David Mann and FinnNk.
//! Group schemas, file naming, content hashes and storage policy remain with the application.
/// Largest accepted tip side.
pub const MAX_SIDE: u32 = 16384;
/// Largest accepted sample count.
pub const MAX_SAMPLES: u64 = 1 << 26;
const TIP_MAGIC: &[u8; 6] = b"PCTIP1";
const TIP_HEADER: usize = 6 + 1 + 4 + 4;
/// Decoded grayscale samples. Eight-bit samples expand losslessly by multiplication by 257.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Tip {
pub width: u32,
pub height: u32,
pub data: Vec<u16>,
}
/// `PCTIP1`, bits (8|16), width, height (u32 LE), then the zlib-deflated samples.
/// Returns an empty vector for invalid dimensions/sample counts or compression failure.
pub fn encode(width: u32, height: u32, data: &[u16]) -> Vec<u8> {
use std::io::Write;
let count = u64::from(width) * u64::from(height);
if width == 0 || height == 0 || width > MAX_SIDE || height > MAX_SIDE || count > MAX_SAMPLES || count != data.len() as u64 {
return Vec::new();
}
let eight = data.iter().all(|v| v % 257 == 0);
let mut out = Vec::with_capacity(TIP_HEADER + data.len() / 4);
out.extend_from_slice(TIP_MAGIC);
out.push(if eight { 8 } else { 16 });
out.extend_from_slice(&width.to_le_bytes());
out.extend_from_slice(&height.to_le_bytes());
// Level 3: zlib-rs level 1 writes static Huffman blocks only, 13-30% bigger than miniz's level 1.
let mut z = flate2::write::ZlibEncoder::new(out, flate2::Compression::new(3));
let mut buf = Vec::with_capacity(8192);
let mut ok = true;
for chunk in data.chunks(4096) {
buf.clear();
if eight {
buf.extend(chunk.iter().map(|v| (v / 257) as u8));
} else {
for v in chunk {
buf.extend_from_slice(&v.to_le_bytes());
}
}
ok &= z.write_all(&buf).is_ok();
}
match z.finish() {
Ok(v) if ok => v,
_ => Vec::new(),
}
}
/// Inverse of [`encode`]; any malformed, truncated or oversized input is an error.
pub fn decode(bytes: &[u8]) -> Result<Tip, String> {
decode_with_max_side(bytes, MAX_SIDE)
}
/// [`decode`] refusing (before inflating anything) a bitmap with a side over `max_side`.
pub fn decode_with_max_side(bytes: &[u8], max_side: u32) -> Result<Tip, String> {
let head = bytes.get(..TIP_HEADER).ok_or("truncated tip header")?;
if &head[..6] != TIP_MAGIC {
return Err("not a PhotoCraft tip".into());
}
let bits = head[6];
let u32_at = |i: usize| u32::from_le_bytes([head[i], head[i + 1], head[i + 2], head[i + 3]]);
let (w, h) = (u32_at(7), u32_at(11));
if w == 0 || h == 0 || w > MAX_SIDE.min(max_side) || h > MAX_SIDE.min(max_side) {
return Err(format!("bad tip size {w}×{h}"));
}
let n = u64::from(w) * u64::from(h);
if n > MAX_SAMPLES {
return Err(format!("tip too large ({w}×{h})"));
}
let bytes_per = match bits {
8 => 1u64,
16 => 2,
b => return Err(format!("unsupported tip depth {b}")),
};
let want = n * bytes_per;
// One byte beyond the declared size detects overlong output, without allocating for
// an attacker-controlled expansion. Require the zlib trailer, not merely enough samples.
let mut raw = Vec::with_capacity(want as usize + 1);
let status = flate2::Decompress::new(true)
.decompress_vec(&bytes[TIP_HEADER..], &mut raw, flate2::FlushDecompress::Finish)
.map_err(|e| format!("tip data: {e}"))?;
if status != flate2::Status::StreamEnd {
return Err("tip data: truncated or oversized zlib stream".into());
}
if raw.len() as u64 != want {
return Err(format!("tip data has {} bytes, expected {want}", raw.len()));
}
let data: Vec<u16> = if bits == 8 {
raw.iter().map(|&v| u16::from(v) * 257).collect()
} else {
raw.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes(*c)).collect()
};
Ok(Tip { width: w, height: h, data })
}
+58
View File
@@ -0,0 +1,58 @@
use craft_pcraft_format::tip::{MAX_SAMPLES, MAX_SIDE, decode, decode_with_max_side, encode};
use std::io::Write;
fn fixture(bits: u8, width: u32, height: u32, samples: &[u8]) -> Vec<u8> {
let mut out = b"PCTIP1".to_vec();
out.push(bits);
out.extend(width.to_le_bytes());
out.extend(height.to_le_bytes());
let mut z = flate2::write::ZlibEncoder::new(out, flate2::Compression::new(3));
z.write_all(samples).unwrap();
z.finish().unwrap()
}
#[test]
fn legacy_eight_and_sixteen_bit_fixtures_and_roundtrips() {
for (bits, raw, samples) in [(8, vec![0, 128, 255], vec![0, 32896, 65535]), (16, vec![1, 0, 52, 18, 255, 255], vec![1, 0x1234, 65535])] {
let legacy = fixture(bits, 3, 1, &raw);
let tip = decode(&legacy).unwrap();
assert_eq!((tip.width, tip.height), (3, 1));
assert_eq!(tip.data, samples);
let encoded = encode(3, 1, &samples);
assert_eq!(&encoded[..15], &legacy[..15]);
assert_eq!(decode(&encoded).unwrap(), tip);
}
}
#[test]
fn checks_headers_limits_and_sample_lengths() {
let good = fixture(8, 1, 1, &[255]);
for n in 0..good.len() {
assert!(decode(&good[..n]).is_err(), "truncation at {n}");
}
let mut bad = good.clone();
bad[0] = b'X';
assert!(decode(&bad).is_err());
for (bits, w, h) in [(7, 1, 1), (8, 0, 1), (8, 1, 0), (8, MAX_SIDE + 1, 1), (8, MAX_SIDE, MAX_SIDE)] {
assert!(decode(&fixture(bits, w, h, &[])).is_err());
}
assert!(MAX_SAMPLES < u64::from(MAX_SIDE) * u64::from(MAX_SIDE));
for raw in [vec![], vec![0, 1], vec![0; 10000]] {
assert!(decode(&fixture(8, 1, 1, &raw)).is_err());
}
assert!(decode(&fixture(16, 1, 1, &[1])).is_err());
let mut checksum = good;
*checksum.last_mut().unwrap() ^= 1;
assert!(decode(&checksum).is_err());
assert!(encode(0, 1, &[]).is_empty());
assert!(encode(1, 1, &[]).is_empty());
assert!(encode(MAX_SIDE + 1, 1, &[0]).is_empty());
}
#[test]
fn preview_side_limit_is_checked_before_inflation() {
let good = encode(2, 1, &[0, 65535]);
assert!(decode_with_max_side(&good, 1).is_err());
assert!(decode_with_max_side(&good, 2).is_ok());
assert!(decode_with_max_side(&good, 0).is_err());
}
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "craft-plist"
description = "Bounded cross-platform binary Apple property-list reader"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
thiserror.workspace = true
+177
View File
@@ -0,0 +1,177 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 ArtCraft Team and the Craft Anything contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+11
View File
@@ -0,0 +1,11 @@
# craft-plist
A cross-platform bounded binary (`bplist00`) reader, extracted from Craft Anything's existing implementation and hardening history. Typed dictionaries retain order and duplicate keys; `get` returns the first match. Strings retain the source reader's lossy decoding policy. Shared references expand under node and decoded-byte budgets, and cycles are rejected.
`parse_binary_with_limits` accepts explicit input, object, expanded-node, nesting and decoded-byte limits. Recursion always has a hard ceiling of 256 even if a caller supplies a larger depth. Counts are checked before container reservation; allocations can return a resource error. Limits are per parse, not a promise of a precise process RSS cap.
This first PR contains reading only. XML parsing/writing and keyed-archive interpretation are not implemented. JSON projection, date formatting, OS file access and preference/locale selection are not part of this crate. Existing updater/Photo streaming `plist` users remain unchanged.
Initial consumers: PhotoCraft's AppleLanguages binary-reader path; later Craft Anything binary parsing and LightCraft XML presets (after XML support/parity). Photo must retain its 4 MiB input policy and first-language selection.
Source: `storytold/craft-anything` at `88d1d9cac852aec1c7fd97886db451e005e49d2a`, `crates/formats/src/plist.rs` and checked byte reader. Source license files retained. Imported changes retain Brandon Thomas, BFlat, RRFZ and Afloat as primary Git authors; imported regression tests are BFlat's. No external specification implementation copied.
+391
View File
@@ -0,0 +1,391 @@
use crate::{FormatError, Limits, bytes::Reader};
#[derive(Debug, Clone, PartialEq)]
pub enum Value {
Dict(Vec<(String, Value)>),
Array(Vec<Value>),
String(String),
Integer(i128),
Real(f64),
Bool(bool),
/// Seconds since 2001-01-01T00:00:00Z (binary), or the ISO text (XML).
Date(DateValue),
Data(Vec<u8>),
/// A keyed-archive object reference.
Uid(u64),
Null,
}
#[derive(Debug, Clone, PartialEq)]
pub enum DateValue {
Seconds(f64),
Text(String),
}
impl Value {
pub fn get(&self, key: &str) -> Option<&Value> {
match self {
Value::Dict(d) => d.iter().find(|(k, _)| k == key).map(|(_, v)| v),
_ => None,
}
}
pub fn as_str(&self) -> Option<&str> {
match self {
Value::String(s) => Some(s),
_ => None,
}
}
pub fn as_array(&self) -> Option<&[Value]> {
match self {
Value::Array(a) => Some(a),
_ => None,
}
}
pub fn as_uid(&self) -> Option<u64> {
match self {
Value::Uid(u) => Some(*u),
_ => None,
}
}
pub fn as_int(&self) -> Option<i128> {
match self {
Value::Integer(i) => Some(*i),
_ => None,
}
}
}
struct Bin<'a> {
r: Reader<'a>,
offsets: Vec<usize>,
ref_size: usize,
nodes: usize,
/// Data and text bytes still allowed to be copied out.
bytes_left: usize,
limits: Limits,
}
/// Parse a `bplist00` binary property list.
pub fn parse_binary(data: &[u8]) -> Result<Value, FormatError> {
parse_binary_with_limits(data, Limits::default())
}
/// Parse a binary property list, with caller-selected input, object, expansion and nesting limits.
pub fn parse_binary_with_limits(data: &[u8], limits: Limits) -> Result<Value, FormatError> {
let (mut b, top) = reader(data, limits)?;
let mut stack = reserved(limits.max_depth.min(256))?;
b.object(top, &mut stack)
}
fn reader(data: &[u8], limits: Limits) -> Result<(Bin<'_>, usize), FormatError> {
if data.len() > limits.max_input_bytes {
return Err(FormatError::TooLarge("input bytes".into()));
}
if !data.starts_with(b"bplist") {
return Err(FormatError::Malformed("not a binary plist".into()));
}
if !data.starts_with(b"bplist00") {
return Err(FormatError::Unsupported("unknown binary plist version".into()));
}
let len = data.len();
if len < 8 + 32 {
return Err(FormatError::Truncated("binary plist trailer".into()));
}
let r = Reader::new(data);
let t = len - 32;
let off_size = usize::from(r.u8(t + 6).unwrap_or(0));
let ref_size = usize::from(r.u8(t + 7).unwrap_or(0));
let num = r.u64_be(t + 8).unwrap_or(0);
let top = r.u64_be(t + 16).unwrap_or(0);
let table = r.u64_be(t + 24).unwrap_or(0);
if !(1..=8).contains(&off_size) || !(1..=8).contains(&ref_size) {
return Err(FormatError::Malformed("bad offset or reference size".into()));
}
let num = usize::try_from(num).map_err(|_| FormatError::Malformed("object count".into()))?;
let table = usize::try_from(table).map_err(|_| FormatError::Malformed("offset table".into()))?;
if num == 0 || num > len {
return Err(FormatError::Malformed(format!("{num} objects in a {len}-byte file")));
}
if num > limits.max_objects {
return Err(FormatError::TooLarge("object count".into()));
}
let need = num.checked_mul(off_size).and_then(|n| n.checked_add(table)).ok_or_else(|| FormatError::Malformed("offset table".into()))?;
if need > t || table < 8 {
return Err(FormatError::Truncated("offset table runs past the trailer".into()));
}
let mut offsets = reserved(num)?;
for i in 0..num {
let o = read_be(&r, table + i * off_size, off_size).ok_or_else(|| FormatError::Truncated("offset table".into()))?;
let o = usize::try_from(o).map_err(|_| FormatError::Malformed("object offset".into()))?;
if o < 8 || o >= table {
return Err(FormatError::Malformed(format!("object {i} lies outside the object area")));
}
offsets.push(o);
}
let top = usize::try_from(top).map_err(|_| FormatError::Malformed("top object".into()))?;
// Object payloads and references must not borrow bytes from the offset table or trailer.
let objects = data.get(..table).ok_or_else(|| FormatError::Truncated("object area".into()))?;
let b = Bin { r: Reader::new(objects), offsets, ref_size, nodes: 0, bytes_left: limits.max_expanded_bytes, limits };
Ok((b, top))
}
fn read_be(r: &Reader<'_>, off: usize, n: usize) -> Option<u64> {
let s = r.slice(off, n)?;
Some(s.iter().fold(0u64, |acc, &b| (acc << 8) | u64::from(b)))
}
/// UTF-8 size of `String::from_utf8_lossy(bytes)`: each damaged sequence becomes a U+FFFD.
fn lossy_utf8_len(bytes: &[u8]) -> usize {
bytes.utf8_chunks().fold(0usize, |n, c| {
let replacement = if c.invalid().is_empty() { 0 } else { char::REPLACEMENT_CHARACTER.len_utf8() };
n.saturating_add(c.valid().len()).saturating_add(replacement)
})
}
/// UTF-8 size of `String::from_utf16_lossy` over big-endian code units: a lone surrogate becomes
/// a U+FFFD.
fn lossy_utf16_len(bytes: &[u8]) -> usize {
let units = bytes.as_chunks::<2>().0.iter().map(|c| u16::from_be_bytes(*c));
char::decode_utf16(units).fold(0usize, |n, c| n.saturating_add(c.map_or(char::REPLACEMENT_CHARACTER.len_utf8(), char::len_utf8)))
}
impl Bin<'_> {
fn count(&self, at: usize, low: u8) -> Result<(usize, usize), FormatError> {
if low != 0xf {
return Ok((usize::from(low), at + 1));
}
let m = self.r.u8(at + 1).ok_or_else(|| FormatError::Truncated("length".into()))?;
if m & 0xf0 != 0x10 {
return Err(FormatError::Malformed("bad extended length marker".into()));
}
if m & 0x0f > 3 {
return Err(FormatError::Malformed("extended length width exceeds 64 bits".into()));
}
let n = 1usize << (m & 0x0f);
let v = read_be(&self.r, at + 2, n).ok_or_else(|| FormatError::Truncated("length".into()))?;
let v = usize::try_from(v).map_err(|_| FormatError::Malformed("length".into()))?;
Ok((v, at + 2 + n))
}
fn reference(&self, at: usize, i: usize) -> Result<usize, FormatError> {
let off = i.checked_mul(self.ref_size).and_then(|x| x.checked_add(at)).ok_or_else(|| FormatError::Malformed("reference".into()))?;
let v = read_be(&self.r, off, self.ref_size).ok_or_else(|| FormatError::Truncated("object reference".into()))?;
usize::try_from(v).map_err(|_| FormatError::Malformed("reference".into()))
}
/// Refuse a container whose `children` would pass the node limit, before space is reserved for them.
fn room_for_nodes(&self, children: usize) -> Result<(), FormatError> {
if children > self.limits.max_nodes.saturating_sub(self.nodes) {
return Err(FormatError::TooLarge("expanded node count".into()));
}
Ok(())
}
/// Spend `n` bytes of the data and text budget before copying them out.
fn spend(&mut self, n: usize) -> Result<(), FormatError> {
self.bytes_left =
self.bytes_left.checked_sub(n).ok_or_else(|| FormatError::TooLarge("repeated data and text expand past the plist byte budget".into()))?;
Ok(())
}
/// Read object `idx`. `stack` holds the containers on the current path, so a cycle is refused.
fn object(&mut self, idx: usize, stack: &mut Vec<usize>) -> Result<Value, FormatError> {
self.nodes += 1;
if self.nodes > self.limits.max_nodes {
return Err(FormatError::TooLarge("expanded node count".into()));
}
if stack.len() >= self.limits.max_depth.min(256) {
return Err(FormatError::Malformed("nesting too deep".into()));
}
if stack.contains(&idx) {
return Err(FormatError::Malformed(format!("object {idx} contains itself")));
}
let at = *self.offsets.get(idx).ok_or_else(|| FormatError::Malformed(format!("reference to missing object {idx}")))?;
let m = self.r.u8(at).ok_or_else(|| FormatError::Truncated("object marker".into()))?;
let (hi, lo) = (m >> 4, m & 0x0f);
let v = match hi {
0x0 => match lo {
0x0 => Value::Null,
0x8 => Value::Bool(false),
0x9 => Value::Bool(true),
_ => return Err(FormatError::Malformed(format!("unknown simple plist object {m:#04x}"))),
},
0x1 => {
if lo > 4 {
return Err(FormatError::Malformed("integer width exceeds 128 bits".into()));
}
let n = 1usize << lo;
let bytes = self.r.slice(at + 1, n).ok_or_else(|| FormatError::Truncated("integer".into()))?;
let v = match n {
8 => i128::from(i64::from_be_bytes(bytes.try_into().map_err(|_| FormatError::Truncated("integer".into()))?)),
16 => i128::from_be_bytes(bytes.try_into().map_err(|_| FormatError::Truncated("integer".into()))?),
_ => i128::from(bytes.iter().fold(0u64, |acc, &b| (acc << 8) | u64::from(b))),
};
Value::Integer(v)
}
0x2 => {
let v = match lo {
2 => self.r.u32_be(at + 1).map(|b| f64::from(f32::from_bits(b))),
3 => self.r.u64_be(at + 1).map(f64::from_bits),
_ => None,
};
Value::Real(v.ok_or_else(|| FormatError::Truncated("real".into()))?)
}
0x3 if lo == 3 => {
Value::Date(DateValue::Seconds(self.r.u64_be(at + 1).map(f64::from_bits).ok_or_else(|| FormatError::Truncated("date".into()))?))
}
0x4 => {
let (n, s) = self.count(at, lo)?;
let bytes = self.r.slice(s, n).ok_or_else(|| FormatError::Truncated("data".into()))?;
self.spend(bytes.len())?;
{
let mut out = reserved(bytes.len())?;
out.extend_from_slice(bytes);
Value::Data(out)
}
}
0x5 => {
let (n, s) = self.count(at, lo)?;
let bytes = self.r.slice(s, n).ok_or_else(|| FormatError::Truncated("string".into()))?;
let size = lossy_utf8_len(bytes);
self.spend(size)?;
let mut out = reserved_string(size)?;
for chunk in bytes.utf8_chunks() {
out.push_str(chunk.valid());
if !chunk.invalid().is_empty() {
out.push(char::REPLACEMENT_CHARACTER);
}
}
Value::String(out)
}
0x6 => {
let (n, s) = self.count(at, lo)?;
let bytes = self
.r
.slice(s, n.checked_mul(2).ok_or_else(|| FormatError::Malformed("string".into()))?)
.ok_or_else(|| FormatError::Truncated("string".into()))?;
let size = lossy_utf16_len(bytes);
self.spend(size)?;
let mut out = reserved_string(size)?;
let units = bytes.as_chunks::<2>().0.iter().map(|c| u16::from_be_bytes(*c));
for ch in char::decode_utf16(units) {
out.push(ch.unwrap_or(char::REPLACEMENT_CHARACTER));
}
Value::String(out)
}
0x8 => {
if lo > 7 {
return Err(FormatError::Malformed("uid width exceeds 64 bits".into()));
}
let n = usize::from(lo) + 1;
Value::Uid(read_be(&self.r, at + 1, n).ok_or_else(|| FormatError::Truncated("uid".into()))?)
}
0xa | 0xc => {
let (n, s) = self.count(at, lo)?;
// Writers store equal values once, so an array may name one object many times:
// only its references have to fit in the file. the node limit and the byte budget bound
// the expansion.
if s.saturating_add(n.saturating_mul(self.ref_size)) > self.r.len() {
return Err(FormatError::Malformed("array larger than the file".into()));
}
self.room_for_nodes(n)?;
stack.push(idx);
let mut out = reserved(n)?;
for i in 0..n {
let child = self.reference(s, i)?;
out.push(self.object(child, stack)?);
}
stack.pop();
Value::Array(out)
}
0xd => {
let (n, s) = self.count(at, lo)?;
if s.saturating_add(n.saturating_mul(self.ref_size).saturating_mul(2)) > self.r.len() {
return Err(FormatError::Malformed("dictionary larger than the file".into()));
}
self.room_for_nodes(n.saturating_mul(2))?;
stack.push(idx);
let mut out = reserved(n)?;
for i in 0..n {
let k = self.reference(s, i)?;
let v = self.reference(s, i + n)?;
let key = match self.object(k, stack)? {
Value::String(s) => s,
_ => return Err(FormatError::Unsupported("non-string dictionary keys cannot be represented in this plist view".into())),
};
out.push((key, self.object(v, stack)?));
}
stack.pop();
Value::Dict(out)
}
_ => return Err(FormatError::Malformed(format!("unknown object marker {m:#04x}"))),
};
Ok(v)
}
}
fn reserved<T>(n: usize) -> Result<Vec<T>, FormatError> {
let mut v = Vec::new();
v.try_reserve_exact(n).map_err(|_| FormatError::TooLarge("allocation".into()))?;
Ok(v)
}
fn reserved_string(n: usize) -> Result<String, FormatError> {
let mut s = String::new();
s.try_reserve_exact(n).map_err(|_| FormatError::TooLarge("string allocation".into()))?;
Ok(s)
}
/// Select the first string in one top-level dictionary array without expanding unrelated values.
/// First matching dictionary key wins. Missing/wrong-typed values return `None`; malformed
/// selected objects and resource exhaustion return errors. Unselected value graphs are not
/// validated. This permits preference readers to ignore unrelated future object kinds.
pub fn first_string_in_array(data: &[u8], key: &str, limits: Limits) -> Result<Option<String>, FormatError> {
let (mut b, top) = reader(data, limits)?;
let (kind, n, start) = b.header(top)?;
if kind != 0xd {
return Ok(None);
}
if n > limits.max_nodes {
return Err(FormatError::TooLarge("dictionary lookup entries".into()));
}
let bytes = n.checked_mul(2).and_then(|n| n.checked_mul(b.ref_size)).ok_or_else(|| FormatError::Malformed("dictionary references".into()))?;
b.r.slice(start, bytes).ok_or_else(|| FormatError::Truncated("dictionary references".into()))?;
for i in 0..n {
let k = b.reference(start, i)?;
if b.selected_string(k)?.as_deref() != Some(key) {
continue;
}
let value = b.reference(start, n + i)?;
let (kind, count, payload) = b.header(value)?;
if kind != 0xa || count == 0 {
return Ok(None);
}
let first = b.reference(payload, 0)?;
return b.selected_string(first);
}
Ok(None)
}
impl Bin<'_> {
fn header(&self, idx: usize) -> Result<(u8, usize, usize), FormatError> {
let at = *self.offsets.get(idx).ok_or_else(|| FormatError::Malformed("missing object".into()))?;
let marker = self.r.u8(at).ok_or_else(|| FormatError::Truncated("object marker".into()))?;
let kind = marker >> 4;
// Only containers and strings use an extended length. Unknown types are not traversed.
let (n, start) = if matches!(kind, 0x5 | 0x6 | 0xa | 0xd) { self.count(at, marker & 15)? } else { (usize::from(marker & 15), at + 1) };
Ok((kind, n, start))
}
fn selected_string(&mut self, idx: usize) -> Result<Option<String>, FormatError> {
let (kind, _, _) = self.header(idx)?;
if !matches!(kind, 0x5 | 0x6) {
return Ok(None);
}
match self.object(idx, &mut Vec::new())? {
Value::String(s) => Ok(Some(s)),
_ => Ok(None),
}
}
}
+37
View File
@@ -0,0 +1,37 @@
//! Checked little/big-endian reads over untrusted bytes. Every read returns `None` when out of range.
#[derive(Debug, Clone, Copy)]
pub struct Reader<'a> {
data: &'a [u8],
}
impl<'a> Reader<'a> {
pub fn new(data: &'a [u8]) -> Self {
Reader { data }
}
pub fn len(&self) -> usize {
self.data.len()
}
pub fn slice(&self, off: usize, len: usize) -> Option<&'a [u8]> {
let end = off.checked_add(len)?;
self.data.get(off..end)
}
pub fn u8(&self, off: usize) -> Option<u8> {
self.data.get(off).copied()
}
fn arr<const N: usize>(&self, off: usize) -> Option<[u8; N]> {
self.slice(off, N)?.try_into().ok()
}
pub fn u32_be(&self, off: usize) -> Option<u32> {
self.arr(off).map(u32::from_be_bytes)
}
pub fn u64_be(&self, off: usize) -> Option<u64> {
self.arr(off).map(u64::from_be_bytes)
}
}
+33
View File
@@ -0,0 +1,33 @@
//! Bounded binary Apple property lists, independent of operating-system preferences.
//! XML and writing are intentionally not implemented in this first extraction.
//! File discovery, locale selection, bundle validation and application policy stay in callers.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod binary;
mod bytes;
pub use binary::{DateValue, Value, first_string_in_array, parse_binary, parse_binary_with_limits};
/// Caller-selected resource limits. Zero values refuse the corresponding resource.
#[derive(Clone, Copy, Debug)]
pub struct Limits {
pub max_input_bytes: usize,
pub max_objects: usize,
pub max_nodes: usize,
pub max_depth: usize,
pub max_expanded_bytes: usize,
}
impl Default for Limits {
fn default() -> Self {
Self { max_input_bytes: 16 << 20, max_objects: 100_000, max_nodes: 100_000, max_depth: 64, max_expanded_bytes: 64 << 20 }
}
}
#[derive(Debug, thiserror::Error)]
pub enum FormatError {
#[error("malformed property list: {0}")]
Malformed(String),
#[error("truncated property list: {0}")]
Truncated(String),
#[error("unsupported property list: {0}")]
Unsupported(String),
#[error("property list resource limit: {0}")]
TooLarge(String),
}
+75
View File
@@ -0,0 +1,75 @@
use craft_plist::{Limits, Value, parse_binary, parse_binary_with_limits};
fn plist(objects: &[&[u8]]) -> Vec<u8> {
let mut b = b"bplist00".to_vec();
let mut offsets = Vec::new();
for obj in objects {
offsets.push(b.len() as u8);
b.extend_from_slice(obj);
}
let table = b.len() as u64;
b.extend_from_slice(&offsets);
b.extend_from_slice(&[0, 0, 0, 0, 0, 0, 1, 1]);
b.extend_from_slice(&(objects.len() as u64).to_be_bytes());
b.extend_from_slice(&0u64.to_be_bytes());
b.extend_from_slice(&table.to_be_bytes());
b
}
#[test]
fn languages_and_every_truncation() {
let b = plist(&[&[0xd1, 1, 2], b"\x5eAppleLanguages", &[0xa1, 3], b"\x55ja-JP"]);
let p = parse_binary(&b).unwrap();
assert_eq!(p.get("AppleLanguages").unwrap().as_array().unwrap()[0].as_str(), Some("ja-JP"));
for n in 0..b.len() {
assert!(parse_binary(&b[..n]).is_err(), "prefix {n}");
}
}
#[test]
fn cycles_and_repeated_references() {
assert!(parse_binary(&plist(&[&[0xa1, 0]])).is_err());
let b = plist(&[&[0xa3, 1, 1, 1], b"\x51x"]);
assert_eq!(parse_binary(&b).unwrap(), Value::Array(vec![Value::String("x".into()); 3]));
assert!(parse_binary_with_limits(&b, Limits { max_nodes: 3, ..Limits::default() }).is_err());
assert!(parse_binary_with_limits(&b, Limits { max_expanded_bytes: 2, ..Limits::default() }).is_err());
}
#[test]
fn explicit_limits_and_version() {
let b = plist(&[&[0xa1, 1], b"\x51x"]);
for l in [
Limits { max_input_bytes: b.len() - 1, ..Limits::default() },
Limits { max_objects: 1, ..Limits::default() },
Limits { max_depth: 1, ..Limits::default() },
Limits { max_nodes: 0, ..Limits::default() },
] {
assert!(parse_binary_with_limits(&b, l).is_err());
}
let mut future = b;
future[7] = b'1';
assert!(parse_binary(&future).is_err());
}
#[test]
fn utf16_and_lossy_expansion_spend_budget() {
let b = plist(&[&[0x62, 0xd8, 0x3d, 0xde, 0x00]]);
assert_eq!(parse_binary(&b).unwrap().as_str(), Some("😀"));
assert!(parse_binary_with_limits(&b, Limits { max_expanded_bytes: 3, ..Limits::default() }).is_err());
let bad = plist(&[&[0x51, 0xff]]);
assert_eq!(parse_binary(&bad).unwrap().as_str(), Some("�"));
assert!(parse_binary_with_limits(&bad, Limits { max_expanded_bytes: 2, ..Limits::default() }).is_err());
}
#[test]
fn selective_lookup_ignores_unrelated_graphs_and_preserves_first_match() {
use craft_plist::first_string_in_array;
let b = plist(&[&[0xd2, 1, 2, 3, 4], b"\x55Other", b"\x5eAppleLanguages", &[0xaf], &[0xa2, 5, 6], b"\x55ja-JP", &[0xff]]);
assert!(parse_binary(&b).is_err());
assert_eq!(first_string_in_array(&b, "AppleLanguages", Limits::default()).unwrap().as_deref(), Some("ja-JP"));
let duplicate = plist(&[&[0xd2, 1, 1, 2, 3], b"\x5eAppleLanguages", &[0xa1, 4], &[0xa1, 5], b"\x55zh-TW", b"\x55ko-KR"]);
assert_eq!(first_string_in_array(&duplicate, "AppleLanguages", Limits::default()).unwrap().as_deref(), Some("zh-TW"));
assert!(first_string_in_array(&b, "AppleLanguages", Limits { max_expanded_bytes: 1, ..Limits::default() }).is_err());
}
#[test]
fn selective_lookup_requires_an_array_not_a_set() {
use craft_plist::first_string_in_array;
let b = plist(&[&[0xd1, 1, 2], b"\x5eAppleLanguages", &[0xc1, 3], b"\x55ja-JP"]);
assert_eq!(first_string_in_array(&b, "AppleLanguages", Limits::default()).unwrap(), None);
}
+47
View File
@@ -0,0 +1,47 @@
use craft_plist::{Value, parse_binary};
fn single_object(object: &[u8]) -> Vec<u8> {
let mut data = b"bplist00".to_vec();
data.extend_from_slice(object);
let table = data.len() as u64;
data.push(8);
data.extend_from_slice(&[0, 0, 0, 0, 0, 0, 1, 1]);
data.extend_from_slice(&1u64.to_be_bytes());
data.extend_from_slice(&0u64.to_be_bytes());
data.extend_from_slice(&table.to_be_bytes());
data
}
#[test]
fn unsupported_integer_widths_are_not_clamped() {
for marker in 0x15..=0x1f {
let mut object = vec![marker];
object.extend_from_slice(&[0; 16]);
assert!(parse_binary(&single_object(&object)).is_err(), "accepted {marker:#x}");
}
}
#[test]
fn extended_lengths_and_uids_do_not_lose_high_bytes() {
let mut length = vec![0x4f, 0x14];
length.extend_from_slice(&[0; 16]);
assert!(parse_binary(&single_object(&length)).is_err());
for marker in 0x88..=0x8f {
let mut object = vec![marker, 1];
object.resize(usize::from(marker & 15) + 2, 0);
assert!(parse_binary(&single_object(&object)).is_err(), "accepted {marker:#x}");
}
}
#[test]
fn supported_maximum_widths_keep_their_values() {
let mut integer = vec![0x14];
integer.extend_from_slice(&i128::MAX.to_be_bytes());
assert!(matches!(parse_binary(&single_object(&integer)), Ok(Value::Integer(i)) if i == i128::MAX));
let mut uid = vec![0x87];
uid.extend_from_slice(&u64::MAX.to_be_bytes());
assert!(matches!(parse_binary(&single_object(&uid)), Ok(Value::Uid(i)) if i == u64::MAX));
let mut empty = vec![0x4f, 0x13];
empty.extend_from_slice(&0u64.to_be_bytes());
assert!(matches!(parse_binary(&single_object(&empty)), Ok(Value::Data(d)) if d.is_empty()));
}
+31
View File
@@ -0,0 +1,31 @@
use craft_plist::{Value, parse_binary};
fn single_object(object: &[u8], offset: u8) -> Vec<u8> {
let mut data = b"bplist00".to_vec();
data.extend_from_slice(object);
let table = data.len() as u64;
data.push(offset);
data.extend_from_slice(&[0, 0, 0, 0, 0, 0, 1, 1]);
data.extend_from_slice(&1u64.to_be_bytes());
data.extend_from_slice(&0u64.to_be_bytes());
data.extend_from_slice(&table.to_be_bytes());
data
}
#[test]
fn binary_values_cannot_consume_the_offset_table_or_trailer() {
for object in [&[0x54, b'x'][..], &[0x43, 0x42], &[0x13], &[0x87], &[0x62, 0, b'x']] {
assert!(parse_binary(&single_object(object, 8)).is_err(), "accepted object {object:02x?}");
}
}
#[test]
fn binary_offsets_cannot_point_inside_the_file_header() {
assert!(parse_binary(&single_object(&[0x00], 0)).is_err());
assert!(matches!(parse_binary(&single_object(&[0x00], 8)), Ok(Value::Null)));
}
#[test]
fn objects_ending_at_the_table_boundary_are_valid() {
assert!(matches!(parse_binary(&single_object(&[0x51, b'x'], 8)), Ok(Value::String(s)) if s == "x"));
}
+955
View File
@@ -0,0 +1,955 @@
//! Based on the direct CUPS transport from contributor PR #156 (ahmedhosnypro),
//! kept separate from the broader network-printing registry in PR #116.
//! IPP/1.1 straight to the local CUPS server: printer discovery (`CUPS-Get-Printers`,
//! `CUPS-Get-Default`) and job submission (`Print-Job`) over HTTP/1.1, for when `lpstat`/`lp`
//! are missing (a sandboxed install, where the print dialog would otherwise have no printers).
//! Implemented from the public IPP encoding (RFC 2910/8010) and semantics (RFC 8011) and
//! CUPS's IPP documentation; the scheduler is reached on its socket or selected TCP endpoint.
//!
//! # Blocking and authorization
//! The caller authorizes endpoint selection. The absolute exchange deadline covers all request
//! writes and reply reads **after connection**. Standard-library DNS resolution and Unix socket
//! connection are blocking OS calls outside that deadline. TCP connection attempts have their
//! own timeout. This is not a whole-operation deadline API: do not call it on a UI thread or
//! promise bounded completion for arbitrary named hosts/Unix listeners. No detached timeout
//! thread is spawned; callers needing cancellation must supply a separately bounded transport.
#[cfg(all(test, unix))]
mod tests;
use super::{Duplex, Error, Job, Printer, Scaling};
use std::io::{Read, Write};
use std::net::{SocketAddr, TcpStream, ToSocketAddrs};
#[cfg(unix)]
use std::os::unix::net::UnixStream;
use std::path::PathBuf;
use std::sync::atomic::{AtomicU32, Ordering};
use std::time::{Duration, Instant};
/// Where the local scheduler listens: its socket, else its loopback port.
const CUPS_SOCKET: &str = "/run/cups/cups.sock";
/// Caps on what the server may hand back: a reply is read into memory before it is parsed.
const MAX_BODY: usize = 1 << 20;
const MAX_HEADERS: usize = 8 << 10;
const MAX_PRINTERS: usize = 256;
const MAX_NAME: usize = 256;
/// A job's title on the wire; IPP values are u16-length, and no real title is this long.
const MAX_JOB_NAME: usize = 255;
/// A wedged scheduler must not hang the dialog; a job may carry megabytes and is given longer.
const CONNECT_TIMEOUT: Duration = Duration::from_secs(1);
const DISCOVERY_TIMEOUT: Duration = Duration::from_secs(2);
const JOB_TIMEOUT: Duration = Duration::from_secs(30);
/// IPP operation codes: the standard Print-Job, and CUPS's discovery extensions.
const OPERATION_PRINT_JOB: u16 = 0x0002;
const OPERATION_CUPS_GET_DEFAULT: u16 = 0x4001;
const OPERATION_CUPS_GET_PRINTERS: u16 = 0x4002;
/// IPP value tags and group delimiters (RFC 8010 §5.1); the ones this client sends or reads.
const GROUP_OPERATION: u8 = 0x01;
const GROUP_JOB: u8 = 0x02;
const GROUP_END: u8 = 0x03;
const GROUP_PRINTER: u8 = 0x04;
const TAG_INTEGER: u8 = 0x21;
const TAG_BOOLEAN: u8 = 0x22;
const TAG_NAME: u8 = 0x42;
const TAG_KEYWORD: u8 = 0x44;
const TAG_URI: u8 = 0x45;
const TAG_CHARSET: u8 = 0x47;
const TAG_LANGUAGE: u8 = 0x48;
const TAG_MIME: u8 = 0x49;
static REQUEST_ID: AtomicU32 = AtomicU32::new(1);
/// How the scheduler is reached: its unix socket, else its loopback port.
#[derive(Clone, Debug)]
pub enum Server {
Unix(PathBuf),
Tcp(SocketAddr),
/// A caller-authorized host. DNS is resolved once for each connection attempt.
Named(String, u16),
}
impl Server {
/// Parse an explicitly selected CUPS_SERVER value, without connecting. No URLs,
/// credentials, control characters or HTTP authority delimiters are accepted.
pub fn parse(value: &str) -> Result<Self, Error> {
if value.starts_with('/') {
return Ok(Self::Unix(value.into()));
}
if value.is_empty() || value.len() > 255 || value.bytes().any(|c| c.is_ascii_control() || c.is_ascii_whitespace() || b"/@?#\\".contains(&c)) {
return Err(Error::Spool("invalid CUPS server".into()));
}
let (host, port) = if let Some(rest) = value.strip_prefix('[') {
let (host, tail) = rest.split_once(']').ok_or_else(|| Error::Spool("invalid CUPS IPv6 host".into()))?;
if !host.contains(':') {
return Err(Error::Spool("bracketed CUPS host must be IPv6".into()));
}
let port = if tail.is_empty() {
631
} else {
tail.strip_prefix(':')
.and_then(|p| p.parse::<u16>().ok())
.filter(|p| *p != 0)
.ok_or_else(|| Error::Spool("invalid CUPS port".into()))?
};
(host, port)
} else if value.matches(':').count() > 1 {
// A bare IPv6 address is a host. A colon after its scope name may
// specify a port without cutting an address hextet in half.
if let Some((_, zone)) = value.split_once('%')
&& zone.contains(':')
{
let (host, port) = value.rsplit_once(':').ok_or_else(|| Error::Spool("invalid CUPS endpoint".into()))?;
(host, port.parse::<u16>().ok().filter(|p| *p != 0).ok_or_else(|| Error::Spool("invalid CUPS port".into()))?)
} else {
(value, 631)
}
} else {
match value.rsplit_once(':') {
Some((host, port)) => (host, port.parse::<u16>().ok().filter(|p| *p != 0).ok_or_else(|| Error::Spool("invalid CUPS port".into()))?),
None => (value, 631),
}
};
if host.is_empty() || host.contains(['[', ']']) {
return Err(Error::Spool("invalid CUPS host".into()));
}
if let Ok(ip) = host.parse::<std::net::IpAddr>() {
return Ok(Self::Tcp(SocketAddr::new(ip, port)));
}
if host.contains(':') {
let (ip, zone) = host.split_once('%').ok_or_else(|| Error::Spool("invalid CUPS IPv6 host".into()))?;
if ip.parse::<std::net::Ipv6Addr>().is_err()
|| zone.is_empty()
|| !zone.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.'))
{
return Err(Error::Spool("invalid CUPS IPv6 scope".into()));
}
} else if host.contains('%') {
return Err(Error::Spool("invalid CUPS host".into()));
}
Ok(Self::Named(host.into(), port))
}
fn authority(&self) -> String {
match self {
Self::Unix(_) => "localhost".into(),
Self::Tcp(addr) => addr.to_string().replace('%', "%25"),
Self::Named(host, port) if host.contains(':') => format!("[{}]:{port}", host.replace('%', "%25")),
Self::Named(host, port) => format!("{host}:{port}"),
}
}
}
/// Local scheduler candidates, honoring the user's explicit CUPS_SERVER setting.
/// No requests are made by this function; apps must authorize selection before use.
pub fn configured_servers() -> Result<Vec<Server>, Error> {
if let Some(value) = std::env::var_os("CUPS_SERVER").filter(|v| !v.is_empty()) {
return Ok(vec![Server::parse(&value.to_string_lossy())?]);
}
Ok(vec![
Server::Unix(CUPS_SOCKET.into()),
Server::Unix("/var/run/cups/cups.sock".into()),
Server::Unix("/private/var/run/cupsd".into()),
Server::Tcp(([127, 0, 0, 1], 631).into()),
])
}
fn endpoints() -> [Server; 2] {
[Server::Unix(PathBuf::from(CUPS_SOCKET)), Server::Tcp(([127, 0, 0, 1], 631).into())]
}
/// Whether the local CUPS server is reachable: its socket, else its loopback port. A missing
/// scheduler is a normal `false`, not an error.
pub fn cups_reachable() -> bool {
endpoints().iter().any(reachable)
}
/// Probe a caller-authorized endpoint without sending a print request.
/// DNS and Unix connect have the blocking limitations documented on this module.
pub fn reachable(server: &Server) -> bool {
connect(server).is_ok()
}
fn connect(server: &Server) -> std::io::Result<Stream> {
match server {
#[cfg(unix)]
Server::Unix(path) => UnixStream::connect(path).map(Stream::Unix),
#[cfg(not(unix))]
Server::Unix(_) => Err(std::io::Error::new(std::io::ErrorKind::Unsupported, "Unix sockets unavailable")),
Server::Named(host, port) => {
// Validate even directly constructed public variants before resolving or writing headers.
let endpoint = if host.contains(':') { format!("[{host}]:{port}") } else { format!("{host}:{port}") };
let parsed = Server::parse(&endpoint).map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidInput, e))?;
if matches!(parsed, Server::Unix(_)) {
return Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, "a named CUPS host cannot be a Unix path"));
}
let addr = (host.as_str(), *port)
.to_socket_addrs()?
.next()
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "CUPS host has no address"))?;
TcpStream::connect_timeout(&addr, CONNECT_TIMEOUT).map(Stream::Tcp)
}
// A loopback connect either answers promptly or the server is not there.
Server::Tcp(addr) => TcpStream::connect_timeout(addr, CONNECT_TIMEOUT).map(|s| {
let _ = s.set_nodelay(true);
Stream::Tcp(s)
}),
}
}
/// A connection to the scheduler.
enum Stream {
#[cfg(unix)]
Unix(UnixStream),
Tcp(TcpStream),
}
impl Stream {
fn set_timeouts(&self, timeout: Duration) -> std::io::Result<()> {
let (read, write) = match self {
#[cfg(unix)]
Stream::Unix(s) => (s.set_read_timeout(Some(timeout)), s.set_write_timeout(Some(timeout))),
Stream::Tcp(s) => (s.set_read_timeout(Some(timeout)), s.set_write_timeout(Some(timeout))),
};
read.and(write)
}
}
impl Read for Stream {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
match self {
#[cfg(unix)]
Stream::Unix(s) => s.read(buf),
Stream::Tcp(s) => s.read(buf),
}
}
}
impl Write for Stream {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
match self {
#[cfg(unix)]
Stream::Unix(s) => s.write(buf),
Stream::Tcp(s) => s.write(buf),
}
}
fn flush(&mut self) -> std::io::Result<()> {
match self {
#[cfg(unix)]
Stream::Unix(s) => s.flush(),
Stream::Tcp(s) => s.flush(),
}
}
}
/// The server's queues (CUPS-Get-Printers) and its default destination (CUPS-Get-Default), for
/// the Print dialog when `lpstat` is missing. A default the queue list lacks is appended, so
/// the dialog always has a selection to restore; a default that cannot be named still leaves
/// the queues usable.
pub fn printers() -> Result<Vec<Printer>, Error> {
printers_at(&endpoints())
}
pub fn printers_at(endpoints: &[Server]) -> Result<Vec<Printer>, Error> {
let queues = discover(endpoints, OPERATION_CUPS_GET_PRINTERS)?;
let default = discover(endpoints, OPERATION_CUPS_GET_DEFAULT).ok().and_then(|names| names.into_iter().next());
let mut printers: Vec<Printer> = Vec::new();
for name in queues {
if printers.len() >= MAX_PRINTERS {
break;
}
if !printers.iter().any(|p| p.name == name) {
printers.push(Printer { description: String::new(), default: default.as_deref() == Some(name.as_str()), name, two_sided: None });
}
}
if let Some(name) = default
&& !printers.iter().any(|p| p.name == name)
{
printers.push(Printer { description: String::new(), name, default: true, two_sided: None });
}
Ok(printers)
}
/// The printer names a discovery reply carries: every queue (CUPS-Get-Printers), or the default
/// destination (CUPS-Get-Default).
fn discover(endpoints: &[Server], operation: u16) -> Result<Vec<String>, Error> {
let reply = post(endpoints, "/", &discovery_request(operation), DISCOVERY_TIMEOUT, true)?;
let parsed = parse_reply(&reply)?;
if status_ok(parsed.status) { Ok(parsed.names) } else { Err(refused(parsed.status)) }
}
/// Submit the PDF as a Print-Job to the printer (the job's, else the server's default); the
/// reply is the job message, like `lp` prints it (`request id is Office-12`). The driver's own
/// job options (PPD keywords) are not sent on this path: they have no IPP equivalents without
/// reading the printer's capabilities, which is another request.
pub fn print_job(pdf: &[u8], job: &Job) -> Result<String, Error> {
print_job_at(&endpoints(), pdf, job)
}
pub(crate) fn print_job_at(endpoints: &[Server], pdf: &[u8], job: &Job) -> Result<String, Error> {
let queue = match &job.printer {
Some(name) => name.clone(),
None => discover(endpoints, OPERATION_CUPS_GET_DEFAULT)?
.into_iter()
.next()
.ok_or_else(|| Error::Spool("the print server has no default printer; choose one in the dialog".into()))?,
};
if !is_queue_name(&queue) {
return Err(Error::Spool(format!("not a printer name: {queue}")));
}
let reply = post(endpoints, &format!("/printers/{queue}"), &print_job_request(&queue, pdf, job), JOB_TIMEOUT, false)?;
let parsed = parse_reply(&reply)?;
if !status_ok(parsed.status) {
return Err(refused(parsed.status));
}
Ok(match parsed.job_id {
Some(id) => format!("request id is {queue}-{id}"),
None => format!("the job was accepted by {queue}"),
})
}
/// A queue class can route a job to any member printer. Keep the destination kind
/// explicit rather than guessing it from a name shared by a printer and a class.
#[derive(Clone, Debug)]
pub struct Destination {
pub name: String,
pub is_class: bool,
}
/// List both printer queues and classes from caller-selected CUPS endpoints.
/// The caller owns endpoint selection/authorization; this API does not discover network hosts.
pub fn destinations_at(endpoints: &[Server]) -> Result<Vec<Queue>, Error> {
let mut out = queues_at(endpoints, false)?;
out.extend(queues_at(endpoints, true)?);
if out.len() > MAX_PRINTERS {
return Err(Error::Spool("too many CUPS destinations".into()));
}
let default = default_at(endpoints)?;
for queue in &mut out {
queue.is_default = default.as_deref() == Some(queue.name.as_str());
}
Ok(out)
}
/// List either printer queues or classes, without resolving defaults. Applications can
/// explicitly choose whether an optional class/default query failure should hide otherwise
/// usable printer queues. No error is swallowed here except CUPS's absent/unsupported list.
pub fn queues_at(endpoints: &[Server], is_class: bool) -> Result<Vec<Queue>, Error> {
let operation = if is_class { 0x4005 } else { OPERATION_CUPS_GET_PRINTERS };
let reply = post(endpoints, "/", &discovery_request(operation), DISCOVERY_TIMEOUT, true)?;
let parsed = parse_reply(&reply)?;
if !status_ok(parsed.status) {
if parsed.status == 0x0406 || (is_class && parsed.status == 0x0501) {
return Ok(Vec::new());
}
return Err(refused(parsed.status));
}
let mut queues = parsed.queues;
for queue in &mut queues {
queue.is_class = is_class;
}
Ok(queues)
}
/// The scheduler's default queue; not-found means no default has been configured.
pub fn default_at(endpoints: &[Server]) -> Result<Option<String>, Error> {
let reply = post(endpoints, "/", &discovery_request(OPERATION_CUPS_GET_DEFAULT), DISCOVERY_TIMEOUT, true)?;
let parsed = parse_reply(&reply)?;
if parsed.status == 0x0406 {
return Ok(None);
}
if !status_ok(parsed.status) {
return Err(refused(parsed.status));
}
Ok(parsed.names.into_iter().next())
}
/// Metadata from one CUPS printer group, without losing which fields belong together.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Queue {
pub name: String,
pub info: String,
pub state: u32,
pub accepting_jobs: bool,
pub is_default: bool,
pub is_class: bool,
}
impl Default for Queue {
fn default() -> Self {
Self { name: String::new(), info: String::new(), state: 3, accepting_jobs: true, is_default: false, is_class: false }
}
}
/// Submit once to an explicitly selected queue/class, returning the numeric server job id.
/// An absent id is an uncertain accepted outcome, not permission to retry the document.
pub fn submit_at(endpoints: &[Server], destination: &Destination, pdf: &[u8], job: &Job) -> Result<u32, Error> {
submit_as_at(endpoints, destination, pdf, job, "")
}
/// As [`submit_at`], with the user name supplied by the application, never inferred from
/// process credentials. Once any request bytes may have been sent, no other endpoint is tried.
pub fn submit_as_at(endpoints: &[Server], destination: &Destination, pdf: &[u8], job: &Job, user: &str) -> Result<u32, Error> {
let path = destination_path(destination)?;
if user.len() > MAX_JOB_NAME || user.chars().any(char::is_control) {
return Err(Error::Spool("invalid CUPS user name".into()));
}
if job.copies == 0 || job.copies > 999 {
return Err(Error::Spool("copies must be between 1 and 999".into()));
}
let mut last = Error::Spool("no CUPS endpoint selected".into());
for endpoint in endpoints {
let mut stream = match connect(endpoint) {
Ok(stream) => stream,
Err(error) => {
last = Error::Spool(format!("CUPS connection failed: {error}"));
continue;
}
};
let authority = endpoint.authority();
let request = print_job_request_for(&authority, &path, pdf, job, user);
// Never retry exchange errors: the scheduler may already have accepted the job.
let reply = exchange(&mut stream, &authority, &path, &request, JOB_TIMEOUT)?;
let parsed = parse_reply(&reply)?;
if !status_ok(parsed.status) {
return Err(refused(parsed.status));
}
return parsed
.job_id
.filter(|id| *id != 0 && *id <= i32::MAX as u32)
.ok_or_else(|| Error::Spool("CUPS accepted the job without a usable job id; do not resubmit".into()));
}
Err(last)
}
/// Encode one destination as a URI path segment, never as routing syntax. Names from
/// discovery may include spaces or Unicode. Reject separators, controls and dot segments
/// rather than relying on a server to keep an encoded traversal request harmless.
fn destination_path(destination: &Destination) -> Result<String, Error> {
let name = &destination.name;
if name.is_empty()
|| name.len() > MAX_NAME
|| matches!(name.as_str(), "." | "..")
|| name.chars().any(|c| c.is_control() || matches!(c, '/' | '\\'))
{
return Err(Error::Spool("invalid CUPS destination name".into()));
}
let kind = if destination.is_class { "classes" } else { "printers" };
let mut path = format!("/{kind}/");
for byte in name.bytes() {
if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'.' | b'_' | b'~') {
path.push(char::from(byte));
} else {
use std::fmt::Write as _;
write!(&mut path, "%{byte:02X}").map_err(|_| Error::Spool("could not encode CUPS destination".into()))?;
}
}
Ok(path)
}
/// A CUPS queue name: ASCII letters, digits and `_`, `-`, `.` — what the scheduler accepts, and
/// what cannot break the printer URI's path.
fn is_queue_name(name: &str) -> bool {
!name.is_empty() && name.len() <= MAX_NAME && name.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.'))
}
/// One IPP request and its reply body. Discovery may try each endpoint in turn; a job is given
/// to the first endpoint that accepts a connection, once: a retry could print it twice.
pub(crate) fn post(endpoints: &[Server], path: &str, body: &[u8], timeout: Duration, retry: bool) -> Result<Vec<u8>, Error> {
let mut failed: Option<Error> = None;
for server in endpoints {
let mut stream = match connect(server) {
Ok(stream) => stream,
Err(e) => {
failed = Some(Error::Spool(format!("the print server could not be reached: {e}")));
continue;
}
};
match exchange(&mut stream, &server.authority(), path, body, timeout) {
Ok(reply) => return Ok(reply),
Err(e) => {
failed = Some(e);
if !retry {
break;
}
}
}
}
Err(failed.unwrap_or_else(|| Error::Spool("the print server could not be reached".into())))
}
/// Send one IPP request and read the reply's body.
fn exchange(stream: &mut Stream, authority: &str, path: &str, body: &[u8], timeout: Duration) -> Result<Vec<u8>, Error> {
let mut stream = DeadlineReader { stream, end: Instant::now() + timeout };
let head = format!(
"POST {path} HTTP/1.1\r\nHost: {authority}\r\nContent-Type: application/ipp\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
body.len()
);
stream
.write_all(head.as_bytes())
.and_then(|()| stream.write_all(body))
.and_then(|()| stream.flush())
.map_err(|e| Error::Spool(format!("the request could not be sent to the print server: {e}")))?;
let reply = read_reply(&mut stream)?;
validate_reply_identity(body, &reply)?;
Ok(reply)
}
/// One absolute deadline shared by request writes and reply reads after connection.
struct DeadlineReader<'a> {
stream: &'a mut Stream,
end: Instant,
}
impl Write for DeadlineReader<'_> {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
let left = self
.end
.checked_duration_since(Instant::now())
.filter(|d| !d.is_zero())
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::TimedOut, "CUPS exchange deadline exceeded"))?;
self.stream.set_timeouts(left)?;
self.stream.write(buf)
}
fn flush(&mut self) -> std::io::Result<()> {
self.stream.flush()
}
}
fn validate_reply_identity(request: &[u8], reply: &[u8]) -> Result<(), Error> {
if reply.get(..2) != Some(&[1, 1]) || request.get(4..8).is_none() || request.get(4..8) != reply.get(4..8) {
return Err(Error::Spool("CUPS reply version or request id does not match; do not resubmit".into()));
}
Ok(())
}
impl Read for DeadlineReader<'_> {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
let left = self
.end
.checked_duration_since(Instant::now())
.filter(|d| !d.is_zero())
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::TimedOut, "CUPS reply deadline exceeded"))?;
#[cfg(not(target_os = "macos"))]
self.stream.set_timeouts(left)?;
#[cfg(target_os = "macos")]
if let Err(error) = self.stream.set_timeouts(left) {
// Darwin rejects timeout updates on a disconnected Unix socket even
// when a complete reply is still buffered. Never fall back to a
// blocking read: drain at most this buffer, or fail on WouldBlock.
// Every subsequent read rechecks the same absolute deadline above.
if error.raw_os_error() == Some(22)
&& let Stream::Unix(stream) = self.stream
{
stream.set_nonblocking(true)?;
let result = stream.read(buf);
let restored = stream.set_nonblocking(false);
return result.and_then(|count| restored.map(|()| count));
}
return Err(error);
}
self.stream.read(buf)
}
}
fn read_reply(stream: &mut impl Read) -> Result<Vec<u8>, Error> {
let mut head = Vec::new();
let mut byte = [0u8; 1];
loop {
if head.len() >= MAX_HEADERS {
return Err(Error::Spool("the print server sent a header block that is too large".into()));
}
match stream.read(&mut byte) {
Ok(0) => return Err(Error::Spool("the print server closed the connection before sending its reply".into())),
Ok(_) => head.push(byte[0]),
Err(e) => return Err(Error::Spool(format!("the print server's reply could not be read: {e}"))),
}
if head.ends_with(b"\r\n\r\n") {
break;
}
}
let head = String::from_utf8_lossy(&head);
let Some(status_line) = head.lines().next() else { return Err(Error::Spool("the print server sent an unreadable reply".into())) };
let code = status_line
.strip_prefix("HTTP/")
.and_then(|rest| rest.split_once(' '))
.and_then(|(_, code)| code.split_whitespace().next())
.and_then(|code| code.parse::<u16>().ok())
.ok_or_else(|| Error::Spool("the print server sent an unreadable reply".into()))?;
match code {
200..=299 => {}
401 => return Err(Error::Spool("the print server requires authentication".into())),
426 => return Err(Error::Spool("the print server only accepts encrypted connections".into())),
_ => return Err(Error::Spool(format!("the print server refused the request (HTTP {code})"))),
}
let mut content_length: Option<usize> = None;
let mut chunked = false;
for line in head.lines().skip(1) {
// The empty line ends the header block; any other line without a colon is malformed.
if line.is_empty() {
continue;
}
let Some((name, value)) = line.split_once(':') else {
return Err(Error::Spool("the print server sent an unreadable header".into()));
};
match name.trim().to_ascii_lowercase().as_str() {
"content-length" => {
let len = value.trim().parse::<usize>().map_err(|_| Error::Spool("invalid Content-Length".into()))?;
if content_length.replace(len).is_some() {
return Err(Error::Spool("duplicate Content-Length".into()));
}
}
// Only `identity` is not a transfer encoding to be decoded.
"transfer-encoding" => {
if chunked || !value.trim().eq_ignore_ascii_case("chunked") {
return Err(Error::Spool("unsupported Transfer-Encoding".into()));
}
chunked = true;
}
_ => {}
}
}
if chunked {
if content_length.is_some() {
return Err(Error::Spool("ambiguous reply framing".into()));
}
return read_chunks(stream);
}
let Some(len) = content_length else { return Err(Error::Spool("the print server sent no Content-Length".into())) };
if len > MAX_BODY {
return Err(Error::Spool(format!("the print server's reply is too large ({len} bytes)")));
}
let mut body = vec![0u8; len];
stream.read_exact(&mut body).map_err(|e| Error::Spool(format!("the print server's reply was cut short: {e}")))?;
Ok(body)
}
fn read_chunks(stream: &mut impl Read) -> Result<Vec<u8>, Error> {
fn line(stream: &mut impl Read) -> Result<Vec<u8>, Error> {
let mut out = Vec::new();
for _ in 0..MAX_HEADERS {
let mut byte = [0];
stream.read_exact(&mut byte).map_err(|e| Error::Spool(format!("truncated chunk: {e}")))?;
out.push(byte[0]);
if out.ends_with(b"\r\n") {
out.truncate(out.len() - 2);
return Ok(out);
}
}
Err(Error::Spool("chunk line exceeds limit".into()))
}
let mut body = Vec::new();
for _ in 0..100_000 {
let header = line(stream)?;
let size = header.split(|b| *b == b';').next().unwrap_or_default();
if size.is_empty() || !size.iter().all(u8::is_ascii_hexdigit) {
return Err(Error::Spool("invalid chunk size".into()));
}
let len = std::str::from_utf8(size)
.ok()
.and_then(|s| usize::from_str_radix(s, 16).ok())
.ok_or_else(|| Error::Spool("invalid chunk size".into()))?;
if len == 0 {
let mut total = 0usize;
loop {
let trailer = line(stream)?;
total = total.saturating_add(trailer.len() + 2);
if total > MAX_HEADERS {
return Err(Error::Spool("chunk trailers exceed limit".into()));
}
if trailer.is_empty() {
return Ok(body);
}
if !trailer.contains(&b':') {
return Err(Error::Spool("invalid chunk trailer".into()));
}
}
}
let end = body.len().checked_add(len).filter(|n| *n <= MAX_BODY).ok_or_else(|| Error::Spool("chunked reply exceeds limit".into()))?;
let start = body.len();
body.resize(end, 0);
stream.read_exact(&mut body[start..]).map_err(|e| Error::Spool(format!("truncated chunk: {e}")))?;
let mut crlf = [0; 2];
stream.read_exact(&mut crlf).map_err(|e| Error::Spool(format!("truncated chunk: {e}")))?;
if crlf != *b"\r\n" {
return Err(Error::Spool("invalid chunk terminator".into()));
}
}
Err(Error::Spool("too many chunks".into()))
}
/// An IPP request being built: a version, an operation and a request id, then attributes, then
/// the document.
struct Request {
bytes: Vec<u8>,
}
impl Request {
fn new(operation: u16) -> Self {
// IPP 1.1: version, operation, a request id (any nonzero value).
let mut bytes = vec![1, 1];
bytes.extend(operation.to_be_bytes());
bytes.extend(REQUEST_ID.fetch_add(1, Ordering::Relaxed).max(1).to_be_bytes());
Request { bytes }
}
fn group(&mut self, tag: u8) {
self.bytes.push(tag);
}
fn end(&mut self) {
self.bytes.push(GROUP_END);
}
fn attribute(&mut self, tag: u8, name: &str, value: &[u8]) {
let (Ok(name_len), Ok(value_len)) = (u16::try_from(name.len()), u16::try_from(value.len())) else {
return;
};
self.bytes.push(tag);
self.bytes.extend(name_len.to_be_bytes());
self.bytes.extend(name.as_bytes());
self.bytes.extend(value_len.to_be_bytes());
self.bytes.extend(value);
}
/// An additional value of the previous attribute (a `1setOf`): the name is empty.
fn additional(&mut self, tag: u8, value: &str) {
self.attribute(tag, "", value.as_bytes());
}
}
/// A discovery request: the operation's required attributes, then the names to be answered with.
fn discovery_request(operation: u16) -> Vec<u8> {
let mut r = Request::new(operation);
r.group(GROUP_OPERATION);
r.attribute(TAG_CHARSET, "attributes-charset", b"utf-8");
r.attribute(TAG_LANGUAGE, "attributes-natural-language", b"en");
r.attribute(TAG_URI, "printer-uri", b"ipp://localhost/");
r.attribute(TAG_KEYWORD, "requested-attributes", b"printer-name");
r.additional(TAG_KEYWORD, "printer-info");
r.additional(TAG_KEYWORD, "printer-state");
r.additional(TAG_KEYWORD, "printer-is-accepting-jobs");
r.end();
r.bytes
}
/// A Print-Job request for `queue`: the job's options as IPP attributes, the PDF as the document
/// data that follows the end of attributes.
fn print_job_request(queue: &str, pdf: &[u8], job: &Job) -> Vec<u8> {
print_job_request_path(&format!("/printers/{queue}"), pdf, job)
}
fn print_job_request_path(path: &str, pdf: &[u8], job: &Job) -> Vec<u8> {
print_job_request_for("localhost", path, pdf, job, "")
}
fn print_job_request_for(authority: &str, path: &str, pdf: &[u8], job: &Job, user: &str) -> Vec<u8> {
let mut r = Request::new(OPERATION_PRINT_JOB);
r.group(GROUP_OPERATION);
r.attribute(TAG_CHARSET, "attributes-charset", b"utf-8");
r.attribute(TAG_LANGUAGE, "attributes-natural-language", b"en");
r.attribute(TAG_URI, "printer-uri", format!("ipp://{authority}{path}").as_bytes());
if !user.is_empty() {
r.attribute(TAG_NAME, "requesting-user-name", user.as_bytes());
}
r.attribute(TAG_NAME, "job-name", truncate_utf8(&job.title, MAX_JOB_NAME).as_bytes());
r.attribute(TAG_MIME, "document-format", b"application/pdf");
r.group(GROUP_JOB);
r.attribute(TAG_INTEGER, "copies", &job.copies.clamp(1, 999).to_be_bytes());
r.attribute(TAG_BOOLEAN, "collate", &[u8::from(job.collate)]);
if let Some(duplex) = job.duplex {
r.attribute(
TAG_KEYWORD,
"sides",
match duplex {
Duplex::Off => "one-sided",
Duplex::LongEdge => "two-sided-long-edge",
Duplex::ShortEdge => "two-sided-short-edge",
}
.as_bytes(),
);
}
if job.grayscale {
r.attribute(TAG_KEYWORD, "print-color-mode", b"monochrome");
}
// PWG 5100.13 §6.2.5: `none` keeps every sheet at its size, `auto-fit` shrinks only
// oversized ones — the same choices `lp`'s fit-to-page and print-scaling options make.
r.attribute(
TAG_KEYWORD,
"print-scaling",
match job.scaling {
Scaling::Exact => "none",
Scaling::ShrinkToFit => "auto-fit",
}
.as_bytes(),
);
r.end();
r.bytes.extend(pdf);
r.bytes
}
/// The string cut to at most `max` bytes, at a character boundary.
fn truncate_utf8(s: &str, max: usize) -> &str {
if s.len() <= max {
return s;
}
let mut end = max;
while !s.is_char_boundary(end) {
end -= 1;
}
// `end` is a checked boundary; nothing is the only name that cannot be cut.
s.get(..end).unwrap_or_default()
}
/// The parsed parts of a reply: the IPP status, the printer names in its printer groups, and a
/// submission's job id.
struct Reply {
status: u16,
names: Vec<String>,
queues: Vec<Queue>,
job_id: Option<u32>,
}
/// A cursor over a reply: `None` at the end or past a length, never an over-read.
struct Reader<'a> {
bytes: &'a [u8],
pos: usize,
}
impl<'a> Reader<'a> {
fn take(&mut self, len: usize) -> Option<&'a [u8]> {
let end = self.pos.checked_add(len)?;
let taken = self.bytes.get(self.pos..end)?;
self.pos = end;
Some(taken)
}
fn array<const N: usize>(&mut self) -> Option<[u8; N]> {
<[u8; N]>::try_from(self.take(N)?).ok()
}
fn u16(&mut self) -> Option<u16> {
self.array::<2>().map(u16::from_be_bytes)
}
}
fn parse_reply(reply: &[u8]) -> Result<Reply, Error> {
let malformed = || Error::Spool("the print server sent a malformed reply".into());
let mut r = Reader { bytes: reply, pos: 0 };
let _version = r.array::<2>().ok_or_else(malformed)?;
let status = r.u16().ok_or_else(malformed)?;
let _request_id = r.array::<4>().ok_or_else(malformed)?;
let (mut names, mut job_id, mut group) = (Vec::new(), None, 0u8);
let mut queues = Vec::new();
let mut queue = Queue::default();
loop {
let Some(tag) = r.array::<1>().map(|t| t[0]) else { return Err(malformed()) };
match tag {
GROUP_END => {
if !queue.name.is_empty() {
queues.push(queue);
}
break;
}
GROUP_OPERATION | GROUP_JOB | GROUP_PRINTER | 0x05 => {
if !queue.name.is_empty() {
if queues.len() >= MAX_PRINTERS {
return Err(malformed());
}
queues.push(std::mem::take(&mut queue));
} else {
queue = Queue::default();
}
group = tag;
}
// An attribute: name and value, each u16-length. An empty name is an additional
// value of the previous one (the attributes read here are single-valued, so those
// are ignored). Group tags not in the registry and collections (the attributes
// requested here are never collections) are refused, not guessed.
0x10..=0x33 | 0x35..=0x4A => {
let name_len = r.u16().ok_or_else(malformed)?;
if usize::from(name_len) > MAX_NAME {
return Err(malformed());
}
let name_bytes = r.take(usize::from(name_len)).ok_or_else(malformed)?;
let name = std::str::from_utf8(name_bytes).map_err(|_| malformed())?;
let value_len = r.u16().ok_or_else(malformed)?;
let value = r.take(usize::from(value_len)).ok_or_else(malformed)?;
match (group, name, tag) {
(GROUP_PRINTER, "printer-name", TAG_NAME) => {
if let Some(printer) = std::str::from_utf8(value).ok().filter(|n| !n.is_empty() && n.len() <= MAX_NAME) {
if names.len() >= MAX_PRINTERS {
return Err(Error::Spool("too many CUPS destinations".into()));
}
if !queue.name.is_empty() {
return Err(malformed());
}
queue.name = printer.to_string();
names.push(printer.to_string());
}
}
(GROUP_PRINTER, "printer-info", 0x41 | TAG_NAME) => {
// Human descriptions are text, not queue identifiers. Their u16
// wire length and the whole-response MAX_BODY cap bound allocation.
queue.info = std::str::from_utf8(value).map_err(|_| malformed())?.to_owned();
}
(GROUP_PRINTER, "printer-state", 0x23 | TAG_INTEGER) => {
queue.state = u32::from_be_bytes(value.try_into().map_err(|_| malformed())?);
}
(GROUP_PRINTER, "printer-is-accepting-jobs", TAG_BOOLEAN) => {
queue.accepting_jobs = match value {
[0] => false,
[1] => true,
_ => return Err(malformed()),
};
}
(GROUP_JOB, "job-id", TAG_INTEGER) => {
if let Ok(id) = <[u8; 4]>::try_from(value) {
job_id = Some(u32::from_be_bytes(id));
}
}
_ => {}
}
}
_ => return Err(malformed()),
}
}
Ok(Reply { status, names, queues, job_id })
}
/// Successful IPP status codes are `0x00xx` (RFC 8011 Appendix B).
fn status_ok(status: u16) -> bool {
status < 0x0100
}
/// The IPP status code's name, for the error the user sees.
fn status_name(status: u16) -> Option<&'static str> {
Some(match status {
0x0400 => "bad request",
0x0401 => "forbidden",
0x0402 => "not authenticated",
0x0403 => "not authorized",
0x0404 => "not possible",
0x0406 => "printer not found",
0x0408 => "request too large",
0x040A => "PDF is not a supported document format for this printer",
0x0412 => "the document could not be accessed",
0x0500 => "internal error",
0x0501 => "operation not supported",
0x0502 => "service unavailable",
0x0503 => "IPP version not supported",
0x0504 => "device error",
0x0505 => "temporary error",
0x0506 => "the printer is not accepting jobs",
0x0507 => "the printer is busy",
_ => return None,
})
}
fn refused(status: u16) -> Error {
match status_name(status) {
Some(name) => Error::Spool(format!("the print server refused the request ({name})")),
None => Error::Spool(format!("the print server refused the request (IPP status 0x{status:04X})")),
}
}
+593
View File
@@ -0,0 +1,593 @@
//! The IPP client against a fake CUPS server (a unix socket or a loopback port): discovery,
//! Print-Job, and the malformed replies it must refuse without a panic.
use super::*;
use crate as spool;
use crate::cups::{self as ipp, Server};
use std::collections::VecDeque;
use std::io::{Read, Write};
use std::sync::Mutex;
use std::sync::mpsc::{self, Receiver};
use std::time::Duration;
const TIMEOUT: Duration = Duration::from_secs(2);
/// A fake CUPS server: each connection carries one request; the next canned reply goes back
/// (nothing, when the list is out — the client then sees a hang-up). Every request is recorded
/// for the assertions.
struct FakeCups {
server: Server,
requests: Receiver<Vec<u8>>,
}
impl FakeCups {
fn on_unix(replies: Vec<Vec<u8>>) -> std::io::Result<Self> {
let dir = tempfile::tempdir()?;
let path = dir.path().join("cups.sock");
let listener = std::os::unix::net::UnixListener::bind(&path)?;
// The socket must outlive this function; the folder is left for the process to reap.
std::mem::forget(dir);
let requests = listen_unix(listener, replies);
Ok(FakeCups { server: Server::Unix(path), requests })
}
fn on_tcp(replies: Vec<Vec<u8>>) -> std::io::Result<Self> {
let listener = std::net::TcpListener::bind("127.0.0.1:0")?;
let server = Server::Tcp(listener.local_addr()?);
let requests = listen_tcp(listener, replies);
Ok(FakeCups { server, requests })
}
fn request(&self) -> Result<Vec<u8>, mpsc::RecvTimeoutError> {
self.requests.recv_timeout(Duration::from_secs(5))
}
/// The server as the one-endpoint list the client functions take.
fn endpoint(&self) -> &[Server] {
std::slice::from_ref(&self.server)
}
}
fn listen_unix(listener: std::os::unix::net::UnixListener, replies: Vec<Vec<u8>>) -> Receiver<Vec<u8>> {
let (tx, rx) = mpsc::channel();
let replies = Mutex::new(VecDeque::from(replies));
std::thread::spawn(move || {
for stream in listener.incoming().flatten() {
serve(stream, &replies, &tx);
}
});
rx
}
fn listen_tcp(listener: std::net::TcpListener, replies: Vec<Vec<u8>>) -> Receiver<Vec<u8>> {
let (tx, rx) = mpsc::channel();
let replies = Mutex::new(VecDeque::from(replies));
std::thread::spawn(move || {
for stream in listener.incoming().flatten() {
serve(stream, &replies, &tx);
}
});
rx
}
fn serve(mut stream: impl Read + Write, replies: &Mutex<VecDeque<Vec<u8>>>, requests: &mpsc::Sender<Vec<u8>>) {
let Some(request) = read_request(&mut stream) else { return };
let Some(body) = ipp_body(&request) else { return };
let request_id = body.get(4..8).map(|id| id.to_vec());
let _ = requests.send(request);
// A list out of replies is a server that hangs up before answering.
let Ok(mut replies) = replies.lock() else { return };
if let Some(mut reply) = replies.pop_front() {
if let Some(body) = reply.windows(4).position(|w| w == b"\r\n\r\n").map(|at| at + 4)
&& reply.get(body..body + 2) == Some(&[1, 1])
&& let Some(id) = request_id
&& let Some(destination) = reply.get_mut(body + 4..body + 8)
{
destination.copy_from_slice(&id);
}
let _ = stream.write_all(&reply);
let _ = stream.flush();
}
}
/// One HTTP request: the headers (bounded), then the `Content-Length` body it announces.
fn read_request(stream: &mut impl Read) -> Option<Vec<u8>> {
let mut buf = Vec::new();
let mut byte = [0u8; 1];
loop {
match stream.read(&mut byte) {
Ok(0) | Err(_) => return None,
Ok(_) => buf.push(byte[0]),
}
if buf.ends_with(b"\r\n\r\n") {
break;
}
if buf.len() > 1 << 16 {
return None;
}
}
let head = String::from_utf8_lossy(&buf);
let len: usize = head.lines().find_map(|l| l.strip_prefix("Content-Length:")).and_then(|v| v.trim().parse().ok())?;
let head_len = buf.len();
buf.resize(head_len + len, 0);
stream.read_exact(&mut buf[head_len..]).ok()?;
Some(buf)
}
/// An HTTP reply carrying `body`, as CUPS would send it.
fn http_reply(body: &[u8]) -> Vec<u8> {
let mut out = format!("HTTP/1.1 200 OK\r\nContent-Type: application/ipp\r\nContent-Length: {}\r\n\r\n", body.len()).into_bytes();
out.extend(body);
out
}
/// An IPP reply body: `status`, then the attribute groups as raw bytes, then end of attributes.
fn ipp_reply(status: u16, groups: &[&[u8]]) -> Vec<u8> {
let mut out = vec![1, 1];
out.extend(status.to_be_bytes());
out.extend(1u32.to_be_bytes());
for &group in groups {
out.extend(group);
}
out.push(0x03);
out
}
fn group(tag: u8) -> Vec<u8> {
vec![tag]
}
fn printer_name(name: &str) -> Vec<u8> {
attr(0x42, "printer-name", name.as_bytes())
}
/// One attribute, framed the way the client frames them, so `has` finds it in a request.
fn attr(tag: u8, name: &str, value: &[u8]) -> Vec<u8> {
let mut out = vec![tag];
out.extend((name.len() as u16).to_be_bytes());
out.extend(name.as_bytes());
out.extend((value.len() as u16).to_be_bytes());
out.extend(value);
out
}
fn has(bytes: &[u8], needle: &[u8]) -> bool {
!needle.is_empty() && bytes.windows(needle.len()).any(|w| w == needle)
}
/// The IPP part of a recorded request: everything after the HTTP head.
fn ipp_body(request: &[u8]) -> Option<&[u8]> {
let at = request.windows(4).position(|w| w == b"\r\n\r\n")?;
request.get(at + 4..)
}
fn entry(name: &str, default: bool) -> spool::Printer {
spool::Printer { description: String::new(), name: name.into(), default, two_sided: None }
}
#[test]
fn discovery_finds_queues_and_the_default_over_a_unix_socket() {
let fake = FakeCups::on_unix(vec![
http_reply(&ipp_reply(
0x0000,
&[
&group(0x01),
&printer_name("Office_Laser"),
&group(0x04),
&printer_name("Office_Laser"),
&group(0x04),
&printer_name("Label_Writer"),
&group(0x04),
&printer_name("Office_Laser"),
],
)),
http_reply(&ipp_reply(0x0000, &[&group(0x01), &group(0x04), &printer_name("Office_Laser")])),
])
.unwrap();
let printers = ipp::printers_at(fake.endpoint()).unwrap();
assert_eq!(printers, [entry("Office_Laser", true), entry("Label_Writer", false)], "each queue once, the default marked");
let taken = fake.request().unwrap();
let queues = ipp_body(&taken).unwrap();
assert_eq!(&queues[..4], &[1, 1, 0x40, 0x02], "IPP 1.1, CUPS-Get-Printers");
assert!(has(queues, b"ipp://localhost/"));
assert!(has(queues, &attr(0x44, "requested-attributes", b"printer-name")));
assert!(has(queues, b"printer-is-accepting-jobs"), "only the attributes the dialog needs are asked for");
let taken = fake.request().unwrap();
let default = ipp_body(&taken).unwrap();
assert_eq!(&default[..4], &[1, 1, 0x40, 0x01], "CUPS-Get-Default");
}
#[test]
fn a_print_job_carries_the_pdf_and_the_options() {
let pdf: Vec<u8> = b"%PDF-1.7 fake print job\n".iter().copied().cycle().take(1 << 20).collect();
let job = spool::Job {
printer: Some("Office".into()),
copies: 2,
collate: false,
duplex: Some(spool::Duplex::LongEdge),
grayscale: true,
scaling: spool::Scaling::ShrinkToFit,
title: "memo.pdf".into(),
..Job::default()
};
let fake = FakeCups::on_tcp(vec![http_reply(&ipp_reply(
0x0000,
&[&group(0x01), &group(0x02), &attr(0x21, "job-id", &12u32.to_be_bytes()), &attr(0x23, "job-state", &[3u8])],
))])
.unwrap();
let message = ipp::print_job_at(fake.endpoint(), &pdf, &job).unwrap();
assert_eq!(message, "request id is Office-12", "the same message lp prints");
let taken = fake.request().unwrap();
let request = ipp_body(&taken).unwrap();
assert_eq!(&request[..4], &[1, 1, 0x00, 0x02], "IPP 1.1, Print-Job");
assert!(has(request, b"ipp://localhost/printers/Office"));
let mut copies = group(0x02);
copies.extend(attr(0x21, "copies", &2u32.to_be_bytes()));
assert!(has(request, &copies), "copies are a job attribute");
assert!(has(request, &attr(0x22, "collate", &[0])));
assert!(has(request, &attr(0x44, "sides", b"two-sided-long-edge")));
assert!(has(request, &attr(0x44, "print-color-mode", b"monochrome")));
assert!(has(request, &attr(0x44, "print-scaling", b"auto-fit")));
assert!(has(request, &attr(0x49, "document-format", b"application/pdf")));
assert!(has(request, &attr(0x42, "job-name", b"memo.pdf")));
assert!(request.ends_with(&pdf), "the whole job is the document data");
}
#[test]
fn the_default_printer_is_used_when_the_job_has_none() {
let fake = FakeCups::on_tcp(vec![
http_reply(&ipp_reply(0x0000, &[&group(0x01), &group(0x04), &printer_name("Office")])),
http_reply(&ipp_reply(0x0000, &[&group(0x01), &group(0x02), &attr(0x21, "job-id", &7u32.to_be_bytes())])),
])
.unwrap();
let message = ipp::print_job_at(fake.endpoint(), b"%PDF-1.7\n", &Job::default()).unwrap();
assert_eq!(message, "request id is Office-7");
let default = fake.request().unwrap();
assert_eq!(&ipp_body(&default).unwrap()[..4], &[1, 1, 0x40, 0x01], "the default comes from CUPS-Get-Default");
let taken = fake.request().unwrap();
assert!(has(ipp_body(&taken).unwrap(), b"ipp://localhost/printers/Office"), "the resolved default is the target");
}
#[test]
fn a_default_outside_the_queue_list_still_gets_its_marker() {
let fake = FakeCups::on_unix(vec![
http_reply(&ipp_reply(0x0000, &[&group(0x01), &group(0x04), &printer_name("Office_Laser")])),
http_reply(&ipp_reply(0x0000, &[&group(0x01), &group(0x04), &printer_name("Label_Writer")])),
])
.unwrap();
let printers = ipp::printers_at(fake.endpoint()).unwrap();
assert_eq!(
printers,
[entry("Office_Laser", false), entry("Label_Writer", true)],
"the default joins the list, so the dialog has a selection to restore"
);
}
#[test]
fn no_default_printer_is_an_error_when_the_job_names_none() {
let fake = FakeCups::on_unix(vec![http_reply(&ipp_reply(0x0000, &[&group(0x01)]))]).unwrap();
let err = ipp::print_job_at(fake.endpoint(), b"%PDF-1.7\n", &Job::default()).unwrap_err();
assert!(err.to_string().contains("no default printer"), "{err}");
}
#[test]
fn a_printer_name_that_cannot_be_a_uri_path_is_refused() {
let fake = FakeCups::on_tcp(vec![]).unwrap();
let mut long = "x".repeat(257);
long.push('y');
for name in ["Office (east)", "../../admin", "", "a b", "Brother/HL", "Копир", long.as_str()] {
let job = spool::Job { printer: Some(name.into()), ..Job::default() };
assert_eq!(
ipp::print_job_at(fake.endpoint(), b"pdf", &job),
Err(spool::Error::Spool(format!("not a printer name: {name}"))),
"{name:?} cannot go in the printer URI's path"
);
}
}
#[test]
fn an_ipp_refusal_is_an_error_that_names_the_problem() {
let fake = FakeCups::on_tcp(vec![http_reply(&ipp_reply(0x0506, &[&group(0x01)]))]).unwrap();
let job = spool::Job { printer: Some("Office".into()), ..Job::default() };
assert_eq!(
ipp::print_job_at(fake.endpoint(), b"%PDF-1.7\n", &job),
Err(spool::Error::Spool("the print server refused the request (the printer is not accepting jobs)".into()))
);
}
#[test]
fn malformed_replies_are_errors_never_a_panic() {
let bodies: Vec<(&str, Vec<u8>)> = vec![
// Shorter than an IPP header.
("shorter than an IPP header", vec![1, 1, 0]),
// A reply that ends inside an attribute: the name is announced, the value never comes.
("cut inside an attribute", vec![1, 1, 0, 0, 0, 0, 0, 1, 0x04, 0x42, 0x00, 0x20, b'p']),
// A value tag the registry does not know.
("unknown value tag", vec![1, 1, 0, 0, 0, 0, 0, 1, 0x04, 0xFF, 0x00, 0x00, 0x00, 0x00]),
// A collection, which the attributes asked for never are.
("collection", vec![1, 1, 0, 0, 0, 0, 0, 1, 0x04, 0x34, 0x00, 0x00, 0x00, 0x00]),
// A group tag that is no delimiter in the registry.
("reserved delimiter", vec![1, 1, 0, 0, 0, 0, 0, 1, 0x06]),
// A length within the cap that runs past the reply, and one past the cap.
("length past the reply", vec![1, 1, 0, 0, 0, 0, 0, 1, 0x04, 0x42, 0x00, 0xFE, b'p']),
("length past the cap", vec![1, 1, 0, 0, 0, 0, 0, 1, 0x04, 0x42, 0xFF, 0xFF, b'p']),
// No end of attributes before the body runs out.
("no end of attributes", vec![1, 1, 0, 0, 0, 0, 0, 1, 0x04, 0x42, 0x00, 0x01, b'x']),
];
for (why, body) in bodies {
let fake = FakeCups::on_unix(vec![http_reply(&body)]).unwrap();
let result = ipp::printers_at(fake.endpoint());
assert!(result.is_err(), "{why}: the reply must be an error, not a panic or a success");
}
}
#[test]
fn http_replies_that_cannot_carry_an_answer_are_refused() {
let replies: Vec<(&str, Vec<u8>)> = vec![
("requires authentication", b"HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n".to_vec()),
("demands a TLS upgrade", b"HTTP/1.1 426 Upgrade Required\r\nContent-Length: 0\r\n\r\n".to_vec()),
("chunked", b"HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n25\r\nthe body is chunked\r\n0\r\n\r\n".to_vec()),
("no Content-Length", b"HTTP/1.1 200 OK\r\nContent-Type: application/ipp\r\n\r\n".to_vec()),
("Content-Length past the cap", b"HTTP/1.1 200 OK\r\nContent-Length: 99999999\r\n\r\n".to_vec()),
("unreadable status line", b"not HTTP at all\r\n\r\n".to_vec()),
];
for (why, reply) in replies {
let fake = FakeCups::on_unix(vec![reply]).unwrap();
let result = ipp::post(&[fake.server], "/", b"ignored", TIMEOUT, true);
assert!(result.is_err(), "{why}: the reply must be an error, not a panic or a success");
}
// A server that takes the request and hangs up.
let fake = FakeCups::on_unix(vec![]).unwrap();
assert!(ipp::post(&[fake.server], "/", b"ignored", TIMEOUT, true).is_err(), "a hang-up is an error");
}
#[test]
fn a_server_that_answers_is_reachable_and_silence_is_not() {
let fake = FakeCups::on_unix(vec![]).unwrap();
assert!(ipp::reachable(&fake.server), "a unix socket that accepts connections is reachable");
let fake = FakeCups::on_tcp(vec![]).unwrap();
assert!(ipp::reachable(&fake.server), "a loopback port that accepts connections is reachable");
let absent = Server::Unix("/nonexistent/craft-print-test.sock".into());
assert!(!ipp::reachable(&absent), "a socket nothing listens on is not reachable");
let addr = {
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
listener.local_addr().unwrap()
};
assert!(!ipp::reachable(&Server::Tcp(addr)), "a port nothing listens on is not reachable");
}
#[test]
fn chunked_reply_is_bounded_and_rejects_ambiguous_framing() {
let good = b"HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n3\r\nabc\r\n2\r\nde\r\n0\r\n\r\n";
assert_eq!(super::read_reply(&mut &good[..]).unwrap(), b"abcde");
for bad in [
b"HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\nContent-Length: 0\r\n\r\n0\r\n\r\n".as_slice(),
b"HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n100001\r\n",
b"HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n3\r\na",
b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\nContent-Length: 0\r\n\r\n",
] {
assert!(super::read_reply(&mut &bad[..]).is_err());
}
}
#[test]
fn explicit_server_rejects_header_injection_and_malformed_port() {
for value in ["host\r\nInjected: yes", "host:0", "host:99999", "http://host", "user@host", ""] {
assert!(Server::parse(value).is_err(), "{value:?}");
}
assert_eq!(Server::parse("[::1]:631").unwrap().authority(), "[::1]:631");
assert_eq!(Server::parse("print.example:8631").unwrap().authority(), "print.example:8631");
}
#[test]
fn class_submission_preserves_authority_user_and_numeric_job_id() {
let fake = FakeCups::on_tcp(vec![http_reply(&ipp_reply(0, &[&group(2), &attr(0x21, "job-id", &42u32.to_be_bytes())]))]).unwrap();
let destination = super::Destination { name: "Studio".into(), is_class: true };
assert_eq!(super::submit_as_at(fake.endpoint(), &destination, b"pdf", &Job::default(), "artist").unwrap(), 42);
let request = fake.request().unwrap();
assert!(has(&request, b"POST /classes/Studio HTTP/1.1"));
assert!(has(&request, format!("Host: {}", fake.server.authority()).as_bytes()));
assert!(has(ipp_body(&request).unwrap(), format!("ipp://{}/classes/Studio", fake.server.authority()).as_bytes()));
assert!(has(ipp_body(&request).unwrap(), &attr(0x42, "requesting-user-name", b"artist")));
}
#[test]
fn uncertain_submission_never_tries_the_second_endpoint() {
let first = FakeCups::on_tcp(vec![]).unwrap();
let second = FakeCups::on_tcp(vec![]).unwrap();
let destination = super::Destination { name: "Studio".into(), is_class: false };
assert!(super::submit_at(&[first.server.clone(), second.server.clone()], &destination, b"pdf", &Job::default()).is_err());
let _ = first.request().unwrap();
assert!(second.requests.recv_timeout(Duration::from_millis(100)).is_err());
}
#[test]
fn queue_metadata_stays_with_its_printer_group() {
let bytes = ipp_reply(
0,
&[
&group(4),
&attr(0x41, "printer-info", b"Studio printer"),
&printer_name("First"),
&attr(0x23, "printer-state", &5u32.to_be_bytes()),
&attr(0x22, "printer-is-accepting-jobs", &[0]),
&group(4),
&printer_name("Second"),
],
);
let reply = super::parse_reply(&bytes).unwrap();
assert_eq!(reply.queues.len(), 2);
assert_eq!(reply.queues[0].info, "Studio printer");
assert_eq!(reply.queues[0].state, 5);
assert!(!reply.queues[0].accepting_jobs);
assert!(reply.queues[1].info.is_empty());
assert!(reply.queues[1].accepting_jobs);
}
#[test]
fn reply_identity_and_metadata_request_are_checked() {
let request = super::discovery_request(0x4002);
assert!(has(&request, b"printer-info"));
let mut reply = vec![1, 1, 0, 0];
reply.extend_from_slice(&request[4..8]);
reply.push(3);
assert!(super::validate_reply_identity(&request, &reply).is_ok());
reply[7] ^= 1;
assert!(super::validate_reply_identity(&request, &reply).is_err());
reply[4..8].copy_from_slice(&request[4..8]);
reply[0] = 9;
assert!(super::validate_reply_identity(&request, &reply).is_err());
}
#[test]
fn slow_reply_cannot_reset_the_absolute_deadline() {
let (client, mut peer) = std::os::unix::net::UnixStream::pair().unwrap();
let producer = std::thread::spawn(move || {
// Finite work and a joined handle: no abandoned timeout worker.
for _ in 0..20 {
if peer.write_all(b"x").is_err() {
break;
}
std::thread::sleep(Duration::from_millis(20));
}
});
let start = std::time::Instant::now();
let mut stream = super::Stream::Unix(client);
let mut reader = super::DeadlineReader { stream: &mut stream, end: start + Duration::from_millis(80) };
let mut bytes = [0; 20];
assert!(reader.read_exact(&mut bytes).is_err(), "trickle reads must not extend the absolute deadline");
drop(stream);
producer.join().unwrap();
assert!(start.elapsed() < Duration::from_secs(3));
}
#[test]
fn blocked_upload_obeys_the_same_absolute_deadline() {
let (client, _peer) = std::os::unix::net::UnixStream::pair().unwrap();
let start = std::time::Instant::now();
let mut stream = super::Stream::Unix(client);
let mut writer = super::DeadlineReader { stream: &mut stream, end: start + Duration::from_millis(80) };
let chunk = [0u8; 64 * 1024];
let mut timed_out = false;
// A peer that never drains cannot turn each partial write into a fresh timeout budget.
for _ in 0..512 {
if writer.write_all(&chunk).is_err() {
timed_out = true;
break;
}
}
assert!(timed_out, "blocked upload must terminate without a reader");
assert!(start.elapsed() < Duration::from_secs(3));
}
#[test]
fn recorded_request_body_requires_complete_http_headers() {
assert!(ipp_body(b"POST / HTTP/1.1\r\n").is_none());
assert_eq!(ipp_body(b"POST / HTTP/1.1\r\n\r\nbody"), Some(b"body".as_slice()));
}
#[test]
fn named_destinations_encode_one_path_segment_on_both_wire_fields() {
for is_class in [false, true] {
let fake = FakeCups::on_tcp(vec![http_reply(&ipp_reply(0, &[&group(2), &attr(0x21, "job-id", &42u32.to_be_bytes())]))]).unwrap();
let destination = super::Destination { name: "Office café%20?#".into(), is_class };
assert_eq!(super::submit_as_at(fake.endpoint(), &destination, b"pdf", &Job::default(), "artist").unwrap(), 42);
let kind = if is_class { "classes" } else { "printers" };
let path = format!("/{kind}/Office%20caf%C3%A9%2520%3F%23");
let request = fake.request().unwrap();
assert!(has(&request, format!("POST {path} HTTP/1.1").as_bytes()));
assert!(has(ipp_body(&request).unwrap(), format!("ipp://{}{path}", fake.server.authority()).as_bytes()));
}
}
#[test]
fn destination_path_rejects_routing_syntax_before_connecting() {
for name in ["", ".", "..", "../admin", "a/b", "a\\b", "a\r\nb", "a\0b"] {
let destination = super::Destination { name: name.into(), is_class: false };
assert!(super::destination_path(&destination).is_err(), "{name:?}");
}
let destination = super::Destination { name: "x".repeat(257), is_class: false };
assert!(super::destination_path(&destination).is_err());
}
#[test]
fn separate_queue_query_preserves_optional_discovery_errors() {
let fake = FakeCups::on_tcp(vec![http_reply(&ipp_reply(0x0403, &[&group(1)]))]).unwrap();
assert!(super::queues_at(fake.endpoint(), true).is_err(), "authorization refusal is not an empty class list");
let fake = FakeCups::on_tcp(vec![http_reply(&ipp_reply(0x0501, &[&group(1)]))]).unwrap();
assert!(super::queues_at(fake.endpoint(), true).unwrap().is_empty(), "unsupported class operation is absent");
let fake = FakeCups::on_tcp(vec![http_reply(&ipp_reply(0, &[&group(1), &group(4), &printer_name("Pool")]))]).unwrap();
let queues = super::queues_at(fake.endpoint(), true).unwrap();
assert_eq!(queues.len(), 1);
assert!(queues[0].is_class);
assert!(!queues[0].is_default, "default resolution is caller-owned for this API");
let request = fake.request().unwrap();
assert_eq!(&ipp_body(&request).unwrap()[..4], &[1, 1, 0x40, 0x05]);
}
#[test]
fn ipv6_endpoint_keeps_scope_for_resolution_and_escapes_wire_authority() {
assert_eq!(Server::parse("[::1]").unwrap().authority(), "[::1]:631");
assert_eq!(Server::parse("::1").unwrap().authority(), "[::1]:631");
let scoped = Server::parse("[fe80::1%en0]:8631").unwrap();
assert!(matches!(&scoped, Server::Named(host, 8631) if host == "fe80::1%en0"));
assert_eq!(scoped.authority(), "[fe80::1%25en0]:8631");
assert_eq!(Server::parse("fe80::1%en0:8631").unwrap().authority(), scoped.authority());
assert_eq!(Server::parse("fe80::1%en0").unwrap().authority(), "[fe80::1%25en0]:631");
assert!(Server::parse("[host]:631").is_err());
assert_eq!(super::connect(&Server::Named("/invalid".into(), 631)).err().unwrap().kind(), std::io::ErrorKind::InvalidInput);
for bad in ["[::1]junk", "[::1]:0", "[::1]:abc", "[fe80::1%]:631", "[fe80::1%x%y]:631", "host%zone"] {
assert!(Server::parse(bad).is_err(), "{bad}");
}
}
#[test]
fn long_printer_descriptions_are_not_limited_like_queue_names() {
let description = "Studio ".repeat(200);
let body = ipp_reply(0, &[&group(1), &group(4), &printer_name("Studio"), &attr(0x41, "printer-info", description.as_bytes())]);
let parsed = super::parse_reply(&body).unwrap();
assert_eq!(parsed.queues[0].info, description);
}
#[test]
fn destination_limit_is_explicit_and_never_silently_truncates() {
let mut body = vec![1, 1, 0, 0, 0, 0, 0, 1];
for index in 0..super::MAX_PRINTERS {
body.push(4);
body.extend(printer_name(&format!("Printer{index}")));
}
body.push(3);
assert_eq!(super::parse_reply(&body).unwrap().queues.len(), super::MAX_PRINTERS);
assert_eq!(body.pop(), Some(3));
body.push(4);
body.extend(printer_name("OneTooMany"));
body.push(3);
assert!(super::parse_reply(&body).err().unwrap().to_string().contains("too many CUPS destinations"));
}
#[test]
fn closed_unix_peer_keeps_its_buffered_reply_readable_with_a_deadline() {
let (client, mut peer) = std::os::unix::net::UnixStream::pair().unwrap();
let body = ipp_reply(0, &[&group(1), &group(4), &printer_name("Studio")]);
peer.write_all(&http_reply(&body)).unwrap();
drop(peer);
let mut stream = super::Stream::Unix(client);
let mut reader = super::DeadlineReader { stream: &mut stream, end: std::time::Instant::now() + Duration::from_secs(1) };
assert_eq!(super::read_reply(&mut reader).unwrap(), body);
let mut byte = [0];
assert_eq!(reader.read(&mut byte).unwrap(), 0);
reader.end = std::time::Instant::now();
assert_eq!(reader.read(&mut byte).unwrap_err().kind(), std::io::ErrorKind::TimedOut);
}
#[test]
fn stalled_unix_peer_still_fails_within_the_absolute_read_deadline() {
let (client, _peer) = std::os::unix::net::UnixStream::pair().unwrap();
let start = std::time::Instant::now();
let mut stream = super::Stream::Unix(client);
let mut reader = super::DeadlineReader { stream: &mut stream, end: start + Duration::from_millis(80) };
let mut byte = [0];
let error = reader.read(&mut byte).unwrap_err();
assert!(matches!(error.kind(), std::io::ErrorKind::TimedOut | std::io::ErrorKind::WouldBlock));
assert!(start.elapsed() < Duration::from_secs(3));
}
+4
View File
@@ -8,6 +8,10 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
/// Direct local-CUPS transport, independent of command-line spooler selection.
#[cfg(not(target_arch = "wasm32"))]
pub mod cups;
#[cfg(any(test, windows))]
mod progress;
#[cfg(any(test, windows))]
+230
View File
@@ -0,0 +1,230 @@
//! Bounded, borrowed views and serialization of PSD global `Anno` records.
//!
//! Framing follows PhotoCraft's annotation reader (Brandon Thomas, aa87012a), with
//! David Mann's minimum-length guard and the per-entry span fix from PhotoCraft
//! #11138. Coordinates, colour conversion, text decoding and popup defaults are
//! deliberately caller policy. Unknown records can be carried through byte-exact.
use crate::{PsdError, Result};
/// Explicit limits shared by readers and writers.
#[derive(Clone, Copy, Debug)]
pub struct Limits {
/// Maximum complete block size.
pub bytes: usize,
/// Maximum annotation count.
pub records: usize,
}
impl Default for Limits {
fn default() -> Self {
Self { bytes: 16 * 1024 * 1024, records: 4096 }
}
}
struct Reader<'a> {
d: &'a [u8],
p: usize,
}
impl<'a> Reader<'a> {
fn take(&mut self, n: usize) -> Result<&'a [u8]> {
let end = self.p.checked_add(n).ok_or(PsdError::LimitExceeded("annotation offset"))?;
let s = self.d.get(self.p..end).ok_or(PsdError::UnexpectedEof { offset: self.p, needed: n })?;
self.p = end;
Ok(s)
}
fn u8(&mut self) -> Result<u8> {
Ok(self.take(1)?.first().copied().unwrap_or_default())
}
fn u16(&mut self) -> Result<u16> {
Ok(u16::from_be_bytes(self.take(2)?.try_into().map_err(|_| PsdError::invalid("annotation u16"))?))
}
fn u32(&mut self) -> Result<u32> {
Ok(u32::from_be_bytes(self.take(4)?.try_into().map_err(|_| PsdError::invalid("annotation u32"))?))
}
fn key(&mut self) -> Result<[u8; 4]> {
self.take(4)?.try_into().map_err(|_| PsdError::invalid("annotation key"))
}
fn rect(&mut self) -> Result<[i32; 4]> {
Ok([self.u32()? as i32, self.u32()? as i32, self.u32()? as i32, self.u32()? as i32])
}
fn pascal(&mut self) -> Result<&'a [u8]> {
let n = usize::from(self.u8()?);
let bytes = self.take(n)?;
if (n + 1) % 2 == 1 {
self.take(1)?;
}
Ok(bytes)
}
}
/// A borrowed record, including its original length, padding and unknown fields.
#[derive(Clone, Copy, Debug)]
pub struct Record<'a> {
raw: &'a [u8],
}
impl<'a> Record<'a> {
/// Complete self-counting record, suitable for lossless passthrough.
pub fn raw(&self) -> &'a [u8] {
self.raw
}
/// Parse text records; other record kinds remain opaque.
pub fn text(&self) -> Result<Option<Text<'a>>> {
let mut r = Reader { d: self.raw, p: 4 };
if r.key()? != *b"txtA" {
return Ok(None);
}
// Never read beyond this record, even if a text length points into its neighbour.
let open = r.u8()?;
let flags = r.u8()?;
let optional_blocks = r.u16()?;
let icon = r.rect()?;
let popup = r.rect()?;
let color_space = r.u16()?;
let color = [r.u16()?, r.u16()?, r.u16()?, r.u16()?];
let author = r.pascal()?;
let name = r.pascal()?;
let modified = r.pascal()?;
let data_length = r.u32()?;
let data_key = r.key()?;
let size = usize::try_from(r.u32()?).map_err(|_| PsdError::LimitExceeded("annotation text"))?;
let data = r.take(size)?;
Ok(Some(Text { open, flags, optional_blocks, icon, popup, color_space, color, author, name, modified, data_length, data_key, data }))
}
}
/// Wire-level text annotation. Text payload and Pascal strings remain bytes.
/// No text normalisation or application colour/coordinate policy is applied.
#[derive(Clone, Copy, Debug)]
pub struct Text<'a> {
/// Open state byte.
pub open: u8,
/// Flags byte.
pub flags: u8,
/// Optional block flags.
pub optional_blocks: u16,
/// Icon rectangle, top/left/bottom/right.
pub icon: [i32; 4],
/// Popup rectangle, top/left/bottom/right.
pub popup: [i32; 4],
/// PSD colour space.
pub color_space: u16,
/// Raw colour components.
pub color: [u16; 4],
/// Pascal author bytes, maximum 255.
pub author: &'a [u8],
/// Pascal name bytes, maximum 255.
pub name: &'a [u8],
/// Pascal modification-date bytes, maximum 255.
pub modified: &'a [u8],
/// Original self-counting data length, exposed for diagnostics.
/// The writer recomputes this field.
pub data_length: u32,
/// Usually `txtC`; retained without imposing application policy.
pub data_key: [u8; 4],
/// Payload, including any text byte-order mark.
pub data: &'a [u8],
}
/// Parse complete framing before exposing records. Borrowed payloads do not allocate.
/// Trailing block bytes are accepted as in the existing PhotoCraft reader.
pub fn read(data: &[u8], limits: Limits) -> Result<Vec<Record<'_>>> {
if data.len() > limits.bytes {
return Err(PsdError::LimitExceeded("annotation bytes"));
}
let mut r = Reader { d: data, p: 0 };
r.u16()?;
r.u16()?;
let count = usize::try_from(r.u32()?).map_err(|_| PsdError::LimitExceeded("annotation count"))?;
if count > limits.records || count > data.len().saturating_sub(8) / 8 {
return Err(PsdError::LimitExceeded("annotation count"));
}
let mut out = Vec::new();
out.try_reserve_exact(count).map_err(|_| PsdError::OutOfMemory("annotation records"))?;
for _ in 0..count {
let start = r.p;
let len = usize::try_from(r.u32()?).map_err(|_| PsdError::LimitExceeded("annotation length"))?;
// David Mann's zero-length guard: a self-counting record must advance.
if len < 8 {
return Err(PsdError::invalid("annotation record shorter than its header"));
}
r.p = start;
let record = Record { raw: r.take(len)? };
record.text()?; // validate text spans, including data borrowed by later consumers
out.push(record);
}
Ok(out)
}
fn append(out: &mut Vec<u8>, bytes: &[u8], limit: usize) -> Result<()> {
let len = out.len().checked_add(bytes.len()).ok_or(PsdError::LimitExceeded("annotation bytes"))?;
if len > limit {
return Err(PsdError::LimitExceeded("annotation bytes"));
}
out.try_reserve(bytes.len()).map_err(|_| PsdError::OutOfMemory("annotation bytes"))?;
out.extend_from_slice(bytes);
Ok(())
}
fn pascal(out: &mut Vec<u8>, bytes: &[u8], limit: usize) -> Result<()> {
let n = u8::try_from(bytes.len()).map_err(|_| PsdError::LimitExceeded("annotation Pascal string"))?;
append(out, &[n], limit)?;
append(out, bytes, limit)?;
if (bytes.len() + 1) % 2 == 1 {
append(out, &[0], limit)?;
}
Ok(())
}
/// Serialize one text record, computing both length fields. Caller supplies raw
/// text bytes and already-mapped colour/coordinates; nothing is truncated.
pub fn write_text(text: &Text<'_>, limits: Limits) -> Result<Vec<u8>> {
let mut out = Vec::new();
append(&mut out, &[0; 4], limits.bytes)?;
append(&mut out, b"txtA", limits.bytes)?;
append(&mut out, &[text.open, text.flags], limits.bytes)?;
append(&mut out, &text.optional_blocks.to_be_bytes(), limits.bytes)?;
for value in text.icon.into_iter().chain(text.popup) {
append(&mut out, &value.to_be_bytes(), limits.bytes)?;
}
append(&mut out, &text.color_space.to_be_bytes(), limits.bytes)?;
for value in text.color {
append(&mut out, &value.to_be_bytes(), limits.bytes)?;
}
for value in [text.author, text.name, text.modified] {
pascal(&mut out, value, limits.bytes)?;
}
let n = u32::try_from(text.data.len()).map_err(|_| PsdError::LimitExceeded("annotation text"))?;
let data_length = n.checked_add(12).ok_or(PsdError::LimitExceeded("annotation data length"))?;
append(&mut out, &data_length.to_be_bytes(), limits.bytes)?;
append(&mut out, &text.data_key, limits.bytes)?;
append(&mut out, &n.to_be_bytes(), limits.bytes)?;
append(&mut out, text.data, limits.bytes)?;
let len = u32::try_from(out.len()).map_err(|_| PsdError::LimitExceeded("annotation record length"))?;
out.get_mut(..4).ok_or_else(|| PsdError::invalid("annotation header"))?.copy_from_slice(&len.to_be_bytes());
Ok(out)
}
/// Combine already-framed records into a version 2.1 block. Unknown record types
/// are preserved byte-exact; malformed text records are refused.
pub fn write(records: &[&[u8]], limits: Limits) -> Result<Vec<u8>> {
if records.len() > limits.records {
return Err(PsdError::LimitExceeded("annotation count"));
}
let count = u32::try_from(records.len()).map_err(|_| PsdError::LimitExceeded("annotation count"))?;
let mut out = Vec::new();
append(&mut out, &[0, 2, 0, 1], limits.bytes)?;
append(&mut out, &count.to_be_bytes(), limits.bytes)?;
for raw in records {
let mut r = Reader { d: raw, p: 0 };
let declared = usize::try_from(r.u32()?).map_err(|_| PsdError::LimitExceeded("annotation record length"))?;
if raw.len() < 8 || declared != raw.len() {
return Err(PsdError::invalid("annotation record length mismatch"));
}
Record { raw }.text()?;
append(&mut out, raw, limits.bytes)?;
}
Ok(out)
}
#[cfg(test)]
mod tests;
+117
View File
@@ -0,0 +1,117 @@
use super::*;
fn note() -> Text<'static> {
Text {
open: 1,
flags: 0x1c,
optional_blocks: 1,
icon: [10, 20, 30, 36],
popup: [30, 40, 190, 280],
color_space: 0,
color: [65535, 1000, 3000, 0],
author: b"Writer",
name: b"",
modified: b"2026",
data_length: 0,
data_key: *b"txtC",
data: &[0xfe, 0xff, 0, 65, 0, 13, 0, 66],
}
}
#[test]
fn text_and_unknown_sound_round_trip_without_copying_payloads() {
let limits = Limits::default();
let text = write_text(&note(), limits).unwrap();
let sound = [0, 0, 0, 11, b's', b'n', b'd', b'A', 42, 3, 9];
let block = write(&[&text, &sound], limits).unwrap();
let parsed = read(&block, limits).unwrap();
assert_eq!(parsed.len(), 2);
let view = parsed[0].text().unwrap().unwrap();
assert_eq!(view.author, note().author);
assert_eq!(view.data, note().data);
assert_eq!(view.icon, note().icon);
assert_eq!(view.color, note().color);
assert_eq!(view.data_length, 20);
assert!(parsed[1].text().unwrap().is_none());
assert_eq!(parsed[1].raw(), sound);
let slices: Vec<_> = parsed.iter().map(Record::raw).collect();
assert_eq!(write(&slices, limits).unwrap(), block);
assert!(view.data.as_ptr() >= block.as_ptr());
assert!(view.data.as_ptr() < block.as_ptr().wrapping_add(block.len()));
}
#[test]
fn text_cannot_read_past_the_declared_entry_into_its_neighbour() {
// Regression from PhotoCraft #11138, without its app Note/Color policy.
let mut record = write_text(&note(), Limits::default()).unwrap();
let shortened = record.len() - note().data.len();
record[..4].copy_from_slice(&(shortened as u32).to_be_bytes());
let mut block = vec![0, 2, 0, 1, 0, 0, 0, 1];
block.extend_from_slice(&record);
assert!(read(&block, Limits::default()).is_err());
assert!(write(&[&record], Limits::default()).is_err());
}
#[test]
fn truncation_and_hostile_counts_lengths_fail_closed() {
let record = write_text(&note(), Limits::default()).unwrap();
let block = write(&[&record], Limits::default()).unwrap();
for end in 0..block.len() {
assert!(read(&block[..end], Limits::default()).is_err(), "{end}");
}
for len in [0u32, 1, 7, u32::MAX] {
let mut bad = block.clone();
bad[8..12].copy_from_slice(&len.to_be_bytes());
assert!(read(&bad, Limits::default()).is_err());
}
let mut bad = block;
bad[4..8].copy_from_slice(&u32::MAX.to_be_bytes());
assert!(read(&bad, Limits::default()).is_err());
}
#[test]
fn explicit_limits_and_pascal_length_are_not_silently_truncated() {
let record = write_text(&note(), Limits::default()).unwrap();
let block = write(&[&record], Limits::default()).unwrap();
assert!(read(&block, Limits { records: 0, ..Limits::default() }).is_err());
assert!(read(&block, Limits { bytes: block.len() - 1, ..Limits::default() }).is_err());
assert!(write(&[&record], Limits { records: 0, ..Limits::default() }).is_err());
assert!(write_text(&note(), Limits { bytes: record.len() - 1, ..Limits::default() }).is_err());
let long = [0; 256];
let mut text = note();
text.author = &long;
assert!(write_text(&text, Limits::default()).is_err());
}
#[test]
fn preserves_legacy_version_and_unused_data_header_acceptance() {
let record = write_text(&note(), Limits::default()).unwrap();
let mut block = write(&[&record], Limits::default()).unwrap();
block[..4].copy_from_slice(&[0, 9, 0, 8]);
block.extend_from_slice(b"trailing");
assert_eq!(read(&block, Limits::default()).unwrap()[0].raw(), record);
}
#[test]
fn canonical_layout_matches_the_existing_photocraft_writer() {
// PhotoCraft annotations_map::write_note layout (Brandon Thomas, aa87012a).
// App RGB/position/text conversion happens before this shared wire writer.
let n = note();
let mut expected = vec![0, 0, 0, 0];
expected.extend_from_slice(b"txtA");
expected.extend_from_slice(&[1, 0x1c, 0, 1]);
for value in [10i32, 20, 30, 36, 30, 40, 190, 280] {
expected.extend_from_slice(&value.to_be_bytes());
}
for value in [0u16, 65535, 1000, 3000, 0] {
expected.extend_from_slice(&value.to_be_bytes());
}
expected.extend_from_slice(b"\x06Writer\x00\x00\x00\x042026\x00");
expected.extend_from_slice(&20u32.to_be_bytes());
expected.extend_from_slice(b"txtC");
expected.extend_from_slice(&8u32.to_be_bytes());
expected.extend_from_slice(n.data);
let len = expected.len() as u32;
expected[..4].copy_from_slice(&len.to_be_bytes());
assert_eq!(write_text(&n, Limits::default()).unwrap(), expected);
}
+116
View File
@@ -0,0 +1,116 @@
//! Bounded two-plane PSD Displace (`DspD`) payloads.
//! App filter settings, image conversion and external-path policy belong to the caller.
//! Ported from PhotoCraft `crates/io/src/displace_map.rs` (MIT/Apache-2.0).
const HEADER: usize = 10;
const MODE_TWO_PLANES: u16 = 3;
/// Maximum supported decoded pixel count (8K by 8K).
pub const MAX_MAP_PIXELS: usize = 1 << 26;
/// A parsed embedded map: size and the two 8-bit planes (borrowed from the blob).
#[derive(Debug, PartialEq)]
pub struct EmbeddedMap<'a> {
/// Width in pixels.
pub width: usize,
/// Height in pixels.
pub height: usize,
/// Horizontal displacement samples.
pub horizontal: &'a [u8],
/// Vertical displacement samples.
pub vertical: &'a [u8],
}
/// Parses an embedded displacement map; `None` for any other mode, a zero or oversized map, or a
/// blob shorter than the header plus both planes.
pub fn parse_map(data: &[u8]) -> Option<EmbeddedMap<'_>> {
let u32_at = |i: usize| Some(u32::from_le_bytes(data.get(i..i + 4)?.try_into().ok()?));
let height = usize::try_from(u32_at(0)?).ok()?;
let width = usize::try_from(u32_at(4)?).ok()?;
let mode = u16::from_le_bytes(data.get(8..HEADER)?.try_into().ok()?);
let n = width.checked_mul(height)?;
if mode != MODE_TWO_PLANES || n == 0 || n > MAX_MAP_PIXELS {
return None;
}
let horizontal = data.get(HEADER..HEADER.checked_add(n)?)?;
let vertical = data.get(HEADER + n..HEADER.checked_add(n.checked_mul(2)?)?)?;
Some(EmbeddedMap { width, height, horizontal, vertical })
}
/// Writes a mode-3 payload from exact-sized 8-bit planes, without padding.
/// Returns `None` for empty/oversized dimensions, mismatched planes or allocation failure.
/// Callers retain their own (possibly lower) embedding and image-conversion budgets.
pub fn write_map(width: usize, height: usize, horizontal: &[u8], vertical: &[u8]) -> Option<Vec<u8>> {
write_map_iter(width, height, horizontal.iter().copied(), vertical.iter().copied())
}
/// Writes exact-sized sample iterators without allocating intermediate planes.
/// Iterators must terminate after exactly width times height samples; extra or missing
/// samples are rejected. At most that many samples plus one are consumed per plane.
pub fn write_map_iter(
width: usize,
height: usize,
mut horizontal: impl Iterator<Item = u8>,
mut vertical: impl Iterator<Item = u8>,
) -> Option<Vec<u8>> {
let n = width.checked_mul(height)?;
if n == 0 || n > MAX_MAP_PIXELS {
return None;
}
let width = u32::try_from(width).ok()?;
let height = u32::try_from(height).ok()?;
let len = HEADER.checked_add(n.checked_mul(2)?)?;
let mut out = Vec::new();
out.try_reserve_exact(len).ok()?;
out.extend_from_slice(&height.to_le_bytes());
out.extend_from_slice(&width.to_le_bytes());
out.extend_from_slice(&MODE_TWO_PLANES.to_le_bytes());
for samples in [&mut horizontal as &mut dyn Iterator<Item = u8>, &mut vertical] {
for _ in 0..n {
out.push(samples.next()?);
}
if samples.next().is_some() {
return None;
}
}
Some(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn exact_planes_roundtrip_and_padding_is_ignored() {
let mut bytes = write_map(2, 1, &[0, 255], &[128, 64]).unwrap();
assert_eq!(bytes, [1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 255, 128, 64]);
bytes.extend_from_slice(&[99, 88]);
let m = parse_map(&bytes).unwrap();
assert_eq!((m.width, m.height), (2, 1));
assert_eq!(m.horizontal, &[0, 255]);
assert_eq!(m.vertical, &[128, 64]);
}
#[test]
fn truncated_unsupported_and_overflow_are_rejected() {
let bytes = write_map(2, 1, &[0, 255], &[128, 64]).unwrap();
for end in 0..bytes.len() {
assert!(parse_map(&bytes[..end]).is_none());
}
let mut invalid = bytes.clone();
invalid[8] = 4;
assert!(parse_map(&invalid).is_none());
invalid[8] = 3;
invalid[..8].fill(255);
assert!(parse_map(&invalid).is_none());
invalid[..8].fill(0);
assert!(parse_map(&invalid).is_none());
invalid[..4].copy_from_slice(&1u32.to_le_bytes());
invalid[4..8].copy_from_slice(&((MAX_MAP_PIXELS + 1) as u32).to_le_bytes());
assert!(parse_map(&invalid).is_none());
assert!(write_map_iter(2, 1, std::iter::repeat(0), std::iter::repeat(0)).is_none());
assert!(write_map(usize::MAX, 2, &[], &[]).is_none());
assert!(write_map(MAX_MAP_PIXELS + 1, 1, &[], &[]).is_none());
assert!(write_map(2, 1, &[0], &[0, 0]).is_none());
assert!(write_map(2, 1, &[0, 0], &[0, 0, 0]).is_none());
}
}
+2
View File
@@ -54,6 +54,7 @@ pub mod aco;
pub mod act;
pub mod adjust;
pub mod animation;
pub mod annotations;
pub mod ase;
pub mod asl;
pub mod atn;
@@ -63,6 +64,7 @@ mod codepage;
pub mod compression;
pub mod csh;
pub mod descriptor;
pub mod displace_map;
pub mod engine_data;
pub mod error;
pub mod file;
+143 -20
View File
@@ -470,6 +470,55 @@ fn linked_file(item: &[u8], at: usize) -> Result<LinkedFile> {
Ok(out)
}
/// Header of an embedded (`liFD`) linked-layer item, without reading its payload.
/// Offsets are relative to the item (not its enclosing eight-byte length field).
/// A deferred reader can supply just the header, then validate the payload range
/// against the full record length before reading those bytes.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct EmbeddedFileHeader {
/// Lossy UTF-8 identifier, matching Photoshop metadata display semantics.
pub uuid: String,
/// Lossy UTF-16 filename with trailing NULs removed.
pub name: String,
/// Start of the payload within the item.
pub data_offset: usize,
/// Declared payload length; the payload need not be resident.
pub data_len: usize,
}
impl EmbeddedFileHeader {
/// Borrow the payload only when the supplied complete item contains it.
pub fn payload<'a>(&self, item: &'a [u8]) -> Option<&'a [u8]> {
item.get(self.data_offset..self.data_offset.checked_add(self.data_len)?)
}
}
/// Read an embedded item's header from a possibly partial/deferred item buffer.
/// This deliberately does not require its declared payload to be present. A malformed
/// header or a non-embedded item is an error, not an empty embedded file. Callers walking
/// framed records may continue to the next record after such an error.
/// Ported from PhotoCraft's linked-item reader; record versions remain forward-compatible.
pub fn embedded_file_header(item: &[u8]) -> Result<EmbeddedFileHeader> {
let mut r = Reader::new(item);
let kind = r.array::<4>()?;
let _version = r.u32()?;
let uuid = String::from_utf8_lossy(&read_pascal(&mut r, 1)?).into_owned();
// A filename is metadata, never an unbounded allocation. Check before decoding.
if r.clone().u32()? > 32_768 {
return Err(PsdError::LimitExceeded("linked filename exceeds 32768 UTF-16 units"));
}
let name = UnicodeString::read(&mut r)?.to_string_lossy();
r.skip(8)?; // file type and creator
let data_len = usize::try_from(r.u64()?).map_err(|_| PsdError::LimitExceeded("linked payload exceeds address space"))?;
if r.u8()? != 0 {
crate::descriptor::VersionedDescriptor::read(&mut r)?;
}
if kind != *b"liFD" {
return Err(PsdError::invalid("linked item is not embedded"));
}
Ok(EmbeddedFileHeader { uuid, name, data_offset: r.pos(), data_len })
}
/// The four-character file type Photoshop records for an embedded file, from its first bytes:
/// `8BPS` (`8BPB` for a PSB), `PNGf`, `JPEG`, `TIFF`, `GIFf`, or four spaces.
pub fn file_type(bytes: &[u8]) -> [u8; 4] {
@@ -519,7 +568,29 @@ pub struct LinkedRecord<'a> {
pub raw: &'a [u8],
}
impl LinkedRecord<'_> {
impl<'a> LinkedRecord<'a> {
/// The complete item, excluding framing and padding; absent for a damaged tail.
pub fn item(&self) -> Option<&'a [u8]> {
framed_record(self.raw).map(|(item, _)| item)
}
/// Copy this complete record under a new ID, leaving the payload byte-identical.
/// Selection policy belongs to the caller; malformed tails cannot be copied.
pub fn copy_with_uuid(&self, new_uuid: &str) -> Option<Vec<u8>> {
let item = self.item()?;
let old_end = 9usize.checked_add(usize::from(*item.get(8)?))?;
let new_len = u8::try_from(new_uuid.len()).ok()?;
let mut copy = item.get(..8)?.to_vec();
copy.push(new_len);
copy.extend_from_slice(new_uuid.as_bytes());
copy.extend_from_slice(item.get(old_end..)?);
let mut out = Vec::with_capacity(copy.len() + 11);
out.put_u64(copy.len() as u64);
out.extend(copy);
out.resize(out.len().next_multiple_of(4), 0);
Some(out)
}
/// The unique id as text, when it is readable and valid UTF-8.
pub fn uuid_str(&self) -> Option<&str> {
std::str::from_utf8(self.uuid?).ok()
@@ -545,17 +616,26 @@ fn record_uuid(item: &[u8]) -> Option<&[u8]> {
/// The records of a linked layer block's data, in order, each with its unique id when its header
/// is readable. A tail that is no complete record is returned as one record without an id.
pub fn linked_records(data: &[u8]) -> Vec<LinkedRecord<'_>> {
let mut out = Vec::new();
iter_linked_records(data).collect()
}
/// Stream the same raw views as [`linked_records`] without allocating a record list.
/// Complete frames with malformed inner headers do not hide subsequent frames;
/// an incomplete tail is yielded once with no identifier.
pub fn iter_linked_records(data: &[u8]) -> impl Iterator<Item = LinkedRecord<'_>> {
let mut rest = data;
while !rest.is_empty() {
std::iter::from_fn(move || {
if rest.is_empty() {
return None;
}
let Some((item, raw)) = framed_record(rest) else {
out.push(LinkedRecord { uuid: None, raw: rest });
break;
let tail = rest;
rest = &[];
return Some(LinkedRecord { uuid: None, raw: tail });
};
out.push(LinkedRecord { uuid: record_uuid(item), raw });
rest = rest.get(raw.len()..).unwrap_or_default();
}
out
Some(LinkedRecord { uuid: record_uuid(item), raw })
})
}
/// The unique ids of every record of a linked layer block's data that has a readable one.
@@ -653,18 +733,7 @@ pub fn contains_linked_record(data: &[u8], record: &[u8]) -> bool {
/// field and padding; the rest of the record (embedded, external or alias data) is kept.
pub fn copy_linked_record(data: &[u8], uuid: &str, new_uuid: &str) -> Option<Vec<u8>> {
let record = linked_records(data).into_iter().find(|r| r.uuid == Some(uuid.as_bytes()))?;
let (item, _) = framed_record(record.raw)?;
let old_end = 9usize.checked_add(usize::from(*item.get(8)?))?;
let new_len = u8::try_from(new_uuid.len()).ok()?;
let mut copy = item.get(..8)?.to_vec();
copy.push(new_len);
copy.extend_from_slice(new_uuid.as_bytes());
copy.extend_from_slice(item.get(old_end..)?);
let mut out = Vec::with_capacity(copy.len() + 11);
out.put_u64(copy.len() as u64);
out.extend(copy);
out.resize(out.len().next_multiple_of(4), 0);
Some(out)
record.copy_with_uuid(new_uuid)
}
impl PsdFile {
@@ -1111,3 +1180,57 @@ mod tests {
assert!(u64::from(w) * u64::from(h) <= MAX_BAKE_PIXELS);
}
}
#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod embedded_header_tests {
use super::*;
#[test]
fn headers_do_not_require_resident_payload() {
let data = encode_embedded_file("id", "a.psd", b"payload");
let record = iter_linked_records(&data).next().unwrap();
let item = record.item().unwrap();
let header = embedded_file_header(item).unwrap();
assert_eq!(header.uuid, "id");
assert_eq!(header.name, "a.psd");
assert_eq!(header.payload(item), Some(&b"payload"[..]));
assert_eq!(embedded_file_header(&item[..header.data_offset]).unwrap(), header);
assert_eq!(header.payload(&item[..header.data_offset]), None);
for n in 0..header.data_offset {
assert!(embedded_file_header(&item[..n]).is_err());
}
}
#[test]
fn filename_limits_and_lossy_metadata_are_preserved() {
let data = encode_embedded_file("x", &"a".repeat(32767), b"");
let item = iter_linked_records(&data).next().unwrap().item().unwrap();
assert_eq!(embedded_file_header(item).unwrap().name.len(), 32767);
let data = encode_embedded_file("x", &"a".repeat(32768), b"");
assert!(embedded_file_header(iter_linked_records(&data).next().unwrap().item().unwrap()).is_err());
let data = encode_embedded_file("x", "y", b"payload");
let mut item = iter_linked_records(&data).next().unwrap().item().unwrap().to_vec();
item[9] = 0xff;
item[14..16].copy_from_slice(&0xd800u16.to_be_bytes());
let h = embedded_file_header(&item).unwrap();
assert_eq!(h.uuid, "\u{fffd}");
assert_eq!(h.name, "\u{fffd}");
item[0..4].copy_from_slice(b"liFE");
assert!(embedded_file_header(&item).is_err());
}
#[test]
fn malformed_inner_records_do_not_hide_later_files() {
let mut data = vec![0; 8]; // A complete empty item, not a truncated frame.
data.extend(encode_embedded_file("wanted", "x", b"ok"));
data.extend([1, 2, 3]); // Incomplete tail retained, never interpreted as an item.
let records: Vec<_> = iter_linked_records(&data).collect();
assert_eq!(records, linked_records(&data));
assert!(embedded_file_header(records[0].item().unwrap()).is_err());
let item = records[1].item().unwrap();
assert_eq!(embedded_file_header(item).unwrap().payload(item), Some(&b"ok"[..]));
assert_eq!(records[2].item(), None);
assert_eq!(records[2].raw, &[1, 2, 3]);
}
}
+3
View File
@@ -150,3 +150,6 @@ mod tests {
assert_eq!(t.style.size, Some(12.0));
}
}
/// Editable type-tool envelope with PhotoCraft-compatible recovery and geometry limits.
pub mod envelope;
+309
View File
@@ -0,0 +1,309 @@
//! Editable PSD Type Tool Object Setting (`TySh`) envelope, extracted from PhotoCraft.
//! App-specific text styles, layout, units and editing policy stay with the consumer.
//! Parsing intentionally retains PhotoCraft's optional-warp and partial-bounds recovery.
//! Existing read-only [`super::TypeLayer`] behavior is unchanged.
use crate::descriptor::{Class, Descriptor, Id, ReferenceItem, UnicodeString, Value as D, VersionedDescriptor};
use crate::error::{PsdError, Result};
/// Maximum encoded envelope size, bounding hostile input and serialized output.
pub const MAX_BYTES: usize = 8 * 1024 * 1024;
/// Parsed `TySh` contents.
#[derive(Clone, Debug, PartialEq)]
pub struct TySh {
/// Affine transform in PSD order: xx, xy, yx, yy, tx, ty.
pub transform: [f64; 6],
/// Text descriptor, including text content and styling data.
pub text: Descriptor,
/// Optional warp descriptor retained from the Type Tool block.
pub warp: Option<Descriptor>,
/// The four trailing big-endian f32 values (left, top, right, bottom) after the warp
/// descriptor. Photoshop writes zeros for unwarped type and the text-space bounds (the
/// `bounds` descriptor's rectangle) for warped type.
pub bounds: [f32; 4],
}
/// Whether a type transform can reach rendering. Pixel coordinates use i32 in the originating PhotoCraft consumer, so non-finite and unrepresentable affine terms are rejected (#4758).
pub fn transform_is_safe(t: &[f64; 6]) -> bool {
t.iter().all(|v| v.is_finite() && v.abs() <= f64::from(i32::MAX))
}
/// Parses a `TySh` block.
pub fn parse_tysh(data: &[u8]) -> Option<TySh> {
if data.len() > MAX_BYTES {
return None;
}
let f = |at: usize| data.get(at..at + 8).map(|b| f64::from_be_bytes(b.try_into().unwrap_or([0; 8])));
let mut m = [0.0; 6];
for (i, v) in m.iter_mut().enumerate() {
*v = f(2 + i * 8)?;
}
if !transform_is_safe(&m) {
return None;
}
let (text, used) = VersionedDescriptor::parse_prefix(data.get(52..)?).ok()?;
let rest = data.get(52 + used..).unwrap_or(&[]);
let (warp, wused) = match rest.get(2..).and_then(|r| VersionedDescriptor::parse_prefix(r).ok()) {
Some((w, n)) => (Some(w.descriptor), n + 2),
None => (None, 0),
};
let tail = rest.get(wused..).unwrap_or(&[]);
let mut bounds = [0f32; 4];
for (i, b) in bounds.iter_mut().enumerate() {
if let Some(x) = tail.get(i * 4..i * 4 + 4) {
*b = f32::from_be_bytes(x.try_into().unwrap_or([0; 4]));
}
}
if bounds.iter().any(|x| !x.is_finite()) {
return None;
}
Some(TySh { transform: m, text: text.descriptor, warp, bounds })
}
/// `tysh` moved by (`dx`, `dy`): only the transform's translation changes. The text, its styles,
/// the warp and the trailing bounds (which are in text space) stay byte for byte, so a moved
/// Photoshop type layer keeps everything Photoshop wrote. `None` when the block is too short.
pub fn translate_tysh(tysh: &[u8], dx: f64, dy: f64) -> Option<Vec<u8>> {
if tysh.len() > MAX_BYTES || tysh.len() < 50 {
return None;
}
let mut transform = [0.0; 6];
for (i, x) in transform.iter_mut().enumerate() {
*x = f64::from_be_bytes(tysh.get(2 + i * 8..10 + i * 8)?.try_into().ok()?);
}
transform[4] += dx;
transform[5] += dy;
if !transform_is_safe(&transform) {
return None;
}
let mut out = Vec::new();
out.try_reserve_exact(tysh.len()).ok()?;
out.extend_from_slice(tysh);
// Version (2 bytes), then xx, xy, yx, yy, tx, ty as big-endian f64: tx at 34, ty at 42.
for (at, d) in [(34, dx), (42, dy)] {
let b = out.get_mut(at..at + 8)?;
let v = f64::from_be_bytes(b.try_into().ok()?) + d;
b.copy_from_slice(&v.to_be_bytes());
}
Some(out)
}
/// Serializes a `TySh` block.
pub fn write_tysh(t: &TySh) -> Result<Vec<u8>> {
if !transform_is_safe(&t.transform) || t.bounds.iter().any(|x| !x.is_finite()) {
return Err(PsdError::LimitExceeded("TySh geometry"));
}
let default;
let warp = match &t.warp {
Some(w) => w,
None => {
default = default_warp();
&default
}
};
let mut budget = Budget(78); // versions, transform and trailing bounds
budget.descriptor(&t.text, 0)?;
budget.descriptor(warp, 0)?;
let mut v = Vec::new();
v.try_reserve_exact(budget.0).map_err(|_| PsdError::OutOfMemory("TySh output"))?;
v.extend_from_slice(&1u16.to_be_bytes());
for x in t.transform {
v.extend_from_slice(&x.to_be_bytes());
}
v.extend_from_slice(&50u16.to_be_bytes());
v.extend_from_slice(&16u32.to_be_bytes());
t.text.write(&mut v);
v.extend_from_slice(&1u16.to_be_bytes());
v.extend_from_slice(&16u32.to_be_bytes());
warp.write(&mut v);
for b in t.bounds {
v.extend_from_slice(&b.to_be_bytes());
}
Ok(v)
}
// Count before cloning or serializing: bound both recursive trees and total output.
struct Budget(usize);
impl Budget {
fn add(&mut self, n: usize) -> Result<()> {
self.0 = self.0.checked_add(n).filter(|n| *n <= MAX_BYTES).ok_or(PsdError::LimitExceeded("TySh bytes"))?;
Ok(())
}
fn unicode(&mut self, s: &UnicodeString) -> Result<()> {
self.add(4)?;
self.add(s.0.len().checked_mul(2).ok_or(PsdError::LimitExceeded("TySh string"))?)
}
fn id(&mut self, id: &Id) -> Result<()> {
self.add(4)?;
self.add(id.as_bytes().len())
}
fn class(&mut self, c: &Class) -> Result<()> {
self.unicode(&c.name)?;
self.id(&c.class_id)
}
fn descriptor(&mut self, d: &Descriptor, depth: usize) -> Result<()> {
if depth > 32 {
return Err(PsdError::LimitExceeded("TySh depth"));
}
self.unicode(&d.name)?;
self.id(&d.class_id)?;
self.add(4)?;
for (k, v) in &d.items {
self.id(k)?;
self.value(v, depth + 1)?;
}
Ok(())
}
fn value(&mut self, v: &D, depth: usize) -> Result<()> {
if depth > 32 {
return Err(PsdError::LimitExceeded("TySh depth"));
}
self.add(4)?;
match v {
D::Descriptor(d) | D::GlobalObject(d) => self.descriptor(d, depth),
D::ObjectArray(o) => {
self.add(4)?;
self.descriptor(&o.body, depth)
}
D::List(xs) => {
self.add(4)?;
for x in xs {
self.value(x, depth + 1)?;
}
Ok(())
}
D::Reference(xs) => {
self.add(4)?;
for x in xs {
self.add(4)?;
match x {
ReferenceItem::Property { class, key } => {
self.class(class)?;
self.id(key)?;
}
ReferenceItem::Class(c) => self.class(c)?,
ReferenceItem::Enumerated { class, type_id, value } => {
self.class(class)?;
self.id(type_id)?;
self.id(value)?;
}
ReferenceItem::Offset { class, .. } | ReferenceItem::Identifier { class, .. } | ReferenceItem::Index { class, .. } => {
self.class(class)?;
self.add(4)?;
}
ReferenceItem::Name { class, name } => {
self.class(class)?;
self.unicode(name)?;
}
}
}
Ok(())
}
D::Text(x) => self.unicode(x),
D::Class(c) | D::GlobalClass(c) => self.class(c),
D::Enumerated { type_id, value } => {
self.id(type_id)?;
self.id(value)
}
D::UnitFloats { values, .. } => {
self.add(8)?;
self.add(values.len().checked_mul(8).ok_or(PsdError::LimitExceeded("TySh values"))?)
}
D::RawData(x) | D::Alias(x) | D::Path(x) => {
self.add(4)?;
self.add(x.len())
}
D::Double(_) | D::LargeInteger(_) => self.add(8),
D::UnitFloat { .. } => self.add(12),
D::Integer(_) => self.add(4),
D::Boolean(_) => self.add(1),
}
}
}
fn default_warp() -> Descriptor {
Descriptor::new("warp")
.with("warpStyle", enumv("warpStyle", "warpNone"))
.with("warpValue", D::Double(0.0))
.with("warpPerspective", D::Double(0.0))
.with("warpPerspectiveOther", D::Double(0.0))
.with("warpRotate", enumv("Ornt", "Hrzn"))
}
fn enumv(t: &str, v: &str) -> D {
D::Enumerated { type_id: Id::new(t), value: Id::new(v) }
}
#[cfg(test)]
mod tests {
use super::*;
fn sample() -> TySh {
TySh {
transform: [1.0, 0.0, 0.0, 1.0, 25.0, 30.0],
text: Descriptor::new("TxLr").with("EngineData", D::RawData(b"preserved".to_vec())),
warp: Some(default_warp()),
bounds: [-1.0, 2.0, 30.0, 40.0],
}
}
#[test]
fn roundtrip_preserves_descriptors_transform_and_bounds() {
let t = sample();
let b = write_tysh(&t).unwrap();
assert_eq!(parse_tysh(&b), Some(t));
let shifted = translate_tysh(&b, 7.0, -3.0).unwrap();
assert_eq!(&shifted[..34], &b[..34]);
assert_eq!(&shifted[50..], &b[50..]);
assert_eq!(parse_tysh(&shifted).unwrap().transform, [1.0, 0.0, 0.0, 1.0, 32.0, 27.0]);
}
#[test]
fn truncations_and_unsafe_transforms_preserve_recovery_contract() {
let mut t = sample();
let bytes = write_tysh(&t).unwrap();
let (_, n) = VersionedDescriptor::parse_prefix(&bytes[52..]).unwrap();
for cut in 0..52 + n {
assert!(parse_tysh(&bytes[..cut]).is_none(), "{cut}");
}
let short = parse_tysh(&bytes[..52 + n]).unwrap();
assert!(short.warp.is_none());
assert_eq!(short.bounds, [0.0; 4]);
for cut in 0..50 {
assert!(translate_tysh(&bytes[..cut], 1.0, 2.0).is_none());
}
for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, f64::from(i32::MAX) + 1.0] {
for i in 0..6 {
t = sample();
t.transform[i] = bad;
assert!(write_tysh(&t).is_err());
}
}
t = sample();
t.warp = None;
assert!(parse_tysh(&write_tysh(&t).unwrap()).unwrap().warp.is_some());
let partial = parse_tysh(&bytes[..bytes.len() - 4]).unwrap();
assert_eq!(partial.bounds, [-1.0, 2.0, 30.0, 0.0]);
}
#[test]
fn hostile_output_and_translations_are_refused_before_copying() {
let bytes = write_tysh(&sample()).unwrap();
for bad in [f64::NAN, f64::INFINITY, f64::MAX] {
assert!(translate_tysh(&bytes, bad, 0.0).is_none());
}
let mut t = sample();
t.bounds[0] = f32::NAN;
assert!(write_tysh(&t).is_err());
t = sample();
t.text = Descriptor::new("TxLr").with("data", D::RawData(vec![0; MAX_BYTES]));
assert!(write_tysh(&t).is_err());
let oversized = vec![0; MAX_BYTES + 1];
assert!(translate_tysh(&oversized, 0.0, 0.0).is_none());
assert!(parse_tysh(&oversized).is_none());
let mut nested = D::Integer(1);
for _ in 0..34 {
nested = D::List(vec![nested]);
}
t = sample();
t.text = Descriptor::new("TxLr").with("nest", nested);
assert!(write_tysh(&t).is_err());
}
}
+1
View File
@@ -12,6 +12,7 @@ workspace = true
[dependencies]
craft-xml = { workspace = true }
quick-xml = { version = "0.41", default-features = false }
craft-image-codecs = { workspace = true }
# SVGZ (gzip), pure-Rust backend.
flate2 = { version = "1", default-features = false, features = ["rust_backend"] }
+56
View File
@@ -0,0 +1,56 @@
//! SVG polyline and triangle path attributes for display-list exporters.
use crate::write::num;
use std::fmt::{self, Display};
/// A fixed-precision polyline attribute streamed into an SVG writer.
pub struct Points<I> {
iter: I,
decimals: usize,
}
/// Format points without allocating an intermediate attribute string. Precision is capped at 32.
pub fn points<I: Iterator<Item = [f64; 2]> + Clone>(iter: I, decimals: usize) -> Points<I> {
Points { iter, decimals: decimals.min(32) }
}
impl<I: Iterator<Item = [f64; 2]> + Clone> Display for Points<I> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
for [x, y] in self.iter.clone() {
write!(f, "{},{} ", num(x, self.decimals), num(y, self.decimals))?;
}
Ok(())
}
}
/// A fixed-precision sequence of closed triangle subpaths.
pub struct Triangles<I> {
iter: I,
decimals: usize,
}
/// Format independent triangles without allocating an intermediate attribute string. Precision is capped at 32.
pub fn triangles<I: Iterator<Item = [[f64; 2]; 3]> + Clone>(iter: I, decimals: usize) -> Triangles<I> {
Triangles { iter, decimals: decimals.min(32) }
}
impl<I: Iterator<Item = [[f64; 2]; 3]> + Clone> Display for Triangles<I> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
for [[ax, ay], [bx, by], [cx, cy]] in self.iter.clone() {
write!(
f,
"M{} {}L{} {}L{} {}Z",
num(ax, self.decimals),
num(ay, self.decimals),
num(bx, self.decimals),
num(by, self.decimals),
num(cx, self.decimals),
num(cy, self.decimals)
)?;
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn fixed_precision_attributes_keep_independent_triangles() {
assert_eq!(points([[1.0, 2.0], [3.0, 4.0]].into_iter(), 2).to_string(), "1.00,2.00 3.00,4.00 ");
assert_eq!(triangles([[[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]].into_iter(), 1).to_string(), "M1.0 2.0L3.0 4.0L5.0 6.0Z");
}
}
+13 -3
View File
@@ -178,6 +178,10 @@ pub fn too_wide(svg: &str, most: usize, most_work: usize) -> bool {
pub struct Prescan<'s> {
/// Whether the elements nest deeper than the cap. The pass stops there.
pub too_deep: bool,
/// Deepest element nesting observed (markup entities count ten times).
pub depth: usize,
/// Deepest stack of unclosed source elements, excluding self-closing leaves.
pub open_depth: usize,
/// The text with each data URL in an element's attribute values left out: a `data:` value's
/// quotes kept, a `url(…)`'s parentheses and quotes. Borrowed when there is none, and the
/// whole text when `too_deep`. An embedded picture is a data URL and most of the text when
@@ -250,7 +254,7 @@ pub fn prescan(svg: &str, most: usize) -> Prescan<'_> {
(b.len(), false)
};
// (now, deepest) of the elements, and of the markup inside the document type.
let (mut elements, mut entities) = ((0usize, 0usize), (0usize, 0usize));
let (mut elements, mut entities, mut open_depth) = ((0usize, 0usize), (0usize, 0usize), 0usize);
let mut doctype_end = 0;
let mut i = 0;
while let Some(at) = b.get(i..).and_then(|rest| rest.iter().position(|c| *c == b'<')).map(|at| i + at) {
@@ -287,8 +291,14 @@ pub fn prescan(svg: &str, most: usize) -> Prescan<'_> {
end
};
if elements.1.saturating_add(entities.1.saturating_mul(10)) > most {
return Prescan { too_deep: true, markers: Cow::Borrowed(svg) };
return Prescan {
too_deep: true,
depth: elements.1.saturating_add(entities.1.saturating_mul(10)),
open_depth,
markers: Cow::Borrowed(svg),
};
}
open_depth = open_depth.max(elements.0);
}
let markers = if data_values.is_empty() {
Cow::Borrowed(svg)
@@ -303,7 +313,7 @@ pub fn prescan(svg: &str, most: usize) -> Prescan<'_> {
text.push_str(svg.get(from..).unwrap_or_default());
Cow::Owned(text)
};
Prescan { too_deep: false, markers }
Prescan { too_deep: false, depth: elements.1.saturating_add(entities.1.saturating_mul(10)), open_depth, markers }
}
#[cfg(test)]
+3
View File
@@ -18,7 +18,10 @@
#![forbid(unsafe_code)]
pub mod color;
pub mod drawing_write;
pub mod guard;
pub mod neutral_document;
pub mod path_data;
pub mod paths;
pub mod preflight;
pub mod sniff;
+407
View File
@@ -0,0 +1,407 @@
//! A bounded SVG document walk that preserves geometric primitive kinds for CAD import.
//!
//! Coordinates remain in SVG user units. Each shape carries the composed transform into
//! millimetres with the page Y axis pointing up; consumers map shapes into their own model.
use crate::path_data::{self, Point, Subpath};
use quick_xml::events::{BytesStart, Event as XmlEvent};
use quick_xml::{Reader, XmlVersion};
use std::collections::BTreeMap;
const MAX_DEPTH: usize = 64;
const MAX_SHAPES: usize = 500_000;
const MAX_POINTS: usize = 8_000_000;
const MAX_POLY_POINTS: usize = 100_001;
const SKIP: &[&[u8]] = &[
b"defs",
b"symbol",
b"clipPath",
b"mask",
b"pattern",
b"marker",
b"linearGradient",
b"radialGradient",
b"filter",
b"style",
b"text",
b"image",
b"title",
b"desc",
b"metadata",
];
const CONTAINERS: &[&[u8]] = &[b"g", b"svg", b"a", b"switch"];
/// Input failure or resource bound.
#[derive(Debug, thiserror::Error)]
#[error("{0}")]
pub struct Error(pub String);
/// A shape's original geometry before its affine transform.
#[derive(Debug, Clone, PartialEq)]
pub enum Primitive {
Rect { x: f64, y: f64, width: f64, height: f64 },
Circle { center: Point, radius: f64 },
Ellipse { center: Point, rx: f64, ry: f64 },
Line { a: Point, b: Point },
Polyline { points: Vec<Point>, closed: bool },
Path(Vec<Subpath>),
}
/// A primitive with its layer and SVG affine matrix `[a,b,c,d,e,f]`.
#[derive(Debug, Clone, PartialEq)]
pub struct Shape {
pub primitive: Primitive,
pub transform: [f64; 6],
pub layer: String,
}
/// The shapes, encountered layer names, and skipped-feature counts. `visit` streams shapes
/// to its sink, so its returned `shapes` is empty; `import` collects them.
#[derive(Debug, Default, PartialEq)]
pub struct Document {
pub shapes: Vec<Shape>,
pub layers: Vec<String>,
pub skipped: BTreeMap<Skipped, usize>,
}
/// Features left out by this geometry-only import.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Skipped {
Text,
Image,
Use,
Style,
RoundedCorners,
}
fn attr(e: &BytesStart<'_>, name: &[u8]) -> Option<String> {
for a in e.attributes() {
let Ok(a) = a else { return None };
if a.key.into_inner() == name {
return a.normalized_value(XmlVersion::Explicit1_0).ok().map(|v| v.into_owned());
}
}
None
}
fn hidden(e: &BytesStart<'_>) -> bool {
attr(e, b"display").as_deref() == Some("none") || attr(e, b"style").is_some_and(|s| s.replace(' ', "").contains("display:none"))
}
fn length(s: &str) -> Option<f64> {
let s = s.trim();
let cut = s.find(|c: char| !(c.is_ascii_digit() || matches!(c, '.' | '-' | '+' | 'e' | 'E'))).unwrap_or(s.len());
let (n, unit) = s.split_at(cut);
let v: f64 = n.trim().parse().ok()?;
if !v.is_finite() {
return None;
}
Some(
v * match unit.trim() {
"" | "px" | "mm" => 1.0,
"cm" => 10.0,
"in" => 25.4,
"pt" => 25.4 / 72.0,
"pc" => 25.4 / 6.0,
_ => 25.4 / 96.0,
},
)
}
fn num(e: &BytesStart<'_>, name: &[u8], default: f64) -> f64 {
attr(e, name).as_deref().and_then(length).unwrap_or(default)
}
const ID: [f64; 6] = [1., 0., 0., 1., 0., 0.];
fn mul(a: [f64; 6], b: [f64; 6]) -> [f64; 6] {
[
a[0] * b[0] + a[2] * b[1],
a[1] * b[0] + a[3] * b[1],
a[0] * b[2] + a[2] * b[3],
a[1] * b[2] + a[3] * b[3],
a[0] * b[4] + a[2] * b[5] + a[4],
a[1] * b[4] + a[3] * b[5] + a[5],
]
}
fn translate(x: f64, y: f64) -> [f64; 6] {
[1., 0., 0., 1., x, y]
}
fn scale(x: f64, y: f64) -> [f64; 6] {
[x, 0., 0., y, 0., 0.]
}
fn rotate(a: f64) -> [f64; 6] {
let (s, c) = a.to_radians().sin_cos();
[c, s, -s, c, 0., 0.]
}
fn numbers(s: &str) -> impl Iterator<Item = f64> + '_ {
path_data::Numbers::new(s)
}
fn transform(s: &str) -> Option<[f64; 6]> {
let mut out = None;
let mut rest = s.trim();
while !rest.is_empty() {
let open = rest.find('(')?;
let name = rest[..open].trim();
let close = rest[open..].find(')')? + open;
// No transform function accepts more than six arguments.
let args: Vec<_> = numbers(&rest[open + 1..close]).take(7).collect();
let m = match (name, args.as_slice()) {
("matrix", [a, b, c, d, e, f]) => [*a, *b, *c, *d, *e, *f],
("translate", [x]) => translate(*x, 0.),
("translate", [x, y]) => translate(*x, *y),
("scale", [x]) => scale(*x, *x),
("scale", [x, y]) => scale(*x, *y),
("rotate", [a]) => rotate(*a),
("rotate", [a, x, y]) => mul(mul(translate(*x, *y), rotate(*a)), translate(-x, -y)),
("skewX", [a]) => [1., 0., a.to_radians().tan(), 1., 0., 0.],
("skewY", [a]) => [1., a.to_radians().tan(), 0., 1., 0., 0.],
_ => return None,
};
out = Some(out.map_or(m, |prev| mul(prev, m)));
rest = rest[close + 1..].trim_start_matches(|c: char| c == ',' || c.is_whitespace());
}
out
}
fn viewport(e: &BytesStart<'_>) -> [f64; 6] {
let vb = attr(e, b"viewBox").and_then(|raw| {
let n: Vec<_> = numbers(&raw).take(5).collect();
match n.as_slice() {
[x, y, w, h] if *w > 0. && *h > 0. => Some((*x, *y, *w, *h)),
_ => None,
}
});
let root = |name: &[u8]| {
let raw = attr(e, name)?;
let mm = length(&raw)?;
let unit = raw.trim().trim_start_matches(|c: char| c.is_ascii_digit() || matches!(c, '.' | '-' | '+' | 'e' | 'E')).trim();
Some(if matches!(unit, "" | "px") { mm * 25.4 / 96. } else { mm })
};
let unit = match (vb, root(b"width"), root(b"height")) {
(Some((_, _, w, _)), Some(x), _) if x > 0. => x / w,
(Some((_, _, _, h)), _, Some(y)) if y > 0. => y / h,
_ => 25.4 / 96.,
};
let (x, y, h) = vb.map_or((0., 0., 0.), |(x, y, _, h)| (x, y, h));
[unit, 0., 0., -unit, -x * unit, (y + h) * unit]
}
fn layer_name(raw: &str) -> String {
let s: String = raw.trim().chars().map(|c| if c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '$') { c } else { '_' }).take(128).collect();
let s = s.trim_matches('_');
if s.is_empty() { "SVG".into() } else { s.into() }
}
/// A layer declaration or a drawable primitive in document order.
pub enum Event {
Layer(String),
Shape(Shape),
}
struct Walker<'a> {
doc: Document,
stack: Vec<[f64; 6]>,
layer: String,
skip: usize,
points: usize,
shapes: usize,
sink: &'a mut dyn FnMut(Event) -> Result<(), Error>,
}
impl Walker<'_> {
fn current(&self) -> [f64; 6] {
self.stack.last().copied().unwrap_or(ID)
}
fn note(&mut self, what: Skipped) {
*self.doc.skipped.entry(what).or_default() += 1;
}
fn skipped(name: &[u8]) -> Option<Skipped> {
match name {
b"text" => Some(Skipped::Text),
b"image" => Some(Skipped::Image),
_ => None,
}
}
fn start(&mut self, name: &[u8], e: &BytesStart<'_>) -> Result<(), Error> {
if name == b"style" {
self.note(Skipped::Style);
}
if self.skip > 0 {
self.skip += 1;
return Ok(());
}
if hidden(e) {
self.skip = 1;
return Ok(());
}
if SKIP.contains(&name) {
if let Some(s) = Self::skipped(name) {
self.note(s);
}
self.skip = 1;
return Ok(());
}
if !CONTAINERS.contains(&name) {
return self.element(name, e);
}
if name == b"svg"
&& self.stack.len() == 1
&& let Some(root) = self.stack.first_mut()
{
*root = viewport(e);
}
if name == b"g"
&& attr(e, b"inkscape:groupmode").as_deref() == Some("layer")
&& let Some(raw) = attr(e, b"inkscape:label").or_else(|| attr(e, b"id"))
{
let layer = layer_name(&raw);
if layer == "0" || self.doc.layers.contains(&layer) {
self.layer = layer;
} else if self.doc.layers.len() < 255 {
self.doc.layers.push(layer.clone());
(self.sink)(Event::Layer(layer.clone()))?;
self.layer = layer;
}
}
if self.stack.len() >= MAX_DEPTH {
return Err(Error(format!("SVG: more than {MAX_DEPTH} nested groups")));
}
let next = attr(e, b"transform").as_deref().and_then(transform).map_or(self.current(), |t| mul(self.current(), t));
self.stack.push(next);
Ok(())
}
fn element(&mut self, name: &[u8], e: &BytesStart<'_>) -> Result<(), Error> {
if self.skip > 0 {
return Ok(());
}
if SKIP.contains(&name) || hidden(e) {
if !hidden(e)
&& let Some(s) = Self::skipped(name)
{
self.note(s);
}
return Ok(());
}
let p = |x, y| Point::new(num(e, x, 0.), num(e, y, 0.));
let primitive = match name {
b"use" => {
self.note(Skipped::Use);
return Ok(());
}
b"rect" => {
let (x, y, w, h) = (num(e, b"x", 0.), num(e, b"y", 0.), num(e, b"width", 0.), num(e, b"height", 0.));
if w <= 0. || h <= 0. {
return Ok(());
}
if num(e, b"rx", 0.) > 0. || num(e, b"ry", 0.) > 0. {
self.note(Skipped::RoundedCorners);
}
Primitive::Rect { x, y, width: w, height: h }
}
b"circle" => {
let r = num(e, b"r", 0.);
if r <= 0. {
return Ok(());
}
Primitive::Circle { center: p(b"cx", b"cy"), radius: r }
}
b"ellipse" => {
let (rx, ry) = (num(e, b"rx", 0.), num(e, b"ry", 0.));
if rx <= 0. || ry <= 0. {
return Ok(());
}
Primitive::Ellipse { center: p(b"cx", b"cy"), rx, ry }
}
b"line" => Primitive::Line { a: p(b"x1", b"y1"), b: p(b"x2", b"y2") },
b"polyline" | b"polygon" => {
let Some(raw) = attr(e, b"points") else { return Ok(()) };
let n: Vec<_> = numbers(&raw).take(MAX_POLY_POINTS * 2).collect();
let pts: Vec<_> = n.as_chunks::<2>().0.iter().map(|[x, y]| Point::new(*x, *y)).collect();
if pts.len() < 2 {
return Ok(());
}
Primitive::Polyline { points: pts, closed: name == b"polygon" }
}
b"path" => {
let Some(raw) = attr(e, b"d") else { return Ok(()) };
Primitive::Path(path_data::parse_path(&raw).map_err(|e| Error(e.to_string()))?)
}
_ => return Ok(()),
};
let cost = match &primitive {
Primitive::Polyline { points, .. } => points.len(),
Primitive::Path(paths) => paths.iter().map(|p| p.segs.len()).sum(),
_ => 1,
};
self.points = self.points.checked_add(cost).filter(|n| *n <= MAX_POINTS).ok_or_else(|| Error("SVG: too much generated geometry".into()))?;
if self.shapes >= MAX_SHAPES {
return Err(Error(format!("SVG: more than {MAX_SHAPES} elements")));
}
let matrix = attr(e, b"transform").as_deref().and_then(transform).map_or(self.current(), |t| mul(self.current(), t));
self.shapes += 1;
(self.sink)(Event::Shape(Shape { primitive, transform: matrix, layer: self.layer.clone() }))
}
}
/// Walk supported SVG geometry without retaining a second copy of the document's shapes.
/// The sink receives each layer before its first shape and each shape in input order.
pub fn visit(text: &str, sink: &mut dyn FnMut(Event) -> Result<(), Error>) -> Result<Document, Error> {
let mut walker = Walker { doc: Document::default(), stack: vec![ID], layer: "0".into(), skip: 0, points: 0, shapes: 0, sink };
let mut reader = Reader::from_str(text);
reader.config_mut().trim_text(true);
loop {
match reader.read_event().map_err(|e| Error(format!("SVG: {e}")))? {
XmlEvent::Start(e) => walker.start(e.name().into_inner(), &e)?,
XmlEvent::Empty(e) => walker.element(e.name().into_inner(), &e)?,
XmlEvent::End(e) => {
if walker.skip > 0 {
walker.skip -= 1;
} else if CONTAINERS.contains(&e.name().into_inner()) && walker.stack.len() > 1 {
walker.stack.pop();
}
}
XmlEvent::Eof => break,
_ => {}
}
}
Ok(walker.doc)
}
/// Read the supported geometry into an owned document.
pub fn import(text: &str) -> Result<Document, Error> {
let mut shapes = Vec::new();
let mut doc = visit(text, &mut |event| {
if let Event::Shape(shape) = event {
shapes.push(shape);
}
Ok(())
})?;
doc.shapes = shapes;
Ok(doc)
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
#[test]
fn keeps_primitives_transform_layers_and_skips() {
let svg = r##"<svg width="20mm" height="10mm" viewBox="0 0 20 10"><g inkscape:groupmode="layer" inkscape:label="cut" transform="translate(2,1)"><circle cx="3" cy="4" r="2"/><ellipse cx="1" cy="2" rx="3" ry="1"/><path d="M0 0 A1 1 0 011 1"/></g><text>x</text><use href="#x"/></svg>"##;
let d = import(svg).unwrap();
assert_eq!(d.layers, ["cut"]);
assert_eq!(d.shapes.len(), 3);
assert_eq!(d.shapes[0].primitive, Primitive::Circle { center: Point::new(3., 4.), radius: 2. });
assert_eq!(d.shapes[0].transform, [1., 0., 0., -1., 2., 9.]);
assert!(matches!(d.shapes[1].primitive, Primitive::Ellipse { .. }));
assert!(matches!(&d.shapes[2].primitive,Primitive::Path(p) if matches!(p[0].segs[0],path_data::Segment::Arc { .. })));
assert_eq!(d.skipped.get(&Skipped::Text), Some(&1));
assert_eq!(d.skipped.get(&Skipped::Use), Some(&1));
}
#[test]
fn streaming_delivers_layers_before_shapes_and_stops_on_error() {
let s = r#"<svg><g inkscape:groupmode="layer" inkscape:label="cut"><circle r="1"/><circle r="2"/></g></svg>"#;
let mut events = Vec::new();
let result = visit(s, &mut |event| {
match event {
Event::Layer(name) => events.push(name),
Event::Shape(_) => {
events.push("shape".into());
return Err(Error("stop".into()));
}
}
Ok(())
});
assert!(result.is_err());
assert_eq!(events, ["cut", "shape"]);
}
#[test]
fn refuses_excessive_nesting() {
let s = format!("<svg>{}{}</svg>", "<g>".repeat(100), "</g>".repeat(100));
assert!(import(&s).is_err());
}
}
+456
View File
@@ -0,0 +1,456 @@
//! SVG path data as neutral line, cubic and elliptical arc segments.
//!
//! Relative commands and smooth controls are resolved, while arcs remain arcs.
//! The caller chooses how to map the result to its own geometry model.
use std::ops::{Add, Mul, Sub};
/// A point in the path's original user coordinate system.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Point {
/// Horizontal coordinate.
pub x: f64,
/// Vertical coordinate.
pub y: f64,
}
impl Point {
/// The origin.
pub const ZERO: Self = Self { x: 0.0, y: 0.0 };
/// Construct a point.
pub const fn new(x: f64, y: f64) -> Self {
Self { x, y }
}
}
impl Add for Point {
type Output = Self;
fn add(self, rhs: Self) -> Self {
Self::new(self.x + rhs.x, self.y + rhs.y)
}
}
impl Sub for Point {
type Output = Self;
fn sub(self, rhs: Self) -> Self {
Self::new(self.x - rhs.x, self.y - rhs.y)
}
}
impl Mul<f64> for Point {
type Output = Self;
fn mul(self, rhs: f64) -> Self {
Self::new(self.x * rhs, self.y * rhs)
}
}
/// Invalid or oversized path data.
#[derive(Debug, thiserror::Error)]
#[error("{0}")]
pub struct Error(pub String);
type Result<T> = std::result::Result<T, Error>;
const MAX_PATH_SEGMENTS: usize = 100_000;
const MAX_CURVE_POINTS: usize = 100_001;
pub(crate) struct Numbers<'a> {
s: &'a [u8],
i: usize,
}
impl<'a> Numbers<'a> {
pub(crate) fn new(s: &'a str) -> Self {
Self { s: s.as_bytes(), i: 0 }
}
fn skip_seps(&mut self) {
while matches!(self.s.get(self.i), Some(b' ' | b'\t' | b'\r' | b'\n' | b',')) {
self.i += 1;
}
}
fn next_num(&mut self) -> Option<f64> {
self.skip_seps();
let start = self.i;
if matches!(self.s.get(self.i), Some(b'+' | b'-')) {
self.i += 1;
}
let mut digits = 0;
let mut dot = false;
let mut exp = false;
while let Some(c) = self.s.get(self.i) {
match c {
b'0'..=b'9' => {
digits += 1;
self.i += 1;
}
b'.' if !dot && !exp => {
dot = true;
self.i += 1;
}
b'e' | b'E' if !exp && digits > 0 => {
exp = true;
self.i += 1;
if matches!(self.s.get(self.i), Some(b'+' | b'-')) {
self.i += 1;
}
}
_ => break,
}
}
if digits == 0 {
self.i = start;
return None;
}
std::str::from_utf8(&self.s[start..self.i]).ok()?.parse::<f64>().ok().filter(|v| v.is_finite())
}
}
impl Iterator for Numbers<'_> {
type Item = f64;
fn next(&mut self) -> Option<f64> {
self.next_num()
}
}
/// One `M …` run of a `d` attribute.
#[derive(Debug, Clone, PartialEq)]
pub struct Subpath {
/// Start point.
pub start: Point,
/// Segments in drawing order.
pub segs: Vec<Segment>,
/// Whether a close-path command closed this subpath.
pub closed: bool,
}
/// A path segment; arc values retain the SVG endpoint parameterization.
#[derive(Debug, Clone, PartialEq)]
pub enum Segment {
Line(Point),
Cubic(Point, Point, Point),
Arc { rx: f64, ry: f64, rot: f64, large: bool, sweep: bool, end: Point },
}
/// Tokens of a `d` attribute: command letters and numbers, in order.
enum Tok {
Cmd(u8),
Num(f64),
}
struct Tokenizer<'a> {
s: &'a [u8],
i: usize,
/// Start of the most recently returned token.
tok_start: usize,
}
impl<'a> Tokenizer<'a> {
fn new(s: &'a str) -> Self {
Tokenizer { s: s.as_bytes(), i: 0, tok_start: 0 }
}
/// Read an arc flag: a single `0` or `1` character, which needs no separator after it.
fn next_flag(&mut self) -> Option<f64> {
let mut nums = Numbers { s: self.s, i: self.i };
nums.skip_seps();
let v = match self.s.get(nums.i)? {
b'0' => 0.0,
b'1' => 1.0,
_ => return None,
};
self.i = nums.i + 1;
Some(v)
}
fn next_tok(&mut self) -> Option<Tok> {
let mut nums = Numbers { s: self.s, i: self.i };
nums.skip_seps();
self.i = nums.i;
self.tok_start = self.i;
let c = self.s.get(self.i).copied()?;
if c.is_ascii_alphabetic() {
self.i += 1;
return Some(Tok::Cmd(c));
}
let tok = nums.next_num().map(Tok::Num);
self.i = nums.i;
tok
}
}
/// Split `d` into subpaths, resolving relative commands and the S/T control reflections.
pub fn parse_path(d: &str) -> Result<Vec<Subpath>> {
let mut tk = Tokenizer::new(d);
let mut lookahead: Option<Tok> = None;
let mut cmd = 0u8;
let mut cur = Point::ZERO;
let mut start = Point::ZERO;
let mut segs: Vec<Segment> = Vec::new();
let mut out: Vec<Subpath> = Vec::new();
let closed = false;
let mut prev_cubic: Option<Point> = None;
let mut prev_quad: Option<Point> = None;
let mut segments = 0usize;
let next_num = |tk: &mut Tokenizer, look: &mut Option<Tok>| -> Result<f64> {
match look.take() {
Some(Tok::Num(v)) => Ok(v),
Some(other @ Tok::Cmd(_)) => {
*look = Some(other);
Err(Error("SVG: path command is missing coordinates".into()))
}
None => match tk.next_tok() {
Some(Tok::Num(v)) => Ok(v),
Some(other @ Tok::Cmd(_)) => {
*look = Some(other);
Err(Error("SVG: path command is missing coordinates".into()))
}
None => Err(Error("SVG: path command is missing coordinates".into())),
},
}
};
while let Some(tok) = lookahead.take().or_else(|| tk.next_tok()) {
let rel = match tok {
Tok::Cmd(c) => {
if c.eq_ignore_ascii_case(&b'z') {
if !segs.is_empty() {
out.push(Subpath { start, segs, closed: true });
segs = Vec::new();
}
cur = start;
cmd = 0;
continue;
}
cmd = c;
c.is_ascii_lowercase()
}
tok @ Tok::Num(_) => {
if cmd == 0 {
return Err(Error("SVG: path data does not start with a command".into()));
}
lookahead = Some(tok);
cmd.is_ascii_lowercase()
}
};
let abs = cmd.to_ascii_uppercase();
let count = match abs {
b'M' | b'L' | b'T' => 2,
b'H' | b'V' => 1,
b'C' => 6,
b'S' | b'Q' => 4,
b'A' => 7,
_ => return Err(Error(format!("SVG: unknown path command `{}`", cmd as char))),
};
let mut args = [0.0f64; 7];
for (idx, slot) in args.iter_mut().enumerate().take(count) {
if abs == b'A' && (idx == 3 || idx == 4) {
// Flags are single characters; re-scan a pending number token from its start.
if matches!(lookahead, Some(Tok::Num(_))) {
lookahead = None;
tk.i = tk.tok_start;
}
if lookahead.is_none() {
*slot = tk.next_flag().ok_or_else(|| Error("SVG: path command is missing coordinates".into()))?;
continue;
}
}
*slot = next_num(&mut tk, &mut lookahead)?;
}
let point = |x: f64, y: f64| if rel { cur + Point::new(x, y) } else { Point::new(x, y) };
match abs {
b'M' => {
if !segs.is_empty() {
out.push(Subpath { start, segs, closed: false });
segs = Vec::new();
}
cur = point(args[0], args[1]);
start = cur;
cmd = if rel { b'l' } else { b'L' };
prev_cubic = None;
prev_quad = None;
}
b'L' => {
cur = point(args[0], args[1]);
segs.push(Segment::Line(cur));
prev_cubic = None;
prev_quad = None;
}
b'H' => {
cur = Point::new(if rel { cur.x + args[0] } else { args[0] }, cur.y);
segs.push(Segment::Line(cur));
prev_cubic = None;
prev_quad = None;
}
b'V' => {
cur = Point::new(cur.x, if rel { cur.y + args[0] } else { args[0] });
segs.push(Segment::Line(cur));
prev_cubic = None;
prev_quad = None;
}
b'C' => {
let (c1, c2, p) = (point(args[0], args[1]), point(args[2], args[3]), point(args[4], args[5]));
segs.push(Segment::Cubic(c1, c2, p));
prev_cubic = Some(c2);
prev_quad = None;
cur = p;
}
b'S' => {
let c1 = prev_cubic.map_or(cur, |c2| cur * 2.0 - c2);
let (c2, p) = (point(args[0], args[1]), point(args[2], args[3]));
segs.push(Segment::Cubic(c1, c2, p));
prev_cubic = Some(c2);
prev_quad = None;
cur = p;
}
b'Q' => {
let (q, p) = (point(args[0], args[1]), point(args[2], args[3]));
segs.push(Segment::Cubic(cur + (q - cur) * (2.0 / 3.0), p + (q - p) * (2.0 / 3.0), p));
prev_quad = Some(q);
prev_cubic = None;
cur = p;
}
b'T' => {
let reflect = prev_quad.map_or(cur, |q| cur * 2.0 - q);
let p = point(args[0], args[1]);
segs.push(Segment::Cubic(cur + (reflect - cur) * (2.0 / 3.0), p + (reflect - p) * (2.0 / 3.0), p));
prev_quad = Some(reflect);
prev_cubic = None;
cur = p;
}
b'A' => {
let end = point(args[5], args[6]);
segs.push(Segment::Arc { rx: args[0].abs(), ry: args[1].abs(), rot: args[2], large: args[3] != 0.0, sweep: args[4] != 0.0, end });
cur = end;
prev_cubic = None;
prev_quad = None;
}
_ => return Err(Error("SVG: unsupported path command".into())),
}
segments += 1;
if segments > MAX_PATH_SEGMENTS {
return Err(Error("SVG: path has too many segments".into()));
}
if segs.len() > MAX_CURVE_POINTS {
return Err(Error("SVG: path has too many segments".into()));
}
}
if !segs.is_empty() {
out.push(Subpath { start, segs, closed });
}
Ok(out)
}
/// The centre and signed sweep of a circular arc from `p0` to `p1` in a Y-up frame, per the
/// SVG endpoint parameterisation (F.6.5). Radii that cannot span the chord are scaled up,
/// as the specification requires.
pub fn arc_center_circular(p0: Point, p1: Point, r: f64, large: bool, sweep: bool) -> Option<(Point, f64)> {
if r <= 0.0 || !r.is_finite() {
return None;
}
let d = p1 - p0;
let dist = d.x.hypot(d.y);
let r = if dist > 2.0 * r { dist / 2.0 } else { r };
if dist <= f64::EPSILON {
return None;
}
let mid = (p0 + p1) * 0.5;
let h = (r * r - (dist * dist) / 4.0).max(0.0).sqrt();
let n = Point::new(-d.y / dist, d.x / dist);
let sign = if large != sweep { 1.0 } else { -1.0 };
let center = mid + n * (h * sign);
let a0 = (p0.y - center.y).atan2(p0.x - center.x);
let a1 = (p1.y - center.y).atan2(p1.x - center.x);
let ccw = (a1 - a0).rem_euclid(std::f64::consts::TAU);
Some((center, pick_sweep(ccw, large, sweep)))
}
/// The signed sweep (CCW positive) for a chord sweep `ccw` in `[0, 2π)`: the centre is
/// already chosen so that the magnitude matches `large`, so only the direction is left.
fn pick_sweep(ccw: f64, large: bool, sweep: bool) -> f64 {
let tau = std::f64::consts::TAU;
let eps = f64::EPSILON;
if sweep {
if ccw <= eps { if large { tau } else { eps } } else { ccw }
} else if ccw >= tau - eps {
if large { -tau } else { -eps }
} else {
ccw - tau
}
}
/// Endpoint → centre parameterisation for a rotated elliptical arc (SVG F.6.5), in the
/// frame the points are given in. Returns the centre, the start parameter and the signed
/// sweep.
pub fn elliptical_params(p0: Point, p1: Point, rx: f64, ry: f64, phi: f64, large: bool, sweep: bool) -> Option<(Point, f64, f64)> {
if rx <= 0.0 || ry <= 0.0 {
return None;
}
let (sphi, cphi) = phi.sin_cos();
let dx = (p0.x - p1.x) / 2.0;
let dy = (p0.y - p1.y) / 2.0;
let x1 = cphi * dx + sphi * dy;
let y1 = -sphi * dx + cphi * dy;
let (rx, ry) = {
let lambda = x1 * x1 / (rx * rx) + y1 * y1 / (ry * ry);
if lambda > 1.0 {
let s = lambda.sqrt();
(rx * s, ry * s)
} else {
(rx, ry)
}
};
let num = rx * rx * ry * ry - rx * rx * y1 * y1 - ry * ry * x1 * x1;
let den = rx * rx * y1 * y1 + ry * ry * x1 * x1;
let coef = if sweep != large { 1.0 } else { -1.0 } * (num.max(0.0) / den.max(f64::MIN_POSITIVE)).sqrt();
let cxp = coef * rx * y1 / ry;
let cyp = -coef * ry * x1 / rx;
let center = Point::new(cphi * cxp - sphi * cyp + (p0.x + p1.x) / 2.0, sphi * cxp + cphi * cyp + (p0.y + p1.y) / 2.0);
let angle = |ux: f64, uy: f64, vx: f64, vy: f64| {
let dot = ux * vx + uy * vy;
let det = ux * vy - uy * vx;
let denom = (ux.hypot(uy) * vx.hypot(vy)).max(f64::MIN_POSITIVE);
(dot / denom).clamp(-1.0, 1.0).acos().copysign(det)
};
let (ux, uy) = ((x1 - cxp) / rx, (y1 - cyp) / ry);
let (vx, vy) = ((-x1 - cxp) / rx, (-y1 - cyp) / ry);
let theta = angle(1.0, 0.0, ux, uy);
let ccw = angle(ux, uy, vx, vy).rem_euclid(std::f64::consts::TAU);
Some((center, theta, pick_sweep(ccw, large, sweep)))
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
#[test]
fn resolves_relative_and_smooth_commands_without_flattening_arcs() {
let paths = parse_path("M1 2 l3 4 C5 6 7 8 9 10 s2 3 4 5 A6 7 30 0110 12 z").unwrap();
assert_eq!(paths.len(), 1);
assert!(paths[0].closed);
assert_eq!(paths[0].start, Point::new(1.0, 2.0));
assert_eq!(paths[0].segs[0], Segment::Line(Point::new(4.0, 6.0)));
assert_eq!(paths[0].segs[2], Segment::Cubic(Point::new(11.0, 12.0), Point::new(11.0, 13.0), Point::new(13.0, 15.0)));
assert_eq!(paths[0].segs[3], Segment::Arc { rx: 6.0, ry: 7.0, rot: 30.0, large: false, sweep: true, end: Point::new(10.0, 12.0) });
}
#[test]
fn smooth_quadratic_consumes_both_coordinates() {
let paths = parse_path("M0 0 Q3 3 6 0 T12 0").unwrap();
assert_eq!(paths[0].segs[1], Segment::Cubic(Point::new(8.0, -2.0), Point::new(10.0, -2.0), Point::new(12.0, 0.0)));
}
#[test]
fn arc_centers_keep_radius_correction_and_sweep() {
let (center, delta) = arc_center_circular(Point::new(0.0, 0.0), Point::new(10.0, 0.0), 2.0, false, true).unwrap();
assert!((center.x - 5.0).abs() < 1e-10);
assert!(center.y.abs() < 1e-10);
assert!((delta - std::f64::consts::PI).abs() < 1e-10);
let (center, start, sweep) = elliptical_params(Point::new(0.0, 0.0), Point::new(10.0, 0.0), 2.0, 1.0, 0.0, false, true).unwrap();
assert!((center.x - 5.0).abs() < 1e-10);
assert!(center.y.abs() < 1e-10 && start.is_finite());
assert!((sweep - std::f64::consts::PI).abs() < 1e-10);
}
#[test]
fn rejects_invalid_flags_and_limits_segments() {
assert!(parse_path("M0 0 A1 1 0 5 1 2 2").is_err());
assert!(parse_path("M0 0 L").is_err());
let excessive = format!("M0 0{}", " L1 1".repeat(MAX_PATH_SEGMENTS));
assert!(parse_path(&excessive).is_err());
}
}
+37 -2
View File
@@ -71,6 +71,12 @@ pub fn text<'a>(bytes: &'a [u8], limits: &Limits) -> Result<Cow<'a, str>, Error>
/// Parses already-decoded SVG text and checks it against `limits`.
pub fn parse_text<'a>(svg: &'a str, limits: &Limits) -> Result<roxmltree::Document<'a>, Error> {
parse_text_with_depth(svg, limits).map(|(xml, _, _)| xml)
}
/// [`parse_text`], with the source nesting: the deepest element nesting (markup entities count
/// ten times) and the deepest stack of open elements (a self-closing leaf opens none).
pub fn parse_text_with_depth<'a>(svg: &'a str, limits: &Limits) -> Result<(roxmltree::Document<'a>, usize, usize), Error> {
if svg.len() > limits.bytes {
return Err(Error::Text(crate::svgz::Error::TooLarge(limits.bytes)));
}
@@ -83,9 +89,38 @@ pub fn parse_text<'a>(svg: &'a str, limits: &Limits) -> Result<roxmltree::Docume
if crate::guard::too_wide(svg, limits.attributes, limits.attribute_work) {
return Err(Error::TooWide(limits.attributes));
}
if crate::guard::deeper_than(svg, limits.depth) {
let prescan = crate::guard::prescan(svg, limits.depth);
if prescan.too_deep {
return Err(Error::TooDeep(limits.depth));
}
let options = roxmltree::ParsingOptions { allow_dtd: true, nodes_limit: limits.xml_nodes, ..Default::default() };
roxmltree::Document::parse_with_options(svg, options).map_err(|e| Error::Xml(e.to_string()))
let xml = roxmltree::Document::parse_with_options(svg, options).map_err(|e| Error::Xml(e.to_string()))?;
Ok((xml, prescan.depth, prescan.open_depth))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parsed_tree_reports_source_nesting_depth() -> Result<(), Error> {
let limits = Limits { depth: 4, ..Default::default() };
let (document, depth, open_depth) = parse_text_with_depth("<svg><g><path/></g></svg>", &limits)?;
assert!(document.root_element().has_tag_name("svg"));
// Every element is a level (svg, g, path); a self-closing leaf opens none (svg, g).
assert_eq!(depth, 3);
assert_eq!(open_depth, 2);
let simple = parse_text("<svg/>", &limits)?;
assert!(simple.root_element().has_tag_name("svg"));
Ok(())
}
#[test]
fn source_depth_and_xml_errors_keep_their_specific_kind() {
let shallow = Limits { depth: 1, ..Default::default() };
assert!(matches!(parse_text_with_depth("<svg><g></g></svg>", &shallow), Err(Error::TooDeep(1))));
let normal = Limits::default();
assert!(matches!(parse_text_with_depth("<svg><g></svg>", &normal), Err(Error::Xml(_))));
}
}
+104 -20
View File
@@ -112,13 +112,19 @@ pub enum Error {
/// usvg's own error.
#[error("invalid SVG: {0}")]
Parse(String),
/// The root viewport is missing or has dimensions this SVG helper cannot preserve.
#[error("invalid SVG root viewport: {0}")]
Viewport(String),
/// The rewritten SVG would exceed the caller's output byte budget.
#[error("rewritten SVG exceeds {0} bytes")]
OutputTooLarge(usize),
}
/// The SVG text of the bytes of an SVG or SVGZ file, checked against `limits`: what [`parse`]
/// hands usvg. For a caller that edits the text before it parses ([`parse_text`]).
pub fn text<'a>(bytes: &'a [u8], limits: &Limits) -> Result<Cow<'a, str>, Error> {
let text = svgz::text(bytes, limits.bytes)?;
checked(&text, limits)?;
preflight(&text, limits)?;
Ok(text)
}
@@ -130,8 +136,7 @@ pub fn parse(bytes: &[u8], limits: &Limits, options: &usvg::Options<'_>) -> Resu
/// [`parse`] for SVG text the caller already holds.
pub fn parse_text(svg: &str, limits: &Limits, options: &usvg::Options<'_>) -> Result<usvg::Tree, Error> {
let xml = checked(svg, limits)?;
usvg::Tree::from_xmltree(&xml, options).map_err(|e| Error::Parse(e.to_string()))
preflight(svg, limits)?.parse(options)
}
/// Read the root SVG's unitless width and height without constructing a rendering tree.
@@ -139,8 +144,8 @@ pub fn parse_text(svg: &str, limits: &Limits, options: &usvg::Options<'_>) -> Re
/// Lengths with units, percentages, missing dimensions, and non-SVG roots return `Ok(None)`;
/// malformed or over-limit XML returns the same bounded parsing error as [`parse_text`].
pub fn root_unitless_size(svg: &str, limits: &Limits) -> Result<Option<(f64, f64)>, Error> {
let xml = checked(svg, limits)?;
let root = xml.root_element();
let checked = preflight(svg, limits)?;
let root = checked.xml.root_element();
if root.tag_name().name() != "svg" {
return Ok(None);
}
@@ -152,8 +157,30 @@ pub fn root_unitless_size(svg: &str, limits: &Limits) -> Result<Option<(f64, f64
Ok(Some((width, height)))
}
/// Every check on SVG text, cheapest first; the XML it parses to on the way.
fn checked<'s>(svg: &'s str, limits: &Limits) -> Result<roxmltree::Document<'s>, Error> {
/// SVG text after shared byte, entity, attribute, XML and expansion-depth checks.
/// Keep it opaque so consumers use the same checked tree and don't reparse XML locally.
pub struct Preflight<'s> {
xml: roxmltree::Document<'s>,
depth: usize,
/// [`height`]: the nesting usvg converts, references followed.
height: usize,
}
impl Preflight<'_> {
/// The deepest stack of open source elements, before references are followed; a
/// self-closing leaf opens no level (`<svg><g><path/></g></svg>` is 2).
pub fn depth(&self) -> usize {
self.depth
}
/// Converts this already-checked XML into the configured usvg tree.
pub fn parse(self, options: &usvg::Options<'_>) -> Result<usvg::Tree, Error> {
usvg::Tree::from_xmltree(&self.xml, options).map_err(|e| Error::Parse(e.to_string()))
}
}
/// Checks already-decoded SVG text once, retaining the parsed XML for both depth policy and tree conversion.
pub fn preflight<'s>(svg: &'s str, limits: &Limits) -> Result<Preflight<'s>, Error> {
let preflight_limits = crate::preflight::Limits {
bytes: limits.bytes,
depth: limits.depth,
@@ -163,7 +190,7 @@ fn checked<'s>(svg: &'s str, limits: &Limits) -> Result<roxmltree::Document<'s>,
attribute_work: limits.attribute_work,
xml_nodes: limits.xml_nodes,
};
let xml = crate::preflight::parse_text(svg, &preflight_limits).map_err(|e| match e {
let (xml, _, depth) = crate::preflight::parse_text_with_depth(svg, &preflight_limits).map_err(|e| match e {
crate::preflight::Error::Text(e) => Error::Text(e),
crate::preflight::Error::Entities => Error::Entities,
crate::preflight::Error::EntityMarkup => Error::EntityMarkup,
@@ -171,10 +198,69 @@ fn checked<'s>(svg: &'s str, limits: &Limits) -> Result<roxmltree::Document<'s>,
crate::preflight::Error::TooWide(attributes) => Error::TooWide(attributes),
crate::preflight::Error::Xml(msg) => Error::Xml(msg),
})?;
if height(&xml, limits.tree_depth)?.is_none() {
let Some(height) = height(&xml, limits.tree_depth)? else {
return Err(Error::TooDeep(limits.tree_depth));
};
Ok(Preflight { xml, depth, height })
}
/// Dimensions of an SVG viewport in SVG user units.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Viewport {
pub width: f64,
pub height: f64,
}
/// Wraps a validated SVG root in a new viewport while preserving the original root as content.
/// The original root must have finite, positive pixel or point dimensions, and the wrapped
/// output must still pass [`preflight`] under `limits`.
pub fn rewrite_root_viewport(svg: &str, target: Viewport, limits: &Limits, output_limit: usize) -> Result<String, Error> {
if !target.width.is_finite() || !target.height.is_finite() || target.width <= 0.0 || target.height <= 0.0 {
return Err(Error::Viewport("target dimensions must be finite and positive".into()));
}
Ok(xml)
let checked = preflight(svg, limits)?;
let root = checked.xml.root_element();
if root.tag_name().name() != "svg" {
return Err(Error::Viewport("root element is not svg".into()));
}
let root_dimension = |key: &str| {
let value = root.attribute(key)?;
let value = value.trim();
let (number, scale) = match value.strip_suffix("pt") {
Some(points) => (points, 4.0 / 3.0),
None => (value.strip_suffix("px").unwrap_or(value), 1.0),
};
number.parse::<f64>().ok().map(|n| n * scale).filter(|n| n.is_finite() && *n > 0.0)
};
let (width, height) = root_dimension("width")
.zip(root_dimension("height"))
.ok_or_else(|| Error::Viewport("source has no finite pixel or point dimensions".into()))?;
let range = root.range();
let preamble = svg.get(..range.start).ok_or_else(|| Error::Viewport("invalid XML preamble range".into()))?;
let inner = svg.get(range).ok_or_else(|| Error::Viewport("invalid root element range".into()))?;
let prefix = format!(
r#"<svg xmlns="http://www.w3.org/2000/svg" width="{}" height="{}" viewBox="0 0 {} {}" preserveAspectRatio="none">"#,
target.width, target.height, width, height
);
let len = preamble
.len()
.checked_add(prefix.len())
.and_then(|n| n.checked_add(inner.len()))
.and_then(|n| n.checked_add(6))
.ok_or(Error::OutputTooLarge(output_limit))?;
if len > output_limit {
return Err(Error::OutputTooLarge(output_limit));
}
let mut output = String::new();
output.try_reserve_exact(len).map_err(|_| Error::OutputTooLarge(output_limit))?;
output.push_str(preamble);
output.push_str(&prefix);
output.push_str(inner);
output.push_str("</svg>");
// The wrapper adds a level, so a source at the depth limit can come out over it: check the
// output under the limits `parse_text` applies rather than return text it would refuse.
preflight(&output, limits)?;
Ok(output)
}
/// Properties whose value an element's descendants use too: the paint server they name is
@@ -376,8 +462,8 @@ impl ImageResolver {
/// Nested SVGs are checked automatically. The scan shares the normal XML limits and
/// streaming-validates URL encoding without allocating another decoded image buffer.
pub fn check_document(&self, svg: &str) -> Result<(), Error> {
let xml = checked(svg, &self.limits)?;
account_invalid_data_urls(&xml, &self.used);
let checked = preflight(svg, &self.limits)?;
account_invalid_data_urls(&checked.xml, &self.used);
Ok(())
}
@@ -520,8 +606,8 @@ fn embedded(used: &Used, limits: &Limits, data: &[u8], options: &usvg::Options<'
return None;
}
used.bytes.fetch_add(text.len(), Ordering::Relaxed);
let xml = match checked(&text, limits) {
Ok(xml) => xml,
let checked = match preflight(&text, limits) {
Ok(checked) => checked,
// Decoding UTF-16 or Latin-1 can exceed the text cap after the
// raw/inflated bytes fitted. This is a resource refusal, not invalid XML.
Err(Error::Text(svgz::Error::TooLarge(_))) => {
@@ -538,10 +624,8 @@ fn embedded(used: &Used, limits: &Limits, data: &[u8], options: &usvg::Options<'
return None;
}
};
let Some(xml_depth) = height(&xml, limits.tree_depth).ok().flatten() else {
used.svg_limit.fetch_add(1, Ordering::Relaxed);
return None;
};
// The nesting usvg converts, references followed, not the source depth alone.
let xml_depth = checked.height;
let total_depth = used.xml_depth.load(Ordering::Relaxed).checked_add(xml_depth);
let Some(total_depth) = total_depth.filter(|depth| *depth <= limits.tree_depth) else {
used.svg_limit.fetch_add(1, Ordering::Relaxed);
@@ -550,8 +634,8 @@ fn embedded(used: &Used, limits: &Limits, data: &[u8], options: &usvg::Options<'
let previous_depth = used.xml_depth.swap(total_depth, Ordering::Relaxed);
let depth = used.depth.fetch_add(1, Ordering::Relaxed).saturating_add(1);
used.svg_depth.fetch_max(depth, Ordering::Relaxed);
account_invalid_data_urls(&xml, used);
let tree = usvg::Tree::from_xmltree(&xml, options);
account_invalid_data_urls(&checked.xml, used);
let tree = checked.parse(options);
used.xml_depth.store(previous_depth, Ordering::Relaxed);
used.depth.fetch_sub(1, Ordering::Relaxed);
match tree {
+103 -2
View File
@@ -292,7 +292,7 @@ mod resource_limit_usage {
assert_eq!(svgz::inflate(&data, cap).unwrap().len(), cap, "raw bytes fit exactly");
assert_eq!(svgz::text(&data, cap).unwrap().len(), decoded.len(), "decoding itself succeeds");
let limits = Limits { bytes: cap, embedded_bytes: decoded.len(), ..shallow() };
assert!(matches!(checked(&decoded, &limits), Err(Error::Text(svgz::Error::TooLarge(n))) if n == cap));
assert!(matches!(preflight(&decoded, &limits), Err(Error::Text(svgz::Error::TooLarge(n))) if n == cap));
let image = data_image(&data);
let (found, usage) = resolved(&svg(&image), limits, 1);
assert!(found.is_empty(), "{encoding}, gzip {gzip}");
@@ -312,7 +312,7 @@ mod resource_limit_usage {
let decoded = svgz::decode(&raw).unwrap();
let limits = Limits { bytes: decoded.len(), embedded_bytes: raw.len(), ..shallow() };
assert!(decoded.len() > limits.embedded_bytes);
checked(&decoded, &limits).unwrap(); // The independent per-image cap allows this complete XML.
preflight(&decoded, &limits).unwrap(); // The independent per-image cap allows this complete XML.
for gzip in [false, true] {
let data = if gzip { svgz::compress(&raw) } else { raw.clone() };
assert_eq!(svgz::inflate(&data, limits.embedded_bytes).unwrap().len(), raw.len());
@@ -584,3 +584,104 @@ mod invalid_image_accounting {
assert_eq!(report.raster_limit_images, 1);
}
}
#[test]
fn preflight_keeps_source_depth_and_parses_the_checked_tree() {
let text = svg("<g><rect width='1' height='1'/></g>");
let checked = preflight(&text, &Limits::default()).unwrap();
// svg and g are open; the self-closing rect opens no level.
assert_eq!(checked.depth(), 2);
let tree = checked.parse(&options()).unwrap();
assert_eq!(tree.size().width(), 10.0);
assert!(matches!(preflight(&svg(&groups(30)), &shallow()), Err(Error::TooDeep(24))));
}
#[test]
fn preflight_matches_parse_text_refusals() {
for text in ["<svg", "<svg xmlns='http://www.w3.org/2000/svg'><g></svg>"] {
assert!(matches!(preflight(text, &Limits::default()), Err(Error::Xml(_))));
assert!(matches!(parse_text(text, &Limits::default(), &options()), Err(Error::Xml(_))));
}
}
#[test]
fn rewrite_root_viewport_wraps_the_root_and_keeps_the_preamble() {
let source = concat!(
"<?xml version='1.0'?>\n<!DOCTYPE svg [<!ENTITY w '4'>]>\n",
"<svg xmlns='http://www.w3.org/2000/svg' width='20' height='10' viewBox='0 0 2 1'>",
"<rect width='&w;' height='1'/></svg>"
);
let out = rewrite_root_viewport(source, Viewport { width: 40.0, height: 30.0 }, &Limits::default(), 4096).unwrap();
assert!(out.starts_with("<?xml version='1.0'?>\n<!DOCTYPE svg [<!ENTITY w '4'>]>\n<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"40\" height=\"30\" viewBox=\"0 0 20 10\" preserveAspectRatio=\"none\"><svg "));
assert!(out.ends_with("</svg></svg>"));
let tree = parse_text(&out, &Limits::default(), &options()).unwrap();
assert_eq!((tree.size().width(), tree.size().height()), (40.0, 30.0));
}
#[test]
fn rewrite_root_viewport_reads_points_and_pixels() {
let points = rewrite_root_viewport(
"<svg xmlns='http://www.w3.org/2000/svg' width='72pt' height='36pt'/>",
Viewport { width: 1.0, height: 1.0 },
&Limits::default(),
4096,
)
.unwrap();
assert!(points.contains("viewBox=\"0 0 96 48\""));
let pixels = rewrite_root_viewport(
"<svg xmlns='http://www.w3.org/2000/svg' width='12px' height='8'/>",
Viewport { width: 1.0, height: 1.0 },
&Limits::default(),
4096,
)
.unwrap();
assert!(pixels.contains("viewBox=\"0 0 12 8\""));
}
#[test]
fn rewrite_root_viewport_refusals() {
let limits = Limits::default();
let one = Viewport { width: 1.0, height: 1.0 };
let sized = "<svg xmlns='http://www.w3.org/2000/svg' width='10' height='10'/>";
for target in [
Viewport { width: f64::NAN, height: 1.0 },
Viewport { width: 1.0, height: f64::INFINITY },
Viewport { width: 0.0, height: 1.0 },
Viewport { width: 1.0, height: -2.0 },
] {
assert!(matches!(rewrite_root_viewport(sized, target, &limits, 4096), Err(Error::Viewport(_))));
}
assert!(matches!(rewrite_root_viewport("<html width='10' height='10'/>", one, &limits, 4096), Err(Error::Viewport(_))));
for source in [
"<svg xmlns='http://www.w3.org/2000/svg'/>",
"<svg xmlns='http://www.w3.org/2000/svg' width='50%' height='10'/>",
"<svg xmlns='http://www.w3.org/2000/svg' width='10mm' height='10'/>",
"<svg xmlns='http://www.w3.org/2000/svg' width='0' height='10'/>",
"<svg xmlns='http://www.w3.org/2000/svg' width='1e400' height='10'/>",
] {
assert!(matches!(rewrite_root_viewport(source, one, &limits, 4096), Err(Error::Viewport(_))), "{source}");
}
assert!(matches!(rewrite_root_viewport("<svg", one, &limits, 4096), Err(Error::Xml(_))));
let fits = rewrite_root_viewport(sized, one, &limits, 4096).unwrap();
assert_eq!(rewrite_root_viewport(sized, one, &limits, fits.len()).unwrap(), fits);
assert!(matches!(rewrite_root_viewport(sized, one, &limits, fits.len() - 1), Err(Error::OutputTooLarge(n)) if n == fits.len() - 1));
}
#[test]
fn rewrite_root_viewport_output_stays_within_the_limits() {
let limits = shallow();
let one = Viewport { width: 1.0, height: 1.0 };
let mut refused_at_the_limit = false;
for n in 0..limits.depth {
let source = svg(&groups(n));
if preflight(&source, &limits).is_err() {
break;
}
match rewrite_root_viewport(&source, one, &limits, 1 << 20) {
Ok(out) => assert!(parse_text(&out, &limits, &options()).is_ok(), "{n} groups"),
Err(Error::TooDeep(_)) => refused_at_the_limit = true,
Err(e) => panic!("{n} groups: {e:?}"),
}
}
assert!(refused_at_the_limit, "a source at the depth limit is refused, not wrapped past it");
}
+27 -1
View File
@@ -86,18 +86,36 @@ impl Attribute {
pub fn translate_scale(x: f64, y: f64, scale_x: f64, scale_y: f64) -> Self {
Self { name: "transform".into(), value: Value::TranslateScale { x, y, scale_x, scale_y } }
}
/// A translate/scale transform with three decimal places for positions and four for scales.
pub fn translate_scale_fixed(x: f64, y: f64, scale_x: f64, scale_y: f64) -> Self {
Self::text("transform", format!("translate({} {}) scale({} {})", num(x, 3), num(y, 3), num(scale_x, 4), num(scale_y, 4)))
}
}
impl Scene {
/// Serialize the scene as an SVG 1.1 document.
pub fn write(&self) -> String {
self.write_impl(false)
}
/// Serialize the root viewBox with three decimal places for stable fixed-width output.
pub fn write_fixed_view_box(&self) -> String {
self.write_impl(true)
}
fn write_impl(&self, fixed: bool) -> String {
let mut writer = SvgWriter::new();
let view_box = if fixed {
format!("{} {} {} {}", num(self.view_box[0], 3), num(self.view_box[1], 3), num(self.view_box[2], 3), num(self.view_box[3], 3))
} else {
view_box_data(self.view_box)
};
writer
.root()
.attr("version", "1.1")
.attr("width", format!("{}mm", num(self.width_mm, 3)))
.attr("height", format!("{}mm", num(self.height_mm, 3)))
.attr("viewBox", view_box_data(self.view_box))
.attr("viewBox", view_box)
.open();
write_elements(&mut writer, &self.elements, 1);
writer.line(0);
@@ -307,6 +325,14 @@ mod tests {
p
}
#[test]
fn scene_can_keep_fixed_view_box_without_changing_default_output() {
let scene = Scene { width_mm: 100.0, height_mm: 150.0, view_box: [0.0, 0.0, 100.0, 150.0], elements: vec![] };
assert!(scene.write().contains("viewBox=\"0 0 100 150\""));
assert!(scene.write_fixed_view_box().contains("viewBox=\"0.000 0.000 100.000 150.000\""));
assert_eq!(Attribute::translate_scale_fixed(6.0, 46.0, 0.5, -0.5).value, Value::Text("translate(6.000 46.000) scale(0.5000 -0.5000)".into()));
}
#[test]
fn numbers_have_fixed_decimals_and_are_never_non_finite() {
assert_eq!(num(1.5, 3).to_string(), "1.500");
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "craft-tcraft"
description = "Streaming binary payloads of TextureCraft project archives"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-zip = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
+14
View File
@@ -0,0 +1,14 @@
# craft-tcraft
Streaming neutral `TCTX` binary payloads used inside TextureCraft `.tcraft` projects. Sparse
paint data stores 64×64 tiles of little-endian `u16` components; baked maps store dense
little-endian `f32` values. This crate does not yet define the project JSON schema or ZIP
envelope and does not depend on TextureCraft's app types.
`read_tiles` validates the expected dimensions and components, bounds tile count, rejects
out-of-range and repeated tile positions, and delivers one owned tile at a time. `read_baked`
validates dimensions and declared length and decodes in bounded chunks. Both consume the same
caller-owned `craft_zip::Budget` used for the surrounding project and reject trailing data.
`write_tiles` and `write_baked` stream their bodies rather than copying an entire image; a caller
must discard an incomplete output if a write fails. Limits and ownership rules beyond this
binary format remain with the project reader.
+428
View File
@@ -0,0 +1,428 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
//! Streaming `TCTX` tile and baked-map payloads in TextureCraft `.tcraft` archives.
//!
//! This codec handles the neutral binary payload, not the application's project model or ZIP
//! envelope. Reads use a caller-owned budget shared with other archive entries. No reader opens
//! a file or reserves memory based on a claimed payload before checking it.
use std::collections::{BTreeMap, HashSet};
use std::io::{self, Read, Write};
use craft_zip::Budget;
use serde::{Deserialize, Serialize};
use serde_json::Value;
pub const TILE_SIDE: u32 = 64;
pub const TILE_AREA: usize = 64 * 64;
pub const HEADER_BYTES: u64 = 24;
pub const VERSION: u32 = 1;
const MAGIC: &[u8; 4] = b"TCTX";
const CHUNK: usize = 1 << 16;
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("invalid TCTX payload: {0}")]
Invalid(String),
#[error("TCTX version {0} is newer than supported")]
NewerVersion(u32),
#[error("TCTX budget: {0}")]
Budget(#[from] craft_zip::Exceeded),
#[error("TCTX limit: {0}")]
Limit(String),
#[error("TCTX I/O: {0}")]
Io(#[from] io::Error),
}
/// Neutral top-level project schema. Nested app-domain values and unknown fields remain JSON
/// so they round-trip without requiring TextureCraft's in-memory model.
#[derive(Clone, Debug, PartialEq, Deserialize)]
pub struct ProjectDocument {
pub format_version: u32,
pub name: String,
pub mesh: String,
pub normal_format: Value,
pub texture_sets: Vec<Value>,
pub layers: BTreeMap<String, Value>,
pub next_id: u64,
pub display: Value,
#[serde(default)]
pub cameras: Vec<Value>,
#[serde(flatten)]
pub extra: BTreeMap<String, Value>,
}
impl Serialize for ProjectDocument {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
use serde::ser::{Error as _, SerializeMap as _};
const RESERVED: &[&str] = &["format_version", "name", "mesh", "normal_format", "texture_sets", "layers", "next_id", "display", "cameras"];
if self.extra.keys().any(|key| RESERVED.contains(&key.as_str())) {
return Err(S::Error::custom("an extra project field duplicates a known field"));
}
let mut map = serializer.serialize_map(Some(9 + self.extra.len()))?;
map.serialize_entry("format_version", &self.format_version)?;
map.serialize_entry("name", &self.name)?;
map.serialize_entry("mesh", &self.mesh)?;
map.serialize_entry("normal_format", &self.normal_format)?;
map.serialize_entry("texture_sets", &self.texture_sets)?;
map.serialize_entry("layers", &self.layers)?;
map.serialize_entry("next_id", &self.next_id)?;
map.serialize_entry("display", &self.display)?;
map.serialize_entry("cameras", &self.cameras)?;
for (key, value) in &self.extra {
map.serialize_entry(key, value)?;
}
map.end()
}
}
/// Read only the version before an application applies its own recovery policy. Serde's
/// structured parse rejects a duplicate or invalid version field, like the project reader.
pub fn project_version(bytes: &[u8]) -> Result<u32, serde_json::Error> {
#[derive(Deserialize)]
struct Version {
format_version: u32,
}
Ok(serde_json::from_slice::<Version>(bytes)?.format_version)
}
/// Width, height and number of components expected by the enclosing project schema.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Layout {
pub width: u32,
pub height: u32,
pub components: usize,
}
#[derive(Clone, Copy, Debug)]
struct Header {
layout: Layout,
count: u32,
}
fn charge(budget: &mut Budget, n: u64) -> Result<(), Error> {
budget.charge(n).map_err(Error::from)
}
fn read_header(reader: &mut (impl Read + ?Sized), budget: &mut Budget) -> Result<Header, Error> {
charge(budget, HEADER_BYTES)?;
let mut bytes = [0u8; HEADER_BYTES as usize];
reader.read_exact(&mut bytes)?;
if bytes.get(..4) != Some(MAGIC.as_slice()) {
return Err(Error::Invalid("bad magic".into()));
}
let word = |i: usize| bytes.get(i * 4..i * 4 + 4).map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]])).unwrap_or(0);
let version = word(1);
if version > VERSION {
return Err(Error::NewerVersion(version));
}
Ok(Header { layout: Layout { width: word(2), height: word(3), components: word(4) as usize }, count: word(5) })
}
fn write_header(writer: &mut (impl Write + ?Sized), layout: Layout, count: u32) -> Result<(), Error> {
let components = u32::try_from(layout.components).map_err(|_| Error::Limit("too many components".into()))?;
writer.write_all(MAGIC)?;
for value in [VERSION, layout.width, layout.height, components, count] {
writer.write_all(&value.to_le_bytes())?;
}
Ok(())
}
fn expect_end(reader: &mut (impl Read + ?Sized)) -> Result<(), Error> {
let mut byte = [0u8; 1];
if reader.read(&mut byte)? != 0 {
return Err(Error::Invalid("trailing data".into()));
}
Ok(())
}
fn tile_dimensions(layout: Layout) -> Result<(u32, u32, usize), Error> {
if layout.width == 0 || layout.height == 0 || layout.components == 0 {
return Err(Error::Invalid("empty tile layout".into()));
}
let x = layout.width.div_ceil(TILE_SIDE);
let y = layout.height.div_ceil(TILE_SIDE);
let bytes = TILE_AREA.checked_mul(layout.components).and_then(|n| n.checked_mul(2)).ok_or_else(|| Error::Limit("tile is too large".into()))?;
Ok((x, y, bytes))
}
/// Decode tiles one at a time, transferring each tile to the callback.
/// Positions and duplicate tiles are checked before delivery; the entry must end exactly.
pub fn read_tiles(
reader: &mut (impl Read + ?Sized),
expected: Layout,
max_texels: u64,
budget: &mut Budget,
mut tile: impl FnMut(u32, u32, Vec<u16>) -> Result<(), Error>,
) -> Result<(), Error> {
let header = read_header(reader, budget)?;
let texels = u64::from(expected.width) * u64::from(expected.height);
if texels == 0 || texels > max_texels {
return Err(Error::Limit("tile image exceeds its texel limit".into()));
}
if header.layout != expected {
return Err(Error::Invalid("tile layout differs from the project".into()));
}
let (tiles_x, tiles_y, bytes_per_tile) = tile_dimensions(expected)?;
if u64::from(header.count) > u64::from(tiles_x) * u64::from(tiles_y) {
return Err(Error::Invalid("more tiles than the image holds".into()));
}
let mut bytes = Vec::new();
let mut seen = HashSet::new();
for _ in 0..header.count {
let payload = u64::try_from(bytes_per_tile).map_err(|_| Error::Limit("tile is too large".into()))?.saturating_add(8);
charge(budget, payload)?;
if bytes.is_empty() {
bytes.try_reserve_exact(bytes_per_tile).map_err(|_| Error::Limit("tile allocation failed".into()))?;
bytes.resize(bytes_per_tile, 0);
}
let mut pos = [0u8; 8];
reader.read_exact(&mut pos)?;
let x = u32::from_le_bytes([pos[0], pos[1], pos[2], pos[3]]);
let y = u32::from_le_bytes([pos[4], pos[5], pos[6], pos[7]]);
if x >= tiles_x || y >= tiles_y || seen.contains(&(x, y)) {
return Err(Error::Invalid(format!("bad or repeated tile ({x}, {y})")));
}
seen.try_reserve(1).map_err(|_| Error::Limit("tile index allocation failed".into()))?;
seen.insert((x, y));
reader.read_exact(&mut bytes)?;
let mut values = Vec::new();
values.try_reserve_exact(bytes_per_tile / 2).map_err(|_| Error::Limit("tile allocation failed".into()))?;
values.extend(bytes.as_chunks::<2>().0.iter().map(|b| u16::from_le_bytes(*b)));
tile(x, y, values)?;
}
expect_end(reader)
}
/// Write tiles in caller order, without buffering the image. A failure may leave a partial
/// entry; callers writing a project should discard the incomplete output.
pub fn write_tiles<'a>(
writer: &mut (impl Write + ?Sized),
layout: Layout,
count: u32,
tiles: impl IntoIterator<Item = (u32, u32, &'a [u16])>,
) -> Result<(), Error> {
let (tiles_x, tiles_y, bytes_per_tile) = tile_dimensions(layout)?;
if u64::from(count) > u64::from(tiles_x) * u64::from(tiles_y) {
return Err(Error::Invalid("more tiles than the image holds".into()));
}
write_header(writer, layout, count)?;
let mut seen = HashSet::new();
let mut bytes = Vec::new();
let mut written = 0u32;
for (x, y, values) in tiles {
if written >= count || x >= tiles_x || y >= tiles_y || seen.contains(&(x, y)) || values.len() != bytes_per_tile / 2 {
return Err(Error::Invalid("bad, repeated or incorrectly sized tile".into()));
}
seen.try_reserve(1).map_err(|_| Error::Limit("tile index allocation failed".into()))?;
seen.insert((x, y));
if bytes.is_empty() {
bytes.try_reserve_exact(bytes_per_tile).map_err(|_| Error::Limit("tile allocation failed".into()))?;
}
bytes.clear();
bytes.extend(values.iter().flat_map(|v| v.to_le_bytes()));
writer.write_all(&x.to_le_bytes())?;
writer.write_all(&y.to_le_bytes())?;
writer.write_all(&bytes)?;
written += 1;
}
if written != count {
return Err(Error::Invalid("tile count differs from its data".into()));
}
Ok(())
}
/// Read a dense f32 map, validating declared size and charging its shared budget first.
pub fn read_baked(
reader: &mut (impl Read + ?Sized),
declared_bytes: u64,
components: usize,
max_texels: u64,
budget: &mut Budget,
) -> Result<(Layout, Vec<f32>), Error> {
let header = read_header(reader, budget)?;
let layout = header.layout;
let texels = u64::from(layout.width) * u64::from(layout.height);
if texels == 0 || texels > max_texels || layout.components != components || components == 0 {
return Err(Error::Invalid("bad baked-map dimensions or components".into()));
}
let count = texels.checked_mul(components as u64).ok_or_else(|| Error::Limit("too many map values".into()))?;
let payload = count.checked_mul(4).ok_or_else(|| Error::Limit("map is too large".into()))?;
if declared_bytes != HEADER_BYTES.checked_add(payload).ok_or_else(|| Error::Limit("map is too large".into()))? {
return Err(Error::Invalid(format!("{declared_bytes} bytes for a {}×{}×{} map", layout.width, layout.height, layout.components)));
}
charge(budget, payload)?;
let count = usize::try_from(count).map_err(|_| Error::Limit("too many map values".into()))?;
let mut values = Vec::new();
let chunk_bytes = CHUNK.min(count) * 4;
let mut bytes = Vec::new();
bytes.try_reserve_exact(chunk_bytes).map_err(|_| Error::Limit("map chunk allocation failed".into()))?;
bytes.resize(chunk_bytes, 0);
while values.len() < count {
let n = CHUNK.min(count - values.len());
let chunk = bytes.get_mut(..n * 4).ok_or_else(|| Error::Invalid("bad map chunk".into()))?;
reader.read_exact(chunk)?;
values.try_reserve(n).map_err(|_| Error::Limit("map allocation failed".into()))?;
values.extend(chunk.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)));
}
expect_end(reader)?;
Ok((layout, values))
}
/// Write a dense f32 map in bounded chunks without constructing a second copy of its payload.
pub fn write_baked(writer: &mut (impl Write + ?Sized), layout: Layout, values: &[f32]) -> Result<(), Error> {
let count = u64::from(layout.width).checked_mul(u64::from(layout.height)).and_then(|n| n.checked_mul(layout.components as u64));
if layout.width == 0 || layout.height == 0 || layout.components == 0 || count != Some(values.len() as u64) {
return Err(Error::Invalid("map dimensions differ from its data".into()));
}
write_header(writer, layout, 0)?;
let mut bytes = Vec::new();
bytes.try_reserve_exact(CHUNK * 4).map_err(|_| Error::Limit("map chunk allocation failed".into()))?;
for chunk in values.chunks(CHUNK) {
bytes.clear();
bytes.extend(chunk.iter().flat_map(|v| v.to_le_bytes()));
writer.write_all(&bytes)?;
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::Cursor;
fn header(layout: Layout, count: u32) -> Vec<u8> {
let mut bytes = Vec::new();
write_header(&mut bytes, layout, count).unwrap();
bytes
}
#[test]
fn project_schema_keeps_nested_and_future_fields() {
let json = serde_json::json!({
"format_version": 2, "name": "Stone", "mesh": "mesh.obj", "normal_format": "openGl",
"texture_sets": [{"name": "main", "futureSet": {"keep": true}}],
"layers": {"1": {"kind": "paint", "futureLayer": [1, 2]}}, "next_id": 2,
"display": {"futureDisplay": 4}, "mesh_file": "source.obj", "futureProject": [3]
});
let bytes = serde_json::to_vec(&json).unwrap();
assert_eq!(project_version(&bytes).unwrap(), 2);
let document: ProjectDocument = serde_json::from_slice(&bytes).unwrap();
let mut expected = json;
expected["cameras"] = serde_json::json!([]);
assert_eq!(serde_json::to_value(&document).unwrap(), expected);
let mut duplicate = document;
duplicate.extra.insert("mesh".into(), serde_json::json!("other.obj"));
assert!(serde_json::to_vec(&duplicate).is_err());
assert!(project_version(br#"{"format_version":1,"format_version":2}"#).is_err());
assert!(project_version(br#"{"format_version":-1}"#).is_err());
}
#[test]
fn baked_map_matches_the_native_little_endian_wire_layout() {
let layout = Layout { width: 2, height: 1, components: 1 };
let mut expected = b"TCTX".to_vec();
for value in [1u32, 2, 1, 1, 0] {
expected.extend_from_slice(&value.to_le_bytes());
}
expected.extend_from_slice(&1.0f32.to_le_bytes());
expected.extend_from_slice(&(-0.5f32).to_le_bytes());
let mut actual = Vec::new();
write_baked(&mut actual, layout, &[1.0, -0.5]).unwrap();
assert_eq!(actual, expected);
let (decoded, values) = read_baked(&mut Cursor::new(&expected), expected.len() as u64, 1, 2, &mut Budget::new("project", 32)).unwrap();
assert_eq!(decoded, layout);
assert_eq!(values, [1.0, -0.5]);
expected[4..8].copy_from_slice(&2u32.to_le_bytes());
assert!(matches!(read_baked(&mut Cursor::new(&expected), 32, 1, 2, &mut Budget::new("project", 32)), Err(Error::NewerVersion(2))));
}
#[test]
fn dense_maps_round_trip_bit_exactly_in_bounded_chunks() {
let layout = Layout { width: 300, height: 300, components: 1 };
let mut values = vec![0.25; 90_000];
values[123] = f32::from_bits(0x7fc0_1234);
let mut bytes = Vec::new();
write_baked(&mut bytes, layout, &values).unwrap();
let mut budget = Budget::new("project", bytes.len() as u64);
let (decoded_layout, decoded) = read_baked(&mut Cursor::new(&bytes), bytes.len() as u64, 1, 100_000, &mut budget).unwrap();
assert_eq!(decoded_layout, layout);
assert!(decoded.iter().zip(values.iter()).all(|(a, b)| a.to_bits() == b.to_bits()));
assert_eq!(budget.remaining(), 0);
}
#[test]
fn dense_maps_refuse_false_lengths_limits_and_trailing_data() {
let layout = Layout { width: 2, height: 2, components: 1 };
let mut bytes = Vec::new();
write_baked(&mut bytes, layout, &[1.0; 4]).unwrap();
let mut budget = Budget::new("project", 100);
assert!(read_baked(&mut Cursor::new(&bytes), 999, 1, 4, &mut budget).is_err());
let mut budget = Budget::new("project", 39);
assert!(matches!(read_baked(&mut Cursor::new(&bytes), 40, 1, 4, &mut budget), Err(Error::Budget(_))));
let mut extra = bytes.clone();
extra.push(0);
let mut budget = Budget::new("project", 100);
assert!(read_baked(&mut Cursor::new(extra), 40, 1, 4, &mut budget).is_err());
}
#[test]
fn hostile_headers_and_tiles_are_rejected_without_trusting_counts() {
let layout = Layout { width: 64, height: 64, components: 1 };
assert!(matches!(
read_tiles(&mut Cursor::new(header(layout, 0)), layout, 4095, &mut Budget::new("project", 100), |_, _, _| Ok(())),
Err(Error::Limit(_))
));
let mut bad_magic = header(layout, 0);
bad_magic[0] = b'X';
assert!(read_tiles(&mut Cursor::new(bad_magic), layout, u64::MAX, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err());
assert!(read_tiles(&mut Cursor::new(header(layout, 2)), layout, u64::MAX, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err());
let other = Layout { width: 65, ..layout };
assert!(read_tiles(&mut Cursor::new(header(layout, 0)), other, u64::MAX, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err());
let mut outside = header(layout, 1);
outside.extend_from_slice(&1u32.to_le_bytes());
outside.extend_from_slice(&0u32.to_le_bytes());
assert!(read_tiles(&mut Cursor::new(outside), layout, u64::MAX, &mut Budget::new("project", 10_000), |_, _, _| Ok(())).is_err());
let mut truncated = header(layout, 1);
truncated.extend_from_slice(&[0; 8]);
assert!(read_tiles(&mut Cursor::new(truncated), layout, u64::MAX, &mut Budget::new("project", 10_000), |_, _, _| Ok(())).is_err());
let mut extra = header(layout, 0);
extra.push(1);
assert!(read_tiles(&mut Cursor::new(extra), layout, u64::MAX, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err());
}
#[test]
fn sparse_tiles_stream_and_reject_duplicates_and_short_budget() {
let layout = Layout { width: 128, height: 64, components: 1 };
let mut bytes = header(layout, 2);
for x in [0u32, 1] {
bytes.extend_from_slice(&x.to_le_bytes());
bytes.extend_from_slice(&0u32.to_le_bytes());
for _ in 0..TILE_AREA {
bytes.extend_from_slice(&(x as u16 + 1).to_le_bytes());
}
}
let first = vec![1u16; TILE_AREA];
let second = vec![2u16; TILE_AREA];
let mut written = Vec::new();
write_tiles(&mut written, layout, 2, [(0, 0, first.as_slice()), (1, 0, second.as_slice())]).unwrap();
assert_eq!(written, bytes, "the streamed writer keeps the native wire layout");
assert!(write_tiles(&mut Vec::new(), layout, 2, [(0, 0, first.as_slice())]).is_err());
let mut seen = Vec::new();
let mut budget = Budget::new("project", bytes.len() as u64);
read_tiles(&mut Cursor::new(&bytes), layout, u64::MAX, &mut budget, |x, y, tile| {
seen.push((x, y, tile.first().copied()));
Ok(())
})
.unwrap();
assert_eq!(seen, [(0, 0, Some(1)), (1, 0, Some(2))]);
let mut duplicate = bytes.clone();
let second = HEADER_BYTES as usize + 8 + TILE_AREA * 2;
duplicate[second..second + 4].copy_from_slice(&0u32.to_le_bytes());
assert!(read_tiles(&mut Cursor::new(duplicate), layout, u64::MAX, &mut Budget::new("project", u64::MAX), |_, _, _| Ok(())).is_err());
assert!(matches!(
read_tiles(&mut Cursor::new(bytes), layout, u64::MAX, &mut Budget::new("project", HEADER_BYTES), |_, _, _| Ok(())),
Err(Error::Budget(_))
));
}
}
+3
View File
@@ -15,3 +15,6 @@ flate2 = { version = "1", default-features = false, features = ["rust_backend"]
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
[dev-dependencies]
proptest = { workspace = true }
+12 -1
View File
@@ -34,6 +34,7 @@
//! [`sniff`] reads: a reader of a compressed file decompresses it with its own limits first.
pub mod base64;
pub mod stream;
use std::collections::{BTreeMap, HashMap};
use std::fmt;
@@ -769,10 +770,20 @@ impl<'a> Tail<'a> {
/// Write what follows the JSON: [`BLOB_MAGIC`] and the entries, or nothing when there are none.
pub fn write_to(&self, mut w: impl Write) -> io::Result<()> {
self.write_to_with(&mut w, |_, _| Ok(()))
}
/// Write the marker and parts, calling `before_part` before each payload. A compressed
/// writer can use the MIME type to switch between compressed and stored deflate blocks.
pub fn write_to_with<W: Write>(&self, mut w: W, mut before_part: impl FnMut(&mut W, &str) -> io::Result<()>) -> io::Result<()> {
if self.parts.is_empty() {
return Ok(());
}
w.write_all(BLOB_MAGIC)?;
self.parts.iter().try_for_each(|p| w.write_all(p.bytes))
for part in &self.parts {
before_part(&mut w, &part.mime)?;
w.write_all(part.bytes)?;
}
Ok(())
}
}
+302
View File
@@ -0,0 +1,302 @@
//! Streaming helpers for the native JSON envelope.
//!
//! Field values are emitted in bounded chunks. The decoded JSON and tail framing stay the same
//! as VectorCraft's previous writer, but compressed bytes can differ when a deflate backend's
//! output depends on input chunking. Gzip readers still validate the CRC and size trailer.
//!
//! Copyright (c) 2026 ArtCraft Team and the VectorCraft contributors.
//! Extracted from VectorCraft, licensed under MIT OR Apache-2.0.
use serde::Serialize;
use std::collections::{BTreeMap, HashSet};
use std::io::{self, Write};
/// Native file metadata for streaming a JSON envelope. Asset entries should be prepared using
/// the same [`crate::Tail`] whose parts will be written after the JSON.
pub struct FileHeader<'a> {
/// Native format version to write.
pub version: u32,
/// Application generator string.
pub generator: &'a str,
/// Optional saved PDF compatibility preference.
pub pdf_compatible: Option<bool>,
/// Optional inline preview.
pub preview: Option<&'a crate::Image>,
/// Embedded profiles keyed by profile name.
pub profiles: &'a BTreeMap<&'a str, crate::Image>,
/// Optional PDF entry.
pub pdf: Option<&'a crate::Image>,
}
/// Write the native JSON envelope, streaming the document through `document`. The callback
/// returns the image entries after serializing the document, allowing it to collect image keys
/// without keeping a copy of the document JSON. It must write one complete JSON value.
pub fn write_file_json<'a>(
mut out: impl Write,
header: &FileHeader<'a>,
pretty: bool,
document: impl FnOnce(&mut dyn Write) -> io::Result<BTreeMap<&'a str, crate::Image>>,
) -> io::Result<()> {
if !(crate::MIN_VERSION..=crate::VERSION).contains(&header.version) {
return Err(io::Error::new(io::ErrorKind::InvalidInput, "unsupported native file version"));
}
let mut env = Envelope::new(pretty);
let format = if header.version < 3 { crate::LEGACY_EXTENSION } else { crate::EXTENSION };
env.field(&mut out, "format", &format)?;
env.field(&mut out, "version", &header.version)?;
env.field(&mut out, "generator", &header.generator)?;
if let Some(compatible) = header.pdf_compatible {
env.field(&mut out, "pdfCompatible", &compatible)?;
}
if let Some(preview) = header.preview {
env.field(&mut out, "preview", preview)?;
}
if !header.profiles.is_empty() {
env.field(&mut out, "profiles", header.profiles)?;
}
if let Some(pdf) = header.pdf {
env.field(&mut out, "pdf", pdf)?;
}
env.key(&mut out, "document")?;
let images = document(&mut Indent { inner: &mut out, on: pretty })?;
env.field(&mut out, "images", &images)?;
env.finish(&mut out)
}
/// Indents JSON text written through it one level (two spaces after each newline), as a member
/// of the file's top-level object; newlines only occur between tokens, inside strings they are
/// escaped.
pub struct Indent<W: Write> {
pub inner: W,
pub on: bool,
}
impl<W: Write> Write for Indent<W> {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
self.write_all(buf)?;
Ok(buf.len())
}
fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
if !self.on {
return self.inner.write_all(buf);
}
let mut lines = buf.split(|&b| b == b'\n');
self.inner.write_all(lines.next().unwrap_or_default())?;
for line in lines {
self.inner.write_all(b"\n ")?;
self.inner.write_all(line)?;
}
Ok(())
}
fn flush(&mut self) -> io::Result<()> {
self.inner.flush()
}
}
/// The member that names an image.
const TAG: &[u8] = b"\"key\":";
/// Passes JSON text through, collecting the string values of every `"key": "…"` member at any
/// depth (what the images a document uses are named by). Quotes inside JSON strings are escaped,
/// so every match is a real member.
pub struct KeyScan<W: Write> {
pub inner: W,
pub keys: HashSet<String>,
/// Looking for keys (else it only passes the text on).
pub active: bool,
/// How much of [`TAG`] the last bytes matched.
matched: usize,
/// Right after a tag: skipping whitespace to its value.
after_tag: bool,
/// The value string so far, quotes included.
value: Option<Vec<u8>>,
escaped: bool,
}
impl<W: Write> KeyScan<W> {
pub fn new(inner: W) -> Self {
Self { inner, keys: HashSet::new(), active: true, matched: 0, after_tag: false, value: None, escaped: false }
}
fn scan(&mut self, buf: &[u8]) {
if !self.active {
return;
}
let mut i = 0;
while let Some(&b) = buf.get(i) {
// Nothing in progress: skip to the next quote.
if self.matched == 0 && !self.after_tag && self.value.is_none() {
match buf.get(i..).and_then(|r| r.iter().position(|&c| c == b'"')) {
Some(at) => i += at,
None => return,
}
self.matched = 1;
i += 1;
continue;
}
self.step(b);
i += 1;
}
}
fn step(&mut self, b: u8) {
if let Some(v) = self.value.as_mut() {
v.push(b);
if self.escaped {
self.escaped = false;
} else if b == b'\\' {
self.escaped = true;
} else if b == b'"'
&& let Some(v) = self.value.take()
&& let Ok(s) = serde_json::from_slice::<String>(&v)
{
self.keys.insert(s);
}
} else if self.after_tag && !b.is_ascii_whitespace() {
self.after_tag = false;
if b == b'"' {
self.value = Some(vec![b]);
}
}
if TAG.get(self.matched) == Some(&b) {
self.matched += 1;
if self.matched == TAG.len() {
self.matched = 0;
self.after_tag = true;
self.value = None;
self.escaped = false;
}
} else {
self.matched = usize::from(b == b'"');
}
}
}
impl<W: Write> Write for KeyScan<W> {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
self.write_all(buf)?;
Ok(buf.len())
}
fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
self.scan(buf);
self.inner.write_all(buf)
}
fn flush(&mut self) -> io::Result<()> {
self.inner.flush()
}
}
/// The file's top-level object, written member by member (the document is streamed in).
pub struct Envelope {
pretty: bool,
first: bool,
}
impl Envelope {
/// Start an object with optional indentation.
pub fn new(pretty: bool) -> Self {
Self { pretty, first: true }
}
/// Serialize a member directly to the output without buffering the full value.
pub fn field(&mut self, out: &mut impl Write, key: &str, value: &impl Serialize) -> io::Result<()> {
self.key(out, key)?;
// serde_json emits small writes; keep compression and underlying I/O efficient while
// bounding temporary memory independently of the serialized table size.
let mut buffered = io::BufWriter::with_capacity(64 << 10, out);
let indented = Indent { inner: &mut buffered, on: self.pretty };
if self.pretty { serde_json::to_writer_pretty(indented, value) } else { serde_json::to_writer(indented, value) }.map_err(io::Error::other)?;
buffered.into_inner().map(|_| ()).map_err(|e| e.into_error())
}
/// The start of member `key` (a plain name): its value follows, indented one level when
/// pretty (as serde_json would: see [`Indent`]).
pub fn key(&mut self, out: &mut impl Write, key: &str) -> io::Result<()> {
let sep: &[u8] = if std::mem::take(&mut self.first) { b"{" } else { b"," };
let indent: &[u8] = if self.pretty { b"\n " } else { b"" };
out.write_all(sep)?;
out.write_all(indent)?;
serde_json::to_writer(&mut *out, key).map_err(io::Error::other)?;
out.write_all(if self.pretty { b": " } else { b":" })
}
/// Close the object.
pub fn finish(self, out: &mut impl Write) -> io::Result<()> {
if self.first {
return out.write_all(b"{}");
}
out.write_all(if self.pretty { b"\n}" } else { b"}" })
}
}
#[cfg(test)]
mod tests {
use proptest::prelude::*;
use super::*;
/// How the keys were found before saves were streamed: in the whole JSON text at once.
fn string_members(json: &[u8]) -> HashSet<String> {
let mut out = HashSet::new();
let mut rest = json;
while let Some(at) = rest.windows(TAG.len()).position(|w| w == TAG) {
rest = rest.get(at + TAG.len()..).unwrap_or_default();
let value = rest.trim_ascii_start();
if value.first() == Some(&b'"')
&& let Some(Ok(s)) = serde_json::Deserializer::from_slice(value).into_iter::<String>().next()
{
out.insert(s);
}
}
out
}
/// The keys `KeyScan` finds in `json` written in pieces of `chunk` bytes.
fn scanned(json: &[u8], chunk: usize) -> HashSet<String> {
let mut scan = KeyScan::new(Vec::new());
for piece in json.chunks(chunk.max(1)) {
scan.write_all(piece).unwrap();
}
assert_eq!(scan.inner, json, "the text passes through");
scan.keys
}
#[test]
fn finds_the_keys_the_whole_text_search_found() {
let v = serde_json::json!({"key": "a", "x": [{"key": "b \"q\" \\ é"}, {"monkey": "no"}, {"k": "key"}], "s": "\"key\": \"no\"", "key2": "n", "o": {"key": 3}});
for json in [serde_json::to_vec(&v).unwrap(), serde_json::to_vec_pretty(&v).unwrap()] {
let want = string_members(&json);
assert_eq!(want, HashSet::from(["a".to_string(), "b \"q\" \\ é".to_string()]));
for chunk in [1, 2, 3, 7, 64, json.len()] {
assert_eq!(scanned(&json, chunk), want, "chunk {chunk}");
}
}
}
fn arb_json() -> impl Strategy<Value = serde_json::Value> {
let key = prop::sample::select(vec!["key", "k", "kkey", "key ", "x"]).prop_map(str::to_string);
let leaf = prop_oneof![
Just(serde_json::Value::Null),
any::<i32>().prop_map(serde_json::Value::from),
"[a-z\"\\\\: ké\n]{0,8}".prop_map(serde_json::Value::from),
];
leaf.prop_recursive(4, 32, 6, move |inner| {
prop_oneof![
prop::collection::vec(inner.clone(), 0..5).prop_map(serde_json::Value::from),
prop::collection::vec((key.clone(), inner), 0..5).prop_map(|m| serde_json::Value::Object(m.into_iter().collect())),
]
})
}
proptest! {
#[test]
fn scanning_in_pieces_finds_what_the_whole_text_search_found(v in arb_json(), chunk in 1usize..40, pretty in any::<bool>()) {
let json = if pretty { serde_json::to_vec_pretty(&v) } else { serde_json::to_vec(&v) }.unwrap();
prop_assert_eq!(scanned(&json, chunk), string_members(&json));
}
}
}
+182
View File
@@ -0,0 +1,182 @@
use craft_vectorcraft_format::stream::{Envelope, Indent, KeyScan};
use std::io::{self, Write};
#[test]
fn envelope_streams_nested_json_and_escapes_keys() {
for pretty in [false, true] {
let mut bytes = Vec::new();
let mut env = Envelope::new(pretty);
env.field(&mut bytes, "quoted\"key", &vec![1, 2]).unwrap();
env.key(&mut bytes, "document").unwrap();
let mut output = Indent { inner: &mut bytes, on: pretty };
if pretty {
serde_json::to_writer_pretty(&mut output, &serde_json::json!({"nested": [3,4]})).unwrap();
} else {
serde_json::to_writer(&mut output, &serde_json::json!({"nested": [3,4]})).unwrap();
}
env.finish(&mut bytes).unwrap();
let value: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
assert_eq!(value, serde_json::json!({"quoted\"key": [1, 2], "document": {"nested": [3,4]}}));
let mut expected = Vec::new();
let empty = Envelope::new(pretty);
empty.finish(&mut expected).unwrap();
assert_eq!(expected, b"{}");
}
}
#[test]
fn scan_survives_every_chunk_boundary_and_forwards_data() {
let json = br#"{"key":"one","nested":[{"key":"two \\\"quoted\\\""},{"key":42}],"other":"x"}"#;
for chunk in 1..=json.len() {
let mut scan = KeyScan::new(Vec::new());
for part in json.chunks(chunk) {
scan.write_all(part).unwrap();
}
assert_eq!(scan.inner, json);
assert!(scan.keys.contains("one"));
assert_eq!(scan.keys.len(), 2);
}
}
struct Broken;
impl Write for Broken {
fn write(&mut self, _: &[u8]) -> io::Result<usize> {
Err(io::Error::other("failure"))
}
fn flush(&mut self) -> io::Result<()> {
Err(io::Error::other("failure"))
}
}
#[test]
fn forwards_writer_errors() {
assert!(Envelope::new(false).field(&mut Broken, "x", &1).is_err());
assert!(KeyScan::new(Broken).write_all(b"{}").is_err());
assert!(Indent { inner: Broken, on: true }.write_all(b"x\ny").is_err());
}
#[test]
fn tail_calls_hook_in_order_and_propagates_errors() {
use craft_vectorcraft_format::{BLOB_MAGIC, INLINE_MAX, Tail};
let first = vec![1; INLINE_MAX];
let second = vec![2; INLINE_MAX];
let mut tail = Tail::new(4);
tail.image("image/png", &first, false);
tail.image("application/pdf", &second, false);
let mut out = Vec::new();
let mut seen = Vec::new();
tail.write_to_with(&mut out, |_, mime| {
seen.push(mime.to_owned());
Ok(())
})
.unwrap();
assert_eq!(seen, ["image/png", "application/pdf"]);
assert_eq!(out, [BLOB_MAGIC, &first, &second].concat());
assert!(tail.write_to_with(Vec::new(), |_, _| Err(io::Error::other("failure"))).is_err());
let mut called = false;
Tail::new(4)
.write_to_with(Vec::new(), |_, _| {
called = true;
Ok(())
})
.unwrap();
assert!(!called);
}
#[test]
fn native_schema_order_and_versions() {
use craft_vectorcraft_format::stream::{FileHeader, write_file_json};
let profiles = Default::default();
for (version, name) in [(1, "drawcraft"), (4, "vectorcraft")] {
for pretty in [false, true] {
let header = FileHeader { version, generator: "test", pdf_compatible: Some(false), preview: None, profiles: &profiles, pdf: None };
let mut out = Vec::new();
write_file_json(&mut out, &header, pretty, |w| {
w.write_all(if pretty { b"{\n \"key\": \"image\"\n}" } else { b"{\"key\":\"image\"}" })?;
Ok(Default::default())
})
.unwrap();
let value: serde_json::Value = serde_json::from_slice(&out).unwrap();
assert_eq!(value["format"], name);
assert_eq!(value["pdfCompatible"], false);
let text = std::str::from_utf8(&out).unwrap();
assert!(text.find("\"format\"").unwrap() < text.find("\"version\"").unwrap());
assert!(text.find("\"document\"").unwrap() < text.find("\"images\"").unwrap());
}
}
let header = FileHeader { version: 0, generator: "test", pdf_compatible: None, preview: None, profiles: &profiles, pdf: None };
assert!(write_file_json(Vec::new(), &header, false, |_| Ok(Default::default())).is_err());
}
// Oracle for the previous app writer: each member was first serialized to a Vec, then
// indented and appended. Compare decoded file bytes, not backend-dependent gzip bytes.
#[test]
fn streamed_native_file_matches_previous_framing() {
use craft_vectorcraft_format::{
Tail,
stream::{FileHeader, write_file_json},
};
use flate2::{Compression, read::GzDecoder, write::GzEncoder};
use std::collections::BTreeMap;
use std::io::Read;
fn old_field(out: &mut Vec<u8>, first: &mut bool, pretty: bool, key: &str, value: &impl serde::Serialize) {
out.extend_from_slice(if std::mem::take(first) { b"{" } else { b"," });
if pretty {
out.extend_from_slice(b"\n ");
}
out.extend_from_slice(format!("\"{key}\"{}", if pretty { ": " } else { ":" }).as_bytes());
let json = if pretty { serde_json::to_vec_pretty(value) } else { serde_json::to_vec(value) }.unwrap();
let mut indent = Indent { inner: out, on: pretty };
indent.write_all(&json).unwrap();
}
let payload = vec![42; craft_vectorcraft_format::INLINE_MAX];
for version in [1, 3, 4] {
for pretty in [false, true] {
let mut tail = Tail::new(version);
let image = tail.image("image/png", &payload, false);
let profile = tail.image("application/vnd.iccprofile", &payload, false);
let pdf = tail.image("application/pdf", &payload, false);
let profiles = BTreeMap::from([("profile", profile)]);
let images = BTreeMap::from([("image", image)]);
let document = serde_json::json!({"layers": [{"key": "image", "name": "A"}]});
let header = FileHeader {
version,
generator: "VectorCraft test",
pdf_compatible: Some(true),
preview: None,
profiles: &profiles,
pdf: Some(&pdf),
};
let mut actual = Vec::new();
write_file_json(&mut actual, &header, pretty, |w| {
if pretty { serde_json::to_writer_pretty(w, &document) } else { serde_json::to_writer(w, &document) }.map_err(io::Error::other)?;
Ok(images.clone())
})
.unwrap();
tail.write_to(&mut actual).unwrap();
let mut old = Vec::new();
let mut first = true;
let format = if version < 3 { "drawcraft" } else { "vectorcraft" };
old_field(&mut old, &mut first, pretty, "format", &format);
old_field(&mut old, &mut first, pretty, "version", &version);
old_field(&mut old, &mut first, pretty, "generator", &"VectorCraft test");
old_field(&mut old, &mut first, pretty, "pdfCompatible", &true);
old_field(&mut old, &mut first, pretty, "profiles", &profiles);
old_field(&mut old, &mut first, pretty, "pdf", &pdf);
old_field(&mut old, &mut first, pretty, "document", &document);
old_field(&mut old, &mut first, pretty, "images", &images);
old.extend_from_slice(if pretty { b"\n}" } else { b"}" });
tail.write_to(&mut old).unwrap();
assert_eq!(actual, old, "version {version}, pretty {pretty}");
for bytes in [&old, &actual] {
let mut gzip = GzEncoder::new(Vec::new(), Compression::default());
gzip.write_all(bytes).unwrap();
let mut decoded = Vec::new();
GzDecoder::new(gzip.finish().unwrap().as_slice()).read_to_end(&mut decoded).unwrap();
assert_eq!(decoded, old);
}
}
}
}

Some files were not shown because too many files have changed in this diff Show More