Expose bounded multi-image print PDF serialization with per-image ICC

This commit is contained in:
Dylan M. Taylor committed 2026-11-15 17:48:04 -05:00
1 parent f0fa27110d
commit 2651dbeb2b
2 files changed
+199 -57

No files matched your search

+4
View File
@@ -3,6 +3,10 @@
//! Callers map their page and color models to these neutral records. This module owns PDF object
//! layout, image streams, ICC/Separation resources, page labels, marks, xref and trailer syntax.
/// Multi-image 8/16-bit print pages with per-image ICC resources and explicit byte budgets.
#[path = "raster_print.rs"]
pub mod print;
use std::collections::BTreeSet;
use std::fmt::Write as _;
use std::io::Write as _;
+195 -57
View File
@@ -8,10 +8,17 @@
//! The file is PDF 1.6 (16-bit images need 1.5): classic cross-reference table, no object streams,
//! deterministic (no dates or IDs), so the same pages always give the same bytes.
//!
//! Encoded JPEG and Flate payloads are copied, not decoded or verified against declared
//! dimensions. Callers own their encoding validity and ICC/profile-channel compatibility.
//! An output intent describes a printing condition; this API does not certify PDF/X.
//! Byte limits bound accounted input and emitted output, not peak process memory or
//! caller-owned image construction. This is not the streaming slideshow writer.
//!
//! Sources: ISO 32000-1:2008 (§7.3 objects, §7.5 file structure, §8.6.5.5 ICCBased colour spaces,
//! §8.9 images, §14.11.5 output intents). Own design.
use std::collections::HashMap;
use std::io::Write as _;
use std::sync::Arc;
/// Pages per document: a print job beyond this is a mistake, not a book.
@@ -23,6 +30,19 @@ pub const MAX_PAGE_POINTS: f64 = 14_400.0;
/// Largest image, in pixels per side.
pub const MAX_IMAGE_SIDE: u32 = 65_535;
/// Serialization budgets; input records already belong to the caller. These are not a
/// process-wide peak-memory guarantee. Repeated references count toward the input budget.
#[derive(Clone, Copy, Debug)]
pub struct Limits {
pub input_bytes: usize,
pub output_bytes: usize,
}
impl Default for Limits {
fn default() -> Self {
Self { input_bytes: 512 * 1024 * 1024, output_bytes: 512 * 1024 * 1024 }
}
}
/// How an image's samples are stored.
#[derive(Clone, Debug, PartialEq)]
pub enum ImageData {
@@ -58,8 +78,11 @@ impl PdfImage {
/// hold every page's uncompressed samples until the file is written.
pub fn deflated(self) -> Result<PdfImage, String> {
self.check()?;
if matches!(&self.data, ImageData::Raw { samples, .. } if samples.len() > Limits::default().input_bytes) {
return Err("PDF input byte limit exceeded".into());
}
let data = match self.data {
ImageData::Raw { bits, samples } => ImageData::Flate { bits, data: deflate(&samples) },
ImageData::Raw { bits, samples } => ImageData::Flate { bits, data: deflate(&samples, Limits::default().output_bytes)? },
other => other,
};
Ok(PdfImage { data, ..self })
@@ -130,6 +153,8 @@ pub struct OutputIntent {
pub struct PdfInfo {
pub title: Option<String>,
pub output_intent: Option<OutputIntent>,
/// Application name, not a PDF/X conformance claim.
pub producer: String,
}
fn finite(v: f64) -> bool {
@@ -157,47 +182,89 @@ fn text(s: &str) -> String {
out.push(')');
out
} else {
let mut out = String::from("<FEFF");
for unit in s.encode_utf16() {
out.push_str(&format!("{unit:04X}"));
}
out.push('>');
out
super::pdf_unicode_string(s)
}
}
struct Writer {
out: Vec<u8>,
offsets: Vec<usize>,
limit: usize,
}
impl Writer {
/// Reserve an object number (filled later by [`Writer::object`]).
fn reserve(&mut self) -> usize {
self.offsets.push(0);
self.offsets.len()
fn put(&mut self, bytes: &[u8]) -> Result<(), String> {
let end = self.out.len().checked_add(bytes.len()).ok_or("PDF output size overflow")?;
if end > self.limit {
return Err("PDF output byte limit exceeded".into());
}
self.out.try_reserve(bytes.len()).map_err(|_| "PDF output allocation failed")?;
self.out.extend_from_slice(bytes);
Ok(())
}
fn object(&mut self, id: usize, dict: &str, stream: Option<&[u8]>) {
if let Some(slot) = self.offsets.get_mut(id.wrapping_sub(1)) {
*slot = self.out.len();
}
self.out.extend_from_slice(format!("{id} 0 obj\n{dict}").as_bytes());
fn reserve(&mut self) -> Result<usize, String> {
self.offsets.try_reserve(1).map_err(|_| "PDF object allocation failed")?;
self.offsets.push(0);
Ok(self.offsets.len())
}
fn object(&mut self, id: usize, dict: &str, stream: Option<&[u8]>) -> Result<(), String> {
let pos = self.out.len();
*self.offsets.get_mut(id.checked_sub(1).ok_or("invalid PDF object")?).ok_or("invalid PDF object")? = pos;
self.put(format!("{id} 0 obj\n{dict}").as_bytes())?;
if let Some(data) = stream {
self.out.extend_from_slice(b"\nstream\n");
self.out.extend_from_slice(data);
self.out.extend_from_slice(b"\nendstream");
self.put(b"\nstream\n")?;
self.put(data)?;
self.put(b"\nendstream")?;
}
self.out.extend_from_slice(b"\nendobj\n");
self.put(b"\nendobj\n")
}
}
fn deflate(data: &[u8]) -> Vec<u8> {
miniz_oxide::deflate::compress_to_vec_zlib(data, 6)
fn deflate(data: &[u8], max: usize) -> Result<Vec<u8>, String> {
struct Sink {
bytes: Vec<u8>,
max: usize,
}
impl std::io::Write for Sink {
fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
if bytes.len() > self.max.saturating_sub(self.bytes.len()) {
return Err(std::io::Error::other("PDF compressed byte limit exceeded"));
}
self.bytes.try_reserve(bytes.len()).map_err(std::io::Error::other)?;
self.bytes.extend_from_slice(bytes);
Ok(bytes.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
let mut encoder = flate2::write::ZlibEncoder::new(Sink { bytes: Vec::new(), max }, flate2::Compression::new(6));
encoder.write_all(data).map_err(|e| e.to_string())?;
Ok(encoder.finish().map_err(|e| e.to_string())?.bytes)
}
/// Write a document. Errors name the first page or image that can't be written.
pub fn write(pages: &[PdfPage], info: &PdfInfo) -> Result<Vec<u8>, String> {
write_with_limits(pages, info, Limits::default())
}
/// Write with explicit total input and serialized output budgets. ICC bytes are opaque:
/// callers validate their profile semantics; resources are keyed by bytes AND channels.
pub fn write_with_limits(pages: &[PdfPage], info: &PdfInfo, limits: Limits) -> Result<Vec<u8>, String> {
let mut input = 0usize;
let mut account = |n: usize| -> Result<(), String> {
input = input.checked_add(n).ok_or("PDF input size overflow")?;
if input > limits.input_bytes {
return Err("PDF input byte limit exceeded".into());
}
Ok(())
};
account(info.producer.len())?;
account(info.title.as_ref().map_or(0, String::len))?;
if let Some(intent) = &info.output_intent {
account(intent.icc.len())?;
account(intent.condition.len())?;
}
if pages.is_empty() {
return Err("there are no pages to write".into());
}
@@ -218,6 +285,13 @@ pub fn write(pages: &[PdfPage], info: &PdfInfo) -> Result<Vec<u8>, String> {
return Err(format!("page {n} has more than {MAX_IMAGES_PER_PAGE} images"));
}
for (image, at) in &page.images {
account(match &image.data {
ImageData::Raw { samples, .. } => samples.len(),
ImageData::Jpeg(data) | ImageData::Flate { data, .. } => data.len(),
})?;
if let Some(icc) = &image.icc {
account(icc.len())?;
}
image.check().map_err(|e| format!("page {n}: {e}"))?;
if ![at.x, at.y, at.width, at.height].into_iter().all(finite) || at.width <= 0.0 || at.height <= 0.0 {
return Err(format!("page {n}: an image has no usable placement"));
@@ -230,49 +304,50 @@ pub fn write(pages: &[PdfPage], info: &PdfInfo) -> Result<Vec<u8>, String> {
return Err("the output intent's profile has 1, 3 or 4 components".into());
}
let mut w = Writer { out: Vec::new(), offsets: Vec::new() };
w.out.extend_from_slice(b"%PDF-1.6\n%\xE2\xE3\xCF\xD3\n");
let catalog = w.reserve();
let pages_id = w.reserve();
let info_id = w.reserve();
let mut w = Writer { out: Vec::new(), offsets: Vec::new(), limit: limits.output_bytes };
w.put(b"%PDF-1.6\n%\xE2\xE3\xCF\xD3\n")?;
let catalog = w.reserve()?;
let pages_id = w.reserve()?;
let info_id = w.reserve()?;
// ICC profiles, each written once (keyed by content) with its component count
let mut profiles: HashMap<Vec<u8>, usize> = HashMap::new();
let mut profile = |w: &mut Writer, icc: &Arc<Vec<u8>>, n: u8| -> usize {
if let Some(&id) = profiles.get(icc.as_slice()) {
return id;
let mut profiles: HashMap<(Arc<Vec<u8>>, u8), usize> = HashMap::new();
let mut profile = |w: &mut Writer, icc: &Arc<Vec<u8>>, n: u8| -> Result<usize, String> {
if let Some(&id) = profiles.get(&(Arc::clone(icc), n)) {
return Ok(id);
}
let id = w.reserve();
let data = deflate(icc);
let id = w.reserve()?;
let data = deflate(icc, limits.output_bytes)?;
let alternate = match n {
1 => "/DeviceGray",
4 => "/DeviceCMYK",
_ => "/DeviceRGB",
};
w.object(id, &format!("<< /N {n} /Alternate {alternate} /Filter /FlateDecode /Length {} >>", data.len()), Some(&data));
profiles.insert(icc.to_vec(), id);
id
w.object(id, &format!("<< /N {n} /Alternate {alternate} /Filter /FlateDecode /Length {} >>", data.len()), Some(&data))?;
profiles.try_reserve(1).map_err(|_| "PDF profile allocation failed")?;
profiles.insert((Arc::clone(icc), n), id);
Ok(id)
};
let intent_id = info.output_intent.as_ref().map(|intent| profile(&mut w, &intent.icc, intent.channels));
let intent_id = info.output_intent.as_ref().map(|intent| profile(&mut w, &intent.icc, intent.channels)).transpose()?;
let mut kids = Vec::with_capacity(pages.len());
for page in pages {
let page_id = w.reserve();
let page_id = w.reserve()?;
let mut xobjects = String::new();
let mut content = String::new();
for (k, (image, at)) in page.images.iter().enumerate() {
let space = match &image.icc {
Some(icc) => format!("[/ICCBased {} 0 R]", profile(&mut w, icc, image.channels)),
Some(icc) => format!("[/ICCBased {} 0 R]", profile(&mut w, icc, image.channels)?),
None => match image.channels {
1 => "/DeviceGray".into(),
4 => "/DeviceCMYK".into(),
_ => "/DeviceRGB".into(),
},
};
let id = w.reserve();
let id = w.reserve()?;
let (bits, filter, data): (u8, &str, std::borrow::Cow<[u8]>) = match &image.data {
ImageData::Raw { bits, samples } => (*bits, "/FlateDecode", deflate(samples).into()),
ImageData::Raw { bits, samples } => (*bits, "/FlateDecode", deflate(samples, limits.output_bytes)?.into()),
ImageData::Flate { bits, data } => (*bits, "/FlateDecode", data.as_slice().into()),
ImageData::Jpeg(jpeg) => (8, "/DCTDecode", jpeg.as_slice().into()),
};
@@ -285,13 +360,13 @@ pub fn write(pages: &[PdfPage], info: &PdfInfo) -> Result<Vec<u8>, String> {
data.len()
),
Some(&data),
);
)?;
xobjects.push_str(&format!("/Im{k} {id} 0 R "));
content.push_str(&format!("q {} 0 0 {} {} {} cm /Im{k} Do Q\n", num(at.width), num(at.height), num(at.x), num(at.y)));
}
let content_id = w.reserve();
let stream = deflate(content.as_bytes());
w.object(content_id, &format!("<< /Filter /FlateDecode /Length {} >>", stream.len()), Some(&stream));
let content_id = w.reserve()?;
let stream = deflate(content.as_bytes(), limits.output_bytes)?;
w.object(content_id, &format!("<< /Filter /FlateDecode /Length {} >>", stream.len()), Some(&stream))?;
w.object(
page_id,
&format!(
@@ -300,10 +375,10 @@ pub fn write(pages: &[PdfPage], info: &PdfInfo) -> Result<Vec<u8>, String> {
num(page.height)
),
None,
);
)?;
kids.push(format!("{page_id} 0 R"));
}
w.object(pages_id, &format!("<< /Type /Pages /Count {} /Kids [{}] >>", kids.len(), kids.join(" ")), None);
w.object(pages_id, &format!("<< /Type /Pages /Count {} /Kids [{}] >>", kids.len(), kids.join(" ")), None)?;
let intents = match (&info.output_intent, intent_id) {
(Some(intent), Some(id)) => format!(
@@ -312,9 +387,9 @@ pub fn write(pages: &[PdfPage], info: &PdfInfo) -> Result<Vec<u8>, String> {
),
_ => String::new(),
};
w.object(catalog, &format!("<< /Type /Catalog /Pages {pages_id} 0 R{intents} >>"), None);
w.object(catalog, &format!("<< /Type /Catalog /Pages {pages_id} 0 R{intents} >>"), None)?;
let title = info.title.as_deref().map(|t| format!(" /Title {}", text(t))).unwrap_or_default();
w.object(info_id, &format!("<< /Producer (LightCraft){title} >>"), None);
w.object(info_id, &format!("<< /Producer {}{title} >>", text(&info.producer)), None)?;
let xref = w.out.len();
let mut table = format!("xref\n0 {}\n0000000000 65535 f \n", w.offsets.len() + 1);
@@ -322,14 +397,14 @@ pub fn write(pages: &[PdfPage], info: &PdfInfo) -> Result<Vec<u8>, String> {
table.push_str(&format!("{offset:010} 00000 n \n"));
}
table.push_str(&format!("trailer\n<< /Size {} /Root {catalog} 0 R /Info {info_id} 0 R >>\nstartxref\n{xref}\n%%EOF\n", w.offsets.len() + 1));
w.out.extend_from_slice(table.as_bytes());
w.put(table.as_bytes())?;
Ok(w.out)
}
#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
use super::*;
use lightcraft_codecs::NamedSpace;
/// The body of object `id` (dictionary and raw stream bytes), found through the xref table.
fn object(pdf: &[u8], id: usize) -> (String, Vec<u8>) {
@@ -355,7 +430,12 @@ mod tests {
}
fn inflate(data: &[u8]) -> Vec<u8> {
miniz_oxide::inflate::decompress_to_vec_zlib(data).unwrap()
{
use std::io::Read;
let mut out = Vec::new();
flate2::read::ZlibDecoder::new(data).read_to_end(&mut out).unwrap();
out
}
}
/// Object ids of every image XObject, in file order.
@@ -370,7 +450,7 @@ mod tests {
}
fn srgb() -> Arc<Vec<u8>> {
Arc::new(lightcraft_codecs::icc::write_named(NamedSpace::Srgb))
Arc::new(b"opaque RGB profile fixture".to_vec())
}
fn page(images: Vec<(PdfImage, Placement)>) -> PdfPage {
@@ -397,7 +477,6 @@ mod tests {
let (profile, icc) = object(&pdf, reference(&dict, "/ICCBased"));
assert!(profile.contains("/N 3") && profile.contains("/Alternate /DeviceRGB"), "{profile}");
assert_eq!(inflate(&icc), *srgb());
assert_eq!(lightcraft_codecs::icc::parse(&inflate(&icc)).and_then(|i| i.named), Some(NamedSpace::Srgb));
}
#[test]
@@ -428,6 +507,7 @@ mod tests {
let cmyk_like = srgb();
let info = PdfInfo {
title: Some("Garden – prints (2)".into()),
producer: "Fixture".into(),
output_intent: Some(OutputIntent { icc: cmyk_like.clone(), channels: 3, condition: "Glossy (Photo) \\ test".into() }),
};
let img = PdfImage::from_u16(1, 1, 3, &[0, 0, 0], Some(cmyk_like));
@@ -503,7 +583,11 @@ mod tests {
assert!(bad(vec![page(vec![(not_jpeg, at)])]));
let too_many = (0..MAX_PAGES + 1).map(|_| page(vec![])).collect();
assert!(bad(too_many));
let info = PdfInfo { title: None, output_intent: Some(OutputIntent { icc: srgb(), channels: 2, condition: String::new() }) };
let info = PdfInfo {
producer: String::new(),
title: None,
output_intent: Some(OutputIntent { icc: srgb(), channels: 2, condition: String::new() }),
};
assert!(write(&[page(vec![])], &info).is_err());
}
@@ -517,4 +601,58 @@ mod tests {
assert_eq!(text("a(b)c\\"), "(a\\(b\\)c\\\\)");
assert_eq!(text("é"), "<FEFF00E9>");
}
#[test]
fn distinct_profiles_and_component_counts_are_not_conflated() {
let common = Arc::new(b"opaque profile A".to_vec());
let different = Arc::new(b"opaque profile B".to_vec());
let image = |channels, profile| PdfImage {
width: 1,
height: 1,
channels,
data: ImageData::Raw { bits: 8, samples: vec![7; channels as usize] },
icc: Some(profile),
};
let pages = [page(vec![
(image(3, common.clone()), full(1.0, 1.0)),
(image(4, common.clone()), full(1.0, 1.0)),
(image(3, different.clone()), full(1.0, 1.0)),
(image(3, common.clone()), full(1.0, 1.0)),
])];
let pdf = write(&pages, &PdfInfo::default()).unwrap();
let refs: Vec<_> = images(&pdf).iter().map(|&id| reference(&object(&pdf, id).0, "/ICCBased")).collect();
assert_ne!(refs[0], refs[1]);
assert_ne!(refs[0], refs[2]);
assert_eq!(refs[0], refs[3]);
for (i, channels, bytes) in [(0, 3, common.as_slice()), (1, 4, common.as_slice()), (2, 3, different.as_slice())] {
let (dict, data) = object(&pdf, refs[i]);
assert!(dict.contains(&format!("/N {channels}")));
assert_eq!(inflate(&data), bytes);
}
}
#[test]
fn gray_rgb_cmyk_raw_depths_preserve_samples() {
for channels in [1, 3, 4] {
for bits in [8, 16] {
let bytes: Vec<u8> = (0..channels * (bits / 8)).collect();
let image = PdfImage { width: 1, height: 1, channels, data: ImageData::Raw { bits, samples: bytes.clone() }, icc: None };
let pdf = write(&[page(vec![(image, full(1.0, 1.0))])], &PdfInfo::default()).unwrap();
let (dict, data) = object(&pdf, images(&pdf)[0]);
assert!(dict.contains(&format!("/BitsPerComponent {bits}")));
assert_eq!(inflate(&data), bytes);
}
}
}
#[test]
fn input_and_output_budgets_fail_without_partial_success() {
let image = PdfImage::from_u16(1, 1, 3, &[1, 2, 3], None);
let pages = [page(vec![(image, full(1.0, 1.0))])];
let info = PdfInfo::default();
let expected = write(&pages, &info).unwrap();
assert_eq!(write_with_limits(&pages, &info, Limits { input_bytes: 6, output_bytes: expected.len() }).unwrap(), expected);
assert!(write_with_limits(&pages, &info, Limits { input_bytes: 5, output_bytes: expected.len() }).is_err());
assert!(write_with_limits(&pages, &info, Limits { input_bytes: 6, output_bytes: expected.len() - 1 }).is_err());
assert!(write_with_limits(&pages, &info, Limits { input_bytes: 6, output_bytes: 0 }).is_err());
}
}