#[cfg(not(feature = "qtest-driver"))]
pub(crate) mod repair;
#[cfg(feature = "qtest-driver")]
#[doc(hidden)]
pub mod repair;
pub mod tree_rebuild;
use crate::object_handle::ObjectHandleIdentity;
use crate::pipeline::buffer::Buffer;
use crate::{Error, ObjectHandle, ObjectRef, Pdf, Result};
use std::collections::{BTreeSet, HashSet};
use std::fmt;
use std::io::{Read, Seek};
#[cfg(test)]
use std::cell::Cell;
#[cfg(test)]
thread_local! {
static PAGE_WALK_VISITS: Cell<usize> = const { Cell::new(0) };
}
#[cfg(test)]
pub(crate) fn page_walk_visits_for_test() -> usize {
PAGE_WALK_VISITS.with(Cell::get)
}
pub const DEFAULT_MAX_PAGE_TREE_DEPTH: usize = 100;
#[derive(Debug, Clone)]
pub(crate) struct PageParentCursor {
handle: ObjectHandle,
}
impl PageParentCursor {
pub(crate) fn from_handle(handle: ObjectHandle) -> Self {
Self { handle }
}
pub(crate) fn handle(&self) -> ObjectHandle {
self.handle.clone()
}
}
impl fmt::Display for PageParentCursor {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self.handle.object_ref() {
Some(reference) => write!(f, "{reference}"),
None => f.write_str("direct page-tree dictionary"),
}
}
}
pub(crate) fn page_parent_entries(
cursor: &PageParentCursor,
key: &[u8],
) -> Result<Option<(ObjectHandle, ObjectHandle)>> {
let dict = cursor.handle();
dict.try_dereference()?;
Ok(Some((
dict.try_get_key(key)?,
dict.try_get_key(b"/Parent")?,
)))
}
pub(crate) fn next_page_parent(parent: ObjectHandle) -> Result<Option<PageParentCursor>> {
if !parent.is_indirect() && parent.try_is_null()? {
return Ok(None);
}
if parent.is_indirect() && !parent.is_resolved() {
return Ok(Some(PageParentCursor::from_handle(parent)));
}
if !parent.try_is_dictionary()? {
return Ok(None);
}
Ok(Some(PageParentCursor::from_handle(parent)))
}
pub(crate) fn is_inheritable_page_attribute(key: &[u8]) -> bool {
matches!(key, b"/MediaBox" | b"/CropBox" | b"/Resources" | b"/Rotate")
}
pub(crate) fn resolve_inherited_handle_from_node_with_max_depth(
node: ObjectHandle,
key: &[u8],
max_depth: usize,
) -> Result<Option<ObjectHandle>> {
let mut seen: Vec<ObjectHandle> = Vec::new();
let mut current = PageParentCursor::from_handle(node);
let mut depth = 0usize;
let inheritable = is_inheritable_page_attribute(key);
loop {
if depth >= max_depth {
return Err(Error::Unsupported(format!(
"page tree depth exceeds maximum of {max_depth} at {current}"
)));
}
let current_handle = current.handle();
if seen
.iter()
.any(|seen_handle| seen_handle.is_same_object_as(¤t_handle))
{
return Ok(None);
}
seen.push(current_handle);
let Some((value, parent)) = page_parent_entries(¤t, key)? else {
return Ok(None);
};
let terminal = value.clone();
terminal.try_dereference()?;
if !terminal.try_is_null()? {
return Ok(Some(value));
}
if !inheritable {
return Ok(None);
}
let Some(parent) = next_page_parent(parent)? else {
return Ok(None);
};
current = parent;
depth += 1;
}
}
pub(crate) fn resolve_inherited_handle_with_max_depth<R: Read + Seek>(
pdf: &mut Pdf<R>,
page_ref: ObjectRef,
key: &[u8],
max_depth: usize,
) -> Result<Option<ObjectHandle>> {
let page = pdf.get_object_handle(page_ref);
resolve_inherited_handle_from_node_with_max_depth(page, key, max_depth)
}
pub fn page_refs<R: Read + Seek>(pdf: &mut Pdf<R>) -> Result<Vec<ObjectRef>> {
if let Some(prepared) = pdf.cached_page_list() {
pdf.mark_get_all_pages_called();
return prepared.page_refs();
}
pdf.mark_get_all_pages_called();
PageWalk::new(pdf)?.collect()
}
pub fn page_refs_with_max_depth<R: Read + Seek>(
pdf: &mut Pdf<R>,
max_depth: usize,
) -> Result<Vec<ObjectRef>> {
pdf.mark_get_all_pages_called();
PageWalk::with_max_depth(pdf, max_depth)?.collect()
}
pub fn page_content_bytes<R: Read + Seek>(
pdf: &mut Pdf<R>,
page_ref: ObjectRef,
) -> Result<Vec<u8>> {
let page = pdf.get_object_handle(page_ref);
page.try_dereference()?;
if !page.try_is_dictionary()? {
return Err(Error::Unsupported(format!(
"object {page_ref} is not a dictionary, cannot extract /Contents"
)));
}
let page_type = page.try_get_key(b"/Type")?;
match page_type.try_as_name()? {
Some(name) if name.as_slice() == b"Page" => {}
Some(name) => {
return Err(Error::Unsupported(format!(
"object {page_ref} has /Type /{}, expected /Page",
String::from_utf8_lossy(&name)
)));
}
None if page.try_has_key(b"/Type")? => {
return Err(Error::Unsupported(format!(
"object {page_ref} has a non-name /Type entry"
)));
}
None => {
return Err(Error::Unsupported(format!(
"object {page_ref} has no /Type entry"
)));
}
}
let streams = page.get_page_contents()?;
if streams.is_empty() {
return Ok(Vec::new());
}
let normalized_contents = ObjectHandle::array(streams);
let mut buffer = Buffer::new("page content bytes", None);
let mut all_description = String::new();
normalized_contents.pipe_content_streams(
&mut buffer,
&format!("page object {page_ref}"),
&mut all_description,
)?;
Ok(buffer.take_buffer()?)
}
#[derive(Clone)]
enum PageNode {
Indirect(ObjectRef),
Direct(ObjectHandle),
Leaf(ObjectRef),
}
impl PageNode {
fn from_handle(handle: ObjectHandle) -> Self {
match handle.object_ref() {
Some(object_ref) => Self::Indirect(object_ref),
None => Self::Direct(handle),
}
}
fn handle<R: Read + Seek>(&self, pdf: &mut Pdf<R>) -> ObjectHandle {
match self {
Self::Indirect(object_ref) | Self::Leaf(object_ref) => {
pdf.get_object_handle(*object_ref)
}
Self::Direct(handle) => handle.clone(),
}
}
fn object_ref(&self) -> Option<ObjectRef> {
match self {
Self::Indirect(object_ref) | Self::Leaf(object_ref) => Some(*object_ref),
Self::Direct(_) => None,
}
}
fn label(&self) -> String {
self.object_ref().map_or_else(
|| "direct page-tree object".to_owned(),
|reference| reference.to_string(),
)
}
}
pub struct PageWalk<'a, R: Read + Seek + 'static> {
pdf: &'a mut Pdf<R>,
stack: Vec<(PageNode, usize)>,
seen: BTreeSet<ObjectRef>,
#[allow(
clippy::mutable_key_type,
reason = "direct page-tree cycle detection keys on canonical handle identity"
)]
seen_direct: HashSet<ObjectHandleIdentity>,
max_depth: Option<usize>,
done: bool,
}
fn probe_page_kids(handle: &ObjectHandle) -> Result<()> {
let contextless = handle.context().is_none();
match handle.try_has_key(b"/Kids") {
Ok(_) => Ok(()),
Err(Error::QpdfExc(_)) if contextless => Ok(()),
Err(error) => Err(error),
}
}
fn page_kid_has_kids(handle: &ObjectHandle) -> Result<bool> {
let contextless = handle.context().is_none();
match handle.try_has_key(b"/Kids") {
Ok(has_kids) => Ok(has_kids),
Err(Error::QpdfExc(_)) if contextless => Ok(false),
Err(error) => Err(error),
}
}
impl<'a, R: Read + Seek> PageWalk<'a, R> {
pub fn new(pdf: &'a mut Pdf<R>) -> Result<Self> {
let root = pdf.trailer_key_handle(b"Root");
if !root.is_indirect() && root.try_is_null()? {
return Err(Error::Missing("/Root"));
}
let catalog = pdf.root_handle()?;
let pages = catalog.try_get_key(b"/Pages")?;
if !pages.is_indirect() && pages.try_is_null()? {
probe_page_kids(&pages)?;
return Err(Error::Missing("/Pages"));
}
let pages = PageNode::from_handle(pages);
Ok(PageWalk {
pdf,
stack: vec![(pages, 0)],
seen: BTreeSet::new(),
seen_direct: HashSet::new(),
max_depth: None,
done: false,
})
}
pub fn with_max_depth(pdf: &'a mut Pdf<R>, max_depth: usize) -> Result<Self> {
let root = pdf.trailer_key_handle(b"Root");
if !root.is_indirect() && root.try_is_null()? {
return Err(Error::Missing("/Root"));
}
let catalog = pdf.root_handle()?;
let pages = catalog.try_get_key(b"/Pages")?;
if !pages.is_indirect() && pages.try_is_null()? {
probe_page_kids(&pages)?;
return Err(Error::Missing("/Pages"));
}
let pages = PageNode::from_handle(pages);
Ok(PageWalk {
pdf,
stack: vec![(pages, 0)],
seen: BTreeSet::new(),
seen_direct: HashSet::new(),
max_depth: Some(max_depth),
done: false,
})
}
fn visit_node(&mut self, node: &PageNode, depth: usize) -> Result<Option<ObjectRef>> {
let node_obj = node.handle(self.pdf);
node_obj.try_dereference()?;
if !node_obj.try_is_dictionary()? {
probe_page_kids(&node_obj)?;
return Ok(None); }
let node_type = node_obj.try_get_key(b"/Type")?;
if node_type.try_as_name()?.as_deref() == Some(b"Pages") {
let kids = node_obj.try_get_key(b"/Kids")?;
if let Some(kids_items) = kids.try_as_array()? {
let mut classified = Vec::with_capacity(kids_items.len());
for (index, kid) in kids_items.iter().enumerate() {
if page_kid_has_kids(kid)? {
if let Some(r) = kid.object_ref() {
classified.push(PageNode::Indirect(r));
} else {
classified.push(PageNode::Direct(kid.clone()));
}
} else if let Some(r) = kid.object_ref() {
classified.push(PageNode::Leaf(r));
} else {
let promoted = self.pdf.make_indirect_object_handle(kid.clone())?;
kids.set_array_item(index, promoted.clone())?;
let promoted_ref = promoted
.object_ref()
.expect("make_indirect_object_handle returns an indirect handle");
classified.push(PageNode::Leaf(promoted_ref));
}
}
for node in classified.into_iter().rev() {
self.stack.push((node, depth + 1));
}
}
return Ok(None);
}
if node_type.try_as_name()?.as_deref() == Some(b"Page") {
return Ok(node.object_ref());
}
Ok(None)
}
}
impl<'a, R: Read + Seek> Iterator for PageWalk<'a, R> {
type Item = Result<ObjectRef>;
fn next(&mut self) -> Option<Self::Item> {
if self.done {
return None;
}
loop {
let (node, depth) = self.stack.pop()?;
#[cfg(test)]
PAGE_WALK_VISITS.with(|visits| visits.set(visits.get() + 1));
if self.max_depth.is_some_and(|max_depth| depth >= max_depth) {
self.done = true;
return Some(Err(Error::Unsupported(format!(
"page tree depth exceeds maximum of {} at {}",
self.max_depth.expect("checked above"),
node.label()
))));
}
let first_visit = match &node {
PageNode::Indirect(reference) | PageNode::Leaf(reference) => {
self.seen.insert(*reference)
}
PageNode::Direct(handle) => self.seen_direct.insert(handle.identity_key()),
};
if !first_visit {
continue; }
let visited = match &node {
PageNode::Leaf(reference) => Ok(Some(*reference)),
PageNode::Indirect(_) | PageNode::Direct(_) => self.visit_node(&node, depth),
};
match visited {
Ok(Some(page)) => return Some(Ok(page)),
Ok(None) => continue,
Err(error) => {
self.done = true;
return Some(Err(error));
}
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn unbounded_page_walk_reports_a_missing_root() {
let mut pdf = Pdf::<std::io::Cursor<Vec<u8>>>::uninitialized();
assert!(matches!(
PageWalk::new(&mut pdf),
Err(Error::Missing("/Root"))
));
}
#[test]
fn unbounded_page_walk_reports_a_missing_pages_entry() {
let mut pdf = Pdf::empty().expect("empty PDF");
let catalog = pdf.root_handle().expect("empty catalog");
catalog.remove_key(b"/Pages");
assert!(matches!(
PageWalk::new(&mut pdf),
Err(Error::Missing("/Pages"))
));
let messages: Vec<_> = pdf
.repair_diagnostics()
.entries()
.iter()
.map(|entry| entry.message_string())
.collect();
assert_eq!(messages.len(), 1);
assert!(messages[0].contains(
"operation for dictionary attempted on object of type null: returning false for a key containment request"
));
}
#[test]
fn bounded_page_walk_reports_a_missing_pages_entry() {
let mut pdf = Pdf::empty().expect("empty PDF");
pdf.root_handle()
.expect("empty catalog")
.remove_key(b"/Pages");
assert!(matches!(
PageWalk::with_max_depth(&mut pdf, 4),
Err(Error::Missing("/Pages"))
));
}
#[test]
fn page_kids_probe_propagates_uninitialized_handle_errors() {
let error = probe_page_kids(&ObjectHandle::uninitialized()).unwrap_err();
assert!(matches!(error, Error::Internal(_)));
}
#[test]
fn page_kid_classification_propagates_uninitialized_handle_errors() {
let error = page_kid_has_kids(&ObjectHandle::uninitialized()).unwrap_err();
assert!(matches!(error, Error::Internal(_)));
}
#[test]
fn explicit_page_walk_limit_remains_available() {
let mut pdf = Pdf::empty().expect("empty PDF");
let mut walk = PageWalk::with_max_depth(&mut pdf, 0).expect("empty pages root");
let error = walk
.next()
.expect("bounded walk must report an error")
.unwrap_err();
assert!(error.to_string().contains("depth exceeds maximum of 0"));
}
#[test]
fn page_refs_reuses_the_nonempty_prepared_page_cache() {
let mut pdf = Pdf::open_mem_owned(
include_bytes!("../../../tests/fixtures/compat/one-page.pdf").to_vec(),
)
.expect("one-page fixture");
let prepared = crate::pages::repair::prepare_for_optimization(&mut pdf)
.expect("prepare pages")
.expect("prepared page list");
let before = page_walk_visits_for_test();
let actual = page_refs(&mut pdf).expect("cached page refs");
assert_eq!(
actual,
prepared
.pages
.iter()
.map(|page| page.object_ref().expect("page identity"))
.collect::<Vec<_>>()
);
assert_eq!(page_walk_visits_for_test(), before);
}
#[test]
fn page_walk_expands_a_direct_pages_kid() {
let mut pdf = Pdf::empty().expect("empty PDF");
let root_pages = pdf
.root_handle()
.expect("empty catalog")
.try_get_key(b"/Pages")
.expect("empty /Pages");
let page = pdf
.make_indirect_object_handle(ObjectHandle::dictionary(vec![(
b"/Type".to_vec(),
ObjectHandle::name(b"Page".to_vec()),
)]))
.expect("indirect page");
let direct_subtree = ObjectHandle::dictionary(vec![
(b"/Type".to_vec(), ObjectHandle::name(b"Pages".to_vec())),
(b"/Kids".to_vec(), ObjectHandle::array(vec![page.clone()])),
]);
root_pages
.replace_key(b"/Kids", ObjectHandle::array(vec![direct_subtree]))
.expect("install direct subtree");
root_pages
.replace_key(b"/Count", ObjectHandle::integer(1))
.expect("install count");
let refs = page_refs(&mut pdf).expect("direct subtree is expanded");
assert_eq!(
refs,
vec![page.object_ref().expect("indirect page identity")]
);
}
#[test]
fn direct_scalar_kids_are_promoted_in_forward_order() {
let mut pdf = Pdf::empty().expect("empty PDF");
let pages = pdf
.root_handle()
.expect("empty catalog")
.try_get_key(b"/Pages")
.expect("empty /Pages");
let kids = ObjectHandle::array(vec![ObjectHandle::integer(42), ObjectHandle::integer(43)]);
pages
.replace_key(b"/Kids", kids.clone())
.expect("install scalar kids");
pages
.replace_key(b"/Count", ObjectHandle::integer(2))
.expect("install count");
let refs = page_refs(&mut pdf).expect("two scalar leaves are two pages");
assert_eq!(refs.len(), 2);
assert!(
refs[0].number < refs[1].number,
"the first kid must mint the lower object number, got {refs:?}"
);
let values: Vec<_> = refs
.iter()
.map(|r| {
pdf.get_object_handle(*r)
.try_as_integer()
.expect("resolve promoted leaf")
})
.collect();
assert_eq!(values, vec![Some(42), Some(43)]);
}
#[test]
fn page_walk_promotes_a_direct_scalar_kid_like_qpdf() {
let mut pdf = Pdf::empty().expect("empty PDF");
let pages = pdf
.root_handle()
.expect("empty catalog")
.try_get_key(b"/Pages")
.expect("empty /Pages");
let kids = ObjectHandle::array(vec![ObjectHandle::integer(42)]);
pages
.replace_key(b"/Kids", kids.clone())
.expect("install scalar kid");
pages
.replace_key(b"/Count", ObjectHandle::integer(1))
.expect("install count");
let refs = page_refs(&mut pdf).expect("a scalar leaf is a page");
assert_eq!(refs.len(), 1, "qpdf counts the scalar leaf as one page");
assert_eq!(
pdf.get_object_handle(refs[0])
.try_as_integer()
.expect("resolve promoted leaf"),
Some(42)
);
assert!(
kids.try_get_array_item(0)
.expect("rewritten kid")
.is_indirect(),
"qpdf promotes a direct kid to an indirect page object"
);
}
#[test]
fn inherited_attribute_walk_propagates_an_unresolved_parent_child_error() {
let node = ObjectHandle::dictionary(vec![
(b"/MediaBox".to_vec(), ObjectHandle::null()),
(
b"/Parent".to_vec(),
ObjectHandle::new_indirect_unresolved(ObjectRef::new(99, 0), -1),
),
]);
let error =
resolve_inherited_handle_from_node_with_max_depth(node, b"/MediaBox", 4).unwrap_err();
assert!(error
.to_string()
.contains("object 99 0 belongs to a dropped PDF"));
}
}