//! The core object-handle graph: shared, cloneable identity for direct and
//! indirect PDF objects, with parsed-offset tracking and document-owned
//! reserved-object construction.
//!
//! qpdf correspondence: `QPDFObjectHandle`, `QPDFObject`, and `QPDFValue` identity and payload ownership, `QPDF::newReserved`/`QPDF_Reserved`, `QPDFObjectHandle::copyStream`/`QPDF::copyStreamData` stream-copy primitives, and `QPDF::setImmediateCopyFrom`.
//!
//! `QPDFObjectHandle` holds `std::shared_ptr<QPDFObject>` and defines object
//! sameness by that pointer, not by structural equality
//! (`include/qpdf/QPDFObjectHandle.hh:304-309,1338-1350`,
//! `libqpdf/QPDFObjectHandle.cc:224-227`). [`ObjectHandle`] maps that one
//! shared allocation to one uniform `Rc<RefCell<ObjectSlot>>`: direct and
//! indirect forms therefore share one identity, payload, and metadata slot.
//!
//! qpdf's `QPDFObject` owns one shared `QPDFValue`; that value carries the
//! current `QPDF*`, object generation, and parsed offset
//! (`libqpdf/qpdf/QPDFObject_private.hh:19-29,60-68,117-150,176-180`,
//! `libqpdf/qpdf/QPDFValue.hh:60-72,90-110,144-152`). Resolution reads the
//! current metadata from this same allocation
//! (`libqpdf/QPDFObject.cc:7-16`). `ObjectSlot::identity` shares the active
//! object reference and resolver alongside its shared value state; assignment
//! and swap move both allocations, while removal detaches both.
//!
//! qpdf promotion registers and updates the existing allocation rather than
//! cloning a direct payload (`libqpdf/QPDF.cc:1835-1839,1882-1897`); this
//! port's [`ObjectHandle::promote_to_indirect`] mutates its existing slot on
//! the same boundary. During teardown qpdf disconnects every cached indirect
//! object, including unresolved entries, and destroys only non-null values
//! (`libqpdf/QPDF.cc:215-235`); this port's
//! [`ObjectHandle::disconnect`] clears the same slot's indirect metadata and
//! state-sensitive value.
//!
//! `QPDFObjectHandle.cc:327-471,759-785,869-955,1027-1039` supplies the
//! name/dictionary/stream/array inspection and live array mutation mirrored
//! by `try_is_name_and_equals`, `try_is_string`, `try_is_dictionary_of_type`,
//! `try_is_stream_of_type`, `try_array_len`, `try_array_item`, `set_array_item`, `set_array_items`,
//! `insert_array_item`, `append_array_item`, and `erase_array_item`.
//!
//! `QPDFObjectHandle` (`include/qpdf/QPDFObjectHandle.hh`) shares a canonical `QPDFObject`
//! (`libqpdf/qpdf/QPDFObject.hh`), which owns the `QPDFValue` payload
//! (`libqpdf/qpdf/QPDFValue.hh`).
//!
//! qpdf stores a stream's deferred source as a
//! `std::shared_ptr<QPDFObjectHandle::StreamDataProvider>` in
//! `QPDF_Stream` (`include/qpdf/QPDFObjectHandle.hh:68-127`,
//! `libqpdf/QPDF_Stream.cc:575-604,640-660`). [`ObjectValue::Stream`] uses
//! `Rc<dyn StreamDataProvider>` as an internal container substitution: it
//! preserves provider ownership, exclusive buffer/provider source state,
//! lazy invocation, repeated-call behavior, and the source pipeline order.
//! The `Rc` choice is an internal Rust ownership detail; qpdf's observable
//! callback, identity, retry, error, and `/Length` contracts remain the
//! authority.
//!
//! qpdf keeps the token-filter list on `QPDF_Stream`, not on the common
//! `QPDFValue` base (`libqpdf/qpdf/QPDF_Stream.hh:101-107`). [`ObjectValue::Stream`]
//! mirrors that boundary: its stream-local filters and the flpdf-only
//! normalization marker move with the shared stream value, which is boxed as
//! `ObjectValue::Stream(Box<StreamValue>)` so scalar/container values do not
//! carry the concrete stream subclass layout. qpdf also stores
//! `QPDFValue::Description` through an optional `std::shared_ptr` rather than
//! embedding its largest variant (`libqpdf/qpdf/QPDFValue.hh:29-58,60-82,
//! 141-144`); [`SharedValueState::description`] keeps the common template
//! form inline while boxing the larger JSON and child forms, so the value
//! layout does not carry their maximum shape.
//! No extra mutation-generation field is retained; writer modification
//! decisions remain on the stream-local state.
//!
//! `ValueIdentity::active_pdf_unique_id` is a container representation
//! substitute for qpdf's per-value `QPDF*` back-pointer (`QPDFValue.hh:150`):
//! a real qpdf counterpart exists, flpdf just projects it to a nonzero numeric
//! id beside a separate `Weak` resolver route. qpdf's default unique id is
//! zero (`QPDF.hh:1454`), so `Option<NonZeroU64>` preserves the same absent
//! state without carrying a separate discriminant.
//!
//! qpdf's containers hold only forward child handles and never maintain an
//! upward index (`QPDF_Array.cc:33-48,235-286`, `QPDF_Dictionary.cc:10-18,51-56,117-150`);
//! `QPDFValue::ChildDescr`'s weak parent is diagnostic description context for
//! warning text, not a containment lookup (`QPDFValue.hh:41-58,74-84`,
//! `QPDFObject_private.hh:77-92`). Production ObjectHandle state follows that
//! boundary. Unit-test-only containment-root assertions derive reverse paths
//! by scanning the registered forward graph and are not part of the value or
//! slot layout.
//! Neither ownership, warning text, writer scheduling, nor output bytes needs
//! a production reverse edge.
//
// qpdf-deviation-start: qpdf 11.9.0's default destruction of a sufficiently
// deep programmatic direct container graph recursively follows the
// shared-pointer children. Its depth-unbounded direct factories and default
// container destructors are documented by `QPDFObjectHandle.cc:1944-2013`,
// `QPDF_Array.hh:9-50`, and `QPDF_Dictionary.hh:11-38`; a pinned live probe
// drops depth 5,000 successfully but finishes construction and exits 139 at
// depths 50,000 and 100,000. flpdf automatically drains only final-owner
// acyclic direct children with a heap worklist, preserving shared identity,
// payload, and PDF output while avoiding Rust stack exhaustion.
// qpdf-deviation-end
//!
//! ## Page/Form content-family correspondence
//!
//! The content-family surface below is a direct qpdf 11.9.0 responsibility
//! mapping. The qpdf declarations and implementation ranges are kept beside
//! the Rust entry points so every consumer can be checked against one
//! canonical route rather than adding a second parser or decoder.
//!
//! | qpdf 11.9.0 declaration/implementation | flpdf entry point | regression evidence |
//! | --- | --- | --- |
//! | `QPDFObjectHandle::TokenFilter`, `QPDFObjectHandle::ParserCallbacks` (`include/qpdf/QPDFObjectHandle.hh:129-227`) | [`crate::token_filter::TokenFilter`], [`crate::content_stream::ObjectHandleParserCallbacks`], [`crate::content_stream::ParseControl`] | `object_handle_content_parser_tests.rs`: token-filter output/discard/EOF, parser callback lifecycle, and warning/error boundary tests |
//! | `QPDFObjectHandle::parse` overloads (`include/qpdf/QPDFObjectHandle.hh:382-413`; `libqpdf/QPDFObjectHandle.cc:1672-1699`) | [`ObjectHandle::parse`], [`ObjectHandle::parse_with_description`], [`ObjectHandle::parse_with_context`] | `object_handle.rs::parse_tests` and `flpdf-qtest-tools` test 31: described errors, canonical unresolved references, warning order, and trailing-data checks |
//! | `parseContentStream`, `pipeContentStreams`, `addTokenFilter`, `parsePageContents`, `filterPageContents`, `pipePageContents`, `addContentTokenFilter`, `filterAsContents`, `parseAsContents` (`include/qpdf/QPDFObjectHandle.hh:421-473`) | [`ObjectHandle::parse_page_contents`], [`ObjectHandle::parse_as_contents`], [`ObjectHandle::filter_page_contents`], [`ObjectHandle::filter_as_contents`], [`ObjectHandle::pipe_page_contents`], [`ObjectHandle::pipe_content_streams`], [`ObjectHandle::add_token_filter`], [`ObjectHandle::add_content_token_filter`], `ObjectHandle::parse_content_stream_handles` (private orchestration for `parseContentStream`) | `object_handle_content_parser_tests.rs` and `object_handle_page_content_pipeline_tests.rs` |
//! | `makeResourcesIndirect` (`include/qpdf/QPDFObjectHandle.hh:789-793`; `libqpdf/QPDFObjectHandle.cc:1042-1060`) | [`ObjectHandle::make_resources_indirect`] | `object_handle::mutation_tests::make_resources_indirect_promotes_direct_second_level_values_only` and `acroform_document_helper::tests::prepare_foreign_resource_plan_indirectizes_both_dr_second_level_values` |
//! | `getResourceNames` (`include/qpdf/QPDFObjectHandle.hh:831-835`; `libqpdf/QPDFObjectHandle.cc:1156-1170`) | [`ObjectHandle::get_resource_names`] | `public_object_primitives.rs::qpdf_object_handle_primitives_are_available_to_external_crates` |
//! | `getUniqueResourceName` (`include/qpdf/QPDFObjectHandle.hh:837-850`) | [`ObjectHandle::get_unique_resource_name`] | `object_handle_content_shape_tests.rs::unique_resource_name_uses_the_supplied_prefix_and_suffix_cursor` and related shape tests |
//! | `getPageContents`, `addPageContents`, `rotatePage`, `coalesceContentStreams` (`include/qpdf/QPDFObjectHandle.hh:1242-1254`) | [`ObjectHandle::get_page_contents`], [`ObjectHandle::add_page_contents`], [`ObjectHandle::rotate_page`], [`ObjectHandle::coalesce_content_streams`] | `object_handle_content_shape_tests.rs` and `object_handle_page_content_pipeline_tests.rs` |
//! | `isFormXObject`, `isImage` (`include/qpdf/QPDFObjectHandle.hh:1328-1334`) | [`ObjectHandle::is_form_xobject`], [`ObjectHandle::is_image`] | `object_handle_content_shape_tests.rs::form_and_image_classification_matches_qpdf` |
//! | `CoalesceProvider` (`libqpdf/QPDFObjectHandle.cc:94-118`) | `CoalesceContentProvider` and [`ObjectHandle::coalesce_content_streams`] | `object_handle_page_content_pipeline_tests.rs::coalesce_content_streams_installs_a_lazy_document_owned_provider` |
//! | `arrayOrStreamToStreamArray`, `getPageContents`, `addPageContents`, `rotatePage`, `coalesceContentStreams` (`libqpdf/QPDFObjectHandle.cc:1438-1572`) | `array_or_stream_to_stream_array`, [`ObjectHandle::get_page_contents`], [`ObjectHandle::add_page_contents`], [`ObjectHandle::rotate_page`], [`ObjectHandle::coalesce_content_streams`] | shape normalization, prepend/append, inherited rotation, malformed-array, and lazy-provider tests |
//! | `pipePageContents`, `pipeContentStreams` (`libqpdf/QPDFObjectHandle.cc:1702-1737`) | [`ObjectHandle::pipe_page_contents`], [`ObjectHandle::pipe_content_streams`] | `object_handle_page_content_pipeline_tests.rs::pipe_page_contents_decodes_and_joins_streams_with_qpdf_newline_rules` and failure/description tests; `flpdf-b8xcx` CLI differential covers unknown-filter error propagation |
//! | `parsePageContents`, `parseAsContents`, `filterPageContents`, `filterAsContents`, `parseContentStream_internal`, inline-image recovery, `addContentTokenFilter`, `addTokenFilter` (`libqpdf/QPDFObjectHandle.cc:1740-1859`) | [`ObjectHandle::parse_page_contents`], [`ObjectHandle::parse_as_contents`], [`ObjectHandle::filter_page_contents`], [`ObjectHandle::filter_as_contents`], [`ObjectHandle::add_content_token_filter`], [`ObjectHandle::add_token_filter`], [`crate::content_stream::parse_content_stream_handles`] | `object_handle_content_parser_tests.rs` callback identity/span/warning-error/early-stop/inline-image/filter tests |
//! | `isFormXObject`, `isImage` (`libqpdf/QPDFObjectHandle.cc:2340-2352`) | [`ObjectHandle::is_form_xobject`], [`ObjectHandle::is_image`] | direct/indirect subtype and ImageMask exclusion tests |
//!
//! `QPDFObjectHandle::parse` overloads, `QPDFParser::parseRemainder`, and the tokenizer dispatch that backs the
//! ObjectHandle callbacks remain in [`crate::parser`] and
//! `crate::pipeline::qpdf_tokenizer::QpdfTokenizer`; their qpdf source
//! correspondence is documented at
//! `libqpdf/QPDFParser.cc:135-176,221-223,266-274,408-444,456-469` and
//! `libqpdf/Pl_QPDFTokenizer.cc:36-65`. This module owns the handle identity,
//! stream normalization, provider/filter dispatch, and public consumer
//! boundary. The context-taking parse route uses the canonical resolver's
//! object cache and warning sink; PageObjectHelper and page-tree orchestration
//! are intentionally outside this table and tracked separately.
// Deviation: shared handle identity uses Rc<RefCell<..>> in place of qpdf's
// std::shared_ptr<QPDFObject>; ObjectValue is the QPDFValue payload. This is
// internal structure only and does not affect output bytes (see
// docs/qpdf-correspondence.md).
//
// Deviation: qpdf's canonical name strings include a leading slash and its
// array access borrows QPDF_Array, while ObjectValue stores decoded name bytes
// without the slash and Vec<ObjectHandle>. Dictionary keys, however, retain
// qpdf's canonical leading slash in the ObjectHandle graph. Inspection
// compares the same decoded name bytes and clones only one Rc-backed child per
// valid array access. It emits no bytes or diagnostics; the warning-producing
// signed-index surface is try_get_array_item and the try_*_array_item_at
// mutators. See docs/qpdf-correspondence.md.
use crate::matrix::Rectangle;
use crate::pdf_string::{decode_pdf_text_string, lossy_utf16_to_utf8, utf8_value};
use crate::qpdf_obj_gen::QpdfObjGen;
use crate::token_filter::TokenFilter;
use crate::{
content_normalizer::ContentNormalizerPipeline,
content_stream::{parse_content_stream_handles, ObjectHandleParserCallbacks},
pipeline::{
buffer::Buffer,
count::Count,
flate::{Flate, FlateAction, DEFAULT_OUT_BUFFER_SIZE},
qpdf_tokenizer::QpdfTokenizer,
Discard, Pipeline, PipelineError, PipelineRef, PlString,
},
stream_filter::{
normalize_filter_name, stream_filter_for, OwnedDecodePipeline, RegisteredStreamFilter,
DECODE_PARMS_LENGTH_ERROR, FILTER_TYPE_ERROR,
},
writer::DecodeLevel,
};
use crate::{json::Json, Error, ObjectRef, QpdfErrorCode, QpdfExc, Result};
#[cfg(test)]
use std::cell::Cell;
use std::cell::RefCell;
use std::collections::{BTreeMap, BTreeSet};
use std::hash::{Hash, Hasher};
use std::num::NonZeroU64;
use std::rc::{Rc, Weak};
type StreamTokenFilter = Rc<RefCell<dyn TokenFilter>>;
#[cfg(test)]
thread_local! {
static TRY_DEREFERENCE_CALLS: Cell<usize> = const { Cell::new(0) };
}
/// The qpdf stream-local token-filter vector. The newtype only supplies a
/// cycle-safe debug representation for the trait objects; it does not add an
/// ownership cell or another allocation around the vector.
#[derive(Clone, Default)]
struct StreamTokenFilters(Vec<StreamTokenFilter>);
#[derive(Clone, Default)]
pub(crate) struct StreamTokenFilterList(Option<Box<StreamTokenFilters>>);
impl StreamTokenFilterList {
fn is_empty(&self) -> bool {
self.0.as_ref().is_none_or(|filters| filters.0.is_empty())
}
fn push(&mut self, filter: StreamTokenFilter) {
self.0
.get_or_insert_with(|| Box::new(StreamTokenFilters::default()))
.0
.push(filter);
}
}
impl std::fmt::Debug for StreamTokenFilterList {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_list()
.entries(
self.0
.as_deref()
.into_iter()
.flat_map(|filters| filters.0.iter())
.map(|_| "<TokenFilter>"),
)
.finish()
}
}
/// Request Flate compression when encoding stream data for
/// [`ObjectHandle::pipe_stream_data`]'s `encode_flags` argument.
///
/// qpdf correspondence: `qpdf_ef_compress` bit in `QPDF_Stream::pipeStreamData`.
pub const STREAM_ENCODE_COMPRESS: u32 = 1;
/// Request content-stream token normalization when encoding stream data for
/// [`ObjectHandle::pipe_stream_data`]'s `encode_flags` argument.
///
/// qpdf correspondence: `qpdf_ef_normalize` bit in `QPDF_Stream::pipeStreamData`.
pub const STREAM_ENCODE_NORMALIZE: u32 = 2;
const STREAM_DATA_PROVIDER_DEFAULT_ERROR: &str =
"you must override provideStreamData -- see QPDFObjectHandle.hh";
const STREAM_DATA_PROVIDER_REQUIRES_INDIRECT_ERROR: &str =
"stream data provider requires an indirect stream";
const FOREIGN_OBJECT_OWNERSHIP_ERROR: &str =
"Attempting to add an object from a different QPDF. Use QPDF::copyForeignObject to add objects from another file.";
/// Deferred stream-data source corresponding to qpdf's
/// `QPDFObjectHandle::StreamDataProvider`
/// (`include/qpdf/QPDFObjectHandle.hh:68-127`).
///
/// Registration retains this trait object and does not invoke it. The source
/// is called only when the stream is piped, and every invocation for one
/// stream must produce the same bytes. Providers must not mutate PDF objects
/// while producing data because qpdf may invoke them more than once during a
/// linearized write.
///
/// Rust uses distinct method names for qpdf's overloaded forms. The
/// `ObjectRef` methods delegate to the numeric identity methods by default,
/// matching qpdf's `QPDFObjGen` overload delegation. A provider that supports
/// the retry-aware form must return `true` from [`Self::supports_retry`].
pub trait StreamDataProvider {
/// Whether the retry-aware success-returning callback should be used.
fn supports_retry(&self) -> bool {
false
}
/// Legacy provider form receiving the complete stream identity.
fn provide_stream_data(
&self,
object_ref: ObjectRef,
pipeline: &mut dyn Pipeline,
) -> Result<()> {
self.provide_stream_data_by_id(object_ref.number, object_ref.generation, pipeline)
}
/// Legacy provider form receiving numeric object identity.
fn provide_stream_data_by_id(
&self,
_object_number: u32,
_generation: u16,
_pipeline: &mut dyn Pipeline,
) -> Result<()> {
Err(Error::Internal(
STREAM_DATA_PROVIDER_DEFAULT_ERROR.to_owned(),
))
}
/// Raw qpdf object/generation form of the provider callback. Existing
/// providers that only implement the narrower numeric form retain their
/// behavior for projectable identities; providers that need the full qpdf
/// range can override this method directly.
fn provide_stream_data_by_qpdf_obj_gen(
&self,
object_number: i64,
generation: i64,
pipeline: &mut dyn Pipeline,
) -> Result<()> {
if let (Ok(number), Ok(generation)) =
(u32::try_from(object_number), u16::try_from(generation))
{
return self.provide_stream_data(ObjectRef::new(number, generation), pipeline);
}
self.provide_stream_data_by_id(object_number as u32, generation as u16, pipeline)
}
/// Retry-aware provider form receiving the complete stream identity.
fn provide_stream_data_with_retry(
&self,
object_ref: ObjectRef,
pipeline: &mut dyn Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
self.provide_stream_data_with_retry_by_id(
object_ref.number,
object_ref.generation,
pipeline,
suppress_warnings,
will_retry,
)
}
/// Retry-aware provider form receiving numeric object identity.
fn provide_stream_data_with_retry_by_id(
&self,
_object_number: u32,
_generation: u16,
_pipeline: &mut dyn Pipeline,
_suppress_warnings: bool,
_will_retry: bool,
) -> Result<bool> {
Err(Error::Internal(
STREAM_DATA_PROVIDER_DEFAULT_ERROR.to_owned(),
))
}
/// Retry-aware raw qpdf object/generation form of the provider callback.
fn provide_stream_data_with_retry_by_qpdf_obj_gen(
&self,
object_number: i64,
generation: i64,
pipeline: &mut dyn Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
if let (Ok(number), Ok(generation)) =
(u32::try_from(object_number), u16::try_from(generation))
{
return self.provide_stream_data_with_retry(
ObjectRef::new(number, generation),
pipeline,
suppress_warnings,
will_retry,
);
}
self.provide_stream_data_with_retry_by_id(
object_number as u32,
generation as u16,
pipeline,
suppress_warnings,
will_retry,
)
}
}
impl std::fmt::Debug for dyn StreamDataProvider {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("StreamDataProvider(..)")
}
}
struct CallbackProvider<F> {
callback: F,
}
impl<F> StreamDataProvider for CallbackProvider<F>
where
F: Fn(&mut dyn Pipeline) -> Result<()> + 'static,
{
fn provide_stream_data_by_id(
&self,
_object_number: u32,
_generation: u16,
pipeline: &mut dyn Pipeline,
) -> Result<()> {
(self.callback)(pipeline)
}
}
struct RetryCallbackProvider<F> {
callback: F,
}
impl<F> StreamDataProvider for RetryCallbackProvider<F>
where
F: Fn(&mut dyn Pipeline, bool, bool) -> Result<bool> + 'static,
{
fn supports_retry(&self) -> bool {
true
}
fn provide_stream_data_with_retry_by_id(
&self,
_object_number: u32,
_generation: u16,
pipeline: &mut dyn Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
(self.callback)(pipeline, suppress_warnings, will_retry)
}
}
/// qpdf's `CopiedStreamDataProvider` (`libqpdf/QPDF.cc:126-163`), retaining
/// the source handle so copied provider/original streams are still dispatched
/// through the source document when the destination stream is read.
struct CopiedStreamDataProvider {
source: ObjectHandle,
}
impl StreamDataProvider for CopiedStreamDataProvider {
fn supports_retry(&self) -> bool {
true
}
fn provide_stream_data_with_retry_by_id(
&self,
_object_number: u32,
_generation: u16,
pipeline: &mut dyn Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
let mut filtering_attempted = false;
self.source.pipe_stream_data(
pipeline,
&mut filtering_attempted,
0,
DecodeLevel::None,
suppress_warnings,
will_retry,
)
}
}
pub(crate) fn copied_stream_data_provider(source: ObjectHandle) -> Rc<dyn StreamDataProvider> {
Rc::new(CopiedStreamDataProvider { source })
}
/// qpdf's `CoalesceProvider` (`QPDFObjectHandle.cc:94-118`), retaining the
/// page and the pre-coalesced `/Contents` handle so the replacement stream
/// stays lazy and reuses the canonical content-stream pipeline every time it
/// is read.
struct CoalesceContentProvider {
containing_page: ObjectHandle,
old_contents: ObjectHandle,
}
impl StreamDataProvider for CoalesceContentProvider {
fn provide_stream_data_by_id(
&self,
_object_number: u32,
_generation: u16,
pipeline: &mut dyn Pipeline,
) -> Result<()> {
let description = format!(
"page object {}",
object_generation_description(&self.containing_page)
);
let mut all_description = String::new();
self.old_contents
.pipe_content_streams(pipeline, &description, &mut all_description)
}
}
struct StreamFilterPlan {
filters: Vec<Box<dyn RegisteredStreamFilter>>,
specialized_compression: bool,
lossy_compression: bool,
}
/// The no-offset sentinel qpdf uses for values that were not parsed from a
/// source position (`QPDFValue`'s parsed offset starts at `-1` and is set
/// only while still negative; see
/// `libqpdf/qpdf/QPDFValue.hh:90-100,149-152`).
pub(crate) const NO_PARSED_OFFSET: i64 = -1;
/// qpdf's `QPDF::ObjCache` source extent pair
/// (`include/qpdf/QPDF.hh:868-889`). These positions belong to the
/// document-owned cache entry, not to every `QPDFValue`/`ObjectSlot`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct SourceExtents {
pub(crate) end_before_space: i64,
pub(crate) end_after_space: i64,
}
impl SourceExtents {
pub(crate) const UNSET: Self = Self {
end_before_space: NO_PARSED_OFFSET,
end_after_space: NO_PARSED_OFFSET,
};
}
impl Default for SourceExtents {
fn default() -> Self {
Self::UNSET
}
}
/// The conflicts-tracking map [`ObjectHandle::merge_resources`] populates:
/// `rtype -> old_key -> new_key`, mirroring
/// `QPDFObjectHandle::mergeResources`'s own
/// `std::map<std::string, std::map<std::string, std::string>>` parameter.
pub type ResourceConflicts =
std::collections::BTreeMap<Vec<u8>, std::collections::BTreeMap<Vec<u8>, Vec<u8>>>;
/// The document-owned resolver qpdf's `QPDFObject` calls through its owning
/// `QPDF*` and object identity. Kept crate-private so only the canonical
/// document implementation can resolve an indirect slot.
pub(crate) trait DocumentResolver {
fn resolve_indirect(&self, object_ref: ObjectRef, handle: &ObjectHandle) -> Result<()>;
/// Return whether qpdf's live object cache contains a newer generation for
/// this object number. A lower-generation handle removed by qpdf's
/// xref-chain cleanup has no remaining indirect identity when it resolves
/// to null (`QPDF.cc:710-718,1996-2005`); foreign-copy replacement must
/// therefore emit a direct null rather than reserve that stale identity.
fn has_newer_cached_generation(&self, _object_gen: QpdfObjGen) -> bool {
false
}
/// Return qpdf's source extent pair from the document-owned object cache.
/// Direct/contextless values and resolvers without a cache have no extent.
fn source_extents(&self, _object_gen: QpdfObjGen) -> SourceExtents {
SourceExtents::UNSET
}
/// Update qpdf's source extent pair on the document-owned object cache.
/// The default is a no-op for context-only test resolvers.
fn set_source_extents(&self, _object_gen: QpdfObjGen, _extents: SourceExtents) {}
/// Resolve the raw qpdf object identity carried by a canonical handle.
///
/// Ordinary test/document implementations can keep the valid
/// `ObjectRef` route. The document resolver overrides this boundary so a
/// parsed object header whose generation is outside the `N G R` parser
/// range still reaches qpdf's `QPDFObjGen`-keyed cache.
fn resolve_qpdf_obj_gen(&self, object_gen: QpdfObjGen, handle: &ObjectHandle) -> Result<()> {
let Some(object_ref) = object_gen.to_object_ref() else {
// No `ObjectRef` projection means qpdf's null fallback, not an
// error: an identity absent from the xref resolves to null
// (`libqpdf/QPDF.cc:1745-1748`).
handle.set_resolved(ObjectValue::Null);
return Ok(());
};
self.resolve_indirect(object_ref, handle)
}
/// The owning document identity carried by qpdf's `QPDF*` on parser-made
/// direct values (`QPDFValue::setDescription`,
/// `libqpdf/qpdf/QPDFValue.hh:60-66`). Detached/test resolvers have no
/// document owner.
fn pdf_unique_id(&self) -> Option<u64> {
None
}
/// The byte-preserving input name carried by qpdf's `InputSource`, used
/// when a stream accessor constructs a `QPDFExc` at the document boundary.
fn input_description(&self) -> Vec<u8> {
Vec::new()
}
/// Create qpdf's owned empty stream object for an ObjectHandle operation.
fn new_stream(&self) -> Result<ObjectHandle> {
Err(Error::Internal(
"stream creation requested from a resolver without a document".to_owned(),
))
}
/// Copy raw stream data into an already-created destination stream. The
/// destination resolver owns the provider registration, while the source
/// handle retains the source document's lazy dispatch boundary.
fn copy_stream_data(&self, destination: &ObjectHandle, source: &ObjectHandle) -> Result<()> {
let _ = (destination, source);
Err(Error::Internal(
"stream data copy requested from a resolver without a document".to_owned(),
))
}
/// Create qpdf's lazy provider for an original file-backed foreign
/// stream. Unlike a provider-backed source, this provider must not retain
/// the source `ObjectHandle`: qpdf captures the source input and stream
/// metadata so the source `QPDF` may be destroyed after the copy.
fn original_stream_data_provider(
&self,
source: &ObjectHandle,
destination_dict: &ObjectHandle,
) -> Result<Rc<dyn StreamDataProvider>> {
let _ = (source, destination_dict);
Err(Error::Internal(
"original stream data provider requested from a resolver without a document".to_owned(),
))
}
/// The destination-aware form used by qpdf's foreign-stream dispatch.
/// Test-only resolver implementations can keep the default behavior;
/// document-backed resolvers override it to route deferred warnings to
/// the destination document.
fn original_stream_data_provider_for_destination(
&self,
source: &ObjectHandle,
destination_dict: &ObjectHandle,
destination_resolver: Weak<dyn DocumentResolver>,
) -> Result<Rc<dyn StreamDataProvider>> {
let _ = destination_resolver;
self.original_stream_data_provider(source, destination_dict)
}
/// Deliver a warning raised while a destination stream is reading a
/// foreign source. qpdf's `pipeForeignStreamData` passes the destination
/// `QPDF` as `qpdf_for_warning` (`libqpdf/QPDF.cc:2565-2585`), even though
/// the bytes, `last_offset`, and location text (the exception's filename)
/// all belong to the captured source input: the static `pipeStreamData`
/// builds its `QPDFExc` from the explicit `file` argument, not from
/// `qpdf_for_warning` (`libqpdf/QPDF.cc:2477-2530`;
/// `libqpdf/QPDF_encryption.cc:1122-1128`). `description_override` carries
/// that captured source description when set; `self`'s own description is
/// used only for the ordinary (non-foreign) caller, which passes `None`.
fn warn_stream_data(&self, warning: QpdfExc) -> Result<()> {
let _ = warning;
Err(Error::Internal(
"stream data warning requested from a resolver without a document".to_owned(),
))
}
/// Whether this resolver is a qpdf source configured for immediate stream
/// copying (`QPDF::setImmediateCopyFrom`).
fn immediate_copy_from(&self) -> bool {
false
}
/// The document-side half of `QPDFObjectHandle::warn`
/// (`libqpdf/QPDFObjectHandle.cc:2385-2396`): `QPDF::warn`
/// (`libqpdf/QPDF.cc:487-494`) reached from an object rather than from a
/// caller that holds the document.
///
/// The message arrives fully formed, as qpdf's `QPDFExc` is by the time
/// it reaches `QPDF::warn`. The exception filename is `""`; its object
/// slot is filled from the handle description before the message reaches
/// this sink. Live parser values now carry that description, while
/// programmatic handles retain their existing empty/object-reference
/// fallback.
///
/// The default reports rather than swallows, matching
/// [`Self::pipe_stream_data`]'s. Every document-backed resolver overrides
/// it; qpdf has no resolver that cannot warn, so reaching this default is
/// the same condition as qpdf's null context, which `QPDFObjectHandle::warn`
/// also turns into a thrown exception.
fn warn(&self, warning: QpdfExc) -> Result<()> {
Err(Error::Internal(format!(
"warning raised through a resolver with no document warning sink: {warning}"
)))
}
#[allow(clippy::too_many_arguments)]
fn pipe_stream_data(
&self,
object_ref: ObjectRef,
offset: i64,
length: usize,
stream_dict: &ObjectHandle,
pipeline: &mut dyn crate::pipeline::Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
let _ = (
object_ref,
offset,
length,
stream_dict,
pipeline,
suppress_warnings,
will_retry,
);
Err(Error::Internal(
"stream data requested from a resolver without a stream source".to_owned(),
))
}
/// Raw qpdf object identity form used by original streams whose header
/// generation is outside the parser's `N G R` projection range.
#[allow(clippy::too_many_arguments)]
fn pipe_stream_data_qpdf_obj_gen(
&self,
object_gen: QpdfObjGen,
offset: i64,
length: usize,
stream_dict: &ObjectHandle,
pipeline: &mut dyn crate::pipeline::Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
let object_ref = object_gen.to_object_ref().ok_or_else(|| {
Error::Internal(format!(
"object {} {} is not a valid indirect reference",
object_gen.get_obj(),
object_gen.get_gen()
))
})?;
self.pipe_stream_data(
object_ref,
offset,
length,
stream_dict,
pipeline,
suppress_warnings,
will_retry,
)
}
}
#[cfg(test)]
mod parse_tests {
use super::*;
use crate::pipeline::{Pipeline, PipelineError, PipelineHandle, PipelineResult};
struct FailingWarningSink;
impl Pipeline for FailingWarningSink {
fn identifier(&self) -> &str {
"failing parse warning sink"
}
fn write(&mut self, _data: &[u8]) -> PipelineResult<()> {
Err(PipelineError::runtime("parse warning sink failed"))
}
fn finish(&mut self) -> PipelineResult<()> {
Ok(())
}
}
fn quiet_context() -> crate::Pdf<std::io::Cursor<Vec<u8>>> {
crate::Pdf::open_mem_owned_with_options(
include_bytes!("../../../tests/fixtures/minimal.pdf").to_vec(),
crate::PdfOpenOptions {
suppress_warnings: true,
..crate::PdfOpenOptions::default()
},
)
.expect("minimal PDF context")
}
#[test]
fn parse_without_context_rejects_a_nested_indirect_reference() {
// qpdf's `QPDFObjectHandle::parse("[1 0 R]")` has no owning
// document and therefore throws `std::logic_error` rather than
// inventing a detached reference. Returning a successfully parsed
// array here would hide the missing context boundary.
let error = ObjectHandle::parse(b"[1 0 R]").expect_err("missing parse context");
assert_eq!(
error.to_string(),
"QPDFParser::parse called without context on an object with indirect references"
);
}
#[test]
fn parse_without_context_keeps_nested_direct_values_contextless() {
let parsed = ObjectHandle::parse(b"<< /L1 << /L2 7 >> >>")
.expect("direct values do not need a parse context");
let level_one = parsed
.as_dictionary()
.and_then(|values| values.get(b"/L1".as_slice()).cloned())
.expect("level one dictionary");
let level_two = level_one
.as_dictionary()
.and_then(|values| values.get(b"/L2".as_slice()).cloned())
.expect("level two scalar");
let error = level_two
.object_warning("contextless explicit parse")
.expect_err("an explicit parse must not acquire a document context");
assert!(matches!(
error,
crate::Error::QpdfExc(warning)
if warning.get_object() == b"parsed object, at offset 14"
&& warning.get_message_detail() == b"contextless explicit parse"
));
}
#[test]
fn parse_without_context_stamps_the_qpdf_parsed_object_description() {
let parsed = ObjectHandle::parse(b"<< /Value 7 >>")
.expect("direct values do not need a parse context");
assert_eq!(parsed.description(), b"parsed object, at offset 2");
let value = parsed
.as_dictionary()
.and_then(|values| values.get(b"/Value".as_slice()).cloned())
.expect("parsed scalar");
assert_eq!(value.description(), b"parsed object, at offset 10");
let error = value
.object_warning("contextless explicit parse")
.expect_err("an explicit parse must remain contextless");
assert!(matches!(
error,
crate::Error::QpdfExc(warning)
if warning.get_object() == b"parsed object, at offset 10"
&& warning.get_message_detail() == b"contextless explicit parse"
));
}
#[test]
fn parse_without_context_turns_recovery_warnings_into_errors() {
let error = ObjectHandle::parse(b"{").expect_err("qpdf warning must fail explicit parse");
assert!(matches!(
error,
crate::Error::QpdfExc(warning)
if warning.get_filename() == b"parsed object"
&& warning.get_object().is_empty()
&& warning.get_file_position() == 0
&& warning.get_message_detail() == b"treating unexpected brace token as null"
));
}
#[test]
fn parse_without_context_rejects_the_501st_nested_container() {
// qpdf's heap-owned parser stack accepts 500 containers, then warns
// for the 501st. With no QPDF context, `QPDFParser::warn` throws that
// warning instead of recording it on the document.
let input = vec![b'['; 501];
let error =
ObjectHandle::parse(&input).expect_err("depth warning must fail explicit parse");
assert!(matches!(
error,
crate::Error::QpdfExc(warning)
if warning.get_filename() == b"parsed object"
&& warning.get_object().is_empty()
&& warning.get_message_detail()
== b"ignoring excessively deeply nested data structure"
));
}
#[test]
fn parse_without_context_keeps_the_first_warning_ahead_of_later_references() {
// `QPDFParser::warn` throws immediately when `context == nullptr`.
// The later `1 0 R` must not replace the earlier brace warning with
// the no-context indirect-reference logic error.
let error = ObjectHandle::parse(b"[ { 1 0 R ]")
.expect_err("the first recoverable condition must terminate parse");
assert!(matches!(
error,
crate::Error::QpdfExc(warning)
if warning.get_filename() == b"parsed object"
&& warning.get_object().is_empty()
&& warning.get_file_position() == 2
&& warning.get_message_detail() == b"treating unexpected brace token as null"
));
}
#[test]
fn parse_without_context_propagates_each_late_recovery_warning() {
for (input, expected) in [
(
b"bare-word".as_slice(),
"unknown token while reading object; treating as string",
),
(
b"<< /Last >>".as_slice(),
"dictionary ended prematurely; using null as value for last key",
),
(
b"<< /QPDFFake1 1 2 >>".as_slice(),
"expected dictionary key but found non-name object; inserting key /QPDFFake2",
),
(
b"<< /K 1 /K 2 >>".as_slice(),
"dictionary has duplicated key /K; last occurrence overrides earlier ones",
),
] {
let error = ObjectHandle::parse(input).expect_err("qpdf warning must fail parse");
assert!(matches!(
error,
crate::Error::QpdfExc(warning)
if warning.get_filename() == b"parsed object"
&& warning.get_object().is_empty()
&& warning.get_message_detail() == expected.as_bytes()
));
}
}
#[test]
fn parse_without_context_allows_only_c_whitespace_after_the_object() {
let parsed = ObjectHandle::parse(b"1 \t\r\n").expect("C whitespace is allowed");
assert_eq!(parsed.as_integer(), Some(1));
let error = ObjectHandle::parse(b"1 % not trailing whitespace")
.expect_err("a PDF comment is not C whitespace");
assert!(matches!(
error,
crate::Error::Parse {
offset: 0,
ref message,
} if message == "trailing data found parsing object from string"
));
}
#[test]
fn parse_with_description_preserves_qpdf_trailing_exception_offset() {
let error = ObjectHandle::parse_with_description(b"0 trailing", "trailing test")
.expect_err("qpdf must reject non-whitespace trailing data");
assert!(matches!(
error,
crate::Error::Parse {
offset: 0,
ref message,
} if message == "trailing data found parsing object from string"
));
}
#[test]
fn parse_with_context_keeps_canonical_unresolved_indirect_handles() {
let mut pdf = quiet_context();
let parsed = ObjectHandle::parse_with_context(&pdf, b"[5 0 R 5 0 R]", "indirect test")
.expect("context permits indirect references");
let items = parsed.as_array().expect("parsed array");
let first = items.first().expect("first indirect reference");
let second = items.get(1).expect("second indirect reference");
assert_eq!(first.object_ref(), Some(crate::ObjectRef::new(5, 0)));
assert!(first.is_same_object_as(second));
assert!(!first.is_resolved());
let canonical = pdf.get_object_handle(crate::ObjectRef::new(5, 0));
assert!(first.is_same_object_as(&canonical));
assert!(!canonical.is_resolved());
}
#[test]
fn parse_with_context_records_qpdf_described_recovery_warnings() {
let pdf = quiet_context();
let parsed = ObjectHandle::parse_with_context(&pdf, b"}", "brace test")
.expect("qpdf recovers a brace as null in document context");
assert!(parsed.is_null());
let diagnostics = pdf.repair_diagnostics();
assert_eq!(
diagnostics
.entries()
.first()
.map(|entry| String::from_utf8_lossy(entry.what_bytes()).into_owned()),
Some("parsed object (brace test): treating unexpected brace token as null".to_owned())
);
assert!(diagnostics
.entries()
.first()
.is_some_and(|warning| !warning.get_object().is_empty()));
}
#[test]
fn parse_with_context_routes_recovery_before_trailing_data_error() {
let pdf = quiet_context();
let error = ObjectHandle::parse_with_context(&pdf, b"} trailing", "context test")
.expect_err("qpdf throws after recording parser warnings");
assert!(matches!(
error,
crate::Error::Parse {
offset: 0,
ref message,
} if message == "trailing data found parsing object from string"
));
let diagnostics = pdf.repair_diagnostics();
assert_eq!(
diagnostics
.entries()
.first()
.map(|entry| String::from_utf8_lossy(entry.what_bytes()).into_owned()),
Some(
"parsed object (context test): treating unexpected brace token as null".to_owned()
)
);
}
#[test]
fn parse_with_context_formats_nonzero_described_warning_offsets() {
let pdf = quiet_context();
let parsed =
ObjectHandle::parse_with_context(&pdf, b"<< /QPDFFake1 1 2 >>", "dictionary test")
.expect("qpdf recovers a missing dictionary key");
assert!(parsed.as_dictionary().is_some());
let diagnostics = pdf.repair_diagnostics();
assert_eq!(
diagnostics
.entries()
.first()
.map(|entry| String::from_utf8_lossy(entry.what_bytes()).into_owned()),
Some(
"parsed object (dictionary test, offset 2): expected dictionary key but found non-name object; inserting key /QPDFFake2".to_owned()
)
);
}
#[test]
fn parse_with_context_preserves_raw_dictionary_key_bytes_in_duplicate_warning() {
let pdf = quiet_context();
let parsed =
ObjectHandle::parse_with_context(&pdf, b"<< /K#ff 1 /K#ff 2 >>", "raw dictionary key")
.expect("qpdf recovers a duplicate dictionary key");
assert_eq!(
parsed
.try_get_key(b"/K\xff")
.expect("the decoded raw key is present")
.as_integer(),
Some(2)
);
let diagnostics = pdf.repair_diagnostics();
let warning = diagnostics
.entries()
.first()
.expect("duplicate-key warning");
assert_eq!(
warning.get_message_detail(),
b"dictionary has duplicated key /K\xff; last occurrence overrides earlier ones"
);
assert_eq!(
warning.what_bytes(),
b"parsed object (raw dictionary key, offset 2): dictionary has duplicated key /K\xff; last occurrence overrides earlier ones"
);
}
#[test]
fn parse_without_context_preserves_raw_dictionary_key_bytes_in_qpdf_exception() {
let error =
ObjectHandle::parse_with_description(b"<< /K#ff 1 /K#ff 2 >>", "raw dictionary key")
.expect_err("qpdf throws a contextless duplicate-key warning");
assert!(matches!(
error,
crate::Error::QpdfExc(warning)
if warning.get_filename() == b"parsed object"
&& warning.get_object() == b"raw dictionary key"
&& warning.get_file_position() == 2
&& warning.get_message_detail()
== b"dictionary has duplicated key /K\xff; last occurrence overrides earlier ones"
&& warning.what_bytes()
== b"parsed object (raw dictionary key, offset 2): dictionary has duplicated key /K\xff; last occurrence overrides earlier ones"
));
}
#[test]
fn parse_with_context_propagates_warning_sink_failures_after_recording() {
let mut pdf = quiet_context();
let mut sink = FailingWarningSink;
assert_eq!(sink.identifier(), "failing parse warning sink");
sink.finish().expect("the test sink finish is infallible");
let logger = crate::QPDFLogger::create();
logger.set_warn(Some(PipelineHandle::new(sink)));
pdf.set_logger(logger);
pdf.set_suppress_warnings(false);
let error = ObjectHandle::parse_with_context(&pdf, b"}", "brace test")
.expect_err("warning sink failure must cross the parse boundary");
assert!(matches!(
error,
crate::Error::System(message) if message == "parse warning sink failed"
));
assert_eq!(pdf.repair_diagnostics().entries().len(), 1);
}
}
/// A shared, cloneable handle to a PDF object.
///
/// Cloning a handle is O(1) and does not deep-copy the underlying value;
/// every clone, direct or indirect, shares one canonical identity, payload,
/// and resolution state. This maps qpdf's shared `QPDFObject` allocation and
/// pointer-identity `isSameObjectAs` comparison
/// (`include/qpdf/QPDFObjectHandle.hh:304-309,1338-1350`,
/// `libqpdf/QPDFObjectHandle.cc:224-227`).
///
/// Document-created handles resolve indirect references lazily through their
/// document's qpdf-compatible resolver.
#[derive(Clone)]
pub struct ObjectHandle(Rc<RefCell<ObjectSlot>>);
impl Default for ObjectHandle {
fn default() -> Self {
Self::uninitialized()
}
}
/// Opaque canonical identity for an [`ObjectHandle`].
///
/// The retained slot keeps the allocation alive while a traversal set uses
/// the key. Equality and hashing compare the slot pointer only, matching
/// qpdf's `QPDFObjectHandle::isSameObjectAs` rather than structural value
/// equality (`include/qpdf/QPDFObjectHandle.hh:304-309`,
/// `libqpdf/QPDFObjectHandle.cc:224-227`).
#[derive(Clone)]
pub(crate) struct ObjectHandleIdentity(Rc<RefCell<ObjectSlot>>);
impl PartialEq for ObjectHandleIdentity {
fn eq(&self, other: &Self) -> bool {
Rc::ptr_eq(&self.0, &other.0)
}
}
impl Eq for ObjectHandleIdentity {}
impl Hash for ObjectHandleIdentity {
fn hash<H: Hasher>(&self, state: &mut H) {
Rc::as_ptr(&self.0).hash(state);
}
}
// Hand-written rather than derived: a resolved value can hold other
// `ObjectHandle`s sharing canonical `Rc` identities (array/dict/stream-dict
// children — see `Pdf::drop`'s own comment on indirect cycles). A self- or
// reciprocal reference would make a derived, recursively-expanding `Debug`
// walk back into the same slot forever. Snapshot only metadata and the state
// name, never the resolved value, so formatting is total for direct and
// indirect cycles alike.
impl std::fmt::Debug for ObjectHandle {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let slot = self.0.borrow();
let (state, parsed_offset) = {
let shared = slot.shared.borrow();
(
match &shared.value {
ObjectValue::Unresolved => "Unresolved",
ObjectValue::Reserved => "Reserved",
ObjectValue::Destroyed => "Destroyed",
_ => "Resolved(..)",
},
shared.parsed_offset,
)
};
let label = if slot.is_indirect() {
"ObjectHandle::Indirect"
} else {
"ObjectHandle::Direct"
};
f.debug_struct(label)
.field("object_ref", &slot.object_ref())
.field("state", &state)
.field("parsed_offset", &parsed_offset)
.finish()
}
}
#[derive(Clone)]
pub(crate) struct ChildDescription {
parent: Weak<RefCell<SharedValueState>>,
static_descr: Vec<u8>,
var_descr: Vec<u8>,
}
#[derive(Clone)]
pub(crate) struct JsonDescription {
pub(crate) input: Vec<u8>,
pub(crate) object: Vec<u8>,
}
#[derive(Clone)]
/// qpdf's `QPDFValue::Description`, whose `std::string` payload is an
/// arbitrary byte sequence rather than a UTF-8 contract.
pub(crate) enum ObjectDescription {
/// qpdf's parser owns one shared Description per parse call; keep only an
/// Rc handle in each value rather than copying the template bytes.
Template(Rc<Vec<u8>>),
/// Keep the larger qpdf description shapes out of every common value
/// allocation by boxing their independent payloads.
Json(Box<JsonDescription>),
Child(Box<ChildDescription>),
}
#[cfg(test)]
mod reverse_containment_layout_tests {
use super::*;
#[test]
fn reverse_containment_state_does_not_live_in_production_slots() {
assert!(std::mem::size_of::<ObjectSlot>() < 56);
assert!(std::mem::size_of::<SharedValueState>() < 136);
}
#[test]
fn production_source_has_no_reverse_containment_fields() {
let source = include_str!("object_handle.rs");
let containment_field = ["containment_", "parents"].concat();
let owner_field = ["state_", "owners"].concat();
assert!(!source.contains(&containment_field));
assert!(!source.contains(&owner_field));
}
#[test]
fn source_extent_state_does_not_live_in_production_slots() {
assert!(std::mem::size_of::<ObjectSlot>() < 40);
}
/// A slot costs one shared pointer and the flag that says whether it
/// points at anything — nothing per name/number tree.
///
/// qpdf's name/number tree keeps its owning `QPDF` on the tree itself
/// (`NNTreeImpl::qpdf`, `libqpdf/qpdf/NNTree.hh:125`); the document claim
/// belongs to the tree, not to every object handle in the file. Measuring
/// the slot rather than searching this file for a field name keeps the
/// claim attached to what it costs: an `Option<NonZeroU64>` claim per slot
/// grew `ObjectSlot` from 16 to 24 bytes on a 64-bit target. The looser
/// bounds above (`< 56`, `< 40`) do not reject that growth.
#[test]
fn tree_document_claim_does_not_live_in_production_slots() {
assert!(
std::mem::size_of::<ObjectSlot>()
<= std::mem::size_of::<Rc<RefCell<SharedValueState>>>()
+ std::mem::size_of::<usize>(),
"name/number-tree ownership belongs to NNTree, not every ObjectSlot"
);
}
#[test]
fn raw_identity_width_does_not_widen_shared_value_metadata() {
assert_eq!(std::mem::size_of::<QpdfObjGen>(), 8);
assert_eq!(std::mem::size_of::<Option<QpdfObjGen>>(), 12);
assert!(std::mem::size_of::<ValueIdentity>() <= 40);
}
}
fn replace_first(bytes: &mut Vec<u8>, needle: &[u8], replacement: &[u8]) {
if let Some(position) = bytes
.windows(needle.len())
.position(|window| window == needle)
{
bytes.splice(
position..position + needle.len(),
replacement.iter().copied(),
);
}
}
fn expand_description_template(
template: &[u8],
object_gen: Option<QpdfObjGen>,
state: &ObjectValue,
parsed_offset: i64,
) -> Vec<u8> {
let og = object_gen
.map(|object_gen| format!("{} {}", object_gen.get_obj(), object_gen.get_gen()).into_bytes())
.unwrap_or_default();
let shift = match state {
ObjectValue::Dictionary(_) | ObjectValue::Stream(_) => 2,
ObjectValue::Array(_) => 1,
_ => 0,
};
let offset = if parsed_offset >= 0 {
(parsed_offset + shift).to_string().into_bytes()
} else {
parsed_offset.to_string().into_bytes()
};
// qpdf's QPDFValue::getDescription performs one `find`/`replace` for
// each marker (`libqpdf/QPDFValue.cc:23-31`). There is no `$$` escape
// convention: unknown and repeated markers remain in the result.
let mut result = template.to_vec();
replace_first(&mut result, b"$OG", &og);
replace_first(&mut result, b"$PO", &offset);
result
}
// Deliberately not `Debug`: see `ObjectHandle`'s own hand-written `Debug`
// impl above for why a derived one is unsafe here (object-handle cycles).
// This is flpdf's counterpart to qpdf's QPDFValue allocation: every field
// here moves as one value pointer through QPDFObject::assign/swapWith.
struct SharedValueState {
value: ObjectValue,
identity: ValueIdentity,
parsed_offset: i64,
/// qpdf keeps `Description` behind an optional shared pointer
/// (`libqpdf/qpdf/QPDFValue.hh:58-82,141-144`). The parser template keeps
/// its payload in one Rc allocation per parse call; JSON and child forms
/// remain boxed to keep their larger shapes out of every value allocation.
description: Option<ObjectDescription>,
}
impl SharedValueState {
fn qpdf_obj_gen(&self) -> Option<QpdfObjGen> {
self.identity.qpdf_obj_gen
}
fn object_ref(&self) -> Option<ObjectRef> {
self.qpdf_obj_gen().and_then(QpdfObjGen::to_object_ref)
}
fn get_description(&self) -> Vec<u8> {
if let Some(desc) = &self.description {
match desc {
ObjectDescription::Template(tmpl) => expand_description_template(
tmpl.as_slice(),
self.qpdf_obj_gen(),
&self.value,
self.parsed_offset,
),
ObjectDescription::Json(j) => {
let mut result = j.input.clone();
if !j.object.is_empty() {
result.extend_from_slice(b", ");
result.extend_from_slice(&j.object);
}
result.extend_from_slice(b" at offset ");
result.extend_from_slice(self.parsed_offset.to_string().as_bytes());
result
}
ObjectDescription::Child(child) => {
let mut result = child
.parent
.upgrade()
.map(|parent| parent.borrow().get_description())
.unwrap_or_default();
result.extend_from_slice(&child.static_descr);
// qpdf's child branch replaces only the first marker in
// the already-rendered parent/static string
// (`libqpdf/QPDFValue.cc:52-54`).
replace_first(&mut result, b"$VD", &child.var_descr);
result
}
}
} else if let Some(object_gen) = self.qpdf_obj_gen() {
format!("object {} {}", object_gen.get_obj(), object_gen.get_gen()).into_bytes()
} else {
Vec::new()
}
}
}
fn new_shared_value_state(
value: ObjectValue,
identity: ValueIdentity,
parsed_offset: i64,
) -> Rc<RefCell<SharedValueState>> {
new_shared_value_state_with_description(value, identity, parsed_offset, None)
}
fn new_shared_value_state_with_description(
value: ObjectValue,
identity: ValueIdentity,
parsed_offset: i64,
description: Option<ObjectDescription>,
) -> Rc<RefCell<SharedValueState>> {
Rc::new(RefCell::new(SharedValueState {
value,
identity,
parsed_offset,
description,
}))
}
// This outer allocation corresponds to qpdf's QPDFObject. It preserves
// handle/cache/provenance identity while its `shared` QPDFValue counterpart
// can be assigned independently.
struct ObjectSlot {
/// Whether this handle points at an actual qpdf object allocation.
/// qpdf's default-constructed `QPDFObjectHandle` has no value at all;
/// keeping this separate from `ObjectValue::Unresolved` preserves that
/// state from both an initialized lazy indirect object and a null value.
initialized: bool,
shared: Rc<RefCell<SharedValueState>>,
}
// Reverse containment is needed only by unit-test diagnostics that assert the
// current indirect roots of a direct value. Keep that observation out of the
// production ObjectSlot/SharedValueState layout: tests register live slots and
// derive parent paths from their forward children instead of maintaining a
// second ownership graph during every mutation.
#[cfg(test)]
thread_local! {
static TEST_SLOTS: RefCell<Vec<Weak<RefCell<ObjectSlot>>>> = const { RefCell::new(Vec::new()) };
static STATE_CHILDREN_VECTOR_CALLS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
static OBJECT_REF_PROMOTION_CALLS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
static DETACHED_STATE_REBIND_ALLOCATIONS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}
#[cfg(test)]
fn register_test_slot(slot: &Rc<RefCell<ObjectSlot>>) {
TEST_SLOTS.with(|slots| slots.borrow_mut().push(Rc::downgrade(slot)));
}
#[cfg(not(test))]
fn register_test_slot(_slot: &Rc<RefCell<ObjectSlot>>) {}
#[cfg(test)]
pub(crate) fn object_ref_promotion_calls_for_test() -> usize {
OBJECT_REF_PROMOTION_CALLS.with(std::cell::Cell::get)
}
#[cfg(test)]
pub(crate) fn detached_state_rebind_allocations_for_test() -> usize {
DETACHED_STATE_REBIND_ALLOCATIONS.with(std::cell::Cell::get)
}
#[cfg(test)]
fn registered_test_slots() -> Vec<ObjectHandle> {
TEST_SLOTS.with(|slots| {
let mut slots = slots.borrow_mut();
slots.retain(|candidate| candidate.strong_count() != 0);
slots
.iter()
.filter_map(Weak::upgrade)
.map(ObjectHandle)
.collect()
})
}
/// The active identity on qpdf's shared QPDFValue (QPDFValue.hh:68-72).
/// One raw ObjGen is the canonical object identity; the valid ObjectRef view
/// is derived only at the parser/public projection boundary. The document
/// back-pointer is represented by its unique id and weak resolver.
#[derive(Clone, Default)]
struct ValueIdentity {
qpdf_obj_gen: Option<QpdfObjGen>,
/// qpdf's nullable/default document identity (`QPDFValue.hh:149-152` and
/// `QPDF.hh:1454`) represented with the zero niche.
active_pdf_unique_id: Option<NonZeroU64>,
resolver: Option<Weak<dyn DocumentResolver>>,
}
impl ObjectSlot {
fn qpdf_obj_gen(&self) -> Option<QpdfObjGen> {
self.shared.borrow().qpdf_obj_gen()
}
fn object_ref(&self) -> Option<ObjectRef> {
self.shared.borrow().object_ref()
}
fn is_indirect(&self) -> bool {
let shared = self.shared.borrow();
shared
.identity
.qpdf_obj_gen
.is_some_and(QpdfObjGen::is_indirect)
}
fn active_pdf_unique_id(&self) -> Option<u64> {
self.shared
.borrow()
.identity
.active_pdf_unique_id
.map(NonZeroU64::get)
}
fn resolver(&self) -> Option<Weak<dyn DocumentResolver>> {
self.shared.borrow().identity.resolver.clone()
}
fn get_description(&self) -> Vec<u8> {
self.shared.borrow().get_description()
}
}
/// The stream-specific payload of a direct `ObjectHandle`, mirroring qpdf's
/// `QPDF_Stream` derived value (`libqpdf/qpdf/QPDF_Stream.hh`).
#[derive(Debug, Clone)]
pub(crate) struct StreamValue {
pub(crate) stream_dict: ObjectHandle,
/// `None` means original source bytes; `Some` is replacement data.
pub(crate) stream_data: Option<Rc<Vec<u8>>>,
/// A deferred replacement source, mutually exclusive with `stream_data`.
pub(crate) stream_provider: Option<Rc<dyn StreamDataProvider>>,
/// Whether qpdf's writer may decode, normalize, or recompress this stream.
pub(crate) filter_on_write: bool,
/// Parse-time length for the original-source branch.
pub(crate) stream_length: usize,
/// qpdf's stream-local token-filter list.
pub(crate) stream_token_filters: StreamTokenFilterList,
/// flpdf's writer-only completed content-normalization marker.
// qpdf-deviation: no qpdf QPDF_Stream field records this external marker.
pub(crate) content_normalization_applied: bool,
}
/// The value payload of a direct `ObjectHandle`, mirroring qpdf's
/// `QPDFValue` type family (`libqpdf/qpdf/QPDFValue.hh`).
///
/// Array and dictionary children are [`ObjectHandle`]s rather than raw
/// nested `ObjectValue`s, so cloning a container clones only `Rc` handles
/// (O(1) per child), not the subtree.
#[derive(Debug, Clone)]
pub(crate) enum ObjectValue {
Null,
/// qpdf's lazy cache sentinel (`QPDF_Unresolved`), whose object identity
/// and resolver context remain on the surrounding [`ObjectSlot`].
Unresolved,
/// qpdf's document-allocation sentinel (`QPDF_Reserved`).
Reserved,
/// qpdf's post-document-lifetime sentinel (`QPDF_Destroyed`).
Destroyed,
Boolean(bool),
Integer(i64),
Real(f64),
/// Preserves a non-canonical source spelling (e.g. `.4`) alongside its
/// parsed value, so that a real number written in the source PDF unparses
/// byte-identically.
RealLiteral {
value: f64,
literal: Vec<u8>,
},
Name(Vec<u8>),
String(Vec<u8>),
/// A content-stream operator token (e.g. `q`, `Do`). Only meaningful inside a content stream
/// (`include/qpdf/QPDFObjectHandle.hh:318-319`: "Operator and
/// InlineImage are only allowed in content streams").
Operator(Vec<u8>),
/// Raw inline-image (`BI`...`ID`...`EI`) bytes. Same content-stream-only constraint
/// as `Operator` above.
InlineImage(Vec<u8>),
Array(Vec<ObjectHandle>),
Dictionary(std::collections::BTreeMap<Vec<u8>, ObjectHandle>),
/// The stream payload is boxed so scalar/container values do not carry
/// qpdf's stream subclass layout. The box is paid only by stream values.
Stream(Box<StreamValue>),
}
fn empty_object_slot() -> Rc<RefCell<ObjectSlot>> {
Rc::new(RefCell::new(ObjectSlot {
initialized: false,
shared: new_shared_value_state(
ObjectValue::Unresolved,
ValueIdentity::default(),
NO_PARSED_OFFSET,
),
}))
}
impl ObjectValue {
/// Return qpdf's value-layer type ordinal.
///
/// qpdf stores this as `QPDFValue::type_code` and lets
/// `QPDFObject::getTypeCode` read it directly
/// (`libqpdf/qpdf/QPDFObject_private.hh:42-50`). The enum match is the
/// Rust equivalent of each `QPDFValue` subclass initializing that field.
pub(crate) fn type_code(&self) -> u8 {
match self {
Self::Null => 2,
Self::Unresolved => 13,
Self::Reserved => 1,
Self::Destroyed => 14,
Self::Boolean(_) => 3,
Self::Integer(_) => 4,
Self::Real(_) | Self::RealLiteral { .. } => 5,
Self::String(_) => 6,
Self::Name(_) => 7,
Self::Array(_) => 8,
Self::Dictionary(_) => 9,
Self::Stream(_) => 10,
Self::Operator(_) => 11,
Self::InlineImage(_) => 12,
}
}
/// Return qpdf's value-layer type name.
///
/// This mirrors `QPDFValue::type_name`, which
/// `QPDFObject::getTypeName` reads alongside `type_code`
/// (`libqpdf/qpdf/QPDFObject_private.hh:52-60`).
pub(crate) fn type_name(&self) -> &'static str {
match self {
Self::Null => "null",
Self::Unresolved => "unresolved",
Self::Reserved => "reserved",
Self::Destroyed => "destroyed",
Self::Boolean(_) => "boolean",
Self::Integer(_) => "integer",
Self::Real(_) | Self::RealLiteral { .. } => "real",
Self::String(_) => "string",
Self::Name(_) => "name",
Self::Array(_) => "array",
Self::Dictionary(_) => "dictionary",
Self::Stream(_) => "stream",
Self::Operator(_) => "operator",
Self::InlineImage(_) => "inline-image",
}
}
}
/// qpdf stores dictionary names in their canonical name-string form, including
/// the leading slash (`QPDFObjectHandle.hh:747-780`; `QPDF_Dictionary.cc:97-153`).
/// The legacy `Object`/`Dictionary` bridge deliberately omits that slash, so
/// conversion happens only at the boundary between the two representations.
pub(crate) fn canonical_dictionary_key(key: &[u8]) -> Vec<u8> {
if key.first() == Some(&b'/') {
key.to_vec()
} else {
let mut canonical = Vec::with_capacity(key.len() + 1);
canonical.push(b'/');
canonical.extend_from_slice(key);
canonical
}
}
fn canonicalize_object_value(value: ObjectValue) -> ObjectValue {
match value {
ObjectValue::Dictionary(entries) => {
if entries.keys().all(|key| key.starts_with(b"/")) {
ObjectValue::Dictionary(entries)
} else {
ObjectValue::Dictionary(
entries
.into_iter()
.map(|(key, value)| (canonical_dictionary_key(&key), value))
.collect(),
)
}
}
other => other,
}
}
#[cfg(test)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
struct ContainmentOwner {
pdf_unique_id: Option<u64>,
object_ref: ObjectRef,
}
/// The all-zero-default matrix nested inside qpdf's `QPDFObjectHandle`.
///
/// This is intentionally distinct from [`crate::Matrix`]. qpdf's nested
/// `QPDFObjectHandle::Matrix` defaults to six zeroes, while the standalone
/// affine matrix used by flpdf defaults to the identity transform
/// (`include/qpdf/QPDFObjectHandle.hh:239-267`).
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct ObjectHandleMatrix {
/// Horizontal scale and rotation component.
pub a: f64,
/// Vertical rotation component.
pub b: f64,
/// Horizontal rotation component.
pub c: f64,
/// Vertical scale and rotation component.
pub d: f64,
/// Horizontal translation.
pub e: f64,
/// Vertical translation.
pub f: f64,
}
impl ObjectHandleMatrix {
/// Construct a qpdf object-handle matrix from its six components.
pub const fn new(a: f64, b: f64, c: f64, d: f64, e: f64, f: f64) -> Self {
Self { a, b, c, d, e, f }
}
}
/// A qpdf-shaped view over the items of an array handle.
pub struct ArrayItems {
array: ObjectHandle,
}
/// A reversible cursor over [`ArrayItems`]. The cursor keeps the canonical
/// array handle and returns an owned handle clone for its current child.
pub struct ArrayItemCursor {
array: ObjectHandle,
index: usize,
}
/// A qpdf-shaped view over the entries of a dictionary handle.
pub struct DictItems {
dictionary: ObjectHandle,
keys: Rc<Vec<Vec<u8>>>,
}
/// One dictionary entry returned by [`DictItemCursor::current`]. At the end
/// cursor its value is an explicit uninitialized handle, matching qpdf's
/// default iterator value rather than a null object.
pub struct DictItem {
/// The canonical slash-prefixed dictionary key.
pub key: Vec<u8>,
/// The value handle fetched for this key, or an uninitialized handle at
/// the end.
pub value: ObjectHandle,
}
/// A reversible cursor over [`DictItems`].
pub struct DictItemCursor {
dictionary: ObjectHandle,
keys: Rc<Vec<Vec<u8>>>,
index: usize,
}
impl ArrayItems {
/// Return a cursor positioned at the first item, or at end for an empty
/// array.
pub fn begin(&self) -> ArrayItemCursor {
ArrayItemCursor::new(self.array.clone(), 0)
}
/// Return a cursor positioned at the end sentinel.
pub fn end(&self) -> ArrayItemCursor {
ArrayItemCursor::new(self.array.clone(), self.len())
}
fn len(&self) -> usize {
ArrayItemCursor::array_len(&self.array)
}
}
impl ArrayItemCursor {
fn new(array: ObjectHandle, index: usize) -> Self {
Self { array, index }
}
/// Read the array length without cloning every child handle, unlike
/// [`ObjectHandle::as_array`]. Every cursor step calls this, so an O(n)
/// clone here would make a full traversal O(n²).
fn array_len(array: &ObjectHandle) -> usize {
array.with_value(|value| match value {
Some(ObjectValue::Array(children)) => children.len(),
_ => 0,
})
}
fn len(&self) -> usize {
Self::array_len(&self.array)
}
/// Return the current child handle, or an uninitialized handle at the
/// cursor's end position. The returned handle shares the selected child's
/// canonical identity but does not follow later cursor movement, matching
/// a value copy of qpdf's iterator `ivalue`.
pub fn current(&mut self) -> ObjectHandle {
self.array
.with_value(|value| match value {
Some(ObjectValue::Array(children)) => children.get(self.index).cloned(),
_ => None,
})
.unwrap_or_else(ObjectHandle::uninitialized)
}
/// Advance one item, retaining the end sentinel when already at end.
pub fn next(&mut self) {
self.index = self.index.saturating_add(1).min(self.len());
}
/// Move one item backward, retaining the begin sentinel when already at
/// the first item.
pub fn previous(&mut self) {
self.index = self.index.saturating_sub(1);
}
/// Whether the cursor is at or beyond the current end.
pub fn is_end(&self) -> bool {
self.index >= self.len()
}
}
impl DictItems {
/// Return a cursor positioned at the first key, or at end for an empty
/// dictionary.
pub fn begin(&self) -> DictItemCursor {
DictItemCursor::new(self.dictionary.clone(), self.keys.clone(), 0)
}
/// Return a cursor positioned at the end sentinel.
pub fn end(&self) -> DictItemCursor {
DictItemCursor::new(self.dictionary.clone(), self.keys.clone(), self.len())
}
fn len(&self) -> usize {
self.keys.len()
}
}
impl DictItemCursor {
fn new(dictionary: ObjectHandle, keys: Rc<Vec<Vec<u8>>>, index: usize) -> Self {
Self {
dictionary,
keys,
index,
}
}
/// Return the current entry. At the key snapshot's end, the key is empty
/// and the value is an explicit uninitialized handle. At every non-end
/// position, the value comes from the live dictionary's `get_key` path, so
/// a removed key returns an initialized null and a non-dictionary receiver
/// follows qpdf's contextual warning/null contract.
pub fn current(&mut self) -> DictItem {
let Some(key) = self.keys.get(self.index) else {
return DictItem {
key: Vec::new(),
value: ObjectHandle::uninitialized(),
};
};
DictItem {
key: key.clone(),
value: self
.dictionary
.try_get_key(key)
.unwrap_or_else(|error| panic!("DictItemCursor::current failed: {error}")),
}
}
/// Advance one entry, retaining the end sentinel when already at end.
pub fn next(&mut self) {
self.index = self.index.saturating_add(1).min(self.len());
}
/// Move one entry backward, retaining the begin sentinel when already at
/// the first entry.
pub fn previous(&mut self) {
self.index = self.index.saturating_sub(1);
}
/// Whether the cursor is at or beyond the current end.
pub fn is_end(&self) -> bool {
self.index >= self.len()
}
fn len(&self) -> usize {
self.keys.len()
}
}
impl ObjectHandle {
/// Construct qpdf's default, uninitialized handle.
///
/// This is distinct from an initialized indirect handle whose value is
/// still unresolved, and from an initialized null. Type predicates return
/// false for it without attempting resolution; operations that require a
/// value report qpdf's uninitialized-handle error at the dereference
/// boundary (`include/qpdf/QPDFObjectHandle.hh:325-326`).
pub fn uninitialized() -> Self {
let handle = Self(empty_object_slot());
register_test_slot(&handle.0);
handle
}
/// Whether this handle has a qpdf object allocation behind it.
pub fn is_initialized(&self) -> bool {
self.0.borrow().initialized
}
/// Parse one standalone PDF object without an owning document context.
///
/// This ports `QPDFObjectHandle::parse(string)`: malformed input that
/// would make qpdf warn is an error here, only C whitespace may trail the
/// object, and a nested indirect reference is rejected because no
/// document can canonicalize it. Parse an indirect file object through
/// [`crate::Pdf`] instead when object-cache identity is required.
///
/// qpdf correspondence: `QPDFObjectHandle::parse`
/// (`libqpdf/QPDFObjectHandle.cc:1672-1698`) and no-context indirect
/// reference handling in `QPDFParser::parseRemainder`
/// (`libqpdf/QPDFParser.cc:135-176`).
pub fn parse(input: &[u8]) -> Result<Self> {
crate::parser::parse_explicit_object_handle(input)
}
/// Parse one standalone PDF object with qpdf's object description.
///
/// This is the Rust spelling of the public qpdf overload
/// `QPDFObjectHandle::parse(string, object_description)`. The input has no
/// owning document, so recoverable parser warnings remain errors and
/// nested indirect references return the qpdf logic-error equivalent.
///
/// qpdf correspondence: `QPDFObjectHandle::parse`
/// (`libqpdf/QPDFObjectHandle.cc:1672-1698`) and the `QPDFParser` warning
/// boundary (`libqpdf/QPDFParser.cc:488-518`).
pub fn parse_with_description(input: &[u8], object_description: &str) -> Result<Self> {
crate::parser::parse_explicit_object_handle_with_description(input, object_description)
}
/// Parse one PDF object with a document-owned qpdf context.
///
/// Indirect references are inserted into the document's canonical object
/// cache without being resolved, and parser recovery warnings are recorded
/// on that document in qpdf order. This is the Rust spelling of
/// `QPDFObjectHandle::parse(QPDF*, string, object_description)`.
///
/// qpdf correspondence: `QPDFObjectHandle::parse`
/// (`libqpdf/QPDFObjectHandle.cc:1678-1698`),
/// `QPDFParser::parseRemainder` (`libqpdf/QPDFParser.cc:135-176`), and
/// `QPDF::getObject` (`libqpdf/QPDF.cc:1952-1959`).
pub fn parse_with_context<R: std::io::Read + std::io::Seek + 'static>(
pdf: &crate::Pdf<R>,
input: &[u8],
object_description: &str,
) -> Result<Self> {
pdf.resolver
.parse_object_handle_from_bytes(input, object_description)
}
/// True if this handle wraps a value constructed directly, without an
/// indirect object number/generation.
pub fn is_direct(&self) -> bool {
!self.0.borrow().is_indirect()
}
/// True if this handle refers to an indirect object.
pub fn is_indirect(&self) -> bool {
self.0.borrow().is_indirect()
}
/// True if this handle is qpdf's internal reserved construction sentinel.
///
/// The sentinel is represented as an `ObjectValue`, while the surrounding
/// slot retains its indirect identity and resolver metadata
/// (`include/qpdf/Constants.h:108-127`,
/// `libqpdf/QPDF_Reserved.cc:1-27`). [`crate::Pdf::new_reserved`]'s own
/// sentinel always has an indirect identity and document owner, but
/// [`Self::shallow_copy`] on a reserved handle mirrors
/// `QPDF_Reserved::copy` (`libqpdf/QPDF_Reserved.cc:14-19`) and produces
/// a second, *direct* reserved handle with neither — so indirect
/// identity is this sentinel's common case, not a universal one.
pub fn is_reserved(&self) -> bool {
self.with_value(|value| matches!(value, Some(ObjectValue::Reserved)))
}
/// The valid PDF `N G R` projection for an indirect handle, or `None` for
/// a direct handle and for a raw qpdf identity outside the valid reference
/// syntax (for example generation 65535).
pub fn object_ref(&self) -> Option<ObjectRef> {
self.0.borrow().object_ref()
}
/// The qpdf raw object identity carried by this handle, if it has one.
/// Unlike [`Self::object_ref`], this preserves generations that
/// qpdf accepts in an object header but rejects in an `N G R` reference.
pub(crate) fn qpdf_obj_gen(&self) -> Option<QpdfObjGen> {
self.0.borrow().qpdf_obj_gen()
}
/// Return whether this null-resolved handle is a lower generation that
/// qpdf has already superseded in the owning document's live cache.
/// Foreign-copy uses this at the array-element boundary where qpdf emits
/// a direct null after `removeObject`, while a genuinely absent object
/// number remains an indirect null reference.
pub(crate) fn has_newer_cached_generation(&self) -> bool {
let Some(object_gen) = self.qpdf_obj_gen() else {
return false;
};
self.context()
.is_some_and(|resolver| resolver.has_newer_cached_generation(object_gen))
}
/// The owning document identity carried by this canonical handle, if it
/// was minted by a [`crate::Pdf`]. This is qpdf's source-QPDF identity
/// key used by `QPDF::copyForeignObject`'s per-source `ObjCopier` map
/// (`libqpdf/QPDF.cc:2065`).
pub fn owning_pdf_unique_id(&self) -> Option<u64> {
self.0.borrow().active_pdf_unique_id()
}
/// True if `self` and `other` share the same underlying storage — the
/// same canonical object, not merely an equal value.
///
/// This is qpdf's `QPDFObjectHandle::isSameObjectAs`: mutations and lazy
/// resolution observed through either handle affect the same allocation
/// (`include/qpdf/QPDFObjectHandle.hh:304-309`,
/// `libqpdf/QPDFObjectHandle.cc:224-227`).
pub fn is_same_object_as(&self, other: &Self) -> bool {
Rc::ptr_eq(&self.0, &other.0)
}
/// Return a stable set key for this canonical allocation.
pub(crate) fn identity_key(&self) -> ObjectHandleIdentity {
ObjectHandleIdentity(self.0.clone())
}
#[cfg(test)]
fn ptr_eq(&self, other: &Self) -> bool {
self.is_same_object_as(other)
}
/// An indirect slot without an owning document resolver. This is the
/// detached handle shape used by syntax-only parser boundaries.
pub(crate) fn new_indirect_unresolved(object_ref: ObjectRef, offset: i64) -> Self {
Self::new_indirect_unresolved_with_identity(object_ref, offset, None, None)
}
/// Construct a canonical unresolved slot carrying both its owning
/// document's identity and that document's resolver — what
/// `Pdf::get_object_handle` needs to hand out.
///
/// Neither half is sufficient alone. The resolver is what
/// [`Self::try_dereference`] upgrades and calls; the identity is what
/// [`Self::belongs_to_pdf`] answers on. [`Self::set_resolved`] installs
/// the resolved value and its forward child graph independently.
///
/// `pdf_unique_id` itself ports qpdf's document-level unique id:
/// `QPDF::getUniqueId` (`include/qpdf/QPDF.hh:283`,
/// `libqpdf/QPDF.cc:2294-2296`) over the member
/// `unsigned long long unique_id{0}` (`include/qpdf/QPDF.hh:1454`),
/// minted from a function-static atomic counter in the constructor
/// (`libqpdf/QPDF.cc:211-212`). `Pdf`'s own `NEXT_PDF_ID.fetch_add`
/// (`reader.rs:645`) is that same mechanism, serving the same
/// cross-document identity purpose qpdf uses it for: keying
/// `m->object_copiers` by the *other* document's id
/// (`libqpdf/QPDF.cc:2065`, already noted at `reader.rs:82`) and
/// comparing two documents for sameness
/// (`libqpdf/QPDFPageObjectHelper.cc:1020`).
///
/// Storing that id *per object* does have a qpdf counterpart -- it is a
/// container representation substitute (CLAUDE.md class (B)), not a
/// class (C) deviation. A qpdf value reaches its document through a raw
/// `QPDF*` back-pointer
/// (`libqpdf/qpdf/QPDFValue.hh:150`, `QPDF* qpdf{nullptr}`) which
/// `QPDFObject::doResolve` hands straight to `QPDF::Resolver::resolve`
/// (`libqpdf/QPDFObject.cc:6-11`), so upstream one pointer is both the
/// identity and the route to the resolver. This port splits that single
/// pointer into a plain tag plus a `Weak`, which is why both arguments
/// have to be supplied together here.
#[cfg(test)]
pub(crate) fn new_indirect_for_pdf_with_resolver(
object_ref: ObjectRef,
offset: i64,
pdf_unique_id: u64,
resolver: Weak<dyn DocumentResolver>,
) -> Self {
Self::new_indirect_unresolved_with_identity(
object_ref,
offset,
Some(pdf_unique_id),
Some(resolver),
)
}
/// Construct a canonical unresolved slot from qpdf's raw object identity.
/// The valid `ObjectRef` view is only a projection of this identity.
pub(crate) fn new_indirect_for_qpdf_obj_gen_with_resolver(
object_gen: QpdfObjGen,
offset: i64,
pdf_unique_id: u64,
resolver: Weak<dyn DocumentResolver>,
) -> Self {
Self::new_indirect_unresolved_qpdf_obj_gen_with_identity(
object_gen,
offset,
Some(pdf_unique_id),
Some(resolver),
)
}
/// Construct qpdf's document-owned reserved sentinel with a fresh
/// indirect identity. The resolver link is weak for the same lifetime
/// reason as ordinary canonical handles.
pub(crate) fn new_reserved_for_pdf(
object_ref: ObjectRef,
pdf_unique_id: u64,
resolver: Weak<dyn DocumentResolver>,
) -> Self {
let Some(qpdf_obj_gen) = QpdfObjGen::try_from_object_ref(object_ref).ok() else {
return Self::uninitialized();
};
let handle = Self(Rc::new(RefCell::new(ObjectSlot {
initialized: true,
shared: new_shared_value_state(
ObjectValue::Reserved,
ValueIdentity {
qpdf_obj_gen: Some(qpdf_obj_gen),
active_pdf_unique_id: NonZeroU64::new(pdf_unique_id),
resolver: Some(resolver),
},
NO_PARSED_OFFSET,
),
})));
register_test_slot(&handle.0);
handle
}
/// Construct a fresh, direct reserved sentinel with no object number and
/// no document owner — the shape [`Self::shallow_copy`] needs to mirror
/// `QPDF_Reserved::copy` (`libqpdf/QPDF_Reserved.cc:14-19`), which
/// unconditionally returns `create()`: a brand-new `QPDF_Reserved`
/// instance, wrapped by `QPDFObjectHandle::shallowCopy`
/// (`libqpdf/QPDFObjectHandle.cc:2073-2079`) the same direct-handle way
/// as any other type's `copy()` result. Unlike
/// [`Self::new_reserved_for_pdf`] (the indirect, document-owned sentinel
/// [`crate::Pdf::new_reserved`] hands out), this shares no identity, no
/// object number, and no owning document with the handle it was copied
/// from.
pub(crate) fn new_reserved_direct() -> Self {
let handle = Self(Rc::new(RefCell::new(ObjectSlot {
initialized: true,
shared: new_shared_value_state(
ObjectValue::Reserved,
ValueIdentity::default(),
NO_PARSED_OFFSET,
),
})));
register_test_slot(&handle.0);
handle
}
/// Construct a canonical unresolved slot attached to a document resolver
/// but initially without active document metadata. The resolver link is
/// weak so a surviving handle cannot keep its document alive.
///
/// Its resolved direct children remain forward handles in the shared
/// value. Unit-test containment inspection derives parent paths from the
/// registered forward graph; production construction neither copies Root
/// metadata to children nor records a permanent `None` root. Until this slot is
/// promoted, it has no active identity, so [`Self::belongs_to_pdf`] is
/// false for every document. That makes this the narrower test
/// constructor, not the
/// qpdf-native shape: upstream one `QPDF*` carries both identity and the
/// resolver, while [`Self::new_indirect_for_qpdf_obj_gen_with_resolver`] is what a
/// handle vended by a `Pdf` needs.
#[cfg(test)]
pub(crate) fn new_indirect_with_resolver(
object_ref: ObjectRef,
resolver: Weak<dyn DocumentResolver>,
) -> Self {
Self::new_indirect_unresolved_with_identity(
object_ref,
NO_PARSED_OFFSET,
None,
Some(resolver),
)
}
fn new_indirect_unresolved_with_identity(
object_ref: ObjectRef,
offset: i64,
pdf_unique_id: Option<u64>,
resolver: Option<Weak<dyn DocumentResolver>>,
) -> Self {
let Some(qpdf_obj_gen) = QpdfObjGen::try_from_object_ref(object_ref).ok() else {
return Self::uninitialized();
};
Self::new_indirect_unresolved_qpdf_obj_gen_with_identity(
qpdf_obj_gen,
offset,
pdf_unique_id,
resolver,
)
}
fn new_indirect_unresolved_qpdf_obj_gen_with_identity(
object_gen: QpdfObjGen,
offset: i64,
pdf_unique_id: Option<u64>,
resolver: Option<Weak<dyn DocumentResolver>>,
) -> Self {
let _ = offset;
let handle = Self(Rc::new(RefCell::new(ObjectSlot {
initialized: true,
shared: new_shared_value_state(
ObjectValue::Unresolved,
ValueIdentity {
qpdf_obj_gen: Some(object_gen),
active_pdf_unique_id: pdf_unique_id.and_then(NonZeroU64::new),
resolver,
},
NO_PARSED_OFFSET,
),
})));
register_test_slot(&handle.0);
handle
}
fn new_direct(value: ObjectValue, parsed_offset: i64) -> Self {
Self::new_direct_with_resolver(value, parsed_offset, None)
}
fn new_direct_with_resolver(
value: ObjectValue,
parsed_offset: i64,
resolver: Option<Weak<dyn DocumentResolver>>,
) -> Self {
Self::new_direct_with_resolver_inner(
canonicalize_object_value(value),
parsed_offset,
resolver,
)
}
/// Construct the result of qpdf's `shallowCopy` without rewriting raw
/// dictionary keys. `QPDF_Name::normalizeName` preserves a key's first
/// byte, so a caller that supplied `replaceKey("Array1", ...)` must still
/// see that slashless key when the copied dictionary is later emitted.
fn new_direct_preserving_dictionary_keys(value: ObjectValue, parsed_offset: i64) -> Self {
Self::new_direct_with_resolver_inner(value, parsed_offset, None)
}
fn new_direct_with_resolver_inner(
value: ObjectValue,
parsed_offset: i64,
resolver: Option<Weak<dyn DocumentResolver>>,
) -> Self {
let handle = Self(Rc::new(RefCell::new(ObjectSlot {
initialized: true,
shared: new_shared_value_state(
value,
ValueIdentity {
resolver,
..ValueIdentity::default()
},
parsed_offset,
),
})));
register_test_slot(&handle.0);
handle
}
fn new_parsed_direct_with_resolver(
value: ObjectValue,
parsed_offset: i64,
resolver: Weak<dyn DocumentResolver>,
pdf_unique_id: Option<u64>,
) -> Self {
Self::new_parsed_direct_with_resolver_and_description(
value,
parsed_offset,
resolver,
pdf_unique_id,
None,
)
}
fn new_parsed_direct_with_resolver_and_description(
value: ObjectValue,
parsed_offset: i64,
resolver: Weak<dyn DocumentResolver>,
pdf_unique_id: Option<u64>,
description: Option<Rc<Vec<u8>>>,
) -> Self {
let is_null = matches!(&value, ObjectValue::Null);
let handle = Self(Rc::new(RefCell::new(ObjectSlot {
initialized: true,
shared: new_shared_value_state_with_description(
canonicalize_object_value(value),
ValueIdentity {
active_pdf_unique_id: (!is_null)
.then_some(pdf_unique_id)
.flatten()
.and_then(NonZeroU64::new),
resolver: Some(resolver),
..ValueIdentity::default()
},
parsed_offset,
description.map(ObjectDescription::Template),
),
})));
register_test_slot(&handle.0);
handle
}
fn state_children(state: &ObjectValue) -> Vec<ObjectHandle> {
#[cfg(test)]
STATE_CHILDREN_VECTOR_CALLS.with(|calls| calls.set(calls.get() + 1));
Self::direct_children(state)
}
/// Replace the shared payload. Forward children remain owned by the
/// shared value itself; no reverse owner list is needed to synchronize
/// aliases.
fn replace_shared_state(&self, new_state: ObjectValue) -> ObjectValue {
let shared = self.0.borrow().shared.clone();
{
let mut shared = shared.borrow_mut();
std::mem::replace(&mut shared.value, new_state)
}
}
/// Swap the value allocations of two distinct indirect object slots while
/// retaining each slot's object identity.
///
/// qpdf's `QPDF::swapObjects` resolves both cache entries and calls
/// `QPDFObject::swapWith` (`libqpdf/QPDF.cc:2279-2289`). `swapWith`
/// exchanges the `QPDFValue` pointers and then restores each value's
/// object generation, so aliases of the first object continue to observe
/// the first object number while seeing the second object's value. In
/// flpdf the shared value identity moves with the payload; only its
/// object generation is restored. The owning document follows the value,
/// including when another document has re-promoted one of these objects.
/// The QObject slots retain their identity while the shared value and its
/// forward children move together.
pub(crate) fn swap_value_state_with(&self, other: &Self) {
if Rc::ptr_eq(&self.0, &other.0) {
return;
}
{
let left = self.0.borrow();
let right = other.0.borrow();
let left_shared = left.shared.clone();
let right_shared = right.shared.clone();
if Rc::ptr_eq(&left_shared, &right_shared) {
return;
}
}
let left_object_gen = self.qpdf_obj_gen();
let right_object_gen = other.qpdf_obj_gen();
{
let mut left = self.0.borrow_mut();
let mut right = other.0.borrow_mut();
std::mem::swap(&mut left.shared, &mut right.shared);
}
{
let shared = self.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
shared.identity.qpdf_obj_gen = left_object_gen;
}
{
let shared = other.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
shared.identity.qpdf_obj_gen = right_object_gen;
}
}
/// Replace only this slot's whole-object state, leaving other slots that
/// currently share its payload untouched. qpdf's remove/disconnect
/// transitions rebind the departing `QPDFObject`; they do not mutate the
/// `QPDFValue` allocation that a replacement alias still observes.
fn replace_detached_state(&self, new_state: ObjectValue) {
let (old_shared, uniquely_owned) = {
let slot = self.0.borrow();
let uniquely_owned = Rc::strong_count(&slot.shared) == 1;
(slot.shared.clone(), uniquely_owned)
};
if uniquely_owned {
let old_value = {
let mut shared = old_shared.borrow_mut();
std::mem::replace(&mut shared.value, new_state)
};
drop(old_value);
return;
}
let (identity, parsed_offset, description) = {
let shared = old_shared.borrow();
(
shared.identity.clone(),
shared.parsed_offset,
shared.description.clone(),
)
};
#[cfg(test)]
DETACHED_STATE_REBIND_ALLOCATIONS.with(|allocations| {
allocations.set(allocations.get() + 1);
});
let new_shared = new_shared_value_state(new_state, identity, parsed_offset);
new_shared.borrow_mut().description = description;
{
let mut slot = self.0.borrow_mut();
slot.shared = new_shared;
}
}
/// Validate the source-state contract for qpdf-shaped replacement.
///
/// flpdf currently accepts only a direct handle with a resolved value at
/// this boundary. Keeping this check separate lets the resolver run it
/// before minting an absent target cache entry. qpdf's
/// `QPDF::replaceObject` rejects both an indirect and an uninitialized
/// handle with the same message
/// (`libqpdf/QPDF.cc:1986-1989`: `if (oh.isIndirect() ||
/// !oh.isInitialized())`).
pub(crate) fn validate_replacement_source(&self) -> Result<()> {
if !self.is_direct() {
return Err(crate::Error::Unsupported(
"replacement ObjectHandle must be direct".to_string(),
));
}
if !self.is_initialized() {
return Err(crate::Error::Unsupported(
"QPDF::replaceObject called with indirect object handle".to_string(),
));
}
Ok(())
}
/// Rebind this QObject slot to the source's shared QPDFValue allocation.
/// qpdf's `QPDFObject::assign` accepts the prepared value without checking
/// indirectness (`libqpdf/qpdf/QPDFObject_private.hh:117-120`). Validation
/// and setting the replacement identity belong to `QPDF::replaceObject`
/// and `updateCache`, before this assignment.
pub(crate) fn assign_value_state(&self, source: &Self) {
if self.is_same_object_as(source) {
return;
}
let source_shared = source.0.borrow().shared.clone();
self.0.borrow_mut().shared = source_shared;
}
/// Turn an indirect canonical slot into the floating null object qpdf
/// leaves behind after `removeObject`.
pub(crate) fn remove_from_document(&self) {
if !self.is_indirect() {
return;
}
self.set_end_offsets(NO_PARSED_OFFSET, NO_PARSED_OFFSET);
self.replace_detached_state(ObjectValue::Null);
let shared = self.0.borrow().shared.clone();
{
let mut shared = shared.borrow_mut();
shared.identity.qpdf_obj_gen = None;
shared.identity.active_pdf_unique_id = None;
shared.identity.resolver = None;
shared.description = None;
shared.parsed_offset = NO_PARSED_OFFSET;
}
}
/// Promote this existing uniform slot to an indirect object in place.
///
/// qpdf registers the existing `QPDFObject` in its cache, then gives that
/// same allocation its object generation and owning document
/// (`libqpdf/QPDF.cc:1835-1839,1882-1897`); it does not clone a direct
/// payload during promotion. This is the corresponding primitive here:
/// every alias keeps its `Rc` identity while this slot receives its active
/// object reference, document identity, and weak resolver.
pub(crate) fn promote_to_indirect(
&self,
object_ref: ObjectRef,
pdf_unique_id: u64,
resolver: Weak<dyn DocumentResolver>,
) -> Self {
let Some(qpdf_obj_gen) = QpdfObjGen::try_from_object_ref(object_ref).ok() else {
return Self::uninitialized();
};
#[cfg(test)]
OBJECT_REF_PROMOTION_CALLS.with(|calls| calls.set(calls.get() + 1));
let shared = self.0.borrow().shared.clone();
shared.borrow_mut().identity = ValueIdentity {
qpdf_obj_gen: Some(qpdf_obj_gen),
active_pdf_unique_id: NonZeroU64::new(pdf_unique_id),
resolver: Some(resolver),
};
self.clone()
}
/// Promote an existing slot using qpdf's raw object identity. The public
/// `ObjectRef` projection remains absent when the generation is outside
/// the parser's `N G R` range, while the canonical handle still remains
/// indirect and resolvable through the raw cache key.
pub(crate) fn promote_to_indirect_qpdf_obj_gen(
&self,
object_gen: QpdfObjGen,
pdf_unique_id: u64,
resolver: Weak<dyn DocumentResolver>,
) -> Self {
let mut identity = { self.0.borrow().shared.borrow().identity.clone() };
identity.qpdf_obj_gen = Some(object_gen);
identity.active_pdf_unique_id = NonZeroU64::new(pdf_unique_id);
identity.resolver = Some(resolver);
self.0.borrow().shared.borrow_mut().identity = identity;
self.clone()
}
/// Construct a direct handle wrapping an already-built [`ObjectValue`], at
/// the no-offset sentinel. Used by parser and bootstrap boundaries to wrap
/// an already-decoded internal value without going through one of the
/// typed public factories above.
pub(crate) fn from_value(value: ObjectValue) -> Self {
Self::new_direct(value, NO_PARSED_OFFSET)
}
/// Construct a direct value with a weak resolver context. The resolver is
/// intentionally weak so a direct value does not keep its document alive;
/// parser-created values use [`Self::from_parsed_value_with_resolver`] to
/// add qpdf's per-value document identity as well.
pub(crate) fn from_value_with_resolver(
value: ObjectValue,
resolver: Weak<dyn DocumentResolver>,
) -> Self {
Self::new_direct_with_resolver(value, NO_PARSED_OFFSET, Some(resolver))
}
/// Construct a parser-created direct value with the owning document's
/// weak resolver and identity, matching qpdf's per-value `QPDF*`
/// association (`QPDFValue.hh:60-66,149-152`). Programmatic direct values
/// deliberately use [`Self::from_value_with_resolver`] instead: qpdf does
/// not assign an owner to a newly constructed direct array merely because
/// it is inserted into an indirect dictionary.
pub(crate) fn from_parsed_value_with_resolver(
value: ObjectValue,
resolver: Weak<dyn DocumentResolver>,
) -> Self {
let pdf_unique_id = resolver
.upgrade()
.and_then(|resolver| resolver.pdf_unique_id());
Self::new_parsed_direct_with_resolver(value, NO_PARSED_OFFSET, resolver, pdf_unique_id)
}
/// Construct a parser-created direct value when the owning resolver's
/// already-cached PDF identity is available. This avoids upgrading the
/// same weak resolver and probing the new handle's null state for every
/// scalar in an object stream (`QPDFParser.cc:394-444`).
pub(crate) fn from_parsed_value_with_resolver_and_pdf_unique_id(
value: ObjectValue,
resolver: Weak<dyn DocumentResolver>,
pdf_unique_id: u64,
) -> Self {
Self::new_parsed_direct_with_resolver(
value,
NO_PARSED_OFFSET,
resolver,
Some(pdf_unique_id),
)
}
/// Construct a parser-created direct value with all qpdf parser metadata
/// installed before the handle crosses the parser boundary. This is the
/// one-shot form of `QPDFParser::addScalar`'s `setDescription` call
/// (`libqpdf/QPDFParser.cc:413-421`), used by the live resolver where the
/// description template and cached document identity are already known.
pub(crate) fn from_parsed_value_with_resolver_and_pdf_unique_id_and_description(
value: ObjectValue,
resolver: Weak<dyn DocumentResolver>,
pdf_unique_id: u64,
description: Rc<Vec<u8>>,
parsed_offset: i64,
) -> Self {
Self::new_parsed_direct_with_resolver_and_description(
value,
parsed_offset,
resolver,
Some(pdf_unique_id),
Some(description),
)
}
/// Consume a directly-constructed, exclusively-owned handle and return
/// its value and parsed offset without cloning.
///
/// Used by the canonical parser's top-level file-object handle entry point
/// (`parser::parse_qpdf_direct_object_handle_with_diagnostics`), which builds the
/// top-level value as a handle purely to reuse the same
/// offset-assignment machinery as every nested child, then immediately
/// unwraps it into the pre-existing indirect slot the resolved object
/// actually belongs to.
///
/// Returns `None` for an indirect handle, or for a direct handle whose
/// `Rc` is still shared elsewhere (refcount > 1) — the latter cannot
/// happen for a handle a caller alone constructed and never cloned.
#[allow(unsafe_code)]
pub(crate) fn into_direct_value(self) -> Option<(ObjectValue, i64)> {
if self.0.borrow().is_indirect() {
return None; // cov:ignore: unreachable per the invariant noted above
}
if Rc::strong_count(&self.0) != 1 {
return None;
}
{
let slot = self.0.borrow();
let shared = slot.shared.borrow();
if matches!(
&shared.value,
ObjectValue::Unresolved | ObjectValue::Reserved | ObjectValue::Destroyed
) {
return None;
}
}
let this = std::mem::ManuallyDrop::new(self);
// SAFETY: the preflight checks above keep this slot direct and
// exclusively owned. `ManuallyDrop` prevents the custom ObjectHandle
// destructor from observing the field after it is moved.
let slot = unsafe { std::ptr::read(&this.0) };
let slot = Rc::try_unwrap(slot).ok()?.into_inner();
let shared = Rc::try_unwrap(slot.shared).ok()?.into_inner();
Some((shared.value, shared.parsed_offset))
}
/// Legacy direct-value extraction for `object_copy`'s remaining facade
/// cache consumer. Indirect and unresolved inputs have no extractable
/// direct value. Streams privatize their dictionary while sharing the
/// immutable payload buffer; reserved values are unsupported here.
/// Canonical promotion uses [`Self::promote_to_indirect`] and never copies.
pub(crate) fn direct_value_clone(&self) -> Result<Option<ObjectValue>> {
let slot = self.0.borrow();
if slot.is_indirect() {
return Ok(None);
}
let shared = slot.shared.borrow();
Ok(Some(match &shared.value {
ObjectValue::Reserved => return Err(reserved_clone_error()),
ObjectValue::Unresolved | ObjectValue::Destroyed => return Ok(None),
ObjectValue::Stream(stream) => ObjectValue::Stream(Box::new(StreamValue {
stream_dict: shallow_copy_child(&stream.stream_dict)?,
stream_data: stream.stream_data.clone(),
stream_provider: stream.stream_provider.clone(),
filter_on_write: stream.filter_on_write,
stream_length: stream.stream_length,
stream_token_filters: StreamTokenFilterList::default(),
content_normalization_applied: false,
})),
other => other.clone(),
}))
}
/// Mark this indirect handle's value as resolved to `value`. A no-op for
/// a direct handle, which has no resolution state to update.
///
/// qpdf's null cache update carries `-1` source positions. Reset the
/// provenance before a parser can install a real offset for a parsed
/// literal null (`libqpdf/QPDF.cc:1706-1749,1843-1858`).
pub(crate) fn set_resolved(&self, value: ObjectValue) {
// Gate on carrying a qpdf identity, not on `is_indirect()`. Object
// number zero has an identity but is not an indirect reference
// (`include/qpdf/QPDFObjGen.hh:78-81`), and qpdf still settles it:
// `QPDF::resolve` ends at
// `updateCache(og, QPDF_Null::create(), -1, -1)`
// (`libqpdf/QPDF.cc:1745-1748`).
if self.0.borrow().shared.borrow().qpdf_obj_gen().is_some() {
self.0.borrow_mut().initialized = true;
let value = canonicalize_object_value(value);
let is_null = matches!(value, ObjectValue::Null);
self.replace_shared_state(value);
if is_null {
let shared = self.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
shared.parsed_offset = NO_PARSED_OFFSET;
shared.description = None;
drop(shared);
self.set_end_offsets(NO_PARSED_OFFSET, NO_PARSED_OFFSET);
}
}
}
/// Return the canonical indirect objects that contain this direct handle.
/// Indirect handles own themselves and are intentionally excluded: callers
/// that need that case already use [`Self::object_ref`].
#[cfg(test)]
pub(crate) fn containing_object_refs(&self) -> Vec<ObjectRef> {
self.containment_roots()
.into_iter()
.map(|owner| owner.object_ref)
.collect()
}
#[cfg(test)]
pub(crate) fn containing_object_refs_for_pdf(&self, pdf_unique_id: u64) -> Vec<ObjectRef> {
self.containment_roots()
.into_iter()
.filter(|owner| owner.pdf_unique_id == Some(pdf_unique_id))
.map(|owner| owner.object_ref)
.collect()
}
pub(crate) fn belongs_to_pdf(&self, pdf_unique_id: u64) -> bool {
let slot = self.0.borrow();
if slot.is_indirect() {
slot.active_pdf_unique_id() == Some(pdf_unique_id)
} else {
match slot.active_pdf_unique_id() {
Some(owner) => owner == pdf_unique_id,
None => true,
}
}
}
/// True if every indirect descendant reachable through `self`'s direct
/// value graph (stopping at each indirect boundary) belongs to
/// `pdf_unique_id`, or carries no recorded document identity at all.
///
/// Unlike qpdf's own `checkOwnership`
/// (`libqpdf/QPDFObjectHandle.cc:2355-2365`, `QPDF_Array.cc:10-26`),
/// which is a shallow, O(1) comparison of only the top-level handle's
/// own owning document, this walks the complete direct-value descendant
/// graph. It exists for resolver-side replacement validation as a
/// flpdf-specific defense against a foreign indirect object nested several
/// direct hops below a replacement value -- a shape qpdf's own shallow
/// check does not catch. [`Self::check_key_value_ownership`] (the
/// `replace_key` and array mutator ownership boundary) intentionally does
/// not call this: qpdf's real `checkOwnership` never does either.
pub(crate) fn belongs_exclusively_to_pdf(&self, pdf_unique_id: u64) -> bool {
let mut pending = vec![self.clone()];
let mut visited = BTreeSet::new();
while let Some(handle) = pending.pop() {
let identity = Rc::as_ptr(&handle.0) as usize;
if !visited.insert(identity) {
continue;
}
let (is_indirect, active_pdf_unique_id, children) = {
let slot = handle.0.borrow();
let shared = slot.shared.borrow();
(
slot.is_indirect(),
slot.active_pdf_unique_id(),
Self::state_children(&shared.value),
)
};
if is_indirect {
if active_pdf_unique_id != Some(pdf_unique_id) {
return false;
}
continue;
}
if active_pdf_unique_id.is_some_and(|owner| owner != pdf_unique_id) {
return false;
}
pending.extend(children);
}
true
}
/// Recursively remove this handle's association with its owning
/// document, without changing its value.
///
/// A resolved indirect value can hold direct-owning [`ObjectHandle`]
/// children (array/dictionary/stream-dict entries) that are themselves
/// indirect handles sharing the same canonical `Rc` identity as this
/// document's registry entries. Two objects that reference each other
/// (e.g. a `/Pages` node and a page's `/Parent`, both common in real
/// PDFs) therefore form a strong reference cycle once both are resolved,
/// which `Rc` alone never collects.
///
/// Mirrors qpdf's `QPDFObjectHandle::disconnect()`
/// (`libqpdf/QPDFObjectHandle.cc:229-237`) plus its per-value-type
/// overrides (`QPDF_Dictionary.cc:51-56`, `QPDF_Array.cc:104-113`,
/// `QPDF_Stream.cc:167-171`): walk into every direct (non-indirect) child
/// first, then clear this value's own identity. An indirect child gets
/// its own call from the top-level `object_cache` walk
/// (`ResolverHandle::disconnect_all`), so recursing into it here would be
/// redundant; skipping it also matches qpdf, whose recursion is bounded
/// by the same indirect-object check rather than a cycle detector. A
/// direct object retained by an external caller beyond its owning
/// `Pdf`'s lifetime (e.g. a resolved `/Resources` dictionary held
/// separately from its owning page) is reached this way rather than
/// through the `object_cache` walk itself. A stream additionally releases
/// its deferred data provider before its dictionary is walked, as
/// `QPDF_Stream::disconnect` does.
///
/// This method alone never converts a value to `Destroyed` --
/// [`Self::disconnect_and_destroy`] does that, and only for the
/// top-level entry `ResolverHandle::disconnect_all` calls it on, exactly
/// as qpdf's `QPDF::~QPDF()` calls `object->destroy()` only on its own
/// `obj_cache` entries, never recursively (`libqpdf/QPDF.cc:229-233`).
///
/// qpdf's own recursion has no cycle guard, because no parsed PDF can
/// produce a direct-object cycle (only this crate's public
/// `ObjectHandle` API can, e.g. two direct dictionaries built by hand
/// and pointed at each other). This method still bounds its recursion
/// with a currently-visiting stack -- the same crate-specific,
/// non-qpdf-parity guard `ForeignObjectCopier::direct_visiting` uses
/// (`object_copy.rs`) -- so that possibility can't stack-overflow a
/// `Pdf` drop.
pub(crate) fn disconnect(&self) {
// An explicit heap worklist rather than recursion, for the same reason
// `drain_owned_descendants` uses one: a direct object graph's depth is
// bounded only by what the public `ObjectHandle` API allows a caller to
// build, and this module's own `drop_tests` pin stack independence at
// `DEEP_DROP_DEPTH` (100,000). The visited set records every allocation
// reached, not just the active path, so a direct DAG — an array holding
// the same child twice is enough — is walked once per node rather than
// once per path.
// Key on the raw allocation address of `SharedValueState`, rather than
// on a handle or its outer `ObjectSlot`: the shared state contains
// interior mutability, which clippy's `mutable_key_type` rightly
// rejects as a set key. `ObjectHandle::is_same_object_as` compares
// outer `ObjectSlot` identity; this visited key instead identifies a
// shared value allocation so each shared value is processed once,
// even when multiple slots or handles refer to it.
let mut visited: BTreeSet<*const RefCell<SharedValueState>> = BTreeSet::new();
let mut pending = vec![self.clone()];
while let Some(handle) = pending.pop() {
let shared = handle.0.borrow().shared.clone();
if !visited.insert(Rc::as_ptr(&shared)) {
continue;
}
// A stream's deferred data provider retains whatever the provider
// captured -- `CopiedStreamDataProvider` holds a handle from the
// document the stream was copied out of -- so it is released
// before the stream dictionary is handed to the walk, the order
// `QPDF_Stream::disconnect` uses (`libqpdf/QPDF_Stream.cc:167-171`).
// Only the provider slot is cleared there; replacement bytes and
// the write-time filter flag stay. This mutable borrow ends before
// the walk collects children, because a direct container that
// holds itself makes `append_direct_children` re-enter this same
// shared allocation through `ObjectHandle::is_indirect`.
// Take the provider out under the borrow but drop it after the
// borrow ends: a caller's `Drop` may read the very stream it was
// installed on, and dropping it here would panic with `RefCell
// already mutably borrowed`.
let released_provider = {
let mut shared = shared.borrow_mut();
match &mut shared.value {
ObjectValue::Stream(stream) => stream.stream_provider.take(),
_ => None,
}
};
drop(released_provider);
{
let shared = shared.borrow();
Self::append_direct_children(&shared.value, &mut pending);
}
shared.borrow_mut().identity = ValueIdentity::default();
}
}
/// [`Self::disconnect`] this top-level indirect object, then replace its
/// resolved value with qpdf's post-lifetime `Destroyed` sentinel.
///
/// The sole caller is `ResolverHandle::disconnect_all`, once per
/// canonical registry entry -- the pairing qpdf's `QPDF::~QPDF()`
/// applies directly to each `obj_cache` entry: `object->disconnect();
/// if (... != ot_null) object->destroy();` (`libqpdf/QPDF.cc:229-233`).
/// Literal null values stay null; only a non-null value is replaced.
/// Resets the parsed offset to the no-offset sentinel only when the
/// value is destroyed.
pub(crate) fn disconnect_and_destroy(&self) {
self.set_end_offsets(NO_PARSED_OFFSET, NO_PARSED_OFFSET);
self.disconnect();
let should_destroy = {
let shared = self.0.borrow().shared.clone();
let should_destroy = !matches!(shared.borrow().value, ObjectValue::Null);
should_destroy
};
if should_destroy {
self.replace_detached_state(ObjectValue::Destroyed);
let shared = self.0.borrow().shared.clone();
{
let mut shared = shared.borrow_mut();
shared.description = None;
shared.parsed_offset = NO_PARSED_OFFSET;
}
}
}
/// The `Rc` strong count backing this handle's identity. Test-only:
/// lets a regression test prove a cycle-breaking fix actually frees the
/// `Rc`s involved, without exposing reference counting as production API.
#[cfg(test)]
pub(crate) fn strong_count(&self) -> usize {
Rc::strong_count(&self.0)
}
#[cfg(test)]
pub(crate) fn reset_try_dereference_call_count() {
TRY_DEREFERENCE_CALLS.with(|count| count.set(0));
}
#[cfg(test)]
pub(crate) fn try_dereference_call_count() -> usize {
TRY_DEREFERENCE_CALLS.with(Cell::get)
}
/// True if this handle's value is known without performing resolution: a
/// direct handle always is; an indirect handle is once it has left its
/// initial state, whether that landed on a real value, on a reference
/// that turned out to be missing from the source, or on a value severed
/// because its owning document was dropped.
pub fn is_resolved(&self) -> bool {
self.with_value(|value| !matches!(value, Some(ObjectValue::Unresolved)))
}
/// Resolve this handle's own canonical slot in place, mirroring
/// `QPDFObjectHandle::dereference` → `QPDFObject::resolve`.
///
/// Direct and already-terminal handles are no-ops. An unresolved handle
/// whose document has been dropped returns an error and stays unresolved.
pub(crate) fn try_dereference(&self) -> Result<()> {
#[cfg(test)]
TRY_DEREFERENCE_CALLS.with(|count| count.set(count.get() + 1));
let (object_gen, resolver) = {
let slot = self.0.borrow();
if !slot.initialized {
return Err(Error::Internal(
"attempted to dereference an uninitialized QPDFObjectHandle".to_owned(),
));
}
let shared = slot.shared.borrow();
let Some(object_gen) = shared.qpdf_obj_gen() else {
return Ok(());
};
if !matches!(&shared.value, ObjectValue::Unresolved) {
return Ok(());
}
(
object_gen,
shared.identity.resolver.as_ref().and_then(Weak::upgrade),
)
};
let Some(resolver) = resolver else {
return Err(Error::Internal(format!(
"object {} {} belongs to a dropped PDF",
object_gen.get_obj(),
object_gen.get_gen()
)));
};
resolver.resolve_qpdf_obj_gen(object_gen, self)
}
/// The document that owns this handle, qpdf's `QPDF* context`.
///
/// `QPDFValue::qpdf` is set by the description machinery
/// (`libqpdf/qpdf/QPDFValue.hh:60-83`), so upstream a direct object
/// parsed out of a file carries a context as well as an indirect one.
/// Live parser direct values and canonical indirect slots carry that
/// weak resolver here; programmatic direct handles and
/// `QPDFObjectHandle::parse`-equivalent explicit parses remain
/// contextless.
pub(crate) fn context(&self) -> Option<Rc<dyn DocumentResolver>> {
// qpdf's `setChildDescription` copies the owning QPDF onto the child
// (`libqpdf/QPDFObject_private.hh:79-91`). A missing-key null can be
// nested through several dictionary lookups, so follow the complete
// child-description chain rather than checking only its immediate
// parent. Keep a slot-identity guard because malformed programmatic
// direct values can construct reciprocal description links.
let mut current = self.0.borrow().shared.clone();
let mut seen = BTreeSet::new();
loop {
let current_id = Rc::as_ptr(¤t) as usize;
if !seen.insert(current_id) {
break;
}
let (resolver, parent) = {
let shared = current.borrow();
let resolver = shared.identity.resolver.as_ref().and_then(Weak::upgrade);
let parent = match &shared.description {
Some(ObjectDescription::Child(child)) => child.parent.upgrade(),
_ => None,
};
(resolver, parent)
};
if let Some(resolver) = resolver {
return Some(resolver);
}
let Some(parent) = parent else {
break;
};
current = parent;
}
// Containment links are ownership/traversal metadata, not qpdf object
// context. `QPDF_Dictionary::replaceKey` and `QPDF_Array::push_back`
// never call `setChildDescription` or assign the parent QPDF to a
// programmatic direct child (`QPDF_Dictionary.cc:135-146`,
// `QPDF_Array.cc:276-285`). Only the child's own resolver or an
// explicit child-description chain above can supply context.
None
}
pub(crate) fn set_description_json(
&self,
input: impl AsRef<[u8]>,
object: impl AsRef<[u8]>,
offset: i64,
) {
let shared = self.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
shared.description = Some(ObjectDescription::Json(Box::new(JsonDescription {
input: input.as_ref().to_vec(),
object: object.as_ref().to_vec(),
})));
// qpdf writes the description offset through the same set-once guard
// as any other parsed offset (`QPDFValue::setDescription` calls
// `setParsedOffset`, `libqpdf/qpdf/QPDFValue.hh:60-65,90-100`), so a
// value that already carries an operational offset (e.g. a stream's
// encoded-data start) keeps it.
if shared.parsed_offset < 0 {
shared.parsed_offset = offset;
}
}
/// Emit `message` through this handle's context, or report it as the
/// error qpdf throws when there is none.
///
/// Ports `QPDFObjectHandle::warn`
/// (`libqpdf/QPDFObjectHandle.cc:2385-2396`), whose contextless arm is
/// `throw e`. `QPDFExc` derives from `std::runtime_error`
/// (`include/qpdf/QPDFExc.hh:29`), which this crate classifies as
/// [`crate::Error::System`]. With an empty filename,
/// `QPDFExc::createWhat` (`libqpdf/QPDFExc.cc:19-49`) prefixes a non-empty
/// object description and renders a bare message only when that
/// description is empty; this port forms the same prefix before the
/// contextless error is returned.
fn warn_through_context(&self, warning: QpdfExc) -> Result<()> {
match self.context() {
Some(context) => context.warn(warning),
None => Err(Error::QpdfExc(warning)),
}
}
/// Return the rendered qpdf diagnostic description carried by this handle.
///
/// qpdf keeps the same description on the shared `QPDFValue` and consumes
/// it from `QPDFObjectHandle::typeWarning` rather than reconstructing a
/// filename/object/offset tuple (`libqpdf/QPDFValue.cc:14-61`,
/// `libqpdf/QPDFObjectHandle.cc:2168-2188`). This accessor exposes that
/// already-rendered byte string to cross-crate qpdf compatibility
/// consumers; it does not resolve the handle or create a second source
/// location model.
pub fn description(&self) -> Vec<u8> {
self.0.borrow().get_description()
}
/// Return the unrendered qpdf-style template, when this handle carries
/// one. Canonical resolver transfers must copy this representation rather
/// than the rendered [`Self::description`]: a caller's escaped literal
/// `$PO`/`$OG` would otherwise become parser-owned placeholders again on
/// the next render.
pub(crate) fn description_template(&self) -> Option<Rc<Vec<u8>>> {
let shared = self.0.borrow().shared.clone();
let description = match shared.borrow().description.as_ref() {
Some(ObjectDescription::Template(template)) => Some(Rc::clone(template)),
Some(ObjectDescription::Json(_) | ObjectDescription::Child(_)) | None => None,
};
description
}
#[cfg(test)]
fn description_template_owner(&self) -> Option<Rc<Vec<u8>>> {
self.description_template()
}
/// Attach a qpdf document and explicit description to this shared object
/// allocation, mirroring `QPDFObjectHandle::setObjectDescription`
/// (`libqpdf/QPDFObjectHandle.cc:2056-2063`) and
/// `QPDFValue::setDescription` (`libqpdf/qpdf/QPDFValue.hh:60-66`).
///
/// This operation does not resolve or clone the handle. It changes the
/// warning context seen by every alias of the same handle, just as qpdf
/// stores the document pointer and description on the shared
/// `QPDFValue`. The supplied `Pdf` must remain alive while the handle may
/// emit a warning; the weak resolver preserves that lifetime boundary.
/// `description` accepts qpdf's raw `std::string` bytes through
/// `AsRef<[u8]>`, so a non-UTF-8 source name is not replaced by U+FFFD.
///
/// # Errors
///
/// Returns [`Error::Internal`] if the document's canonical resolver link
/// is no longer available.
pub fn set_object_description<R: std::io::Read + std::io::Seek + 'static>(
&self,
pdf: &crate::Pdf<R>,
description: impl AsRef<[u8]>,
) -> Result<()> {
let resolver = pdf.resolver.document_resolver_weak()?;
let shared = self.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
shared.identity.resolver = Some(resolver);
shared.identity.active_pdf_unique_id = NonZeroU64::new(pdf.unique_id);
shared.description = Some(ObjectDescription::Template(Rc::new(
description.as_ref().to_vec(),
)));
Ok(())
}
#[cfg(test)]
pub(crate) fn set_description(&self, description: impl AsRef<[u8]>, offset: i64) {
self.set_shared_description(Rc::new(description.as_ref().to_vec()), offset);
}
pub(crate) fn set_shared_description(&self, template: Rc<Vec<u8>>, offset: i64) {
let shared = self.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
shared.description = Some(ObjectDescription::Template(template));
// Set-once, matching qpdf's `setParsedOffset` guard that
// `QPDFValue::setDescription` calls through
// (`libqpdf/qpdf/QPDFValue.hh:60-65,90-100`). `QPDF_Stream::setDescription`
// delegates to the same guarded setter (`QPDF_Stream.cc:299-302`), so a
// stream's already-recorded encoded-data start survives a later
// description assignment rather than being overwritten by the
// description's own offset.
if shared.parsed_offset < 0 {
shared.parsed_offset = offset;
}
}
/// Clear source-description metadata when the handle's value is replaced
/// by caller-supplied data. The replacement no longer belongs to the
/// source location that produced the old description, so the indirect
/// object fallback (`object N G`) must be used instead.
pub(crate) fn clear_description(&self) {
let shared = self.0.borrow().shared.clone();
shared.borrow_mut().description = None;
}
pub(crate) fn set_child_description(
&self,
parent: &ObjectHandle,
static_descr: impl AsRef<[u8]>,
var_descr: impl AsRef<[u8]>,
) {
// qpdf's `setChildDescription` stores a weak parent value and copies
// the parent's owning QPDF onto the child at the same time
// (`libqpdf/qpdf/QPDFValue.hh:74-83`). The parent value may be
// replaced immediately after this call, so retain the effective
// resolver on the child rather than relying on the weak description
// chain to keep reaching the old shared state. `context` completes
// its traversal before this child borrow begins.
let parent_context = parent.context();
let active_pdf_unique_id = parent_context
.as_ref()
.and_then(|context| context.pdf_unique_id())
.or_else(|| parent.owning_pdf_unique_id());
let resolver = parent_context.as_ref().map(Rc::downgrade);
let parent_shared = parent.0.borrow().shared.clone();
let shared = self.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
shared.identity.resolver = resolver;
shared.identity.active_pdf_unique_id = active_pdf_unique_id.and_then(NonZeroU64::new);
shared.description = Some(ObjectDescription::Child(Box::new(ChildDescription {
parent: Rc::downgrade(&parent_shared),
static_descr: static_descr.as_ref().to_vec(),
var_descr: var_descr.as_ref().to_vec(),
})));
}
/// Report that an accessor expecting `expected_type` ran on this handle.
///
/// Ports `QPDFObjectHandle::typeWarning`
/// (`libqpdf/QPDFObjectHandle.cc:2168-2189`). qpdf dereferences first and
/// throws `std::logic_error` when it cannot; [`Self::try_dereference`]
/// already returns [`crate::Error::Internal`], this crate's counterpart,
/// for the one state that cannot resolve.
///
/// # Errors
///
/// Returns [`crate::Error::System`] when no owning document is reachable,
/// mirroring the exception qpdf throws instead of warning.
pub(crate) fn type_warning(&self, expected_type: &str, warning: &str) -> Result<()> {
self.try_dereference()?;
let desc = self.description();
let type_name = self.type_name()?;
self.warn_through_context(QpdfExc::new(
QpdfErrorCode::Object,
b"",
desc,
0,
format!(
"operation for {expected_type} attempted on object of type {type_name}: {warning}"
)
.into_bytes(),
))
}
/// Report damage this handle noticed about itself.
///
/// Ports `QPDFObjectHandle::warnIfPossible`
/// (`libqpdf/QPDFObjectHandle.cc:2191-2201`). Its guard is
/// `dereference() && obj->getDescription(context, description)`, and that
/// second call returns `qpdf != nullptr`
/// (`libqpdf/qpdf/QPDFObject_private.hh:94-100`), so the else-branch is
/// exactly the no-context case. Unlike [`Self::type_warning`] it writes
/// the bare message to the process-global default logger's error stream
/// and returns normally rather than reporting an error.
///
/// A handle whose document has been dropped is this port's counterpart of
/// that null context, so the context is tested before resolution is
/// attempted: dereferencing first would turn the dropped document into a
/// resolution error and lose the branch. Any *other* resolution failure
/// still propagates rather than being reported as a contextless warning.
///
/// # Errors
///
/// Propagates a resolution failure from a document that is still
/// reachable, and reports a sink that refuses the message.
pub(crate) fn warn_if_possible(&self, warning: &str) -> Result<()> {
if let Some(context) = self.context() {
self.try_dereference()?;
let desc = self.description();
context.warn(QpdfExc::new(
QpdfErrorCode::DamagedPdf,
b"",
desc,
0,
warning.as_bytes(),
))
} else {
crate::QPDFLogger::default_logger().error(format!("{warning}\n"))
}
}
/// Report an object-level problem whose message qpdf passes through
/// unchanged.
///
/// Ports `QPDFObjectHandle::objectWarning`
/// (`libqpdf/QPDFObjectHandle.cc:2203-2212`). No type name is interposed,
/// and — unlike [`Self::type_warning`] — qpdf performs no dereference
/// here, because the callers that reach it have already type-checked.
///
/// # Errors
///
/// Returns [`crate::Error::System`] when no owning document is reachable,
/// mirroring the exception qpdf throws instead of warning.
pub(crate) fn object_warning(&self, warning: &str) -> Result<()> {
let desc = self.description();
self.warn_through_context(QpdfExc::new(
QpdfErrorCode::Object,
b"",
desc,
0,
warning.as_bytes(),
))
}
/// Report whether this handle resolves to the PDF null object.
///
/// An uninitialized handle returns `Ok(false)` without entering the
/// value-demanding error boundary.
///
/// qpdf correspondence: `isNull`'s `dereference() && ...` implementation
/// (`libqpdf/QPDFObjectHandle.cc:353-356`).
pub fn try_is_null(&self) -> Result<bool> {
if !self.is_initialized() {
return Ok(false);
}
self.try_dereference()?;
Ok(self.is_null())
}
/// qpdf-compatible dictionary inspection with lazy dereference.
///
/// An uninitialized handle returns `Ok(None)`, matching
/// `asDictionary`'s `dereference() ? ... : nullptr` branch
/// (`libqpdf/QPDFObjectHandle.cc:265-268`).
///
/// Ports `QPDFObjectHandle::asDictionary`, the silent internal helper the
/// dictionary accessors branch on. It raises no warning of its own; the
/// warning belongs to [`Self::try_get_key`] and [`Self::try_get_keys`],
/// which is where qpdf places it.
pub(crate) fn try_as_dictionary(
&self,
) -> Result<Option<std::collections::BTreeMap<Vec<u8>, ObjectHandle>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_dictionary())
}
/// Return the sorted qpdf-canonical keys whose values do not lazily resolve
/// to null. Each returned key is a decoded PDF name string including its
/// leading `/`, such as `/Type`; the set is sorted lexicographically.
///
/// Ports `QPDF_Dictionary::getKeys` and its `QPDFObjectHandle::getKeys`
/// delegation (`libqpdf/QPDF_Dictionary.cc:117-127`;
/// `libqpdf/QPDFObjectHandle.cc:997-1009`). The dictionary snapshot is
/// owned before child resolution, so no container borrow crosses a
/// resolver call.
///
/// A non-dictionary receiver yields an empty set after raising qpdf's
/// `typeWarning("dictionary", "treating as empty")` at `:1000`.
///
/// # Errors
///
/// Propagates resolution failures.
pub fn try_get_keys(&self) -> Result<BTreeSet<Vec<u8>>> {
self.try_dereference()?;
self.resolved_get_keys()
}
/// Return visible dictionary keys from a receiver already resolved by the
/// caller. This keeps the qpdf `getKeys` child-null filtering and warning
/// boundary while avoiding a second receiver dereference.
pub(crate) fn resolved_get_keys(&self) -> Result<BTreeSet<Vec<u8>>> {
let Some(entries) = self.as_dictionary() else {
self.type_warning("dictionary", "treating as empty")?;
return Ok(BTreeSet::new());
};
let mut result = BTreeSet::new();
for (key, child) in entries {
if !child.try_is_null()? {
result.insert(key);
}
}
Ok(result)
}
/// Return visible dictionary keys from a resolved receiver without
/// cloning the complete child-handle map. The key bytes are copied in
/// sorted order first, then each child is resolved through the canonical
/// key boundary after the container borrow has ended.
pub(crate) fn resolved_get_visible_keys(&self) -> Result<Vec<Vec<u8>>> {
let Some(keys) = self.with_value(|value| match value {
Some(ObjectValue::Dictionary(entries)) => {
Some(entries.keys().cloned().collect::<Vec<_>>())
}
_ => None,
}) else {
self.type_warning("dictionary", "treating as empty")?;
return Ok(Vec::new());
};
let mut visible = Vec::with_capacity(keys.len());
for key in keys {
if !self.resolved_get_key(&key)?.try_is_null()? {
visible.push(key);
}
}
Ok(visible)
}
/// qpdf-compatible name inspection with lazy dereference.
///
/// An uninitialized handle returns `Ok(None)`, matching
/// `asName`'s `dereference() ? ... : nullptr` branch
/// (`libqpdf/QPDFObjectHandle.cc:283-286`).
pub(crate) fn try_as_name(&self) -> Result<Option<Vec<u8>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_name())
}
/// qpdf-compatible string inspection with lazy dereference.
///
/// Ports `QPDFObjectHandle::asString`, the silent internal helper the
/// dictionary/array/integer/name siblings already have
/// ([`Self::try_as_dictionary`], [`Self::try_as_array`],
/// [`Self::try_as_integer`], [`Self::try_as_name`]) but the string family
/// was missing. Unlike `getIntValue`, qpdf's `getStringValue` does not
/// route through `asString()` — it dereferences via `isString()` and
/// reads the string value directly (`libqpdf/QPDFObjectHandle.cc:659-668`)
/// — so [`Self::try_get_string_value`] keeps its own inline dereference
/// rather than delegating here. This completes the resolving family for
/// callers currently pairing an explicit resolve with the non-resolving
/// [`Self::as_string`].
///
/// An uninitialized handle returns `Ok(None)`, matching `asString`'s
/// `dereference() ? ... : nullptr` branch
/// (`libqpdf/QPDFObjectHandle.cc:327-330`).
pub(crate) fn try_as_string(&self) -> Result<Option<Vec<u8>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_string())
}
/// True when this handle lazily resolves to the requested decoded name.
///
/// Ports `QPDFObjectHandle::isNameAndEquals`
/// (`libqpdf/QPDFObjectHandle.cc:456-459`). qpdf's canonical name string
/// includes its leading slash; the internal name representation follows
/// this crate's existing convention and stores the same decoded bytes
/// without it.
pub fn try_is_name_and_equals(&self, name: &[u8]) -> Result<bool> {
self.try_dereference()?;
Ok(self.with_value(
|value| matches!(value, Some(ObjectValue::Name(actual)) if actual.as_slice() == name),
))
}
/// True when this handle is the requested decoded name or an array with a
/// matching name item.
///
/// Ports `QPDFObjectHandle::isOrHasName` in its exact short-circuit order:
/// inspect the holder as a name first, then inspect array items one at a
/// time (`libqpdf/QPDFObjectHandle.cc:1027-1039`). Each array borrow ends
/// before the selected child is resolved.
pub fn try_is_or_has_name(&self, name: &[u8]) -> Result<bool> {
if self.try_is_name_and_equals(name)? {
return Ok(true);
}
let Some(count) = self.try_array_len()? else {
return Ok(false);
};
for index in 0..count {
if self
.try_array_item(index)?
.map(|item| item.try_is_name_and_equals(name))
.transpose()?
.unwrap_or(false)
{
return Ok(true);
}
}
Ok(false)
}
/// True when this handle lazily resolves to a dictionary whose optional
/// `/Type` and `/Subtype` names equal the requested decoded bytes.
///
/// Ports `QPDFObjectHandle::isDictionaryOfType` and its left-to-right
/// short-circuiting (`libqpdf/QPDFObjectHandle.cc:461-466`). Dictionary
/// keys use qpdf's canonical leading slash; the requested type names
/// remain decoded name bytes without it, such as
/// `CryptFilterDecodeParms`.
pub fn try_is_dictionary_of_type(&self, type_name: &[u8], subtype_name: &[u8]) -> Result<bool> {
self.try_dereference()?;
let is_dictionary =
self.with_value(|value| matches!(value, Some(ObjectValue::Dictionary(_))));
if !is_dictionary {
return Ok(false);
}
if !type_name.is_empty()
&& !self
.try_get_key(b"/Type")?
.try_is_name_and_equals(type_name)?
{
return Ok(false);
}
if !subtype_name.is_empty()
&& !self
.try_get_key(b"/Subtype")?
.try_is_name_and_equals(subtype_name)?
{
return Ok(false);
}
Ok(true)
}
/// Inspect a receiver that the caller has already resolved.
///
/// This is the private counterpart of [`Self::try_is_dictionary_of_type`]
/// for qpdf-shaped walkers that establish the receiver's resolution
/// boundary once and then perform several type/key probes. Child handles
/// still use their ordinary fallible name predicate, so their lazy
/// resolution and warning order are unchanged.
pub(crate) fn resolved_is_dictionary_of_type(
&self,
type_name: &[u8],
subtype_name: &[u8],
) -> Result<bool> {
let is_dictionary =
self.with_value(|value| matches!(value, Some(ObjectValue::Dictionary(_))));
if !is_dictionary {
return Ok(false);
}
if !type_name.is_empty()
&& !self
.resolved_get_key(b"/Type")?
.try_is_name_and_equals(type_name)?
{
return Ok(false);
}
if !subtype_name.is_empty()
&& !self
.resolved_get_key(b"/Subtype")?
.try_is_name_and_equals(subtype_name)?
{
return Ok(false);
}
Ok(true)
}
/// True when this handle lazily resolves to a stream whose own
/// dictionary's optional `/Type` and `/Subtype` names equal the
/// requested decoded bytes.
///
/// Ports `QPDFObjectHandle::isStreamOfType`
/// (`libqpdf/QPDFObjectHandle.cc:468-471`): `isStream() &&
/// getDict().isDictionaryOfType(type, subtype)`. Unlike
/// [`Self::try_is_dictionary_of_type`], which only matches a plain
/// dictionary value, this matches a stream's *nested* dictionary --
/// the shape every `/Type /ObjStm` or `/Type /XRef` object actually
/// has, since both are required to carry stream data.
pub fn try_is_stream_of_type(&self, type_name: &[u8], subtype_name: &[u8]) -> Result<bool> {
self.try_dereference()?;
let Some(stream_dict) = self.as_stream_dict() else {
return Ok(false);
};
stream_dict.try_is_dictionary_of_type(type_name, subtype_name)
}
/// qpdf-compatible array inspection with lazy dereference. Only the array
/// itself is resolved; each returned child keeps its own identity.
pub(crate) fn try_as_array(&self) -> Result<Option<Vec<ObjectHandle>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_array())
}
/// Test whether the resolved value is an integer. An uninitialized qpdf
/// handle has no value and therefore returns false without a warning.
pub fn try_is_integer(&self) -> Result<bool> {
if !self.is_initialized() {
return Ok(false);
}
self.try_dereference()?;
Ok(self.as_integer().is_some())
}
/// Test whether the resolved value is an array without snapshotting its
/// children. This mirrors qpdf's `isArray`, which dereferences and checks
/// only the value type code (`libqpdf/QPDFObjectHandle.cc:426-428`).
pub fn try_is_array(&self) -> Result<bool> {
if !self.is_initialized() {
return Ok(false);
}
self.try_dereference()?;
Ok(self.with_value(|value| matches!(value, Some(ObjectValue::Array(_)))))
}
/// Test whether the resolved value is a dictionary without snapshotting
/// its entries. This mirrors qpdf's `isDictionary`, which dereferences
/// and checks only the value type code
/// (`libqpdf/QPDFObjectHandle.cc:432-434`).
pub fn try_is_dictionary(&self) -> Result<bool> {
if !self.is_initialized() {
return Ok(false);
}
self.try_dereference()?;
Ok(self.with_value(|value| matches!(value, Some(ObjectValue::Dictionary(_)))))
}
/// Test whether the resolved value is a name.
pub fn try_is_name(&self) -> Result<bool> {
if !self.is_initialized() {
return Ok(false);
}
self.try_dereference()?;
Ok(self.as_name().is_some())
}
/// Test whether the resolved value is a string without copying its bytes.
/// This mirrors qpdf's `isString`, which dereferences and checks only the
/// value type code (`libqpdf/QPDFObjectHandle.cc:327-330,408-410`).
pub fn try_is_string(&self) -> Result<bool> {
if !self.is_initialized() {
return Ok(false);
}
self.try_dereference()?;
Ok(self.with_value(|value| matches!(value, Some(ObjectValue::String(_)))))
}
/// Test whether the resolved value is a scalar in qpdf's sense: boolean,
/// integer, name, null, real, or string
/// (`libqpdf/QPDFObjectHandle.cc:449-453`).
pub fn try_is_scalar(&self) -> Result<bool> {
if !self.is_initialized() {
return Ok(false);
}
is_scalar(self)
}
/// Test whether the resolved value is an integer or real number.
pub fn try_is_number(&self) -> Result<bool> {
if !self.is_initialized() {
return Ok(false);
}
self.try_dereference()?;
Ok(self.as_integer().is_some() || self.as_real().is_some())
}
/// Create a cursor view over this array after resolving the receiver.
pub fn try_array_items(&self) -> Result<ArrayItems> {
self.try_dereference()?;
Ok(ArrayItems {
array: self.clone(),
})
}
/// Create a cursor view over this dictionary after resolving the
/// receiver.
pub fn try_dict_items(&self) -> Result<DictItems> {
self.try_dereference()?;
let mut keys = Vec::new();
if let Some(entries) = self.as_dictionary() {
for (key, value) in entries {
if !value.try_is_null()? {
keys.push(key);
}
}
}
Ok(DictItems {
dictionary: self.clone(),
keys: Rc::new(keys),
})
}
/// Copy the next live dictionary key into a reusable cursor buffer and
/// return its child handle.
///
/// JSON emission follows qpdf's `QPDF_Dictionary::writeJSON` loop over the
/// live `std::map` (`libqpdf/QPDF_Dictionary.cc:72-95`). Rust must release
/// the `RefCell` borrow before resolving a child because a direct child can
/// share the same canonical allocation. The caller supplies the previous
/// key as an exclusive lower bound and reuses `key_buffer`, so this copies
/// only the current key bytes and does not allocate a complete dictionary
/// snapshot or a new key allocation for every entry.
fn next_dictionary_entry_for_live_write(
&self,
after: Option<&[u8]>,
key_buffer: &mut LiveDictionaryKeyBuffer,
) -> Option<ObjectHandle> {
use std::ops::Bound::{Excluded, Unbounded};
self.with_value(|value| {
let Some(ObjectValue::Dictionary(entries)) = value else {
return None;
};
let next = match after {
Some(after) => entries
.range::<[u8], _>((Excluded(after), Unbounded))
.next(),
None => entries.iter().next(),
}?;
key_buffer.replace(next.0);
Some(next.1.clone())
})
}
/// Copy the next live dictionary key into a reusable cursor buffer and
/// return its child handle for writer-owned traversal.
///
/// The writer must release the parent value borrow before resolving the
/// returned child because a direct child may share the same canonical
/// allocation. Only the current key and child handle cross the borrow
/// boundary; the complete dictionary is never cloned.
pub(crate) fn next_dictionary_entry_for_live_walk(
&self,
after: Option<&[u8]>,
key_buffer: &mut LiveDictionaryKeyBuffer,
) -> Option<ObjectHandle> {
use std::ops::Bound::{Excluded, Unbounded};
self.with_value(|value| {
let Some(ObjectValue::Dictionary(entries)) = value else {
return None;
};
let next = match after {
Some(after) => entries
.range::<[u8], _>((Excluded(after), Unbounded))
.next(),
None => entries.iter().next(),
}?;
key_buffer.replace(next.0);
Some(next.1.clone())
})
}
/// Return qpdf's warning-free `getValueAsBool` result.
///
/// The receiver is resolved before the silent type check, while an
/// uninitialized or wrong-type handle returns `None` without a warning
/// (`include/qpdf/QPDFObjectHandle.hh:601-606`;
/// `libqpdf/QPDFObjectHandle.cc:484-498`).
pub fn try_get_value_as_bool(&self) -> Result<Option<bool>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_boolean())
}
/// Return qpdf's warning-free `getValueAsInt(long long&)` result.
///
/// `None` represents qpdf's false return for a wrong type; it is not a
/// zero fallback and does not emit a type warning
/// (`libqpdf/QPDFObjectHandle.cc:516-524`).
pub fn try_get_value_as_int(&self) -> Result<Option<i64>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_integer())
}
/// Return qpdf's `getValueAsInt(int&)` result, including its saturation
/// warning for values outside the i32 range
/// (`libqpdf/QPDFObjectHandle.cc:535-553`).
pub fn try_get_value_as_int_as_int(&self) -> Result<Option<i32>> {
let Some(value) = self.try_get_value_as_int()? else {
return Ok(None);
};
if value < i64::from(i32::MIN) {
self.warn_if_possible("requested value of integer is too small; returning INT_MIN")?;
Ok(Some(i32::MIN))
} else if value > i64::from(i32::MAX) {
self.warn_if_possible("requested value of integer is too big; returning INT_MAX")?;
Ok(Some(i32::MAX))
} else {
Ok(Some(value as i32))
}
}
/// Return qpdf's warning-free `getValueAsUInt(unsigned long long&)`
/// result. Negative integers use qpdf's zero conversion and warning
/// (`libqpdf/QPDFObjectHandle.cc:563-577`).
pub fn try_get_value_as_uint(&self) -> Result<Option<u64>> {
let Some(value) = self.try_get_value_as_int()? else {
return Ok(None);
};
if value < 0 {
self.warn_if_possible("unsigned value request for negative number; returning 0")?;
Ok(Some(0))
} else {
Ok(Some(value as u64))
}
}
/// Return qpdf's `getValueAsUInt(unsigned int&)` result, including its
/// negative and upper-bound warnings
/// (`libqpdf/QPDFObjectHandle.cc:588-606`).
pub fn try_get_value_as_uint_as_uint(&self) -> Result<Option<u32>> {
let Some(value) = self.try_get_value_as_int()? else {
return Ok(None);
};
if value < 0 {
self.warn_if_possible(
"unsigned integer value request for negative number; returning 0",
)?;
Ok(Some(0))
} else if value > i64::from(u32::MAX) {
self.warn_if_possible(
"requested value of unsigned integer is too big; returning UINT_MAX",
)?;
Ok(Some(u32::MAX))
} else {
Ok(Some(value as u32))
}
}
/// Return qpdf's warning-free `getValueAsReal` source spelling
/// (`libqpdf/QPDFObjectHandle.cc:623-630`).
pub fn try_get_value_as_real(&self) -> Result<Option<Vec<u8>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.with_value(|value| match value {
Some(ObjectValue::RealLiteral { literal, .. }) => Some(literal.clone()),
Some(ObjectValue::Real(value)) => Some(value.to_string().into_bytes()),
_ => None,
}))
}
/// Return qpdf's warning-free `getValueAsNumber` result
/// (`libqpdf/QPDFObjectHandle.cc:391-399`).
pub fn try_get_value_as_number(&self) -> Result<Option<f64>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.with_value(|value| match value {
Some(ObjectValue::Integer(value)) => Some(*value as f64),
Some(ObjectValue::Real(value)) => Some(*value),
Some(ObjectValue::RealLiteral { value, .. }) => Some(*value),
_ => None,
}))
}
/// Return qpdf's canonical warning-free name string, including its
/// leading slash (`libqpdf/QPDFObjectHandle.cc:647-654`).
pub fn try_get_value_as_name(&self) -> Result<Option<Vec<u8>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_name().map(|name| {
let mut result = Vec::with_capacity(name.len() + 1);
result.push(b'/');
result.extend_from_slice(&name);
result
}))
}
/// Return qpdf's warning-free raw string bytes
/// (`libqpdf/QPDFObjectHandle.cc:671-678`).
pub fn try_get_value_as_string(&self) -> Result<Option<Vec<u8>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_string())
}
/// Return qpdf's warning-free UTF-8 string view
/// (`libqpdf/QPDFObjectHandle.cc:694-702`).
pub fn try_get_value_as_utf8(&self) -> Result<Option<Vec<u8>>> {
Ok(self.try_as_string()?.map(|value| utf8_value(&value)))
}
/// Return qpdf's warning-free operator bytes
/// (`libqpdf/QPDFObjectHandle.cc:719-726`).
pub fn try_get_value_as_operator(&self) -> Result<Option<Vec<u8>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_operator())
}
/// Return qpdf's warning-free inline-image bytes
/// (`libqpdf/QPDFObjectHandle.cc:741-748`).
pub fn try_get_value_as_inline_image(&self) -> Result<Option<Vec<u8>>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_inline_image())
}
/// Construct a four-item rectangle array owned by this canonical handle
/// layer (`libqpdf/QPDFObjectHandle.cc:1987-1991`).
pub fn new_from_rectangle(rectangle: Rectangle) -> Self {
Self::array(vec![
Self::real(rectangle.llx),
Self::real(rectangle.lly),
Self::real(rectangle.urx),
Self::real(rectangle.ury),
])
}
/// Return whether this handle is exactly a four-number array without
/// emitting type warnings (`libqpdf/QPDFObjectHandle.cc:789-799`).
pub fn try_is_rectangle(&self) -> Result<bool> {
let Some(items) = self.try_as_array()? else {
return Ok(false);
};
if items.len() != 4 {
return Ok(false);
}
for item in items {
if !item.try_is_number()? {
return Ok(false);
}
}
Ok(true)
}
/// Convert a four-number array to qpdf's normalized rectangle, returning
/// the zero rectangle for an invalid shape
/// (`libqpdf/QPDFObjectHandle.cc:801-824`).
pub fn try_get_array_as_rectangle(&self) -> Result<Rectangle> {
let Some(items) = self.try_as_array()? else {
return Ok(Rectangle::default());
};
if items.len() != 4 {
return Ok(Rectangle::default());
}
let mut values = [0.0; 4];
for (index, item) in items.into_iter().enumerate() {
let Some(value) = item.try_get_value_as_number()? else {
return Ok(Rectangle::default());
};
values[index] = value;
}
Ok(Rectangle::new(
values[0].min(values[2]),
values[1].min(values[3]),
values[0].max(values[2]),
values[1].max(values[3]),
))
}
/// Construct a six-item qpdf object-handle matrix array.
pub fn new_from_matrix(matrix: ObjectHandleMatrix) -> Self {
Self::array(vec![
Self::real(matrix.a),
Self::real(matrix.b),
Self::real(matrix.c),
Self::real(matrix.d),
Self::real(matrix.e),
Self::real(matrix.f),
])
}
/// Construct a six-item array from flpdf's standalone `QPDFMatrix`
/// equivalent. This is the second qpdf `newFromMatrix` overload; its
/// identity-default behavior belongs to [`crate::Matrix`], not to the
/// nested [`ObjectHandleMatrix`]
/// (`include/qpdf/QPDFObjectHandle.hh:254-285`).
pub fn new_from_qpdf_matrix(matrix: crate::Matrix) -> Self {
Self::array(vec![
Self::real(matrix.a),
Self::real(matrix.b),
Self::real(matrix.c),
Self::real(matrix.d),
Self::real(matrix.e),
Self::real(matrix.f),
])
}
/// Return whether this handle is exactly a six-number array without
/// emitting type warnings (`libqpdf/QPDFObjectHandle.cc:801-811`).
pub fn try_is_matrix(&self) -> Result<bool> {
let Some(items) = self.try_as_array()? else {
return Ok(false);
};
if items.len() != 6 {
return Ok(false);
}
for item in items {
if !item.try_is_number()? {
return Ok(false);
}
}
Ok(true)
}
/// Convert a six-number array to the qpdf nested matrix type, returning
/// its all-zero default for an invalid shape
/// (`libqpdf/QPDFObjectHandle.cc:826-853`).
pub fn try_get_array_as_matrix(&self) -> Result<ObjectHandleMatrix> {
let Some(items) = self.try_as_array()? else {
return Ok(ObjectHandleMatrix::default());
};
if items.len() != 6 {
return Ok(ObjectHandleMatrix::default());
}
let mut values = [0.0; 6];
for (index, item) in items.into_iter().enumerate() {
let Some(value) = item.try_get_value_as_number()? else {
return Ok(ObjectHandleMatrix::default());
};
values[index] = value;
}
Ok(ObjectHandleMatrix::new(
values[0], values[1], values[2], values[3], values[4], values[5],
))
}
/// qpdf-compatible array *length* with lazy dereference — the item count
/// without materializing the items.
///
/// `QPDFObjectHandle::getArrayNItems` is `asArray()->size()`
/// (`libqpdf/QPDFObjectHandle.cc:758-768`), and `asArray` is
/// `return dereference() ? obj->as<QPDF_Array>() : nullptr;` — a borrowed
/// `QPDF_Array*`, not a copy (`libqpdf/QPDFObjectHandle.cc:252-256`), so
/// qpdf reads the length in place. `QPDF_Stream::filterable` uses that to
/// size its `/Filter` and `/DecodeParms` loops
/// (`libqpdf/QPDF_Stream.cc:398`, `:443`, `:447`) before touching a single
/// item. [`Self::try_as_array`]
/// cannot serve that caller: it snapshots the child vector, so a length
/// that is only going to be rejected still costs a `Vec` allocation and
/// one `Rc` clone per child.
///
/// **Deliberately not qpdf's non-array answer.** `getArrayNItems` warns
/// `typeWarning("array", "treating as empty")` and returns 0 for a
/// non-array (`libqpdf/QPDFObjectHandle.cc:763-766`), so qpdf reads a
/// non-array as an empty one. This returns `None`, matching
/// [`Self::try_as_array`], and leaves the meaning of "not an array" to the
/// caller — for the canonical stream filter planning route that is the
/// "stream filter type is not name or array" error. That
/// divergence predates this accessor and is not widened by it; folding
/// qpdf's treat-as-empty in here would silently turn a rejected `/Filter`
/// into an accepted unfiltered stream.
pub(crate) fn try_array_len(&self) -> Result<Option<usize>> {
self.try_dereference()?;
Ok(self.with_value(|value| match value {
Some(ObjectValue::Array(children)) => Some(children.len()),
_ => None,
}))
}
/// Return one live child handle from a lazily resolved array.
///
/// This is the valid-index portion of `QPDFObjectHandle::getArrayItem`
/// (`libqpdf/QPDFObjectHandle.cc:770-775`). qpdf borrows its `QPDF_Array`
/// and copies one `QPDFObjectHandle`; this port briefly borrows the backing
/// `Vec` and clones one `Rc`-backed handle. The child is not resolved.
///
/// qpdf warns and returns a special null for a non-array or out-of-bounds
/// index (`:776-785`). This prerequisite's consumer only calls after both
/// arrays have equal, known lengths, so invalid-domain diagnostics remain
/// outside this method and are represented as `None` rather than guessed.
pub(crate) fn try_array_item(&self, index: usize) -> Result<Option<ObjectHandle>> {
self.try_dereference()?;
Ok(self.with_value(|value| match value {
Some(ObjectValue::Array(children)) => children.get(index).cloned(),
_ => None,
}))
}
/// Return qpdf's array length, warning and treating a non-array as empty
/// (`libqpdf/QPDFObjectHandle.cc:758-768`).
pub fn try_get_array_n_items(&self) -> Result<usize> {
self.try_dereference()?;
match self.with_value(|value| match value {
Some(ObjectValue::Array(children)) => Some(children.len()),
_ => None,
}) {
Some(length) => Ok(length),
None => {
self.type_warning("array", "treating as empty")?;
Ok(0)
}
}
}
/// Return one array item using qpdf's signed-index domain. A non-array
/// warns with the array fallback; an invalid index on an array warns at
/// the object boundary and returns a contextual null
/// (`libqpdf/QPDFObjectHandle.cc:770-785`).
pub fn try_get_array_item(&self, index: i64) -> Result<ObjectHandle> {
self.try_dereference()?;
let item = self.with_value(|value| {
let Some(ObjectValue::Array(children)) = value else {
return Err(false);
};
let Some(index) = usize::try_from(index).ok() else {
return Err(true);
};
children.get(index).cloned().ok_or(true)
});
match item {
Ok(item) => Ok(item),
Err(true) => {
self.object_warning("returning null for out of bounds array access")?;
let null = ObjectHandle::null();
null.set_child_description(self, " -> null returned from invalid array access", "");
Ok(null)
}
Err(false) => {
self.type_warning("array", "returning null")?;
let null = ObjectHandle::null();
null.set_child_description(self, " -> null returned from invalid array access", "");
Ok(null)
}
}
}
/// Return the array children, warning and treating a non-array as an
/// empty vector (`libqpdf/QPDFObjectHandle.cc:787-801`).
pub fn try_get_array_as_vector(&self) -> Result<Vec<ObjectHandle>> {
self.try_dereference()?;
match self.as_array() {
Some(items) => Ok(items),
None => {
self.type_warning("array", "treating as empty")?;
Ok(Vec::new())
}
}
}
/// qpdf-compatible integer inspection with lazy dereference.
///
/// Ports `QPDFObjectHandle::asInteger`, the silent internal helper.
/// [`Self::try_get_int_value`] is the accessor that warns. An
/// uninitialized handle returns `Ok(None)`, matching `asInteger`'s
/// `dereference() ? ... : nullptr` branch
/// (`libqpdf/QPDFObjectHandle.cc:277-280`).
pub(crate) fn try_as_integer(&self) -> Result<Option<i64>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_integer())
}
/// qpdf-compatible real inspection with lazy dereference.
///
/// Ports `QPDFObjectHandle::asReal`, the silent internal helper the
/// dictionary/array/integer/name siblings already have
/// ([`Self::try_as_dictionary`], [`Self::try_as_array`],
/// [`Self::try_as_integer`], [`Self::try_as_name`]) but the real family
/// was missing. Unlike `getIntValue`, qpdf's `getRealValue` does not
/// route through `asReal()` — it dereferences via `isReal()` and reads
/// the source-literal string directly
/// (`libqpdf/QPDFObjectHandle.cc:611-620`) — so
/// [`Self::try_get_real_value`] keeps its own inline dereference rather
/// than delegating here. This completes the resolving family for callers
/// currently pairing an explicit resolve with the non-resolving
/// [`Self::as_real`].
///
/// An uninitialized handle returns `Ok(None)`, matching `asReal`'s
/// `dereference() ? ... : nullptr` branch
/// (`libqpdf/QPDFObjectHandle.cc:301-304`).
// qpdf has no internal caller of `asReal`; keep this primitive available
// for a later caller cutover without treating it as an active route here.
#[allow(dead_code)]
pub(crate) fn try_as_real(&self) -> Result<Option<f64>> {
if !self.is_initialized() {
return Ok(None);
}
self.try_dereference()?;
Ok(self.as_real())
}
/// This handle's integer value, warning and yielding `0` for any other
/// type.
///
/// Ports `QPDFObjectHandle::getIntValue`
/// (`libqpdf/QPDFObjectHandle.cc:502-513`).
///
/// # Errors
///
/// Propagates resolution failures, and — for a receiver with no reachable
/// document — the error reported by the internal type-warning boundary
/// appears in place of the warning.
pub fn try_get_int_value(&self) -> Result<i64> {
match self.try_as_integer()? {
Some(value) => Ok(value),
None => {
self.type_warning("integer", "returning 0")?;
Ok(0)
}
}
}
/// Return qpdf's boolean value, warning and yielding `false` on any
/// other type (`libqpdf/QPDFObjectHandle.cc:474-487`).
pub fn try_get_bool_value(&self) -> Result<bool> {
self.try_dereference()?;
match self.as_boolean() {
Some(value) => Ok(value),
None => {
self.type_warning("boolean", "returning false")?;
Ok(false)
}
}
}
/// Return qpdf's source spelling for a real, warning and yielding `0.0`
/// for any other type (`libqpdf/QPDFObjectHandle.cc:542-560`).
pub fn try_get_real_value(&self) -> Result<Vec<u8>> {
self.try_dereference()?;
let value = self.with_value(|value| match value {
Some(ObjectValue::RealLiteral { literal, .. }) => Some(literal.clone()),
Some(ObjectValue::Real(value)) => Some(value.to_string().into_bytes()),
_ => None,
});
match value {
Some(value) => Ok(value),
None => {
self.type_warning("real", "returning 0.0")?;
Ok(b"0.0".to_vec())
}
}
}
/// Return qpdf's numeric value for an integer or real, warning and
/// yielding `0.0` for any other type (`libqpdf/QPDFObjectHandle.cc:371-389`).
pub fn try_get_numeric_value(&self) -> Result<f64> {
self.try_dereference()?;
let value = self.with_value(|value| match value {
Some(ObjectValue::Integer(value)) => Some(*value as f64),
Some(ObjectValue::Real(value)) => Some(*value),
Some(ObjectValue::RealLiteral { value, .. }) => Some(*value),
_ => None,
});
match value {
Some(value) => Ok(value),
None => {
self.type_warning("number", "returning 0")?;
Ok(0.0)
}
}
}
/// Return qpdf's canonical slash-prefixed name, warning and yielding
/// `/QPDFFakeName` for any other type (`libqpdf/QPDFObjectHandle.cc:542-584`).
pub fn try_get_name(&self) -> Result<Vec<u8>> {
self.try_dereference()?;
match self.as_name() {
Some(value) => {
let mut result = Vec::with_capacity(value.len() + 1);
result.push(b'/');
result.extend_from_slice(&value);
Ok(result)
}
None => {
self.type_warning("name", "returning dummy name")?;
Ok(b"/QPDFFakeName".to_vec())
}
}
}
/// Return stored string bytes, warning and yielding an empty string for
/// any other type (`libqpdf/QPDFObjectHandle.cc:587-611`).
pub fn try_get_string_value(&self) -> Result<Vec<u8>> {
self.try_dereference()?;
match self.as_string() {
Some(value) => Ok(value),
None => {
self.type_warning("string", "returning empty string")?;
Ok(Vec::new())
}
}
}
/// Return qpdf's UTF-8 string view, warning and yielding an empty string
/// for any other type (`libqpdf/QPDFObjectHandle.cc:613-640`).
pub fn try_get_utf8_value(&self) -> Result<Vec<u8>> {
match self.try_as_string()? {
Some(value) => Ok(utf8_value(&value)),
None => {
self.type_warning("string", "returning empty string")?;
Ok(Vec::new())
}
}
}
/// Return an operator's bytes, warning and yielding qpdf's fake value for
/// any other type (`libqpdf/QPDFObjectHandle.cc:642-666`).
pub fn try_get_operator_value(&self) -> Result<Vec<u8>> {
self.try_dereference()?;
match self.as_operator() {
Some(value) => Ok(value),
None => {
self.type_warning("operator", "returning fake value")?;
Ok(b"QPDFFAKE".to_vec())
}
}
}
/// Return inline-image bytes, warning and yielding an empty buffer for
/// any other type (`libqpdf/QPDFObjectHandle.cc:668-690`).
pub fn try_get_inline_image_value(&self) -> Result<Vec<u8>> {
self.try_dereference()?;
match self.as_inline_image() {
Some(value) => Ok(value),
None => {
self.type_warning("inlineimage", "returning empty data")?;
Ok(Vec::new())
}
}
}
/// [`Self::try_get_int_value`] saturated into `i32`, warning at each
/// clamp.
///
/// Ports `QPDFObjectHandle::getIntValueAsInt`
/// (`libqpdf/QPDFObjectHandle.cc:525-543`). The comparisons are strict,
/// so `i32::MIN` and `i32::MAX` themselves pass through unwarned.
///
/// # Errors
///
/// As [`Self::try_get_int_value`]. A clamp warning also goes through
/// `warn_if_possible`, which — unlike `type_warning` —
/// usually reports no error of its own; but a *reachable* document whose
/// warning sink itself fails (no default logger sink, a resolver with no
/// warn receiver) still propagates that failure here, and the saturated
/// value is not returned in that case.
pub fn try_get_int_value_as_int(&self) -> Result<i32> {
let value = self.try_get_int_value()?;
if value < i64::from(i32::MIN) {
self.warn_if_possible("requested value of integer is too small; returning INT_MIN")?;
Ok(i32::MIN)
} else if value > i64::from(i32::MAX) {
self.warn_if_possible("requested value of integer is too big; returning INT_MAX")?;
Ok(i32::MAX)
} else {
Ok(value as i32)
}
}
/// Return qpdf's unsigned-long-long integer value, warning and yielding
/// `0` for a negative integer (`libqpdf/QPDFObjectHandle.cc:556-575`).
/// Non-integer values use [`Self::try_get_int_value`]'s zero fallback,
/// so they emit only that type warning.
pub fn try_get_uint_value(&self) -> Result<u64> {
let value = self.try_get_int_value()?;
if value < 0 {
self.warn_if_possible("unsigned value request for negative number; returning 0")?;
Ok(0)
} else {
// A non-negative i64 always fits in qpdf's unsigned long long
// counterpart on the supported 64-bit targets.
Ok(value as u64)
}
}
/// Return qpdf's unsigned-int integer value, warning and saturating at
/// `0`/`u32::MAX` when the signed value is outside that range
/// (`libqpdf/QPDFObjectHandle.cc:580-604`).
/// Non-integer values use [`Self::try_get_int_value`]'s zero fallback,
/// so they emit only that type warning.
pub fn try_get_uint_value_as_uint(&self) -> Result<u32> {
let value = self.try_get_int_value()?;
if value < 0 {
let warning = "unsigned integer value request for negative number; returning 0";
self.warn_if_possible(warning)?;
Ok(0)
} else if value > i64::from(u32::MAX) {
let warning = "requested value of unsigned integer is too big; returning UINT_MAX";
self.warn_if_possible(warning)?;
Ok(u32::MAX)
} else {
Ok(value as u32)
}
}
/// Look up a dictionary key. The holder dictionary is resolved;
/// the returned child retains its own direct/indirect identity.
///
/// qpdf correspondence: `QPDFObjectHandle::getKey`
/// (`libqpdf/QPDFObjectHandle.cc:978-989`). A non-dictionary receiver
/// yields null. qpdf additionally raises
/// `typeWarning("dictionary", "returning null for attempted key
/// retrieval")` at `:984`, and gives that null the
/// `" -> null returned from getting key $VD from non-Dictionary"`
/// child description. A dictionary's missing-key null instead carries
/// the key-specific description from `QPDF_Dictionary::getKey`.
///
/// `key` must be qpdf's decoded, canonical dictionary key including its
/// leading `/` (for example, `/Type`). Lookup is exact; a slashless key is
/// not an alias and is treated as missing.
///
/// # Errors
///
/// Propagates resolution failures.
pub fn try_get_key(&self, key: &[u8]) -> Result<ObjectHandle> {
self.try_dereference()?;
self.resolved_get_key(key)
}
/// Return a dictionary child from a receiver already resolved by the
/// caller. Missing-key and non-dictionary descriptions intentionally match
/// [`Self::try_get_key`]; only the receiver's redundant resolution probe is
/// omitted.
pub(crate) fn resolved_get_key(&self, key: &[u8]) -> Result<ObjectHandle> {
let (is_dictionary, child) = self.with_value(|value| match value {
Some(ObjectValue::Dictionary(entries)) => (true, entries.get(key).cloned()),
_ => (false, None),
});
if let Some(child) = child {
Ok(child)
} else if !is_dictionary {
self.type_warning("dictionary", "returning null for attempted key retrieval")?;
let null = ObjectHandle::null();
null.set_child_description(
self,
b" -> null returned from getting key $VD from non-Dictionary",
b"",
);
Ok(null)
} else {
let null = ObjectHandle::null();
let var_descr = if key.starts_with(b"/") {
key.to_vec()
} else {
let mut var_descr = Vec::with_capacity(key.len() + 1);
var_descr.push(b'/');
var_descr.extend_from_slice(key);
var_descr
};
null.set_child_description(self, b" -> dictionary key $VD", &var_descr);
Ok(null)
}
}
/// Report whether a dictionary key is present and non-null.
///
/// `key` must be qpdf's decoded, canonical dictionary key including its
/// leading `/` (for example, `/Type`). Lookup is exact; a slashless key
/// is not an alias. A present value that resolves to null is treated as
/// absent.
///
/// qpdf correspondence: `QPDF_Dictionary::hasKey`.
pub fn try_has_key(&self, key: &[u8]) -> Result<bool> {
self.try_dereference()?;
let (is_dictionary, child) = self.with_value(|value| match value {
Some(ObjectValue::Dictionary(entries)) => (true, entries.get(key).cloned()),
_ => (false, None),
});
if !is_dictionary {
self.type_warning(
"dictionary",
"returning false for a key containment request",
)?;
return Ok(false);
}
match child {
Some(child) => Ok(!child.try_is_null()?),
None => Ok(false),
}
}
/// Return a child only when this handle is a non-null dictionary. qpdf's
/// `getKeyIfDict` short-circuits null values before invoking `getKey`, so
/// null receivers do not emit a warning (`libqpdf/QPDFObjectHandle.cc:1008-1014`).
pub fn try_get_key_if_dict(&self, key: &[u8]) -> Result<ObjectHandle> {
if self.try_is_null()? {
return Ok(ObjectHandle::null());
}
self.try_get_key(key)
}
/// Return qpdf's dictionary snapshot, warning and treating a non-dict as
/// empty (`libqpdf/QPDFObjectHandle.cc:1010-1021`).
pub fn try_get_dict_as_map(&self) -> Result<BTreeMap<Vec<u8>, ObjectHandle>> {
self.try_dereference()?;
match self.as_dictionary() {
Some(entries) => Ok(entries),
None => {
self.type_warning("dictionary", "treating as empty")?;
Ok(BTreeMap::new())
}
}
}
/// Fallible spelling of qpdf's `hasKey` accessor for callers crossing the
/// crate boundary.
pub fn try_get_has_key(&self, key: &[u8]) -> Result<bool> {
self.try_has_key(key)
}
/// Construct a direct integer value.
pub fn integer(value: i64) -> Self {
Self::new_direct(ObjectValue::Integer(value), NO_PARSED_OFFSET)
}
/// This handle's currently cached parsed offset, without resolving it
/// first. `-1` means no offset has been recorded on this slot yet --
/// including an as-yet-unresolved indirect handle, whose real object may
/// still carry a different offset once resolved. Prefer
/// [`Self::try_get_parsed_offset`], which matches
/// `QPDFObjectHandle::getParsedOffset` exactly; keep using this bare
/// accessor only where the handle is already known to be resolved (a
/// direct value, or an indirect one already dereferenced by the caller).
pub fn get_parsed_offset(&self) -> i64 {
let shared = self.0.borrow().shared.clone();
let parsed_offset = shared.borrow().parsed_offset;
parsed_offset
}
/// Return the byte offset where this handle's value was parsed,
/// resolving a lazy indirect reference first when needed.
///
/// An uninitialized handle returns `-1` without an error.
///
/// qpdf correspondence: `QPDFObjectHandle::getParsedOffset`
/// (`include/qpdf/QPDFObjectHandle.hh:419`,
/// `libqpdf/QPDFObjectHandle.cc:1874-1881`): qpdf's `dereference()`
/// resolves the handle before reading the offset it recorded when the
/// object was actually parsed, and returns `false` for an uninitialized
/// handle rather than throwing.
///
/// # Errors
/// Returns `Err` if the handle is initialized but its owning document
/// has been dropped while this reference was still unresolved.
pub fn try_get_parsed_offset(&self) -> Result<i64> {
if !self.is_initialized() {
return Ok(NO_PARSED_OFFSET);
}
self.try_dereference()?;
Ok(self.get_parsed_offset())
}
// Record `offset` as the parsed offset, but only if none has been set
// yet (matches qpdf: "set only while still negative",
// `libqpdf/qpdf/QPDFValue.hh:90-100`). The live parser wires up callers;
// this remains exposed so this module's own tests can exercise the
// set-once contract independently.
pub(crate) fn set_parsed_offset_if_unset(&self, offset: i64) {
let shared = self.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
if shared.parsed_offset < 0 {
shared.parsed_offset = offset;
}
}
fn source_extent_route(&self) -> Option<(QpdfObjGen, Rc<dyn DocumentResolver>)> {
let (object_gen, resolver) = {
let slot = self.0.borrow();
let shared = slot.shared.borrow();
(shared.qpdf_obj_gen(), shared.identity.resolver.clone())
};
let object_gen = object_gen?;
let resolver = resolver?.upgrade()?;
Some((object_gen, resolver))
}
/// Record qpdf's source extent metadata on the owning document cache
/// entry. These offsets are distinct from the value's parsed/token offset:
/// they bracket the indirect object's `endobj` token and following
/// whitespace (`libqpdf/QPDF.cc:1641-1692,1843-1858`).
pub(crate) fn set_end_offsets(&self, end_before_space: i64, end_after_space: i64) {
if let Some((object_gen, resolver)) = self.source_extent_route() {
resolver.set_source_extents(
object_gen,
SourceExtents {
end_before_space,
end_after_space,
},
);
}
}
/// Return qpdf's cached source extent metadata from the owning document
/// cache entry. Direct values and contextless handles return `(-1,-1)`.
pub(crate) fn end_offsets(&self) -> (i64, i64) {
self.source_extent_route()
.map(|(object_gen, resolver)| {
let extents = resolver.source_extents(object_gen);
(extents.end_before_space, extents.end_after_space)
})
.unwrap_or((NO_PARSED_OFFSET, NO_PARSED_OFFSET))
}
/// Construct a direct null value.
pub fn null() -> Self {
Self::new_direct(ObjectValue::Null, NO_PARSED_OFFSET)
}
/// Construct a direct boolean value.
pub fn boolean(value: bool) -> Self {
Self::new_direct(ObjectValue::Boolean(value), NO_PARSED_OFFSET)
}
/// Construct a direct real (floating-point) value.
pub fn real(value: f64) -> Self {
Self::new_direct(ObjectValue::Real(value), NO_PARSED_OFFSET)
}
/// Construct a direct name value.
pub fn name(value: Vec<u8>) -> Self {
Self::new_direct(ObjectValue::Name(value), NO_PARSED_OFFSET)
}
/// Construct a direct string value.
pub fn string(value: Vec<u8>) -> Self {
Self::new_direct(ObjectValue::String(value), NO_PARSED_OFFSET)
}
/// Construct a direct content-stream operator token value.
pub fn operator(value: Vec<u8>) -> Self {
Self::new_direct(ObjectValue::Operator(value), NO_PARSED_OFFSET)
}
/// Construct a direct raw inline-image byte payload value.
pub fn inline_image(value: Vec<u8>) -> Self {
Self::new_direct(ObjectValue::InlineImage(value), NO_PARSED_OFFSET)
}
/// Construct a direct array value. Child values are handles, so cloning
/// or re-reading this array's children never deep-copies their subtrees.
pub fn array(children: Vec<ObjectHandle>) -> Self {
Self::new_direct(ObjectValue::Array(children), NO_PARSED_OFFSET)
}
/// Construct a direct dictionary value from `entries`. Iteration order
/// is the lexicographic order of the keys, not insertion order; a repeated
/// key keeps its last value. Values
/// are handles, so cloning or re-reading this dictionary's entries never
/// deep-copies their subtrees. Each input key is normalized to qpdf's
/// decoded canonical name string, including the leading `/`.
pub fn dictionary(entries: Vec<(Vec<u8>, ObjectHandle)>) -> Self {
let entries = entries
.into_iter()
.map(|(key, value)| (canonical_dictionary_key(&key), value))
.collect();
Self::new_direct(ObjectValue::Dictionary(entries), NO_PARSED_OFFSET)
}
/// Construct a direct stream value from `dict` (a dictionary handle —
/// typically built via [`Self::dictionary`]) and `data` (the stream's
/// raw, undecoded bytes). qpdf's own model never allows a stream to be a
/// direct value (only ever a top-level indirect object,
/// `libqpdf/QPDF_Stream.cc:173-178`); this crate's own types do not
/// forbid it, matching [`Self::unparse_resolved`]'s own doc for that
/// case. Mainly useful for building a handle that is deliberately never
/// attached to a [`crate::Pdf`]'s object graph, e.g. in tests.
///
/// `data` is used as given rather than copied, the way
/// `QPDFObjectHandle::newStream(QPDF*, std::shared_ptr<Buffer>)` uses "the
/// given buffer as the stream data"
/// (`include/qpdf/QPDFObjectHandle.hh:546-558`). Handing the same buffer
/// to a second stream shares it; nothing here copies the bytes.
pub fn stream(dict: ObjectHandle, data: Rc<Vec<u8>>) -> Self {
Self::new_direct(
ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(data),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})),
NO_PARSED_OFFSET,
)
}
/// Construct a direct real value that preserves a non-canonical source
/// literal (e.g. `.4`) alongside its parsed value, mirroring
/// the parser's preserved-literal value, so that a real number written in
/// the source PDF unparses byte-identically. `literal` is expected to parse
/// back to `value` and to differ from `value`'s canonical string form.
pub fn real_literal(value: f64, literal: Vec<u8>) -> Self {
Self::new_direct(
ObjectValue::RealLiteral { value, literal },
NO_PARSED_OFFSET,
)
}
/// The value as an `f64`/literal-bytes pair if this handle's value — its
/// own if direct, or its already-resolved value if indirect — is a real
/// value with a preserved source literal, or `None` otherwise. This
/// never performs resolution itself: an indirect handle that has not
/// yet been resolved returns `None` too, the same as a resolved value
/// of a different type.
pub fn as_real_literal(&self) -> Option<(f64, Vec<u8>)> {
self.with_value(|value| match value {
Some(ObjectValue::RealLiteral { value, literal }) => Some((*value, literal.clone())),
_ => None,
})
}
/// The value as `bool` if this handle's value — its own if direct, or
/// its already-resolved value if indirect — is a boolean, or `None`
/// otherwise. Never performs resolution itself.
pub fn as_boolean(&self) -> Option<bool> {
self.with_value(|value| match value {
Some(ObjectValue::Boolean(b)) => Some(*b),
_ => None,
})
}
/// The value as `f64` if this handle's value — its own if direct, or
/// its already-resolved value if indirect — is a real number (including
/// one with a preserved non-canonical source literal), or `None`
/// otherwise. The real-or-real-literal distinction is collapsed by this
/// accessor. It never performs resolution itself.
pub fn as_real(&self) -> Option<f64> {
self.with_value(|value| match value {
Some(ObjectValue::Real(v) | ObjectValue::RealLiteral { value: v, .. }) => Some(*v),
_ => None,
})
}
/// The value as decoded PDF name bytes if this handle's value — its own
/// if direct, or its already-resolved value if indirect — is a name, or
/// `None` otherwise. Never performs resolution itself.
pub fn as_name(&self) -> Option<Vec<u8>> {
self.with_value(|value| match value {
Some(ObjectValue::Name(bytes)) => Some(bytes.clone()),
_ => None,
})
}
/// The value as string bytes if this handle's value — its own if
/// direct, or its already-resolved value if indirect — is a string, or
/// `None` otherwise. Never performs resolution itself.
pub fn as_string(&self) -> Option<Vec<u8>> {
self.with_value(|value| match value {
Some(ObjectValue::String(bytes)) => Some(bytes.clone()),
_ => None,
})
}
/// True if this handle's value is known to be null. An indirect handle
/// whose value has not yet been resolved returns `false` — this method
/// never performs resolution itself, so an unresolved handle is not
/// assumed to be null. Once resolved, this reflects the real value:
/// `true` for both a genuinely parsed `null` object and a reference that
/// qpdf resolved to its null fallback. A handle disconnected when its
/// owning document is dropped is `Destroyed`, not null.
pub fn is_null(&self) -> bool {
self.with_value(|value| matches!(value, Some(ObjectValue::Null)))
}
/// The value as `i64` if this handle's value — its own if direct, or its
/// already-resolved value if indirect — is an integer, or `None`
/// otherwise. This never performs resolution itself: an indirect handle
/// that has not yet been resolved returns `None` too, the same as a
/// resolved value of a different type.
pub fn as_integer(&self) -> Option<i64> {
self.with_value(|value| match value {
Some(ObjectValue::Integer(n)) => Some(*n),
_ => None,
})
}
/// The child handles if this handle's value — its own if direct, or its
/// already-resolved value if indirect — is an array, or `None`
/// otherwise. This never performs resolution itself: an indirect handle
/// that has not yet been resolved returns `None` too, the same as a
/// resolved value of a different type. Cloning the returned `Vec` clones
/// only the child `Rc` handles, not their subtrees.
pub fn as_array(&self) -> Option<Vec<ObjectHandle>> {
self.with_value(|value| match value {
Some(ObjectValue::Array(children)) => Some(children.clone()),
_ => None,
})
}
/// The entries if this handle's value — its own if direct, or its
/// already-resolved value if indirect — is a dictionary, or `None`
/// otherwise. This never performs resolution itself: an indirect handle
/// that has not yet been resolved returns `None` too, the same as a
/// resolved value of a different type. Cloning the returned map clones
/// only the child `Rc` handles, not their subtrees. Dictionary keys use
/// qpdf's usual decoded name spelling with a leading `/` for
/// parser-created and factory-created dictionaries. A raw key supplied to
/// [`Self::replace_key`] retains its qpdf spelling, including a
/// deliberately slashless first byte.
pub fn as_dictionary(&self) -> Option<std::collections::BTreeMap<Vec<u8>, ObjectHandle>> {
self.with_value(|value| match value {
Some(ObjectValue::Dictionary(entries)) => Some(entries.clone()),
_ => None,
})
}
/// Return qpdf's live child handle for `key`, or a contextual null for a
/// missing key/non-dictionary receiver.
///
/// This convenience method has the same successful behavior as qpdf's
/// `QPDFObjectHandle::getKey` (`libqpdf/QPDFObjectHandle.cc:978-989`). It
/// panics when lazy resolution or qpdf's type warning would return an
/// error; callers that need to propagate that error should use
/// [`Self::try_get_key`]. The successful behavior includes the
/// parent-context description on a missing-key null from
/// `QPDF_Dictionary::getKey` (`libqpdf/QPDF_Dictionary.cc:103-115`).
///
/// `key` must be qpdf's decoded, canonical dictionary key including its
/// leading `/` (for example, `/Type`); lookup is exact and slashless
/// keys are missing.
#[cfg(feature = "qtest-driver")]
#[doc(hidden)]
pub fn get_key(&self, key: &[u8]) -> ObjectHandle {
self.try_get_key(key)
.unwrap_or_else(|error| panic!("ObjectHandle::get_key failed: {error}"))
}
/// Return whether qpdf considers `key` visible in this dictionary.
///
/// This convenience method panics on lazy-resolution or type-warning
/// errors; use [`Self::try_has_key`] when the error must be propagated. A
/// present value that resolves to null is absent, matching
/// `QPDF_Dictionary::hasKey` (`libqpdf/QPDF_Dictionary.cc:97-101`) and
/// `QPDFObjectHandle::hasKey` (`libqpdf/QPDFObjectHandle.cc:966-976`).
/// `key` must be qpdf's decoded, canonical dictionary key including its
/// leading `/`; lookup is exact and slashless keys are absent.
#[cfg(feature = "qtest-driver")]
#[doc(hidden)]
pub fn has_key(&self, key: &[u8]) -> bool {
self.try_has_key(key)
.unwrap_or_else(|error| panic!("ObjectHandle::has_key failed: {error}"))
}
/// Insert or overwrite `key` in this handle's dictionary with `value`,
/// mutating the live value every other clone of this handle also
/// observes — mirrors `QPDFObjectHandle::replaceKey`
/// (`libqpdf/QPDFObjectHandle.cc:1199-1209`) and
/// `QPDF_Dictionary::replaceKey`
/// (`libqpdf/QPDF_Dictionary.cc:135-153`). The receiver is dereferenced
/// before its dictionary type is inspected, matching qpdf's
/// `asDictionary()` boundary. A non-dictionary receiver emits qpdf's
/// type warning and is otherwise ignored. Ownership is checked with
/// qpdf's own shallow `checkOwnership` comparison
/// (`libqpdf/QPDFObjectHandle.cc:2355-2365`) before insertion — only
/// `self`'s and `value`'s own owning document, never a walk into
/// `value`'s descendants — and a value indirectly owned by a different
/// document returns qpdf's `checkOwnership` logic error as
/// [`Error::Internal`]. A programmatic direct value (including a direct
/// null) is unowned for this check, while a non-null direct value parsed
/// from a file carries the parser's QPDF context. In either case,
/// containment alone never confers ownership. A direct null removes the
/// key, while an indirect null or dangling indirect reference is retained
/// as the dictionary value. Also a no-op if `value` is a direct handle
/// sharing `self`'s value state — inserting it into the dictionary would
/// otherwise create a direct cycle, which this crate's recursive walkers
/// would meet as unbounded recursion because they stop only at an
/// indirect-handle boundary. This check does not detect a multi-hop
/// reciprocal cycle built from two or more `replace_key` calls across
/// distinct direct dictionaries. Those walkers survive such a cycle
/// anyway: [`Self::shallow_copy`] and [`Self::unparse_resolved`] stop at
/// the parser's container-nesting limit and report
/// [`Error::Unsupported`] rather than recursing without end.
/// `key` must be qpdf's decoded, canonical dictionary key including its
/// leading `/`; this API does not normalize slashless input.
///
/// This mutates the live handle graph directly. If `self`'s ref has
/// already been read through canonical ObjectHandle resolution, resolution
/// keeps the same canonical handle
/// identity while this mutation changes the live value in place. A later
/// canonical resolve observes that value; it does not rebuild a separate
/// raw snapshot.
///
/// The mutation updates the shared canonical handle graph in place, so the
/// writer observes the new value through its normal live-cache traversal.
///
/// # Errors
///
/// Returns [`Error::Internal`] when the value belongs to a different
/// document than the dictionary receiver, matching qpdf's
/// `checkOwnership` failure boundary.
pub fn replace_key(&self, key: &[u8], value: ObjectHandle) -> Result<()> {
if !self.prepare_dictionary_mutation("ignoring key replacement request")? {
return Ok(());
}
self.check_key_value_ownership(&value)?;
self.replace_key_unchecked(key, value);
Ok(())
}
/// Replace `key` and return the supplied value, mirroring
/// `QPDFObjectHandle::replaceKeyAndGetNew`
/// (`libqpdf/QPDFObjectHandle.cc:1213-1217`). The ordinary replacement
/// operation owns resolution, warning, ownership, and live-identity
/// behavior; this method only returns the same handle after it completes.
pub fn replace_key_and_get_new(&self, key: &[u8], value: ObjectHandle) -> Result<ObjectHandle> {
self.replace_key(key, value.clone())?;
Ok(value)
}
/// Remove `key`, replace it with `value`, and return the old value,
/// mirroring `QPDFObjectHandle::replaceKeyAndGetOld`
/// (`libqpdf/QPDFObjectHandle.cc:1219-1225`). The removal is deliberately
/// performed before the replacement, so an ownership failure in the
/// second operation has the same partial-mutation boundary as qpdf.
pub fn replace_key_and_get_old(&self, key: &[u8], value: ObjectHandle) -> Result<ObjectHandle> {
let old = self.remove_key_and_get_old(key)?;
self.replace_key(key, value)?;
Ok(old)
}
/// Remove `key` and return its old value, or a fresh direct null when the
/// key was absent, mirroring `QPDFObjectHandle::removeKeyAndGetOld`
/// (`libqpdf/QPDFObjectHandle.cc:1240-1248`). The receiver is resolved
/// before the old dictionary value is read. A non-dictionary receiver
/// emits qpdf's `removeKey` type warning and returns a direct null when
/// warning delivery succeeds.
pub fn remove_key_and_get_old(&self, key: &[u8]) -> Result<ObjectHandle> {
self.try_dereference()?;
let old = self.with_value(|current| match current {
Some(ObjectValue::Dictionary(entries)) => entries.get(key).cloned(),
_ => None,
});
if !self.with_value(|current| matches!(current, Some(ObjectValue::Dictionary(_)))) {
self.type_warning("dictionary", "ignoring key removal request")?;
return Ok(ObjectHandle::null());
}
self.remove_key(key);
Ok(old.unwrap_or_else(ObjectHandle::null))
}
fn replace_key_unchecked(&self, key: &[u8], value: ObjectHandle) {
if value.is_direct() && value.is_null() {
self.remove_key(key);
return;
}
if self.is_direct_value_alias(&value) {
return;
}
self.with_value_mut(|v| {
if let Some(ObjectValue::Dictionary(entries)) = v {
entries.insert(key.to_vec(), value.clone());
}
});
}
/// Resolve this handle and emit qpdf's dictionary type warning when a
/// dictionary mutation is attempted on another object type. This is the
/// `asDictionary()` branch shared by `replaceKey` and its AndGet variant.
fn prepare_dictionary_mutation(&self, warning: &str) -> Result<bool> {
self.try_dereference()?;
if self.with_value(|current| matches!(current, Some(ObjectValue::Dictionary(_)))) {
return Ok(true);
}
self.type_warning("dictionary", warning)?;
Ok(false)
}
/// Set one item in the live array, porting qpdf's `setArrayItem`
/// (`libqpdf/QPDFObjectHandle.cc:871-883`). The receiver is dereferenced
/// before its array type is inspected, so an unresolved indirect holder
/// is mutated through the same canonical slot that every alias observes.
///
/// qpdf checks the index before `QPDF_Array::checkOwnership`, warns and
/// leaves the array unchanged for an invalid index, and otherwise throws
/// a logic error for a foreign or destroyed item. `Error::Internal` is the
/// crate's logic-error boundary. A contextless qpdf warning is likewise
/// returned as the existing `type_warning`/`object_warning` error.
/// For process safety, flpdf rejects a direct item whose direct-child graph
/// already reaches this array with [`Error::Internal`]. qpdf's `setAt`
/// does not detect that cycle, but qpdf's later `makeDirect` traversal does
/// reject loops with a visited set (`libqpdf/QPDFObjectHandle.cc:2091-2133`).
/// This remains public because qpdf exposes the same live mutation on
/// `QPDFObjectHandle`; external canonical consumers must not replace an
/// indirect array through its parent dictionary or copy it into a separate
/// value model.
///
/// This mutates the shared live handle graph directly, and the canonical
/// writer observes the same allocation without a separate notification.
pub fn set_array_item(&self, index: usize, value: ObjectHandle) -> Result<()> {
if !self.prepare_array_mutation("ignoring attempt to set item")? {
return Ok(());
}
let in_bounds = self.with_value(
|current| matches!(current, Some(ObjectValue::Array(items)) if index < items.len()),
);
if !in_bounds {
return self.object_warning("ignoring attempt to set out of bounds array item");
}
if self.would_create_direct_cycle(&value) {
return Err(Self::direct_cycle_error());
}
self.check_array_item_ownership(&value)?;
let _old_value = self.with_value_mut(|current| {
let Some(ObjectValue::Array(items)) = current else {
return None; // cov:ignore: prepare_array_mutation fixed the type
};
Some(std::mem::replace(&mut items[index], value.clone()))
});
Ok(())
}
/// Replace the live array contents in qpdf's `setFromVector` order
/// (`libqpdf/QPDFObjectHandle.cc:884-893`, `libqpdf/QPDF_Array.cc:220-243`).
/// The old contents are removed before the first ownership check. Items
/// are then checked and inserted one at a time, so an ownership error at
/// item `n` intentionally leaves the accepted prefix in place, matching
/// qpdf's non-transactional `resize(0)` plus `push_back` loop.
/// A direct replacement that would make the array graph cyclic returns
/// [`Error::Internal`] as the flpdf process-safety boundary; qpdf's
/// `setFromVector` itself checks ownership only.
/// The canonical writer observes this live mutation directly.
pub fn set_array_items(&self, items: Vec<ObjectHandle>) -> Result<()> {
if !self.prepare_array_mutation("ignoring attempt to replace items")? {
return Ok(());
}
if items
.iter()
.any(|item| self.would_create_direct_cycle(item))
{
return Err(Self::direct_cycle_error());
}
let expected_len = items.len();
let old_items = self.with_value_mut(|current| {
let Some(ObjectValue::Array(current_items)) = current else {
return None; // cov:ignore: prepare_array_mutation fixed the type
};
let old_items = std::mem::take(current_items);
current_items.reserve(expected_len);
Some(old_items)
});
let Some(_old_items) = old_items else {
return Ok(()); // cov:ignore: prepare_array_mutation fixed the type
};
for item in items {
self.check_array_item_ownership(&item)?;
let _ = self.with_value_mut(|current| {
let Some(ObjectValue::Array(current_items)) = current else {
return false; // cov:ignore: only this method can change the state
};
current_items.push(item);
true
});
}
Ok(())
}
/// Insert one item at an inclusive array position, porting qpdf's
/// `insertItem` (`libqpdf/QPDFObjectHandle.cc:895-907`). Position `size`
/// is the append position; larger positions warn without checking item
/// ownership or changing the array. A direct item whose descendants
/// already reach this array returns [`Error::Internal`] to keep recursive
/// live-handle walkers terminating; qpdf's `insert` does not perform this
/// cycle check.
/// The canonical writer observes this live mutation directly.
pub fn insert_array_item(&self, index: usize, value: ObjectHandle) -> Result<()> {
if !self.prepare_array_mutation("ignoring attempt to insert item")? {
return Ok(());
}
let in_bounds = self.with_value(
|current| matches!(current, Some(ObjectValue::Array(items)) if index <= items.len()),
);
if !in_bounds {
return self.object_warning("ignoring attempt to insert out of bounds array item");
}
if self.would_create_direct_cycle(&value) {
return Err(Self::direct_cycle_error());
}
self.check_array_item_ownership(&value)?;
let _ = self.with_value_mut(|current| {
let Some(ObjectValue::Array(items)) = current else {
return false; // cov:ignore: prepare_array_mutation fixed the type
};
if index == items.len() {
items.push(value);
} else {
items.insert(index, value);
}
true
});
Ok(())
}
/// Insert one item into the live array and return the same handle back.
///
/// The handle comes back whether or not the insertion happened: a
/// document-owned non-array receiver, or an index past the array's
/// length, warns and leaves the receiver untouched.
///
/// Follows the same insertion/warning/ownership path as
/// [`Self::insert_array_item`]. A direct-cycle rejection is propagated
/// as [`Error::Internal`], so no handle is returned for a mutation that
/// was not inserted.
///
/// qpdf correspondence: `insertItemAndGetNew`.
pub fn insert_array_item_and_get_new(
&self,
index: usize,
value: ObjectHandle,
) -> Result<ObjectHandle> {
self.insert_array_item(index, value.clone())?;
Ok(value)
}
/// Append one item to the live array, porting qpdf's `appendItem`
/// (`libqpdf/QPDFObjectHandle.cc:916-925`, `libqpdf/QPDF_Array.cc:300-313`).
/// A direct item whose descendants already reach this array returns
/// [`Error::Internal`] to keep recursive live-handle walkers terminating;
/// qpdf's `push_back` checks ownership but does not perform this cycle
/// check.
/// The canonical writer observes this live mutation directly.
pub fn append_array_item(&self, value: ObjectHandle) -> Result<()> {
if !self.prepare_array_mutation("ignoring attempt to append item")? {
return Ok(());
}
if self.would_create_direct_cycle(&value) {
return Err(Self::direct_cycle_error());
}
self.check_array_item_ownership(&value)?;
let _ = self.with_value_mut(|current| {
let Some(ObjectValue::Array(items)) = current else {
return false; // cov:ignore: prepare_array_mutation fixed the type
};
items.push(value);
true
});
Ok(())
}
/// Append one item to the live array and return the same handle back.
///
/// The handle comes back whether or not the append happened: a
/// document-owned non-array receiver warns and leaves the receiver
/// untouched.
///
/// Follows the same append/warning/ownership path as
/// [`Self::append_array_item`]. A direct-cycle rejection is propagated
/// as [`Error::Internal`], so no handle is returned for a mutation that
/// was not appended.
///
/// qpdf correspondence: `appendItemAndGetNew`.
pub fn append_array_item_and_get_new(&self, value: ObjectHandle) -> Result<ObjectHandle> {
self.append_array_item(value.clone())?;
Ok(value)
}
/// Erase one live array item, porting qpdf's `eraseItem`
/// (`libqpdf/QPDFObjectHandle.cc:934-946`).
/// The canonical writer observes this live mutation directly.
pub fn erase_array_item(&self, index: usize) -> Result<()> {
self.erase_array_item_and_get_old(index).map(|_| ())
}
/// Erase one live array item and return its original handle, porting
/// qpdf's `eraseItemAndGetOld` (`libqpdf/QPDFObjectHandle.cc:948-955`).
/// Invalid positions and non-array receivers return a fresh null after
/// emitting the corresponding qpdf warning when the handle has document
/// warning context. A direct/contextless handle cannot route that warning
/// and therefore returns the existing `Error::System` boundary instead.
/// The canonical writer observes this live mutation directly.
pub fn erase_array_item_and_get_old(&self, index: usize) -> Result<ObjectHandle> {
if !self.prepare_array_mutation("ignoring attempt to erase item")? {
return Ok(ObjectHandle::null());
}
let in_bounds = self.with_value(
|current| matches!(current, Some(ObjectValue::Array(items)) if index < items.len()),
);
if !in_bounds {
self.object_warning("ignoring attempt to erase out of bounds array item")?;
return Ok(ObjectHandle::null());
}
let old_value = self.with_value_mut(|current| {
let Some(ObjectValue::Array(items)) = current else {
return None; // cov:ignore: prepare_array_mutation fixed the type
};
Some(items.remove(index))
});
let Some(old_value) = old_value else {
return Ok(ObjectHandle::null()); // cov:ignore: prepare_array_mutation fixed the type
};
Ok(old_value)
}
/// Append one item to the live array through a fallible Rust boundary.
///
/// Preserves the existing canonical mutation path in
/// [`Self::append_array_item`].
pub fn try_append_array_item(&self, value: ObjectHandle) -> Result<()> {
self.append_array_item(value)
}
/// Replace the live array's items through a fallible Rust boundary.
///
/// Preserves qpdf's non-transactional prefix mutation behavior through
/// [`Self::set_array_items`].
pub fn try_set_array_items(&self, items: Vec<ObjectHandle>) -> Result<()> {
self.set_array_items(items)
}
/// Set an array item using qpdf's signed index domain. Negative and
/// oversized indexes produce an object warning on arrays; a non-array
/// receiver produces the type warning and is left unchanged.
pub fn try_set_array_item_at(&self, index: i64, value: ObjectHandle) -> Result<()> {
self.try_dereference()?;
let Some(index) = usize::try_from(index).ok() else {
if self.with_value(|current| matches!(current, Some(ObjectValue::Array(_)))) {
self.object_warning("ignoring attempt to set out of bounds array item")?;
} else {
self.type_warning("array", "ignoring attempt to set item")?;
}
return Ok(());
};
let in_bounds = self.with_value(
|current| matches!(current, Some(ObjectValue::Array(items)) if index < items.len()),
);
if !in_bounds {
if self.with_value(|current| matches!(current, Some(ObjectValue::Array(_)))) {
self.object_warning("ignoring attempt to set out of bounds array item")?;
} else {
self.type_warning("array", "ignoring attempt to set item")?;
}
return Ok(());
}
self.set_array_item(index, value)
}
/// Insert an array item using qpdf's signed index domain. The valid range
/// is inclusive of the current length.
pub fn try_insert_array_item_at(&self, index: i64, value: ObjectHandle) -> Result<()> {
self.try_dereference()?;
let Some(index) = usize::try_from(index).ok() else {
if self.with_value(|current| matches!(current, Some(ObjectValue::Array(_)))) {
self.object_warning("ignoring attempt to insert out of bounds array item")?;
} else {
self.type_warning("array", "ignoring attempt to insert item")?;
}
return Ok(());
};
let in_bounds = self.with_value(
|current| matches!(current, Some(ObjectValue::Array(items)) if index <= items.len()),
);
if !in_bounds {
if self.with_value(|current| matches!(current, Some(ObjectValue::Array(_)))) {
self.object_warning("ignoring attempt to insert out of bounds array item")?;
} else {
self.type_warning("array", "ignoring attempt to insert item")?;
}
return Ok(());
}
self.insert_array_item(index, value)
}
/// Erase an array item using qpdf's signed index domain.
pub fn try_erase_array_item_at(&self, index: i64) -> Result<()> {
self.try_dereference()?;
let Some(index) = usize::try_from(index).ok() else {
if self.with_value(|current| matches!(current, Some(ObjectValue::Array(_)))) {
self.object_warning("ignoring attempt to erase out of bounds array item")?;
} else {
self.type_warning("array", "ignoring attempt to erase item")?;
}
return Ok(());
};
let in_bounds = self.with_value(
|current| matches!(current, Some(ObjectValue::Array(items)) if index < items.len()),
);
if !in_bounds {
if self.with_value(|current| matches!(current, Some(ObjectValue::Array(_)))) {
self.object_warning("ignoring attempt to erase out of bounds array item")?;
} else {
self.type_warning("array", "ignoring attempt to erase item")?;
}
return Ok(());
}
self.erase_array_item(index)
}
/// Resolve the receiver and emit qpdf's type warning when it is not an
/// array. This is deliberately separate from `with_value_mut`: the
/// latter remains a no-hidden-I/O helper for legacy mutation paths, while
/// qpdf's public array mutators call `asArray()` and therefore resolve
/// their holder first.
fn prepare_array_mutation(&self, warning: &str) -> Result<bool> {
self.try_dereference()?;
if self.with_value(|current| matches!(current, Some(ObjectValue::Array(_)))) {
return Ok(true);
}
self.type_warning("array", warning)?;
Ok(false)
}
/// Port `QPDF_Array::checkOwnership` (`libqpdf/QPDF_Array.cc:10-26`) at
/// the Rust error boundary. As with
/// [`Self::check_key_value_ownership`], compare only the receiver's and
/// item's own active PDF identities. Containment does not assign a
/// document owner to a programmatic direct value, so no propagated
/// containment metadata can reject an array insertion; a non-null
/// parser-created direct
/// value carries its source document identity just as qpdf's parsed value
/// does.
fn check_array_item_ownership(&self, item: &ObjectHandle) -> Result<()> {
let item_is_destroyed =
item.with_value(|value| matches!(value, Some(ObjectValue::Destroyed)));
// qpdf's QPDF_Array::checkOwnership rejects an item whose
// getObjectPtr() is null -- the default-constructed
// QPDFObjectHandle() shape, distinct from an initialized handle
// whatever its current value type -- with this same message
// (`libqpdf/QPDF_Array.cc:9-24`).
if item_is_destroyed || !item.is_initialized() {
return Err(Error::Internal(
"Attempting to add an uninitialized object to a QPDF_Array.".to_owned(),
));
}
self.check_key_value_ownership(item)
}
/// Port `QPDFObjectHandle::checkOwnership` (`libqpdf/QPDFObjectHandle.cc:
/// 2355-2365`) exactly: qpdf compares only `this->getOwningQPDF()` and
/// `item.getOwningQPDF()`, two O(1) reads of each handle's *own* owning
/// document -- never a walk into either handle's descendants. A value's
/// `getOwningQPDF()` in qpdf is `nullptr` for programmatically created
/// direct values and literal nulls; file-parser-created direct values do
/// carry the parser's QPDF context (`QPDFParser.cc:394-444`). Mere
/// containment inside another document's object graph does not confer
/// ownership. This deliberately does not consult
/// [`Self::belongs_exclusively_to_pdf`]: qpdf's real `checkOwnership`
/// compares only the two handles' own active document identities and does
/// not walk direct containment edges.
fn check_key_value_ownership(&self, value: &ObjectHandle) -> Result<()> {
if let (Some(self_pdf_unique_id), Some(value_pdf_unique_id)) =
(self.owning_pdf_unique_id(), value.owning_pdf_unique_id())
{
if self_pdf_unique_id != value_pdf_unique_id {
return Err(Error::Internal(FOREIGN_OBJECT_OWNERSHIP_ERROR.to_owned()));
}
}
Ok(())
}
/// Replace an existing array item with `value`, preserving `value`'s
/// shared handle identity. Returns `false` when this handle is not an
/// array or `index` is out of bounds.
#[cfg(test)]
pub(crate) fn replace_array_item(&self, index: usize, value: ObjectHandle) -> bool {
if self.would_create_direct_cycle(&value) {
return false; // cov:ignore: exercised by replace_array_item_preserves_identity_and_rejects_invalid_slots but attributed to closure setup
}
let old_value = self.with_value_mut(|current| {
let Some(ObjectValue::Array(items)) = current else {
return None; // cov:ignore: exercised by replace_array_item_preserves_identity_and_rejects_invalid_slots but attributed to closure setup
};
let Some(item) = items.get_mut(index) else {
return None; // cov:ignore: exercised by replace_array_item_preserves_identity_and_rejects_invalid_slots but attributed to closure setup
};
Some(std::mem::replace(item, value.clone()))
});
old_value.is_some()
}
/// Replace every item in this live array while preserving the array
/// handle itself. Returns `false` for a non-array handle or when the
/// replacement would create a direct value-alias cycle.
#[cfg(test)]
pub(crate) fn replace_array_items(&self, items: Vec<ObjectHandle>) -> bool {
if items
.iter()
.any(|item| self.would_create_direct_cycle(item))
{
return false;
}
let old_items = self.with_value_mut(|current| {
let Some(ObjectValue::Array(current_items)) = current else {
return None;
};
Some(std::mem::replace(current_items, items.clone()))
});
let Some(_old_items) = old_items else {
return false;
};
true
}
/// True if `other` is a direct handle sharing this handle's value state.
/// A direct alias of an indirect container is still a direct cycle when
/// inserted into that container, while an indirect child remains a legal
/// PDF reference boundary for recursive walks.
fn is_direct_value_alias(&self, other: &Self) -> bool {
if !other.is_direct() {
return false;
}
let self_shared = self.0.borrow().shared.clone();
let other_shared = other.0.borrow().shared.clone();
Rc::ptr_eq(&self_shared, &other_shared)
}
fn direct_cycle_error() -> Error {
Error::Internal("attempted to create a direct object cycle".to_owned())
}
/// Return whether inserting `candidate` as a direct child would make a
/// direct-child path reach `self`. Indirect handles are recursion
/// boundaries in the same way they are for materialization and unparse,
/// so an indirect candidate or an indirect descendant is not traversed.
/// The visited set also makes this guard total if a pre-existing direct
/// cycle came from a dictionary path or an internal caller.
fn would_create_direct_cycle(&self, candidate: &Self) -> bool {
if !candidate.is_direct() {
return false;
}
let target_shared = self.0.borrow().shared.clone();
let target_id = Rc::as_ptr(&target_shared) as usize;
let mut pending = vec![candidate.clone()];
let mut visited = BTreeSet::new();
while let Some(handle) = pending.pop() {
let shared = handle.0.borrow().shared.clone();
let identity = Rc::as_ptr(&shared) as usize;
if identity == target_id {
return true;
}
if !visited.insert(identity) {
continue;
}
let children = Self::direct_children(&shared.borrow().value);
pending.extend(children.into_iter().filter(|child| child.is_direct()));
}
false
}
fn direct_children(value: &ObjectValue) -> Vec<ObjectHandle> {
match value {
ObjectValue::Array(children) => children.clone(),
ObjectValue::Dictionary(entries) => entries.values().cloned().collect(),
ObjectValue::Stream(stream) => vec![stream.stream_dict.clone()],
_ => Vec::new(),
}
}
fn append_direct_children(value: &ObjectValue, pending: &mut Vec<ObjectHandle>) {
match value {
ObjectValue::Array(children) => pending.extend(
children
.iter()
.filter(|child| !child.is_indirect())
.cloned(),
),
ObjectValue::Dictionary(entries) => pending.extend(
entries
.values()
.filter(|child| !child.is_indirect())
.cloned(),
),
ObjectValue::Stream(stream) if !stream.stream_dict.is_indirect() => {
pending.push(stream.stream_dict.clone());
}
_ => {}
}
}
/// Empty a final owner's direct container edges before its `ObjectHandle`
/// or `ObjectHandleIdentity` wrapper releases the slot.
///
/// qpdf's `QPDFObject`/`QPDFValue` ownership is shared, so a child may be
/// removed here only when both the slot and its payload have no other
/// strong owner. Leaving an empty container in the payload makes the
/// ordinary field drop constant-depth; the moved children are then walked
/// by [`Self::drain_owned_descendants`].
fn take_owned_direct_children(slot: &Rc<RefCell<ObjectSlot>>) -> Vec<Self> {
if Rc::strong_count(slot) != 1 {
return Vec::new();
}
let children = {
let slot_ref = slot.borrow();
if Rc::strong_count(&slot_ref.shared) != 1 {
return Vec::new();
}
let mut shared = slot_ref.shared.borrow_mut();
match &mut shared.value {
ObjectValue::Array(children) => std::mem::take(children),
ObjectValue::Dictionary(entries) => std::mem::take(entries).into_values().collect(),
ObjectValue::Stream(stream) => {
vec![std::mem::replace(
&mut stream.stream_dict,
ObjectHandle::null(),
)]
}
_ => Vec::new(),
}
};
children
}
/// Release a direct acyclic object graph with an explicit heap worklist.
///
/// This is deliberately called from both wrapper types that retain the
/// slot's `Rc`: internal identity keys can outlive the last public
/// `ObjectHandle`, and must not reintroduce recursive field destruction.
fn drain_owned_descendants(slot: &Rc<RefCell<ObjectSlot>>) {
let mut pending = Self::take_owned_direct_children(slot);
while let Some(handle) = pending.pop() {
pending.extend(Self::take_owned_direct_children(&handle.0));
}
}
#[cfg(test)]
fn containment_roots(&self) -> BTreeSet<ContainmentOwner> {
if self.is_indirect() {
return BTreeSet::new();
}
let mut roots = BTreeSet::new();
let mut visited = BTreeSet::new();
let mut pending = vec![self.clone()];
let registered = registered_test_slots();
let mut parents_by_child: BTreeMap<usize, Vec<ObjectHandle>> = BTreeMap::new();
for parent in ®istered {
let child_ids = {
let slot = parent.0.borrow();
let shared = slot.shared.borrow();
match &shared.value {
ObjectValue::Array(children) => children
.iter()
.map(|child| Rc::as_ptr(&child.0) as usize)
.collect::<Vec<_>>(),
ObjectValue::Dictionary(entries) => entries
.values()
.map(|child| Rc::as_ptr(&child.0) as usize)
.collect::<Vec<_>>(),
ObjectValue::Stream(stream) => {
vec![Rc::as_ptr(&stream.stream_dict.0) as usize]
}
_ => Vec::new(),
}
};
for child_id in child_ids {
parents_by_child
.entry(child_id)
.or_default()
.push(parent.clone());
}
}
while let Some(handle) = pending.pop() {
let identity = Rc::as_ptr(&handle.0) as usize;
if !visited.insert(identity) {
continue;
}
if let Some(parents) = parents_by_child.get(&identity) {
for parent in parents {
if let Some(object_ref) = parent.object_ref() {
roots.insert(ContainmentOwner {
pdf_unique_id: parent.owning_pdf_unique_id(),
object_ref,
});
} else {
pending.push(parent.clone());
}
}
}
}
roots
}
/// Remove `key` from this handle's dictionary if present, mutating the
/// live value every other clone of this handle also observes — mirrors
/// `QPDFObjectHandle::removeKey` (`libqpdf/QPDFObjectHandle.cc:1226-1234`).
/// A no-op if `key` is absent, this handle is not a dictionary, or the
/// indirect handle is unresolved/destroyed. `key` must be qpdf's
/// decoded, canonical dictionary key including its leading `/`; this API
/// does not normalize slashless input. Never performs resolution itself.
///
/// See [`Self::replace_key`]'s doc comment for the same canonical
/// resolution behavior.
pub fn remove_key(&self, key: &[u8]) {
let _removed = self.with_value_mut(|v| {
if let Some(ObjectValue::Dictionary(entries)) = v {
return entries.remove(key);
}
None
});
}
/// A fresh, direct handle with a value copied from `self` — mirrors
/// `QPDFObjectHandle::shallowCopy` (`libqpdf/QPDFObjectHandle.cc:2073-2079`,
/// which defers to each type's own `copy(shallow=false)` default —
/// `libqpdf/QPDF_Dictionary.cc`/`libqpdf/QPDF_Array.cc`). Despite the
/// name, this recursively copies through every *direct* array/dictionary
/// descendant (each direct child is itself shallow-copied), stopping
/// only at an *indirect* child, which keeps its existing shared
/// identity rather than being copied — "shallow" describes stopping at
/// indirect children after resolving the receiver, not a single-level-
/// only copy. A scalar value is cloned outright. Always returns a direct
/// handle regardless of whether `self` is indirect. The receiver is
/// resolved before the copy, matching qpdf's `dereference()` boundary.
/// A contextless unresolved or destroyed value still reaches the
/// corresponding copy error after that no-op resolution attempt.
///
/// A reserved handle (see [`crate::Pdf::new_reserved`]) is the one
/// exception to that resolution boundary: `QPDF_Reserved::copy(bool shallow)`
/// (`libqpdf/QPDF_Reserved.cc:14-19`) ignores its `shallow` argument and
/// unconditionally returns `create()`, a brand-new `QPDF_Reserved`
/// instance, never null and never a throw. This method mirrors that: a
/// fresh, direct,
/// independent reserved sentinel, sharing no identity with `self`.
///
/// # Errors
///
/// Returns [`Error::System`] for a stream, whether it is this handle's
/// own value or a *direct* descendant reached by the recursion.
/// `QPDF_Stream::copy` (`libqpdf/QPDF_Stream.cc:140-145`) ignores its
/// `shallow` argument and unconditionally throws
/// `std::runtime_error("stream objects cannot be cloned")`, so both
/// `shallowCopy` and `unsafeShallowCopy` refuse a stream; a direct
/// stream nested in a copied container throws from the same place,
/// since `QPDF_Dictionary::copy`/`QPDF_Array::copy` call `shallowCopy`
/// on each direct child. qpdf's own supported way to copy a stream is
/// `QPDFObjectHandle::copyStream` (`libqpdf/QPDFObjectHandle.cc:2136-2151`),
/// which mints a *new* stream object and backs it with the source's
/// buffer instead of duplicating this one in place; the buffer-sharing
/// half of that is available here through [`Self::replace_stream_data`].
pub fn shallow_copy(&self) -> Result<ObjectHandle> {
if !self.is_initialized() {
return Err(Error::Internal(
"operation attempted on uninitialized QPDFObjectHandle".to_owned(),
));
}
if self.is_reserved() {
return Ok(ObjectHandle::new_reserved_direct());
}
self.try_dereference()?;
direct_graph_walk_hub(|| {
self.with_value(|value| match value {
Some(v) => Ok(ObjectHandle::new_direct_preserving_dictionary_keys(
shallow_copy_value(v)?,
NO_PARSED_OFFSET,
)),
None => Ok(ObjectHandle::null()),
})
})
}
/// Create qpdf's writer-internal `unsafeShallowCopy` form
/// (`libqpdf/QPDFObjectHandle.cc:2082-2088`). Unlike [`Self::shallow_copy`],
/// this copies only the immediate container, retaining every child handle
/// as-is. qpdf uses this when it will remove or replace only top-level
/// dictionary keys (`libqpdf/QPDFWriter.cc:1346-1352,2009-2013`); in
/// particular, a direct child that became `QPDF_Destroyed` must survive
/// this copy so the later writer unparse reports qpdf's destroyed-object
/// error instead of failing while copying the child.
///
/// This is crate-private because it is not a general-purpose ownership or
/// value-copy API. The writer is its only consumer, and the method keeps
/// qpdf's own uninitialized, stream, unresolved, and destroyed copy errors
/// at this exact boundary.
pub(crate) fn unsafe_shallow_copy(&self) -> Result<ObjectHandle> {
if !self.is_initialized() {
return Err(Error::Internal(
"operation attempted on uninitialized QPDFObjectHandle".to_owned(),
));
}
if self.is_reserved() {
return Ok(ObjectHandle::new_reserved_direct());
}
self.try_dereference()?;
self.with_value(|value| {
Ok(ObjectHandle::new_direct_preserving_dictionary_keys(
unsafe_shallow_copy_value(value.expect("resolved ObjectHandle has a value"))?,
NO_PARSED_OFFSET,
))
})
}
/// Convert this handle to a direct copy of its reachable object graph,
/// mirroring qpdf's `QPDFObjectHandle::makeDirect`
/// (`libqpdf/QPDFObjectHandle.cc:2091-2133,2154-2157`). The receiver is
/// rebound to the new handle; aliases retained before this call continue
/// to observe the original object, just as qpdf's assignment to the
/// receiver's `shared_ptr<QPDFObject>` does.
///
/// Arrays and dictionaries are copied recursively through every indirect
/// boundary. Each occurrence is copied independently, so two references
/// that used to identify the same indirect object no longer alias in the
/// resulting direct graph. A per-call identity set detects an indirect
/// cycle while it is being traversed.
///
/// When `allow_streams` is true, stream handles are retained as-is and
/// are not converted to direct values. When it is false, encountering a
/// stream returns qpdf's exact runtime-error text.
pub fn make_direct(&mut self, allow_streams: bool) -> Result<()> {
#[allow(
clippy::mutable_key_type,
reason = "identity key compares only Rc pointer identity and retains the slot deliberately"
)]
let mut visited = std::collections::HashSet::new();
let replacement =
stacker::maybe_grow(UNPARSE_STACK_RED_ZONE, UNPARSE_STACK_GROWTH_SIZE, || {
self.make_direct_copy(&mut visited, allow_streams)
})?;
*self = replacement;
Ok(())
}
#[allow(
clippy::mutable_key_type,
reason = "identity key compares only Rc pointer identity and retains the slot deliberately"
)]
fn make_direct_copy(
&self,
visited: &mut std::collections::HashSet<ObjectHandleIdentity>,
allow_streams: bool,
) -> Result<Self> {
self.try_dereference()?;
let identity = self.identity_key();
if !visited.insert(identity.clone()) {
return Err(Error::System(
"loop detected while converting object from indirect to direct".to_owned(),
));
}
let result = self.make_direct_copy_value(visited, allow_streams);
visited.remove(&identity);
result
}
#[allow(
clippy::mutable_key_type,
reason = "identity key compares only Rc pointer identity and retains the slot deliberately"
)]
fn make_direct_copy_value(
&self,
visited: &mut std::collections::HashSet<ObjectHandleIdentity>,
allow_streams: bool,
) -> Result<Self> {
// Snapshot the value before descending. Resolving a child may re-enter
// the same document resolver, so no RefCell borrow may span the
// recursive call.
let value = self
.with_value(|value| value.cloned())
.expect("resolved ObjectHandle always exposes its value");
match value {
ObjectValue::Boolean(_)
| ObjectValue::Integer(_)
| ObjectValue::Name(_)
| ObjectValue::Null
| ObjectValue::Real(_)
| ObjectValue::RealLiteral { .. }
| ObjectValue::String(_) => Ok(Self::from_value(value)),
ObjectValue::Array(items) => {
let mut copied = Vec::with_capacity(items.len());
for item in items {
copied.push(item.make_direct_copy(visited, allow_streams)?);
}
Ok(Self::new_direct(
ObjectValue::Array(copied),
NO_PARSED_OFFSET,
))
}
ObjectValue::Dictionary(entries) => {
let mut copied = std::collections::BTreeMap::new();
for (key, item) in entries {
copied.insert(key, item.make_direct_copy(visited, allow_streams)?);
}
Ok(Self::new_direct(
ObjectValue::Dictionary(copied),
NO_PARSED_OFFSET,
))
}
ObjectValue::Stream(_) => {
if allow_streams {
Ok(self.clone())
} else {
Err(Error::System(
"attempt to make a stream into a direct object".to_owned(),
))
}
}
ObjectValue::Reserved => Err(Error::System(
"QPDFObjectHandle: attempting to make a reserved object handle direct".to_owned(),
)),
ObjectValue::Unresolved
| ObjectValue::Destroyed
| ObjectValue::Operator(_)
| ObjectValue::InlineImage(_) => Err(Error::System(
"QPDFObjectHandle::makeDirectInternal: unknown object type".to_owned(),
)),
}
}
/// Create a new stream in this handle's owning document, copying its
/// dictionary across indirect boundaries and retaining its data through
/// qpdf's buffer/provider source boundary. This is
/// `QPDFObjectHandle::copyStream` (`libqpdf/QPDFObjectHandle.cc:2136-2151`):
/// indirect dictionary entries keep their identity, while direct entries
/// are recursively `shallowCopy`-ed, and stream bytes are copied only by
/// sharing an existing buffer or registering a deferred provider.
///
/// The source must have an owning document because qpdf's `newStream` is
/// document-owned and `StreamCopier::copyStreamData` needs that document
/// for the source-dispatch lifetime contract.
pub fn copy_stream(&self) -> Result<ObjectHandle> {
let type_name = self.type_name()?;
let Some(source_dict) = self.as_stream_dict() else {
return Err(Error::System(format!(
"operation for stream attempted on object of type {}",
type_name
)));
};
let resolver = self.context().ok_or_else(|| {
Error::Internal("copyStream called on a stream with no owning PDF".to_owned())
})?;
let result = resolver.new_stream()?;
let destination_dict = result.as_stream_dict().ok_or_else(|| {
Error::Internal("copyStream created a non-stream destination".to_owned())
})?;
for (key, value) in source_dict.as_dictionary().unwrap_or_default() {
let value = if value.is_indirect() {
value
} else {
value.shallow_copy()?
};
destination_dict.replace_key_unchecked(&key, value);
}
resolver.copy_stream_data(&result, self)?;
Ok(result)
}
/// Merge `other`'s top-level entries into this handle's dictionary,
/// mirroring `QPDFObjectHandle::mergeResources`
/// (`libqpdf/QPDFObjectHandle.cc:1063-1153`; intended for merging two
/// `/Resources`- or `/DR`-shaped dictionaries, per its own header doc,
/// `include/qpdf/QPDFObjectHandle.hh:820-829`). `conflicts`, if given,
/// records `rtype -> old_key -> new_key` for some (not all — see below)
/// inner keys `other` had that collided with an existing key under the
/// same top-level `rtype`.
///
/// A no-op unless both `self` and `other` are dictionaries. For each of
/// `other`'s top-level entries `(rtype, other_val)`:
/// - if `self` has no `rtype` key yet, `other_val` is privatized via
/// [`Self::shallow_copy`] and installed via [`Self::replace_key`].
/// - if `self`'s existing `rtype` value and `other_val` are both
/// dictionaries: `self`'s value is privatized first if it is
/// indirect (`shallow_copy` + `replace_key`, mirroring
/// `replaceKeyAndGetNew`'s combined mutate-and-rebind). Then each of
/// `other_val`'s own entries is merged in: a key the (now-private)
/// sub-dictionary does not have yet is installed directly
/// (privatized first unless already indirect); a key it already has
/// is left untouched unless `conflicts` is given, in which case an
/// incoming *indirect* value whose object identity already exists
/// somewhere in the sub-dictionary (as of the first such conflict
/// this call encounters — a snapshot taken once per `rtype`, not
/// re-taken per key) is reused under its existing name (`conflicts`
/// records this rename only when that existing name differs from the
/// incoming key — no rename is recorded, and nothing is installed,
/// when they already match); anything else is installed verbatim
/// under a freshly minted unique name (`conflicts` always records
/// this one).
/// - if `self`'s existing `rtype` value and `other_val` are both
/// arrays: every scalar item in `other_val` whose
/// [`Self::unparse`] text does not already match a scalar item
/// already in `self`'s array is appended to it — a set union by
/// unparsed text, not object identity.
/// - any other existing-`rtype` shape combination (mismatched types,
/// or neither dictionary nor array) leaves that entry untouched.
///
/// # Resolution
///
/// The receiver, `other`, and each top-level resource-category handle are
/// resolved here before the non-fallible `as_dictionary`/`as_array` shape
/// accessors inspect them. This mirrors qpdf's `isDictionary`/`isArray`
/// calls, which dereference on every invocation. Dictionary key lookup
/// inside a confirmed category uses the fallible qpdf-shaped accessors and
/// propagates resolution errors. Nested type
/// inspection follows qpdf: `isScalar()` resolves
/// every array item (`QPDFObjectHandle.cc:449-452`, with the scalar
/// accessors following the same `dereference() && ...` pattern, e.g.
/// `isBool` at `:338-341`), and `getResourceNames()` resolves each
/// second-level value through `isDictionary()` (`:1156-1170,431-434`).
///
/// The uniqueness pool for a freshly minted name is
/// `this_val.getResourceNames()`'s own "second-level keys" definition
/// (`libqpdf/QPDFObjectHandle.cc:1156-1170`) applied to the *inner*
/// sub-dictionary itself, not to `self` as a whole — i.e. the keys of
/// whichever of the sub-dictionary's *own* values are themselves
/// dictionaries, not the sub-dictionary's own key set. This looks like
/// it checks the wrong level (it does not, in general, collect the
/// F1/F2-style names actually in scope), but it is qpdf's real,
/// verified behavior, not a paraphrase — port it exactly rather than
/// the more "sensible"-looking alternative of the sub-dictionary's own
/// keys.
///
/// See [`Self::replace_key`]'s doc comment for the same canonical
/// resolution behavior, since this method installs and rebinds entries
/// via `replace_key`.
///
/// # Errors
///
/// Propagates [`Self::shallow_copy`]'s stream rejection: qpdf privatizes
/// an incoming value with `shallowCopy` (`libqpdf/QPDFObjectHandle.cc:1090`,
/// `:1113`, `:1122`), which throws for a *direct* stream, so a resources
/// dictionary holding one — rather than the indirect reference a stream
/// must be in a valid PDF — fails here too. Entries merged before the
/// failing one stay installed, matching an exception unwinding out of
/// qpdf's own loop.
/// Also propagates lazy-resolution errors from nested array items and
/// second-level dictionary values inspected by the qpdf-shaped helpers.
pub fn merge_resources(
&self,
other: &ObjectHandle,
mut conflicts: Option<&mut ResourceConflicts>,
) -> Result<()> {
self.try_dereference()?;
if !self.try_is_dictionary()? {
return Ok(());
}
other.try_dereference()?;
let Some(other_entries) = other.as_dictionary() else {
return Ok(());
};
for (rtype, other_val) in other_entries {
if !self.try_has_key(&rtype)? {
other_val.try_dereference()?;
self.replace_key(&rtype, other_val.shallow_copy()?)?;
continue;
}
let mut this_val = self.try_get_key(&rtype)?;
this_val.try_dereference()?;
other_val.try_dereference()?;
if this_val.try_is_dictionary()? && other_val.try_is_dictionary()? {
if this_val.is_indirect() {
let privatized = this_val.shallow_copy()?;
self.replace_key(&rtype, privatized.clone())?;
this_val = privatized;
}
merge_resource_subdict(&this_val, &other_val, &rtype, conflicts.as_deref_mut())?;
} else if this_val.try_is_array()? && other_val.try_is_array()? {
merge_resource_array(&this_val, &other_val)?;
}
// Any other shape combination for an existing rtype: untouched,
// matching qpdf's own fallthrough (neither the dictionary nor
// the array arm matches, and there is no further branch).
}
Ok(())
}
/// Make every direct value in every dictionary-valued top-level resource
/// category indirect, mirroring `QPDFObjectHandle::makeResourcesIndirect`
/// (`libqpdf/QPDFObjectHandle.cc:1042-1060`). The category dictionaries
/// themselves are not promoted and the walk does not recurse into a
/// promoted value. qpdf registers the existing `QPDFObject` allocation
/// with `QPDF::makeIndirectObject` (`libqpdf/QPDF.cc:1882-1894`), so the
/// Rust path uses the canonical in-place promotion primitive rather than a
/// shallow or materialized clone.
///
/// `owning_pdf` is mutable because promotion updates its canonical object
/// registry. This corresponds to qpdf's `init_dr_map` call order, which
/// performs this normalization before `mergeResources`
/// (`libqpdf/QPDFAcroFormDocumentHelper.cc:775-800`).
pub fn make_resources_indirect<R: std::io::Read + std::io::Seek + 'static>(
&self,
owning_pdf: &mut crate::Pdf<R>,
) -> Result<()> {
let Some(top_entries) = self.try_as_dictionary()? else {
return Ok(());
};
for (_resource_type, category) in top_entries {
let Some(category_entries) = category.try_as_dictionary()? else {
continue;
};
for (name, value) in category_entries {
if value.is_indirect() {
continue;
}
let indirect = owning_pdf.make_indirect_from_object_handle(value)?;
category.replace_key(&name, indirect)?;
}
}
Ok(())
}
/// Return all names in the second-level dictionaries of a resource
/// dictionary.
///
/// This ports `QPDFObjectHandle::getResourceNames`
/// (`include/qpdf/QPDFObjectHandle.hh:831-835`,
/// `libqpdf/QPDFObjectHandle.cc:1156-1170`). The receiver and each
/// top-level value are resolved through the owning document before their
/// dictionary shape is inspected. The fallible `Result` preserves this
/// crate's resolver error boundary; qpdf's equivalent reports the same
/// collection for successfully resolved values.
pub fn get_resource_names(&self) -> Result<std::collections::BTreeSet<Vec<u8>>> {
try_get_resource_names(self)
}
/// Return the unique resource name qpdf would select for `prefix`.
///
/// This ports `QPDFObjectHandle::getUniqueResourceName`
/// (`libqpdf/QPDFObjectHandle.cc:1175-1192`). When `resource_names` is
/// absent, the names are collected from the second-level dictionary keys
/// exactly as the private `try_get_resource_names` helper does. `min_suffix` is left at
/// the suffix that was selected, rather than advanced past it, so callers
/// can reuse the cursor for a later insertion. The `usize`/byte-vector
/// representation is the Rust spelling of qpdf's `int`/`std::string`
/// boundary; no PDF bytes are materialized while searching.
pub fn get_unique_resource_name(
&self,
prefix: &[u8],
min_suffix: &mut usize,
resource_names: Option<&std::collections::BTreeSet<Vec<u8>>>,
) -> Result<Vec<u8>> {
let names = match resource_names {
Some(names) => names.clone(),
None => self.get_resource_names()?,
};
let max_suffix = *min_suffix + names.len();
while *min_suffix <= max_suffix {
let mut candidate = prefix.to_vec();
candidate.extend(min_suffix.to_string().into_bytes());
if !names.contains(&candidate) {
return Ok(candidate);
}
*min_suffix += 1;
}
// qpdf treats this as an internal coding error and throws
// std::logic_error (`libqpdf/QPDFObjectHandle.cc:1188-1191`); this
// maps to `Error::Internal` like every other logic_error in this
// file. The loop tests one more candidate than there are entries in
// `names`, so by pigeonhole this is unreachable for any input.
// cov:ignore-start: unreachable by the pigeonhole argument above for any input
Err(Error::Internal(
"unable to find unconflicting resource name".to_owned(),
))
// cov:ignore-end
}
/// Whether this handle is a Form XObject.
///
/// This ports `QPDFObjectHandle::isFormXObject`
/// (`libqpdf/QPDFObjectHandle.cc:2340-2343`). The stream and subtype
/// holder are resolved through the owning document before inspection;
/// programmatically constructed direct handles remain context-free.
pub fn is_form_xobject(&self) -> Result<bool> {
if self.type_code()? != 10 {
return Ok(false);
}
let Some(stream_dict) = self.as_stream_dict() else {
return Ok(false); // cov:ignore: stream values always carry a dictionary
};
stream_dict
.try_get_key(b"/Subtype")?
.try_is_name_and_equals(b"Form")
}
/// Whether this handle is an Image XObject.
///
/// This ports `QPDFObjectHandle::isImage`
/// (`libqpdf/QPDFObjectHandle.cc:2345-2352`). With
/// `exclude_imagemask` set, a boolean `/ImageMask true` excludes the
/// stream; non-boolean or missing `/ImageMask` values do not.
pub fn is_image(&self, exclude_imagemask: bool) -> Result<bool> {
if self.type_code()? != 10 {
return Ok(false);
}
let Some(stream_dict) = self.as_stream_dict() else {
return Ok(false); // cov:ignore: stream values always carry a dictionary
};
if !stream_dict
.try_get_key(b"/Subtype")?
.try_is_name_and_equals(b"Image")?
{
return Ok(false);
}
if !exclude_imagemask {
return Ok(true);
}
let image_mask = stream_dict.try_get_key(b"/ImageMask")?;
image_mask.try_dereference()?;
Ok(image_mask.as_boolean() != Some(true))
}
/// Return the page's `/Contents` as the qpdf-normalized stream list.
///
/// This ports `QPDFObjectHandle::getPageContents` and its
/// `arrayOrStreamToStreamArray` helper
/// (`libqpdf/QPDFObjectHandle.cc:1438-1493`). A missing or null `/Contents`
/// is an empty list. A single stream is returned as a one-item list. An
/// array resolves each member, keeps stream members in order, and reports
/// non-stream members at the same warning boundary as qpdf. The returned
/// handles retain their canonical identity and no stream data is decoded.
pub fn get_page_contents(&self) -> Result<Vec<ObjectHandle>> {
Ok(self.page_contents_with_description()?.0)
}
/// Add a content stream to this page, preserving qpdf's always-array
/// result and prepend/append order.
///
/// This ports `QPDFObjectHandle::addPageContents`
/// (`libqpdf/QPDFObjectHandle.cc:1495-1513`). The incoming handle is
/// checked before the existing page contents are inspected, matching
/// qpdf's `assertStream` ordering. Existing malformed content arrays use
/// the same normalization and warning boundary as [`Self::get_page_contents`].
///
/// # Errors
///
/// Returns [`Error::System`] when `new_contents` is not a stream, and
/// propagates content normalization, ownership, or replacement failures.
pub fn add_page_contents(&self, new_contents: ObjectHandle, first: bool) -> Result<()> {
if new_contents.type_code()? != 10 {
let type_name = new_contents.type_name()?;
return Err(Error::System(format!(
"operation for stream attempted on object of type {}",
type_name
)));
}
let mut content_streams = Vec::new();
if first {
content_streams.push(new_contents.clone());
}
content_streams.extend(self.get_page_contents()?);
if !first {
content_streams.push(new_contents);
}
self.replace_key(b"/Contents", ObjectHandle::array(content_streams))
}
/// Saturate `value` to the `i32` range, warning on `self` (the source of
/// the value) at each clamp.
///
/// Ports the saturating half of `QPDFObjectHandle::getIntValueAsInt`
/// (`libqpdf/QPDFObjectHandle.cc:525-543`) for a caller that has already
/// obtained an `i64` some other way than [`Self::try_get_int_value`] --
/// [`rotate_page`](Self::rotate_page)'s relative-rotation walk needs the
/// same saturate-and-warn behavior qpdf's `getValueAsInt(int&)` applies
/// to a *found* integer, without that function's unconditional warn-and-
/// default-to-0 for a non-integer receiver, which would misfire on the
/// common case of an ancestor with no `/Rotate` at all.
fn saturate_i64_to_i32_range_with_warning(&self, value: i64) -> Result<i64> {
if value < i64::from(i32::MIN) {
self.warn_if_possible("requested value of integer is too small; returning INT_MIN")?;
Ok(i64::from(i32::MIN))
} else if value > i64::from(i32::MAX) {
self.warn_if_possible("requested value of integer is too big; returning INT_MAX")?;
Ok(i64::from(i32::MAX))
} else {
Ok(value)
}
}
/// Set this page's rotation, optionally adding the nearest inherited
/// `/Rotate` value.
///
/// This ports `QPDFObjectHandle::rotatePage`
/// (`libqpdf/QPDFObjectHandle.cc:1517-1546`). Relative lookup walks
/// `/Parent` through dictionary handles, stops at the first integer
/// `/Rotate`, ignores a non-quarter-turn inherited value, and uses
/// canonical object identity to break cycles.
///
/// # Errors
///
/// Returns [`Error::System`] for a non-multiple-of-90 angle and
/// propagates lazy-resolution, warning, or dictionary replacement errors.
pub fn rotate_page(&self, angle: i32, relative: bool) -> Result<()> {
if angle % 90 != 0 {
return Err(Error::System(
"QPDF::rotatePage called with an angle that is not a multiple of 90".to_owned(),
));
}
let mut new_angle = i64::from(angle);
if relative {
let mut old_angle = 0_i64;
let mut current = self.clone();
// qpdf's visited set is keyed by canonical object identity. The
// retained Rc is intentional: it keeps pointer identity stable
// for the duration of the parent walk.
#[allow(
clippy::mutable_key_type,
reason = "identity key compares only Rc pointer identity and retains the slot deliberately"
)]
let mut visited = std::collections::HashSet::new();
while visited.insert(current.identity_key()) {
let rotate = current.try_get_key(b"/Rotate")?;
if let Some(value) = rotate.try_as_integer()? {
// qpdf's rotatePage reads the found value through
// getValueAsInt(int&), which saturates out-of-i32-range
// integers to INT_MIN/INT_MAX with a warning
// (getIntValueAsInt, QPDFObjectHandle.cc:525-543) rather
// than using the raw value. Absent/non-integer /Rotate
// still falls through to the /Parent walk below, exactly
// as qpdf's isInteger() guard does, so this only clamps
// once an integer is actually found.
old_angle = rotate.saturate_i64_to_i32_range_with_warning(value)?;
break;
}
let parent = current.try_get_key(b"/Parent")?;
parent.try_dereference()?;
if parent.try_is_dictionary()? {
current = parent;
} else {
break;
}
}
if old_angle % 90 != 0 {
old_angle = 0;
}
new_angle += old_angle;
}
// Keep C++'s remainder semantics for negative angles while widening
// before the addition so the Rust implementation cannot overflow at
// the edge of the i32 API domain.
let normalized = (new_angle + 360) % 360;
self.replace_key(b"/Rotate", ObjectHandle::integer(normalized))
}
/// Replace an array-valued `/Contents` entry with one lazy stream whose
/// bytes are produced by the canonical page-content pipeline.
///
/// This ports `QPDFObjectHandle::coalesceContentStreams`
/// (`libqpdf/QPDFObjectHandle.cc:1550-1572`). A single stream, missing
/// `/Contents`, null, and other non-array values are no-ops. An array
/// requires an owning document because qpdf creates a document-owned
/// replacement stream and registers a deferred provider; no decoded byte
/// cache is installed here.
///
/// # Errors
///
/// Returns [`Error::Internal`] when an array needs coalescing but this
/// handle has no owning document, and propagates resolution, ownership,
/// stream allocation, or provider-registration failures.
pub fn coalesce_content_streams(&self) -> Result<()> {
let old_contents = self.try_get_key(b"/Contents")?;
if old_contents.type_code()? == 10 || !old_contents.try_is_array()? {
return Ok(());
}
let resolver = self.context().ok_or_else(|| {
Error::System(
"coalesceContentStreams called on object with no associated PDF file".to_owned(),
)
})?;
let new_contents = resolver.new_stream()?;
self.replace_key(b"/Contents", new_contents.clone())?;
let provider = Rc::new(CoalesceContentProvider {
containing_page: self.clone(),
old_contents,
});
new_contents.replace_stream_data_provider(
provider,
Some(ObjectHandle::null()),
Some(ObjectHandle::null()),
)
}
/// Pipe this page's `/Contents` through qpdf's decoded, newline-joining
/// content-stream pipeline.
///
/// This ports `QPDFObjectHandle::pipePageContents`
/// (`libqpdf/QPDFObjectHandle.cc:1702-1707`). `all_description` is kept
/// internal to the delegated call so parse/stream errors retain the same
/// page and object-generation context as qpdf.
pub fn pipe_page_contents(&self, pipeline: &mut dyn Pipeline) -> Result<()> {
let description = format!("page object {}", object_generation_description(self));
let contents = self.try_get_key(b"/Contents")?;
let mut all_description = String::new();
contents.pipe_content_streams(pipeline, &description, &mut all_description)
}
/// Pipe this handle when it is a stream or an array of streams, decoding
/// each stream at qpdf's specialized level and inserting one newline only
/// when the preceding decoded stream did not end in one.
///
/// This ports `QPDFObjectHandle::pipeContentStreams`
/// (`libqpdf/QPDFObjectHandle.cc:1709-1737`). A private buffer mirrors
/// qpdf's `Pl_Buffer`: stream pipelines may finish it after each member,
/// while the caller's pipeline is written and finished exactly once after
/// all members have been decoded.
pub fn pipe_content_streams(
&self,
pipeline: &mut dyn Pipeline,
description: &str,
all_description: &mut String,
) -> Result<()> {
let (streams, generated_description) = self.array_or_stream_to_stream_array(description)?;
all_description.clear();
all_description.push_str(&generated_description);
let mut buffer = Buffer::new("concatenated content stream buffer", None);
let mut need_newline = false;
for stream in streams {
if need_newline {
buffer.write(b"\n")?;
}
let mut last_char = Count::new("last character", &mut buffer);
let mut filtering_attempted = false;
// qpdf's five-argument `pipeStreamData` overload
// (`QPDFObjectHandle.cc:1313-1324`) discards the inner six-
// argument overload's own success return and reports only
// whether filtering was attempted, so this discards it too: a
// decode failure whose filter still ran is not itself a content
// stream failure here, matching qpdf's caller
// (`QPDFObjectHandle.cc:1719-1729`), which checks only that.
let _ = stream.pipe_stream_data(
&mut last_char,
&mut filtering_attempted,
0,
DecodeLevel::Specialized,
false,
false,
)?;
if !filtering_attempted {
return Err(Error::QpdfExc(QpdfExc::new(
QpdfErrorCode::DamagedPdf,
b"content stream",
format!(
"content stream object {}",
object_generation_description(&stream)
),
0,
b"errors while decoding content stream",
)));
}
last_char.finish()?;
need_newline = last_char.last_byte() != b'\n';
}
let data = buffer.take_buffer()?;
pipeline.write(&data)?;
pipeline.finish()?;
Ok(())
}
/// Parse this page's decoded `/Contents` through qpdf's ObjectHandle
/// callback boundary.
///
/// This ports `QPDFObjectHandle::parsePageContents`
/// (`libqpdf/QPDFObjectHandle.cc:1740-1744`). The decoded bytes are
/// buffered only for the parser, just as qpdf's `Pl_Buffer` path is; the
/// page-content source remains the canonical stream/provider pipeline.
pub fn parse_page_contents<C: ObjectHandleParserCallbacks>(
&self,
callbacks: &mut C,
) -> Result<()> {
let contents = self.try_get_key(b"/Contents")?;
self.parse_content_stream_handles(
&contents,
format!("page object {}", object_generation_description(self)),
callbacks,
)
}
/// Parse this stream or stream array as content, matching qpdf's
/// `QPDFObjectHandle::parseAsContents` (`:1747-1751`).
pub fn parse_as_contents<C: ObjectHandleParserCallbacks>(
&self,
callbacks: &mut C,
) -> Result<()> {
self.parse_content_stream_handles(
self,
format!("object {}", object_generation_description(self)),
callbacks,
)
}
fn parse_content_stream_handles<C: ObjectHandleParserCallbacks>(
&self,
contents: &ObjectHandle,
description: String,
callbacks: &mut C,
) -> Result<()> {
let mut buffer = Buffer::new("concatenated content stream buffer", None);
let mut all_description = String::new();
contents.pipe_content_streams(&mut buffer, &description, &mut all_description)?;
let data = buffer.take_buffer()?;
parse_content_stream_handles(
&data,
contents.context().or_else(|| self.context()),
&all_description,
callbacks,
)
}
/// Apply one qpdf lexical token filter to decoded page contents.
///
/// `next` is the optional downstream pipeline corresponding to qpdf's
/// nullable `Pipeline*` argument. The canonical page-content route owns
/// tokenizer construction and finishes it exactly once.
pub fn filter_page_contents<'a>(
&self,
filter: &'a mut dyn TokenFilter,
next: Option<&'a mut dyn Pipeline>,
) -> Result<()> {
let description = format!(
"token filter for page object {}",
object_generation_description(self)
);
let mut token_pipeline = QpdfTokenizer::new(description, filter, next);
self.pipe_page_contents(&mut token_pipeline)
}
/// Apply one qpdf lexical token filter to this stream/Form contents.
///
/// This ports `QPDFObjectHandle::filterAsContents`
/// (`libqpdf/QPDFObjectHandle.cc:1762-1767`) over the specialized decode
/// path, without introducing a second tokenizer or filter implementation.
pub fn filter_as_contents<'a>(
&self,
filter: &'a mut dyn TokenFilter,
next: Option<&'a mut dyn Pipeline>,
) -> Result<()> {
let description = format!(
"token filter for object {}",
object_generation_description(self)
);
let mut token_pipeline = QpdfTokenizer::new(description, filter, next);
let mut filtering_attempted = false;
// qpdf's legacy pipeStreamData overload returns only whether
// filtering was attempted; filterAsContents deliberately ignores the newer
// overall-success bool. Provider/source/sink errors still propagate
// through `?`, while an ordinary false result is not an exception.
self.pipe_stream_data(
&mut token_pipeline,
&mut filtering_attempted,
0,
DecodeLevel::Specialized,
false,
false,
)?;
Ok(())
}
/// The normalized page content streams plus the qpdf description used by
/// downstream pipe/parse error messages. Keeping this alongside
/// [`Self::get_page_contents`] prevents later entry points from
/// reimplementing array/null handling.
fn page_contents_with_description(&self) -> Result<(Vec<ObjectHandle>, String)> {
let description = format!("page object {}", object_generation_description(self));
let contents = self.try_get_key(b"/Contents")?;
contents.array_or_stream_to_stream_array(&description)
}
/// Normalize this handle when it is a stream or an array of streams.
///
/// The helper is intentionally private to the ObjectHandle content family;
/// callers should use [`Self::get_page_contents`] so the description is
/// attached to the page object rather than guessed at each call site.
fn array_or_stream_to_stream_array(
&self,
description: &str,
) -> Result<(Vec<ObjectHandle>, String)> {
self.try_dereference()?;
let mut result = Vec::new();
if let Some(items) = self.as_array() {
for (index, item) in items.into_iter().enumerate() {
if item.type_code()? == 10 {
result.push(item);
} else {
item.warn_through_context(QpdfExc::new(
QpdfErrorCode::DamagedPdf,
b"",
format!("{description}: item index {index} (from 0)"),
0,
b"ignoring non-stream in an array of streams",
))?;
}
}
} else if self.type_code()? == 10 {
result.push(self.clone());
} else if !self.is_null() {
self.warn_through_context(QpdfExc::new(
QpdfErrorCode::DamagedPdf,
b"",
description,
0,
b" object is supposed to be a stream or an array of streams but is neither",
))?;
}
let mut all_description = description.to_owned();
let mut first = true;
for item in &result {
if first {
first = false;
} else {
all_description.push(',');
}
all_description.push_str(" stream ");
all_description.push_str(&object_generation_description(item));
}
Ok((result, all_description))
}
/// Replace this handle's stream data with the given buffer, and — when
/// given — its `/Filter` and `/DecodeParms` dictionary keys, mirroring
/// `QPDFObjectHandle::replaceStreamData`'s buffer overload
/// (`libqpdf/QPDFObjectHandle.cc:1345-1350`, delegating to
/// `QPDF_Stream::replaceStreamData`/`replaceFilterData`,
/// `libqpdf/QPDF_Stream.cc:637-649,669-685`). `filter`/`decode_parms`
/// are `Some` exactly where qpdf's own overload checks
/// `QPDFObjectHandle::isInitialized()`: `Some` installs the key through
/// qpdf's stream-internal dictionary replacement path, `None` leaves it
/// untouched rather than removing it. A zero byte length removes
/// `/Length`; a nonzero length installs the exact integer, matching qpdf's
/// shared `QPDF_Stream::replaceFilterData` boundary for buffer and
/// provider replacement. A no-op if this handle's value is not a stream.
///
/// `data` is installed as given, not copied — qpdf's own
/// `std::shared_ptr<Buffer>` overload is documented against its
/// string overload precisely on that point
/// (`include/qpdf/QPDFObjectHandle.hh:1086-1097`). This is what lets one
/// buffer back two streams, as `QPDF::copyStreamData` does
/// (`libqpdf/QPDF.cc:2240,2256-2258`).
///
/// See [`Self::replace_key`]'s doc comment for the same canonical
/// resolution behavior, since this method mutates the stream data in
/// place and updates its dictionary through qpdf's lower-level
/// stream-internal path.
pub fn replace_stream_data(
&self,
data: Rc<Vec<u8>>,
filter: Option<ObjectHandle>,
decode_parms: Option<ObjectHandle>,
) {
self.set_content_normalization_applied(false);
let length = data.len();
self.with_value_mut(|v| {
if let Some(ObjectValue::Stream(stream)) = v {
stream.stream_data = Some(data);
stream.stream_provider = None;
}
});
self.replace_filter_data(filter, decode_parms, length);
}
/// Replace this handle's stream source with a deferred qpdf-style
/// [`StreamDataProvider`]. The provider is retained without being called
/// or materialized. The provider source clears any replaced buffer, and a
/// zero length is passed to the shared filter boundary so `/Length` is
/// removed until the pipe path observes the provider's actual output.
///
/// `None` filter/decode parameters preserve existing keys. An explicit
/// [`ObjectHandle::null`] removes them through the canonical dictionary
/// mutation path. A non-stream handle returns qpdf's `asStreamWithAssert`
/// runtime classification as [`Error::System`]. Provider registration is
/// restricted to indirect streams because the provider callback requires
/// the stream's stable `ObjectRef`; a direct stream is rejected here at
/// registration time rather than being accepted and failing later at the
/// pipe boundary.
///
/// This mutates the live stream and dictionary in place; the canonical
/// writer observes the same live allocation before writing the document.
pub fn replace_stream_data_provider(
&self,
provider: Rc<dyn StreamDataProvider>,
filter: Option<ObjectHandle>,
decode_parms: Option<ObjectHandle>,
) -> Result<()> {
self.try_dereference()?;
if !self.with_value(|value| matches!(value, Some(ObjectValue::Stream(_)))) {
let type_name = self.type_name()?;
return Err(Error::System(format!(
"operation for stream attempted on object of type {}",
type_name
)));
}
self.set_content_normalization_applied(false);
if !self.is_indirect() {
return Err(Error::System(
STREAM_DATA_PROVIDER_REQUIRES_INDIRECT_ERROR.to_owned(),
));
}
self.with_value_mut(|value| {
if let Some(ObjectValue::Stream(stream)) = value {
stream.stream_data = None;
stream.stream_provider = Some(provider);
}
});
self.replace_filter_data(filter, decode_parms, 0);
Ok(())
}
/// Register a qpdf-style void callback as a deferred stream provider.
pub fn replace_stream_data_with_callback<F>(
&self,
callback: F,
filter: Option<ObjectHandle>,
decode_parms: Option<ObjectHandle>,
) -> Result<()>
where
F: Fn(&mut dyn Pipeline) -> Result<()> + 'static,
{
self.replace_stream_data_provider(
Rc::new(CallbackProvider { callback }),
filter,
decode_parms,
)
}
/// Register a qpdf-style retry-aware callback as a deferred stream
/// provider. Its return value is consumed by the provider pipe boundary.
pub fn replace_stream_data_with_retry_callback<F>(
&self,
callback: F,
filter: Option<ObjectHandle>,
decode_parms: Option<ObjectHandle>,
) -> Result<()>
where
F: Fn(&mut dyn Pipeline, bool, bool) -> Result<bool> + 'static,
{
self.replace_stream_data_provider(
Rc::new(RetryCallbackProvider { callback }),
filter,
decode_parms,
)
}
/// Replace a stream's dictionary while retaining the stream object's
/// identity and payload/provider.
///
/// This is qpdf's `QPDF_Stream::replaceDict` boundary
/// (`libqpdf/QPDF_Stream.cc:688-693`), used by
/// `QPDF::JSONReactor::dictionaryItem` for `stream.dict`
/// (`libqpdf/QPDF_json.cc:629-637`). The replacement updates the stream's
/// forward dictionary child in the same canonical mutation path as
/// ordinary dictionary changes.
pub(crate) fn replace_stream_dict(&self, dictionary: ObjectHandle) -> Result<()> {
self.try_dereference()?;
dictionary.try_dereference()?;
if !dictionary.try_is_dictionary()? {
return Err(Error::System(
"operation for stream dictionary attempted with a non-dictionary".to_owned(),
));
}
self.check_key_value_ownership(&dictionary)?;
let previous = self.with_value_mut(|value| match value {
Some(ObjectValue::Stream(stream)) => Some(std::mem::replace(
&mut stream.stream_dict,
dictionary.clone(),
)),
_ => None,
});
let Some(_previous) = previous else {
let type_name = self.type_name()?;
return Err(Error::System(format!(
"operation for stream attempted on object of type {}",
type_name
)));
};
Ok(())
}
/// Apply the filter and length dictionary mutations shared by qpdf's
/// buffer and provider `QPDF_Stream::replaceStreamData` overloads
/// (`libqpdf/QPDF_Stream.cc:640-684`).
fn replace_filter_data(
&self,
filter: Option<ObjectHandle>,
decode_parms: Option<ObjectHandle>,
length: usize,
) {
let Some(dict) = self.as_stream_dict() else {
return;
};
if let Some(filter) = filter {
dict.replace_key_unchecked(b"/Filter", filter);
}
if let Some(decode_parms) = decode_parms {
dict.replace_key_unchecked(b"/DecodeParms", decode_parms);
}
if length == 0 {
dict.remove_key(b"/Length");
} else {
dict.replace_key_unchecked(
b"/Length",
ObjectHandle::integer(i64::try_from(length).unwrap_or(i64::MAX)),
);
}
}
/// Return the live dictionary owned by a stream after lazily resolving the
/// receiver. This is qpdf's public `QPDFObjectHandle::getDict()` boundary
/// (`include/qpdf/QPDFObjectHandle.hh:968-970`), whose implementation calls
/// `asStreamWithAssert()` and therefore dereferences before asserting the
/// stream type (`libqpdf/QPDFObjectHandle.cc:313-324,1257-1262`).
///
/// Unlike [`Self::as_stream_dict`], this is fallible and resolving: a
/// non-stream or uninitialized handle returns qpdf's runtime-error
/// equivalent, while resolver failures propagate unchanged.
///
/// # Errors
///
/// Returns [`Error::System`] for a non-stream or uninitialized handle and
/// propagates any resolver error encountered while dereferencing an
/// indirect handle.
pub fn try_get_stream_dict(&self) -> Result<ObjectHandle> {
if !self.is_initialized() {
return Err(Error::System(
"operation for stream attempted on object of type uninitialized".to_owned(),
));
}
self.try_dereference()?;
if let Some(dictionary) = self.as_stream_dict() {
return Ok(dictionary);
}
let type_name = self.type_name()?;
Err(Error::System(format!(
"operation for stream attempted on object of type {type_name}"
)))
}
/// The stream's own dictionary handle if this handle's value — its own
/// if direct, or its already-resolved value if indirect — is a stream,
/// or `None` otherwise. This never performs resolution itself: an
/// indirect handle that has not yet been resolved returns `None` too,
/// the same as a resolved value of a different type. Cloning the
/// returned handle is O(1): it shares the dictionary's identity rather
/// than copying its subtree.
pub fn as_stream_dict(&self) -> Option<ObjectHandle> {
self.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => Some(stream.stream_dict.clone()),
_ => None,
})
}
/// Enable or disable qpdf writer filtering for this stream.
///
/// This is qpdf's `QPDFObjectHandle::setFilterOnWrite`
/// (`include/qpdf/QPDFObjectHandle.hh:972-982`,
/// `libqpdf/QPDFObjectHandle.cc:1265-1268`). When disabled, the writer
/// must not decode, normalize, or recompress the stream, even when the
/// stream is modified or the writer requests a non-none decode level.
/// The setting belongs to the canonical stream value, so cloned handles
/// observe the same state. It is not serialized; the canonical stream state
/// is updated so the next writer observation uses the new filtering policy.
pub fn set_filter_on_write(&self, value: bool) -> Result<()> {
self.try_dereference()?;
let is_stream = self.with_value_mut(|state| match state {
Some(ObjectValue::Stream(stream)) => {
stream.filter_on_write = value;
true
}
_ => false,
});
if is_stream {
Ok(())
} else {
let type_name = self.type_name()?;
Err(Error::System(format!(
"operation for stream attempted on object of type {type_name}"
)))
}
}
/// Return whether qpdf's writer may filter this stream.
///
/// This is qpdf's `QPDFObjectHandle::getFilterOnWrite`
/// (`include/qpdf/QPDFObjectHandle.hh:972-982`,
/// `libqpdf/QPDFObjectHandle.cc:1271-1273`).
pub fn get_filter_on_write(&self) -> Result<bool> {
self.try_dereference()?;
let value = self.with_value(|state| match state {
Some(ObjectValue::Stream(stream)) => Some(stream.filter_on_write),
_ => None,
});
if let Some(value) = value {
return Ok(value);
}
let type_name = self.type_name()?;
Err(Error::System(format!(
"operation for stream attempted on object of type {type_name}"
)))
}
/// The stream's raw encoded byte payload if this handle's value — its
/// own if direct, or its already-resolved value if indirect — is a
/// stream, or `None` otherwise. This never performs resolution itself:
/// an indirect handle that has not yet been resolved returns `None`
/// too, the same as a resolved value of a different type.
///
/// The payload is shared, not copied: this hands out the same allocation
/// the stream holds, mirroring `QPDF_Stream::getStreamDataBuffer`
/// (`libqpdf/qpdf/QPDF_Stream.hh:39`), which returns qpdf's
/// `std::shared_ptr<Buffer>` itself.
pub fn as_stream_data(&self) -> Option<Rc<Vec<u8>>> {
self.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => stream.stream_data.clone(),
_ => None,
})
}
/// Whether this stream currently uses a deferred provider source rather
/// than replacement bytes or its parsed original source. This is kept at
/// the canonical stream boundary so qpdf's foreign-copy path can preserve
/// the different source-lifetime contracts of provider and file-backed
/// streams.
pub(crate) fn has_stream_data_provider(&self) -> bool {
self.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => stream.stream_provider.is_some(),
_ => false,
})
}
/// The parsed source length retained by an original stream, when this
/// handle currently contains a stream. qpdf stores this alongside the
/// source offset in `QPDF_Stream`; the foreign-copy provider captures it
/// without retaining the source `ObjectHandle` itself.
pub(crate) fn stream_source_length(&self) -> Option<usize> {
self.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => Some(stream.stream_length),
_ => None,
})
}
/// Whether qpdf must treat this stream's data as modified even when its
/// original encoded payload is still available. `QPDF_Stream::isDataModified`
/// is true as soon as a token filter is registered
/// (`libqpdf/QPDF_Stream.cc:321-324`); the writer uses that bit to avoid
/// copying a lone `/FlateDecode` source without running the filter
/// (`libqpdf/QPDFWriter.cc:1234-1315`).
pub(crate) fn is_data_modified(&self) -> bool {
self.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => !stream.stream_token_filters.is_empty(),
_ => false,
})
}
/// Whether the current stream bytes have already passed the explicit
/// content-normalization consumer. This is intentionally not inferred
/// from `replaceStreamData`: qpdf's replacement API is also used for
/// arbitrary caller data that still needs QDF normalization.
pub(crate) fn content_normalization_applied(&self) -> bool {
self.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => stream.content_normalization_applied,
_ => false,
})
}
/// Mark the current stream bytes as normalized by the content consumer.
/// The marker follows the shared payload state, just like qpdf's stream
/// token-filter list, so aliases do not cause a second normalization pass.
#[doc(hidden)]
pub fn mark_content_normalization_applied(&self) {
self.set_content_normalization_applied(true);
}
fn set_content_normalization_applied(&self, applied: bool) {
self.with_value_mut(|value| {
if let Some(ObjectValue::Stream(stream)) = value {
stream.content_normalization_applied = applied;
}
});
}
/// Register a qpdf-style lazy token filter on this stream. The original
/// source bytes remain untouched; the filter is inserted into the decoded
/// stream pipeline only when a filtering pipe is requested.
pub fn add_token_filter(&self, filter: Rc<RefCell<dyn TokenFilter>>) -> Result<()> {
self.try_dereference()?;
if !self.with_value(|value| matches!(value, Some(ObjectValue::Stream(_)))) {
let type_name = self.type_name()?;
return Err(Error::System(format!(
"operation for stream attempted on object of type {}",
type_name
)));
}
self.with_value_mut(|value| {
if let Some(ObjectValue::Stream(stream)) = value {
stream.stream_token_filters.push(filter);
}
});
Ok(())
}
/// Coalesce a page's content array through the canonical lazy provider and
/// attach a token filter to the replacement stream, matching qpdf's
/// `QPDFObjectHandle::addContentTokenFilter` (`:1850-1854`).
pub fn add_content_token_filter(&self, filter: Rc<RefCell<dyn TokenFilter>>) -> Result<()> {
self.coalesce_content_streams()?;
self.try_get_key(b"/Contents")?.add_token_filter(filter)
}
/// Pipe this stream through qpdf's filter branch.
///
/// This is the `QPDFObjectHandle::pipeStreamData` entry point
/// (`libqpdf/QPDFObjectHandle.cc:1300-1341`) over the
/// `QPDF_Stream::filterable` and reverse-stage construction owned here
/// (`libqpdf/QPDF_Stream.cc:379-569`). `filtering_attempted` is the
/// qpdf out-parameter: it records a usable installed filter branch and is
/// cleared if the source branch fails; the returned bool is overall
/// source-pipeline success. Keeping those results separate is what lets a
/// writer retry a failed filtering decision with raw bytes
/// (`libqpdf/QPDFWriter.cc:1239-1314`).
///
/// `encode_flags` is a bitwise OR of [`STREAM_ENCODE_COMPRESS`] and
/// [`STREAM_ENCODE_NORMALIZE`], qpdf's `qpdf_ef_compress` and
/// `qpdf_ef_normalize` bits. The output stages are built first, then
/// the stream filters are added in reverse `/Filter` order. The source
/// is finally dispatched through the completed chain.
#[allow(clippy::too_many_arguments)]
pub fn pipe_stream_data(
&self,
pipeline: &mut dyn Pipeline,
filtering_attempted: &mut bool,
encode_flags: u32,
decode_level: DecodeLevel,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
self.pipe_stream_data_inner(
pipeline,
filtering_attempted,
encode_flags,
decode_level,
suppress_warnings,
will_retry,
)
}
/// Return decoded stream data through the canonical source pipeline.
///
/// This is qpdf's `QPDFObjectHandle::getStreamData`
/// (`libqpdf/QPDFObjectHandle.cc:1289-1292`) over the same
/// `QPDF_Stream::pipeStreamData` path used by page-content piping
/// (`libqpdf/QPDFObjectHandle.cc:1710-1722`). Both this path and
/// [`Self::get_raw_stream_data`] use the source pipeline's decryption;
/// this method additionally applies the requested decode filters.
pub fn get_stream_data(&self, decode_level: DecodeLevel) -> Result<Rc<Vec<u8>>> {
// qpdf calls asStreamWithAssert before entering QPDF_Stream
// (`libqpdf/QPDFObjectHandle.cc:1288-1292`), so receiver resolution
// and non-stream errors belong at this public boundary.
let _stream_dict = self.try_get_stream_dict()?;
let mut buffer = crate::pipeline::buffer::Buffer::new("stream data", None);
let mut filtering_attempted = false;
let stream_data_succeeded = self.pipe_stream_data(
&mut buffer,
&mut filtering_attempted,
0,
decode_level,
false,
false,
)?; // cov:ignore: multiline call terminator has no executable coverage region
if !filtering_attempted {
let filename = self
.context()
.map(|context| context.input_description())
.unwrap_or_default();
return Err(Error::QpdfExc(QpdfExc::new(
QpdfErrorCode::Unsupported,
filename,
b"",
self.get_parsed_offset(),
b"getStreamData called on unfilterable stream",
)));
}
let _ = stream_data_succeeded;
Ok(Rc::new(buffer.take_buffer()?))
}
/// Probe whether qpdf can construct a filtering pipe for this stream.
///
/// This is the overload of `QPDFObjectHandle::pipeStreamData` that calls
/// `QPDF_Stream::pipeStreamData` with a null pipeline and returns only its
/// `filtering_attempted` result (`libqpdf/QPDFObjectHandle.cc:1300-1317`,
/// `libqpdf/QPDF_Stream.cc:488-512`). The probe validates filters and
/// decode parameters but never reads source bytes, matching qpdf's
/// `QPDFJob::doShowObj` preflight.
pub fn stream_data_filterable(&self, decode_level: DecodeLevel) -> Result<bool> {
self.try_dereference()?;
let Some(stream_dict) = self.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => Some(stream.stream_dict.clone()),
_ => None,
}) else {
return Err(Error::Internal(
"pipeStreamData called for non-stream".to_owned(),
));
};
let Some(plan) = self.prepare_stream_filter_plan(&stream_dict)? else {
return Ok(false);
};
Ok(
!((plan.lossy_compression && decode_level < DecodeLevel::All)
|| (plan.specialized_compression && decode_level < DecodeLevel::Specialized)),
)
}
/// Write qpdf's extended stream JSON representation.
///
/// This is `QPDF_Stream::writeStreamJSON`
/// (`libqpdf/QPDF_Stream.cc:207-295`), kept on the canonical stream handle
/// rather than split between a separate stream payload reader and
/// a document-level dictionary writer. `json_data` matches qpdf's three
/// `qpdf_json_stream_data_e` values. The optional pipeline is the side-file
/// sink required by `File`; it is deliberately not the JSON output sink.
///
/// The returned decode level is the effective level used after qpdf's
/// filtered-to-raw retry. Callers that do not need it may discard it, but
/// retaining it is what lets a future `getStreamJSON` facade attach an
/// inline blob to the exact successful decode level.
#[allow(clippy::too_many_arguments)]
pub(crate) fn write_stream_json(
&self,
json_version: i32,
out: &mut dyn Pipeline,
json_data: QpdfStreamJsonData,
mut decode_level: DecodeLevel,
pipeline: Option<&mut dyn Pipeline>,
data_filename: impl AsRef<[u8]>,
no_data_key: bool,
depth: usize,
) -> std::result::Result<DecodeLevel, ObjectJsonError> {
let data_filename = data_filename.as_ref();
if !matches!(json_version, 1 | 2) {
return Err(ObjectJsonError::UnsupportedVersion(json_version));
}
match json_data {
QpdfStreamJsonData::None | QpdfStreamJsonData::Inline if pipeline.is_some() => {
return Err(ObjectJsonError::Pdf(
"QPDF_Stream::writeStreamJSON: pipeline should only be supplied when json_data is file"
.to_owned(),
));
}
QpdfStreamJsonData::File if pipeline.is_none() => {
return Err(ObjectJsonError::Pdf(
"QPDF_Stream::writeStreamJSON: pipeline must be supplied when json_data is file"
.to_owned(),
));
}
QpdfStreamJsonData::File if data_filename.is_empty() => {
return Err(ObjectJsonError::Pdf(
"QPDF_Stream::writeStreamJSON: data_filename must be supplied when json_data is file"
.to_owned(),
));
}
_ => {}
}
self.try_dereference()
.map_err(|error| ObjectJsonError::Pdf(error.to_string()))?;
let stream_dict = self.as_stream_dict().ok_or_else(|| {
ObjectJsonError::Pdf(
"QPDF_Stream::writeStreamJSON called on a non-stream object".to_owned(),
)
})?;
let mut stream_first = true;
Json::write_dictionary_open(out, &mut stream_first, depth)?;
if matches!(json_data, QpdfStreamJsonData::None) {
Json::write_dictionary_key(out, &mut stream_first, b"dict", depth + 1)?;
stream_dict.write_json(json_version, out, false, depth + 1)?;
Json::write_dictionary_close(out, stream_first, depth)?;
return Ok(decode_level);
}
let mut payload = None;
let mut filtered = false;
let mut filter = !matches!(decode_level, DecodeLevel::None);
for attempt in 1..=2 {
let mut buffer = Buffer::new("stream data", None);
let mut discard = Discard;
let data_pipeline: &mut dyn Pipeline =
if no_data_key && matches!(json_data, QpdfStreamJsonData::Inline) {
&mut discard
} else {
&mut buffer
};
let mut filtering_attempted = false;
let succeeded = self
.pipe_stream_data(
data_pipeline,
&mut filtering_attempted,
0,
decode_level,
false,
attempt == 1,
)
.map_err(|error| ObjectJsonError::Pdf(error.to_string()))?;
if !succeeded || (filter && !filtering_attempted) {
filter = false;
decode_level = DecodeLevel::None;
continue;
}
filtered = filter && filtering_attempted;
if !no_data_key || !matches!(json_data, QpdfStreamJsonData::Inline) {
buffer.finish().map_err(ObjectJsonError::Pipeline)?;
payload = Some(buffer.take_buffer().map_err(ObjectJsonError::Pipeline)?);
} else {
payload = Some(Vec::new());
}
break;
}
let payload = payload.ok_or_else(|| {
ObjectJsonError::Pdf("QPDF_Stream: failed to get stream data".to_owned())
})?;
let dict = stream_dict
.shallow_copy()
.map_err(|error| ObjectJsonError::Pdf(error.to_string()))?;
dict.remove_key(b"/Length");
if filter && filtered {
dict.remove_key(b"/Filter");
dict.remove_key(b"/DecodeParms");
}
match json_data {
QpdfStreamJsonData::Inline if !no_data_key => {
Json::write_dictionary_item(
out,
&mut stream_first,
b"data",
&Json::make_blob(move |sink| sink.write(&payload)),
depth + 1,
)?;
}
QpdfStreamJsonData::Inline => {}
QpdfStreamJsonData::File => {
Json::write_dictionary_item(
out,
&mut stream_first,
b"datafile",
&Json::make_string(data_filename),
depth + 1,
)?;
pipeline
.expect("file mode pipeline was validated above")
.write(&payload)?;
}
QpdfStreamJsonData::None => {
unreachable!("none mode returned before payload piping") // cov:ignore: none mode returns before payload piping
}
}
Json::write_dictionary_key(out, &mut stream_first, b"dict", depth + 1)?;
dict.write_json(json_version, out, false, depth + 1)?;
Json::write_dictionary_close(out, stream_first, depth)?;
Ok(decode_level)
}
/// Return qpdf's extended stream JSON representation.
///
/// This is `QPDFObjectHandle::getStreamJSON` and
/// `QPDF_Stream::getStreamJSON` (`include/qpdf/QPDFObjectHandle.hh:1235`,
/// `libqpdf/QPDF_Stream.cc:96-107`). `None` returns only the stream
/// dictionary, `File` writes payload bytes to the supplied pipeline, and
/// `Inline` attaches a lazy JSON blob that retains this stream handle until
/// the returned JSON value is serialized. The owning [`crate::Pdf`] must
/// remain alive until that serialization, matching qpdf's source-lifetime
/// contract for `StreamBlobProvider`.
pub fn get_stream_json(
&self,
json_version: i32,
json_data: QpdfStreamJsonData,
decode_level: DecodeLevel,
pipeline: Option<&mut dyn Pipeline>,
data_filename: impl AsRef<[u8]>,
) -> std::result::Result<Json, ObjectJsonError> {
let data_filename = data_filename.as_ref();
let no_data_key = matches!(json_data, QpdfStreamJsonData::Inline);
let mut output = Buffer::new("stream JSON", None);
let effective_decode_level = self.write_stream_json(
json_version,
&mut output,
json_data,
decode_level,
pipeline,
data_filename,
no_data_key,
0,
)?; // cov:ignore: the validated canonical writer call has no independent LLVM terminator counter
output.finish().map_err(ObjectJsonError::Pipeline)?;
let bytes = output.take_buffer().map_err(ObjectJsonError::Pipeline)?;
let result =
Json::parse(&bytes).map_err(|error| ObjectJsonError::Json(error.to_string()))?;
if matches!(json_data, QpdfStreamJsonData::Inline) {
let stream = self.clone();
let blob = Json::make_blob(move |sink| {
let mut filtering_attempted = false;
let succeeded = stream
.pipe_stream_data(
sink,
&mut filtering_attempted,
0,
effective_decode_level,
false,
false,
)
// qpdf's StreamBlobProvider forwards whatever
// `pipeStreamData` throws without catching it
// (`QPDF_Stream.cc:104-107`), so a `logic_error` must stay
// a logic error. `Error::Internal` is this crate's
// `std::logic_error`, so map it back to the logic category
// instead of flattening every failure to runtime.
.map_err(|error| match error {
crate::Error::Internal(message) => PipelineError::logic(message),
other => PipelineError::runtime(other.to_string()),
})?;
let _ = succeeded;
Ok(())
});
result
.add_dictionary_member(b"data", blob)
.map_err(|error| ObjectJsonError::Json(error.to_string()))?;
}
Ok(result)
}
#[allow(clippy::too_many_arguments)]
fn pipe_stream_data_inner(
&self,
pipeline: &mut dyn Pipeline,
filtering_attempted: &mut bool,
encode_flags: u32,
decode_level: DecodeLevel,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
self.try_dereference()?;
let Some((token_filters, stream_dict, stream_data, stream_provider, stream_length)) = self
.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => Some((
stream.stream_token_filters.clone(),
stream.stream_dict.clone(),
stream.stream_data.clone(),
stream.stream_provider.clone(),
stream.stream_length,
)),
_ => None,
})
else {
return Err(Error::Internal(
"pipeStreamData called for non-stream".to_owned(),
));
};
*filtering_attempted = false;
// `QPDF_Stream::pipeStreamData` constructs the filtering stages only
// when an encode/decode policy is requested (`QPDF_Stream.cc:488-520`).
// `isDataModified` is consumed by `QPDFWriter::willFilterStream` to
// decide whether the writer must enter this pipe at all; it does not
// by itself turn Preserve-mode pipe calls into decoded token-filter
// calls.
let filter_requested = encode_flags != 0 || !matches!(decode_level, DecodeLevel::None);
if !filter_requested {
return self.pipe_stream_source(
&stream_dict,
stream_data,
stream_provider.clone(),
stream_length,
pipeline,
suppress_warnings,
will_retry,
);
}
let Some(mut plan) = self.prepare_stream_filter_plan(&stream_dict)? else {
return self.pipe_stream_source(
&stream_dict,
stream_data,
stream_provider.clone(),
stream_length,
pipeline,
suppress_warnings,
will_retry,
);
};
if (plan.lossy_compression && decode_level < DecodeLevel::All)
|| (plan.specialized_compression && decode_level < DecodeLevel::Specialized)
{
return self.pipe_stream_source(
&stream_dict,
stream_data,
stream_provider.clone(),
stream_length,
pipeline,
suppress_warnings,
will_retry,
);
}
*filtering_attempted = true;
let mut head = PipelineRef::Borrowed(pipeline);
let warning_delivery_error: Rc<RefCell<Option<Error>>> = Rc::new(RefCell::new(None));
let normalization_warnings =
if encode_flags & STREAM_ENCODE_NORMALIZE != 0 && !suppress_warnings {
Some(Rc::new(RefCell::new(Vec::new())))
} else {
None
};
if encode_flags & STREAM_ENCODE_COMPRESS != 0 {
let compress = Flate::new(
"compress stream",
head,
FlateAction::Deflate,
DEFAULT_OUT_BUFFER_SIZE,
)?; // cov:ignore: fixed nonzero output buffer makes Flate::new's failure branch untestable here
head = PipelineRef::Owned(Box::new(compress));
}
if encode_flags & STREAM_ENCODE_NORMALIZE != 0 {
let mut normalizer = ContentNormalizerPipeline::new("normalizer", head);
if let Some(warnings) = normalization_warnings.as_ref() {
let warnings = Rc::clone(warnings);
normalizer.set_warning_callback(Box::new(move |message| {
warnings.borrow_mut().push(message.to_owned());
Ok(())
}));
}
head = PipelineRef::Owned(Box::new(normalizer));
}
// qpdf's source order is decode filters -> token filters -> content
// normalization -> encoding. Since `head` is assembled from the
// sink backwards, token filters are wrapped before the decode stages
// in reverse registration order (`QPDF_Stream.cc:488-620`).
for filter in token_filters
.0
.into_iter()
.flat_map(|filters| filters.0)
.rev()
{
let tokenizer = QpdfTokenizer::new_shared("stream token filter", filter, Some(head));
head = PipelineRef::Owned(Box::new(tokenizer));
}
for filter in plan.filters.iter_mut().rev() {
let warning_handle = self.clone();
let warning_delivery_error = Rc::clone(&warning_delivery_error);
let suppress_filter_warnings = suppress_warnings;
filter.set_warning_callback(Box::new(move |message, _code| {
if suppress_filter_warnings {
return Ok(());
}
match warning_handle.stream_data_warning(message) {
Ok(()) => Ok(()),
Err(error) => {
let error_message = error.to_string();
*warning_delivery_error.borrow_mut() = Some(error);
Err(PipelineError::runtime(error_message))
}
}
}));
head = match filter.get_decode_pipeline(head)? {
OwnedDecodePipeline::Stage(stage) => PipelineRef::Owned(stage),
OwnedDecodePipeline::NoStage(next) => next,
};
}
let success = self
.pipe_stream_source(
&stream_dict,
stream_data,
stream_provider,
stream_length,
&mut head,
suppress_warnings,
will_retry,
)
.map_err(|error| warning_delivery_error.borrow_mut().take().unwrap_or(error))?;
if let Some(error) = warning_delivery_error.borrow_mut().take() {
// A source-backed decoder can recover its codec failure and
// return `false` after the warning callback itself failed. Keep
// that callback error visible to the resolver instead of
// converting the member to qpdf's ordinary null fallback.
return Err(error);
}
if !success {
*filtering_attempted = false;
}
if success {
if let Some(warnings) = normalization_warnings {
for warning in warnings.borrow_mut().drain(..) {
self.stream_data_warning(&warning)?;
}
}
}
Ok(success)
}
/// Report a warning raised by `QPDF_Stream` itself (filter-plan
/// validation, `pipeStreamData`) with the stream-data location, not the
/// generic object-warning description.
///
/// qpdf's `QPDF_Stream::warn` (`libqpdf/QPDF_Stream.cc:695-698`) is the
/// single private helper every in-class warning shares — `filterable`'s
/// malformed `/Filter`/`/DecodeParms` warnings (`QPDF_Stream.cc:413,459`)
/// as well as `pipeStreamData`'s codec and content-normalization
/// warnings — and routes them through `QPDF::warn(..., parsed_offset,
/// ...)`, so a parsed stream warning is rendered as `file (offset N):
/// message` and retains that offset in the document warning collection.
/// Programmatic streams have no parsed offset; they retain the ordinary
/// `QPDFObjectHandle::objectWarning` fallback.
fn stream_data_warning(&self, message: &str) -> Result<()> {
let offset = self.get_parsed_offset();
if offset >= 0 {
if let Some(context) = self.context() {
return context.warn_stream_data(QpdfExc::new(
QpdfErrorCode::DamagedPdf,
context.input_description(),
b"",
offset,
message.as_bytes(),
));
} // cov:ignore: the return above makes this LLVM closing-branch artifact unreachable
}
self.object_warning(message)
}
fn prepare_stream_filter_plan(
&self,
stream_dict: &ObjectHandle,
) -> Result<Option<StreamFilterPlan>> {
let filter = stream_dict.try_get_key(b"/Filter")?;
let filter_names = if filter.try_is_null()? {
Vec::new()
} else if let Some(name) = filter.try_as_name()? {
vec![name]
} else if let Some(count) = filter.try_array_len()? {
let mut names = Vec::with_capacity(count);
let mut malformed = false;
for index in 0..count {
let item = filter.try_array_item(index)?.ok_or_else(|| {
// cov:ignore-start: immutable array length and item lookup cannot diverge
Error::Internal("filter array item disappeared during inspection".to_owned())
// cov:ignore-end
// cov:ignore-start: LLVM attributes the unreachable defensive closure result here
})?;
// cov:ignore-end
if let Some(name) = item.try_as_name()? {
names.push(name);
} else {
malformed = true;
}
}
if malformed {
self.stream_data_warning(FILTER_TYPE_ERROR)?;
return Ok(None);
}
names
} else {
self.stream_data_warning(FILTER_TYPE_ERROR)?;
return Ok(None);
};
// qpdf ignores /DecodeParms entirely when /Filter is empty.
if filter_names.is_empty() {
return Ok(Some(StreamFilterPlan {
filters: Vec::new(),
specialized_compression: false,
lossy_compression: false,
}));
}
// qpdf looks up every factory before it reads /DecodeParms. Keeping
// this ordering is observable for an unknown filter paired with a
// dangling or mismatched parameter object.
let mut filters = Vec::with_capacity(filter_names.len());
let mut filters_okay = true;
for name in &filter_names {
let normalized_name = normalize_filter_name(name);
if let Some(filter) = stream_filter_for(normalized_name)? {
filters.push(filter);
} else {
filters_okay = false;
};
}
if !filters_okay {
return Ok(None);
}
let decode_params = stream_dict.try_get_key(b"/DecodeParms")?;
let decode_param_handles = if decode_params.try_is_null()? {
vec![ObjectHandle::null(); filter_names.len()]
} else if let Some(count) = decode_params.try_array_len()? {
if count == 0 {
vec![ObjectHandle::null(); filter_names.len()]
} else {
if count != filter_names.len() {
self.stream_data_warning(DECODE_PARMS_LENGTH_ERROR)?;
return Ok(None);
}
let mut handles = Vec::with_capacity(count);
for index in 0..count {
// cov:ignore-start: llvm-cov attributes this defensive closure to the call line
handles.push(decode_params.try_array_item(index)?.ok_or_else(|| {
Error::Internal(
"decode parameters array item disappeared during inspection".to_owned(),
)
})?);
// cov:ignore-end
}
handles
}
} else {
vec![decode_params; filter_names.len()]
};
let mut plan = StreamFilterPlan {
filters: Vec::with_capacity(filter_names.len()),
specialized_compression: false,
lossy_compression: false,
};
let mut filterable = true;
for (mut filter, decode_params) in filters.into_iter().zip(decode_param_handles) {
// qpdf calls every stage's setDecodeParms before returning the
// aggregate filterable result (`QPDF_Stream.cc:467-482`). Keep
// capability flags only from accepted stages; a rejected stage
// still has to run so its later warning/resolution effects remain
// observable.
let stage_filterable = filter.set_decode_params(&decode_params)?;
if !stage_filterable {
filterable = false;
} else {
plan.specialized_compression |= filter.is_specialized_compression();
plan.lossy_compression |= filter.is_lossy_compression();
}
plan.filters.push(filter);
}
Ok(filterable.then_some(plan))
}
/// Return this stream's raw (undecoded) bytes.
///
/// Replaced stream data is written directly; original data is read through
/// the owning document at the parsed offset and stored parse-time length.
/// No filter or decoder stage is constructed here.
///
/// qpdf correspondence: `QPDF_Stream::getRawStreamData`
/// (`libqpdf/QPDF_Stream.cc:362-376`).
pub fn get_raw_stream_data(&self) -> Result<Rc<Vec<u8>>> {
// Match QPDFObjectHandle::getRawStreamData's asStreamWithAssert
// boundary (`libqpdf/QPDFObjectHandle.cc:1294-1297`) before the raw
// source pipe performs its stream-data work.
let _stream_dict = self.try_get_stream_dict()?;
let mut buffer = crate::pipeline::buffer::Buffer::new("stream data", None);
if !self.pipe_raw_stream_data(&mut buffer)? {
return Err(Error::QpdfExc(QpdfExc::new(
QpdfErrorCode::Unsupported,
self.context()
.map(|context| context.input_description())
.unwrap_or_default(),
b"",
self.get_parsed_offset(),
b"error getting raw stream data",
)));
}
Ok(Rc::new(buffer.take_buffer()?))
}
fn pipe_raw_stream_data(&self, pipeline: &mut dyn crate::pipeline::Pipeline) -> Result<bool> {
self.try_dereference()?;
let Some((stream_dict, stream_data, stream_provider, stream_length)) =
self.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => Some((
stream.stream_dict.clone(),
stream.stream_data.clone(),
stream.stream_provider.clone(),
stream.stream_length,
)),
_ => None,
})
else {
return Err(Error::Internal(
"pipeStreamData called for non-stream".to_owned(),
));
};
self.pipe_stream_source(
&stream_dict,
stream_data,
stream_provider,
stream_length,
pipeline,
false,
false,
)
}
#[allow(clippy::too_many_arguments)]
fn pipe_stream_source(
&self,
stream_dict: &ObjectHandle,
stream_data: Option<Rc<Vec<u8>>>,
stream_provider: Option<Rc<dyn StreamDataProvider>>,
stream_length: usize,
pipeline: &mut dyn Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
if let Some(stream_data) = stream_data {
pipeline.write(&stream_data)?;
pipeline.finish()?;
return Ok(true);
}
// qpdf dispatches the deferred source after replaced bytes and before
// the parsed-offset/original branch (`libqpdf/QPDF_Stream.cc:571-620`).
// Pl_Count is part of that provider boundary: it forwards every
// incremental write and measures the bytes that actually reached the
// decoder/output pipeline (`libqpdf/QPDF_Stream.cc:575-604`).
if let Some(provider) = stream_provider {
let object_gen = self
.qpdf_obj_gen()
.filter(|object_gen| object_gen.is_indirect())
.ok_or_else(|| {
Error::Internal(
"pipeStreamData called for provider-backed direct stream".to_owned(),
)
})?;
let mut count = Count::new("stream provider count", pipeline);
let success = if provider.supports_retry() {
provider.provide_stream_data_with_retry_by_qpdf_obj_gen(
i64::from(object_gen.get_obj()),
i64::from(object_gen.get_gen()),
&mut count,
suppress_warnings,
will_retry,
)?
} else {
provider.provide_stream_data_by_qpdf_obj_gen(
i64::from(object_gen.get_obj()),
i64::from(object_gen.get_gen()),
&mut count,
)?;
true
};
if !success {
return Ok(false);
}
let actual_length = i64::try_from(count.count()).map_err(|_| {
// cov:ignore-start: an in-memory provider cannot emit more than i64::MAX bytes in a test
Error::System("stream data provider length exceeds PDF integer range".to_owned())
// cov:ignore-end
})?; // cov:ignore: closing line of the unreachable signed-PDF-range guard
if stream_dict.try_has_key(b"/Length")? {
let desired_length = stream_dict.try_get_key(b"/Length")?.try_get_int_value()?;
if actual_length != desired_length {
return Err(Error::System(format!(
"stream data provider for {} {} provided {} bytes instead of expected {} bytes",
object_gen.get_obj(),
object_gen.get_gen(),
actual_length,
desired_length
)));
}
} else {
stream_dict.replace_key_unchecked(b"/Length", ObjectHandle::integer(actual_length));
}
return Ok(true);
}
let parsed_offset = self.get_parsed_offset();
if parsed_offset == 0 {
return Err(Error::Internal(
"pipeStreamData called for stream with no data".to_owned(),
));
}
let (object_gen, resolver) = {
let slot = self.0.borrow();
let Some(object_gen) = slot
.qpdf_obj_gen()
.filter(|object_gen| object_gen.is_indirect())
else {
return Err(Error::Internal(
"pipeStreamData called for original direct stream".to_owned(),
));
};
(object_gen, slot.resolver())
};
let Some(resolver) = resolver.and_then(|resolver| resolver.upgrade()) else {
return Err(Error::Internal(format!(
"object {} {} belongs to a dropped PDF",
object_gen.get_obj(),
object_gen.get_gen()
)));
};
resolver.pipe_stream_data_qpdf_obj_gen(
object_gen,
parsed_offset,
stream_length,
stream_dict,
pipeline,
suppress_warnings,
will_retry,
)
}
/// The value as raw operator bytes if this handle's value — its own if
/// direct, or its already-resolved value if indirect — is a
/// content-stream operator token, or `None` otherwise. Never performs
/// resolution itself.
pub fn as_operator(&self) -> Option<Vec<u8>> {
self.with_value(|value| match value {
Some(ObjectValue::Operator(bytes)) => Some(bytes.clone()),
_ => None,
})
}
/// The value as raw inline-image bytes if this handle's value — its own
/// if direct, or its already-resolved value if indirect — is an
/// inline-image payload, or `None` otherwise. Never performs resolution
/// itself.
pub fn as_inline_image(&self) -> Option<Vec<u8>> {
self.with_value(|value| match value {
Some(ObjectValue::InlineImage(bytes)) => Some(bytes.clone()),
_ => None,
})
}
/// Return the qpdf-compatible numeric type code after resolving this
/// handle's own indirect object: `include/qpdf/Constants.h:108-127`'s
/// `qpdf_object_type_e` ordinals. qpdf's own `getTypeCode()`/`getTypeName()`
/// (`include/qpdf/QPDFObjectHandle.hh:311-316`,
/// `libqpdf/QPDFObjectHandle.cc:240-250`) call `dereference()` before
/// inspecting the value. The internal `try_dereference` helper mirrors that
/// handle-layer responsibility and propagates resolver failures through
/// [`crate::Result`].
///
/// Reserved and destroyed handles are checked before resolution and retain
/// qpdf's `1` (`ot_reserved`) and `14` (`ot_destroyed`) ordinals. The
/// An uninitialized handle returns qpdf's `ot_uninitialized` code (`0`)
/// without entering the resolver, matching `getTypeCode`'s null-handle
/// fallback (`libqpdf/QPDFObjectHandle.cc:240-244`).
///
/// # Errors
///
/// Returns the resolver error when an unresolved indirect handle cannot be
/// resolved, such as when its owning document has been dropped.
pub fn type_code(&self) -> Result<u8> {
if !self.is_initialized() {
return Ok(0);
}
self.try_dereference()?;
self.with_value(|value| {
Ok(value
.expect("every reachable state here (direct or indirect Resolved) carries a value")
.type_code())
})
}
/// Return this handle's value type as a human-readable name.
///
/// An uninitialized handle returns `"uninitialized"`; other resolution
/// errors are propagated unchanged.
///
/// qpdf correspondence: `QPDFObjectHandle::getTypeName` dereferences and
/// delegates to `QPDFObject::getTypeName`
/// (`libqpdf/QPDFObjectHandle.cc:247-250`), which reads the value-layer
/// `type_name` field.
pub fn type_name(&self) -> Result<&'static str> {
if !self.is_initialized() {
return Ok("uninitialized");
}
self.try_dereference()?;
self.with_value(|value| {
Ok(value
.expect("every reachable state here (direct or indirect Resolved) carries a value")
.type_name())
})
}
/// Write this handle's JSON encoding to a pipeline.
///
/// This ports `QPDFObjectHandle::writeJSON`
/// (`include/qpdf/QPDFObjectHandle.hh:1205`,
/// `libqpdf/QPDFObjectHandle.cc:1630-1647`), which qpdf documents as
/// equivalent to, but more efficient than, calling
/// `getJSON(json_version, dereference_indirect).write(p, depth)` — see
/// [`Self::get_json`]. The writer is deliberately owned by the handle
/// layer: qpdf dispatches from `QPDFObjectHandle::writeJSON` into each
/// `QPDF_*::writeJSON` implementation using one `JSON::Writer`
/// (`QPDF_Array.cc:153-187`, `QPDF_Dictionary.cc:72-95`,
/// `qpdf/JSON_writer.hh:16-135`), and the caller retains the outer
/// pipeline's `finish` boundary. `dereference_indirect` applies only to
/// this handle: array and dictionary children use qpdf's ordinary
/// non-dereferencing child dispatch, so an indirect child remains an
/// `"N G R"` string even when the parent was requested with
/// `dereference_indirect = true`.
///
/// # Errors
///
/// Returns [`ObjectJsonError::UnsupportedVersion`] unless `json_version`
/// is `1` or `2`, and otherwise propagates the pipeline and object-state
/// failures documented on [`ObjectJsonError`].
pub fn write_json(
&self,
json_version: i32,
out: &mut dyn Pipeline,
dereference_indirect: bool,
depth: usize,
) -> std::result::Result<(), ObjectJsonError> {
if !matches!(json_version, 1 | 2) {
return Err(ObjectJsonError::UnsupportedVersion(json_version));
}
ObjectJsonWriter::new(out, depth).write_handle(
self,
json_version,
dereference_indirect,
depth,
ObjectJsonDispatch::Handle,
)
}
/// Return this handle's JSON encoding.
///
/// This ports `QPDFObjectHandle::getJSON(int json_version, bool
/// dereference_indirect)` (`include/qpdf/QPDFObjectHandle.hh:1198`).
/// `PlString` is the flpdf equivalent of qpdf's `Pl_Buffer` at this
/// boundary: `get_json` writes through the same canonical handle writer
/// used by [`Self::write_json`] and only parses the completed bytes
/// after that writer returns, rather than exposing a second serializer
/// path.
///
/// # Errors
///
/// Propagates [`Self::write_json`]'s errors, plus
/// [`ObjectJsonError::Json`] if the intermediate bytes fail to parse.
pub fn get_json(
&self,
json_version: i32,
dereference_indirect: bool,
) -> std::result::Result<crate::json::Json, ObjectJsonError> {
let mut bytes = Vec::new();
{
let mut out = PlString::new("object json", None, &mut bytes);
self.write_json(json_version, &mut out, dereference_indirect, 0)?;
}
crate::json::Json::parse(&bytes).map_err(|error| ObjectJsonError::Json(error.to_string()))
}
// `try_dereference` owns the explicit resolution boundary. Once the
// handle is resolved, including to qpdf's internal Unresolved/Reserved/
// Destroyed value, this helper exposes the actual ObjectValue.
pub(crate) fn with_value<T>(&self, f: impl FnOnce(Option<&ObjectValue>) -> T) -> T {
let shared = self.0.borrow().shared.clone();
let shared = shared.borrow();
f(Some(&shared.value))
}
fn json_dispatch_state(&self) -> JsonDispatchState {
let slot = self.0.borrow();
let shared = slot.shared.borrow();
JsonDispatchState {
initialized: slot.initialized,
object_gen: shared.qpdf_obj_gen(),
unresolved: matches!(shared.value, ObjectValue::Unresolved),
reserved: matches!(shared.value, ObjectValue::Reserved),
resolver_present: shared.identity.resolver.is_some(),
}
}
// Mutable twin of `with_value`: every resolved qpdf value, including the
// internal sentinels, is a real mutable value-layer slot.
fn with_value_mut<T>(&self, f: impl FnOnce(Option<&mut ObjectValue>) -> T) -> T {
let shared = self.0.borrow().shared.clone();
let mut shared = shared.borrow_mut();
f(Some(&mut shared.value))
}
/// This handle's qpdf-syntax unparse form
/// (`include/qpdf/QPDFObjectHandle.hh:1159`,
/// `libqpdf/QPDFObjectHandle.cc:1574-1584`): an indirect handle always
/// unparses to its own `"N G R"`, regardless of resolution state; a
/// direct handle delegates to [`Self::unparse_resolved`].
pub fn unparse(&self) -> Vec<u8> {
if let Some(object_gen) = self
.qpdf_obj_gen()
.filter(|object_gen| object_gen.is_indirect())
{
return format!("{} {} R", object_gen.get_obj(), object_gen.get_gen()).into_bytes();
}
match self.object_ref() {
Some(object_ref) => object_ref.to_string().into_bytes(),
None => self.unparse_resolved(),
}
}
/// This handle's resolved qpdf-syntax form
/// (`libqpdf/QPDFObjectHandle.cc:1586-1593`). The direct serializer walks
/// `ObjectValue` and child [`ObjectHandle`] values without constructing
/// a detached value tree. It resolves the receiver before
/// dispatch, resolves array/dictionary children in qpdf's order, omits
/// dictionary entries whose values resolve to null, and keeps indirect
/// children in reference form (`libqpdf/QPDF_Array.cc:122-149`,
/// `libqpdf/QPDF_Dictionary.cc:58-68`). An indirect stream remains its
/// own reference because `QPDF_Stream::unparse` returns that form
/// (`libqpdf/QPDF_Stream.cc:173-178`).
///
/// This non-fallible convenience method retains the existing null fallback
/// when the qpdf operation would throw. Call [`Self::try_unparse_resolved`]
/// at production error boundaries that need the qpdf error classification.
pub fn unparse_resolved(&self) -> Vec<u8> {
let mut out = Vec::new();
if unparse_resolved_into(self, &mut out, false).is_err() {
out.clear();
out.extend_from_slice(b"null");
}
out
}
/// This handle's resolved qpdf-syntax form through a fallible error
/// boundary, porting `QPDFObjectHandle::unparseResolved`
/// (`libqpdf/QPDFObjectHandle.cc:1586-1593`). Unlike
/// [`Self::unparse_resolved`], this variant first resolves an unresolved
/// indirect handle and preserves qpdf's logic errors for reserved and
/// destroyed values (`QPDF_Reserved::unparse`,
/// `libqpdf/QPDF_Reserved.cc:22-26`; `QPDF_Destroyed::unparse`,
/// `libqpdf/QPDF_Destroyed.cc:24-29`).
///
/// The fallible qpdf-shaped error boundary for resolved serialization.
///
/// `QPDFObjectHandle::unparseResolved` first dereferences the receiver and
/// then delegates to `QPDFObject::unparse`; the value implementations throw
/// for unresolved, reserved, and destroyed values
/// (`libqpdf/QPDFObjectHandle.cc:1586-1593`,
/// `libqpdf/QPDF_Unresolved.cc:23-27`,
/// `libqpdf/QPDF_Reserved.cc:22-26`,
/// `libqpdf/QPDF_Destroyed.cc:24-28`). This method preserves those errors
/// while the non-fallible [`Self::unparse_resolved`] facade maps them to its
/// established `null` fallback.
pub fn try_unparse_resolved(&self) -> Result<Vec<u8>> {
let mut out = Vec::new();
unparse_resolved_into(self, &mut out, true)?;
Ok(out)
}
/// Replace this handle's own value in place, preserving its identity
/// (every other outstanding clone observes the new value) and its
/// already-recorded parsed offset (`parsed_offset` is untouched here --
/// see [`Self::reset_parsed_offset`] to clear it). A no-op for an
/// indirect handle; see [`Self::set_resolved`] for that case.
///
/// Used by canonical replacement code to update a stream's own dictionary handle
/// in place when the replacement value is also a stream, so the
/// dictionary handle's already-recorded `<<`-start parsed offset
/// survives instead of being lost to a freshly minted handle.
#[cfg(test)]
pub(crate) fn replace_direct_value(&self, value: ObjectValue) {
if self.is_direct() {
self.replace_shared_state(canonicalize_object_value(value));
}
}
/// Reset this handle's parsed offset back to the no-offset sentinel,
/// overriding the set-once contract [`Self::set_parsed_offset_if_unset`]
/// normally enforces.
///
/// Used by canonical replacement code: once it replaces an indirect handle's
/// value with a caller-supplied one, any previously recorded source
/// position no longer describes that value.
pub(crate) fn reset_parsed_offset(&self) {
let shared = self.0.borrow().shared.clone();
shared.borrow_mut().parsed_offset = NO_PARSED_OFFSET;
}
}
// Direct `QPDFObjectHandle::unparseResolved` serialization. The value and
// child handles remain in the canonical ObjectHandle graph; no detached raw
// `Object` projection is created. Dictionary null suppression follows
// `QPDF_Dictionary::unparse` (`libqpdf/QPDF_Dictionary.cc:58-68`), while array
// elements retain nulls (`libqpdf/QPDF_Array.cc:122-149`).
fn unparse_resolved_into(handle: &ObjectHandle, out: &mut Vec<u8>, strict: bool) -> Result<()> {
direct_graph_walk_hub(|| {
handle.try_dereference()?;
let value = handle
.with_value(|value| value.cloned())
.expect("every ObjectHandle carries a value state");
if handle.is_indirect() && matches!(value, ObjectValue::Stream(_)) {
if let Some(object_ref) = handle.object_ref() {
write_unparse_reference(object_ref, out);
} else if let Some(object_gen) = handle.qpdf_obj_gen() {
out.extend_from_slice(
format!("{} {} R", object_gen.get_obj(), object_gen.get_gen()).as_bytes(),
);
}
return Ok(());
}
unparse_resolved_value(handle, value, out, strict)
})
}
// `QPDF_Array::unparse` resolves each element only to read its own object/
// generation identity (`item.second->resolve(); auto og =
// item.second->getObjGen();`, `libqpdf/QPDF_Array.cc:130-132`), but that
// identity is a property of the *handle itself*, not of whatever it resolves
// to — an indirect handle already carries its object/generation number before
// resolution ever runs. Read the raw qpdf identity first, so a dangling or
// malformed indirect child still emits its own `N G R` form without requiring
// resolution to succeed.
fn unparse_resolved_child(handle: &ObjectHandle, out: &mut Vec<u8>, strict: bool) -> Result<()> {
if let Some(object_gen) = handle
.qpdf_obj_gen()
.filter(|object_gen| object_gen.is_indirect())
{
out.extend_from_slice(
format!("{} {} R", object_gen.get_obj(), object_gen.get_gen()).as_bytes(),
);
Ok(())
} else {
unparse_resolved_into(handle, out, strict)
}
}
fn unparse_resolved_value(
handle: &ObjectHandle,
value: ObjectValue,
out: &mut Vec<u8>,
strict: bool,
) -> Result<()> {
match value {
ObjectValue::Null => out.extend_from_slice(b"null"),
ObjectValue::Unresolved => {
if strict {
return Err(unresolved_unparse_error());
}
out.extend_from_slice(b"null");
}
ObjectValue::Reserved => {
if strict {
return Err(reserved_unparse_error());
}
out.extend_from_slice(b"null");
}
ObjectValue::Destroyed => {
if strict {
return Err(destroyed_unparse_error());
}
out.extend_from_slice(b"null");
}
ObjectValue::Boolean(value) => {
out.extend_from_slice(if value { b"true" } else { b"false" });
}
ObjectValue::Integer(value) => out.extend_from_slice(value.to_string().as_bytes()),
ObjectValue::Real(value) => out.extend_from_slice(value.to_string().as_bytes()),
ObjectValue::RealLiteral { value, literal } => {
if crate::pdf_syntax::real_literal_is_safe(&literal, value) {
out.extend_from_slice(&literal);
} else {
out.extend_from_slice(value.to_string().as_bytes());
}
}
ObjectValue::Name(value) => {
out.push(b'/');
crate::writer::output::with_buffer_sink(out, |sink| {
crate::pdf_syntax::write_name_escaped(sink, &value)
})?;
}
ObjectValue::String(value) => {
crate::writer::output::with_buffer_sink(out, |sink| {
crate::pdf_syntax::write_string_value(sink, &value)
})?;
}
ObjectValue::Operator(value) | ObjectValue::InlineImage(value) => {
out.extend_from_slice(&value);
}
ObjectValue::Array(children) => {
out.extend_from_slice(b"[ ");
for child in children {
unparse_resolved_child(&child, out, strict)?;
out.push(b' ');
}
out.push(b']');
}
ObjectValue::Dictionary(entries) => {
out.extend_from_slice(b"<< ");
for (key, child) in entries {
if child.try_is_null()? {
continue;
}
write_unparse_dictionary_key(out, &key)?;
out.push(b' ');
unparse_resolved_child(&child, out, strict)?;
out.push(b' ');
}
out.extend_from_slice(b">>");
}
ObjectValue::Stream(stream) => {
// qpdf owns streams as indirect objects. This direct-stream arm
// retains the existing Rust-only factory behavior for a value
// without an object number.
unparse_resolved_into(&stream.stream_dict, out, strict)?;
out.extend_from_slice(b"\nstream\n");
let data = match &stream.stream_data {
Some(data) => data.clone(),
None => handle.get_raw_stream_data()?,
};
out.extend_from_slice(&data);
out.extend_from_slice(b"\nendstream");
}
}
Ok(())
}
fn write_unparse_reference(object_ref: ObjectRef, out: &mut Vec<u8>) {
out.extend_from_slice(object_ref.to_string().as_bytes());
}
fn write_unparse_dictionary_key(out: &mut Vec<u8>, key: &[u8]) -> Result<()> {
if let Some((&first, tail)) = key.split_first() {
// QPDF_Name::normalizeName preserves the first byte and escapes only
// the remainder (`libqpdf/QPDF_Name.cc:27-49`).
out.push(first);
crate::writer::output::with_buffer_sink(out, |sink| {
crate::pdf_syntax::write_name_escaped(sink, tail)
})?;
}
Ok(())
}
// Stack growth uses the same red-zone and growth size for direct serialization,
// makeDirect, and the other recursive ObjectHandle walkers in this module.
// The direct-graph walkers reach them through `direct_graph_walk_hub` below,
// which adds the nesting bound they need; `make_direct` uses them on its own.
const UNPARSE_STACK_RED_ZONE: usize = 32 * 1024;
const UNPARSE_STACK_GROWTH_SIZE: usize = 1024 * 1024;
// Active recursion depth of this module's direct-graph walkers
// (`ObjectHandle::shallow_copy` and `unparse_resolved_into`).
//
// `stacker::maybe_grow` swaps stack segments without leaving the current
// thread, so a thread-local counter observes every level of one walk and
// never mixes two concurrent copies or serializations.
//
// Neither walker records the nodes already on its path, and neither does
// qpdf: `QPDF_Dictionary::copy`/`QPDF_Array::copy`
// (`libqpdf/QPDF_Dictionary.cc:36-48`, `libqpdf/QPDF_Array.cc:74-99`) call
// `shallowCopy` on every direct child, and
// `QPDF_Dictionary::unparse`/`QPDF_Array::unparse`
// (`libqpdf/QPDF_Dictionary.cc:58-68`, `libqpdf/QPDF_Array.cc:122-149`)
// unparse every direct child, with no depth argument and no visited set in
// either pair. A pair of *direct* dictionaries holding each other therefore
// recurses until the process runs out of memory. Parsed input cannot reach
// that shape -- `parser.rs` caps direct container nesting at
// `MAX_PARSE_DEPTH` and the direct containers it builds are trees -- but
// [`ObjectHandle::replace_key`] accepts it from a library caller, since it
// refuses only the single-hop self-insert and not the two-hop pair
// `a.replace_key(b"/B", b)` plus `b.replace_key(b"/A", a)`. The array
// mutators reject it already ([`ObjectHandle::set_array_item`] and its
// siblings gate on `would_create_direct_cycle`, a full reachability walk),
// so the dictionary path is the only way in. Bounding both walkers at the
// parser's own limit turns such a graph into a diagnostic instead of
// resource exhaustion, and leaves every graph the parser can produce
// untouched.
//
// `ObjectHandle::make_direct` deliberately stays outside this hub even
// though it shares the stack constants above. It is the one walker here
// that recurses *through* indirect boundaries
// (`Self::make_direct_copy` dereferences every child), so its depth tracks
// indirect chain length, which `MAX_PARSE_DEPTH` does not cap -- a parsed
// file may legally chain far more indirect objects than that. It carries a
// per-call `ObjectHandleIdentity` visited set instead, which already
// rejects a direct cycle as well as an indirect one.
//
// The count starts at zero for the outermost hub, so `MAX_PARSE_DEPTH + 1`
// hub levels are admitted rather than exactly `MAX_PARSE_DEPTH`. That extra
// level is not slack. Both walkers re-enter the hub for a direct *scalar*
// child as well (`unparse_resolved_child` and `shallow_copy_child` recurse
// for everything that is not indirect), so the maximally nested container
// the parser admits -- `MAX_PARSE_DEPTH` containers around a scalar leaf --
// needs `MAX_PARSE_DEPTH + 1` levels to finish. A direct stream spends a
// further level on its own dictionary (`unparse_resolved_value`'s `Stream`
// arm re-enters the walk with `stream_dict`), but that shape comes from the
// value factories rather than the parser, which owns streams indirectly.
thread_local! {
static DIRECT_GRAPH_WALK_DEPTH: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}
// Counts one active level of a direct-graph walk and restores the count when
// the level unwinds, on the error path as well as the success path.
struct DirectGraphWalkDepthGuard;
impl DirectGraphWalkDepthGuard {
fn enter() -> Result<Self> {
let depth = DIRECT_GRAPH_WALK_DEPTH.with(|depth| {
let entered = depth.get();
depth.set(entered + 1);
entered
});
// Constructed before the bound is tested so the count is restored
// even when this level is rejected.
let guard = Self;
if depth > crate::parser::MAX_PARSE_DEPTH {
return Err(Error::Unsupported(format!(
"object handle: direct object nesting exceeds maximum of {}",
crate::parser::MAX_PARSE_DEPTH
)));
}
Ok(guard)
}
}
impl Drop for DirectGraphWalkDepthGuard {
fn drop(&mut self) {
DIRECT_GRAPH_WALK_DEPTH.with(|depth| depth.set(depth.get().saturating_sub(1)));
}
}
/// Run one level of a direct-graph `ObjectHandle` recursion with this
/// module's shared stack growth and nesting bound.
///
/// Both hubs in the family route their bodies through here, so a direct
/// container graph that never reaches an indirect boundary is rejected at
/// the same depth whether it is being copied or serialized.
fn direct_graph_walk_hub<T>(body: impl FnOnce() -> Result<T>) -> Result<T> {
let _depth = DirectGraphWalkDepthGuard::enter()?;
stacker::maybe_grow(UNPARSE_STACK_RED_ZONE, UNPARSE_STACK_GROWTH_SIZE, body)
}
fn reserved_unparse_error() -> Error {
Error::System("QPDFObjectHandle: attempting to unparse a reserved object".to_owned())
}
fn unresolved_unparse_error() -> Error {
Error::Internal("attempted to unparse an unresolved QPDFObjectHandle".to_owned())
}
fn destroyed_unparse_error() -> Error {
Error::Internal("attempted to unparse a QPDFObjectHandle from a destroyed QPDF".to_owned())
}
fn unresolved_copy_error() -> Error {
Error::Internal("attempted to shallow copy an unresolved QPDFObjectHandle".to_owned())
}
fn destroyed_copy_error() -> Error {
Error::Internal("attempted to shallow copy QPDFObjectHandle from destroyed QPDF".to_owned())
}
// Legacy object_copy extraction has no qpdf value-clone counterpart for a
// reserved sentinel. Canonical makeIndirectObject accepts it unchanged.
fn reserved_clone_error() -> Error {
Error::Unsupported(
"cannot clone a reserved ObjectHandle's value for indirect promotion".to_owned(),
)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QpdfStreamJsonData {
/// qpdf's `qpdf_sj_none`: emit only the stream dictionary.
None,
/// qpdf's `qpdf_sj_inline`: emit payload as a base64 JSON string unless
/// the caller is using the `getStreamJSON` no-data-key path.
Inline,
/// qpdf's `qpdf_sj_file`: emit a datafile name and send payload to the
/// caller-supplied side-file pipeline.
File,
}
/// Errors raised by the canonical ObjectHandle JSON writer.
///
/// Pipeline failures stay typed until the caller chooses its public error
/// boundary. qpdf's object-level logic errors remain distinguishable from
/// those failures so get_json and document JSON can preserve their existing
/// conversion/error classifications.
#[derive(Debug, thiserror::Error)]
pub enum ObjectJsonError {
#[error(transparent)]
Pipeline(#[from] PipelineError),
#[error("non-finite float cannot be serialized as JSON")]
NonFiniteFloat,
#[error("PDF error: {0}")]
Pdf(String),
#[error("JSON error: {0}")]
Json(String),
#[error("QPDF::writeJSON: only version 1 or 2 is supported (got {0})")]
UnsupportedVersion(i32),
#[error("QPDFObjectHandle: attempting to get JSON from a reserved object")]
Reserved,
#[error("attempted to get JSON from an unresolved QPDFObjectHandle")]
Unresolved,
#[error("attempted to dereference an uninitialized QPDFObjectHandle")]
Uninitialized,
#[error("attempted to get JSON from a QPDFObjectHandle from a destroyed QPDF")]
Destroyed,
}
// qpdf's JSON::Writer grows the native stack around recursive object writers
// only indirectly through the caller's traversal. ObjectHandle graphs can be
// built directly in Rust, including a direct dictionary cycle, so retain the
// parser's bounded recursion contract here as well.
const OBJECT_JSON_STACK_RED_ZONE: usize = 32 * 1024;
const OBJECT_JSON_STACK_GROWTH_SIZE: usize = 1024 * 1024;
struct ObjectJsonWriter<'a> {
out: &'a mut dyn Pipeline,
first: bool,
indent: usize,
}
enum ObjectJsonContainer {
Array,
Dictionary,
Stream(ObjectHandle),
}
struct JsonDispatchState {
initialized: bool,
object_gen: Option<QpdfObjGen>,
unresolved: bool,
reserved: bool,
resolver_present: bool,
}
/// Which of qpdf's two JSON entry points a value is being written through.
///
/// qpdf reaches the same serializer by two routes that differ in exactly one
/// respect: whether the receiver is resolved first.
/// `QPDFObjectHandle::writeJSON` dereferences it
/// (`libqpdf/QPDFObjectHandle.cc:1630-1639`, `:2376-2383`), while
/// `QPDF_Array::writeJSON` bypasses the handle and writes each element through
/// `QPDFObject::writeJSON`, which never resolves
/// (`libqpdf/QPDF_Array.cc:163-169`).
///
/// The two coincide for every identity but object number zero: an indirect
/// identity takes the reference-form branch before either route can resolve
/// anything, and a direct value is never unresolved to begin with.
#[derive(Clone, Copy)]
enum ObjectJsonDispatch {
/// `QPDFObjectHandle::writeJSON`: resolve the receiver, then serialize.
Handle,
/// `QPDFObject::writeJSON`: serialize the value exactly as it stands.
Value,
}
const LIVE_DICTIONARY_KEY_INLINE_CAPACITY: usize = 32;
pub(crate) struct LiveDictionaryKeyBuffer {
inline: [u8; LIVE_DICTIONARY_KEY_INLINE_CAPACITY],
overflow: Vec<u8>,
length: usize,
}
impl Default for LiveDictionaryKeyBuffer {
fn default() -> Self {
Self {
inline: [0; LIVE_DICTIONARY_KEY_INLINE_CAPACITY],
overflow: Vec::new(),
length: 0,
}
}
}
impl LiveDictionaryKeyBuffer {
fn replace(&mut self, value: &[u8]) {
self.length = value.len();
if value.len() <= self.inline.len() {
self.inline[..value.len()].copy_from_slice(value);
} else {
self.overflow.clear();
self.overflow.extend_from_slice(value);
}
}
pub(crate) fn as_slice(&self) -> &[u8] {
if self.length <= self.inline.len() {
&self.inline[..self.length]
} else {
&self.overflow[..self.length]
}
}
}
impl<'a> ObjectJsonWriter<'a> {
const SPACES: &'static [u8; 52] = b",\n ";
const SPACE_BLOCK: usize = Self::SPACES.len() - 2;
fn new(out: &'a mut dyn Pipeline, depth: usize) -> Self {
Self {
out,
first: true,
indent: 2 * depth,
}
}
fn write_handle(
&mut self,
handle: &ObjectHandle,
json_version: i32,
dereference_indirect: bool,
depth: usize,
dispatch: ObjectJsonDispatch,
) -> std::result::Result<(), ObjectJsonError> {
if depth > crate::parser::MAX_PARSE_DEPTH {
return Err(ObjectJsonError::Pdf(format!(
"object nesting exceeds maximum depth of {}",
crate::parser::MAX_PARSE_DEPTH
)));
}
stacker::maybe_grow(
OBJECT_JSON_STACK_RED_ZONE,
OBJECT_JSON_STACK_GROWTH_SIZE,
|| self.write_handle_inner(handle, json_version, dereference_indirect, depth, dispatch),
)
}
fn write_handle_inner(
&mut self,
handle: &ObjectHandle,
json_version: i32,
dereference_indirect: bool,
depth: usize,
dispatch: ObjectJsonDispatch,
) -> std::result::Result<(), ObjectJsonError> {
let state = handle.json_dispatch_state();
if !state.initialized {
return Err(ObjectJsonError::Uninitialized);
}
// qpdf gates only the *reference form* on `isIndirect()`; every other
// path falls through to `dereference()`
// (`libqpdf/QPDFObjectHandle.cc:1630-1639`), which resolves whatever
// identity the handle carries without consulting `isIndirect()` at all
// (`libqpdf/QPDFObjectHandle.cc:2376-2383`, `QPDFObject::resolve`,
// `libqpdf/qpdf/QPDFObject_private.hh:160-166`). Object number zero
// carries a cache identity while not being an indirect reference
// (`include/qpdf/QPDFObjGen.hh:77-81`), and `QPDF::resolve` settles it
// on the unknown-object null fallback (`libqpdf/QPDF.cc:1743-1747`),
// so on the handle route it must reach the value dispatch below as a
// null rather than as an unresolved value. On the value route
// (`QPDFObject::writeJSON`) qpdf performs no resolution at all, and an
// unresolved value raises its own error instead
// (`libqpdf/QPDF_Unresolved.cc:29-33`).
if !dereference_indirect {
if let Some(object_gen) = state
.object_gen
.filter(|object_gen| object_gen.is_indirect())
{
return self.write_qpdf_obj_gen_reference(object_gen);
}
}
if state.reserved {
return Err(ObjectJsonError::Reserved);
}
if matches!(dispatch, ObjectJsonDispatch::Handle)
&& state.object_gen.is_some()
&& state.unresolved
{
if !state.resolver_present {
return Err(ObjectJsonError::Uninitialized);
}
handle
.try_dereference()
.map_err(|error| ObjectJsonError::Pdf(error.to_string()))?;
}
let container = handle.with_value(|value| match value {
Some(ObjectValue::Null | ObjectValue::Operator(_) | ObjectValue::InlineImage(_)) => {
self.write(b"null")?;
Ok(None)
}
Some(ObjectValue::Unresolved) => Err(ObjectJsonError::Unresolved),
// cov:ignore-start: state.reserved rejects this value immediately
// above, so a reserved ObjectValue cannot reach this arm.
Some(ObjectValue::Reserved) => Err(ObjectJsonError::Reserved),
// cov:ignore-end
Some(ObjectValue::Destroyed) => Err(ObjectJsonError::Destroyed),
Some(ObjectValue::Boolean(value)) => {
self.write(if *value { b"true" } else { b"false" })?;
Ok(None)
}
Some(ObjectValue::Integer(value)) => {
self.write_integer(*value)?;
Ok(None)
}
Some(value @ (ObjectValue::Real(_) | ObjectValue::RealLiteral { .. })) => {
self.write_real_value(value)?;
Ok(None)
}
Some(ObjectValue::String(value)) => {
self.write_string(value, json_version)?;
Ok(None)
}
Some(ObjectValue::Name(value)) => {
self.write_name_value(value, json_version)?;
Ok(None)
}
Some(ObjectValue::Array(_)) => Ok(Some(ObjectJsonContainer::Array)),
Some(ObjectValue::Dictionary(_)) => Ok(Some(ObjectJsonContainer::Dictionary)),
Some(ObjectValue::Stream(stream)) => Ok(Some(ObjectJsonContainer::Stream(
stream.stream_dict.clone(),
))),
// cov:ignore-start: with_value always exposes the resolved value
// as Some; an uninitialized handle returns before this dispatch.
None => Err(ObjectJsonError::Uninitialized),
// cov:ignore-end
})?;
match container {
None => Ok(()),
Some(ObjectJsonContainer::Array) => {
self.write_start(b'[')?;
let items = handle
.try_array_items()
.map_err(|error| ObjectJsonError::Pdf(error.to_string()))?;
let mut cursor = items.begin();
while !cursor.is_end() {
self.write_next()?;
let child = cursor.current();
// `QPDF_Array::writeJSON` writes each element through
// `QPDFObject::writeJSON`, not through the handle
// (`libqpdf/QPDF_Array.cc:163-169`), so an element is
// never resolved on the way out.
self.write_handle(
&child,
json_version,
false,
depth + 1,
ObjectJsonDispatch::Value,
)?;
cursor.next();
}
self.write_end(b']')
}
Some(ObjectJsonContainer::Dictionary) => {
self.write_start(b'{')?;
let mut current_key = LiveDictionaryKeyBuffer::default();
let mut next_key = LiveDictionaryKeyBuffer::default();
let mut first_entry = true;
while let Some(child) = handle.next_dictionary_entry_for_live_write(
(!first_entry).then_some(current_key.as_slice()),
&mut next_key,
) {
std::mem::swap(&mut current_key, &mut next_key);
// QPDF_Dictionary::writeJSON calls isNull() before
// emitting a key. isNull() dereferences unconditionally,
// not gated on isIndirect() (`QPDFObjectHandle.cc:353-356`,
// `:2376-2383`), so missing/dangling values disappear
// from the JSON object while non-null indirect children
// still emit their own reference form below. Object
// number zero carries a cache identity while not being
// indirect (`object_gen.is_some()` without
// `is_indirect()`), and it settles on the same
// unknown-object null fallback, so it must be dropped
// here the same way a dangling indirect child is.
let child_state = child.json_dispatch_state();
if child_state.reserved {
// A reserved child is not null; its non-dereferenced
// identity is still a valid JSON reference.
} else if child_state.object_gen.is_some() && child_state.unresolved {
if !child_state.resolver_present {
return Err(ObjectJsonError::Uninitialized);
}
child
.try_dereference()
.map_err(|error| ObjectJsonError::Pdf(error.to_string()))?;
}
let child_is_null =
child.with_value(|value| matches!(value, Some(ObjectValue::Null)));
if child_is_null {
first_entry = false;
continue;
}
self.write_key(current_key.as_slice(), json_version)?;
// `QPDF_Dictionary::writeJSON` keeps the handle route for
// its values (`libqpdf/QPDF_Dictionary.cc:72-92`).
self.write_handle(
&child,
json_version,
false,
depth + 1,
ObjectJsonDispatch::Handle,
)?;
first_entry = false;
}
self.write_end(b'}')
}
Some(ObjectJsonContainer::Stream(dictionary)) => {
// QPDF_Stream::writeJSON writes only its dictionary. The
// outer stream wrapper belongs to QPDF_Stream::writeStreamJSON
// and the document JSON layer.
self.write_handle(
&dictionary,
json_version,
false,
depth,
ObjectJsonDispatch::Handle,
)
}
}
}
fn write_real_value(
&mut self,
value: &ObjectValue,
) -> std::result::Result<(), ObjectJsonError> {
let (number, literal) = match value {
ObjectValue::Real(number) => (*number, None),
ObjectValue::RealLiteral { value, literal } => (*value, Some(literal.as_slice())),
// cov:ignore-start: the caller's match dispatches only real
// variants before this helper is entered.
_ => unreachable!("real value dispatch must select a real variant"),
// cov:ignore-end
};
if !number.is_finite() {
return Err(ObjectJsonError::NonFiniteFloat);
}
let encoded = literal
.filter(|literal| crate::pdf_syntax::real_literal_is_safe(literal, number))
.map_or_else(|| number.to_string().into_bytes(), ToOwned::to_owned);
if encoded.starts_with(b"-.") {
self.write(b"-0.")?;
self.write(&encoded[2..])
} else if encoded.starts_with(b".") {
self.write(b"0")?;
self.write(&encoded)
} else {
self.write(&encoded)
}
}
/// Write an integer without allocating a temporary string.
///
/// qpdf's `QPDF_Integer::writeJSON` formats directly into its pipeline
/// (`libqpdf/QPDF_Integer.cc:29-32`). Twenty bytes cover every `i64`,
/// including the sign and the minimum value, so the equivalent Rust path
/// can use a stack buffer and preserve the same decimal spelling.
fn write_integer(&mut self, value: i64) -> std::result::Result<(), ObjectJsonError> {
let mut encoded = [0u8; 20];
let mut start = encoded.len();
let mut magnitude = value.unsigned_abs();
loop {
start -= 1;
encoded[start] = b'0' + (magnitude % 10) as u8;
magnitude /= 10;
if magnitude == 0 {
break;
}
}
if value < 0 {
start -= 1;
encoded[start] = b'-';
}
self.write(&encoded[start..])
}
fn write_string(
&mut self,
value: &[u8],
json_version: i32,
) -> std::result::Result<(), ObjectJsonError> {
if json_version == 1 {
return self.write_quoted(&utf8_value(value));
}
if let Some(rest) = value.strip_prefix(&[0xFE, 0xFF]) {
return self.write_unicode_quoted(lossy_utf16_to_utf8(rest, false).as_bytes());
}
if let Some(rest) = value.strip_prefix(&[0xFF, 0xFE]) {
return self.write_unicode_quoted(lossy_utf16_to_utf8(rest, true).as_bytes());
}
if let Some(rest) = value.strip_prefix(&[0xEF, 0xBB, 0xBF]) {
if std::str::from_utf8(rest).is_ok() {
return self.write_unicode_quoted(rest);
}
}
if value.iter().all(|&byte| (0x20..=0x7e).contains(&byte)) {
return self.write_unicode_quoted(value);
}
if !json_use_hex_string(value) {
if let Some(text) = decode_pdf_text_string(value) {
return self.write_unicode_quoted(text.as_bytes());
}
}
self.write(b"\"b:")?;
let mut hex = Vec::with_capacity(value.len() * 2);
for &byte in value {
hex.push(b"0123456789abcdef"[(byte >> 4) as usize]);
hex.push(b"0123456789abcdef"[(byte & 0x0f) as usize]);
}
self.write(&hex)?;
self.write(b"\"")
}
fn write_name_value(
&mut self,
value: &[u8],
json_version: i32,
) -> std::result::Result<(), ObjectJsonError> {
let mut raw = Vec::with_capacity(value.len() + 1);
raw.push(b'/');
raw.extend_from_slice(value);
self.write_name_raw(&raw, json_version)
}
fn write_key(
&mut self,
key: &[u8],
json_version: i32,
) -> std::result::Result<(), ObjectJsonError> {
self.write_next()?;
// qpdf duplicates QPDF_Name::writeJSON's encoding branches in
// QPDF_Dictionary::writeJSON so the closing quote and dictionary
// separator are one Pipeline write (`QPDF_Dictionary.cc:78-90`).
// Keep that observable chunk boundary here instead of routing through
// write_name_raw, whose value form must close its quote on its own.
if json_version == 1 {
self.write(b"\"")?;
let raw = if key.first() == Some(&b'/') {
key
} else {
let mut prefixed = Vec::with_capacity(key.len() + 1);
prefixed.push(b'/');
prefixed.extend_from_slice(key);
self.write_json_encoded(&json_normalize_name(&prefixed))?;
return self.write(b"\": ");
};
self.write_json_encoded(&json_normalize_name(raw))?;
} else if key.first() == Some(&b'/') {
if std::str::from_utf8(key).is_ok() {
self.write(b"\"")?;
self.write_json_encoded(key)?;
} else {
self.write(b"\"n:")?;
self.write_json_encoded(&json_normalize_name(key))?;
}
} else {
let mut raw = Vec::with_capacity(key.len() + 1);
raw.push(b'/');
raw.extend_from_slice(key);
if std::str::from_utf8(&raw).is_ok() {
self.write(b"\"")?;
self.write_json_encoded(&raw)?;
} else {
self.write(b"\"n:")?;
self.write_json_encoded(&json_normalize_name(&raw))?;
}
}
self.write(b"\": ")
}
fn write_name_raw(
&mut self,
raw: &[u8],
json_version: i32,
) -> std::result::Result<(), ObjectJsonError> {
if json_version == 1 {
return self.write_quoted(&json_normalize_name(raw));
}
if std::str::from_utf8(raw).is_ok() {
self.write_quoted(raw)
} else {
self.write(b"\"n:")?;
self.write(&json_encode_string(&json_normalize_name(raw)))?;
self.write(b"\"")
}
}
/// Write qpdf's Unicode-prefixed string form without allocating its fixed
/// three-byte opening (`QPDF_String.cc:57-65`).
fn write_unicode_quoted(&mut self, value: &[u8]) -> std::result::Result<(), ObjectJsonError> {
self.write(b"\"u:")?;
self.write_json_encoded(value)?;
self.write(b"\"")
}
fn write_quoted(&mut self, value: &[u8]) -> std::result::Result<(), ObjectJsonError> {
self.write(b"\"")?;
self.write_json_encoded(value)?;
self.write(b"\"")
}
fn write_json_encoded(&mut self, value: &[u8]) -> std::result::Result<(), ObjectJsonError> {
if json_string_is_safe(value) {
self.write(value)
} else {
self.write(&json_encode_string(value))
}
}
fn write_qpdf_obj_gen_reference(
&mut self,
object_gen: QpdfObjGen,
) -> std::result::Result<(), ObjectJsonError> {
let mut encoded = [0u8; 24];
let mut length = 0;
append_decimal_i32(&mut encoded, &mut length, object_gen.get_obj());
encoded[length] = b' ';
length += 1;
append_decimal_i32(&mut encoded, &mut length, object_gen.get_gen());
self.write(b"\"")?;
self.write(&encoded[..length])?;
self.write(b" R\"")
}
fn write(&mut self, bytes: &[u8]) -> std::result::Result<(), ObjectJsonError> {
self.out.write(bytes).map_err(ObjectJsonError::from)
}
fn write_next(&mut self) -> std::result::Result<(), ObjectJsonError> {
let spaces = self.indent;
let remainder = spaces % Self::SPACE_BLOCK;
if self.first {
self.first = false;
self.write(&Self::SPACES[1..remainder + 2])?;
} else {
self.write(&Self::SPACES[..remainder + 2])?;
}
let mut remaining = spaces;
while remaining >= Self::SPACE_BLOCK {
self.write(&Self::SPACES[2..])?;
remaining -= Self::SPACE_BLOCK;
}
Ok(())
}
fn write_start(&mut self, delimiter: u8) -> std::result::Result<(), ObjectJsonError> {
self.write(&[delimiter])?;
self.first = true;
self.indent += 2;
Ok(())
}
fn write_end(&mut self, delimiter: u8) -> std::result::Result<(), ObjectJsonError> {
if self.indent > 1 {
self.indent -= 2;
}
if !self.first {
self.first = true;
self.write_next()?;
}
self.first = false;
self.write(&[delimiter])
}
}
impl Drop for ObjectHandle {
fn drop(&mut self) {
if Rc::strong_count(&self.0) == 1 {
Self::drain_owned_descendants(&self.0);
}
}
}
impl Drop for ObjectHandleIdentity {
fn drop(&mut self) {
if Rc::strong_count(&self.0) == 1 {
ObjectHandle::drain_owned_descendants(&self.0);
}
}
}
fn json_use_hex_string(bytes: &[u8]) -> bool {
let mut non_ascii = 0usize;
for &byte in bytes {
match byte {
0x20..=0x7e => {}
0x18..=0x1f | 0x7f | 0x80..=0xff => non_ascii += 1,
0x08 | 0x09 | 0x0a | 0x0c | 0x0d => {}
_ => return true,
}
}
5 * non_ascii > bytes.len()
}
fn json_normalize_name(raw: &[u8]) -> Vec<u8> {
if raw.is_empty() {
return Vec::new();
}
let mut normalized = Vec::with_capacity(raw.len() + 2);
normalized.push(raw[0]);
for &byte in &raw[1..] {
if byte == 0 {
normalized.push(b'#');
} else if !(33..=126).contains(&byte)
|| matches!(
byte,
b'#' | b'/' | b'(' | b')' | b'{' | b'}' | b'<' | b'>' | b'[' | b']' | b'%'
)
{
normalized.push(b'#');
normalized.push(b"0123456789abcdef"[(byte >> 4) as usize]);
normalized.push(b"0123456789abcdef"[(byte & 0x0f) as usize]);
} else {
normalized.push(byte);
}
}
normalized
}
fn json_string_is_safe(value: &[u8]) -> bool {
value
.iter()
.all(|&byte| (byte > 34 && byte != b'\\') || byte == b' ' || byte == b'!')
}
fn append_decimal_i32(buffer: &mut [u8], length: &mut usize, value: i32) {
let mut digits = [0u8; 10];
let mut digit_count = 0;
let mut magnitude = value.unsigned_abs();
loop {
digits[digit_count] = b'0' + (magnitude % 10) as u8;
digit_count += 1;
magnitude /= 10;
if magnitude == 0 {
break;
}
}
if value < 0 {
buffer[*length] = b'-';
*length += 1;
}
for digit in digits[..digit_count].iter().rev() {
buffer[*length] = *digit;
*length += 1;
}
}
fn json_encode_string(value: &[u8]) -> Vec<u8> {
let mut encoded = Vec::with_capacity(value.len());
for &byte in value {
match byte {
b'\\' => encoded.extend_from_slice(b"\\\\"),
b'"' => encoded.extend_from_slice(b"\\\""),
b'\x08' => encoded.extend_from_slice(b"\\b"),
b'\x0c' => encoded.extend_from_slice(b"\\f"),
b'\n' => encoded.extend_from_slice(b"\\n"),
b'\r' => encoded.extend_from_slice(b"\\r"),
b'\t' => encoded.extend_from_slice(b"\\t"),
0x00..=0x1f => {
encoded.extend_from_slice(if byte < 0x10 { b"\\u000" } else { b"\\u001" });
encoded.push(b"0123456789abcdef"[(byte & 0x0f) as usize]);
}
_ => encoded.push(byte),
}
}
encoded
}
#[cfg(test)]
mod object_json_writer_tests {
use super::*;
use crate::pipeline::PipelineResult;
use crate::pipeline::PlString;
use serde_json::Value as JsonValue;
use std::rc::Rc;
#[test]
fn json_writer_dispatches_resolved_values_once() {
let source = include_str!("object_handle.rs");
let start = source
.find("fn write_handle_inner(")
.expect("JSON handle dispatcher");
let body = &source[start
..source[start..]
.find("\n fn write_real_value(")
.expect("JSON handle dispatcher end")
+ start];
assert!(
body.contains("handle.with_value"),
"JSON dispatch must match the resolved value while its borrow is live"
);
assert!(
!body.contains("handle.type_code()"),
"JSON dispatch must not probe type_code before a second value accessor"
);
}
struct FailOnChunk {
fail_on: &'static [u8],
bytes: Vec<u8>,
}
impl Pipeline for FailOnChunk {
fn identifier(&self) -> &str {
"fail-on-chunk"
}
fn write(&mut self, bytes: &[u8]) -> PipelineResult<()> {
if bytes == self.fail_on {
return Err(PipelineError::runtime("json sink failed"));
}
self.bytes.extend_from_slice(bytes);
Ok(())
}
// cov:ignore-start: this caller-owned sink is never finished by the JSON writer
fn finish(&mut self) -> PipelineResult<()> {
Ok(())
}
// cov:ignore-end
}
struct AlwaysFailStreamResolver;
impl DocumentResolver for AlwaysFailStreamResolver {
fn resolve_indirect(&self, _object_ref: ObjectRef, handle: &ObjectHandle) -> Result<()> {
handle.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(Vec::new()),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
Ok(())
}
fn pipe_stream_data(
&self,
_object_ref: ObjectRef,
_offset: i64,
_length: usize,
_stream_dict: &ObjectHandle,
_pipeline: &mut dyn Pipeline,
_suppress_warnings: bool,
_will_retry: bool,
) -> Result<bool> {
Ok(false)
}
}
#[test]
fn json_writer_resolves_a_repromoted_unresolved_value_only_when_requested() {
let mut pdf = crate::Pdf::empty().unwrap();
let original = pdf.get_object_handle(ObjectRef::new(99, 0));
let promoted = pdf.make_indirect_object_handle(original.clone()).unwrap();
for (dereference, expected) in [
(false, b"\"100 0 R\"".as_slice()),
(true, b"null".as_slice()),
] {
let mut bytes = Vec::new();
let mut output = PlString::new("promoted-json", None, &mut bytes);
promoted.write_json(2, &mut output, dereference, 0).unwrap();
assert_eq!(bytes, expected);
assert_eq!(original.is_resolved(), dereference);
assert!(original.is_same_object_as(&promoted));
}
}
#[test]
fn json_writer_emits_a_raw_generation_without_an_object_ref_projection() {
let (handle, resolver) = identity_tests::resolver_bearing_handle(ObjectValue::Integer(5));
let raw = handle.promote_to_indirect_qpdf_obj_gen(
QpdfObjGen::new(9, 65_535),
20,
Rc::downgrade(&resolver),
);
let mut bytes = Vec::new();
let mut output = PlString::new("raw-generation-json", None, &mut bytes);
raw.write_json(2, &mut output, false, 0)
.expect("raw qpdf identity is sufficient for a JSON reference");
assert_eq!(bytes, b"\"9 65535 R\"");
}
#[test]
fn writer_rejects_a_direct_reserved_handle_before_type_dispatch() {
let handle = ObjectHandle::new_reserved_direct();
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
let error = handle
.write_json(2, &mut output, false, 0)
.expect_err("reserved values have no JSON representation");
assert!(matches!(error, ObjectJsonError::Reserved));
assert!(bytes.is_empty());
}
#[test]
fn writer_treats_a_reserved_dictionary_child_as_non_null_then_rejects_it() {
let handle = ObjectHandle::dictionary(vec![(
b"Reserved".to_vec(),
ObjectHandle::new_reserved_direct(),
)]);
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
let error = handle
.write_json(2, &mut output, false, 0)
.expect_err("reserved children retain their identity but cannot be written");
assert!(matches!(error, ObjectJsonError::Reserved));
assert_eq!(bytes, b"{\n \"/Reserved\": ");
}
#[test]
fn writer_key_adds_qpdf_name_slash_for_a_raw_consumer_key() {
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
let mut writer = ObjectJsonWriter::new(&mut output, 0);
writer
.write_key(b"Plain", 2)
.expect("a raw key is normalized before JSON emission");
assert_eq!(bytes, b"\n\"/Plain\": ");
}
#[test]
fn writer_key_uses_qpdf_name_normalization_for_json_v1() {
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
let mut writer = ObjectJsonWriter::new(&mut output, 0);
writer
.write_key(b"Plain", 1)
.expect("JSON v1 keys use qpdf name normalization");
assert_eq!(bytes, b"\n\"/Plain\": ");
}
#[test]
fn json_name_and_string_helpers_cover_empty_and_json_escape_forms() {
assert_eq!(json_normalize_name(&[]), Vec::<u8>::new());
let encoded = json_encode_string(b"\\\"\x08\x0c\n\r\t\x01");
let expected = vec![
b'\\', b'\\', b'\\', b'"', b'\\', b'b', b'\\', b'f', b'\\', b'n', b'\\', b'r', b'\\',
b't', b'\\', b'u', b'0', b'0', b'0', b'1',
];
assert_eq!(encoded, expected);
}
fn flate_stream() -> ObjectHandle {
ObjectHandle::stream(
ObjectHandle::dictionary(vec![
(b"/Length".to_vec(), ObjectHandle::integer(13)),
(
b"/Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
),
(
b"/DecodeParms".to_vec(),
ObjectHandle::dictionary(Vec::new()),
),
]),
Rc::new(vec![
0x78, 0x9c, 0xcb, 0x48, 0xcd, 0xc9, 0xc9, 0x07, 0x00, 0x06, 0x2c, 0x02, 0x15,
]),
)
}
fn write_stream(
stream: &ObjectHandle,
mode: QpdfStreamJsonData,
decode_level: DecodeLevel,
no_data_key: bool,
pipeline: Option<&mut dyn Pipeline>,
data_filename: &str,
) -> (Vec<u8>, DecodeLevel) {
let mut bytes = Vec::new();
let level = {
let mut output = PlString::new("stream-json", None, &mut bytes);
stream
.write_stream_json(
2,
&mut output,
mode,
decode_level,
pipeline,
data_filename,
no_data_key,
0,
)
.expect("stream JSON should be written")
};
(bytes, level)
}
#[test]
fn stream_json_none_preserves_the_original_dictionary_and_omits_data() {
let stream = flate_stream();
let (bytes, level) = write_stream(
&stream,
QpdfStreamJsonData::None,
DecodeLevel::Generalized,
false,
None,
"",
);
assert_eq!(level, DecodeLevel::Generalized);
let json: JsonValue = serde_json::from_slice(&bytes).expect("valid JSON");
assert_eq!(json["dict"]["/Length"], 13);
assert_eq!(json["dict"]["/Filter"], "/FlateDecode");
assert!(json.get("data").is_none());
}
#[test]
fn stream_json_inline_decodes_and_normalizes_the_dictionary() {
let stream = flate_stream();
let (bytes, level) = write_stream(
&stream,
QpdfStreamJsonData::Inline,
DecodeLevel::Generalized,
false,
None,
"",
);
assert_eq!(level, DecodeLevel::Generalized);
let json: JsonValue = serde_json::from_slice(&bytes).expect("valid JSON");
assert_eq!(json["data"], "aGVsbG8=");
assert_eq!(json["dict"], serde_json::json!({}));
}
#[test]
fn stream_json_inline_no_data_key_discards_payload_but_keeps_effective_level() {
let stream = flate_stream();
let (bytes, level) = write_stream(
&stream,
QpdfStreamJsonData::Inline,
DecodeLevel::Generalized,
true,
None,
"",
);
assert_eq!(level, DecodeLevel::Generalized);
let json: JsonValue = serde_json::from_slice(&bytes).expect("valid JSON");
assert!(json.get("data").is_none());
assert_eq!(json["dict"], serde_json::json!({}));
}
#[test]
fn stream_json_file_writes_the_payload_to_the_supplied_pipeline() {
let stream = flate_stream();
let mut side_bytes = Vec::new();
let (bytes, level) = {
let mut side = PlString::new("side-file", None, &mut side_bytes);
write_stream(
&stream,
QpdfStreamJsonData::File,
DecodeLevel::Generalized,
false,
Some(&mut side),
"side-file-7",
)
};
assert_eq!(level, DecodeLevel::Generalized);
assert_eq!(side_bytes, b"hello");
let json: JsonValue = serde_json::from_slice(&bytes).expect("valid JSON");
assert_eq!(json["datafile"], "side-file-7");
assert_eq!(json["dict"], serde_json::json!({}));
}
#[test]
fn stream_json_retries_an_unfilterable_stream_as_raw_data() {
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![
(b"/Length".to_vec(), ObjectHandle::integer(3)),
(
b"/Filter".to_vec(),
ObjectHandle::name(b"UnknownDecode".to_vec()),
),
]),
Rc::new(b"raw".to_vec()),
);
let (bytes, level) = write_stream(
&stream,
QpdfStreamJsonData::Inline,
DecodeLevel::Generalized,
false,
None,
"",
);
assert_eq!(level, DecodeLevel::None);
let json: JsonValue = serde_json::from_slice(&bytes).expect("valid JSON");
assert_eq!(json["data"], "cmF3");
assert_eq!(json["dict"]["/Filter"], "/UnknownDecode");
assert!(json["dict"].get("/Length").is_none());
}
#[test]
fn stream_json_validates_pipeline_and_filename_combinations_before_output() {
let stream = flate_stream();
let mut side_bytes = Vec::new();
let mut side = PlString::new("side-file", None, &mut side_bytes);
let mut output_bytes = Vec::new();
let mut output = PlString::new("stream-json", None, &mut output_bytes);
let error = stream
.write_stream_json(
3,
&mut output,
QpdfStreamJsonData::None,
DecodeLevel::None,
None,
"",
false,
0,
)
.expect_err("only qpdf JSON versions 1 and 2 are supported");
assert!(matches!(error, ObjectJsonError::UnsupportedVersion(3)));
drop(output);
assert!(output_bytes.is_empty());
let mut output = PlString::new("stream-json", None, &mut output_bytes);
let error = stream
.write_stream_json(
2,
&mut output,
QpdfStreamJsonData::None,
DecodeLevel::None,
Some(&mut side),
"",
false,
0,
)
.expect_err("none mode rejects a supplied pipeline");
assert!(
matches!(error, ObjectJsonError::Pdf(message) if message.contains("pipeline should only"))
);
let error = stream
.write_stream_json(
2,
&mut output,
QpdfStreamJsonData::File,
DecodeLevel::None,
None,
"side-file-7",
false,
0,
)
.expect_err("file mode requires a pipeline");
assert!(
matches!(error, ObjectJsonError::Pdf(message) if message.contains("pipeline must be supplied"))
);
let error = stream
.write_stream_json(
2,
&mut output,
QpdfStreamJsonData::File,
DecodeLevel::None,
Some(&mut side),
"",
false,
0,
)
.expect_err("file mode requires a filename");
assert!(
matches!(error, ObjectJsonError::Pdf(message) if message.contains("data_filename must be supplied"))
);
drop(output);
assert!(output_bytes.is_empty());
}
#[test]
fn stream_json_rejects_a_non_stream_handle() {
let scalar = ObjectHandle::integer(7);
let mut bytes = Vec::new();
let mut output = PlString::new("stream-json", None, &mut bytes);
let error = scalar
.write_stream_json(
2,
&mut output,
QpdfStreamJsonData::None,
DecodeLevel::None,
None,
"",
false,
0,
)
.expect_err("stream JSON requires a stream handle");
assert!(matches!(
error,
ObjectJsonError::Pdf(message)
if message == "QPDF_Stream::writeStreamJSON called on a non-stream object"
));
assert!(bytes.is_empty());
}
#[test]
fn stream_json_reports_failure_after_both_source_attempts() {
let resolver = Rc::new(AlwaysFailStreamResolver);
let resolver_handle: Rc<dyn DocumentResolver> = resolver;
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
let mut bytes = Vec::new();
let mut output = PlString::new("stream-json", None, &mut bytes);
let error = stream
.write_stream_json(
2,
&mut output,
QpdfStreamJsonData::Inline,
DecodeLevel::Generalized,
None,
"",
false,
0,
)
.expect_err("a source that fails both attempts must be reported");
assert!(matches!(
error,
ObjectJsonError::Pdf(message) if message == "QPDF_Stream: failed to get stream data"
));
assert_eq!(bytes, b"{");
}
#[test]
fn stream_json_propagates_inline_output_failure() {
let stream = flate_stream();
let mut output = FailOnChunk {
fail_on: br#""data": "#,
bytes: Vec::new(),
};
assert_eq!(output.identifier(), "fail-on-chunk");
let error = stream
.write_stream_json(
2,
&mut output,
QpdfStreamJsonData::Inline,
DecodeLevel::Generalized,
None,
"",
false,
0,
)
.expect_err("the output sink failure must be preserved");
assert!(matches!(
error,
ObjectJsonError::Pipeline(PipelineError::Runtime(message))
if message.as_bytes() == b"json sink failed"
));
assert_eq!(output.bytes, b"{\n ");
}
#[test]
fn object_json_writer_handles_internal_states_and_real_literals() {
for (value, expected) in [
(ObjectValue::Unresolved, ObjectJsonError::Unresolved),
(ObjectValue::Reserved, ObjectJsonError::Reserved),
(ObjectValue::Destroyed, ObjectJsonError::Destroyed),
] {
let handle = ObjectHandle::from_value(value);
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
let error = handle
.write_json(2, &mut output, false, 0)
.expect_err("internal qpdf states are not JSON values");
assert!(matches!(
(error, expected),
(ObjectJsonError::Unresolved, ObjectJsonError::Unresolved)
| (ObjectJsonError::Reserved, ObjectJsonError::Reserved)
| (ObjectJsonError::Destroyed, ObjectJsonError::Destroyed)
));
}
for (handle, expected) in [
(
ObjectHandle::real_literal(1.2, b"1.2".to_vec()),
b"1.2".as_slice(),
),
(
ObjectHandle::real_literal(0.4, b"not-a-real".to_vec()),
b"0.4".as_slice(),
),
] {
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
handle
.write_json(2, &mut output, false, 0)
.expect("finite real literals serialize as JSON numbers");
assert_eq!(bytes, expected);
}
for (handle, expected) in [
(
ObjectHandle::real_literal(-0.4, b"-.4".to_vec()),
b"-0.4".as_slice(),
),
(
ObjectHandle::real_literal(0.4, b".4".to_vec()),
b"0.4".as_slice(),
),
] {
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
handle
.write_json(2, &mut output, false, 0)
.expect("leading-dot real literals serialize as JSON numbers");
assert_eq!(bytes, expected);
}
for (bytes_value, expected) in [
(b"\xff\xfea\0".to_vec(), b"\"u:a\"".as_slice()),
(b"\xef\xbb\xbfbom".to_vec(), b"\"u:bom\"".as_slice()),
(b"a\"b".to_vec(), b"\"u:a\\\"b\"".as_slice()),
] {
let handle = ObjectHandle::string(bytes_value);
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
handle
.write_json(2, &mut output, false, 0)
.expect("JSON string variant should serialize");
assert_eq!(bytes, expected);
}
let raw = ObjectHandle::new_indirect_unresolved_qpdf_obj_gen_with_identity(
QpdfObjGen::new(-1, -2),
NO_PARSED_OFFSET,
None,
None,
);
let mut bytes = Vec::new();
let mut output = PlString::new("object-handle-json", None, &mut bytes);
raw.write_json(2, &mut output, false, 0)
.expect("raw qpdf identity should serialize");
assert_eq!(bytes, b"\"-1 -2 R\"");
let unresolved = ObjectHandle::new_indirect_unresolved(ObjectRef::new(11, 0), -1);
let mut unresolved_bytes = Vec::new();
let mut unresolved_output =
PlString::new("object-handle-json", None, &mut unresolved_bytes);
let error = unresolved
.write_json(2, &mut unresolved_output, true, 0)
.expect_err("an indirect value without a resolver is uninitialized");
assert!(matches!(error, ObjectJsonError::Uninitialized));
let dictionary_with_unresolved_child = ObjectHandle::dictionary(vec![(
b"/Unresolved".to_vec(),
ObjectHandle::new_indirect_unresolved(ObjectRef::new(12, 0), -1),
)]);
let mut child_error_bytes = Vec::new();
let mut child_error_output =
PlString::new("object-handle-json", None, &mut child_error_bytes);
let error = dictionary_with_unresolved_child
.write_json(2, &mut child_error_output, false, 0)
.expect_err("a resolver-less unresolved dictionary child is uninitialized");
assert!(matches!(error, ObjectJsonError::Uninitialized));
let mut key_output_bytes = Vec::new();
let mut key_output = PlString::new("object-handle-json", None, &mut key_output_bytes);
let mut key_writer = ObjectJsonWriter::new(&mut key_output, 0);
key_writer
.write_key(b"/\xff", 2)
.expect("invalid slash-prefixed name key should serialize");
key_writer
.write_key(b"\xff", 2)
.expect("invalid slashless name key should serialize");
key_writer
.write_name_raw(b"/\xff", 2)
.expect("invalid raw name should serialize");
assert!(key_output_bytes.windows(3).any(|part| part == b"n:/"));
let scalar = ObjectHandle::integer(1);
let mut current_key = LiveDictionaryKeyBuffer::default();
let mut next_key = LiveDictionaryKeyBuffer::default();
assert!(scalar
.next_dictionary_entry_for_live_write(None, &mut next_key)
.is_none());
assert!(scalar
.next_dictionary_entry_for_live_walk(None, &mut current_key)
.is_none());
let long_key = [b'/'; LIVE_DICTIONARY_KEY_INLINE_CAPACITY + 1];
let dictionary =
ObjectHandle::dictionary(vec![(long_key.to_vec(), ObjectHandle::integer(2))]);
let child = dictionary
.next_dictionary_entry_for_live_write(None, &mut current_key)
.expect("long dictionary key child");
assert_eq!(current_key.as_slice(), long_key);
assert_eq!(child.as_integer(), Some(2));
let child = dictionary
.next_dictionary_entry_for_live_walk(None, &mut next_key)
.expect("long dictionary key child for writer walk");
assert_eq!(next_key.as_slice(), long_key);
assert_eq!(child.as_integer(), Some(2));
}
}
// `ObjectHandle::shallow_copy`'s per-variant dispatch: an Array/Dictionary
// child is recursively shallow-copied through `shallow_copy_child` (which
// re-enters `ObjectHandle::shallow_copy`, the recursion hub routed through
// `direct_graph_walk_hub` — the same hub-per-call shape as
// `unparse_resolved_into`/`unparse_resolved_child` above), mirroring
// `QPDF_Dictionary::copy`/`QPDF_Array::copy`, which call `shallowCopy` on
// each direct child and keep an indirect one shared. A `Stream` has no
// copy at all: `QPDF_Stream::copy` (`libqpdf/QPDF_Stream.cc:140-145`)
// throws, and it throws from here too — for this value itself and, through
// the recursion, for any direct stream descendant. Every other variant is
// cloned as-is with no further recursion.
fn shallow_copy_value(value: &ObjectValue) -> Result<ObjectValue> {
Ok(match value {
ObjectValue::Unresolved => return Err(unresolved_copy_error()),
ObjectValue::Reserved => ObjectValue::Reserved,
ObjectValue::Destroyed => return Err(destroyed_copy_error()),
ObjectValue::Array(items) => ObjectValue::Array(
items
.iter()
.map(shallow_copy_child)
.collect::<Result<Vec<_>>>()?,
),
ObjectValue::Dictionary(entries) => ObjectValue::Dictionary(
entries
.iter()
.map(|(k, v)| Ok((k.clone(), shallow_copy_child(v)?)))
.collect::<Result<std::collections::BTreeMap<_, _>>>()?,
),
ObjectValue::Stream(_) => {
return Err(Error::System("stream objects cannot be cloned".to_string()))
}
other => other.clone(),
})
}
fn shallow_copy_child(child: &ObjectHandle) -> Result<ObjectHandle> {
if child.is_indirect() {
Ok(child.clone())
} else {
child.shallow_copy()
}
}
// `ObjectHandle::unsafe_shallow_copy`'s per-variant dispatch mirrors
// `QPDFObject::copy(true)`: container values clone only their immediate
// handle collection, so direct descendants (including destroyed ones) remain
// the same object handles. Streams and terminal error sentinels retain their
// qpdf copy behavior at this boundary.
fn unsafe_shallow_copy_value(value: &ObjectValue) -> Result<ObjectValue> {
Ok(match value {
ObjectValue::Unresolved => return Err(unresolved_copy_error()),
ObjectValue::Destroyed => return Err(destroyed_copy_error()),
ObjectValue::Stream(_) => {
return Err(Error::System("stream objects cannot be cloned".to_string()))
}
ObjectValue::Array(items) => ObjectValue::Array(items.clone()),
ObjectValue::Dictionary(entries) => ObjectValue::Dictionary(entries.clone()),
other => other.clone(),
})
}
// `ObjectHandle::merge_resources`'s per-rtype dictionary merge (the
// `this_val.isDictionary() && other_val.isDictionary()` arm of
// `QPDFObjectHandle::mergeResources`, `libqpdf/QPDFObjectHandle.cc:1095-1129`).
// `this_val` is already the privatized (non-indirect) sub-dictionary by the
// time this is called.
fn merge_resource_subdict(
this_val: &ObjectHandle,
other_val: &ObjectHandle,
rtype: &[u8],
mut conflicts: Option<&mut ResourceConflicts>,
) -> Result<()> {
let mut og_to_name: Option<std::collections::HashMap<QpdfObjGen, Vec<u8>>> = None;
let mut rnames: std::collections::BTreeSet<Vec<u8>> = std::collections::BTreeSet::new();
let mut min_suffix: usize = 1;
let Some(other_sub_entries) = other_val.as_dictionary() else {
return Ok(()); // cov:ignore: caller already confirmed other_val.as_dictionary().is_some()
};
for (key, rval) in other_sub_entries {
if !this_val.try_has_key(&key)? {
let installed = if rval.is_indirect() {
rval
} else {
rval.shallow_copy()?
};
this_val.replace_key(&key, installed)?;
continue;
}
let Some(conflicts_map) = conflicts.as_deref_mut() else {
continue;
};
if og_to_name.is_none() {
og_to_name = Some(build_og_to_name(this_val));
rnames = try_get_resource_names(this_val)?;
}
let reused = rval.qpdf_obj_gen().and_then(|object_gen| {
og_to_name
.as_ref()
.and_then(|m| m.get(&object_gen).cloned())
});
if let Some(existing_key) = reused {
if existing_key != key {
conflicts_map
.entry(rtype.to_vec())
.or_default()
.insert(key, existing_key);
}
} else {
let new_key = unique_resource_name(&key, &mut min_suffix, &rnames)?;
conflicts_map
.entry(rtype.to_vec())
.or_default()
.insert(key, new_key.clone());
this_val.replace_key(&new_key, rval)?;
}
}
Ok(())
}
// `ObjectHandle::merge_resources`'s per-rtype array merge (the
// `this_val.isArray() && other_val.isArray()` arm,
// `libqpdf/QPDFObjectHandle.cc:1130-1146`): union `other_val`'s scalar
// items into `this_val` by unparsed text, appending only what is not
// already present.
fn merge_resource_array(this_val: &ObjectHandle, other_val: &ObjectHandle) -> Result<()> {
let Some(other_items) = other_val.as_array() else {
return Ok(()); // cov:ignore: caller already confirmed other_val.as_array().is_some()
};
let mut scalars = std::collections::BTreeSet::new();
for item in this_val.as_array().into_iter().flatten() {
if is_scalar(&item)? {
scalars.insert(item.unparse());
}
}
for item in other_items {
if !is_scalar(&item)? {
continue;
}
let text = item.unparse();
if scalars.insert(text) {
append_array_item(this_val, item);
}
}
Ok(())
}
fn append_array_item(handle: &ObjectHandle, item: ObjectHandle) {
let _ = handle.with_value_mut(|v| {
if let Some(ObjectValue::Array(items)) = v {
items.push(item);
true
} else {
false // cov:ignore: merge_resource_array only calls after confirming this_val is an array
}
});
}
// Mirrors `isScalar()` (`libqpdf/QPDFObjectHandle.cc:449-452`): dereference
// first, then test bool, integer, name, null, real, or string. qpdf performs
// this dereference for every array item rather than relying on a caller-side
// resolution precondition.
pub(crate) fn is_scalar(handle: &ObjectHandle) -> Result<bool> {
handle.try_dereference()?;
Ok(handle.as_boolean().is_some()
|| handle.as_integer().is_some()
|| handle.as_name().is_some()
|| handle.is_null()
|| handle.as_real().is_some()
|| handle.as_string().is_some())
}
// Mirrors `mergeResources`'s local `make_og_to_name` lambda
// (`libqpdf/QPDFObjectHandle.cc:1071-1078`): every currently-indirect
// entry in `dict`, keyed by object identity.
fn build_og_to_name(dict: &ObjectHandle) -> std::collections::HashMap<QpdfObjGen, Vec<u8>> {
let mut map = std::collections::HashMap::new();
if let Some(entries) = dict.as_dictionary() {
for (key, value) in entries {
if value.is_indirect() {
if let Some(object_gen) = value.qpdf_obj_gen() {
map.insert(object_gen, key);
}
}
}
} // cov:ignore: control-flow marker — llvm-cov instrumentation artifact; the body above is exercised by merge_resources_reuses_an_existing_key_for_the_same_indirect_object
map
}
// Mirrors `getResourceNames` (`libqpdf/QPDFObjectHandle.cc:1156-1170`,
// `include/qpdf/QPDFObjectHandle.hh:831-835`): the union of every key
// belonging to a dictionary-valued entry of `dict` -- i.e. `dict`'s own
// *grandchildren's* keys, not `dict`'s own keys. See `merge_resources`'s
// own doc comment for why this is the correct level to port here despite
// looking mismatched against its call site. The receiver and every value are
// dereferenced before their dictionary shape is inspected, as qpdf does.
fn try_get_resource_names(dict: &ObjectHandle) -> Result<std::collections::BTreeSet<Vec<u8>>> {
dict.try_dereference()?;
let mut result = std::collections::BTreeSet::new();
let Some(entries) = dict.as_dictionary() else {
return Ok(result);
};
for (_, value) in entries {
value.try_dereference()?;
if value.try_is_dictionary()? {
result.extend(value.try_get_keys()?);
}
}
Ok(result)
}
fn object_generation_description(handle: &ObjectHandle) -> String {
handle
.qpdf_obj_gen()
.filter(|object_gen| object_gen.is_indirect())
.map(|object_gen| format!("{} {}", object_gen.get_obj(), object_gen.get_gen()))
.unwrap_or_else(|| "0 0".to_owned())
}
// Mirrors `getUniqueResourceName` (`libqpdf/QPDFObjectHandle.cc:1175-1192`):
// append a decimal suffix (starting at `*min_suffix`) to `key` + `"_"`
// until the result is absent from `names`, leaving `*min_suffix` at the
// value just used (not incremented past it -- a caller minting several
// names in the same sub-dictionary reuses the search position, matching
// qpdf's own "used, not next" contract).
fn unique_resource_name(
key: &[u8],
min_suffix: &mut usize,
names: &std::collections::BTreeSet<Vec<u8>>,
) -> Result<Vec<u8>> {
let mut prefix = key.to_vec();
prefix.push(b'_');
let max_suffix = *min_suffix + names.len();
while *min_suffix <= max_suffix {
let mut candidate = prefix.clone();
candidate.extend(min_suffix.to_string().into_bytes());
if !names.contains(&candidate) {
return Ok(candidate);
}
*min_suffix += 1;
}
// Unreachable per qpdf's own invariant: this loop tests strictly more
// candidates (names.len() + 1) than there are names to conflict with,
// so by pigeonhole one must be free. qpdf itself treats reaching this
// point as a coding error and throws std::logic_error
// (`libqpdf/QPDFObjectHandle.cc:1188-1191`); this maps to `Error::Internal`
// like every other logic_error in this file.
// cov:ignore-start: unreachable by the pigeonhole argument above for any input
Err(Error::Internal(
"unable to find unconflicting resource name".to_owned(),
))
// cov:ignore-end
}
#[cfg(test)]
mod content_shape_internal_tests {
use super::*;
#[test]
fn supplied_resource_names_do_not_resolve_the_receiver_like_qpdf() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(99, 0), 0);
let names = std::collections::BTreeSet::from([b"/F0".to_vec()]);
let mut min_suffix = 0;
assert_eq!(
handle
.get_unique_resource_name(b"/F", &mut min_suffix, Some(&names))
.unwrap(),
b"/F1"
);
}
#[test]
fn all_description_separates_multiple_streams_like_qpdf() {
let page = ObjectHandle::dictionary(vec![(
b"/Contents".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::stream(ObjectHandle::dictionary(Vec::new()), Rc::new(Vec::new())),
ObjectHandle::stream(ObjectHandle::dictionary(Vec::new()), Rc::new(Vec::new())),
]),
)]);
let (streams, all_description) = page.page_contents_with_description().unwrap();
assert_eq!(streams.len(), 2);
assert_eq!(all_description, "page object 0 0 stream 0 0, stream 0 0");
}
}
#[cfg(test)]
pub(crate) mod identity_tests {
use super::*;
struct RecordingResolver {
calls: ResolutionLog,
value: ObjectValue,
}
/// Every `resolve_indirect` a [`RecordingResolver`] performed, in order.
///
/// Shared with the caller by [`logged_resolver_bearing_handle`] so a test
/// can assert a *negative*: that a position was never resolved at all.
/// `ObjectHandle::is_resolved` is not a substitute — a resolver that
/// errored would leave the handle unresolved despite having been called.
pub(crate) type ResolutionLog = Rc<RefCell<Vec<ObjectRef>>>;
impl RecordingResolver {
/// Install `value` instead of the default one-key dictionary, so a
/// test can exercise a resolving accessor for a non-dictionary shape.
///
/// One instance installs the *same* child handles on every resolution:
/// cloning an `ObjectValue` container clones child `Rc`s rather than
/// the subtree (see that enum's own doc). Resolving two handles through
/// a single resolver therefore leaves their children `ptr_eq`, which no
/// current test wants — give each such test its own resolver.
fn installing(value: ObjectValue) -> Self {
Self::logging_into(Rc::new(RefCell::new(Vec::new())), value)
}
/// [`Self::installing`] with the call log owned by the caller instead.
fn logging_into(calls: ResolutionLog, value: ObjectValue) -> Self {
Self { calls, value }
}
}
impl Default for RecordingResolver {
fn default() -> Self {
Self::installing(ObjectValue::Dictionary(
[(b"A".to_vec(), ObjectHandle::integer(1))]
.into_iter()
.collect(),
))
}
}
impl DocumentResolver for RecordingResolver {
fn resolve_indirect(
&self,
object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
self.calls.borrow_mut().push(object_ref);
handle.set_resolved(self.value.clone());
Ok(())
}
}
#[test]
fn source_extents_defaults_to_qpdf_unset_for_context_only_resolvers() {
assert_eq!(SourceExtents::default(), SourceExtents::UNSET);
assert!(!ObjectHandle::integer(1).has_newer_cached_generation());
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
assert!(!resolver.has_newer_cached_generation(QpdfObjGen::new(1, 0)));
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(1, 0),
Rc::downgrade(&resolver),
);
assert_eq!(handle.end_offsets(), (NO_PARSED_OFFSET, NO_PARSED_OFFSET));
handle.set_end_offsets(12, 15);
assert_eq!(handle.end_offsets(), (NO_PARSED_OFFSET, NO_PARSED_OFFSET));
}
#[test]
fn object_number_zero_is_not_indirect_but_settles_as_null() {
let calls: ResolutionLog = Rc::new(RefCell::new(Vec::new()));
let value = ObjectValue::Integer(7);
let resolver: Rc<dyn DocumentResolver> =
Rc::new(RecordingResolver::logging_into(Rc::clone(&calls), value));
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(0, 17),
Rc::downgrade(&resolver),
);
// `isIndirect()` is `obj != 0` (`include/qpdf/QPDFObjGen.hh:78-81`), so
// object zero is not an indirect reference and has no `ObjectRef`.
assert!(!handle.is_indirect());
assert_eq!(handle.object_ref(), None);
// It still settles, as qpdf's null fallback: the identity has no xref
// row, so `QPDF::resolve` caches `QPDF_Null` for it
// (`libqpdf/QPDF.cc:1745-1748`). The default `resolve_qpdf_obj_gen`
// takes that path directly, so the recording resolver is never reached.
// `is_resolved` / `is_null` read the slot without driving resolution,
// so dereference explicitly first — that is the step qpdf performs on
// first access through `QPDFObjectHandle::dereference`.
handle.try_dereference().expect("object zero settles");
assert!(handle.is_resolved());
assert!(handle.is_null());
assert!(calls.borrow().is_empty());
}
/// Resolves a stream value but intentionally has no byte source. This
/// exercises `DocumentResolver::pipe_stream_data`'s default boundary: a
/// resolver may resolve objects without also being a file-backed reader.
struct NoStreamSourceResolver;
impl DocumentResolver for NoStreamSourceResolver {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
handle.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 3,
})));
Ok(())
}
}
struct NonStreamDestinationResolver;
impl DocumentResolver for NonStreamDestinationResolver {
fn resolve_indirect(
&self,
object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
NoStreamSourceResolver.resolve_indirect(object_ref, handle)
}
fn new_stream(&self) -> crate::Result<ObjectHandle> {
Ok(ObjectHandle::integer(1))
}
}
/// An unresolved indirect handle whose resolver installs `value`.
///
/// `pub(crate)` so `stream_filter.rs`'s handle-shape reader tests can
/// build an indirect child without a second harness; the returned
/// resolver is erased, so `RecordingResolver` itself stays private here.
///
/// **The caller must keep the returned resolver alive**, and bind it to a
/// named `_resolver` rather than to `_` — the latter drops it immediately.
/// The handle holds only a `Weak`, so a dropped resolver turns every
/// accessor into `Error::Internal("object 20 0 belongs to a dropped
/// PDF")`: a test expecting a resolved value then fails confusingly, and
/// one expecting an error passes for the wrong reason. Dropping it
/// *deliberately* is how to build a dropped-document handle, as
/// `handle_reader_surfaces_a_dropped_document_from_every_child_position`
/// does.
pub(crate) fn resolver_bearing_handle(
value: ObjectValue,
) -> (ObjectHandle, Rc<dyn DocumentResolver>) {
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::installing(value));
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver),
);
// The resolver is returned so the caller keeps it alive: the handle
// holds only a `Weak`, and dropping it here would turn every accessor
// into the dropped-document error instead.
(handle, resolver)
}
#[test]
fn raw_stream_data_requires_a_file_backed_resolver_for_original_bytes() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(NoStreamSourceResolver);
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver),
);
stream.set_parsed_offset_if_unset(9);
let error = stream
.get_raw_stream_data()
.expect_err("an object-only resolver has no original stream source");
assert!(matches!(error, Error::Internal(message)
if message == "stream data requested from a resolver without a stream source"));
}
#[test]
fn stream_copy_resolver_defaults_report_missing_document_operations() {
let resolver = NoStreamSourceResolver;
assert!(matches!(
resolver.new_stream(),
Err(Error::Internal(message))
if message == "stream creation requested from a resolver without a document"
));
assert!(matches!(
resolver.copy_stream_data(&ObjectHandle::null(), &ObjectHandle::null()),
Err(Error::Internal(message))
if message == "stream data copy requested from a resolver without a document"
));
assert!(matches!(
resolver.original_stream_data_provider(&ObjectHandle::null(), &ObjectHandle::null()),
Err(Error::Internal(message))
if message == "original stream data provider requested from a resolver without a document"
));
assert!(!ObjectHandle::integer(1).has_stream_data_provider());
assert_eq!(ObjectHandle::integer(1).stream_source_length(), None);
assert!(!resolver.immediate_copy_from());
}
#[test]
fn stream_copy_destination_defaults_delegate_and_warning_defaults_fail() {
let resolver = NoStreamSourceResolver;
let destination: Rc<dyn DocumentResolver> = Rc::new(NoStreamSourceResolver);
let destination_resolver = Rc::downgrade(&destination);
assert!(matches!(
resolver.original_stream_data_provider_for_destination(
&ObjectHandle::null(),
&ObjectHandle::null(),
destination_resolver,
),
Err(Error::Internal(message))
if message == "original stream data provider requested from a resolver without a document"
));
assert!(matches!(
resolver.warn_stream_data(QpdfExc::new(
QpdfErrorCode::DamagedPdf,
b"",
b"",
17,
b"late warning",
)),
Err(Error::Internal(message))
if message == "stream data warning requested from a resolver without a document"
));
}
#[test]
fn copy_stream_rejects_a_non_stream_created_by_its_resolver() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(NonStreamDestinationResolver);
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver),
);
let error = stream
.copy_stream()
.expect_err("resolver returned a non-stream destination");
assert!(matches!(error, Error::Internal(message)
if message == "copyStream created a non-stream destination"));
}
/// [`resolver_bearing_handle`] plus the resolver's [`ResolutionLog`].
///
/// For the one question the plain helper cannot answer: whether a child
/// position was resolved *at all*. The same "keep the resolver alive"
/// rule applies — an empty log proves nothing if the resolver was
/// dropped, since a severed handle never reaches `resolve_indirect`
/// either.
pub(crate) fn logged_resolver_bearing_handle(
value: ObjectValue,
) -> (ObjectHandle, Rc<dyn DocumentResolver>, ResolutionLog) {
let calls: ResolutionLog = Rc::new(RefCell::new(Vec::new()));
let resolver: Rc<dyn DocumentResolver> =
Rc::new(RecordingResolver::logging_into(Rc::clone(&calls), value));
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver),
);
(handle, resolver, calls)
}
struct MissingResolver;
impl DocumentResolver for MissingResolver {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
handle.set_resolved(ObjectValue::Null);
Ok(())
}
}
struct ErrorResolver;
impl DocumentResolver for ErrorResolver {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
_handle: &ObjectHandle,
) -> crate::Result<()> {
Err(Error::System("resolver failed".to_string()))
}
}
/// Records a resolution attempt before returning its configured error.
///
/// Unlike [`ErrorResolver`], each instance has an independently chosen
/// message and externally visible call log. This lets an enumeration test
/// distinguish qpdf's lexical fail-fast traversal from a reversed walk
/// that happens to return an error of the same variant.
struct LoggedErrorResolver {
calls: ResolutionLog,
message: String,
}
impl DocumentResolver for LoggedErrorResolver {
fn resolve_indirect(
&self,
object_ref: ObjectRef,
_handle: &ObjectHandle,
) -> crate::Result<()> {
self.calls.borrow_mut().push(object_ref);
Err(Error::System(self.message.clone()))
}
}
/// An unresolved indirect handle whose resolver always errors, mirroring
/// [`resolver_bearing_handle`]'s own doc but for a position that must
/// never be resolved at all rather than one that resolves to a
/// particular value -- a test asserting some code path does not resolve
/// a value it does not need can build one of these and assert success:
/// actually resolving it here would surface as an error instead.
///
/// `pub(crate)` for the same reason as [`resolver_bearing_handle`]: a
/// harness other test modules in this file need, not just this one.
/// Same "keep the resolver alive" rule applies -- see that function's
/// own doc.
pub(crate) fn error_resolving_handle(
object_ref: ObjectRef,
) -> (ObjectHandle, Rc<dyn DocumentResolver>) {
let resolver: Rc<dyn DocumentResolver> = Rc::new(ErrorResolver);
let handle = ObjectHandle::new_indirect_with_resolver(object_ref, Rc::downgrade(&resolver));
(handle, resolver)
}
fn logged_error_resolving_handle(
object_ref: ObjectRef,
message: impl Into<String>,
) -> (ObjectHandle, Rc<dyn DocumentResolver>, ResolutionLog) {
let calls: ResolutionLog = Rc::new(RefCell::new(Vec::new()));
let resolver: Rc<dyn DocumentResolver> = Rc::new(LoggedErrorResolver {
calls: Rc::clone(&calls),
message: message.into(),
});
let handle = ObjectHandle::new_indirect_with_resolver(object_ref, Rc::downgrade(&resolver));
(handle, resolver, calls)
}
#[test]
fn try_get_key_resolves_the_same_indirect_slot_once() {
let resolver = Rc::new(RecordingResolver::default());
let erased: Rc<dyn DocumentResolver> = resolver.clone();
let handle =
ObjectHandle::new_indirect_with_resolver(ObjectRef::new(7, 0), Rc::downgrade(&erased));
let clone = handle.clone();
assert_eq!(handle.try_get_key(b"/A").unwrap().as_integer(), Some(1));
assert!(clone.try_has_key(b"/A").unwrap());
assert_eq!(*resolver.calls.borrow(), vec![ObjectRef::new(7, 0)]);
assert!(handle.ptr_eq(&clone));
assert_eq!(handle.object_ref(), Some(ObjectRef::new(7, 0)));
}
#[test]
fn identity_key_matches_qpdf_object_sameness_without_structural_equality() {
let original =
ObjectHandle::dictionary(vec![(b"Value".to_vec(), ObjectHandle::integer(1))]);
let alias = original.clone();
let distinct =
ObjectHandle::dictionary(vec![(b"Value".to_vec(), ObjectHandle::integer(1))]);
#[allow(
clippy::mutable_key_type,
reason = "identity key compares only Rc pointer identity and retains the slot deliberately"
)]
let mut seen = std::collections::HashSet::new();
assert!(seen.insert(original.identity_key()));
assert!(!seen.insert(alias.identity_key()));
assert!(seen.insert(distinct.identity_key()));
}
#[test]
fn try_dereference_reports_a_dropped_document_without_reconnecting() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(8, 0),
Rc::downgrade(&resolver),
);
drop(resolver);
let error = handle.try_dereference().unwrap_err();
assert_eq!(error.to_string(), "object 8 0 belongs to a dropped PDF");
assert!(!handle.is_resolved());
}
/// A handle needs its owning document's identity *and* that document's
/// resolver at once: `Pdf::get_object_handle` hands out one handle that
/// must answer both questions.
///
/// The identity is not decorative. The slot's single active
/// `pdf_unique_id` drives [`ObjectHandle::belongs_to_pdf`], while live
/// immediate-parent edges drive
/// [`ObjectHandle::containing_object_refs_for_pdf`] — respectively the
/// document-ownership check and current owner lookup in `filespec_helper`
/// and `embedded_files`. Measured against the current tree, not predicted:
/// this is now the constructor `Pdf::get_object_handle` uses — the
/// identity-only `new_indirect_unresolved_for_pdf` was deleted when it
/// switched over — and patching it to discard its `pdf_unique_id`
/// argument fails 62 tests in `cargo test -p flpdf --lib`, not just this
/// one.
///
/// Note this is *not* what `Pdf::is_canonical_object_handle` compares on:
/// that one looks the ref up in `handle_registry` and compares `Rc`
/// pointers, never touching `pdf_unique_id`.
#[test]
fn an_indirect_slot_carries_both_its_pdf_identity_and_its_resolver() {
const PDF_ID: u64 = 4242;
let object_ref = ObjectRef::new(13, 0);
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
let handle = ObjectHandle::new_indirect_for_pdf_with_resolver(
object_ref,
NO_PARSED_OFFSET,
PDF_ID,
Rc::downgrade(&resolver),
);
// Identity: preserved, and specific to this document rather than
// matching any id put to it.
assert!(handle.belongs_to_pdf(PDF_ID));
assert!(!handle.belongs_to_pdf(PDF_ID + 1));
// Resolver: reachable through `try_dereference`'s real path — upgrade
// the `Weak`, call `resolve_indirect` — not merely stored in the slot.
// Without it this is the dropped-document error instead.
handle.try_dereference().unwrap();
assert!(handle.is_resolved());
// Both at once. The child's identity and live root edge are written
// by `set_resolved`, so both can only be present if the document
// identity survived *into* the resolution the resolver drove.
let child = handle.try_get_key(b"/A").unwrap();
assert_eq!(child.as_integer(), Some(1));
assert_eq!(
child.containing_object_refs_for_pdf(PDF_ID),
vec![object_ref]
);
assert!(child.containing_object_refs_for_pdf(PDF_ID + 1).is_empty());
}
#[test]
fn replacement_validation_and_value_assignment_have_separate_contracts() {
let target = ObjectHandle::new_indirect_unresolved(ObjectRef::new(30, 0), -1);
let direct = ObjectHandle::integer(1);
direct.assign_value_state(&direct);
let indirect = ObjectHandle::new_indirect_unresolved(ObjectRef::new(31, 0), -1);
let error = indirect.validate_replacement_source().unwrap_err();
assert_eq!(
error.to_string(),
"unsupported PDF feature: replacement ObjectHandle must be direct"
);
let destroyed = ObjectHandle::integer(2);
let destroyed_resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
destroyed.promote_to_indirect(
ObjectRef::new(32, 0),
4242,
Rc::downgrade(&destroyed_resolver),
);
destroyed.disconnect_and_destroy();
target.assign_value_state(&destroyed);
assert!(target.is_resolved());
assert_eq!(target.type_code().expect("destroyed type code"), 14);
}
#[test]
fn assigning_value_state_shares_mutations_without_merging_slot_identity() {
let source = ObjectHandle::dictionary(vec![(b"Value".to_vec(), ObjectHandle::integer(7))]);
let target = ObjectHandle::dictionary(vec![]);
target.assign_value_state(&source);
assert!(!target.is_same_object_as(&source));
source
.replace_key(b"/Value", ObjectHandle::integer(8))
.expect("dictionary replacement");
assert_eq!(target.try_get_key(b"/Value").unwrap().as_integer(), Some(8));
}
#[test]
fn swapping_value_state_moves_values_without_moving_object_references() {
let left_ref = ObjectRef::new(40, 0);
let right_ref = ObjectRef::new(41, 0);
let left = ObjectHandle::new_indirect_unresolved(left_ref, NO_PARSED_OFFSET);
let right = ObjectHandle::new_indirect_unresolved(right_ref, NO_PARSED_OFFSET);
left.set_resolved(ObjectValue::Dictionary(
[(b"Value".to_vec(), ObjectHandle::integer(7))]
.into_iter()
.collect(),
));
right.set_resolved(ObjectValue::Dictionary(
[(b"Value".to_vec(), ObjectHandle::integer(8))]
.into_iter()
.collect(),
));
left.swap_value_state_with(&right);
assert_eq!(left.object_ref(), Some(left_ref));
assert_eq!(right.object_ref(), Some(right_ref));
assert_eq!(left.try_get_key(b"/Value").unwrap().as_integer(), Some(8));
assert_eq!(right.try_get_key(b"/Value").unwrap().as_integer(), Some(7));
}
#[test]
fn removing_a_direct_handle_is_a_no_op() {
let direct = ObjectHandle::integer(1);
direct.remove_from_document();
assert_eq!(direct.as_integer(), Some(1));
}
#[test]
fn exclusive_pdf_ownership_walk_handles_cycles_and_indirect_mismatch() {
let first = ObjectHandle::dictionary(vec![]);
let second = ObjectHandle::dictionary(vec![]);
first.replace_key(b"/Second", second.clone()).unwrap();
second.replace_key(b"/First", first.clone()).unwrap();
assert!(first.belongs_exclusively_to_pdf(4242));
let foreign_resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
let foreign_indirect = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(33, 0),
NO_PARSED_OFFSET,
4243,
Rc::downgrade(&foreign_resolver),
);
assert!(!foreign_indirect.belongs_exclusively_to_pdf(4242));
let promoted_foreign = ObjectHandle::integer(3);
promoted_foreign.promote_to_indirect(
ObjectRef::new(34, 0),
4243,
Rc::downgrade(&foreign_resolver),
);
assert_eq!(promoted_foreign.object_ref(), Some(ObjectRef::new(34, 0)));
assert_eq!(promoted_foreign.owning_pdf_unique_id(), Some(4243));
assert!(!promoted_foreign.belongs_exclusively_to_pdf(4242));
}
#[test]
fn exclusive_pdf_ownership_walk_checks_all_indirect_children() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
let same_document = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(35, 0),
NO_PARSED_OFFSET,
4242,
Rc::downgrade(&resolver),
);
let foreign_document = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(36, 0),
NO_PARSED_OFFSET,
4243,
Rc::downgrade(&resolver),
);
// The LIFO walk visits the same-document child first in this order;
// it must still inspect the foreign sibling before accepting the
// container.
let same_first = ObjectHandle::array(vec![foreign_document.clone(), same_document.clone()]);
assert!(!same_first.belongs_exclusively_to_pdf(4242));
let foreign_first = ObjectHandle::array(vec![same_document, foreign_document]);
assert!(!foreign_first.belongs_exclusively_to_pdf(4242));
}
#[test]
fn removing_shared_canonical_state_rebinds_only_the_canonical_slot() {
let target = ObjectHandle::new_indirect_unresolved(ObjectRef::new(37, 0), -1);
let replacement =
ObjectHandle::dictionary(vec![(b"Value".to_vec(), ObjectHandle::integer(7))]);
replacement.0.borrow().shared.borrow_mut().identity =
target.0.borrow().shared.borrow().identity.clone();
target.assign_value_state(&replacement);
let allocations_before = super::detached_state_rebind_allocations_for_test();
target.remove_from_document();
assert_eq!(
super::detached_state_rebind_allocations_for_test(),
allocations_before + 1,
"shared value state must retain the detached-state fallback"
);
assert!(target.is_direct());
assert!(target.try_is_null().unwrap());
assert_eq!(target.object_ref(), None);
assert_eq!(
replacement.try_get_key(b"/Value").unwrap().as_integer(),
Some(7)
);
replacement
.replace_key(b"/Value", ObjectHandle::integer(9))
.unwrap();
assert_eq!(
replacement.try_get_key(b"/Value").unwrap().as_integer(),
Some(9)
);
}
#[test]
fn disconnecting_shared_canonical_state_rebinds_only_the_canonical_slot() {
let target = ObjectHandle::new_indirect_unresolved(ObjectRef::new(38, 0), -1);
let replacement =
ObjectHandle::dictionary(vec![(b"Value".to_vec(), ObjectHandle::integer(7))]);
replacement.0.borrow().shared.borrow_mut().identity =
target.0.borrow().shared.borrow().identity.clone();
target.assign_value_state(&replacement);
let allocations_before = super::detached_state_rebind_allocations_for_test();
target.disconnect_and_destroy();
assert_eq!(
super::detached_state_rebind_allocations_for_test(),
allocations_before + 1,
"shared value state must retain the detached-state fallback"
);
assert_eq!(target.type_code().expect("type code"), 14);
assert!(!replacement.try_is_null().unwrap());
assert_eq!(
replacement.try_get_key(b"/Value").unwrap().as_integer(),
Some(7)
);
}
#[test]
fn repeated_destroy_reuses_the_same_unique_value_state_boundary() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(50, 0), -1);
handle.set_resolved(ObjectValue::Integer(9));
let allocations_before = super::detached_state_rebind_allocations_for_test();
handle.disconnect_and_destroy();
handle.disconnect_and_destroy();
assert_eq!(
super::detached_state_rebind_allocations_for_test(),
allocations_before,
"idempotent destruction must not reintroduce detached-state allocation"
);
assert_eq!(handle.type_code().expect("destroyed type code"), 14);
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn shared_state_prunes_dropped_owners() {
let target = ObjectHandle::new_indirect_unresolved(ObjectRef::new(39, 0), -1);
let source = ObjectHandle::integer(7);
target.assign_value_state(&source);
drop(target);
source.replace_direct_value(ObjectValue::Integer(8));
assert_eq!(source.as_integer(), Some(8));
}
#[test]
fn detached_programmatic_child_remains_unowned_without_a_live_root() {
let owner_ref = ObjectRef::new(7, 0);
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
let owner = ObjectHandle::new_indirect_for_pdf_with_resolver(
owner_ref,
NO_PARSED_OFFSET,
41,
Rc::downgrade(&resolver),
);
let parent = ObjectHandle::dictionary(vec![]);
owner.set_resolved(ObjectValue::Dictionary(
[(b"Parent".to_vec(), parent.clone())].into_iter().collect(),
));
let child = ObjectHandle::dictionary(vec![]);
parent.replace_key(b"/Child", child.clone()).unwrap();
parent.remove_key(b"/Child");
assert!(child.belongs_to_pdf(41));
assert!(child.belongs_to_pdf(42));
assert!(child.belongs_exclusively_to_pdf(42));
assert!(child.containing_object_refs_for_pdf(41).is_empty());
}
struct OwnedIdentityResolver;
impl DocumentResolver for OwnedIdentityResolver {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
_handle: &ObjectHandle,
) -> crate::Result<()> {
Ok(())
}
fn pdf_unique_id(&self) -> Option<u64> {
Some(4242)
}
}
#[test]
fn parser_direct_value_uses_its_single_qpdf_owner_identity() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(OwnedIdentityResolver);
let value = ObjectHandle::from_parsed_value_with_resolver(
ObjectValue::Integer(7),
Rc::downgrade(&resolver),
);
assert!(value.belongs_to_pdf(4242));
assert!(!value.belongs_to_pdf(4243));
assert!(value.belongs_exclusively_to_pdf(4242));
assert!(!value.belongs_exclusively_to_pdf(4243));
let unresolved = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(9, 0),
Rc::downgrade(&resolver),
);
unresolved
.try_dereference()
.expect("the identity resolver must remain a valid document resolver");
}
#[test]
fn direct_cycle_ownership_walk_terminates_without_history() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
let owner = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(7, 0),
NO_PARSED_OFFSET,
41,
Rc::downgrade(&resolver),
);
let first = ObjectHandle::dictionary(vec![]);
let second = ObjectHandle::dictionary(vec![]);
first.replace_key(b"/Second", second.clone()).unwrap();
second.replace_key(b"/First", first.clone()).unwrap();
owner.set_resolved(ObjectValue::Dictionary(
[(b"First".to_vec(), first.clone())].into_iter().collect(),
));
assert!(first.belongs_exclusively_to_pdf(41));
assert!(second.belongs_exclusively_to_pdf(41));
}
#[test]
fn resolver_bearing_indirect_slot_starts_without_a_parsed_offset() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(12, 0),
Rc::downgrade(&resolver),
);
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn missing_indirect_slot_resolves_in_place_to_null() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(MissingResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(9, 0),
Rc::downgrade(&resolver),
);
assert!(handle.try_is_null().unwrap());
assert!(handle.is_resolved());
assert_eq!(handle.object_ref(), Some(ObjectRef::new(9, 0)));
}
#[test]
fn every_fallible_accessor_propagates_the_resolver_error() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(ErrorResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(10, 0),
Rc::downgrade(&resolver),
);
assert_eq!(
handle.try_is_null().unwrap_err().to_string(),
"resolver failed"
);
assert_eq!(
handle.try_as_dictionary().unwrap_err().to_string(),
"resolver failed"
);
assert!(
matches!(handle.try_get_keys().unwrap_err(), Error::System(message)
if message == "resolver failed")
);
assert_eq!(
handle.try_get_key(b"/A").unwrap_err().to_string(),
"resolver failed"
);
assert_eq!(
handle.try_has_key(b"/A").unwrap_err().to_string(),
"resolver failed"
);
assert_eq!(
handle.try_as_name().unwrap_err().to_string(),
"resolver failed"
);
assert!(matches!(
handle.try_get_stream_dict().unwrap_err(),
Error::System(message) if message == "resolver failed"
));
assert_eq!(
handle.try_as_array().unwrap_err().to_string(),
"resolver failed"
);
assert_eq!(
handle.try_array_len().unwrap_err().to_string(),
"resolver failed"
);
assert_eq!(
handle.try_as_integer().unwrap_err().to_string(),
"resolver failed"
);
assert!(!handle.is_resolved());
}
#[test]
fn try_get_keys_resolves_every_value_omits_nullish_and_sorts_keys() {
let (indirect_null, _indirect_null_resolver) = resolver_bearing_handle(ObjectValue::Null);
let missing_resolver: Rc<dyn DocumentResolver> = Rc::new(MissingResolver);
let missing = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(21, 0),
Rc::downgrade(&missing_resolver),
);
let (unknown, _unknown_resolver, unknown_calls) =
logged_resolver_bearing_handle(ObjectValue::Integer(2));
let dict = ObjectHandle::dictionary(vec![
(b"Zulu".to_vec(), ObjectHandle::integer(1)),
(b"DirectNull".to_vec(), ObjectHandle::null()),
(b"IndirectNull".to_vec(), indirect_null.clone()),
(b"Dangling".to_vec(), missing.clone()),
(b"Unknown".to_vec(), unknown),
(b"Alpha".to_vec(), ObjectHandle::boolean(true)),
]);
assert_eq!(
dict.try_get_keys().unwrap(),
BTreeSet::from([b"/Alpha".to_vec(), b"/Unknown".to_vec(), b"/Zulu".to_vec(),])
);
assert!(indirect_null.is_resolved());
assert!(missing.is_resolved());
assert_eq!(*unknown_calls.borrow(), vec![ObjectRef::new(20, 0)]);
}
#[test]
fn try_get_keys_lazily_resolves_dictionary_and_non_dictionary_holders() {
let (dict, _dict_resolver, dict_calls) =
logged_resolver_bearing_handle(ObjectValue::Dictionary(
[(b"Keep".to_vec(), ObjectHandle::integer(1))]
.into_iter()
.collect(),
));
assert!(!dict.is_resolved());
assert_eq!(
dict.try_get_keys().unwrap(),
BTreeSet::from([b"/Keep".to_vec()])
);
assert!(dict.is_resolved());
assert_eq!(*dict_calls.borrow(), vec![ObjectRef::new(20, 0)]);
let (scalar, _scalar_resolver, scalar_calls) =
logged_resolver_bearing_handle(ObjectValue::Integer(7));
assert!(matches!(
scalar.try_get_keys().unwrap_err(),
Error::Internal(message)
if message == "warning raised through a resolver with no document warning sink: \
object 20 0: operation for dictionary attempted on object of type integer: \
treating as empty"
));
assert_eq!(*scalar_calls.borrow(), vec![ObjectRef::new(20, 0)]);
}
#[test]
fn try_get_keys_propagates_a_child_resolver_error() {
let (child, _resolver) = error_resolving_handle(ObjectRef::new(30, 0));
let dict = ObjectHandle::dictionary(vec![(b"Broken".to_vec(), child.clone())]);
assert!(
matches!(dict.try_get_keys().unwrap_err(), Error::System(message)
if message == "resolver failed")
);
assert!(!child.is_resolved());
}
#[test]
fn try_get_keys_propagates_a_dropped_resolver_error_from_holder_and_child() {
let (holder, holder_resolver) =
resolver_bearing_handle(ObjectValue::Dictionary(Default::default()));
drop(holder_resolver);
assert!(
matches!(holder.try_get_keys().unwrap_err(), Error::Internal(message)
if message == "object 20 0 belongs to a dropped PDF")
);
let (child, child_resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(child_resolver);
let dict = ObjectHandle::dictionary(vec![(b"Broken".to_vec(), child)]);
assert!(
matches!(dict.try_get_keys().unwrap_err(), Error::Internal(message)
if message == "object 20 0 belongs to a dropped PDF")
);
}
#[test]
fn try_get_keys_stops_at_the_lexical_first_child_resolver_error() {
let (zulu, _zulu_resolver, zulu_calls) =
logged_error_resolving_handle(ObjectRef::new(32, 0), "zulu resolver failed");
let (alpha, _alpha_resolver, alpha_calls) =
logged_error_resolving_handle(ObjectRef::new(31, 0), "alpha resolver failed");
// Insert in reverse lexical order: the dictionary's BTreeMap traversal
// must nevertheless resolve Alpha first and stop there.
let dict =
ObjectHandle::dictionary(vec![(b"Zulu".to_vec(), zulu), (b"Alpha".to_vec(), alpha)]);
assert!(
matches!(dict.try_get_keys().unwrap_err(), Error::System(message)
if message == "alpha resolver failed")
);
assert_eq!(*alpha_calls.borrow(), vec![ObjectRef::new(31, 0)]);
assert!(zulu_calls.borrow().is_empty());
}
#[test]
fn try_has_key_treats_a_present_null_value_as_absent() {
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::null())]);
assert!(!dict.try_has_key(b"/A").unwrap());
assert!(!dict.try_has_key(b"/Missing").unwrap());
}
#[test]
fn fallible_dictionary_accessors_cover_resolved_and_non_dictionary_values() {
let resolver = Rc::new(RecordingResolver::default());
let erased: Rc<dyn DocumentResolver> = resolver;
let dict =
ObjectHandle::new_indirect_with_resolver(ObjectRef::new(11, 0), Rc::downgrade(&erased));
let entries = dict
.try_as_dictionary()
.unwrap()
.expect("recording resolver installs a dictionary");
assert_eq!(entries.get(b"/A".as_slice()).unwrap().as_integer(), Some(1));
let scalar = ObjectHandle::integer(1);
assert!(matches!(
scalar.try_has_key(b"/A"),
Err(Error::QpdfExc(error))
if error.get_message_detail() == b"operation for dictionary attempted on object of type integer: returning false for a key containment request"
));
}
#[test]
fn try_as_name_resolves_an_indirect_name_through_its_document() {
let (handle, _resolver) =
resolver_bearing_handle(ObjectValue::Name(b"FlateDecode".to_vec()));
// The non-resolving accessor cannot see through an unresolved handle,
// and reports the same `None` it would for a wrong-typed value. Closing
// that gap is the whole reason the `try_` form exists.
assert_eq!(handle.as_name(), None);
assert!(!handle.is_resolved());
assert_eq!(handle.try_as_name().unwrap(), Some(b"FlateDecode".to_vec()));
assert!(handle.is_resolved());
}
#[test]
fn try_as_string_resolves_an_indirect_string_through_its_document() {
let (handle, _resolver) = resolver_bearing_handle(ObjectValue::String(b"secret".to_vec()));
// Same gap as `try_as_name`: the non-resolving accessor cannot see
// through an unresolved handle.
assert_eq!(handle.as_string(), None);
assert!(!handle.is_resolved());
assert_eq!(handle.try_as_string().unwrap(), Some(b"secret".to_vec()));
assert!(handle.is_resolved());
}
#[test]
fn try_is_name_and_equals_compares_direct_decoded_name_bytes() {
let name = ObjectHandle::name(b"Crypt".to_vec());
assert!(name.try_is_name_and_equals(b"Crypt").unwrap());
assert!(!name.try_is_name_and_equals(b"FlateDecode").unwrap());
assert!(!ObjectHandle::integer(1)
.try_is_name_and_equals(b"Crypt")
.unwrap());
}
#[test]
fn try_is_name_and_equals_resolves_an_indirect_name() {
let (handle, _resolver) = resolver_bearing_handle(ObjectValue::Name(b"Crypt".to_vec()));
assert!(!handle.is_resolved());
assert!(handle.try_is_name_and_equals(b"Crypt").unwrap());
assert!(handle.is_resolved());
}
#[test]
fn try_is_string_checks_type_without_copying_and_resolves_indirect_value() {
let direct = ObjectHandle::string(vec![b'x'; 4096]);
assert!(direct.try_is_string().unwrap());
assert!(!ObjectHandle::integer(1).try_is_string().unwrap());
assert!(!ObjectHandle::uninitialized().try_is_string().unwrap());
let (indirect, _resolver) =
resolver_bearing_handle(ObjectValue::String(b"indirect".to_vec()));
assert!(!indirect.is_resolved());
assert!(indirect.try_is_string().unwrap());
assert!(indirect.is_resolved());
}
#[test]
fn try_is_string_propagates_resolver_errors() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(ErrorResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(23, 0),
Rc::downgrade(&resolver),
);
assert_eq!(
handle.try_is_string().unwrap_err().to_string(),
"resolver failed"
);
}
#[test]
fn try_is_name_and_equals_propagates_resolver_errors() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(ErrorResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(22, 0),
Rc::downgrade(&resolver),
);
assert_eq!(
handle
.try_is_name_and_equals(b"Crypt")
.unwrap_err()
.to_string(),
"resolver failed"
);
}
#[test]
fn try_is_name_and_equals_reports_a_dropped_document() {
let (handle, resolver) = resolver_bearing_handle(ObjectValue::Name(b"Crypt".to_vec()));
drop(resolver);
assert_eq!(
handle
.try_is_name_and_equals(b"Crypt")
.unwrap_err()
.to_string(),
"object 20 0 belongs to a dropped PDF"
);
}
#[test]
fn try_is_or_has_name_matches_a_direct_name_or_array_item() {
assert!(ObjectHandle::name(b"Crypt".to_vec())
.try_is_or_has_name(b"Crypt")
.unwrap());
assert!(ObjectHandle::array(vec![
ObjectHandle::name(b"FlateDecode".to_vec()),
ObjectHandle::name(b"Crypt".to_vec()),
])
.try_is_or_has_name(b"Crypt")
.unwrap());
}
#[test]
fn try_is_or_has_name_returns_false_for_other_shapes_and_names() {
assert!(!ObjectHandle::name(b"FlateDecode".to_vec())
.try_is_or_has_name(b"Crypt")
.unwrap());
assert!(!ObjectHandle::integer(1)
.try_is_or_has_name(b"Crypt")
.unwrap());
assert!(!ObjectHandle::array(vec![ObjectHandle::integer(1)])
.try_is_or_has_name(b"Crypt")
.unwrap());
}
#[test]
fn try_is_or_has_name_stops_before_a_later_erroring_child() {
let (erroring, _resolver) = error_resolving_handle(ObjectRef::new(24, 0));
let array = ObjectHandle::array(vec![ObjectHandle::name(b"Crypt".to_vec()), erroring]);
assert!(array.try_is_or_has_name(b"Crypt").unwrap());
}
#[test]
fn try_is_or_has_name_resolves_indirect_holder_and_child() {
let (child, _child_resolver) =
resolver_bearing_handle(ObjectValue::Name(b"Crypt".to_vec()));
let (array, _array_resolver) =
resolver_bearing_handle(ObjectValue::Array(vec![child.clone()]));
assert!(array.try_is_or_has_name(b"Crypt").unwrap());
assert!(array.is_resolved());
assert!(child.is_resolved());
}
#[test]
fn try_is_or_has_name_propagates_child_resolution_errors() {
let (erroring, _resolver) = error_resolving_handle(ObjectRef::new(25, 0));
let array = ObjectHandle::array(vec![erroring]);
assert_eq!(
array.try_is_or_has_name(b"Crypt").unwrap_err().to_string(),
"resolver failed"
);
}
#[test]
fn try_is_or_has_name_reports_a_dropped_document() {
let (array, resolver) =
resolver_bearing_handle(ObjectValue::Array(vec![ObjectHandle::null()]));
drop(resolver);
assert_eq!(
array.try_is_or_has_name(b"Crypt").unwrap_err().to_string(),
"object 20 0 belongs to a dropped PDF"
);
}
#[test]
fn try_is_dictionary_of_type_matches_type_subtype_and_empty_constraints() {
let dict = ObjectHandle::dictionary(vec![
(
b"Type".to_vec(),
ObjectHandle::name(b"CryptFilterDecodeParms".to_vec()),
),
(
b"Subtype".to_vec(),
ObjectHandle::name(b"Identity".to_vec()),
),
]);
assert!(dict
.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"")
.unwrap());
assert!(dict
.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"Identity")
.unwrap());
assert!(dict.try_is_dictionary_of_type(b"", b"").unwrap());
assert!(dict.try_is_dictionary_of_type(b"", b"Identity").unwrap());
}
#[test]
fn try_is_dictionary_of_type_rejects_wrong_missing_or_non_name_entries() {
let wrong = ObjectHandle::dictionary(vec![(
b"Type".to_vec(),
ObjectHandle::name(b"Metadata".to_vec()),
)]);
let non_name = ObjectHandle::dictionary(vec![(b"Type".to_vec(), ObjectHandle::integer(1))]);
let missing = ObjectHandle::dictionary(Vec::new());
let wrong_subtype = ObjectHandle::dictionary(vec![
(
b"Type".to_vec(),
ObjectHandle::name(b"CryptFilterDecodeParms".to_vec()),
),
(b"Subtype".to_vec(), ObjectHandle::name(b"Other".to_vec())),
]);
assert!(!wrong
.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"")
.unwrap());
assert!(!non_name
.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"")
.unwrap());
assert!(!missing
.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"")
.unwrap());
assert!(!wrong_subtype
.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"Identity")
.unwrap());
assert!(!ObjectHandle::integer(1)
.try_is_dictionary_of_type(b"", b"")
.unwrap());
}
#[test]
fn try_is_stream_of_type_matches_only_a_stream_with_the_requested_dict_type() {
// Arm 1: a plain (non-stream) dictionary never matches, even when its
// own /Type says the right thing -- `try_is_stream_of_type` requires
// `isStream()`, matching `QPDFObjectHandle::isStreamOfType`
// (`libqpdf/QPDFObjectHandle.cc:468-471`).
let plain_dict = ObjectHandle::dictionary(vec![(
b"Type".to_vec(),
ObjectHandle::name(b"XRef".to_vec()),
)]);
assert!(!plain_dict.try_is_stream_of_type(b"XRef", b"").unwrap());
// Arm 2: a stream whose nested dictionary has the wrong /Type.
let wrong_type_dict = ObjectHandle::dictionary(vec![(
b"Type".to_vec(),
ObjectHandle::name(b"ObjStm".to_vec()),
)]);
let wrong_type_stream = ObjectHandle::stream(wrong_type_dict, std::rc::Rc::new(Vec::new()));
assert!(!wrong_type_stream
.try_is_stream_of_type(b"XRef", b"")
.unwrap());
// Arm 3: a stream whose nested dictionary has the requested /Type --
// the shape every real `/Type /XRef` or `/Type /ObjStm` object has,
// since both are required to carry stream data.
let xref_dict = ObjectHandle::dictionary(vec![(
b"Type".to_vec(),
ObjectHandle::name(b"XRef".to_vec()),
)]);
let xref_stream = ObjectHandle::stream(xref_dict, std::rc::Rc::new(Vec::new()));
assert!(xref_stream.try_is_stream_of_type(b"XRef", b"").unwrap());
let objstm_dict = ObjectHandle::dictionary(vec![(
b"Type".to_vec(),
ObjectHandle::name(b"ObjStm".to_vec()),
)]);
let objstm_stream = ObjectHandle::stream(objstm_dict, std::rc::Rc::new(Vec::new()));
assert!(objstm_stream.try_is_stream_of_type(b"ObjStm", b"").unwrap());
}
#[test]
fn try_is_dictionary_of_type_resolves_indirect_holder_and_type_child() {
let (type_name, _type_resolver) =
resolver_bearing_handle(ObjectValue::Name(b"CryptFilterDecodeParms".to_vec()));
let (dict, _dict_resolver) =
resolver_bearing_handle(ObjectValue::Dictionary(std::collections::BTreeMap::from([
(b"Type".to_vec(), type_name.clone()),
])));
assert!(dict
.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"")
.unwrap());
assert!(dict.is_resolved());
assert!(type_name.is_resolved());
}
#[test]
fn try_is_dictionary_of_type_stops_before_subtype_after_wrong_type() {
let (erroring_subtype, _resolver) = error_resolving_handle(ObjectRef::new(26, 0));
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Metadata".to_vec())),
(b"Subtype".to_vec(), erroring_subtype),
]);
assert!(!dict
.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"Identity")
.unwrap());
}
#[test]
fn try_is_dictionary_of_type_propagates_child_resolution_errors() {
let (erroring_type, _resolver) = error_resolving_handle(ObjectRef::new(27, 0));
let dict = ObjectHandle::dictionary(vec![(b"Type".to_vec(), erroring_type)]);
assert_eq!(
dict.try_is_dictionary_of_type(b"CryptFilterDecodeParms", b"")
.unwrap_err()
.to_string(),
"resolver failed"
);
}
#[test]
fn try_is_dictionary_of_type_reports_a_dropped_document() {
let (dict, resolver) =
resolver_bearing_handle(ObjectValue::Dictionary(std::collections::BTreeMap::new()));
drop(resolver);
assert_eq!(
dict.try_is_dictionary_of_type(b"", b"")
.unwrap_err()
.to_string(),
"object 20 0 belongs to a dropped PDF"
);
}
#[test]
fn try_as_integer_resolves_an_indirect_integer_through_its_document() {
let (handle, _resolver) = resolver_bearing_handle(ObjectValue::Integer(7));
assert_eq!(handle.as_integer(), None);
assert!(!handle.is_resolved());
assert_eq!(handle.try_as_integer().unwrap(), Some(7));
assert!(handle.is_resolved());
}
#[test]
fn try_as_real_resolves_an_indirect_real_through_its_document() {
let (handle, _resolver) = resolver_bearing_handle(ObjectValue::Real(3.5));
assert_eq!(handle.as_real(), None);
assert!(!handle.is_resolved());
assert_eq!(handle.try_as_real().unwrap(), Some(3.5));
assert!(handle.is_resolved());
}
#[test]
fn try_as_array_resolves_an_indirect_array_through_its_document() {
let (handle, _resolver) =
resolver_bearing_handle(ObjectValue::Array(vec![ObjectHandle::from_value(
ObjectValue::Name(b"FlateDecode".to_vec()),
)]));
assert!(handle.as_array().is_none());
assert!(!handle.is_resolved());
let items = handle
.try_as_array()
.unwrap()
.expect("recording resolver installs an array");
// `ObjectHandle` equality is identity rather than value (see
// `two_direct_handles_with_equal_value_are_distinct_identity`), so
// inspect the child's value instead of comparing the `Vec`.
assert_eq!(items.len(), 1);
assert_eq!(items[0].as_name(), Some(b"FlateDecode".to_vec()));
assert!(handle.is_resolved());
}
#[test]
fn try_array_len_counts_in_place_and_keeps_none_for_a_non_array() {
// The count qpdf reads off the borrowed array
// (`getArrayNItems` → `asArray()->size()`,
// `libqpdf/QPDFObjectHandle.cc:758-768`), including the empty array
// `QPDF_Stream::filterable` special-cases at
// `libqpdf/QPDF_Stream.cc:443`.
let array = ObjectHandle::array(vec![
ObjectHandle::name(b"FlateDecode".to_vec()),
ObjectHandle::name(b"ASCII85Decode".to_vec()),
]);
assert_eq!(array.try_array_len().unwrap(), Some(2));
// Counting must not consume or replace the value.
assert_eq!(array.as_array().map(|items| items.len()), Some(2));
assert_eq!(
ObjectHandle::array(Vec::new()).try_array_len().unwrap(),
Some(0)
);
// Deliberately *not* qpdf's non-array answer. `getArrayNItems` warns
// `typeWarning("array", "treating as empty")` and returns 0
// (`libqpdf/QPDFObjectHandle.cc:763-766`); returning `Some(0)` here
// would make the canonical stream filter planner read a scalar
// `/Filter` as an empty chain — an accepted unfiltered stream —
// instead of raising its type error.
for non_array in [
ObjectHandle::null(),
ObjectHandle::integer(1),
ObjectHandle::name(b"FlateDecode".to_vec()),
ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::integer(1))]),
] {
assert_eq!(non_array.try_array_len().unwrap(), None);
}
}
#[test]
fn try_array_len_resolves_an_indirect_array_through_its_document() {
let (handle, _resolver) =
resolver_bearing_handle(ObjectValue::Array(vec![ObjectHandle::null()]));
// Nothing non-resolving can see through an unresolved handle, so
// dropping `try_dereference` from `try_array_len` reports this array
// as "not an array" — the mutation the `stream_filter` call sites
// cannot kill on their own, because a preceding `try_*` has already
// resolved the slot by the time they count it.
assert!(handle.as_array().is_none());
assert!(!handle.is_resolved());
assert_eq!(handle.try_array_len().unwrap(), Some(1));
assert!(handle.is_resolved());
}
#[test]
fn try_array_item_returns_live_first_middle_and_last_handles() {
let first = ObjectHandle::integer(1);
let middle = ObjectHandle::integer(2);
let last = ObjectHandle::integer(3);
let array = ObjectHandle::array(vec![first.clone(), middle.clone(), last.clone()]);
assert!(array.try_array_item(0).unwrap().unwrap().ptr_eq(&first));
assert!(array.try_array_item(1).unwrap().unwrap().ptr_eq(&middle));
assert!(array.try_array_item(2).unwrap().unwrap().ptr_eq(&last));
}
#[test]
fn try_array_item_returns_none_outside_the_valid_array_domain() {
let array = ObjectHandle::array(vec![ObjectHandle::null()]);
assert!(array.try_array_item(1).unwrap().is_none());
assert!(ObjectHandle::integer(1)
.try_array_item(0)
.unwrap()
.is_none());
}
#[test]
fn try_array_item_resolves_an_indirect_holder_once_without_resolving_the_child() {
let (child, _child_resolver) = error_resolving_handle(ObjectRef::new(23, 0));
let (array, _resolver, calls) =
logged_resolver_bearing_handle(ObjectValue::Array(vec![child.clone()]));
let fetched = array.try_array_item(0).unwrap().unwrap();
assert!(fetched.ptr_eq(&child));
assert!(!fetched.is_resolved());
assert_eq!(calls.borrow().as_slice(), &[ObjectRef::new(20, 0)]);
}
#[test]
fn try_array_item_reports_a_dropped_document() {
let (array, resolver) =
resolver_bearing_handle(ObjectValue::Array(vec![ObjectHandle::null()]));
drop(resolver);
assert_eq!(
array.try_array_item(0).unwrap_err().to_string(),
"object 20 0 belongs to a dropped PDF"
);
}
#[test]
fn every_value_accessor_reports_a_dropped_document_rather_than_none() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(RecordingResolver::default());
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(21, 0),
Rc::downgrade(&resolver),
);
drop(resolver);
// A `None` here would be indistinguishable from a resolved value of
// the wrong type, so each accessor must surface the dropped document.
for error in [
handle.try_as_name().unwrap_err(),
handle.try_as_array().unwrap_err(),
handle.try_array_len().unwrap_err(),
handle.try_as_integer().unwrap_err(),
] {
assert_eq!(error.to_string(), "object 21 0 belongs to a dropped PDF");
}
assert!(!handle.is_resolved());
}
#[test]
fn direct_handle_clone_shares_identity_not_a_deep_copy() {
let handle = ObjectHandle::integer(42);
let clone = handle.clone();
assert!(handle.ptr_eq(&clone));
}
#[test]
fn two_direct_handles_with_equal_value_are_distinct_identity() {
let a = ObjectHandle::integer(42);
let b = ObjectHandle::integer(42);
assert!(!a.ptr_eq(&b));
}
#[test]
fn direct_handle_reports_direct_not_indirect() {
let handle = ObjectHandle::integer(1);
assert!(handle.is_direct());
assert!(!handle.is_indirect());
assert_eq!(handle.object_ref(), None);
}
#[test]
fn indirect_handle_retains_object_ref_before_resolution() {
let object_ref = ObjectRef::new(5, 0);
let handle = ObjectHandle::new_indirect_unresolved(object_ref, 0);
assert!(handle.is_indirect());
assert!(!handle.is_direct());
assert_eq!(handle.object_ref(), Some(object_ref));
}
#[test]
fn a_non_document_resolver_settles_a_raw_generation_without_a_valid_projection() {
struct ValidProjectionOnlyResolver;
impl DocumentResolver for ValidProjectionOnlyResolver {
// cov:ignore-start: this valid-reference hook is required by the
// trait but a generation outside the `N G R` range never produces
// an `ObjectRef` for it to receive.
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
_handle: &ObjectHandle,
) -> crate::Result<()> {
Ok(())
}
// cov:ignore-end
}
let resolver: Rc<dyn DocumentResolver> = Rc::new(ValidProjectionOnlyResolver);
let handle = ObjectHandle::new_indirect_for_qpdf_obj_gen_with_resolver(
QpdfObjGen::new(5, 65_536),
NO_PARSED_OFFSET,
1,
Rc::downgrade(&resolver),
);
// qpdf accepts any `QPDFObjGen` without range-checking the generation —
// `QPDF::getObject` (`libqpdf/QPDF.cc:1952-1959`) caches an unresolved
// value for it, and `QPDF::resolve` settles an identity with no xref
// row as null (`libqpdf/QPDF.cc:1745-1748`). An identity that the
// `N G R` parser range cannot express is that case, not an error.
assert_eq!(handle.object_ref(), None);
handle
.try_dereference()
.expect("an unprojectable generation settles as null");
assert!(handle.is_null());
}
#[test]
fn cloning_an_indirect_handle_shares_the_same_slot() {
let object_ref = ObjectRef::new(5, 0);
let handle = ObjectHandle::new_indirect_unresolved(object_ref, 0);
let clone = handle.clone();
assert!(handle.ptr_eq(&clone));
}
#[test]
fn a_direct_and_an_indirect_handle_are_never_identical() {
let direct = ObjectHandle::integer(42);
let indirect = ObjectHandle::new_indirect_unresolved(ObjectRef::new(5, 0), 0);
assert!(!direct.ptr_eq(&indirect));
assert!(!indirect.ptr_eq(&direct));
}
#[test]
fn try_get_parsed_offset_returns_no_parsed_offset_for_an_uninitialized_handle() {
let handle = ObjectHandle::uninitialized();
assert_eq!(handle.try_get_parsed_offset().unwrap(), NO_PARSED_OFFSET);
}
#[test]
fn try_get_parsed_offset_reads_a_direct_handles_offset_without_a_resolver() {
let handle = ObjectHandle::integer(9);
assert_eq!(handle.try_get_parsed_offset().unwrap(), NO_PARSED_OFFSET);
handle.set_parsed_offset_if_unset(123);
assert_eq!(handle.try_get_parsed_offset().unwrap(), 123);
}
#[test]
fn try_get_parsed_offset_forces_resolution_before_reading_an_unresolved_indirect_handle() {
struct OffsetSettingResolver;
impl DocumentResolver for OffsetSettingResolver {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
handle.set_resolved(ObjectValue::Integer(7));
handle.set_parsed_offset_if_unset(200);
Ok(())
}
}
let resolver: Rc<dyn DocumentResolver> = Rc::new(OffsetSettingResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(60, 0),
Rc::downgrade(&resolver),
);
// The raw slot accessor sees the pre-resolution sentinel; only the
// forcing accessor observes the offset the resolver records.
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
assert_eq!(handle.try_get_parsed_offset().unwrap(), 200);
assert!(handle.is_resolved());
}
#[test]
fn try_get_parsed_offset_resets_to_no_parsed_offset_when_resolution_lands_on_null() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(MissingResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(61, 0),
Rc::downgrade(&resolver),
);
assert_eq!(handle.try_get_parsed_offset().unwrap(), NO_PARSED_OFFSET);
assert!(handle.is_resolved());
}
#[test]
fn try_get_parsed_offset_propagates_a_resolver_error_instead_of_collapsing_to_negative_one() {
let (handle, _resolver) = error_resolving_handle(ObjectRef::new(62, 0));
assert_eq!(
handle.try_get_parsed_offset().unwrap_err().to_string(),
"resolver failed"
);
assert!(!handle.is_resolved());
}
#[test]
fn try_get_parsed_offset_propagates_a_dropped_resolver_error() {
let (handle, resolver) = resolver_bearing_handle(ObjectValue::Integer(1));
drop(resolver);
assert!(
matches!(handle.try_get_parsed_offset().unwrap_err(), Error::Internal(message)
if message == "object 20 0 belongs to a dropped PDF")
);
}
#[test]
fn try_get_parsed_offset_does_not_re_resolve_an_already_resolved_handle() {
let (handle, _resolver, calls) = logged_resolver_bearing_handle(ObjectValue::Integer(3));
assert_eq!(handle.try_get_parsed_offset().unwrap(), NO_PARSED_OFFSET);
handle.set_parsed_offset_if_unset(9);
assert_eq!(handle.try_get_parsed_offset().unwrap(), 9);
assert_eq!(*calls.borrow(), vec![ObjectRef::new(20, 0)]);
}
}
#[cfg(test)]
mod uniform_identity_tests {
use super::*;
struct NoopResolver {
calls: Rc<std::cell::Cell<usize>>,
}
impl DocumentResolver for NoopResolver {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
_handle: &ObjectHandle,
) -> crate::Result<()> {
self.calls.set(self.calls.get() + 1);
Ok(())
}
}
fn resolver() -> Rc<dyn DocumentResolver> {
Rc::new(NoopResolver {
calls: Rc::new(std::cell::Cell::new(0)),
})
}
#[test]
fn out_of_range_object_ref_constructors_return_uninitialized_handles() {
let resolver = resolver();
let object_ref = ObjectRef::new(u32::MAX, 0);
assert!(
!ObjectHandle::new_reserved_for_pdf(object_ref, 1, Rc::downgrade(&resolver))
.is_initialized()
);
assert!(
!ObjectHandle::new_indirect_with_resolver(object_ref, Rc::downgrade(&resolver))
.is_initialized()
);
assert!(!ObjectHandle::integer(1)
.promote_to_indirect(object_ref, 1, Rc::downgrade(&resolver))
.is_initialized());
}
fn recording_noop_resolver() -> (Rc<dyn DocumentResolver>, Rc<std::cell::Cell<usize>>) {
let calls = Rc::new(std::cell::Cell::new(0));
(
Rc::new(NoopResolver {
calls: calls.clone(),
}),
calls,
)
}
struct ReenteringResolver {
calls: Rc<RefCell<Vec<ObjectRef>>>,
}
impl DocumentResolver for ReenteringResolver {
fn resolve_indirect(
&self,
object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
self.calls.borrow_mut().push(object_ref);
assert_eq!(handle.object_ref(), Some(object_ref));
handle.set_resolved(ObjectValue::Dictionary(Default::default()));
handle
.replace_key(b"/Resolved", ObjectHandle::boolean(true))
.unwrap();
Ok(())
}
}
#[test]
fn promotion_preserves_one_shared_object_identity_and_offset() {
let resolver = resolver();
let original =
ObjectHandle::dictionary(vec![(b"Value".to_vec(), ObjectHandle::integer(1))]);
let outstanding_clone = original.clone();
original.set_parsed_offset_if_unset(37);
let promoted =
original.promote_to_indirect(ObjectRef::new(17, 2), 41, Rc::downgrade(&resolver));
assert!(original.is_same_object_as(&outstanding_clone));
assert!(original.is_same_object_as(&promoted));
assert!(original.is_indirect());
assert!(outstanding_clone.is_indirect());
assert_eq!(promoted.object_ref(), Some(ObjectRef::new(17, 2)));
assert_eq!(outstanding_clone.get_parsed_offset(), 37);
original
.replace_key(b"/Value", ObjectHandle::integer(2))
.unwrap();
assert_eq!(
promoted.try_get_key(b"/Value").unwrap().as_integer(),
Some(2)
);
promoted
.replace_key(b"/Value", ObjectHandle::integer(3))
.unwrap();
assert_eq!(
outstanding_clone
.try_get_key(b"/Value")
.unwrap()
.as_integer(),
Some(3)
);
}
#[test]
fn promotion_does_not_clone_container_or_stream_storage() {
let resolver = resolver();
let array_child = ObjectHandle::dictionary(vec![]);
let stream_dict = ObjectHandle::dictionary(vec![]);
let stream_data = Rc::new(b"shared stream data".to_vec());
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: stream_dict.clone(),
stream_data: Some(stream_data.clone()),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: stream_data.len(),
})));
let root = ObjectHandle::array(vec![array_child.clone(), stream.clone()]);
let promoted =
root.promote_to_indirect(ObjectRef::new(19, 0), 51, Rc::downgrade(&resolver));
let children = promoted.as_array().expect("promoted array");
assert!(children[0].is_same_object_as(&array_child));
assert!(children[1].is_same_object_as(&stream));
let promoted_dict = children[1].as_stream_dict().expect("stream dictionary");
assert!(promoted_dict.is_same_object_as(&stream_dict));
assert!(children[1].with_value(|value| matches!(
value,
Some(ObjectValue::Stream(stream))
if stream.stream_data.as_ref().is_some_and(|actual| Rc::ptr_eq(actual, &stream_data))
)));
}
#[test]
fn promotion_delegates_unresolved_access_to_its_installed_resolver() {
let (resolver, calls) = recording_noop_resolver();
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(20, 0), -1);
handle.promote_to_indirect(ObjectRef::new(20, 0), 52, Rc::downgrade(&resolver));
handle
.try_dereference()
.expect("the installed resolver accepts the lookup");
assert_eq!(calls.get(), 1);
assert!(
!handle.is_resolved(),
"a resolver that installs no value must not fabricate resolution"
);
}
#[test]
fn contained_children_observe_parent_promotion_without_edge_rewrite() {
let resolver = resolver();
let child = ObjectHandle::dictionary(vec![]);
let parent = ObjectHandle::dictionary(vec![(b"Child".to_vec(), child.clone())]);
assert!(child.containing_object_refs_for_pdf(61).is_empty());
parent.promote_to_indirect(ObjectRef::new(29, 0), 61, Rc::downgrade(&resolver));
assert_eq!(
child.containing_object_refs_for_pdf(61),
vec![ObjectRef::new(29, 0)]
);
}
#[test]
fn re_promotion_updates_active_root_without_claiming_direct_children() {
let first = resolver();
let second = resolver();
let child = ObjectHandle::dictionary(vec![]);
let parent = ObjectHandle::dictionary(vec![(b"Child".to_vec(), child.clone())]);
let first_alias =
parent.promote_to_indirect(ObjectRef::new(31, 0), 71, Rc::downgrade(&first));
let second_alias =
parent.promote_to_indirect(ObjectRef::new(37, 4), 72, Rc::downgrade(&second));
assert!(first_alias.is_same_object_as(&second_alias));
assert_eq!(parent.object_ref(), Some(ObjectRef::new(37, 4)));
assert!(!parent.belongs_to_pdf(71));
assert!(parent.belongs_to_pdf(72));
assert_eq!(child.owning_pdf_unique_id(), None);
assert!(child.belongs_to_pdf(71));
assert!(child.belongs_to_pdf(72));
assert!(child.containing_object_refs_for_pdf(71).is_empty());
assert_eq!(
child.containing_object_refs_for_pdf(72),
vec![ObjectRef::new(37, 4)]
);
}
#[test]
fn promoted_child_is_an_indirect_boundary_not_a_direct_owner_path() {
let resolver = resolver();
let child = ObjectHandle::dictionary(vec![]);
let outer = ObjectHandle::dictionary(vec![(b"Child".to_vec(), child.clone())]);
outer.promote_to_indirect(ObjectRef::new(41, 0), 81, Rc::downgrade(&resolver));
child.promote_to_indirect(ObjectRef::new(43, 0), 81, Rc::downgrade(&resolver));
assert!(child.containing_object_refs_for_pdf(81).is_empty());
let grandchild = ObjectHandle::integer(1);
child
.replace_key(b"/Grandchild", grandchild.clone())
.unwrap();
assert_eq!(
grandchild.containing_object_refs_for_pdf(81),
vec![ObjectRef::new(43, 0)]
);
}
#[test]
fn dormant_parent_edge_tracks_removal_while_child_is_indirect() {
let resolver = resolver();
let child = ObjectHandle::dictionary(vec![]);
let outer = ObjectHandle::dictionary(vec![(b"Child".to_vec(), child.clone())]);
outer.promote_to_indirect(ObjectRef::new(73, 0), 111, Rc::downgrade(&resolver));
child.promote_to_indirect(ObjectRef::new(79, 0), 112, Rc::downgrade(&resolver));
assert!(child.containing_object_refs_for_pdf(111).is_empty());
child.disconnect();
assert_eq!(
child.containing_object_refs_for_pdf(111),
vec![ObjectRef::new(73, 0)]
);
child.promote_to_indirect(ObjectRef::new(83, 0), 112, Rc::downgrade(&resolver));
outer.remove_key(b"/Child");
child.disconnect();
assert!(child.containing_object_refs_for_pdf(111).is_empty());
}
#[test]
fn disconnect_clears_indirect_metadata_for_every_non_null_alias() {
let resolver = resolver();
let original = ObjectHandle::integer(9);
original.set_parsed_offset_if_unset(44);
let promoted =
original.promote_to_indirect(ObjectRef::new(47, 0), 91, Rc::downgrade(&resolver));
promoted.disconnect_and_destroy();
assert!(original.is_same_object_as(&promoted));
assert!(original.is_direct());
assert_eq!(original.object_ref(), None);
assert!(!original.is_null());
assert_eq!(original.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn unique_destroy_reuses_the_existing_value_state() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(48, 0), -1);
handle.set_resolved(ObjectValue::Integer(9));
let allocations_before = super::detached_state_rebind_allocations_for_test();
handle.disconnect_and_destroy();
assert_eq!(
super::detached_state_rebind_allocations_for_test(),
allocations_before,
"a uniquely owned value state must be rebound in place"
);
assert_eq!(handle.type_code().expect("destroyed type code"), 14);
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn unique_remove_reuses_the_existing_value_state() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(49, 0), -1);
handle.set_resolved(ObjectValue::Integer(9));
let allocations_before = super::detached_state_rebind_allocations_for_test();
handle.remove_from_document();
assert_eq!(
super::detached_state_rebind_allocations_for_test(),
allocations_before,
"a uniquely owned value state must be rebound in place"
);
assert!(handle.is_null());
assert_eq!(handle.object_ref(), None);
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn disconnect_preserves_literal_null_and_resolved_null_as_null() {
let resolver = resolver();
let literal_null = ObjectHandle::null();
literal_null.set_parsed_offset_if_unset(55);
literal_null.promote_to_indirect(ObjectRef::new(49, 0), 92, Rc::downgrade(&resolver));
literal_null.disconnect();
assert!(literal_null.is_direct());
assert!(literal_null.is_null());
assert_eq!(literal_null.get_parsed_offset(), 55);
let resolved_null = ObjectHandle::new_indirect_unresolved(ObjectRef::new(51, 0), -1);
resolved_null.set_resolved(ObjectValue::Null);
resolved_null.promote_to_indirect(ObjectRef::new(53, 0), 93, Rc::downgrade(&resolver));
resolved_null.disconnect();
assert!(resolved_null.is_direct());
assert!(resolved_null.is_null());
assert_eq!(resolved_null.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn disconnect_of_an_unresolved_indirect_alias_becomes_destroyed_direct() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(54, 0), -1);
let alias = handle.clone();
handle.set_parsed_offset_if_unset(66);
handle.disconnect_and_destroy();
assert!(alias.is_same_object_as(&handle));
assert!(alias.is_direct());
assert_eq!(alias.object_ref(), None);
assert!(!alias.is_null());
assert_eq!(alias.type_code().expect("type code"), 14);
assert_eq!(alias.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn disconnect_of_a_repromoted_destroyed_handle_resets_its_new_offset() {
let resolver = resolver();
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(56, 0), -1);
handle.disconnect_and_destroy();
handle.promote_to_indirect(ObjectRef::new(58, 0), 94, Rc::downgrade(&resolver));
handle.set_parsed_offset_if_unset(77);
assert!(handle.is_indirect());
assert_eq!(handle.object_ref(), Some(ObjectRef::new(58, 0)));
assert_eq!(handle.type_code().expect("type code"), 14);
assert_eq!(handle.get_parsed_offset(), 77);
handle.disconnect_and_destroy();
assert!(handle.is_direct());
assert_eq!(handle.object_ref(), None);
assert!(!handle.is_null());
assert_eq!(handle.type_code().expect("type code"), 14);
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn destroyed_direct_handle_has_no_legacy_value_to_clone_or_consume() {
let resolver = resolver();
let handle = ObjectHandle::integer(1);
handle.promote_to_indirect(ObjectRef::new(55, 0), 94, Rc::downgrade(&resolver));
handle.disconnect_and_destroy();
assert!(handle.direct_value_clone().expect("destroyed").is_none());
assert!(!handle.is_null(), "destroyed is distinct from literal null");
assert!(handle.into_direct_value().is_none());
}
#[test]
fn replace_direct_value_reinstalls_a_destroyed_direct_slot_payload() {
let resolver = resolver();
let handle = ObjectHandle::integer(1);
handle.promote_to_indirect(ObjectRef::new(56, 0), 94, Rc::downgrade(&resolver));
handle.disconnect();
handle.replace_direct_value(ObjectValue::Integer(2));
assert_eq!(handle.as_integer(), Some(2));
}
#[test]
fn replacing_a_destroyed_direct_slot_attaches_nested_children_to_its_indirect_root() {
let resolver = resolver();
let root_ref = ObjectRef::new(57, 0);
let root = ObjectHandle::new_indirect_for_pdf_with_resolver(
root_ref,
NO_PARSED_OFFSET,
95,
Rc::downgrade(&resolver),
);
let terminal = ObjectHandle::integer(1);
root.set_resolved(ObjectValue::Dictionary(std::collections::BTreeMap::from([
(b"Terminal".to_vec(), terminal.clone()),
])));
terminal.promote_to_indirect(ObjectRef::new(58, 0), 96, Rc::downgrade(&resolver));
terminal.disconnect();
let leaf = ObjectHandle::integer(2);
terminal.replace_direct_value(ObjectValue::Dictionary(
[(b"Nested".to_vec(), ObjectHandle::array(vec![leaf.clone()]))]
.into_iter()
.collect(),
));
assert_eq!(leaf.containing_object_refs_for_pdf(95), vec![root_ref]);
}
#[test]
fn promotion_records_identity_on_a_destroyed_direct_child_without_descending() {
let resolver = resolver();
let child = ObjectHandle::integer(1);
child.promote_to_indirect(ObjectRef::new(57, 0), 95, Rc::downgrade(&resolver));
child.disconnect();
let parent = ObjectHandle::dictionary(vec![(b"Child".to_vec(), child.clone())]);
parent.promote_to_indirect(ObjectRef::new(59, 0), 96, Rc::downgrade(&resolver));
assert!(child.belongs_to_pdf(96));
assert_eq!(
child.containing_object_refs_for_pdf(96),
vec![ObjectRef::new(59, 0)]
);
}
#[test]
fn resolution_state_is_shared_by_every_alias() {
let unresolved = ObjectHandle::new_indirect_unresolved(ObjectRef::new(23, 0), -1);
let alias = unresolved.clone();
unresolved.set_resolved(ObjectValue::Integer(7));
assert!(alias.is_same_object_as(&unresolved));
assert!(alias.is_resolved());
assert_eq!(alias.as_integer(), Some(7));
}
#[test]
fn re_promotion_uses_latest_resolver() {
let first_calls = Rc::new(RefCell::new(Vec::new()));
let first: Rc<dyn DocumentResolver> = Rc::new(ReenteringResolver {
calls: first_calls.clone(),
});
let handle = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(59, 0),
NO_PARSED_OFFSET,
101,
Rc::downgrade(&first),
);
let latest_calls = Rc::new(RefCell::new(Vec::new()));
let latest: Rc<dyn DocumentResolver> = Rc::new(ReenteringResolver {
calls: latest_calls.clone(),
});
let alias = handle.promote_to_indirect(ObjectRef::new(61, 7), 102, Rc::downgrade(&latest));
drop(first);
alias.try_dereference().expect("latest resolver resolves");
assert!(handle.is_same_object_as(&alias));
assert_eq!(*first_calls.borrow(), Vec::<ObjectRef>::new());
assert_eq!(*latest_calls.borrow(), vec![ObjectRef::new(61, 7)]);
assert_eq!(handle.object_ref(), Some(ObjectRef::new(61, 7)));
assert_eq!(
handle.try_get_key(b"/Resolved").unwrap().as_boolean(),
Some(true)
);
}
#[test]
fn resolver_reentry_uses_latest_metadata_without_borrow_panic() {
let calls = Rc::new(RefCell::new(Vec::new()));
let latest: Rc<dyn DocumentResolver> = Rc::new(ReenteringResolver {
calls: calls.clone(),
});
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(63, 0), -1);
handle.promote_to_indirect(ObjectRef::new(67, 3), 103, Rc::downgrade(&latest));
handle.try_dereference().expect("reentrant resolver");
assert_eq!(*calls.borrow(), vec![ObjectRef::new(67, 3)]);
assert_eq!(
handle.try_get_key(b"/Resolved").unwrap().as_boolean(),
Some(true)
);
}
#[test]
fn dropped_latest_resolver_reports_latest_object_and_stays_unresolved() {
let first = resolver();
let latest_calls = Rc::new(RefCell::new(Vec::new()));
let latest: Rc<dyn DocumentResolver> = Rc::new(ReenteringResolver {
calls: latest_calls.clone(),
});
let handle = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(69, 0),
NO_PARSED_OFFSET,
104,
Rc::downgrade(&first),
);
handle.promote_to_indirect(ObjectRef::new(71, 5), 105, Rc::downgrade(&latest));
drop(latest);
let error = handle
.try_dereference()
.expect_err("latest owner was dropped");
assert_eq!(error.to_string(), "object 71 5 belongs to a dropped PDF");
assert!(latest_calls.borrow().is_empty());
assert!(!handle.is_resolved());
}
}
#[cfg(test)]
mod object_value_tests {
use super::*;
#[test]
fn integer_handle_round_trips_its_value() {
let handle = ObjectHandle::integer(42);
assert_eq!(handle.as_integer(), Some(42));
}
#[test]
fn array_handle_holds_child_handles_not_raw_values() {
let child = ObjectHandle::integer(7);
let array = ObjectHandle::array(vec![child.clone()]);
let children = array.as_array().expect("array");
assert_eq!(children.len(), 1);
assert!(children[0].ptr_eq(&child));
}
#[test]
fn dictionary_handle_preserves_insertion_of_child_handles() {
let value = ObjectHandle::name(b"Type".to_vec());
let dict = ObjectHandle::dictionary(vec![(b"Key".to_vec(), value.clone())]);
let entries = dict.as_dictionary().expect("dictionary");
assert!(entries.get(b"/Key".as_slice()).unwrap().ptr_eq(&value));
}
#[test]
fn dictionary_handle_normalizes_aliases_before_last_value_wins_collection() {
let dict = ObjectHandle::dictionary(vec![
(b"K".to_vec(), ObjectHandle::integer(1)),
(b"/K".to_vec(), ObjectHandle::integer(2)),
]);
assert_eq!(dict.try_get_key(b"/K").unwrap().as_integer(), Some(2));
}
#[test]
fn null_handle_is_null() {
assert!(ObjectHandle::null().is_null());
assert!(!ObjectHandle::integer(0).is_null());
}
#[test]
fn stream_handle_round_trips_its_dict_and_data() {
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(3))]);
let stream = ObjectHandle::stream(dict.clone(), Rc::new(b"abc".to_vec()));
assert!(stream.as_stream_dict().expect("stream dict").ptr_eq(&dict));
assert_eq!(stream.as_stream_data(), Some(Rc::new(b"abc".to_vec())));
assert_eq!(
stream
.get_raw_stream_data()
.expect("replaced stream data")
.as_slice(),
b"abc"
);
assert_eq!(stream.type_code().expect("type code"), 10, "ot_stream");
}
#[test]
fn raw_stream_data_uses_replacements_including_an_empty_buffer() {
let stream = ObjectHandle::stream(ObjectHandle::dictionary(vec![]), Rc::new(Vec::new()));
assert!(
stream
.get_raw_stream_data()
.expect("empty replacement data")
.is_empty(),
"an empty replacement is data, not an original-stream sentinel"
);
stream.replace_stream_data(Rc::new(b"replacement".to_vec()), None, None);
assert_eq!(
stream
.get_raw_stream_data()
.expect("replacement data")
.as_slice(),
b"replacement",
"replacement data wins over every original-source detail"
);
}
#[test]
fn real_literal_handle_preserves_the_non_canonical_source_literal() {
// The preserved-literal value exists so a non-canonical source spelling
// (e.g. ".4") survives unparse byte-identically. The handle payload
// must carry the same two fields, or byte-identical output breaks
// the moment a real-literal round-trips through this layer.
let handle = ObjectHandle::real_literal(0.4, b".4".to_vec());
assert_eq!(handle.as_real_literal(), Some((0.4, b".4".to_vec())));
}
#[test]
fn accessors_return_none_for_a_mismatched_direct_value() {
// `as_integer`/`as_array`/`as_dictionary`/`as_real_literal`/
// `as_stream_dict`/`as_stream_data` must reject a direct value of
// the wrong variant, not just a missing one — the same `_ => None`
// arm handles both cases.
let handle = ObjectHandle::string(b"not-an-integer".to_vec());
assert_eq!(handle.as_integer(), None);
assert!(handle.as_array().is_none());
assert!(handle.as_dictionary().is_none());
assert_eq!(handle.as_real_literal(), None);
assert!(handle.as_stream_dict().is_none());
assert!(handle.as_stream_data().is_none());
}
#[test]
fn accessors_return_none_for_an_indirect_handle_before_resolution() {
// `with_value` never performs hidden I/O to resolve an indirect
// handle (design, `Pdf` section), so today every indirect handle
// reads as "value not known" — surfaced as `None` from the typed
// accessors. `is_null` is not an exception: an unresolved indirect
// handle is not assumed to be null (matches qpdf's `isDirectNull`).
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), 0);
assert!(!handle.is_null());
assert_eq!(handle.as_integer(), None);
assert!(handle.as_array().is_none());
assert!(handle.as_dictionary().is_none());
assert_eq!(handle.as_real_literal(), None);
assert!(handle.as_stream_dict().is_none());
assert!(handle.as_stream_data().is_none());
}
}
#[cfg(test)]
mod stream_payload_sharing_tests {
use super::*;
use crate::token_filter::TokenFilterOutput;
use crate::tokenizer::{Token, TokenType};
struct NoopTokenFilter;
impl TokenFilter for NoopTokenFilter {
fn handle_token(
&mut self,
_token: &Token,
_output: &mut TokenFilterOutput<'_>,
) -> crate::pipeline::PipelineResult<()> {
Ok(())
}
}
#[test]
fn token_filter_registration_rejects_non_stream_handles() {
let scalar = ObjectHandle::integer(7);
assert!(!scalar.is_data_modified());
let mut no_op = NoopTokenFilter;
let token = Token::new(TokenType::Word, b"q".to_vec());
let mut output = TokenFilterOutput::new(None);
no_op.handle_token(&token, &mut output).unwrap();
let filter: Rc<RefCell<dyn TokenFilter>> = Rc::new(RefCell::new(no_op));
let error = scalar.add_token_filter(filter).unwrap_err();
assert!(matches!(
error,
Error::System(message)
if message == "operation for stream attempted on object of type integer"
));
assert!(!scalar.is_data_modified());
}
#[test]
fn stream_only_state_is_shared_by_aliases() {
let stream =
ObjectHandle::stream(ObjectHandle::dictionary(vec![]), Rc::new(b"abc".to_vec()));
let alias = stream.clone();
stream.mark_content_normalization_applied();
assert!(alias.content_normalization_applied());
let filter: Rc<RefCell<dyn TokenFilter>> = Rc::new(RefCell::new(NoopTokenFilter));
alias.add_token_filter(filter).unwrap();
assert!(stream.is_data_modified());
let debug = stream.with_value(|value| format!("{value:?}"));
assert!(debug.contains("<TokenFilter>"));
alias.replace_stream_data(Rc::new(b"replacement".to_vec()), None, None);
assert!(!stream.content_normalization_applied());
assert!(stream.is_data_modified());
}
// Every assertion below compares buffer identity against the buffer the
// test itself created, never bytes: a byte-equality assertion passes for a
// deep-copying implementation too.
fn payload_of(handle: &ObjectHandle) -> Rc<Vec<u8>> {
handle.as_stream_data().expect("stream value")
}
fn length_dict(len: usize) -> ObjectHandle {
ObjectHandle::dictionary(vec![(
b"Length".to_vec(),
ObjectHandle::integer(len as i64),
)])
}
// `QPDF::copyStreamData` takes the source stream's buffer
// (`libqpdf/QPDF.cc:2240`) and installs it on a second stream — in a
// different document — with no byte copy (`:2256-2258`), because "if the
// source stream is copied multiple times, we don't have to keep
// duplicating the memory" (`:2242-2244`). That is only expressible when
// both the accessor and the replacement entry point speak in shared
// buffers, as qpdf's own `getStreamDataBuffer` /
// `replaceStreamData(std::shared_ptr<Buffer>, ...)` pair does.
#[test]
fn one_buffer_backs_two_streams_without_copying() {
let shared = Rc::new(vec![0x5a; 4096]);
let source = ObjectHandle::stream(length_dict(4096), Rc::clone(&shared));
let destination = ObjectHandle::stream(length_dict(0), Rc::new(Vec::new()));
destination.replace_stream_data(source.as_stream_data().expect("stream data"), None, None);
assert!(Rc::ptr_eq(&payload_of(&source), &shared));
assert!(Rc::ptr_eq(&payload_of(&destination), &shared));
assert_eq!(
destination
.as_stream_dict()
.expect("stream dict")
.try_get_key(b"/Length")
.unwrap()
.as_integer(),
Some(4096),
);
}
// qpdf's payload is a `std::shared_ptr<Buffer>`
// (`libqpdf/qpdf/QPDF_Stream.hh:104`), so copying a stream value shares
// the bytes instead of duplicating them. The dictionary cannot be shared
// the same way: it is an `ObjectHandle`, so a shared one would carry a
// later `replace_stream_data`'s `/Length` across to a slot whose payload
// field did not change. Sharing the payload is safe precisely because
// replacement swaps the field rather than mutating the buffer.
#[test]
fn direct_value_clone_shares_the_stream_payload_but_not_the_dictionary() {
let shared = Rc::new(vec![0x5a; 4096]);
let stream = ObjectHandle::stream(length_dict(4096), Rc::clone(&shared));
let source_dict = stream.as_stream_dict().expect("source stream dict");
let copy = ObjectHandle::from_value(
stream
.direct_value_clone()
.expect("stream dict privatizes")
.expect("direct value"),
);
assert!(Rc::ptr_eq(&payload_of(©), &shared));
let copy_dict = copy.as_stream_dict().expect("copied stream dict");
assert!(!copy_dict.is_same_object_as(&source_dict));
copy_dict
.replace_key(b"/Length", ObjectHandle::integer(7))
.unwrap();
assert_eq!(
source_dict.try_get_key(b"/Length").unwrap().as_integer(),
Some(4096),
"each slot's dictionary describes only its own payload"
);
}
// The privatizing copy is `shallowCopy` on a dictionary, so a *direct*
// stream inside the stream dictionary hits `QPDF_Dictionary::copy`'s own
// `shallowCopy` of each direct child and the same `QPDF_Stream::copy`
// throw (`libqpdf/QPDF_Stream.cc:140-145`).
#[test]
fn direct_value_clone_propagates_a_nested_direct_streams_rejection() {
let inner = ObjectHandle::stream(length_dict(3), Rc::new(b"abc".to_vec()));
let outer = ObjectHandle::stream(
ObjectHandle::dictionary(vec![(b"Nested".to_vec(), inner)]),
Rc::new(b"xyz".to_vec()),
);
let error = outer
.direct_value_clone()
.expect_err("a direct stream in the stream dictionary is refused");
assert!(
matches!(error, Error::System(ref message)
if message == "stream objects cannot be cloned"),
"{error:?}"
);
}
// `direct_value_clone`'s early `slot.object_ref().is_some()` check already
// confirms this handle is direct before this match ever runs, so its
// `Reserved` arm can only be reached by a *direct* reserved handle --
// only constructible via `ObjectHandle::shallow_copy` on a reserved
// handle (`QPDF_Reserved::copy`, `libqpdf/QPDF_Reserved.cc:14-19`, never
// null, never a throw). A direct reserved handle used to fall into the
// same `Ok(None)` bucket as a
// genuinely indirect handle, so `Pdf::make_indirect_object_handle`
// reported "cannot make an already-indirect ObjectHandle indirect" for
// a handle its own `is_direct()` would confirm is not indirect.
#[test]
fn direct_value_clone_rejects_a_direct_reserved_handle_instead_of_reporting_already_indirect() {
let handle = ObjectHandle::new_reserved_direct();
assert!(handle.is_direct());
let error = handle
.direct_value_clone()
.expect_err("a direct reserved handle has no ObjectValue to clone");
assert!(
!error.to_string().contains("already-indirect"),
"the handle is direct, not indirect: {error}"
);
}
// `QPDF_Stream::copy` (`libqpdf/QPDF_Stream.cc:140-145`) ignores its
// `shallow` argument and unconditionally throws
// `std::runtime_error("stream objects cannot be cloned")`, so
// `shallowCopy` has no stream path to reach.
#[test]
fn shallow_copy_refuses_a_stream() {
let shared = Rc::new(vec![0x5a; 4096]);
let stream = ObjectHandle::stream(length_dict(4096), Rc::clone(&shared));
let error = stream.shallow_copy().expect_err("streams cannot be cloned");
assert!(
matches!(error, Error::System(ref message)
if message == "stream objects cannot be cloned"),
"qpdf throws std::runtime_error here, which this crate classifies \
as Error::System: {error:?}"
);
}
// A stream reached through the recursion is refused for the same reason:
// `QPDF_Dictionary::copy`/`QPDF_Array::copy` shallow-copy each *direct*
// child, so the throw comes from the same `QPDF_Stream::copy`.
#[test]
fn shallow_copy_refuses_a_direct_stream_nested_in_a_container() {
let stream = ObjectHandle::stream(length_dict(4096), Rc::new(vec![0x5a; 4096]));
let dictionary = ObjectHandle::dictionary(vec![(b"Nested".to_vec(), stream.clone())]);
let array = ObjectHandle::array(vec![ObjectHandle::array(vec![stream])]);
for container in [dictionary, array] {
let error = container
.shallow_copy()
.expect_err("a direct stream descendant is refused too");
assert!(
matches!(error, Error::System(ref message)
if message == "stream objects cannot be cloned"),
"{error:?}"
);
}
}
// An *indirect* stream child is not copied at all — it keeps its shared
// identity, exactly as `QPDF_Dictionary::copy`'s `value.isIndirect()`
// arm does — so the container copy succeeds.
#[test]
fn shallow_copy_keeps_an_indirect_stream_child_shared() {
let stream = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), -1);
stream.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: length_dict(4096),
stream_data: Some(Rc::new(vec![0x5a; 4096])),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 4096,
})));
let dictionary = ObjectHandle::dictionary(vec![(b"Nested".to_vec(), stream.clone())]);
let copy = dictionary
.shallow_copy()
.expect("an indirect stream child is shared, never copied");
assert!(copy
.try_get_key(b"/Nested")
.unwrap()
.is_same_object_as(&stream));
}
// `QPDF_Stream::getStreamDataBuffer` (`libqpdf/qpdf/QPDF_Stream.hh:39`)
// hands out the `shared_ptr` itself, which is what lets
// `QPDF::copyStreamData` (`libqpdf/QPDF.cc:2240,2256-2258`) give one
// buffer to a second stream without duplicating the memory.
#[test]
fn as_stream_data_hands_out_the_stored_payload_without_copying_it() {
let shared = Rc::new(vec![0x5a; 4096]);
let stream = ObjectHandle::stream(length_dict(4096), Rc::clone(&shared));
let handed_out = stream.as_stream_data().expect("stream data");
assert!(Rc::ptr_eq(&handed_out, &shared));
}
// An empty payload is still a buffer, not an absent one: it is handed out
// and shared like any other. qpdf nevertheless treats its zero byte length
// as the unknown-length boundary and removes `/Length`.
#[test]
fn an_empty_payload_is_shared_like_any_other() {
let shared = Rc::new(Vec::new());
let stream = ObjectHandle::stream(length_dict(4096), Rc::new(vec![0x5a; 4096]));
stream.replace_stream_data(Rc::clone(&shared), None, None);
assert!(Rc::ptr_eq(&payload_of(&stream), &shared));
assert!(!stream
.as_stream_dict()
.expect("stream dict")
.try_has_key(b"/Length")
.unwrap());
}
}
#[cfg(test)]
mod parsed_offset_tests {
use super::*;
#[test]
fn public_factory_direct_handles_default_to_no_offset_sentinel() {
for handle in [
ObjectHandle::null(),
ObjectHandle::boolean(true),
ObjectHandle::integer(1),
ObjectHandle::real(1.5),
ObjectHandle::name(b"Foo".to_vec()),
ObjectHandle::string(b"bar".to_vec()),
ObjectHandle::array(Vec::new()),
ObjectHandle::dictionary(Vec::new()),
] {
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
}
#[test]
fn new_indirect_unresolved_starts_at_no_offset_sentinel() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn set_parsed_offset_is_retained_once_set() {
let handle = ObjectHandle::integer(1);
handle.set_parsed_offset_if_unset(100);
assert_eq!(handle.get_parsed_offset(), 100);
}
#[test]
fn first_nonnegative_offset_is_retained_a_second_set_is_ignored() {
// "The first nonnegative offset assigned to a value is retained.
// Resolution, cache access, unparse, and writer planning do not
// recompute or replace it." (design, Parsed-Offset Contract)
let handle = ObjectHandle::integer(1);
handle.set_parsed_offset_if_unset(100);
handle.set_parsed_offset_if_unset(200);
assert_eq!(handle.get_parsed_offset(), 100);
}
#[test]
fn indirect_handle_honors_the_same_set_once_contract() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_parsed_offset_if_unset(100);
handle.set_parsed_offset_if_unset(200);
assert_eq!(handle.get_parsed_offset(), 100);
}
#[test]
fn zero_is_a_legitimate_parsed_offset_not_treated_as_unset() {
// The guard is a strict `< 0` check, so `0` (a real token-start
// offset) must count as "already set" and block later writes, the
// same as any other non-negative value.
let handle = ObjectHandle::integer(1);
handle.set_parsed_offset_if_unset(0);
assert_eq!(handle.get_parsed_offset(), 0);
handle.set_parsed_offset_if_unset(50);
assert_eq!(handle.get_parsed_offset(), 0);
}
}
#[cfg(test)]
mod resolution_state_tests {
/// A caller's provider may read the stream it was installed on from its
/// own `Drop`. Releasing the provider while the shared slot is still
/// mutably borrowed panicked with `RefCell already mutably borrowed`,
/// so `disconnect` takes it out under the borrow and drops it after.
#[test]
fn disconnect_releases_a_provider_whose_drop_reads_its_own_stream() {
// The reader runs from `Drop`, so it reaches the stream while
// `disconnect` is walking it. `CallbackProvider` supplies the
// `StreamDataProvider` half; this only adds the destructor.
struct ReadOnDrop {
stream: ObjectHandle,
dropped: Rc<std::cell::Cell<bool>>,
}
impl Drop for ReadOnDrop {
fn drop(&mut self) {
let _ = self.stream.type_code();
self.dropped.set(true);
}
}
struct ReaderHoldingProvider {
_reader: ReadOnDrop,
}
impl StreamDataProvider for ReaderHoldingProvider {}
let stream = ObjectHandle::stream(ObjectHandle::dictionary(vec![]), Rc::new(Vec::new()));
let dropped = Rc::new(std::cell::Cell::new(false));
let reader = ReadOnDrop {
stream: stream.clone(),
dropped: Rc::clone(&dropped),
};
// The destructor is the whole point; the data callback never runs in
// this test, so keep it a shared no-op rather than a fresh closure
// body of its own.
let provider: Rc<dyn StreamDataProvider> =
Rc::new(ReaderHoldingProvider { _reader: reader });
stream.with_value_mut(|value| {
if let Some(ObjectValue::Stream(stream)) = value {
stream.stream_data = None;
stream.stream_provider = Some(Rc::clone(&provider));
}
});
drop(provider);
stream.disconnect();
assert!(
dropped.get(),
"the provider must actually be released by disconnect"
);
assert!(stream.with_value(|value| matches!(
value,
Some(ObjectValue::Stream(stream)) if stream.stream_provider.is_none()
)));
}
use super::*;
#[test]
fn object_slot_shares_object_value_without_a_redundant_state_wrapper() {
let source = include_str!("object_handle.rs");
let state_name = ["Object", "State"].concat();
let resolved_name = [state_name.as_str(), "::Resolved"].concat();
let legacy_state_field = ["state: Rc<RefCell<", "ObjectValue>>"].concat();
let shared_field = ["shared: Rc<RefCell<", "SharedValueState>>"].concat();
let value_field = ["value: Object", "Value"].concat();
assert!(!source.contains(&format!("enum {state_name}")));
assert!(!source.contains(&resolved_name));
assert!(!source.contains(&legacy_state_field));
assert!(source.contains("struct SharedValueState"));
assert!(source.contains(&shared_field));
assert!(source.contains(&value_field));
}
#[test]
fn shared_value_state_has_no_unused_counter() {
let source = include_str!("object_handle.rs");
let field_name = ["mutation", "_generation"].concat();
assert!(!source.contains(&field_name));
}
#[test]
fn exclusive_direct_value_move_does_not_allocate_a_replacement_slot() {
let source = include_str!("object_handle.rs");
let start = source
.find("pub(crate) fn into_direct_value")
.expect("direct-value move helper");
let end = start
+ source[start..]
.find("\n /// Legacy direct-value extraction")
.expect("direct-value move helper end");
let body = &source[start..end];
assert!(
body.contains("ManuallyDrop"),
"exclusive direct values must move their slot without an empty replacement"
);
}
#[test]
fn direct_handle_is_always_resolved() {
// A direct handle has no resolution state to wait on — its value was
// known at construction time.
assert!(ObjectHandle::integer(1).is_resolved());
}
#[test]
fn into_direct_value_preserves_forward_children_when_the_parent_is_shared() {
let child = ObjectHandle::integer(1);
let parent = ObjectHandle::array(vec![child.clone()]);
let retained_parent = parent.clone();
assert!(parent.into_direct_value().is_none());
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, NO_PARSED_OFFSET);
owner.set_resolved(ObjectValue::Array(vec![retained_parent]));
assert_eq!(child.containing_object_refs(), vec![owner_ref]);
}
#[test]
fn fresh_indirect_handle_is_not_resolved() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
assert!(!handle.is_resolved());
}
#[test]
fn set_resolved_marks_the_handle_resolved_and_exposes_its_value() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(7));
assert!(handle.is_resolved());
assert_eq!(handle.as_integer(), Some(7));
}
#[test]
fn resolving_to_qpdf_null_resets_the_cached_source_offset() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(7));
handle.set_parsed_offset_if_unset(100);
handle.set_resolved(ObjectValue::Null);
assert!(handle.is_null());
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn set_resolved_null_marks_the_handle_resolved_to_null() {
// A dangling or broken reference uses the same observable null value
// as a genuinely parsed literal null.
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Null);
assert!(handle.is_resolved());
assert!(handle.is_null());
assert_eq!(handle.as_integer(), None);
}
/// A null-resolved indirect handle has the same value-layer state as a
/// parsed literal null; there is no separate qpdf missing sentinel.
#[test]
fn set_resolved_with_a_null_value_uses_the_null_value_layer() {
let null = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
null.set_resolved(ObjectValue::Null);
assert!(null.is_resolved());
assert!(null.is_null());
let shared = null.0.borrow().shared.clone();
let state = shared.borrow();
assert!(
matches!(&state.value, ObjectValue::Null),
"`set_resolved(Null)` must leave the slot in the value layer"
);
}
#[test]
fn set_resolved_null_resets_a_previously_recorded_parsed_offset() {
// Design's Parsed-Offset Contract: "An absent, freed, dangling,
// cyclic, or otherwise unresolvable indirect object ... resolves to
// null with parsed offset -1." A handle that was already resolved
// with a real (non-negative) offset -- e.g. natively parsed, then
// later deleted -- must not keep reporting its former body's source
// position once it reads as null.
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(7));
handle.set_parsed_offset_if_unset(100);
assert_eq!(handle.get_parsed_offset(), 100);
handle.set_resolved(ObjectValue::Null);
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
assert!(handle.is_null());
}
#[test]
fn set_resolved_is_a_no_op_on_a_direct_handle() {
// Direct handles have no resolution state; calling the setter must not
// panic and must leave the original value untouched.
let handle = ObjectHandle::integer(42);
handle.set_resolved(ObjectValue::Integer(99));
handle.set_resolved(ObjectValue::Null);
assert_eq!(handle.as_integer(), Some(42));
}
#[test]
fn from_value_constructs_a_direct_handle_at_the_offset_sentinel() {
let handle = ObjectHandle::from_value(ObjectValue::Integer(3));
assert!(handle.is_direct());
assert_eq!(handle.as_integer(), Some(3));
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn disconnect_replaces_a_resolved_value_with_destroyed_state() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(7));
handle.disconnect_and_destroy();
assert!(handle.is_resolved());
assert!(!handle.is_null());
assert_eq!(handle.type_code().expect("type code"), 14);
assert_eq!(handle.as_integer(), None);
}
#[test]
fn disconnect_resets_a_previously_recorded_parsed_offset() {
// Mirrors `set_resolved_null_resets_a_previously_recorded_parsed_offset`
// for the same Parsed-Offset Contract clause: a handle a caller
// keeps alive past its owning `Pdf`'s drop must not keep reporting
// its former body's source position once it reads as null.
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(7));
handle.set_parsed_offset_if_unset(100);
assert_eq!(handle.get_parsed_offset(), 100);
handle.disconnect_and_destroy();
assert_eq!(handle.get_parsed_offset(), NO_PARSED_OFFSET);
}
#[test]
fn disconnect_clears_a_previously_recorded_description() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(7));
handle.set_description("input.pdf, object 1 0 at offset $PO", 100);
assert!(handle
.description()
.windows(b"offset".len())
.any(|window| window == b"offset"));
handle.disconnect_and_destroy();
assert_eq!(handle.description(), b"");
}
#[test]
fn disconnect_destroys_a_cached_non_null_object_even_if_its_identity_was_cleared() {
let handle = ObjectHandle::integer(42);
handle.disconnect_and_destroy();
assert!(handle.is_direct());
assert_eq!(handle.type_code().unwrap(), 14);
}
#[test]
fn strong_count_reports_a_direct_handles_rc_count_too() {
let handle = ObjectHandle::integer(1);
assert_eq!(handle.strong_count(), 1);
let clone = handle.clone();
assert_eq!(handle.strong_count(), 2);
drop(clone);
assert_eq!(handle.strong_count(), 1);
}
#[test]
fn disconnect_drops_the_strong_rc_a_resolved_value_holds_to_a_cyclic_child() {
// Two objects that reference each other (e.g. a /Pages node and a
// page's /Parent) form a strong Rc cycle once both are resolved:
// each slot's value embeds the other's canonical handle. `disconnect`
// (called by `Pdf::drop` for every registry entry) must sever that
// cycle so both slots free once external references are gone.
let a = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
let b = ObjectHandle::new_indirect_unresolved(ObjectRef::new(2, 0), 0);
a.set_resolved(ObjectValue::Dictionary(
[(b"Kid".to_vec(), b.clone())].into_iter().collect(),
));
b.set_resolved(ObjectValue::Dictionary(
[(b"Parent".to_vec(), a.clone())].into_iter().collect(),
));
assert_eq!(a.strong_count(), 2, "held by this test and by b's value");
assert_eq!(b.strong_count(), 2, "held by this test and by a's value");
a.disconnect_and_destroy();
b.disconnect_and_destroy();
assert_eq!(a.strong_count(), 1, "only this test's own handle remains");
assert_eq!(b.strong_count(), 1, "only this test's own handle remains");
}
/// Build a direct stream whose data source is a provider retaining
/// `source`, the shape `CopiedStreamDataProvider` installs when a stream
/// is copied out of another document. The provider `Rc` is created inline
/// so the only strong reference to `source` it introduces is the one the
/// stream itself holds.
fn direct_stream_with_provider_for(source: &ObjectHandle) -> ObjectHandle {
let stream = ObjectHandle::stream(ObjectHandle::dictionary(vec![]), Rc::new(Vec::new()));
stream.with_value_mut(|value| {
if let Some(ObjectValue::Stream(stream)) = value {
stream.stream_data = None;
stream.stream_provider = Some(copied_stream_data_provider(source.clone()));
}
});
stream
}
#[test]
fn disconnect_clears_a_direct_streams_stream_provider() {
// A stream data provider retains a handle from the document the
// stream was copied out of, so a provider left in place after
// teardown keeps that document's object alive. An indirect stream is
// replaced wholesale by the `Destroyed` sentinel, which takes its
// provider with it; a direct stream a caller still holds survives the
// walk, so the walk itself has to clear the provider.
let source = ObjectHandle::new_indirect_unresolved(ObjectRef::new(2, 0), 0);
source.set_resolved(ObjectValue::Integer(7));
let stream = direct_stream_with_provider_for(&source);
let owner = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
owner.set_resolved(ObjectValue::Dictionary(
[(b"S".to_vec(), stream.clone())].into_iter().collect(),
));
assert!(stream.has_stream_data_provider());
assert_eq!(
source.strong_count(),
2,
"held by this test and by the stream's provider"
);
owner.disconnect_and_destroy();
assert!(
!stream.has_stream_data_provider(),
"the walk must clear a direct stream's provider"
);
assert_eq!(
source.strong_count(),
1,
"only this test's own handle remains"
);
}
#[test]
fn disconnect_clears_the_provider_of_a_direct_stream_it_is_called_on() {
// The same clearing applies when the walk starts at the stream
// rather than reaching it through a container.
let source = ObjectHandle::new_indirect_unresolved(ObjectRef::new(2, 0), 0);
source.set_resolved(ObjectValue::Integer(7));
let stream = direct_stream_with_provider_for(&source);
assert_eq!(source.strong_count(), 2);
stream.disconnect();
assert!(!stream.has_stream_data_provider());
assert_eq!(
source.strong_count(),
1,
"only this test's own handle remains"
);
}
#[test]
fn disconnect_leaves_a_direct_streams_replacement_data_in_place() {
// Only the provider slot is cleared: the replacement buffer and the
// dictionary the walk descends into are left as they were.
let data = Rc::new(b"stream bytes".to_vec());
let stream_dict = ObjectHandle::dictionary(vec![]);
let stream = ObjectHandle::stream(stream_dict.clone(), data.clone());
let owner = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
owner.set_resolved(ObjectValue::Dictionary(
[(b"S".to_vec(), stream.clone())].into_iter().collect(),
));
owner.disconnect_and_destroy();
assert!(!stream.has_stream_data_provider());
assert!(stream
.as_stream_data()
.is_some_and(|actual| Rc::ptr_eq(&actual, &data)));
assert!(stream
.as_stream_dict()
.expect("stream dictionary")
.is_same_object_as(&stream_dict));
}
#[test]
fn disconnect_walks_a_direct_container_that_holds_itself() {
// Collecting a node's children reads each child's own shared state to
// test `is_indirect`, and a direct container that holds itself makes
// that read re-enter the node the walk is already positioned on. The
// walk must not be holding a mutable borrow of that node by then.
// `replace_key` privatizes the value it stores, so the cycle is
// installed on the map directly to keep the entry the very same
// allocation as its container.
let owner = ObjectHandle::dictionary(vec![]);
let self_reference = owner.clone();
owner.with_value_mut(|value| {
if let Some(ObjectValue::Dictionary(entries)) = value {
entries.insert(b"/Self".to_vec(), self_reference);
}
});
owner.disconnect();
let entries = owner.as_dictionary().expect("the container survives");
assert_eq!(entries.len(), 1);
assert!(entries
.values()
.next()
.expect("its single entry")
.is_same_object_as(&owner));
}
#[test]
fn disconnect_and_destroy_still_drops_an_indirect_streams_provider() {
// The indirect path already released the provider by replacing the
// whole value with `Destroyed`; clearing the slot during the walk
// must not change that outcome.
let source = ObjectHandle::new_indirect_unresolved(ObjectRef::new(2, 0), 0);
source.set_resolved(ObjectValue::Integer(7));
let stream = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
stream.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: None,
stream_provider: Some(copied_stream_data_provider(source.clone())),
filter_on_write: true,
stream_length: 0,
stream_token_filters: Default::default(),
content_normalization_applied: false,
})));
assert!(stream.has_stream_data_provider());
assert_eq!(source.strong_count(), 2);
stream.disconnect_and_destroy();
assert!(!stream.has_stream_data_provider());
assert_eq!(stream.type_code().expect("type code"), 14);
assert_eq!(
source.strong_count(),
1,
"only this test's own handle remains"
);
}
#[test]
fn debug_format_does_not_recurse_through_a_self_referential_handle() {
// A one-object `/Self 1 0 R` dictionary: the handle's own resolved
// value embeds itself. A derived `Debug` would recurse into the
// same slot forever and overflow the stack; formatting must stop at
// the indirect boundary instead.
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Dictionary(
[(b"Self".to_vec(), handle.clone())].into_iter().collect(),
));
let formatted = format!("{handle:?}");
assert!(formatted.contains("ObjectHandle::Indirect"));
assert!(formatted.contains("Resolved(..)"));
}
#[test]
fn debug_format_does_not_recurse_through_a_reciprocal_cycle() {
let a = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
let b = ObjectHandle::new_indirect_unresolved(ObjectRef::new(2, 0), 0);
a.set_resolved(ObjectValue::Dictionary(
[(b"Kid".to_vec(), b.clone())].into_iter().collect(),
));
b.set_resolved(ObjectValue::Dictionary(
[(b"Parent".to_vec(), a.clone())].into_iter().collect(),
));
let formatted = format!("{a:?}");
assert!(formatted.contains("ObjectHandle::Indirect"));
}
#[test]
fn debug_format_of_a_direct_handle_shows_its_value() {
let handle = ObjectHandle::integer(7);
assert!(format!("{handle:?}").contains("ObjectHandle::Direct"));
}
#[test]
fn debug_format_summarizes_every_indirect_resolution_state() {
let unresolved = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
assert!(format!("{unresolved:?}").contains("Unresolved"));
let reserved = ObjectHandle::new_reserved_direct();
assert!(format!("{reserved:?}").contains("Reserved"));
let null = ObjectHandle::new_indirect_unresolved(ObjectRef::new(2, 0), 0);
null.set_resolved(ObjectValue::Null);
assert!(format!("{null:?}").contains("Resolved(..)"));
let destroyed = ObjectHandle::new_indirect_unresolved(ObjectRef::new(3, 0), 0);
destroyed.set_resolved(ObjectValue::Integer(1));
destroyed.disconnect_and_destroy();
assert!(format!("{destroyed:?}").contains("Destroyed"));
}
}
#[cfg(test)]
mod internal_state_value_tests {
use super::*;
use crate::writer::object::unparse_object_value;
#[test]
fn internal_qpdf_values_use_their_value_layer_error_contracts() {
for (value, expected) in [
(
ObjectValue::Unresolved,
"attempted to unparse an unresolved QPDFObjectHandle",
),
(
ObjectValue::Reserved,
"QPDFObjectHandle: attempting to unparse a reserved object",
),
(
ObjectValue::Destroyed,
"attempted to unparse a QPDFObjectHandle from a destroyed QPDF",
),
] {
let mut out = Vec::new();
let unparse_error = crate::writer::output::with_buffer_sink(&mut out, |out| {
unparse_object_value(&value, out)
})
.expect_err("internal qpdf values cannot unparse as PDF values");
assert!(
unparse_error.to_string().contains(expected),
"unexpected unparse error: {unparse_error:?}"
);
}
let reserved_copy = shallow_copy_value(&ObjectValue::Reserved).expect("reserved copies");
assert!(matches!(reserved_copy, ObjectValue::Reserved));
let unresolved_copy = shallow_copy_value(&ObjectValue::Unresolved)
.expect_err("unresolved copy is a qpdf logic error");
assert!(unresolved_copy
.to_string()
.contains("attempted to shallow copy an unresolved QPDFObjectHandle"));
let destroyed_copy = shallow_copy_value(&ObjectValue::Destroyed)
.expect_err("destroyed copy is a qpdf logic error");
assert!(destroyed_copy
.to_string()
.contains("attempted to shallow copy QPDFObjectHandle from destroyed QPDF"));
let unresolved = ObjectHandle::from_value(ObjectValue::Unresolved);
assert_eq!(
unresolved
.try_unparse_resolved()
.expect_err("an unresolved value cannot be unparsed")
.to_string(),
"attempted to unparse an unresolved QPDFObjectHandle"
);
}
}
#[cfg(test)]
mod rounded_accessor_tests {
use super::*;
#[test]
fn boolean_handle_round_trips_its_value() {
assert_eq!(ObjectHandle::boolean(true).as_boolean(), Some(true));
assert_eq!(ObjectHandle::boolean(false).as_boolean(), Some(false));
assert_eq!(ObjectHandle::integer(1).as_boolean(), None);
}
#[test]
fn as_real_accepts_both_real_and_real_literal_like_object_does() {
// Mirrors the handle's own `Real(v) | RealLiteral { value: v, .. }`
// arm — a real-literal value is still "a real"
// for callers that don't care about the source spelling.
assert_eq!(ObjectHandle::real(1.5).as_real(), Some(1.5));
assert_eq!(
ObjectHandle::real_literal(0.4, b".4".to_vec()).as_real(),
Some(0.4)
);
assert_eq!(ObjectHandle::integer(1).as_real(), None);
}
#[test]
fn name_and_string_handles_round_trip_their_bytes() {
assert_eq!(
ObjectHandle::name(b"Type".to_vec()).as_name(),
Some(b"Type".to_vec())
);
assert_eq!(
ObjectHandle::string(b"hi".to_vec()).as_string(),
Some(b"hi".to_vec())
);
assert!(ObjectHandle::name(b"Type".to_vec()).as_string().is_none());
assert!(ObjectHandle::string(b"hi".to_vec()).as_name().is_none());
}
#[test]
fn rounded_accessors_return_none_for_an_indirect_handle_before_resolution() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), 0);
assert_eq!(handle.as_boolean(), None);
assert_eq!(handle.as_real(), None);
assert!(handle.as_name().is_none());
assert!(handle.as_string().is_none());
assert_eq!(handle.object_ref(), Some(ObjectRef::new(9, 0)));
}
}
#[cfg(test)]
mod token_value_tests {
use super::*;
#[test]
fn operator_handle_round_trips_its_bytes() {
let handle = ObjectHandle::operator(b"q".to_vec());
assert_eq!(handle.as_operator(), Some(b"q".to_vec()));
assert!(handle.as_inline_image().is_none());
}
#[test]
fn inline_image_handle_round_trips_its_bytes() {
let handle = ObjectHandle::inline_image(b"\x00\x01raw".to_vec());
assert_eq!(handle.as_inline_image(), Some(b"\x00\x01raw".to_vec()));
assert!(handle.as_operator().is_none());
}
}
#[cfg(test)]
mod is_resolved_visibility_tests {
use super::*;
#[test]
fn is_resolved_is_usable_the_same_way_a_pub_fn_is() {
// This test doesn't exercise new behavior (resolution_state_tests
// already covers is_resolved's semantics exhaustively) — it exists
// only to keep a compile-time witness that `is_resolved` stays
// `pub`, the same way the rest of this module's public surface has
// a direct caller in-tree. The positive compile check here is the
// useful signal for this API.
let handle = ObjectHandle::integer(1);
let _: bool = ObjectHandle::is_resolved(&handle);
}
}
#[cfg(test)]
mod type_code_tests {
use super::*;
#[test]
fn object_values_report_qpdf_internal_state_types() {
let cases = [
(ObjectValue::Unresolved, 13, "unresolved"),
(ObjectValue::Reserved, 1, "reserved"),
(ObjectValue::Destroyed, 14, "destroyed"),
];
for (value, code, name) in cases {
assert_eq!(value.type_code(), code, "{name}");
assert_eq!(value.type_name(), name);
}
}
#[test]
fn direct_scalar_and_container_type_codes_match_qpdf_ordinals() {
// Ordinals and strings verified directly against the pinned qpdf
// 11.9.0 source: `include/qpdf/Constants.h:108-127`
// (`qpdf_object_type_e`) for the numbers, and each type's own
// `libqpdf/QPDF_*.cc` `QPDFValue(::ot_*, "...")` constructor for the
// name string (e.g. `libqpdf/QPDF_InlineImage.cc:6` for the
// hyphenated `"inline-image"`).
let cases: &[(ObjectHandle, u8, &str)] = &[
(ObjectHandle::null(), 2, "null"),
(ObjectHandle::boolean(true), 3, "boolean"),
(ObjectHandle::integer(1), 4, "integer"),
(ObjectHandle::real(1.5), 5, "real"),
(ObjectHandle::real_literal(0.4, b".4".to_vec()), 5, "real"),
(ObjectHandle::string(b"s".to_vec()), 6, "string"),
(ObjectHandle::name(b"N".to_vec()), 7, "name"),
(ObjectHandle::array(vec![]), 8, "array"),
(ObjectHandle::dictionary(vec![]), 9, "dictionary"),
(ObjectHandle::operator(b"q".to_vec()), 11, "operator"),
(
ObjectHandle::inline_image(b"d".to_vec()),
12,
"inline-image",
),
];
for (handle, code, name) in cases {
assert_eq!(handle.type_code().expect("type code"), *code, "{name}");
assert_eq!(handle.type_name().expect("type name"), *name);
assert!(!handle.is_reserved(), "ordinary {name} is not reserved");
}
}
#[test]
fn stream_handle_type_code_is_stream() {
let dict = ObjectHandle::dictionary(vec![]);
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(Vec::new())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
assert_eq!(stream.type_code().expect("type code"), 10);
assert_eq!(stream.type_name().expect("type name"), "stream");
}
#[test]
fn stream_subclass_layout_is_not_carried_by_common_values() {
assert!(
std::mem::size_of::<ObjectValue>() < std::mem::size_of::<StreamValue>(),
"the common value enum must not inline the stream subclass payload"
);
}
#[test]
fn type_code_resolves_an_unresolved_indirect_handle_before_classifying() {
let (handle, _resolver) = crate::object_handle::identity_tests::resolver_bearing_handle(
ObjectValue::Dictionary(std::collections::BTreeMap::new()),
);
assert!(!handle.is_resolved());
assert_eq!(
handle.type_code().expect("type code"),
9,
"qpdf ot_dictionary"
);
assert!(handle.is_resolved());
}
#[test]
fn type_name_resolves_an_unresolved_indirect_handle_before_classifying() {
let (handle, _resolver) =
crate::object_handle::identity_tests::resolver_bearing_handle(ObjectValue::Integer(7));
assert_eq!(handle.type_name().expect("type name"), "integer");
assert!(handle.is_resolved());
}
#[test]
fn type_code_and_type_name_propagate_resolver_errors() {
let (handle, _resolver) =
crate::object_handle::identity_tests::error_resolving_handle(ObjectRef::new(21, 0));
assert_eq!(
handle
.type_code()
.expect_err("type classification must be fallible")
.to_string(),
"resolver failed"
);
let (handle, _resolver) =
crate::object_handle::identity_tests::error_resolving_handle(ObjectRef::new(22, 0));
assert_eq!(
handle
.type_name()
.expect_err("type name must be fallible")
.to_string(),
"resolver failed"
);
assert!(!handle.is_reserved());
}
#[test]
fn destroyed_handle_reports_destroyed_after_indirect_metadata_is_cleared() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(1));
handle.disconnect_and_destroy();
assert_eq!(handle.type_code().expect("type code"), 14, "ot_destroyed");
assert_eq!(handle.type_name().expect("type name"), "destroyed");
assert!(!handle.is_reserved());
}
#[test]
fn null_resolved_indirect_handle_reports_null_not_a_distinct_missing_code() {
// qpdf has no separate "missing" ot_* code — a dangling/broken
// reference presents as ot_null, matching the qpdf null fallback's
// documented is_null()==true contract.
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Null);
assert_eq!(handle.type_code().expect("type code"), 2, "ot_null");
assert_eq!(handle.type_name().expect("type name"), "null");
assert!(!handle.is_reserved());
}
#[test]
fn resolved_indirect_handle_reports_its_real_value_type() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(7));
assert_eq!(handle.type_code().expect("type code"), 4, "ot_integer");
assert_eq!(handle.type_name().expect("type name"), "integer");
}
#[test]
fn unparse_resolved_covers_every_direct_serializer_arm_for_a_nested_array_dict_and_stream() {
// Keep this at a shallow, portable depth. The direct serializer
// protects each recursive descent with stacker and exercises every
// container arm (Array, Dictionary, Stream) without relying on the
// legacy raw-object tree or its recursive Drop implementation.
let stream = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), 0);
stream.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![(
b"Length".to_vec(),
ObjectHandle::integer(0),
)]),
stream_data: Some(Rc::new(Vec::new())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let inner_dict = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::null()),
(b"B".to_vec(), ObjectHandle::integer(2)),
]);
let array = ObjectHandle::array(vec![
ObjectHandle::integer(1),
inner_dict,
stream,
ObjectHandle::array(vec![ObjectHandle::name(b"Nested".to_vec())]),
]);
assert_eq!(
array.unparse_resolved(),
b"[ 1 << /B 2 >> 9 0 R [ /Nested ] ]"
);
}
#[test]
fn direct_scalar_unparses_like_object_write_pdf() {
assert_eq!(ObjectHandle::integer(7).unparse(), b"7");
assert_eq!(ObjectHandle::boolean(true).unparse(), b"true");
assert_eq!(ObjectHandle::name(b"Type".to_vec()).unparse(), b"/Type");
}
#[test]
fn indirect_handle_unparse_is_always_the_reference_form_even_before_resolution() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(7, 2), 0);
assert_eq!(handle.unparse(), b"7 2 R");
}
#[test]
fn indirect_handle_unparse_resolved_falls_back_to_null_before_resolution() {
// No hidden I/O: an unresolved indirect handle's value is not
// known, so unparse_resolved reports the same as materialize()'s
// own documented null fallback rather than triggering resolution.
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(7, 2), 0);
assert_eq!(handle.unparse_resolved(), b"null");
}
#[test]
fn resolved_indirect_handle_unparse_resolved_shows_the_real_value() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(7, 2), 0);
handle.set_resolved(ObjectValue::Integer(42));
assert_eq!(handle.unparse(), b"7 2 R");
assert_eq!(handle.unparse_resolved(), b"42");
}
#[test]
fn stream_value_unparse_resolved_still_reports_the_reference_form() {
// QPDF_Stream::unparse() (libqpdf/QPDF_Stream.cc:173-178) always
// returns its own "N G R" — mirrored here rather than inlining the
// stream's dictionary/data.
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(0))]);
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), 0);
handle.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(Vec::new())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
assert_eq!(handle.unparse(), b"9 0 R");
assert_eq!(handle.unparse_resolved(), b"9 0 R");
}
#[test]
fn direct_array_unparse_writes_indirect_children_as_references_not_recursed() {
let (child, _resolver) = identity_tests::resolver_bearing_handle(ObjectValue::Integer(5));
let array = ObjectHandle::array(vec![ObjectHandle::integer(1), child]);
assert_eq!(array.unparse(), b"[ 1 20 0 R ]");
}
#[test]
fn unparse_resolved_writes_an_unresolvable_indirect_array_child_as_a_reference() {
// qpdf's array unparse resolves each element only to read the
// element's OWN object/generation identity (`item.second->resolve();
// auto og = item.second->getObjGen();`, `libqpdf/QPDF_Array.cc:
// 130-132`) -- that identity is already known on the handle before
// resolution ever runs, so qpdf never needs resolution to SUCCEED to
// emit `N G R` for a dangling or otherwise unresolvable child. Drop
// the child's resolver to force `try_dereference` to fail. Reading the
// raw qpdf identity before trying to resolve it keeps one unresolvable
// element from failing the whole array.
let (child, resolver) = identity_tests::resolver_bearing_handle(ObjectValue::Integer(5));
drop(resolver);
let array = ObjectHandle::array(vec![ObjectHandle::integer(1), child]);
assert_eq!(
array
.try_unparse_resolved()
.expect("an unresolvable indirect child must not fail the whole array"),
b"[ 1 20 0 R ]"
);
}
#[test]
fn unparse_resolved_writes_a_raw_generation_without_an_object_ref_projection() {
let (handle, resolver) = identity_tests::resolver_bearing_handle(ObjectValue::Integer(5));
let raw = handle.promote_to_indirect_qpdf_obj_gen(
QpdfObjGen::new(9, 65_535),
20,
Rc::downgrade(&resolver),
);
assert_eq!(raw.object_ref(), None);
let array = ObjectHandle::array(vec![raw]);
assert_eq!(
array
.try_unparse_resolved()
.expect("raw qpdf identity is sufficient for a reference form"),
b"[ 9 65535 R ]"
);
}
#[test]
fn a_direct_stream_value_unparse_resolved_inlines_rather_than_referencing() {
// A *direct* Stream `ObjectValue` is a Rust-only construction shape
// reachable through the public `ObjectHandle::stream` factory. qpdf
// creates streams as indirect objects (`QPDF.cc:1912-1923`), so this
// case has no qpdf output contract; retain the existing explicit
// factory behavior without introducing another representation.
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(2))]);
let handle = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(b"ab".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
assert_eq!(
handle.unparse_resolved(),
b"<< /Length 2 >>\nstream\nab\nendstream"
);
}
#[test]
fn destroyed_direct_handle_unparse_and_unparse_resolved_fall_back_to_null() {
// Disconnect clears the shared slot's indirect metadata, so both
// entry points reach the existing infallible fallback for the
// `Destroyed` value. qpdf's `QPDF_Destroyed::unparse()`
// (`libqpdf/QPDF_Destroyed.cc:24-29`) throws `std::logic_error`, but
// neither method has an exception channel to mirror that with.
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), 0);
handle.set_resolved(ObjectValue::Integer(7));
handle.disconnect_and_destroy();
assert_eq!(handle.unparse(), b"null");
assert_eq!(handle.unparse_resolved(), b"null");
}
#[test]
fn unparse_resolved_omits_a_direct_null_dictionary_entry() {
// qpdf's QPDF_Dictionary::unparse() (libqpdf/QPDF_Dictionary.cc:59-69)
// skips any entry whose value isNull(), matching the PDF-spec
// equivalence between an explicit null value and a missing key.
let dict = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::null()),
(b"B".to_vec(), ObjectHandle::integer(1)),
]);
assert_eq!(dict.unparse_resolved(), b"<< /B 1 >>");
}
#[test]
fn unparse_resolved_omits_an_already_resolved_null_indirect_dictionary_entry() {
// The same qpdf rule applies to an indirect child, since qpdf's
// isNull() dereferences before checking -- but only when this
// child's value is already known (is_resolved()), never by forcing
// new resolution (see the "keeps a not-yet-resolved" test below).
let missing = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), 0);
missing.set_resolved(ObjectValue::Null);
let dict = ObjectHandle::dictionary(vec![
(b"A".to_vec(), missing),
(b"B".to_vec(), ObjectHandle::integer(1)),
]);
assert_eq!(dict.unparse_resolved(), b"<< /B 1 >>");
}
#[test]
fn unparse_resolved_keeps_a_resolved_non_null_indirect_dictionary_entry() {
// qpdf resolves the child while checking nullness, then retains a
// non-null indirect child as its reference form.
let (unresolved, _resolver) =
identity_tests::resolver_bearing_handle(ObjectValue::Integer(9));
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), unresolved)]);
assert_eq!(dict.unparse_resolved(), b"<< /A 20 0 R >>");
}
#[test]
fn unparse_resolved_resolves_an_unresolved_indirect_dictionary_child() {
let (null_child, _resolver) = identity_tests::resolver_bearing_handle(ObjectValue::Null);
let dict = ObjectHandle::dictionary(vec![
(b"A".to_vec(), null_child.clone()),
(b"B".to_vec(), ObjectHandle::integer(1)),
]);
assert_eq!(dict.unparse_resolved(), b"<< /B 1 >>");
assert!(null_child.is_resolved());
}
#[test]
fn unparse_resolved_resolves_an_unresolved_top_level_handle() {
let (handle, _resolver) = identity_tests::resolver_bearing_handle(ObjectValue::Integer(42));
assert_eq!(handle.unparse_resolved(), b"42");
assert!(handle.is_resolved());
}
#[test]
fn unparse_resolved_omits_nulls_in_a_nested_dictionary_inside_an_array() {
let inner = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::null())]);
let array = ObjectHandle::array(vec![inner]);
assert_eq!(array.unparse_resolved(), b"[ << >> ]");
}
#[test]
fn unparse_resolved_does_not_omit_null_array_elements() {
// Only dictionary keys are omitted for a null value; array elements
// keep their position (QPDF_Array::unparse(),
// libqpdf/QPDF_Array.cc:123-140, explicitly fills gaps with the
// literal "null" token rather than skipping them).
let array = ObjectHandle::array(vec![ObjectHandle::integer(1), ObjectHandle::null()]);
assert_eq!(array.unparse_resolved(), b"[ 1 null ]");
}
#[test]
fn unparse_resolved_preserves_the_first_byte_of_a_slashless_dictionary_key() {
let dictionary = ObjectHandle::dictionary(Vec::new());
dictionary
.replace_key(b"#A", ObjectHandle::integer(1))
.expect("programmatic dictionary mutation");
assert_eq!(dictionary.unparse_resolved(), b"<< #A 1 >>");
}
#[test]
fn unparse_resolved_falls_back_but_try_unparse_resolved_reports_unresolved_values() {
let handle = ObjectHandle::from_value(ObjectValue::Unresolved);
assert_eq!(handle.unparse_resolved(), b"null");
assert_eq!(
handle
.try_unparse_resolved()
.expect_err("strict qpdf unparse must reject unresolved values")
.to_string(),
"attempted to unparse an unresolved QPDFObjectHandle"
);
}
#[test]
fn unparse_resolved_uses_the_canonical_form_for_an_unsafe_real_literal() {
let handle = ObjectHandle::real_literal(0.4, b"not-a-real".to_vec());
assert_eq!(handle.unparse_resolved(), b"0.4");
}
#[test]
fn try_unparse_resolved_reports_missing_original_data_for_a_direct_stream() {
let handle = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(Vec::new()),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
assert!(handle
.try_unparse_resolved()
.expect_err("a direct original stream has no source")
.to_string()
.contains("pipeStreamData called for original direct stream"));
}
}
#[cfg(test)]
mod unparse_object_tests {
use super::identity_tests::{error_resolving_handle, resolver_bearing_handle};
use super::*;
use crate::writer::object::{
dict_is_sig_with_byte_range, unparse_child as unparse_child_to_sink, visible_dict_entries,
ObjectWriterEmissionVecTestExt,
};
fn unparse_child(handle: &ObjectHandle, out: &mut Vec<u8>) -> Result<()> {
crate::writer::output::with_buffer_sink(out, |out| unparse_child_to_sink(handle, out))
}
fn compact_string_hook(out: &mut Vec<u8>, value: &[u8]) -> Result<()> {
out.extend_from_slice(b"<hook:");
out.extend_from_slice(value);
out.extend_from_slice(b">");
Ok(())
}
fn qdf_string_hook(out: &mut Vec<u8>, value: &[u8]) -> Result<()> {
out.extend_from_slice(b"{hook:");
out.extend_from_slice(value);
out.extend_from_slice(b"}");
Ok(())
}
#[test]
fn unparse_resolved_emits_a_raw_qpdf_object_reference() {
let handle = ObjectHandle::new_indirect_unresolved_qpdf_obj_gen_with_identity(
QpdfObjGen::new(5, 65_536),
NO_PARSED_OFFSET,
None,
None,
);
handle.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(Vec::new()),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
assert_eq!(handle.try_unparse_resolved().unwrap(), b"5 65536 R");
}
#[test]
fn unparse_emits_a_raw_qpdf_object_reference_for_unprojectable_generation() {
let handle = ObjectHandle::new_indirect_unresolved_qpdf_obj_gen_with_identity(
QpdfObjGen::new(5, 65_536),
NO_PARSED_OFFSET,
None,
None,
);
handle.set_resolved(ObjectValue::Integer(45));
assert_eq!(handle.unparse(), b"5 65536 R");
}
#[test]
fn visible_dict_entries_keeps_non_null_and_drops_direct_null() {
let entries: Vec<(Vec<u8>, ObjectHandle)> = vec![
(b"Zulu".to_vec(), ObjectHandle::integer(26)),
(b"DirectNull".to_vec(), ObjectHandle::null()),
];
let visible = visible_dict_entries(&entries).expect("no resolver needed");
let keys: Vec<&[u8]> = visible.iter().map(|(k, _)| k.as_slice()).collect();
assert_eq!(keys, [b"Zulu".as_slice()]);
}
#[test]
fn visible_dict_entries_resolves_and_drops_an_indirect_null() {
let (indirect_null, _resolver) = resolver_bearing_handle(ObjectValue::Null);
let entries: Vec<(Vec<u8>, ObjectHandle)> = vec![(b"RefNull".to_vec(), indirect_null)];
let visible = visible_dict_entries(&entries).unwrap();
assert!(visible.is_empty());
}
#[test]
fn visible_dict_entries_propagates_a_dropped_document_error() {
let (indirect_null, resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(resolver);
let entries: Vec<(Vec<u8>, ObjectHandle)> = vec![(b"RefNull".to_vec(), indirect_null)];
assert!(visible_dict_entries(&entries).is_err());
}
#[test]
fn dict_is_sig_with_byte_range_true_when_both_present() {
let entries = vec![
(b"/Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"/ByteRange".to_vec(), ObjectHandle::array(vec![])),
];
assert!(dict_is_sig_with_byte_range(&entries).unwrap());
}
#[test]
fn dict_is_sig_with_byte_range_false_when_byte_range_is_a_direct_null() {
// `QPDF_Dictionary::hasKey` (QPDF_Dictionary.cc:98-101) is
// `items.count(key) > 0 && !items[key].isNull()` -- a null
// `/ByteRange` value counts as *absent*, the same way a null-valued
// entry is excluded from `visible_dict_entries`'s own output.
let entries = vec![
(b"/Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"/ByteRange".to_vec(), ObjectHandle::null()),
];
assert!(!dict_is_sig_with_byte_range(&entries).unwrap());
}
#[test]
fn dict_is_sig_with_byte_range_false_when_byte_range_resolves_to_an_indirect_null() {
// Same null-exclusion rule as the direct case above, but through
// `isNull()`'s own dereference (QPDFObjectHandle.cc:353-356) --
// `hasKey` resolves an indirect `/ByteRange` to decide this too.
let (indirect_null, _resolver) = resolver_bearing_handle(ObjectValue::Null);
let entries = vec![
(b"/Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"/ByteRange".to_vec(), indirect_null),
];
assert!(!dict_is_sig_with_byte_range(&entries).unwrap());
}
#[test]
fn dict_is_sig_with_byte_range_propagates_a_dropped_document_error_from_byte_range() {
// `/Type` is a direct `/Sig`, so the short-circuit passes it and
// reaches `/ByteRange`'s own forced resolution, which must
// propagate a dropped-document error the same way `/Type`'s own
// resolution does.
let (indirect_byte_range, resolver) = error_resolving_handle(ObjectRef::new(32, 0));
drop(resolver);
let entries = vec![
(b"/Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"/ByteRange".to_vec(), indirect_byte_range),
];
assert!(dict_is_sig_with_byte_range(&entries).is_err());
}
#[test]
fn dict_is_sig_with_byte_range_false_without_byte_range_key() {
let entries = vec![(b"/Type".to_vec(), ObjectHandle::name(b"Sig".to_vec()))];
assert!(!dict_is_sig_with_byte_range(&entries).unwrap());
}
#[test]
fn dict_is_sig_with_byte_range_false_without_type_key() {
let entries = vec![(b"/ByteRange".to_vec(), ObjectHandle::array(vec![]))];
assert!(!dict_is_sig_with_byte_range(&entries).unwrap());
}
#[test]
fn dict_is_sig_with_byte_range_false_when_type_is_not_sig() {
let entries = vec![
(b"/Type".to_vec(), ObjectHandle::name(b"Page".to_vec())),
(b"/ByteRange".to_vec(), ObjectHandle::array(vec![])),
];
assert!(!dict_is_sig_with_byte_range(&entries).unwrap());
}
#[test]
fn dict_is_sig_with_byte_range_resolves_an_indirect_type_that_is_sig() {
// Mirrors qpdf's own `getKey("/Type").isNameAndEquals("/Sig")`,
// which dereferences through `isName()` -- an indirect `/Type` must
// be force-resolved to decide this, not conservatively treated as
// "not Sig".
let (indirect_type, _resolver) =
resolver_bearing_handle(ObjectValue::Name(b"Sig".to_vec()));
let entries = vec![
(b"/Type".to_vec(), indirect_type),
(b"/ByteRange".to_vec(), ObjectHandle::array(vec![])),
];
assert!(dict_is_sig_with_byte_range(&entries).unwrap());
}
#[test]
fn dict_is_sig_with_byte_range_propagates_a_dropped_document_error_from_type() {
let (indirect_type, resolver) = error_resolving_handle(ObjectRef::new(30, 0));
drop(resolver);
let entries = vec![
(b"/Type".to_vec(), indirect_type),
(b"/ByteRange".to_vec(), ObjectHandle::array(vec![])),
];
assert!(dict_is_sig_with_byte_range(&entries).is_err());
}
#[test]
fn dict_is_sig_with_byte_range_does_not_resolve_byte_range_when_type_is_not_sig() {
// Mirrors qpdf's own `&&` short-circuit
// (`isDictionaryOfType("/Sig") && hasKey("/ByteRange")`,
// QPDFWriter.cc:1497-1498): `/ByteRange`'s resolver must never run
// at all once `/Type` is confirmed not `/Sig` -- an indirect
// `/ByteRange` whose resolver would error must not surface that
// error here.
let (indirect_byte_range, _resolver) = error_resolving_handle(ObjectRef::new(31, 0));
let entries = vec![
(b"/Type".to_vec(), ObjectHandle::name(b"Page".to_vec())),
(b"/ByteRange".to_vec(), indirect_byte_range),
];
assert!(!dict_is_sig_with_byte_range(&entries).unwrap());
}
#[test]
fn unparse_object_writes_sig_contents_as_a_hex_string() {
// `/Contents` is a printable-ASCII direct String, which the ordinary
// `write_string_value` path (via `use_hex_string`) would write as a
// literal string `(hi)` -- confirms the Sig+ByteRange special case
// overrides that choice with `write_hex_string`'s own byte shape
// (`<` + one lowercase hex pair per byte + `>`: `h` = 0x68, `i` =
// 0x69).
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::string(b"hi".to_vec())),
]);
let mut out = Vec::new();
dict.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /ByteRange [ ] /Contents <6869> /Type /Sig >>");
}
#[test]
fn unparse_object_leaves_contents_literal_without_sig_type() {
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Page".to_vec())),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::string(b"hi".to_vec())),
]);
let mut out = Vec::new();
dict.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /ByteRange [ ] /Contents (hi) /Type /Page >>");
}
#[test]
fn unparse_object_leaves_contents_literal_without_byte_range() {
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"Contents".to_vec(), ObjectHandle::string(b"hi".to_vec())),
]);
let mut out = Vec::new();
dict.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /Contents (hi) /Type /Sig >>");
}
#[test]
fn unparse_object_writes_an_indirect_sig_contents_as_reference_form_not_hex() {
// Mirrors `unparseChild`'s own indirect-first short-circuit
// (QPDFWriter.cc:1149-1156): an indirect `/Contents` value writes
// as its own "N G R" reference form regardless of the Sig+ByteRange
// condition -- qpdf's flags are only consulted inside
// `unparseObject`, which an indirect child never reaches.
let (indirect_contents, _resolver) =
resolver_bearing_handle(ObjectValue::String(b"hi".to_vec()));
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), indirect_contents),
]);
let mut out = Vec::new();
dict.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /ByteRange [ ] /Contents 20 0 R /Type /Sig >>");
}
#[test]
fn unparse_object_leaves_a_non_string_sig_contents_unaffected() {
// The Sig+ByteRange special case only affects a child whose
// resolved value is itself a String (QPDFWriter.cc's `f_hex_string`
// handling lives inside the `ot_string` arm alone) -- a non-String
// direct `/Contents` (unusual in practice, but not structurally
// ruled out) falls through to the ordinary child-writer unaffected.
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::integer(7)),
]);
let mut out = Vec::new();
dict.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /ByteRange [ ] /Contents 7 /Type /Sig >>");
}
#[test]
fn unparse_object_defers_type_and_byte_range_resolution_until_a_contents_key_is_reached() {
// `dict_is_sig_with_byte_range`
// was hoisted to run once, unconditionally, before the per-entry loop
// even started -- rather than lazily, only when the loop's own
// iteration actually reaches a surviving `/Contents` key -- for the
// Sig+ByteRange hex-string special case that same commit added. This
// reintroduced an unnecessary-force-resolution bug. The
// `refiltered`-key exclusion test (see
// `unparse_stream_dict_entries`'s own doc) covers
// `/Filter`/`/DecodeParms`: `/Type` (and, conditionally,
// `/ByteRange`) now gets force-resolved even for a dict with no
// `/Contents` key at all to apply the special case to -- see
// `try_write_sig_contents_hex_string`'s own doc for why the operand
// order matters, not just the call site's existence.
//
// This dict has no `/Contents` key, so a correctly lazy
// implementation never even calls `dict_is_sig_with_byte_range` --
// `/Type`'s own resolution must be driven solely by
// `visible_dict_entries`'s ordinary per-key null-suppression pass,
// which runs in the dict's own (`BTreeMap`) alphabetical key order.
// `/AAA` sorts before `/Type`; both are dropped-document handles at
// distinct object refs, so the surfaced error text -- which embeds
// the failing ref, see
// `try_dereference_reports_a_dropped_document_without_reconnecting`
// -- pins exactly which one was actually touched first: with the
// eager bug, `/Type` (object 30) is resolved before the
// null-suppression loop even starts, so its error surfaces even
// though `/AAA` (object 99) sorts first in qpdf's own single-pass
// loop order; with the fix, `/AAA`'s error surfaces instead, and
// `/Type`'s handle is never dereferenced at all. (A plain
// success-vs-error assertion cannot discriminate this bug on its
// own: `visible_dict_entries` itself already force-resolves every
// surviving entry -- including `/Type`/`/ByteRange` whenever they
// are present as dict keys -- for the ordinary null-suppression
// check, matching qpdf's own `isNull()` call inside the identical
// per-item loop, `QPDFWriter.cc:1488-1491`; a dict with a genuinely
// erroring `/Type` errors either way. The bug is about *which*
// resolution happens first among several, not whether the overall
// call succeeds.)
let (aaa, aaa_resolver) = error_resolving_handle(ObjectRef::new(99, 0));
drop(aaa_resolver);
let (sig_type, type_resolver) = error_resolving_handle(ObjectRef::new(30, 0));
drop(type_resolver);
let dict = ObjectHandle::dictionary(vec![
(b"AAA".to_vec(), aaa),
(b"Type".to_vec(), sig_type),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
]);
let mut out = Vec::new();
let error = dict.unparse_object(&mut out).unwrap_err();
assert_eq!(error.to_string(), "object 99 0 belongs to a dropped PDF");
}
#[test]
fn unparse_object_qdf_writes_sig_contents_as_a_hex_string() {
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::string(b"hi".to_vec())),
]);
let mut out = Vec::new();
dict.unparse_object_qdf(&mut out, 0).unwrap();
assert_eq!(
out,
b"<<\n /ByteRange [\n ]\n /Contents <6869>\n /Type /Sig\n>>"
);
}
#[test]
fn unparse_object_qdf_defers_type_and_byte_range_resolution_until_a_contents_key_is_reached() {
// QDF sibling of
// `unparse_object_defers_type_and_byte_range_resolution_until_a_contents_key_is_reached`
// above -- `unparse_dict_entries_qdf` needed the identical fix at
// its own call site. See that test's own doc for the full
// eager-vs-lazy rationale and why a plain success-vs-error
// assertion cannot discriminate this bug.
let (aaa, aaa_resolver) = error_resolving_handle(ObjectRef::new(99, 0));
drop(aaa_resolver);
let (sig_type, type_resolver) = error_resolving_handle(ObjectRef::new(30, 0));
drop(type_resolver);
let dict = ObjectHandle::dictionary(vec![
(b"AAA".to_vec(), aaa),
(b"Type".to_vec(), sig_type),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
]);
let mut out = Vec::new();
let error = dict.unparse_object_qdf(&mut out, 0).unwrap_err();
assert_eq!(error.to_string(), "object 99 0 belongs to a dropped PDF");
}
#[test]
fn unparse_stream_body_writes_sig_contents_as_a_hex_string() {
// The Sig+ByteRange special case has no `f_stream` guard in real
// qpdf either (QPDFWriter.cc:1490-1504 is the same shared loop the
// stream-dictionary branch falls into) -- a stream whose dict
// happens to be `/Type /Sig` with `/ByteRange` is unusual but not
// structurally ruled out.
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::string(b"hi".to_vec())),
(b"Length".to_vec(), ObjectHandle::integer(2)),
]);
let mut out = Vec::new();
dict.unparse_stream_body(&mut out, false).unwrap();
assert_eq!(
out,
b"<< /ByteRange [ ] /Contents <6869> /Type /Sig /Length 2 >>"
);
}
#[test]
fn unparse_stream_body_defers_type_and_byte_range_resolution_until_a_contents_key_is_reached() {
// Stream sibling of
// `unparse_object_defers_type_and_byte_range_resolution_until_a_contents_key_is_reached`
// above -- `unparse_stream_dict_entries` needed the identical fix at
// its own call site. See that test's own doc for the full
// eager-vs-lazy rationale and why a plain success-vs-error
// assertion cannot discriminate this bug. `/Length` is a harmless
// direct value here -- this test is not about the `refiltered`
// dimension Finding 2 already fixed, so `refiltered == false`.
let (aaa, aaa_resolver) = error_resolving_handle(ObjectRef::new(99, 0));
drop(aaa_resolver);
let (sig_type, type_resolver) = error_resolving_handle(ObjectRef::new(30, 0));
drop(type_resolver);
let dict = ObjectHandle::dictionary(vec![
(b"AAA".to_vec(), aaa),
(b"Type".to_vec(), sig_type),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Length".to_vec(), ObjectHandle::integer(0)),
]);
let mut out = Vec::new();
let error = dict.unparse_stream_body(&mut out, false).unwrap_err();
assert_eq!(error.to_string(), "object 99 0 belongs to a dropped PDF");
}
#[test]
fn unparse_child_writes_indirect_handle_as_reference_form() {
let (indirect, _resolver) = resolver_bearing_handle(ObjectValue::Integer(7));
let mut out = Vec::new();
unparse_child(&indirect, &mut out).unwrap();
assert_eq!(out, b"20 0 R");
}
#[test]
fn unparse_child_recurses_into_a_direct_scalar() {
let mut out = Vec::new();
unparse_child(&ObjectHandle::integer(7), &mut out).unwrap();
assert_eq!(out, b"7");
}
#[test]
fn unparse_object_writes_a_scalar() {
let mut out = Vec::new();
ObjectHandle::integer(42).unparse_object(&mut out).unwrap();
assert_eq!(out, b"42");
}
#[test]
fn unparse_object_writes_a_boolean() {
let mut out = Vec::new();
ObjectHandle::boolean(true)
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, b"true");
out.clear();
ObjectHandle::boolean(false)
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, b"false");
}
#[test]
fn unparse_object_writes_a_real() {
let mut out = Vec::new();
ObjectHandle::real(0.5).unparse_object(&mut out).unwrap();
assert_eq!(out, b"0.5");
}
#[test]
fn unparse_object_writes_a_string() {
let mut out = Vec::new();
ObjectHandle::string(b"hi".to_vec())
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, b"(hi)");
}
#[test]
fn unparse_object_writes_an_operator_verbatim() {
// ObjectValue::InlineImage shares the identical match arm and byte
// path, so this one case covers both bindings.
let mut out = Vec::new();
ObjectHandle::operator(b"q".to_vec())
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, b"q");
}
#[test]
fn unparse_object_serializes_large_scalar_payloads_without_deep_snapshotting() {
let string_payload = vec![b's'; 256 * 1024];
let mut out = Vec::new();
ObjectHandle::string(string_payload.clone())
.unparse_object(&mut out)
.unwrap();
assert_eq!(out.len(), string_payload.len() + 2);
assert_eq!(out.first(), Some(&b'('));
assert_eq!(out.last(), Some(&b')'));
let operator_payload = vec![b'o'; 256 * 1024];
out.clear();
ObjectHandle::operator(operator_payload.clone())
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, operator_payload);
let inline_image_payload = vec![b'i'; 256 * 1024];
out.clear();
ObjectHandle::inline_image(inline_image_payload.clone())
.unparse_object_qdf(&mut out, 0)
.unwrap();
assert_eq!(out, inline_image_payload);
}
#[test]
fn unparse_object_inlines_only_the_dictionary_of_a_direct_stream_value() {
// A *direct* Stream ObjectValue has no qpdf counterpart (a real
// QPDFObjectHandle's resolved value is never itself a stream
// outside an indirect object), so there is no byte-parity oracle
// here. This pins down the same "inline the dictionary, do not
// write the `stream`/`endstream` framing" behavior for which
// `unparse_stream_body` is separately responsible, and stays consistent with
// that primitive's scope rather than reproducing framing logic here.
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(2))]);
let handle = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(b"ab".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let mut out = Vec::new();
handle.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /Length 2 >>");
}
#[test]
fn unparse_object_on_an_indirect_handle_resolving_to_a_stream_inlines_the_dictionary() {
// Unlike the direct-stream case above, this *is* a real, reachable
// qpdf shape: an indirect object whose resolved value is a stream.
// `unparse_object`/`unparse_object_walk` dispatch on `self` directly
// (never through `unparse_child`'s indirect-reference short-circuit,
// which only applies to *child* positions during recursion), so
// this reaches the same `ObjectValue::Stream` arm as the direct
// case and inlines just the dictionary -- not qpdf's real
// stream-writing output at this position (see
// `ObjectHandle::unparse_object`'s own doc). Pins today's actual
// behavior; `unparse_stream_body` is the primitive that implements the
// real stream-writing path.
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(2))]);
let (indirect, _resolver) =
resolver_bearing_handle(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(b"ab".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let mut out = Vec::new();
indirect.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /Length 2 >>");
}
#[test]
fn unparse_object_writes_a_name_escaped() {
let mut out = Vec::new();
ObjectHandle::name(b"application/pdf".to_vec())
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, b"/application#2fpdf");
}
#[test]
fn unparse_object_writes_a_real_literal_when_safe() {
let mut out = Vec::new();
ObjectHandle::real_literal(0.4, b".4".to_vec())
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, b".4");
}
#[test]
fn unparse_object_falls_back_to_canonical_when_literal_is_unsafe() {
let mut out = Vec::new();
ObjectHandle::real_literal(0.4, b"nope".to_vec())
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, b"0.4");
}
#[test]
fn unparse_object_writes_an_array_with_qpdf_spacing() {
let handle = ObjectHandle::array(vec![ObjectHandle::integer(1), ObjectHandle::integer(2)]);
let mut out = Vec::new();
handle.unparse_object(&mut out).unwrap();
assert_eq!(out, b"[ 1 2 ]");
}
#[test]
fn unparse_object_writes_an_empty_array() {
let mut out = Vec::new();
ObjectHandle::array(vec![])
.unparse_object(&mut out)
.unwrap();
assert_eq!(out, b"[ ]");
}
#[test]
fn unparse_object_writes_a_dict_and_suppresses_direct_null() {
let handle = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::integer(1)),
(b"B".to_vec(), ObjectHandle::null()),
]);
let mut out = Vec::new();
handle.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /A 1 >>");
}
#[test]
fn unparse_object_suppresses_an_indirect_entry_resolving_to_null() {
let (indirect_null, _resolver) = resolver_bearing_handle(ObjectValue::Null);
let handle = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::integer(1)),
(b"RefNull".to_vec(), indirect_null),
]);
let mut out = Vec::new();
handle.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /A 1 >>");
}
#[test]
fn unparse_object_writes_an_empty_dict_when_every_entry_is_suppressed() {
let handle = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::null())]);
let mut out = Vec::new();
handle.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< >>");
}
#[test]
fn unparse_object_writes_a_retained_indirect_entry_as_reference_form() {
let (indirect, _resolver) = resolver_bearing_handle(ObjectValue::Integer(7));
let handle = ObjectHandle::dictionary(vec![(b"A".to_vec(), indirect)]);
let mut out = Vec::new();
handle.unparse_object(&mut out).unwrap();
assert_eq!(out, b"<< /A 20 0 R >>");
}
#[test]
fn unparse_object_propagates_a_dropped_document_error() {
let (indirect, resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(resolver);
let mut out = Vec::new();
assert!(indirect.unparse_object(&mut out).is_err());
}
#[test]
fn unparse_encrypted_string_writer_replaces_direct_strings_only() {
let (indirect, _resolver) =
resolver_bearing_handle(ObjectValue::String(b"hidden".to_vec()));
let handle = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::string(b"plain".to_vec())),
(b"Indirect".to_vec(), indirect),
(
b"Nested".to_vec(),
ObjectHandle::array(vec![ObjectHandle::string(b"nested".to_vec())]),
),
]);
let mut out = Vec::new();
let mut callback = compact_string_hook;
handle
.unparse_object_with_string_writer(&mut out, &mut callback)
.unwrap();
assert_eq!(
out,
b"<< /A <hook:plain> /Indirect 20 0 R /Nested [ <hook:nested> ] >>"
);
}
#[test]
fn unparse_encrypted_string_writer_qdf_keeps_signature_contents_cleartext_hex() {
let handle = ObjectHandle::dictionary(vec![
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(
b"Contents".to_vec(),
ObjectHandle::string(b"contents".to_vec()),
),
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
]);
let mut out = Vec::new();
let mut callback = qdf_string_hook;
handle
.unparse_object_qdf_with_string_writer(&mut out, 4, &mut callback)
.unwrap();
assert_eq!(
out,
b"<<\n /ByteRange [\n ]\n /Contents <636f6e74656e7473>\n /Type /Sig\n >>"
);
let mut compact = Vec::new();
let mut compact_callback = compact_string_hook;
handle
.unparse_object_with_string_writer(&mut compact, &mut compact_callback)
.unwrap();
assert_eq!(
compact,
b"<< /ByteRange [ ] /Contents <636f6e74656e7473> /Type /Sig >>"
);
let mut stream_compact = Vec::new();
let mut stream_compact_callback = compact_string_hook;
handle
.unparse_stream_body_with_string_writer(
&mut stream_compact,
false,
&mut stream_compact_callback,
)
.unwrap();
assert_eq!(
stream_compact,
b"<< /ByteRange [ ] /Contents <636f6e74656e7473> /Type /Sig >>"
);
let mut stream_qdf = Vec::new();
let mut stream_qdf_callback = qdf_string_hook;
handle
.unparse_stream_body_qdf_with_string_writer(
&mut stream_qdf,
0,
&mut stream_qdf_callback,
)
.unwrap();
assert_eq!(
stream_qdf,
b"<<\n /ByteRange [\n ]\n /Contents <636f6e74656e7473>\n /Type /Sig\n>>"
);
}
#[test]
fn unparse_encrypted_string_writer_stream_bodies_keep_qpdf_layout() {
let dict = ObjectHandle::dictionary(vec![
(
b"DecodeParms".to_vec(),
ObjectHandle::dictionary(vec![(
b"Name".to_vec(),
ObjectHandle::string(b"params".to_vec()),
)]),
),
(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
),
(b"Length".to_vec(), ObjectHandle::integer(3)),
]);
let mut compact = Vec::new();
let mut compact_callback = compact_string_hook;
dict.unparse_stream_body_with_string_writer(&mut compact, false, &mut compact_callback)
.unwrap();
assert_eq!(
compact,
b"<< /DecodeParms << /Name <hook:params> >> /Filter /FlateDecode /Length 3 >>"
);
let mut qdf = Vec::new();
let mut qdf_callback = qdf_string_hook;
dict.unparse_stream_body_qdf_with_string_writer(&mut qdf, 2, &mut qdf_callback)
.unwrap();
assert_eq!(
qdf,
b"<<\n /DecodeParms <<\n /Name {hook:params}\n >>\n /Filter /FlateDecode\n /Length 3\n >>"
);
}
#[test]
fn unparse_string_writer_covers_stream_reserved_refiltered_and_special_children() {
let stream_dict = ObjectHandle::dictionary(vec![
(
b"DecodeParms".to_vec(),
ObjectHandle::dictionary(vec![(
b"Name".to_vec(),
ObjectHandle::string(b"params".to_vec()),
)]),
),
(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
),
(b"Label".to_vec(), ObjectHandle::string(b"stream".to_vec())),
(b"Length".to_vec(), ObjectHandle::integer(3)),
]);
let stream = ObjectHandle::stream(stream_dict.clone(), Rc::new(b"raw".to_vec()));
let mut compact = Vec::new();
let mut compact_callback = compact_string_hook;
stream
.unparse_object_with_string_writer(&mut compact, &mut compact_callback)
.expect("direct stream object callback emission");
assert!(compact
.windows(b"<hook:stream>".len())
.any(|part| part == b"<hook:stream>"));
let mut qdf = Vec::new();
let mut qdf_callback = qdf_string_hook;
stream
.unparse_object_qdf_with_string_writer(&mut qdf, 2, &mut qdf_callback)
.expect("direct stream object QDF callback emission");
assert!(qdf
.windows(b"{hook:stream}".len())
.any(|part| part == b"{hook:stream}"));
let mut stream_body = Vec::new();
let mut stream_body_callback = compact_string_hook;
stream
.unparse_stream_body_with_string_writer(
&mut stream_body,
false,
&mut stream_body_callback,
)
.expect("direct stream compact body callback emission");
assert!(stream_body
.windows(b"<hook:stream>".len())
.any(|part| part == b"<hook:stream>"));
let mut refiltered = Vec::new();
let mut refiltered_callback = compact_string_hook;
stream_dict
.unparse_stream_body_with_string_writer(&mut refiltered, true, &mut refiltered_callback)
.expect("refiltered stream dictionary callback emission");
assert!(!refiltered
.windows(b"DecodeParms".len())
.any(|part| part == b"DecodeParms"));
assert!(refiltered
.windows(b"/Filter /FlateDecode".len())
.any(|part| part == b"/Filter /FlateDecode"));
let mut stream_qdf = Vec::new();
let mut stream_qdf_callback = qdf_string_hook;
stream
.unparse_stream_body_qdf_with_string_writer(
&mut stream_qdf,
1,
&mut stream_qdf_callback,
)
.expect("stream value QDF body callback emission");
assert!(stream_qdf
.windows(b"{hook:stream}".len())
.any(|part| part == b"{hook:stream}"));
let scalar_stream = ObjectHandle::stream(ObjectHandle::integer(1), Rc::new(Vec::new()));
let mut scalar_stream_body = Vec::new();
let mut scalar_stream_callback = compact_string_hook;
scalar_stream
.unparse_stream_body_with_string_writer(
&mut scalar_stream_body,
false,
&mut scalar_stream_callback,
)
.expect("stream with a non-dictionary dictionary handle uses an empty body");
assert_eq!(scalar_stream_body, b"<< >>");
let mut scalar_stream_qdf_body = Vec::new();
let mut scalar_stream_qdf_callback = qdf_string_hook;
scalar_stream
.unparse_stream_body_qdf_with_string_writer(
&mut scalar_stream_qdf_body,
1,
&mut scalar_stream_qdf_callback,
)
.expect("QDF stream with a non-dictionary dictionary handle uses an empty body");
assert_eq!(scalar_stream_qdf_body, b"<<\n >>");
let mut scalar_body = Vec::new();
let mut scalar_callback = compact_string_hook;
ObjectHandle::integer(1)
.unparse_stream_body_with_string_writer(&mut scalar_body, false, &mut scalar_callback)
.expect("non-dictionary stream body degrades to an empty dictionary");
assert_eq!(scalar_body, b"<< >>");
let mut scalar_qdf_body = Vec::new();
let mut scalar_qdf_callback = qdf_string_hook;
ObjectHandle::integer(1)
.unparse_stream_body_qdf_with_string_writer(
&mut scalar_qdf_body,
1,
&mut scalar_qdf_callback,
)
.expect("non-dictionary QDF stream body degrades to an empty dictionary");
assert_eq!(scalar_qdf_body, b"<<\n >>");
let reserved = ObjectHandle::new_reserved_direct();
let mut reserved_out = Vec::new();
let mut reserved_callback = compact_string_hook;
assert!(reserved
.unparse_object_with_string_writer(&mut reserved_out, &mut reserved_callback)
.is_err());
assert!(reserved
.unparse_object_qdf_with_string_writer(&mut reserved_out, 0, &mut reserved_callback,)
.is_err());
assert!(reserved
.unparse_stream_body_with_string_writer(
&mut reserved_out,
false,
&mut reserved_callback,
)
.is_err());
assert!(reserved
.unparse_stream_body_qdf_with_string_writer(
&mut reserved_out,
0,
&mut reserved_callback,
)
.is_err());
let non_string_sig = ObjectHandle::dictionary(vec![
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::integer(7)),
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
]);
let mut non_string_sig_out = Vec::new();
let mut non_string_sig_callback = compact_string_hook;
non_string_sig
.unparse_object_with_string_writer(
&mut non_string_sig_out,
&mut non_string_sig_callback,
)
.expect("non-string signature contents use the ordinary child writer");
assert!(non_string_sig_out
.windows(b"/Contents 7".len())
.any(|part| part == b"/Contents 7"));
let (indirect_contents, _resolver) =
resolver_bearing_handle(ObjectValue::String(b"indirect".to_vec()));
let indirect_sig = ObjectHandle::dictionary(vec![
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), indirect_contents),
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
]);
let mut indirect_sig_out = Vec::new();
let mut indirect_sig_callback = qdf_string_hook;
indirect_sig
.unparse_object_qdf_with_string_writer(
&mut indirect_sig_out,
0,
&mut indirect_sig_callback,
)
.expect("indirect signature contents use the reference writer");
assert!(indirect_sig_out
.windows(b"/Contents 20 0 R".len())
.any(|part| part == b"/Contents 20 0 R"));
}
#[test]
fn unparse_object_qdf_writes_a_scalar_like_plain_unparse() {
let mut out = Vec::new();
ObjectHandle::integer(42)
.unparse_object_qdf(&mut out, 0)
.unwrap();
assert_eq!(out, b"42");
}
#[test]
fn unparse_object_qdf_writes_an_array_with_newline_indent() {
let handle = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
let mut out = Vec::new();
handle.unparse_object_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"[\n 1\n]");
}
#[test]
fn unparse_object_qdf_writes_a_dict_with_newline_indent_and_suppresses_null() {
let handle = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::integer(1)),
(b"B".to_vec(), ObjectHandle::null()),
]);
let mut out = Vec::new();
handle.unparse_object_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /A 1\n>>");
}
#[test]
fn unparse_object_qdf_nests_indent_one_level_deeper() {
let handle = ObjectHandle::dictionary(vec![(
b"Kids".to_vec(),
ObjectHandle::array(vec![ObjectHandle::integer(1)]),
)]);
let mut out = Vec::new();
handle.unparse_object_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /Kids [\n 1\n ]\n>>");
}
#[test]
fn unparse_object_qdf_writes_a_retained_indirect_entry_as_reference_form() {
// QDF-mode sibling of unparse_object_writes_a_retained_indirect_entry_as_reference_form:
// exercises unparse_child_qdf's indirect arm, which the four
// plan-specified literals above never reach (every handle in them is
// direct).
let (indirect, _resolver) = resolver_bearing_handle(ObjectValue::Integer(7));
let handle = ObjectHandle::dictionary(vec![(b"A".to_vec(), indirect)]);
let mut out = Vec::new();
handle.unparse_object_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /A 20 0 R\n>>");
}
#[test]
fn unparse_object_qdf_on_an_indirect_handle_resolving_to_a_stream_inlines_the_dictionary() {
// QDF-mode sibling of
// unparse_object_on_an_indirect_handle_resolving_to_a_stream_inlines_the_dictionary:
// exercises unparse_object_value_qdf's Stream arm, unreached by the
// four plan-specified literals above.
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(2))]);
let (indirect, _resolver) =
resolver_bearing_handle(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(b"ab".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let mut out = Vec::new();
indirect.unparse_object_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /Length 2\n>>");
}
#[test]
fn unparse_object_qdf_nests_a_dict_inside_a_dict_at_every_indent_slot() {
// The plan-specified nesting literal only stretches the *array*
// closing bracket's indent slot (unparse_object_qdf_nests_indent_one_level_deeper).
// A dict nested in a dict stretches unparse_dict_entries_qdf's own
// closing `>>` indent slot too, which that test leaves at the
// top-level `indent = 0` default.
let handle = ObjectHandle::dictionary(vec![(
b"D".to_vec(),
ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::integer(1))]),
)]);
let mut out = Vec::new();
handle.unparse_object_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /D <<\n /A 1\n >>\n>>");
}
#[test]
fn unparse_object_qdf_propagates_a_dropped_document_error() {
let (indirect, resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(resolver);
let mut out = Vec::new();
assert!(indirect.unparse_object_qdf(&mut out, 0).is_err());
}
#[test]
fn unparse_object_qdf_respects_a_nonzero_starting_indent() {
// Every other QDF test in this module calls the public entry point
// with `indent = 0`, so the internal `indent + 2` recursion is
// exercised but the *argument's own arrival* at the public method
// never is -- a stray `indent = 0` hardcoded inside the function
// body would still pass every one of them. Start at a nonzero
// column instead, so the dict's closing `>>` (written at the
// caller's own `indent`, unincremented) and its one entry (written
// at `indent + 2`) both prove the argument actually reached them.
let handle = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::integer(1))]);
let mut out = Vec::new();
handle.unparse_object_qdf(&mut out, 4).unwrap();
assert_eq!(out, b"<<\n /A 1\n >>");
}
#[test]
fn unparse_object_qdf_writes_an_empty_dict_at_a_nonzero_indent() {
// Sibling of the suppresses-null test above, but with *every* entry
// gone (here: none to begin with) and at a nonzero starting indent
// -- untested at any indent before this. Only the closing `>>`
// carries an indent slot when there are no surviving entries; this
// pins that it still lands at the caller's own `indent`, not the
// default `0`.
let handle = ObjectHandle::dictionary(vec![]);
let mut out = Vec::new();
handle.unparse_object_qdf(&mut out, 4).unwrap();
assert_eq!(out, b"<<\n >>");
}
#[test]
fn unparse_stream_body_writes_length_last_preserved() {
// `/DecodeParms` is a non-null (empty-dictionary) value here, not
// `ObjectHandle::null()`: a null value would already be excluded by
// `visible_dict_entries`'s own null-suppression pass before the
// `refiltered` check ever saw the key, which would let this test
// pass even if `unparse_stream_dict_entries` unconditionally
// dropped `/DecodeParms` regardless of `refiltered`. With
// `refiltered == false`, both `/DecodeParms` and `/Filter` must
// survive at their natural (`BTreeMap`) lexicographic positions
// (`DecodeParms` < `Filter` < the pulled-out-and-appended
// `Length`), unlike the refiltered case pinned by
// `unparse_stream_body_refiltered_drops_filter_and_decodeparms_appends_flate`
// below, where both are dropped.
let dict = ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
),
(b"DecodeParms".to_vec(), ObjectHandle::dictionary(vec![])),
(b"Length".to_vec(), ObjectHandle::integer(3)),
]);
let mut out = Vec::new();
dict.unparse_stream_body(&mut out, false).unwrap();
assert_eq!(
out,
b"<< /DecodeParms << >> /Filter /FlateDecode /Length 3 >>"
);
}
#[test]
fn unparse_stream_body_refiltered_drops_filter_and_decodeparms_appends_flate() {
// `/DecodeParms` is a non-null (empty-dictionary) value here, not
// `ObjectHandle::null()`: a null value would already be excluded by
// `visible_dict_entries`'s own null-suppression pass before the
// refiltered check ever saw the key, which would let this test pass
// even if the `key.as_slice() == b"DecodeParms"` disjunct were
// dropped from that check entirely.
let dict = ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::name(b"ASCIIHexDecode".to_vec()),
),
(b"DecodeParms".to_vec(), ObjectHandle::dictionary(vec![])),
(b"Length".to_vec(), ObjectHandle::integer(3)),
]);
let mut out = Vec::new();
dict.unparse_stream_body(&mut out, true).unwrap();
assert_eq!(out, b"<< /Length 3 /Filter /FlateDecode >>");
}
#[test]
fn unparse_stream_body_refiltered_removes_filter_parameters_before_visibility() {
// Refiltered output must exclude these entries before visibility
// checks:
// `visible_dict_entries` previously ran over every entry --
// including `/Filter`/`/DecodeParms` -- before the `refiltered`
// skip in the write loop below ever got a chance to drop them,
// force-resolving (and potentially failing on) a value guaranteed
// to be discarded from the refiltered output. Real qpdf removes
// both keys from a shallow copy of the dict entirely BEFORE its
// null-suppression loop runs (`QPDFWriter.cc:1454-1455`, ahead of
// `:1488-1491`) -- it never calls `isNull()` on a key it is about
// to discard anyway.
//
// An indirect `/Filter` whose resolver would error, with
// `refiltered == true`, must be excluded before suppression inspects
// it. `/DecodeParms` is a direct empty array here so qpdf's earlier
// empty-array probe is exercised without changing that error boundary.
let (filter, _filter_resolver) = error_resolving_handle(ObjectRef::new(40, 0));
let decode_parms = ObjectHandle::array(Vec::new());
let dict = ObjectHandle::dictionary(vec![
(b"Filter".to_vec(), filter),
(b"DecodeParms".to_vec(), decode_parms),
(b"Length".to_vec(), ObjectHandle::integer(3)),
]);
let mut out = Vec::new();
dict.unparse_stream_body(&mut out, true).unwrap();
assert_eq!(out, b"<< /Length 3 /Filter /FlateDecode >>");
}
#[test]
fn unparse_stream_body_not_refiltered_still_propagates_an_indirect_filter_error() {
// Contrast with the test above: when `refiltered` is false,
// `/Filter` is a surviving key that must actually be written, so an
// indirect value whose resolver errors must still surface that
// error -- proving the fix scopes "skip resolution" to the
// refiltered case alone, rather than exempting
// `/Filter`/`/DecodeParms` from resolution unconditionally (which
// would silently corrupt a non-refiltered stream's real `/Filter`
// value).
let (filter, _resolver) = error_resolving_handle(ObjectRef::new(42, 0));
let dict = ObjectHandle::dictionary(vec![
(b"Filter".to_vec(), filter),
(b"Length".to_vec(), ObjectHandle::integer(3)),
]);
let mut out = Vec::new();
assert!(dict.unparse_stream_body(&mut out, false).is_err());
}
#[test]
fn refiltered_stream_still_probes_an_indirect_decode_parms_before_removal() {
let (decode_parms, _resolver) = error_resolving_handle(ObjectRef::new(43, 0));
let dict = ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::name(b"ASCIIHexDecode".to_vec()),
),
(b"DecodeParms".to_vec(), decode_parms),
(b"Length".to_vec(), ObjectHandle::integer(3)),
]);
let mut out = Vec::new();
let error = dict
.unparse_stream_body(&mut out, true)
.expect_err("qpdf probes DecodeParms before the filtered removal branch");
assert_eq!(error.to_string(), "resolver failed");
}
#[test]
fn mapped_unparse_writes_stream_children_and_non_dictionary_shapes() {
let (child, _resolver) = resolver_bearing_handle(ObjectValue::Integer(7));
let dict = ObjectHandle::dictionary(vec![
(b"Child".to_vec(), child),
(b"Length".to_vec(), ObjectHandle::integer(2)),
]);
let stream = ObjectHandle::stream(dict, Rc::new(b"ab".to_vec()));
let map = |object_ref| {
assert_eq!(object_ref, ObjectRef::new(20, 0));
Ok(ObjectRef::new(8, 0))
};
let mut object = Vec::new();
stream
.unparse_object_with_ref_map_and_removed(&mut object, &map, &BTreeSet::new())
.unwrap();
assert_eq!(object, b"<< /Child 8 0 R /Length 2 >>");
let mut body = Vec::new();
stream
.unparse_stream_body_with_ref_map_and_removed(&mut body, false, &map, &BTreeSet::new())
.unwrap();
assert_eq!(body, b"<< /Child 8 0 R /Length 2 >>");
let signature = ObjectHandle::stream(
ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::string(b"hi".to_vec())),
]),
Rc::new(b"ab".to_vec()),
);
let mut signature_body = Vec::new();
signature
.unparse_stream_body_with_ref_map_and_removed(
&mut signature_body,
false,
&map,
&BTreeSet::new(),
)
.unwrap();
assert_eq!(
signature_body,
b"<< /ByteRange [ ] /Contents <6869> /Type /Sig >>"
);
let mut nested_non_dictionary = Vec::new();
ObjectHandle::stream(ObjectHandle::integer(5), Rc::new(b"ab".to_vec()))
.unparse_stream_body_with_ref_map_and_removed(
&mut nested_non_dictionary,
false,
&map,
&BTreeSet::new(),
)
.unwrap();
assert_eq!(nested_non_dictionary, b"<< >>");
let mut non_dictionary = Vec::new();
ObjectHandle::integer(5)
.unparse_stream_body_with_ref_map_and_removed(
&mut non_dictionary,
false,
&map,
&BTreeSet::new(),
)
.unwrap();
assert_eq!(non_dictionary, b"<< >>");
}
#[test]
fn mapped_unparse_omits_removed_indirect_dictionary_entries() {
let removed_ref = ObjectRef::new(20, 0);
let (removed, _resolver) = resolver_bearing_handle(ObjectValue::Integer(7));
let kept = ObjectHandle::new_indirect_unresolved(ObjectRef::new(21, 0), 0);
kept.set_resolved(ObjectValue::Integer(8));
let mut removed_refs = BTreeSet::new();
removed_refs.insert(removed_ref);
let map = |object_ref| {
assert_ne!(object_ref, removed_ref);
Ok(ObjectRef::new(8, 0))
};
let dict = ObjectHandle::dictionary(vec![
(b"Mapped".to_vec(), kept.clone()),
(b"Removed".to_vec(), removed.clone()),
]);
let mut object = Vec::new();
dict.unparse_object_with_ref_map_and_removed(&mut object, &map, &removed_refs)
.unwrap();
assert_eq!(object, b"<< /Mapped 8 0 R >>");
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![
(b"Mapped".to_vec(), kept),
(b"Length".to_vec(), ObjectHandle::integer(2)),
(b"Removed".to_vec(), removed),
]),
Rc::new(b"ab".to_vec()),
);
let mut body = Vec::new();
stream
.unparse_stream_body_with_ref_map_and_removed(&mut body, false, &map, &removed_refs)
.unwrap();
assert_eq!(body, b"<< /Mapped 8 0 R /Length 2 >>");
}
#[test]
fn mapped_stream_writers_cover_qdf_length_and_filter_variants() {
let kept = ObjectHandle::new_indirect_unresolved(ObjectRef::new(30, 0), 0);
kept.set_resolved(ObjectValue::Integer(7));
let removed = ObjectHandle::new_indirect_unresolved(ObjectRef::new(31, 0), 0);
removed.set_resolved(ObjectValue::Integer(8));
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::string(b"sig".to_vec())),
(b"DecodeParms".to_vec(), ObjectHandle::dictionary(vec![])),
(
b"Filter".to_vec(),
ObjectHandle::name(b"ASCIIHexDecode".to_vec()),
),
(b"Length".to_vec(), ObjectHandle::integer(3)),
(b"Link".to_vec(), kept),
(b"Removed".to_vec(), removed),
(b"Text".to_vec(), ObjectHandle::string(b"plain".to_vec())),
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
]),
stream_data: Some(Rc::new(b"abc".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 3,
})));
let mut removed_refs = BTreeSet::new();
removed_refs.insert(ObjectRef::new(31, 0));
let map = |object_ref: ObjectRef| {
Ok(ObjectRef::new(
object_ref.number + 100,
object_ref.generation,
))
};
let mut compact = Vec::new();
stream
.unparse_stream_body_with_ref_map_and_removed_with_string_writer(
&mut compact,
false,
&map,
&removed_refs,
&mut compact_string_hook,
)
.unwrap();
let compact_text = String::from_utf8_lossy(&compact);
assert!(compact_text.contains("/Link 130 0 R"));
assert!(compact_text.contains("/Length 3"));
assert!(compact_text.contains("<hook:plain>"));
assert!(!compact_text.contains("/Removed"));
let mut refiltered = Vec::new();
stream
.unparse_stream_body_with_ref_map_and_removed_with_string_writer(
&mut refiltered,
true,
&map,
&removed_refs,
&mut compact_string_hook,
)
.unwrap();
let refiltered_text = String::from_utf8_lossy(&refiltered);
assert!(!refiltered_text.contains("/Filter /ASCIIHexDecode"));
assert!(!refiltered_text.contains("/DecodeParms"));
assert!(refiltered_text.contains("/Filter /FlateDecode"));
let mut qdf_source_length = Vec::new();
stream
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length(
&mut qdf_source_length,
2,
&map,
&removed_refs,
None,
)
.unwrap();
let qdf_source_text = String::from_utf8_lossy(&qdf_source_length);
assert!(qdf_source_text.contains("/Length 3"));
assert!(qdf_source_text.contains("/Link 130 0 R"));
let mut qdf_synthetic_length = Vec::new();
stream
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length(
&mut qdf_synthetic_length,
2,
&map,
&removed_refs,
Some(ObjectRef::new(77, 0)),
)
.unwrap();
assert!(String::from_utf8_lossy(&qdf_synthetic_length).contains("/Length 77 0 R"));
let mut qdf_encrypted_source_length = Vec::new();
stream
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length_with_string_writer(
&mut qdf_encrypted_source_length,
2,
&map,
&removed_refs,
None,
&mut qdf_string_hook,
)
.unwrap();
let qdf_encrypted_source_text = String::from_utf8_lossy(&qdf_encrypted_source_length);
assert!(qdf_encrypted_source_text.contains("{hook:plain}"));
assert!(qdf_encrypted_source_text.contains("/Length 3"));
let mut qdf_encrypted_synthetic_length = Vec::new();
stream
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length_with_string_writer(
&mut qdf_encrypted_synthetic_length,
2,
&map,
&removed_refs,
Some(ObjectRef::new(78, 0)),
&mut qdf_string_hook,
)
.unwrap();
assert!(String::from_utf8_lossy(&qdf_encrypted_synthetic_length).contains("/Length 78 0 R"));
let scalar = ObjectHandle::integer(5);
let mut scalar_qdf = Vec::new();
scalar
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length(
&mut scalar_qdf,
0,
&map,
&removed_refs,
None,
)
.unwrap();
assert_eq!(scalar_qdf, b"<<\n>>");
let mut scalar_qdf_encrypted = Vec::new();
scalar
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length_with_string_writer(
&mut scalar_qdf_encrypted,
0,
&map,
&removed_refs,
None,
&mut qdf_string_hook,
)
.unwrap();
assert_eq!(scalar_qdf_encrypted, b"<<\n /Length null\n>>");
let mut scalar_compact_encrypted = Vec::new();
scalar
.unparse_stream_body_with_ref_map_and_removed_with_string_writer(
&mut scalar_compact_encrypted,
false,
&map,
&removed_refs,
&mut compact_string_hook,
)
.unwrap();
assert_eq!(scalar_compact_encrypted, b"<< >>");
let no_length = ObjectHandle::dictionary(vec![(
b"Text".to_vec(),
ObjectHandle::string(b"no-length".to_vec()),
)]);
let mut no_length_qdf = Vec::new();
no_length
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length_with_string_writer(
&mut no_length_qdf,
0,
&map,
&removed_refs,
None,
&mut qdf_string_hook,
)
.unwrap();
assert!(String::from_utf8_lossy(&no_length_qdf).contains("/Length null"));
let reserved = ObjectHandle::new_reserved_direct();
let mut reserved_out = Vec::new();
assert!(reserved
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length(
&mut reserved_out,
0,
&map,
&removed_refs,
None,
)
.is_err());
assert!(reserved
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length_with_string_writer(
&mut reserved_out,
0,
&map,
&removed_refs,
None,
&mut qdf_string_hook,
)
.is_err());
assert!(reserved
.unparse_stream_body_with_ref_map_and_removed_with_string_writer(
&mut reserved_out,
false,
&map,
&removed_refs,
&mut compact_string_hook,
)
.is_err());
let stream_with_non_dictionary_dict =
ObjectHandle::stream(ObjectHandle::integer(1), Rc::new(Vec::new()));
let mut non_dictionary_dict_qdf = Vec::new();
stream_with_non_dictionary_dict
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length(
&mut non_dictionary_dict_qdf,
0,
&map,
&removed_refs,
None,
)
.unwrap();
assert_eq!(non_dictionary_dict_qdf, b"<<\n>>");
let mut non_dictionary_dict_qdf_string = Vec::new();
stream_with_non_dictionary_dict
.unparse_stream_body_qdf_with_ref_map_and_removed_and_length_with_string_writer(
&mut non_dictionary_dict_qdf_string,
0,
&map,
&removed_refs,
None,
&mut qdf_string_hook,
)
.unwrap();
assert_eq!(non_dictionary_dict_qdf_string, b"<<\n /Length null\n>>");
let mut non_dictionary_dict_compact_string = Vec::new();
stream_with_non_dictionary_dict
.unparse_stream_body_with_ref_map_and_removed_with_string_writer(
&mut non_dictionary_dict_compact_string,
false,
&map,
&removed_refs,
&mut compact_string_hook,
)
.unwrap();
assert_eq!(non_dictionary_dict_compact_string, b"<< >>");
}
#[test]
fn unparse_stream_body_suppresses_a_null_valued_key() {
let dict = ObjectHandle::dictionary(vec![
(b"Length".to_vec(), ObjectHandle::integer(3)),
(b"Metadata".to_vec(), ObjectHandle::null()),
]);
let mut out = Vec::new();
dict.unparse_stream_body(&mut out, false).unwrap();
assert_eq!(out, b"<< /Length 3 >>");
}
#[test]
fn unparse_stream_body_uses_the_dictionary_of_a_direct_stream_value() {
// Mirrors unparse_object_inlines_only_the_dictionary_of_a_direct_stream_value
// above: a *direct* Stream ObjectValue has no qpdf counterpart (a
// real QPDFObjectHandle's resolved value is never itself a stream
// outside an indirect object), but `unparse_stream_body` must still
// use its `stream_dict`'s entries rather than falling into the
// non-dictionary-self `<< >>` degrade below -- keeping the promise
// those two `unparse_object`/`unparse_object_qdf` tests made on this
// primitive's behalf (`unparse_stream_body` is separately responsible
// for this).
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(2))]);
let handle = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(b"ab".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let mut out = Vec::new();
handle.unparse_stream_body(&mut out, false).unwrap();
assert_eq!(out, b"<< /Length 2 >>");
}
#[test]
fn unparse_stream_body_on_an_indirect_handle_resolving_to_a_stream_uses_the_dictionary() {
// Mirrors unparse_object_on_an_indirect_handle_resolving_to_a_stream_inlines_the_dictionary
// above: a real, reachable qpdf shape -- an indirect object whose
// resolved value is a stream (e.g. a production reader's own
// resolution of a stream object). The mock-resolver harness resolves
// `self` to `Stream { stream_dict, .. }` the same way that reader
// would; `stream_dict`'s own entries must still surface here rather
// than the non-dictionary-self `<< >>` degrade.
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(2))]);
let (indirect, _resolver) =
resolver_bearing_handle(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(b"ab".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let mut out = Vec::new();
indirect.unparse_stream_body(&mut out, false).unwrap();
assert_eq!(out, b"<< /Length 2 >>");
}
#[test]
fn unparse_stream_body_resolves_an_unresolved_indirect_stream_dict() {
// `stream_dict` is itself an `ObjectHandle` that may not yet be
// resolved (e.g. a production reader's lazily-resolved stream
// dictionary), not just an already-direct one as the two tests
// above build. `self` stays a *direct* Stream value here so the
// only variable under test is `stream_dict`'s own resolution state:
// without the `stream_dict.try_dereference()?` call this fix added,
// `with_value` on a not-yet-resolved indirect handle returns `None`
// and this would degrade to `<< >>` instead of using the resolved
// dictionary's entries.
let (inner, _resolver) = resolver_bearing_handle(ObjectValue::Dictionary(
[(b"Length".to_vec(), ObjectHandle::integer(2))]
.into_iter()
.collect(),
));
let handle = ObjectHandle::stream(inner, Rc::new(b"ab".to_vec()));
let mut out = Vec::new();
handle.unparse_stream_body(&mut out, false).unwrap();
assert_eq!(out, b"<< /Length 2 >>");
}
#[test]
fn unparse_stream_body_propagates_a_dropped_document_error_from_stream_dict() {
// Mirrors unparse_stream_body_propagates_a_dropped_document_error
// below, but for the new Stream-handling path added by this fix:
// the dropped document lives behind `stream_dict`, not `self`
// directly (`self` is a *direct* Stream value; only `stream_dict`
// is the as-yet-unresolved indirect handle whose resolver is
// dropped). The new `stream_dict.try_dereference()?` call must
// surface this error too, not silently degrade to an empty `<< >>`
// the way an unresolved `with_value` read alone would.
let (inner, resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(resolver);
let handle = ObjectHandle::stream(inner, Rc::new(b"ab".to_vec()));
let mut out = Vec::new();
assert!(handle.unparse_stream_body(&mut out, false).is_err());
}
#[test]
fn unparse_stream_body_writes_empty_dict_when_stream_dict_is_not_a_dictionary() {
// `stream_dict` is itself typed as an `ObjectHandle`, so nothing at
// the type level prevents it from resolving to something other than
// a `Dictionary` -- mirroring the same typed-input assumption
// `self` itself is held to by
// unparse_stream_body_writes_empty_dict_for_a_non_dictionary_self
// below. Exercises the new nested `_ => Vec::new()` arm for
// `stream_dict`'s own resolved value.
let handle = ObjectHandle::stream(ObjectHandle::integer(5), Rc::new(b"ab".to_vec()));
let mut out = Vec::new();
handle.unparse_stream_body(&mut out, false).unwrap();
assert_eq!(out, b"<< >>");
}
#[test]
fn unparse_stream_body_writes_empty_dict_for_a_non_dictionary_self() {
// Pins the doc comment's typed-input-assumption claim: a
// non-dictionary `self` (mirroring `write_pdf_stream`'s own
// assumption that it is only ever called on a stream's dictionary)
// writes an empty `<< >>` rather than panicking or erroring.
let mut out = Vec::new();
ObjectHandle::integer(5)
.unparse_stream_body(&mut out, false)
.unwrap();
assert_eq!(out, b"<< >>");
}
#[test]
fn unparse_stream_body_propagates_a_dropped_document_error() {
// Mirrors unparse_object_propagates_a_dropped_document_error: an
// as-yet-unresolved indirect handle whose document has been dropped
// must surface as an error here too, not silently degrade to an
// empty `<< >>` the way an unresolved `with_value` read alone would.
let (indirect, resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(resolver);
let mut out = Vec::new();
assert!(indirect.unparse_stream_body(&mut out, false).is_err());
}
// QDF-mode sibling suite of the `unparse_stream_body_*` tests above,
// for `unparse_stream_body_qdf`. Every hardcoded expected byte string
// below was cross-checked against a live call to
// `Dictionary::write_pdf_stream_qdf` (`object.rs`) with an equivalent
// dictionary before being pinned here, not hand-derived from reading
// the algorithm alone -- see this primitive's own doc for the full
// qpdf-correspondence and the deliberate absence of a `refiltered`
// parameter.
#[test]
fn unparse_stream_body_qdf_writes_length_last_preserved() {
// No `refiltered` dimension exists for the QDF shape (see
// `unparse_stream_body_qdf`'s own doc for why), so unlike its
// compact sibling this has only one shape to pin: every other key
// stays at its natural alphabetical position, and `/Length` is
// pulled out and written last, immediately before the closing
// `>>`. Deliberately includes `/Width`, which sorts *after*
// `/Length` alphabetically (`DecodeParms` < `Filter` < `Length` <
// `Width`): with only `{Filter, DecodeParms, Length}` (no key past
// `Length`), `/Length`'s natural BTreeMap position already happens
// to be last, so a broken implementation that forgot the pull-out
// entirely would still pass -- `/Width` makes the two shapes
// actually diverge (mutation-tested: deleting the pull-out
// `key.as_slice() == b"Length"` branch does not fail this suite
// without `/Width` present). Cross-checked against
// `Dictionary::write_pdf_stream_qdf` with the equivalent dict:
// `<<\n /DecodeParms <<\n >>\n /Filter /FlateDecode\n /Width 100\n /Length 3\n>>`.
let dict = ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
),
(b"DecodeParms".to_vec(), ObjectHandle::dictionary(vec![])),
(b"Length".to_vec(), ObjectHandle::integer(3)),
(b"Width".to_vec(), ObjectHandle::integer(100)),
]);
let mut out = Vec::new();
dict.unparse_stream_body_qdf(&mut out, 0).unwrap();
assert_eq!(
out,
b"<<\n /DecodeParms <<\n >>\n /Filter /FlateDecode\n /Width 100\n /Length 3\n>>"
);
}
#[test]
fn unparse_stream_body_qdf_writes_sig_contents_as_a_hex_string() {
// QDF sibling of `unparse_stream_body_writes_sig_contents_as_a_hex_string`
// above -- `unparse_stream_dict_entries_qdf` applies the same
// Sig+ByteRange special case its compact sibling does (see that
// function's own doc). `/Length` is pulled out and written last, at
// `indent + 2`, same as the non-Sig QDF stream shape above.
let dict = ObjectHandle::dictionary(vec![
(b"Type".to_vec(), ObjectHandle::name(b"Sig".to_vec())),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Contents".to_vec(), ObjectHandle::string(b"hi".to_vec())),
(b"Length".to_vec(), ObjectHandle::integer(2)),
]);
let mut out = Vec::new();
dict.unparse_stream_body_qdf(&mut out, 0).unwrap();
assert_eq!(
out,
b"<<\n /ByteRange [\n ]\n /Contents <6869>\n /Type /Sig\n /Length 2\n>>"
);
}
#[test]
fn unparse_stream_body_qdf_defers_type_and_byte_range_resolution_until_a_contents_key_is_reached(
) {
// QDF-stream sibling of
// `unparse_object_defers_type_and_byte_range_resolution_until_a_contents_key_is_reached`
// above -- `unparse_stream_dict_entries_qdf` needed the identical
// fix at its own call site. See that test's own doc for the full
// eager-vs-lazy rationale and why a plain success-vs-error
// assertion cannot discriminate this bug.
let (aaa, aaa_resolver) = error_resolving_handle(ObjectRef::new(99, 0));
drop(aaa_resolver);
let (sig_type, type_resolver) = error_resolving_handle(ObjectRef::new(30, 0));
drop(type_resolver);
let dict = ObjectHandle::dictionary(vec![
(b"AAA".to_vec(), aaa),
(b"Type".to_vec(), sig_type),
(b"ByteRange".to_vec(), ObjectHandle::array(vec![])),
(b"Length".to_vec(), ObjectHandle::integer(0)),
]);
let mut out = Vec::new();
let error = dict.unparse_stream_body_qdf(&mut out, 0).unwrap_err();
assert_eq!(error.to_string(), "object 99 0 belongs to a dropped PDF");
}
#[test]
fn unparse_stream_body_qdf_suppresses_a_null_valued_key() {
let dict = ObjectHandle::dictionary(vec![
(b"Length".to_vec(), ObjectHandle::integer(3)),
(b"Metadata".to_vec(), ObjectHandle::null()),
]);
let mut out = Vec::new();
dict.unparse_stream_body_qdf(&mut out, 0).unwrap();
// Cross-checked against a direct `Dictionary::write_pdf_stream_qdf`
// call on the equivalent dict *without* the null key removed: that
// call writes `/Metadata null` verbatim (`write_pdf_stream_qdf`
// itself applies no null suppression -- that is layered on top by
// `visible_dict_entries`, exactly like the compact
// `unparse_stream_dict_entries` does), confirming the suppression
// observed here is this primitive's own added behavior, not
// something already built into the legacy function it delegates
// scalar/container formatting to.
assert_eq!(out, b"<<\n /Length 3\n>>");
}
#[test]
fn unparse_stream_body_qdf_writes_an_empty_dict_when_every_entry_is_suppressed() {
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::null())]);
let mut out = Vec::new();
dict.unparse_stream_body_qdf(&mut out, 0).unwrap();
// No surviving entries and no `/Length`: matches
// `write_pdf_stream_qdf`'s own empty-input shape `<<\n>>` (no
// interior spaces at indent 0 -- `push_spaces(indent)` only adds
// spaces when `indent > 0`).
assert_eq!(out, b"<<\n>>");
}
#[test]
fn unparse_stream_body_qdf_respects_a_nonzero_indent() {
// Mirrors unparse_object_qdf_respects_a_nonzero_starting_indent:
// every other QDF test in this suite pins `indent = 0`, which would
// still pass with a stray hardcoded `0` inside the function body.
// Both values here are scalars, so this alone does not prove the
// `indent + 2` passed to `unparse_child_qdf` for each entry actually
// carries the caller's `indent` -- a scalar ignores that argument
// entirely (see `unparse_stream_body_qdf_respects_a_nonzero_indent_for_a_nested_container_value`
// below for the test that does). Cross-checked against
// `Dictionary::write_pdf_stream_qdf(&mut out, 4)` on the equivalent
// dict: `<<\n /A 1\n /Length 2\n >>`.
let dict = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::integer(1)),
(b"Length".to_vec(), ObjectHandle::integer(2)),
]);
let mut out = Vec::new();
dict.unparse_stream_body_qdf(&mut out, 4).unwrap();
assert_eq!(out, b"<<\n /A 1\n /Length 2\n >>");
}
#[test]
fn unparse_stream_body_qdf_respects_a_nonzero_indent_for_a_nested_container_value() {
// The test above only proves `indent` reaches the closing `>>`'s
// own `push_spaces` and the entry lines' *leading* `push_spaces(out,
// indent + 2)` -- both scalar values in it ignore the `indent + 2`
// this primitive also threads through `unparse_child_qdf(value,
// indent + 2, out)` for each entry (a scalar's own QDF form does
// not depend on indent at all). A nested container value does: its
// own children land at `(indent + 2) + 2`, and a hardcoded `2` in
// place of that `indent + 2` argument would still pass every other
// test in this suite (mutation-tested: it survives without this
// test). Cross-checked against `Dictionary::write_pdf_stream_qdf`
// with the equivalent dict at indent 4:
// `<<\n /DecodeParms <<\n /Predictor 12\n >>\n /Length 3\n >>`.
let dict = ObjectHandle::dictionary(vec![
(
b"DecodeParms".to_vec(),
ObjectHandle::dictionary(vec![(b"Predictor".to_vec(), ObjectHandle::integer(12))]),
),
(b"Length".to_vec(), ObjectHandle::integer(3)),
]);
let mut out = Vec::new();
dict.unparse_stream_body_qdf(&mut out, 4).unwrap();
assert_eq!(
out,
b"<<\n /DecodeParms <<\n /Predictor 12\n >>\n /Length 3\n >>"
);
}
#[test]
fn unparse_stream_body_qdf_writes_a_retained_indirect_entry_as_reference_form() {
// QDF-mode sibling of unparse_stream_body_writes_length_last_preserved
// that exercises unparse_child_qdf's indirect arm instead of a direct
// scalar -- unreached by the tests above, whose every value is
// direct.
let (indirect, _resolver) = resolver_bearing_handle(ObjectValue::Integer(7));
let dict = ObjectHandle::dictionary(vec![
(b"A".to_vec(), indirect),
(b"Length".to_vec(), ObjectHandle::integer(2)),
]);
let mut out = Vec::new();
dict.unparse_stream_body_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /A 20 0 R\n /Length 2\n>>");
}
#[test]
fn unparse_stream_body_qdf_uses_the_dictionary_of_a_direct_stream_value() {
// Mirrors unparse_stream_body_uses_the_dictionary_of_a_direct_stream_value:
// a *direct* Stream ObjectValue has no qpdf counterpart, but this
// primitive must still use its `stream_dict`'s entries rather than
// falling into the non-dictionary-self `<< >>` degrade below.
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(2))]);
let handle = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(b"ab".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let mut out = Vec::new();
handle.unparse_stream_body_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /Length 2\n>>");
}
#[test]
fn unparse_stream_body_qdf_on_an_indirect_handle_resolving_to_a_stream_uses_the_dictionary() {
// Mirrors unparse_stream_body_on_an_indirect_handle_resolving_to_a_stream_uses_the_dictionary:
// a real, reachable qpdf shape -- an indirect object whose resolved
// value is a stream (e.g. a production reader's own resolution of a
// stream object).
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(2))]);
let (indirect, _resolver) =
resolver_bearing_handle(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: Some(Rc::new(b"ab".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let mut out = Vec::new();
indirect.unparse_stream_body_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /Length 2\n>>");
}
#[test]
fn unparse_stream_body_qdf_resolves_an_unresolved_indirect_stream_dict() {
// Mirrors unparse_stream_body_resolves_an_unresolved_indirect_stream_dict:
// `stream_dict` is itself an `ObjectHandle` that may not yet be
// resolved. `self` stays a *direct* Stream value here so the only
// variable under test is `stream_dict`'s own resolution state:
// without the `stream_dict.try_dereference()?` call this primitive
// makes, `with_value` on a not-yet-resolved indirect handle returns
// `None` and this would degrade to `<< >>` instead of using the
// resolved dictionary's entries.
let (inner, _resolver) = resolver_bearing_handle(ObjectValue::Dictionary(
[(b"Length".to_vec(), ObjectHandle::integer(2))]
.into_iter()
.collect(),
));
let handle = ObjectHandle::stream(inner, Rc::new(b"ab".to_vec()));
let mut out = Vec::new();
handle.unparse_stream_body_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n /Length 2\n>>");
}
#[test]
fn unparse_stream_body_qdf_propagates_a_dropped_document_error_from_stream_dict() {
// Mirrors unparse_stream_body_propagates_a_dropped_document_error_from_stream_dict:
// the dropped document lives behind `stream_dict`, not `self`
// directly (`self` is a *direct* Stream value; only `stream_dict`
// is the as-yet-unresolved indirect handle whose resolver is
// dropped).
let (inner, resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(resolver);
let handle = ObjectHandle::stream(inner, Rc::new(b"ab".to_vec()));
let mut out = Vec::new();
assert!(handle.unparse_stream_body_qdf(&mut out, 0).is_err());
}
#[test]
fn unparse_stream_body_qdf_writes_empty_dict_when_stream_dict_is_not_a_dictionary() {
// Mirrors unparse_stream_body_writes_empty_dict_when_stream_dict_is_not_a_dictionary:
// `stream_dict` is itself typed as an `ObjectHandle`, so nothing at
// the type level prevents it from resolving to something other than
// a `Dictionary`.
let handle = ObjectHandle::stream(ObjectHandle::integer(5), Rc::new(b"ab".to_vec()));
let mut out = Vec::new();
handle.unparse_stream_body_qdf(&mut out, 0).unwrap();
assert_eq!(out, b"<<\n>>");
}
#[test]
fn unparse_stream_body_qdf_writes_empty_dict_for_a_non_dictionary_self() {
// Mirrors unparse_stream_body_writes_empty_dict_for_a_non_dictionary_self:
// pins the doc comment's typed-input-assumption claim.
let mut out = Vec::new();
ObjectHandle::integer(5)
.unparse_stream_body_qdf(&mut out, 0)
.unwrap();
assert_eq!(out, b"<<\n>>");
}
#[test]
fn unparse_stream_body_qdf_propagates_a_dropped_document_error() {
// Mirrors unparse_stream_body_propagates_a_dropped_document_error:
// an as-yet-unresolved indirect handle whose document has been
// dropped must surface as an error here too, not silently degrade
// to an empty `<< >>` the way an unresolved `with_value` read alone
// would.
let (indirect, resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(resolver);
let mut out = Vec::new();
assert!(indirect.unparse_stream_body_qdf(&mut out, 0).is_err());
}
#[test]
fn unparse_trailer_classic_forces_id_and_encrypt_last() {
let dict = ObjectHandle::dictionary(vec![
(b"Size".to_vec(), ObjectHandle::integer(9)),
(b"Root".to_vec(), ObjectHandle::integer(1)), // stand-in reference shape
(b"Encrypt".to_vec(), ObjectHandle::integer(9)),
(
b"ID".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::string(vec![0u8; 16]),
ObjectHandle::string(vec![1u8; 16]),
]),
),
]);
let mut out = Vec::new();
dict.write_trailer(&mut out, false, None).unwrap();
let text = String::from_utf8_lossy(&out);
assert!(text.starts_with("trailer << "));
assert!(text.ends_with(">>"));
// /Root and /Size appear before /ID, /ID appears before /Encrypt,
// regardless of the dict's own (alphabetical) key order.
let root_pos = text.find("/Root").unwrap();
let id_pos = text.find("/ID").unwrap();
let encrypt_pos = text.find("/Encrypt").unwrap();
assert!(root_pos < id_pos);
assert!(id_pos < encrypt_pos);
}
#[test]
fn unparse_trailer_xref_stream_does_not_write_its_own_open_brace() {
// The caller (a future `writeXRefStream`-shaped consumer) has
// already opened `<<` and hand-emitted the xref-specific keys
// before calling this method with `xref_stream = true` -- see
// this method's own doc for why those keys are never part of
// `entries` here to begin with.
let dict = ObjectHandle::dictionary(vec![(b"Size".to_vec(), ObjectHandle::integer(9))]);
let mut out = Vec::new();
dict.write_trailer(&mut out, true, None).unwrap();
assert!(!String::from_utf8_lossy(&out).contains("<<"));
assert!(String::from_utf8_lossy(&out).ends_with(">>"));
}
#[test]
fn unparse_trailer_without_id_or_encrypt_omits_both() {
let dict = ObjectHandle::dictionary(vec![(b"Size".to_vec(), ObjectHandle::integer(9))]);
let mut out = Vec::new();
dict.write_trailer(&mut out, false, None).unwrap();
let text = String::from_utf8_lossy(&out);
assert!(!text.contains("/ID"));
assert!(!text.contains("/Encrypt"));
}
#[test]
fn unparse_trailer_does_not_suppress_a_null_valued_key() {
// writeTrailer's own key loop has no isNull check anywhere in it
// (QPDFWriter.cc:1174-1192) -- unlike unparseObject's dictionary
// branch. `/Prev` is chosen only as a convenient never-suppressed
// example key for this unit-level test; in production `/Prev`
// itself would already have been stripped by the caller before
// this primitive ever sees the dict (see this method's own doc on
// the `getTrimmedTrailer`-equivalent split), so this does not
// claim `/Prev` null survives end to end -- only that *this*
// primitive's key loop applies no suppression to whatever keys
// the caller does hand it.
let dict = ObjectHandle::dictionary(vec![
(b"Size".to_vec(), ObjectHandle::integer(9)),
(b"Prev".to_vec(), ObjectHandle::null()),
]);
let mut out = Vec::new();
dict.write_trailer(&mut out, false, None).unwrap();
assert!(String::from_utf8_lossy(&out).contains("/Prev null"));
}
#[test]
fn unparse_trailer_id_writer_substitutes_the_id_value() {
let dict = ObjectHandle::dictionary(vec![
(b"Size".to_vec(), ObjectHandle::integer(9)),
(
b"ID".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::string(vec![0u8; 16]),
ObjectHandle::string(vec![0u8; 16]),
]),
),
]);
let mut out = Vec::new();
let mut id_writer = |out: &mut Vec<u8>| out.extend_from_slice(b"<computed>");
dict.write_trailer(&mut out, false, Some(&mut id_writer))
.unwrap();
assert!(String::from_utf8_lossy(&out).contains("/ID <computed>"));
}
#[test]
fn unparse_trailer_id_writer_none_uses_qpdf_compact_hex_shape() {
// Pins the exact byte shape unparse_trailer_id_writer_substitutes_the_id_value's
// dict (all-zero bytes) can't distinguish from a generic array
// serialization -- mirrors write_id_style_value_emits_compact_hex_pair
// (object.rs) byte-for-byte.
let dict = ObjectHandle::dictionary(vec![
(b"Size".to_vec(), ObjectHandle::integer(9)),
(
b"ID".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::string(vec![0xabu8, 0xcdu8, 0xefu8]),
ObjectHandle::string(vec![0x12u8, 0x34u8, 0x56u8]),
]),
),
]);
let mut out = Vec::new();
dict.write_trailer(&mut out, false, None).unwrap();
assert_eq!(out, b"trailer << /Size 9 /ID [<abcdef><123456>] >>");
}
#[test]
fn unparse_trailer_id_writer_none_falls_back_for_unexpected_id_shape() {
// Mirrors write_id_style_value_falls_back_for_unexpected_shapes
// (object.rs): wrong arity falls back to the generic array
// serializer (spaces) rather than silently truncating to two
// elements.
let dict = ObjectHandle::dictionary(vec![(
b"ID".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::string(vec![0x00u8]),
ObjectHandle::string(vec![0x11u8]),
ObjectHandle::string(vec![0x8fu8]),
]),
)]);
let mut out = Vec::new();
dict.write_trailer(&mut out, false, None).unwrap();
assert_eq!(out, b"trailer << /ID [ <00> <11> <8f> ] >>");
}
#[test]
fn unparse_trailer_id_writer_none_falls_back_for_non_string_element() {
// Mirrors write_id_style_value_falls_back_for_unexpected_shapes
// (object.rs): right arity (2 elements) but a non-String element
// type falls back to the generic array serializer rather than
// treating the element as a string.
let dict = ObjectHandle::dictionary(vec![(
b"ID".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::integer(1),
ObjectHandle::string(vec![0x8fu8]),
]),
)]);
let mut out = Vec::new();
dict.write_trailer(&mut out, false, None).unwrap();
assert_eq!(out, b"trailer << /ID [ 1 <8f> ] >>");
}
#[test]
fn unparse_trailer_id_writer_none_falls_back_for_scalar_id() {
// Mirrors write_id_style_value_falls_back_for_unexpected_shapes
// (object.rs): a non-array /ID value is delegated to unparse_child
// verbatim rather than being routed through the compact-pair path.
let dict = ObjectHandle::dictionary(vec![(b"ID".to_vec(), ObjectHandle::integer(7))]);
let mut out = Vec::new();
dict.write_trailer(&mut out, false, None).unwrap();
assert_eq!(out, b"trailer << /ID 7 >>");
}
#[test]
fn unparse_trailer_writes_an_indirect_id_as_reference_form_not_inlined() {
// `object_ref().is_some()` must be checked before shape inspection
// in write_id_style_value_handle: an indirect /ID value (not a
// shape real qpdf itself ever produces, but nothing at the type
// level rules it out) writes as its own "N G R" form, the same
// reference-vs-recurse split unparse_child applies everywhere else
// in this primitive family -- never inlined as compact hex even
// though it would resolve to a matching Array([String, String])
// shape.
let (indirect_id, _resolver) = resolver_bearing_handle(ObjectValue::Array(vec![
ObjectHandle::string(vec![0u8; 2]),
ObjectHandle::string(vec![1u8; 2]),
]));
let dict = ObjectHandle::dictionary(vec![
(b"Size".to_vec(), ObjectHandle::integer(9)),
(b"ID".to_vec(), indirect_id),
]);
let mut out = Vec::new();
dict.write_trailer(&mut out, false, None).unwrap();
let text = String::from_utf8_lossy(&out);
assert!(text.contains("/ID 20 0 R"));
assert!(!text.contains("[<"));
}
#[test]
fn unparse_trailer_writes_empty_shell_for_a_non_dictionary_self() {
// Mirrors unparse_stream_body_writes_empty_dict_for_a_non_dictionary_self:
// a non-dictionary `self` degrades to an empty trailer shell
// rather than panicking or erroring, matching write_pdf_trailer's
// own typed-input assumption.
let mut out = Vec::new();
ObjectHandle::integer(5)
.write_trailer(&mut out, false, None)
.unwrap();
assert_eq!(out, b"trailer << >>");
}
#[test]
fn unparse_trailer_resolves_an_unresolved_indirect_trailer_dict() {
// Without the `self.try_dereference()?` call this method makes
// before `with_value`, `with_value` on a not-yet-resolved
// indirect handle returns `None` and this would degrade to an
// empty `trailer << >>` shell instead of using the resolved
// dictionary's entries -- mirrors
// unparse_stream_body_resolves_an_unresolved_indirect_stream_dict's
// same proof for the same fix pattern.
let (indirect, _resolver) = resolver_bearing_handle(ObjectValue::Dictionary(
[(b"Size".to_vec(), ObjectHandle::integer(9))]
.into_iter()
.collect(),
));
let mut out = Vec::new();
indirect.write_trailer(&mut out, false, None).unwrap();
assert_eq!(out, b"trailer << /Size 9 >>");
}
#[test]
fn unparse_trailer_propagates_a_dropped_document_error() {
// Mirrors unparse_stream_body_propagates_a_dropped_document_error:
// an as-yet-unresolved indirect handle whose document has been
// dropped must surface as an error here too, not silently degrade
// to an empty `trailer << >>` shell the way an unresolved
// `with_value` read alone would.
let (indirect, resolver) = resolver_bearing_handle(ObjectValue::Null);
drop(resolver);
let mut out = Vec::new();
assert!(indirect.write_trailer(&mut out, false, None).is_err());
}
}
#[cfg(test)]
mod mutation_tests {
use super::*;
#[test]
fn make_direct_rebinds_only_the_receiver_and_isolates_repeated_indirect_children() {
let shared_array = ObjectHandle::new_indirect_unresolved(ObjectRef::new(11, 0), -1);
shared_array.set_resolved(ObjectValue::Array(vec![
ObjectHandle::integer(1),
ObjectHandle::integer(2),
ObjectHandle::integer(3),
]));
let original = ObjectHandle::dictionary(vec![
(b"A".to_vec(), shared_array.clone()),
(
b"B".to_vec(),
ObjectHandle::dictionary(vec![(b"A".to_vec(), shared_array.clone())]),
),
]);
let original_alias = original.clone();
let mut direct = original;
direct.make_direct(false).expect("direct conversion");
assert!(original_alias.as_dictionary().is_some());
assert!(original_alias.try_get_key(b"/A").unwrap().is_indirect());
let first = direct.try_get_key(b"/A").unwrap();
let second = direct
.try_get_key(b"/B")
.unwrap()
.try_get_key(b"/A")
.unwrap();
assert!(first.is_direct());
assert!(second.is_direct());
assert!(!first.is_same_object_as(&second));
first
.set_array_item(1, ObjectHandle::integer(5))
.expect("mutate first copied array");
assert_eq!(
first.try_array_item(1).unwrap().unwrap().as_integer(),
Some(5)
);
assert_eq!(
second.try_array_item(1).unwrap().unwrap().as_integer(),
Some(2)
);
}
#[test]
fn make_direct_stops_at_streams_only_when_allowed() {
let stream = ObjectHandle::new_indirect_unresolved(ObjectRef::new(12, 0), -1);
stream.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: Some(Rc::new(b"salad".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let original = ObjectHandle::dictionary(vec![(b"Stream".to_vec(), stream.clone())]);
let mut rejects_stream = original.clone();
let error = rejects_stream
.make_direct(false)
.expect_err("makeDirect must reject a stream without allow_streams");
assert!(matches!(
error,
Error::System(message)
if message == "attempt to make a stream into a direct object"
));
assert!(rejects_stream
.try_get_key(b"/Stream")
.unwrap()
.is_indirect());
let mut stops_at_stream = original;
stops_at_stream
.make_direct(true)
.expect("allow_streams must preserve the stream reference");
assert!(stops_at_stream
.try_get_key(b"/Stream")
.unwrap()
.is_indirect());
assert!(stops_at_stream
.try_get_key(b"/Stream")
.unwrap()
.is_same_object_as(&stream));
}
#[test]
fn make_direct_reports_an_indirect_cycle_without_rebinding_the_receiver() {
let first = ObjectHandle::new_indirect_unresolved(ObjectRef::new(8, 0), -1);
let second = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), -1);
first.set_resolved(ObjectValue::Dictionary(
[(b"/A".to_vec(), second.clone())].into_iter().collect(),
));
second.set_resolved(ObjectValue::Array(vec![first.clone()]));
let alias = first.clone();
let mut candidate = first;
let error = candidate
.make_direct(false)
.expect_err("recursive indirect graph must be rejected");
assert!(matches!(
error,
Error::System(message)
if message == "loop detected while converting object from indirect to direct"
));
assert!(candidate.is_indirect());
assert!(candidate.is_same_object_as(&alias));
}
#[test]
fn make_direct_rejects_reserved_and_non_pdf_object_values() {
let mut reserved = ObjectHandle::new_reserved_direct();
let reserved_error = reserved
.make_direct(false)
.expect_err("reserved handles cannot become direct values");
assert!(matches!(
reserved_error,
Error::System(message)
if message == "QPDFObjectHandle: attempting to make a reserved object handle direct"
));
let mut operator = ObjectHandle::operator(b"q".to_vec());
let operator_error = operator
.make_direct(false)
.expect_err("content operators are not PDF object values");
assert!(matches!(
operator_error,
Error::System(message)
if message == "QPDFObjectHandle::makeDirectInternal: unknown object type"
));
}
struct SourcePipeResolver {
value: ObjectValue,
bytes: Vec<u8>,
calls: RefCell<Vec<(bool, bool)>>,
warnings: RefCell<Vec<String>>,
fail_first: bool,
fail_with_error: bool,
}
impl DocumentResolver for SourcePipeResolver {
fn warn(&self, warning: QpdfExc) -> crate::Result<()> {
self.warnings
.borrow_mut()
.push(String::from_utf8_lossy(warning.what_bytes()).into_owned());
Ok(())
}
fn warn_stream_data(&self, warning: QpdfExc) -> crate::Result<()> {
self.warnings
.borrow_mut()
.push(String::from_utf8_lossy(warning.what_bytes()).into_owned());
Ok(())
}
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
handle.set_resolved(self.value.clone());
Ok(())
}
fn pipe_stream_data(
&self,
_object_ref: ObjectRef,
_offset: i64,
_length: usize,
_stream_dict: &ObjectHandle,
pipeline: &mut dyn Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> crate::Result<bool> {
self.calls
.borrow_mut()
.push((suppress_warnings, will_retry));
if self.fail_with_error {
return Err(crate::Error::Internal("source pipe failure".to_owned()));
}
if self.fail_first && self.calls.borrow().len() == 1 {
return Ok(false);
}
pipeline.write(&self.bytes)?;
pipeline.finish()?;
Ok(true)
}
}
#[test]
fn pipe_stream_data_rejects_a_non_stream_handle() {
let scalar = ObjectHandle::integer(7);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
let error = scalar
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::None,
false,
false,
)
.unwrap_err();
assert!(matches!(
error,
Error::Internal(message) if message == "pipeStreamData called for non-stream"
));
}
#[test]
fn pipe_stream_data_decodes_replaced_flate_through_the_sink() {
let dict = ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
)]);
let stream = ObjectHandle::stream(
dict,
Rc::new(vec![
0x78, 0x9c, 0xcb, 0x48, 0xcd, 0xc9, 0xc9, 0x07, 0x00, 0x06, 0x2c, 0x02, 0x15,
]),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
let success = stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.expect("replaced stream should decode");
assert!(success);
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"hello");
}
#[test]
fn pipe_stream_data_decodes_a_tiff_predictor_through_the_canonical_chain() {
let dict = ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
),
(
b"DecodeParms".to_vec(),
ObjectHandle::dictionary(vec![
(b"Predictor".to_vec(), ObjectHandle::integer(2)),
(b"Columns".to_vec(), ObjectHandle::integer(4)),
(b"Colors".to_vec(), ObjectHandle::integer(1)),
(b"BitsPerComponent".to_vec(), ObjectHandle::integer(8)),
]),
),
]);
let stream = ObjectHandle::stream(
dict,
Rc::new(vec![
0x78, 0x9c, 0xe3, 0xe2, 0xe2, 0xe2, 0x02, 0x00, 0x00, 0x68, 0x00, 0x29,
]),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), [10, 20, 30, 40]);
}
#[test]
fn pipe_stream_data_builds_reverse_decoder_chain() {
let dict = ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::name(b"ASCIIHexDecode".to_vec()),
ObjectHandle::name(b"FlateDecode".to_vec()),
]),
),
(b"DecodeParms".to_vec(), ObjectHandle::array(vec![])),
]);
let stream = ObjectHandle::stream(dict, Rc::new(b"789ccb48cdc9c90700062c0215>".to_vec()));
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"hello");
}
#[test]
fn pipe_stream_data_reads_original_source_through_the_filter_chain() {
let dict = ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
)]);
let encoded = vec![
0x78, 0x9c, 0xcb, 0x48, 0xcd, 0xc9, 0xc9, 0x07, 0x00, 0x06, 0x2c, 0x02, 0x15,
];
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: encoded.len(),
})),
bytes: encoded,
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: false,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"hello");
assert_eq!(resolver.calls.borrow().as_slice(), &[(false, false)]);
}
#[test]
fn pipe_stream_data_propagates_a_filtered_source_error() {
let raw = b"source error".to_vec();
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
)]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw,
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: false,
fail_with_error: true,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
let error = stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap_err();
assert!(matches!(
error,
Error::Internal(message) if message == "source pipe failure"
));
assert!(filtering_attempted);
assert_eq!(resolver.calls.borrow().as_slice(), &[(false, false)]);
}
#[test]
fn get_stream_data_maps_a_filtered_source_retry_to_an_error() {
let raw = b"source error".to_vec();
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
)]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw,
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: true,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let error = stream
.get_stream_data(crate::writer::DecodeLevel::Generalized)
.expect_err("a failed filtered source must not be reported as decoded data");
assert!(matches!(
error,
Error::QpdfExc(error)
if error.get_error_code() == QpdfErrorCode::Unsupported
&& error.get_file_position() == 9
&& error.get_object().is_empty()
&& error.get_message_detail() == b"getStreamData called on unfilterable stream"
));
assert_eq!(resolver.calls.borrow().as_slice(), &[(false, false)]);
}
#[test]
fn get_stream_data_rejects_filters_gated_by_the_requested_decode_level() {
for (filter, decode_level) in [
(b"DCTDecode".as_slice(), DecodeLevel::Generalized),
(b"RunLengthDecode".as_slice(), DecodeLevel::Generalized),
] {
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(filter.to_vec()),
)]),
Rc::new(b"raw filtered bytes".to_vec()),
);
let error = stream
.get_stream_data(decode_level)
.expect_err("gated raw bytes must not be labeled as decoded");
assert!(matches!(
error,
Error::QpdfExc(error)
if error.get_error_code() == QpdfErrorCode::Unsupported
&& error.get_message_detail() == b"getStreamData called on unfilterable stream"
));
}
}
#[test]
fn pipe_stream_data_resolves_filter_and_decode_parameter_values_through_the_document() {
let (filter, _filter_resolver) = super::identity_tests::resolver_bearing_handle(
ObjectValue::Name(b"FlateDecode".to_vec()),
);
let (predictor, _predictor_resolver) =
super::identity_tests::resolver_bearing_handle(ObjectValue::Integer(1));
let dict = ObjectHandle::dictionary(vec![
(b"Filter".to_vec(), filter),
(
b"DecodeParms".to_vec(),
ObjectHandle::dictionary(vec![(b"Predictor".to_vec(), predictor)]),
),
]);
let stream = ObjectHandle::stream(
dict,
Rc::new(vec![
0x78, 0x9c, 0xcb, 0x48, 0xcd, 0xc9, 0xc9, 0x07, 0x00, 0x06, 0x2c, 0x02, 0x15,
]),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"hello");
}
#[test]
fn pipe_stream_data_reports_filter_failure_separately_for_raw_retry() {
let dict = ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
)]);
let raw = vec![1, 2, 3, 4];
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict,
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw.clone(),
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: true,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut failed_sink = crate::pipeline::buffer::Buffer::new("failed", None);
let mut filtering_attempted = false;
assert!(!stream
.pipe_stream_data(
&mut failed_sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
// qpdf clears its filtering flag when the original source reports a
// failure, even though the filter chain was constructed. The caller
// uses the false result and flag to enter the raw retry path.
assert!(!filtering_attempted);
let mut retry_sink = crate::pipeline::buffer::Buffer::new("retry", None);
assert!(stream
.pipe_stream_data(
&mut retry_sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::None,
false,
true,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(retry_sink.take_buffer().unwrap(), raw);
assert_eq!(
resolver.calls.borrow().as_slice(),
&[(false, false), (false, true)]
);
}
#[test]
fn pipe_stream_data_preserves_an_unsupported_filter_without_attempting_filtering() {
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"UnknownDecode".to_vec()),
)]),
Rc::new(b"raw".to_vec()),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = true;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"raw");
}
#[test]
fn pipe_stream_data_checks_unknown_factory_before_decode_parms_shape() {
let raw = b"raw unknown".to_vec();
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::name(b"UnknownDecode".to_vec()),
),
(
b"DecodeParms".to_vec(),
ObjectHandle::array(vec![ObjectHandle::null(), ObjectHandle::null()]),
),
]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw.clone(),
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: false,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = true;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), raw);
assert!(resolver.warnings.borrow().is_empty());
}
#[test]
fn pipe_stream_data_warns_for_mismatched_decode_parms_before_source() {
let raw = b"raw mismatch".to_vec();
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::name(b"FlateDecode".to_vec()),
ObjectHandle::name(b"ASCIIHexDecode".to_vec()),
]),
),
(
b"DecodeParms".to_vec(),
ObjectHandle::array(vec![ObjectHandle::null()]),
),
]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw.clone(),
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: false,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = true;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), raw);
assert_eq!(
resolver.warnings.borrow().as_slice(),
&["offset 9: stream /DecodeParms length is inconsistent with filters"]
);
}
#[test]
fn pipe_stream_data_applies_aligned_decode_parms_across_filter_stages() {
let inner = crate::stream_filter::encode_flate(b"hello").unwrap();
let encoded = crate::stream_filter::encode_flate(&inner).unwrap();
let dict = ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::name(b"FlateDecode".to_vec()),
ObjectHandle::name(b"FlateDecode".to_vec()),
]),
),
(
b"DecodeParms".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::dictionary(vec![(
b"Predictor".to_vec(),
ObjectHandle::integer(1),
)]),
ObjectHandle::dictionary(vec![(
b"Predictor".to_vec(),
ObjectHandle::integer(1),
)]),
]),
),
]);
let stream = ObjectHandle::stream(dict, Rc::new(encoded));
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"hello");
}
#[test]
fn prepare_filter_plan_runs_later_setters_after_an_earlier_rejection() {
let (huge_columns, recorder) =
super::warning_emission_tests::handle_resolving(ObjectValue::Integer(i64::MAX));
let first_params =
ObjectHandle::dictionary(vec![(b"Predictor".to_vec(), ObjectHandle::integer(0))]);
let second_params = ObjectHandle::dictionary(vec![(b"Columns".to_vec(), huge_columns)]);
let dict = ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::name(b"FlateDecode".to_vec()),
ObjectHandle::name(b"LZWDecode".to_vec()),
]),
),
(
b"DecodeParms".to_vec(),
ObjectHandle::array(vec![first_params, second_params]),
),
]);
let stream = ObjectHandle::stream(dict.clone(), Rc::new(Vec::new()));
assert!(stream.prepare_stream_filter_plan(&dict).unwrap().is_none());
assert!(super::warning_emission_tests::warnings(&recorder)
.iter()
.any(|warning| warning
.contains("requested value of integer is too big; returning INT_MAX")));
}
#[test]
fn pipe_stream_data_keeps_crypt_as_a_no_stage_after_filterability() {
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![
(b"Filter".to_vec(), ObjectHandle::name(b"Crypt".to_vec())),
(
b"DecodeParms".to_vec(),
ObjectHandle::dictionary(vec![(
b"Name".to_vec(),
ObjectHandle::name(b"Identity".to_vec()),
)]),
),
]),
Rc::new(b"already clear".to_vec()),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"already clear");
}
#[test]
fn pipe_stream_data_reports_flate_warnings_through_stream_data_sink() {
let raw = vec![0x78];
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
)]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw,
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: false,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert!(sink.take_buffer().unwrap().is_empty());
assert_eq!(
resolver.warnings.borrow().as_slice(),
&["offset 9: input stream is complete but output may still be valid"]
);
resolver.warnings.borrow_mut().clear();
let mut suppressed_sink = crate::pipeline::buffer::Buffer::new("suppressed", None);
assert!(stream
.pipe_stream_data(
&mut suppressed_sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
true,
false,
)
.unwrap());
assert!(filtering_attempted);
assert!(suppressed_sink.take_buffer().unwrap().is_empty());
assert!(resolver.warnings.borrow().is_empty());
}
#[test]
fn pipe_stream_data_reports_normalizer_warnings_only_after_source_success() {
let raw = b"<0g".to_vec();
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw.clone(),
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: false,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
STREAM_ENCODE_NORMALIZE,
crate::writer::DecodeLevel::None,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), raw);
assert_eq!(
resolver.warnings.borrow().as_slice(),
&[
"offset 9: content normalization encountered bad tokens",
"offset 9: normalized content ended with a bad token; you may be able to resolve this by coalescing content streams in combination with normalizing content. From the command line, specify --coalesce-contents",
"offset 9: Resulting stream data may be corrupted but is may still useful for manual inspection. For more information on this warning, search for content normalization in the manual.",
]
);
resolver.warnings.borrow_mut().clear();
let mut suppressed_sink = crate::pipeline::buffer::Buffer::new("suppressed", None);
assert!(stream
.pipe_stream_data(
&mut suppressed_sink,
&mut filtering_attempted,
STREAM_ENCODE_NORMALIZE,
crate::writer::DecodeLevel::None,
true,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(suppressed_sink.take_buffer().unwrap(), raw);
assert!(resolver.warnings.borrow().is_empty());
}
#[test]
fn pipe_stream_data_normalizer_warnings_use_the_stream_data_offset() {
let mut pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf
.new_stream_with_data(Rc::new(b"<0g".to_vec()))
.expect("stream");
stream.reset_parsed_offset();
stream.set_parsed_offset_if_unset(9);
pdf.set_suppress_warnings(true);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
STREAM_ENCODE_NORMALIZE,
crate::writer::DecodeLevel::None,
false,
false,
)
.expect("normalize stream"));
let diagnostics = pdf.repair_diagnostics();
assert_eq!(diagnostics.entries().len(), 3);
let offsets: Vec<_> = diagnostics
.entries()
.iter()
.map(|diagnostic| diagnostic.get_file_position())
.collect();
assert_eq!(offsets, vec![9; 3]);
}
#[test]
fn pipe_stream_data_programmatic_normalizer_warnings_use_object_fallback() {
let mut pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf
.new_stream_with_data(Rc::new(b"<0g".to_vec()))
.expect("stream");
stream.reset_parsed_offset();
pdf.set_suppress_warnings(true);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
STREAM_ENCODE_NORMALIZE,
crate::writer::DecodeLevel::None,
false,
false,
)
.expect("normalize programmatic stream"));
let diagnostics = pdf.repair_diagnostics();
assert_eq!(diagnostics.entries().len(), 3);
assert!(diagnostics
.entries()
.iter()
.all(|diagnostic| diagnostic.get_file_position() == 0));
}
#[test]
fn pipe_stream_data_gates_specialized_filters_by_decode_level() {
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"DCTDecode".to_vec()),
)]),
Rc::new(b"jpeg bytes".to_vec()),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = true;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"jpeg bytes");
}
#[test]
fn pipe_stream_data_gates_non_lossy_specialized_filters_separately() {
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"RunLengthDecode".to_vec()),
)]),
Rc::new(vec![0xff, b'A', 0x80]),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = true;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), vec![0xff, b'A', 0x80]);
}
#[test]
fn pipe_stream_data_accepts_a_qpdf_unbounded_filter_chain() {
let filter_count = 17;
let mut filters = Vec::with_capacity(filter_count);
let mut encoded = b"A".to_vec();
for _ in 0..filter_count {
let mut wrapped = Vec::with_capacity(encoded.len() * 2 + 1);
for byte in encoded {
wrapped.extend_from_slice(format!("{byte:02x}").as_bytes());
}
wrapped.push(b'>');
encoded = wrapped;
filters.push(ObjectHandle::name(b"ASCIIHexDecode".to_vec()));
}
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![(b"Filter".to_vec(), ObjectHandle::array(filters))]),
Rc::new(encoded),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"A");
}
#[test]
fn pipe_stream_data_warns_and_retries_raw_for_a_malformed_filter_shape() {
let raw = b"raw malformed".to_vec();
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::integer(7),
)]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw.clone(),
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: false,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = true;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), raw);
assert_eq!(
resolver.warnings.borrow().as_slice(),
&["offset 9: stream filter type is not name or array"]
);
}
#[test]
fn pipe_stream_data_warns_for_a_non_name_filter_array_item() {
let raw = b"raw malformed array".to_vec();
let resolver = Rc::new(SourcePipeResolver {
value: ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::name(b"FlateDecode".to_vec()),
ObjectHandle::integer(7),
]),
)]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: raw.len(),
})),
bytes: raw.clone(),
calls: RefCell::new(Vec::new()),
warnings: RefCell::new(Vec::new()),
fail_first: false,
fail_with_error: false,
});
let resolver_handle: Rc<dyn DocumentResolver> = resolver.clone();
let stream = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(20, 0),
Rc::downgrade(&resolver_handle),
);
stream.set_parsed_offset_if_unset(9);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = true;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::Generalized,
false,
false,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), raw);
assert_eq!(
resolver.warnings.borrow().as_slice(),
&["offset 9: stream filter type is not name or array"]
);
}
#[test]
fn pipe_stream_data_rejects_present_decode_parms_for_dct_before_stage_build() {
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![
(
b"Filter".to_vec(),
ObjectHandle::name(b"DCTDecode".to_vec()),
),
(
b"DecodeParms".to_vec(),
ObjectHandle::dictionary(vec![(
b"Predictor".to_vec(),
ObjectHandle::integer(1),
)]),
),
]),
Rc::new(b"raw jpeg".to_vec()),
);
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = true;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::All,
false,
false,
)
.unwrap());
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().unwrap(), b"raw jpeg");
}
#[test]
fn pipe_stream_data_normalizes_before_compressing_output() {
let stream =
ObjectHandle::stream(ObjectHandle::dictionary(vec![]), Rc::new(b"q\rQ".to_vec()));
let mut sink = crate::pipeline::buffer::Buffer::new("sink", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
STREAM_ENCODE_COMPRESS | STREAM_ENCODE_NORMALIZE,
crate::writer::DecodeLevel::None,
false,
false,
)
.unwrap());
let compressed = sink.take_buffer().unwrap();
let mut decoded = Vec::new();
std::io::Read::read_to_end(
&mut flate2::read::ZlibDecoder::new(compressed.as_slice()),
&mut decoded,
)
.unwrap();
assert!(filtering_attempted);
assert_eq!(decoded, b"q\nQ");
}
#[test]
fn stream_data_filterability_probe_rejects_an_unknown_filter_without_piping_source() {
let stream = ObjectHandle::stream(
ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"BogusDecode".to_vec()),
)]),
Rc::new(b"encoded".to_vec()),
);
assert!(!stream
.stream_data_filterable(DecodeLevel::All)
.expect("filterability probe should not read source data"));
}
#[test]
fn stream_data_filterability_probe_rejects_a_non_stream_handle() {
let error = ObjectHandle::integer(7)
.stream_data_filterable(DecodeLevel::All)
.expect_err("filterability probe requires a stream handle");
assert!(matches!(
error,
crate::Error::Internal(message) if message == "pipeStreamData called for non-stream"
));
}
#[test]
fn object_value_clone_preserves_scalar_content() {
let value = ObjectValue::Integer(42);
let cloned = value.clone();
assert!(matches!(cloned, ObjectValue::Integer(42)));
}
#[test]
fn object_value_clone_of_a_dictionary_shares_child_identity() {
let child = ObjectHandle::integer(7);
let dict = ObjectValue::Dictionary([(b"/K".to_vec(), child.clone())].into_iter().collect());
let cloned = dict.clone();
let ObjectValue::Dictionary(entries) = cloned else {
panic!("expected dictionary"); // cov:ignore: unreachable in a passing run
};
assert!(entries.get(b"/K".as_slice()).unwrap().ptr_eq(&child));
}
#[test]
fn get_key_returns_a_live_child_handle_without_snapshotting_the_dictionary() {
let child = ObjectHandle::integer(1);
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), child.clone())]);
let fetched = dict.try_get_key(b"/A").unwrap();
assert!(fetched.ptr_eq(&child));
}
#[test]
fn get_key_on_a_missing_key_returns_a_direct_null_handle() {
let dict = ObjectHandle::dictionary(vec![]);
assert!(dict.try_get_key(b"/Missing").unwrap().is_null());
}
#[test]
fn try_get_key_on_a_non_dictionary_handle_reports_qpdf_type_warning() {
let scalar = ObjectHandle::integer(5);
assert!(matches!(
scalar.try_get_key(b"/A"),
Err(crate::Error::QpdfExc(error))
if error.get_message_detail() == b"operation for dictionary attempted on object of type integer: returning null for attempted key retrieval"
));
}
#[test]
fn replace_key_mutates_the_live_dictionary_in_place() {
let dict = ObjectHandle::dictionary(vec![]);
let clone = dict.clone();
dict.replace_key(b"/A", ObjectHandle::integer(9)).unwrap();
assert_eq!(clone.try_get_key(b"/A").unwrap().as_integer(), Some(9));
}
#[test]
fn replace_key_overwrites_an_existing_key() {
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::integer(1))]);
dict.replace_key(b"/A", ObjectHandle::integer(2)).unwrap();
assert_eq!(dict.try_get_key(b"/A").unwrap().as_integer(), Some(2));
}
#[test]
fn replace_key_with_direct_null_removes_an_existing_key_and_detaches_its_child() {
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, -1);
let child = ObjectHandle::dictionary(vec![]);
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), child.clone())]);
owner.set_resolved(ObjectValue::Dictionary(
[(b"Nested".to_vec(), dict.clone())].into_iter().collect(),
));
dict.replace_key(b"/A", ObjectHandle::null()).unwrap();
assert!(!dict.try_has_key(b"/A").unwrap());
assert!(child.containing_object_refs().is_empty());
}
#[test]
fn replace_key_with_direct_null_keeps_a_missing_key_absent() {
let dict = ObjectHandle::dictionary(vec![]);
dict.replace_key(b"/Missing", ObjectHandle::null()).unwrap();
assert!(!dict.try_has_key(b"/Missing").unwrap());
}
#[test]
fn replace_key_with_direct_null_mutates_a_resolved_indirect_dictionary() {
let dict = ObjectHandle::new_indirect_unresolved(ObjectRef::new(7, 0), -1);
dict.set_resolved(ObjectValue::Dictionary(
[(b"A".to_vec(), ObjectHandle::integer(1))]
.into_iter()
.collect(),
));
dict.replace_key(b"/A", ObjectHandle::null()).unwrap();
assert!(!dict.try_has_key(b"/A").unwrap());
}
#[test]
fn replace_key_with_direct_null_on_a_non_dictionary_reports_qpdf_type_warning() {
let scalar = ObjectHandle::integer(1);
let error = scalar
.replace_key(b"/A", ObjectHandle::null())
.expect_err("a contextless qpdf type warning is an exception");
assert!(matches!(
error,
Error::QpdfExc(error)
if error.get_message_detail() == b"operation for dictionary attempted on object of type integer: ignoring key replacement request"
));
assert_eq!(scalar.as_integer(), Some(1));
}
#[test]
fn replace_key_preserves_a_resolved_indirect_null_and_its_identity() {
let indirect_null = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), -1);
indirect_null.set_resolved(ObjectValue::Null);
let dict = ObjectHandle::dictionary(vec![]);
dict.replace_key(b"/Null", indirect_null.clone()).unwrap();
let retained = dict.try_get_key(b"/Null").unwrap();
assert!(!dict.try_has_key(b"/Null").unwrap());
assert!(retained.is_indirect());
assert!(retained.is_null());
assert!(retained.is_same_object_as(&indirect_null));
}
#[test]
fn replace_key_preserves_a_dangling_indirect_reference_and_its_identity() {
let dangling = ObjectHandle::new_indirect_unresolved(ObjectRef::new(10, 0), -1);
dangling.set_resolved(ObjectValue::Null);
let dict = ObjectHandle::dictionary(vec![]);
dict.replace_key(b"/Dangling", dangling.clone()).unwrap();
let retained = dict.try_get_key(b"/Dangling").unwrap();
assert!(!dict.try_has_key(b"/Dangling").unwrap());
assert!(retained.is_indirect());
assert!(retained.is_null());
assert!(retained.is_same_object_as(&dangling));
}
#[test]
fn replace_key_on_a_non_dictionary_handle_reports_qpdf_type_warning() {
let scalar = ObjectHandle::integer(1);
let error = scalar
.replace_key(b"/A", ObjectHandle::integer(2))
.expect_err("a contextless qpdf type warning is an exception");
assert!(matches!(
error,
Error::QpdfExc(error)
if error.get_message_detail() == b"operation for dictionary attempted on object of type integer: ignoring key replacement request"
));
assert_eq!(scalar.as_integer(), Some(1));
}
#[test]
fn replace_array_item_preserves_identity_and_rejects_invalid_slots() {
let array = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
let replacement = ObjectHandle::dictionary(vec![]);
let retained = replacement.clone();
assert!(array.replace_array_item(0, replacement));
retained
.replace_key(b"/K", ObjectHandle::integer(9))
.unwrap();
let inserted = array.as_array().expect("array")[0].clone();
assert_eq!(inserted.try_get_key(b"/K").unwrap().as_integer(), Some(9));
assert!(!array.replace_array_item(1, ObjectHandle::integer(2)));
assert!(!ObjectHandle::integer(1).replace_array_item(0, ObjectHandle::integer(2)));
assert!(!array.replace_array_item(0, array.clone()));
}
#[test]
fn canonical_array_mutators_preserve_live_aliases_and_qpdf_return_handles() {
let first = ObjectHandle::integer(1);
let second = ObjectHandle::integer(2);
let array = ObjectHandle::array(vec![first.clone(), second.clone()]);
let replacement = ObjectHandle::dictionary(vec![]);
array
.set_array_item(1, replacement.clone())
.expect("setArrayItem accepts an in-bounds item");
assert!(array
.try_array_item(1)
.unwrap()
.unwrap()
.is_same_object_as(&replacement));
let inserted_at_front = ObjectHandle::name(b"front".to_vec());
array
.insert_array_item(0, inserted_at_front.clone())
.expect("insertItem accepts zero");
assert!(array
.try_array_item(0)
.unwrap()
.unwrap()
.is_same_object_as(&inserted_at_front));
assert!(array
.try_array_item(1)
.unwrap()
.unwrap()
.is_same_object_as(&first));
let inserted_middle = ObjectHandle::name(b"middle".to_vec());
let returned = array
.insert_array_item_and_get_new(2, inserted_middle.clone())
.expect("insertItemAndGetNew accepts an in-range position");
assert!(returned.is_same_object_as(&inserted_middle));
assert!(array
.try_array_item(2)
.unwrap()
.unwrap()
.is_same_object_as(&inserted_middle));
let appended = ObjectHandle::name(b"append".to_vec());
array
.append_array_item(appended.clone())
.expect("appendItem accepts an item");
assert!(array
.try_array_item(4)
.unwrap()
.unwrap()
.is_same_object_as(&appended));
let appended_and_returned = ObjectHandle::name(b"append-and-get".to_vec());
let returned = array
.append_array_item_and_get_new(appended_and_returned.clone())
.expect("appendItemAndGetNew accepts an item");
assert!(returned.is_same_object_as(&appended_and_returned));
assert!(array
.try_array_item(5)
.unwrap()
.unwrap()
.is_same_object_as(&appended_and_returned));
let erased = array
.erase_array_item_and_get_old(1)
.expect("eraseItemAndGetOld returns the live old handle");
assert!(erased.is_same_object_as(&first));
assert_eq!(array.try_array_len().unwrap(), Some(5));
array
.erase_array_item(2)
.expect("eraseItem accepts an in-bounds position");
assert!(array
.try_array_item(2)
.unwrap()
.unwrap()
.is_same_object_as(&appended));
}
#[test]
fn public_array_mutators_report_direct_self_aliases() {
let array = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
let set_error = array
.set_array_item(0, array.clone())
.expect_err("direct self replacement is rejected");
assert!(matches!(
set_error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let bulk_set_error = array
.set_array_items(vec![array.clone()])
.expect_err("direct self replacement list is rejected");
assert!(matches!(
bulk_set_error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let insert_error = array
.insert_array_item(0, array.clone())
.expect_err("direct self insertion is rejected");
assert!(matches!(
insert_error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let append_error = array
.append_array_item(array.clone())
.expect_err("direct self append is rejected");
assert!(matches!(
append_error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let set_error = array
.set_array_item(usize::MAX, array.clone())
.expect_err("bounds warning must run before the self-alias guard");
assert!(matches!(
set_error,
Error::QpdfExc(warning)
if warning.get_message_detail() == b"ignoring attempt to set out of bounds array item"
));
let insert_error = array
.insert_array_item(usize::MAX, array.clone())
.expect_err("bounds warning must run before the self-alias guard");
assert!(matches!(
insert_error,
Error::QpdfExc(warning)
if warning.get_message_detail() == b"ignoring attempt to insert out of bounds array item"
));
assert_eq!(array.try_array_len().unwrap(), Some(1));
assert_eq!(
array.try_array_item(0).unwrap().unwrap().as_integer(),
Some(1)
);
}
#[test]
fn public_array_mutators_report_multi_hop_direct_cycles() {
let first = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
let second = ObjectHandle::array(vec![ObjectHandle::integer(2)]);
first
.set_array_item(0, second.clone())
.expect("first direct array accepts second");
let set_error = second
.set_array_item(0, first.clone())
.expect_err("reciprocal set is rejected");
assert!(matches!(
set_error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
assert_eq!(
second.try_array_item(0).unwrap().unwrap().as_integer(),
Some(2)
);
let first = ObjectHandle::array(vec![]);
let second = ObjectHandle::array(vec![ObjectHandle::integer(3)]);
first
.insert_array_item(0, second.clone())
.expect("first direct array accepts second");
let insert_error = second
.insert_array_item(0, first.clone())
.expect_err("reciprocal insert is rejected");
assert!(matches!(
insert_error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
assert_eq!(second.try_array_len().unwrap(), Some(1));
assert_eq!(
second.try_array_item(0).unwrap().unwrap().as_integer(),
Some(3)
);
let first = ObjectHandle::array(vec![]);
let second = ObjectHandle::array(vec![ObjectHandle::integer(4)]);
first
.append_array_item(second.clone())
.expect("first direct array accepts second");
let append_error = second
.append_array_item(first.clone())
.expect_err("reciprocal append is rejected");
assert!(matches!(
append_error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
assert_eq!(second.try_array_len().unwrap(), Some(1));
assert_eq!(
second.try_array_item(0).unwrap().unwrap().as_integer(),
Some(4)
);
let repeated = ObjectHandle::integer(5);
let candidate = ObjectHandle::array(vec![repeated.clone(), repeated]);
let target = ObjectHandle::array(vec![]);
target
.append_array_item(candidate)
.expect("repeated direct children do not form a cycle");
}
#[test]
fn public_array_mutators_report_rejected_direct_cycles() {
let array = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
let error = array
.set_array_item(0, array.clone())
.expect_err("self set must report the rejected mutation");
assert!(matches!(
error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let array = ObjectHandle::array(vec![ObjectHandle::integer(2)]);
let error = array
.set_array_items(vec![array.clone()])
.expect_err("self bulk-set must report the rejected mutation");
assert!(matches!(
error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let array = ObjectHandle::array(vec![ObjectHandle::integer(3)]);
let error = array
.insert_array_item(0, array.clone())
.expect_err("self insert must report the rejected mutation");
assert!(matches!(
error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let array = ObjectHandle::array(vec![ObjectHandle::integer(4)]);
let error = array
.insert_array_item_and_get_new(0, array.clone())
.expect_err("self insert-and-get must report the rejected mutation");
assert!(matches!(
error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let array = ObjectHandle::array(vec![ObjectHandle::integer(5)]);
let error = array
.append_array_item(array.clone())
.expect_err("self append must report the rejected mutation");
assert!(matches!(
error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
let array = ObjectHandle::array(vec![ObjectHandle::integer(6)]);
let error = array
.append_array_item_and_get_new(array.clone())
.expect_err("self append-and-get must report the rejected mutation");
assert!(matches!(
error,
Error::Internal(message) if message == "attempted to create a direct object cycle"
));
}
#[test]
fn insert_array_item_at_size_uses_qpdfs_append_position() {
let array = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
let appended_at_size = ObjectHandle::integer(2);
array
.insert_array_item(1, appended_at_size.clone())
.expect("insertItem permits the inclusive end position");
assert!(array
.try_array_item(1)
.unwrap()
.unwrap()
.is_same_object_as(&appended_at_size));
}
#[test]
fn set_array_items_replaces_in_qpdf_order_and_preserves_child_identity() {
let old = ObjectHandle::integer(1);
let first = ObjectHandle::dictionary(vec![]);
let second = ObjectHandle::dictionary(vec![]);
let array = ObjectHandle::array(vec![old.clone()]);
array
.set_array_items(vec![first.clone(), second.clone()])
.expect("setArrayFromVector accepts unowned items");
assert!(old.containing_object_refs().is_empty());
assert!(array
.try_array_item(0)
.unwrap()
.unwrap()
.is_same_object_as(&first));
assert!(array
.try_array_item(1)
.unwrap()
.unwrap()
.is_same_object_as(&second));
assert_eq!(array.try_array_len().unwrap(), Some(2));
}
#[test]
fn array_mutators_reject_foreign_ownership_and_keep_qpdf_partial_replacement_order() {
let (_, resolver) = super::identity_tests::resolver_bearing_handle(ObjectValue::Null);
let old = ObjectHandle::integer(1);
let array = ObjectHandle::array(vec![old.clone()]);
array.promote_to_indirect(ObjectRef::new(40, 0), 41, Rc::downgrade(&resolver));
let foreign = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(41, 0),
NO_PARSED_OFFSET,
42,
Rc::downgrade(&resolver),
);
let error = array
.append_array_item(foreign.clone())
.expect_err("appendItem rejects an object owned by another PDF");
assert!(matches!(error, Error::Internal(_)));
assert_eq!(array.try_array_len().unwrap(), Some(1));
assert!(array
.try_array_item(0)
.unwrap()
.unwrap()
.is_same_object_as(&old));
let accepted = ObjectHandle::dictionary(vec![]);
let error = array
.set_array_items(vec![accepted.clone(), foreign])
.expect_err("setFromVector checks ownership in insertion order");
assert!(matches!(error, Error::Internal(_)));
assert!(old.containing_object_refs().is_empty());
assert_eq!(array.try_array_len().unwrap(), Some(1));
assert!(array
.try_array_item(0)
.unwrap()
.unwrap()
.is_same_object_as(&accepted));
let same_pdf = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(42, 0),
NO_PARSED_OFFSET,
41,
Rc::downgrade(&resolver),
);
array
.append_array_item(same_pdf.clone())
.expect("same-document indirect items remain attachable");
assert!(array
.try_array_item(1)
.unwrap()
.unwrap()
.is_same_object_as(&same_pdf));
}
#[test]
fn replace_key_rejects_foreign_ownership_without_mutating_the_dictionary() {
let (_, resolver) = super::identity_tests::resolver_bearing_handle(ObjectValue::Null);
let destination =
ObjectHandle::dictionary(vec![(b"/Existing".to_vec(), ObjectHandle::integer(1))]);
destination.promote_to_indirect(ObjectRef::new(40, 0), 4242, Rc::downgrade(&resolver));
let foreign = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(41, 0),
NO_PARSED_OFFSET,
4243,
Rc::downgrade(&resolver),
);
let error = destination
.replace_key(b"/Foreign", foreign)
.expect_err("replaceKey must reject a value owned by another QPDF");
assert!(matches!(
error,
Error::Internal(message) if message == FOREIGN_OBJECT_OWNERSHIP_ERROR
));
assert!(!destination.try_has_key(b"/Foreign").unwrap());
assert_eq!(
destination.try_get_key(b"/Existing").unwrap().as_integer(),
Some(1)
);
}
#[test]
fn replace_key_accepts_a_foreign_descendant_nested_in_a_direct_container() {
// `QPDFObjectHandle::checkOwnership` (`libqpdf/QPDFObjectHandle.cc:
// 2355-2365`) compares only `this->getOwningQPDF()` and
// `item.getOwningQPDF()` -- both O(1) reads of the *top-level*
// handle's own owning-document pointer -- and never walks `item`'s
// descendants. `QPDF_Array::checkOwnership` (`QPDF_Array.cc:10-26`)
// is the same shape. A programmatically constructed direct value's
// own `getOwningQPDF()` is `nullptr` regardless of what it contains
// (file-parser-created direct values are the exception: qpdf stamps
// them through `QPDFParser::setDescription`, `QPDFParser.cc:439-443`),
// so real qpdf's `replaceKey` accepts a direct
// container that nests a foreign indirect object several levels
// down -- silently embedding an out-of-context object reference,
// per qpdf's own `copyForeignObject` guidance for the caller to
// avoid this. This is a known qpdf footgun, not a guard qpdf
// implements; flpdf's `replace_key` must match qpdf's actual
// (shallow) `checkOwnership`, not invent a deeper one.
let (_, resolver) = super::identity_tests::resolver_bearing_handle(ObjectValue::Null);
let destination = ObjectHandle::dictionary(vec![]);
destination.promote_to_indirect(ObjectRef::new(42, 0), 4242, Rc::downgrade(&resolver));
let foreign = ObjectHandle::new_indirect_for_pdf_with_resolver(
ObjectRef::new(43, 0),
NO_PARSED_OFFSET,
4243,
Rc::downgrade(&resolver),
);
let direct_container = ObjectHandle::dictionary(vec![(b"/Foreign".to_vec(), foreign)]);
destination
.replace_key(b"/Container", direct_container)
.expect("checkOwnership does not inspect a direct value's descendants");
assert!(destination.try_has_key(b"/Container").unwrap());
assert!(destination
.try_get_key(b"/Container")
.unwrap()
.try_get_key(b"/Foreign")
.unwrap()
.is_indirect());
}
#[test]
fn replace_key_removes_the_key_for_a_direct_null_previously_contained_by_another_document() {
// A direct null handle that was earlier a descendant of a PDF-A
// indirect object remains a programmatic, unowned value: qpdf's
// `getOwningQPDF()` is set on the value itself, not by containment
// (`QPDFValue.hh:60-66,149-152`; `QPDF_Array.cc:10-26`). It must still
// be accepted by `replace_key` on a PDF-B dictionary, after which
// qpdf's null-removes-key branch (`QPDF_Dictionary.cc:135-146`) runs
// unconditionally.
let (_, resolver) = super::identity_tests::resolver_bearing_handle(ObjectValue::Null);
let stale_null = ObjectHandle::null();
let pdf_a_container = ObjectHandle::dictionary(vec![(b"/X".to_vec(), stale_null.clone())]);
pdf_a_container.promote_to_indirect(ObjectRef::new(60, 0), 4242, Rc::downgrade(&resolver));
let destination =
ObjectHandle::dictionary(vec![(b"/K".to_vec(), ObjectHandle::integer(1))]);
destination.promote_to_indirect(ObjectRef::new(61, 0), 4243, Rc::downgrade(&resolver));
destination.replace_key(b"/K", stale_null).expect(
"a programmatic direct null is unowned in qpdf, regardless of prior containment",
);
assert!(!destination.try_has_key(b"/K").unwrap());
}
#[test]
fn replace_key_accepts_a_direct_scalar_previously_contained_by_another_document() {
// Companion to the null regression above: the fix must not be a
// null-specific exemption. qpdf's `checkOwnership` never associates
// ownership with a direct value through containment, for any type,
// so a direct (non-null) scalar previously contained by another
// document must be accepted and inserted, not rejected.
let (_, resolver) = super::identity_tests::resolver_bearing_handle(ObjectValue::Null);
let stale_integer = ObjectHandle::integer(7);
let pdf_a_container =
ObjectHandle::dictionary(vec![(b"/Y".to_vec(), stale_integer.clone())]);
pdf_a_container.promote_to_indirect(ObjectRef::new(62, 0), 4242, Rc::downgrade(&resolver));
let destination = ObjectHandle::dictionary(vec![]);
destination.promote_to_indirect(ObjectRef::new(63, 0), 4243, Rc::downgrade(&resolver));
destination.replace_key(b"/Int", stale_integer).expect(
"a programmatic direct scalar is unowned in qpdf, regardless of prior containment",
);
assert_eq!(
destination.try_get_key(b"/Int").unwrap().as_integer(),
Some(7)
);
}
#[test]
fn set_array_item_accepts_a_direct_null_previously_contained_by_another_document() {
let (_, resolver) = super::identity_tests::resolver_bearing_handle(ObjectValue::Null);
let stale_null = ObjectHandle::null();
let pdf_a_container = ObjectHandle::dictionary(vec![(b"/X".to_vec(), stale_null.clone())]);
pdf_a_container.promote_to_indirect(ObjectRef::new(64, 0), 4242, Rc::downgrade(&resolver));
let destination = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
destination.promote_to_indirect(ObjectRef::new(65, 0), 4243, Rc::downgrade(&resolver));
destination.set_array_item(0, stale_null).expect(
"a programmatic direct null is unowned in qpdf, regardless of prior containment",
);
assert!(destination.try_array_item(0).unwrap().unwrap().is_null());
}
#[test]
fn append_array_item_accepts_a_direct_scalar_previously_contained_by_another_document() {
let (_, resolver) = super::identity_tests::resolver_bearing_handle(ObjectValue::Null);
let stale_integer = ObjectHandle::integer(7);
let pdf_a_container =
ObjectHandle::dictionary(vec![(b"/Y".to_vec(), stale_integer.clone())]);
pdf_a_container.promote_to_indirect(ObjectRef::new(66, 0), 4242, Rc::downgrade(&resolver));
let destination = ObjectHandle::array(vec![]);
destination.promote_to_indirect(ObjectRef::new(67, 0), 4243, Rc::downgrade(&resolver));
destination.append_array_item(stale_integer).expect(
"a programmatic direct scalar is unowned in qpdf, regardless of prior containment",
);
assert_eq!(
destination.try_array_item(0).unwrap().unwrap().as_integer(),
Some(7)
);
}
#[test]
fn canonical_array_mutators_resolve_a_lazy_holder_and_update_every_alias() {
let child = ObjectHandle::integer(1);
let (array, _resolver) =
super::identity_tests::resolver_bearing_handle(ObjectValue::Array(vec![child.clone()]));
let alias = array.clone();
let replacement = ObjectHandle::integer(2);
array
.set_array_item(0, replacement.clone())
.expect("qpdf array mutators dereference their holder");
assert!(array.is_resolved());
assert!(alias
.try_array_item(0)
.unwrap()
.unwrap()
.is_same_object_as(&replacement));
assert!(child.containing_object_refs().is_empty());
}
#[test]
fn array_mutators_reject_destroyed_items_as_uninitialized() {
let (_, resolver) = super::identity_tests::resolver_bearing_handle(ObjectValue::Null);
let array = ObjectHandle::array(vec![]);
array.promote_to_indirect(ObjectRef::new(50, 0), 51, Rc::downgrade(&resolver));
let destroyed = ObjectHandle::integer(1);
destroyed.promote_to_indirect(ObjectRef::new(52, 0), 51, Rc::downgrade(&resolver));
destroyed.disconnect_and_destroy();
let error = array
.append_array_item(destroyed)
.expect_err("QPDF_Destroyed is not an initialized array item");
assert!(matches!(
error,
Error::Internal(message)
if message == "Attempting to add an uninitialized object to a QPDF_Array."
));
assert_eq!(array.try_array_len().unwrap(), Some(0));
}
#[test]
fn array_mutators_reject_uninitialized_items() {
let array = ObjectHandle::array(vec![ObjectHandle::integer(0)]);
let uninitialized = ObjectHandle::uninitialized();
let append_error = array
.append_array_item(uninitialized.clone())
.expect_err("an uninitialized handle must not be appended");
assert!(matches!(
append_error,
Error::Internal(message)
if message == "Attempting to add an uninitialized object to a QPDF_Array."
));
let insert_error = array
.insert_array_item(0, uninitialized.clone())
.expect_err("an uninitialized handle must not be inserted");
assert!(matches!(
insert_error,
Error::Internal(message)
if message == "Attempting to add an uninitialized object to a QPDF_Array."
));
let set_error = array
.set_array_item(0, uninitialized)
.expect_err("an uninitialized handle must not be set into an array slot");
assert!(matches!(
set_error,
Error::Internal(message)
if message == "Attempting to add an uninitialized object to a QPDF_Array."
));
assert_eq!(array.try_array_len().unwrap(), Some(1));
assert_eq!(
array.try_array_item(0).unwrap().unwrap().as_integer(),
Some(0)
);
}
#[test]
fn replace_key_rejects_inserting_a_direct_dictionary_into_itself() {
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::integer(1))]);
let self_clone = dict.clone();
dict.replace_key(b"/Self", self_clone).unwrap();
assert!(dict.try_get_key(b"/Self").unwrap().is_null());
// The rest of the dictionary is untouched by the rejected insert.
assert_eq!(dict.try_get_key(b"/A").unwrap().as_integer(), Some(1));
}
#[test]
fn replace_key_rejects_a_direct_alias_of_a_shared_payload() {
let target = ObjectHandle::new_indirect_unresolved(ObjectRef::new(39, 0), -1);
let replacement = ObjectHandle::dictionary(vec![]);
target.assign_value_state(&replacement);
target.replace_key(b"/Self", replacement.clone()).unwrap();
assert!(!target.try_has_key(b"Self").unwrap());
}
#[test]
fn replace_array_item_rejects_a_direct_alias_of_a_shared_payload() {
let target = ObjectHandle::new_indirect_unresolved(ObjectRef::new(40, 0), -1);
let replacement = ObjectHandle::array(vec![ObjectHandle::integer(2)]);
target.assign_value_state(&replacement);
assert!(!target.replace_array_item(0, replacement.clone()));
assert_eq!(target.as_array().unwrap()[0].as_integer(), Some(2));
}
#[test]
fn replace_array_items_rejects_a_direct_alias_of_a_shared_payload() {
let target = ObjectHandle::new_indirect_unresolved(ObjectRef::new(41, 0), -1);
let replacement = ObjectHandle::array(vec![ObjectHandle::integer(3)]);
target.assign_value_state(&replacement);
assert!(!target.replace_array_items(vec![replacement.clone()]));
assert_eq!(target.as_array().unwrap()[0].as_integer(), Some(3));
}
#[test]
fn replace_array_items_rejects_a_non_array_handle() {
assert!(!ObjectHandle::integer(1).replace_array_items(vec![ObjectHandle::integer(2)]));
}
#[test]
fn replace_key_allows_an_indirect_handle_to_reference_itself() {
// Unlike a direct self-insertion, an indirect handle referencing
// itself is not a direct cycle -- every recursive walker already
// stops at the indirect boundary, so this must remain a normal
// insert rather than being rejected as a no-op.
let indirect = ObjectHandle::new_indirect_unresolved(ObjectRef::new(7, 0), -1);
indirect.set_resolved(ObjectValue::Dictionary(Default::default()));
indirect.replace_key(b"/Self", indirect.clone()).unwrap();
assert!(indirect.try_get_key(b"/Self").unwrap().is_indirect());
}
#[test]
fn remove_key_deletes_a_present_key() {
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::integer(1))]);
dict.remove_key(b"/A");
assert!(dict.try_get_key(b"/A").unwrap().is_null());
}
#[test]
fn remove_key_on_a_missing_key_is_a_no_op() {
let dict = ObjectHandle::dictionary(vec![]);
dict.remove_key(b"/Missing");
assert!(dict.try_get_key(b"/Missing").unwrap().is_null());
}
#[test]
fn remove_key_on_a_non_dictionary_handle_is_a_no_op() {
let scalar = ObjectHandle::integer(1);
scalar.remove_key(b"/A");
assert_eq!(scalar.as_integer(), Some(1));
}
#[test]
fn dictionary_detach_removes_only_the_removed_live_path() {
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, -1);
let child = ObjectHandle::dictionary(vec![]);
owner.set_resolved(ObjectValue::Dictionary(
[
(b"A".to_vec(), child.clone()),
(b"B".to_vec(), child.clone()),
]
.into_iter()
.collect(),
));
owner.remove_key(b"/A");
assert_eq!(child.containing_object_refs(), vec![owner_ref]);
owner.remove_key(b"/B");
assert!(child.containing_object_refs().is_empty());
}
#[test]
fn set_resolved_moves_dictionary_storage_without_cloning_it() {
let owner = ObjectHandle::new_indirect_unresolved(ObjectRef::new(7, 0), -1);
let mut key = vec![b'K'; 4_096];
key[0] = b'/';
let original_key_allocation = key.as_ptr();
let value =
ObjectValue::Dictionary([(key, ObjectHandle::integer(1))].into_iter().collect());
owner.set_resolved(value);
assert!(owner.is_indirect());
let slot = owner.0.borrow();
let shared = slot.shared.clone();
drop(slot);
let shared = shared.borrow();
let ObjectValue::Dictionary(entries) = &shared.value else {
panic!("test owner must resolve to the supplied dictionary"); // cov:ignore: successful set_resolved fixes this state
};
let resolved_key_allocation = entries
.keys()
.next()
.expect("resolved dictionary retains its key")
.as_ptr();
assert_eq!(resolved_key_allocation, original_key_allocation);
}
#[test]
fn forward_graph_query_ignores_expired_direct_parents() {
let child = ObjectHandle::integer(1);
for _ in 0..64 {
let transient_parent = ObjectHandle::array(vec![child.clone()]);
drop(transient_parent);
}
let live_parent = ObjectHandle::array(vec![child.clone()]);
assert!(child.containing_object_refs().is_empty());
drop(live_parent);
assert!(child.containing_object_refs().is_empty());
}
#[test]
fn deep_containment_traversals_do_not_overflow_the_stack() {
let output = std::process::Command::new(std::env::current_exe().unwrap())
.args([
"--exact",
"object_handle::mutation_tests::deep_containment_traversals_probe",
"--ignored",
"--nocapture",
])
.env("FLPDF_DEEP_CONTAINMENT_PROBE", "1")
.output()
.unwrap();
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(
output.status.success(),
"deep-containment probe failed: status={} stderr={}",
output.status,
stderr
);
}
#[test]
#[ignore = "subprocess-only stack-overflow regression probe"]
fn deep_containment_traversals_probe() {
assert_eq!(
std::env::var_os("FLPDF_DEEP_CONTAINMENT_PROBE").as_deref(),
Some(std::ffi::OsStr::new("1"))
);
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved_with_identity(
owner_ref,
NO_PARSED_OFFSET,
Some(41),
None,
);
let leaf = ObjectHandle::integer(1);
let mut nested = leaf.clone();
for _ in 0..100_000 {
nested = ObjectHandle::array(vec![nested]);
}
owner.set_resolved(ObjectValue::Array(vec![nested.clone()]));
assert_eq!(leaf.containing_object_refs_for_pdf(41), vec![owner_ref]);
// These user-constructed values are intentionally deeper than Rust's
// recursive Rc drop can safely release. Keep this probe scoped to the
// two containment traversals under test.
std::mem::forget(owner);
std::mem::forget(nested);
}
#[test]
fn replacing_a_nested_dictionary_path_detaches_the_old_subtree() {
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, -1);
let leaf = ObjectHandle::integer(1);
let nested = ObjectHandle::dictionary(vec![(b"Leaf".to_vec(), leaf.clone())]);
owner.set_resolved(ObjectValue::Dictionary(
[(b"Nested".to_vec(), nested.clone())].into_iter().collect(),
));
owner
.replace_key(b"/Nested", ObjectHandle::dictionary(vec![]))
.unwrap();
assert!(nested.containing_object_refs().is_empty());
assert!(leaf.containing_object_refs().is_empty());
}
#[test]
fn shared_subtree_loses_only_the_detached_indirect_root() {
let first_ref = ObjectRef::new(7, 0);
let second_ref = ObjectRef::new(9, 0);
let first = ObjectHandle::new_indirect_unresolved(first_ref, -1);
let second = ObjectHandle::new_indirect_unresolved(second_ref, -1);
let shared = ObjectHandle::dictionary(vec![]);
first.set_resolved(ObjectValue::Dictionary(
[(b"Shared".to_vec(), shared.clone())].into_iter().collect(),
));
second.set_resolved(ObjectValue::Dictionary(
[(b"Shared".to_vec(), shared.clone())].into_iter().collect(),
));
first.remove_key(b"/Shared");
assert_eq!(shared.containing_object_refs(), vec![second_ref]);
}
#[test]
fn array_and_direct_value_replacement_detach_old_children() {
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, -1);
let first = ObjectHandle::integer(1);
let second = ObjectHandle::integer(2);
let array = ObjectHandle::array(vec![first.clone(), first.clone()]);
owner.set_resolved(ObjectValue::Dictionary(
[(b"Array".to_vec(), array.clone())].into_iter().collect(),
));
assert!(array.replace_array_item(0, second.clone()));
assert_eq!(first.containing_object_refs(), vec![owner_ref]);
assert_eq!(second.containing_object_refs(), vec![owner_ref]);
assert!(array.replace_array_items(vec![]));
assert!(first.containing_object_refs().is_empty());
assert!(second.containing_object_refs().is_empty());
let replacement = ObjectHandle::integer(3);
array.replace_direct_value(ObjectValue::Array(vec![replacement.clone()]));
assert_eq!(replacement.containing_object_refs(), vec![owner_ref]);
array.replace_direct_value(ObjectValue::Array(vec![]));
assert!(replacement.containing_object_refs().is_empty());
}
#[test]
fn stream_dictionary_membership_tracks_replacement_and_root_disconnect() {
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, NO_PARSED_OFFSET);
let old_dictionary = ObjectHandle::dictionary(vec![]);
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: old_dictionary.clone(),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
owner.set_resolved(ObjectValue::Dictionary(
[(b"Stream".to_vec(), stream.clone())].into_iter().collect(),
));
assert_eq!(old_dictionary.containing_object_refs(), vec![owner_ref]);
let new_dictionary = ObjectHandle::dictionary(vec![]);
stream.replace_direct_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: new_dictionary.clone(),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
assert!(old_dictionary.containing_object_refs().is_empty());
assert_eq!(new_dictionary.containing_object_refs(), vec![owner_ref]);
owner.disconnect();
assert!(new_dictionary.containing_object_refs().is_empty());
}
#[test]
fn indirect_state_replacement_detaches_old_direct_children() {
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, -1);
let replaced = ObjectHandle::dictionary(vec![]);
owner.set_resolved(ObjectValue::Dictionary(
[(b"Child".to_vec(), replaced.clone())]
.into_iter()
.collect(),
));
let missing = ObjectHandle::dictionary(vec![]);
owner.set_resolved(ObjectValue::Dictionary(
[(b"Child".to_vec(), missing.clone())].into_iter().collect(),
));
assert!(replaced.containing_object_refs().is_empty());
assert_eq!(missing.containing_object_refs(), vec![owner_ref]);
owner.set_resolved(ObjectValue::Null);
assert!(missing.containing_object_refs().is_empty());
let disconnected = ObjectHandle::dictionary(vec![]);
owner.set_resolved(ObjectValue::Dictionary(
[(b"Child".to_vec(), disconnected.clone())]
.into_iter()
.collect(),
));
owner.disconnect();
assert!(disconnected.containing_object_refs().is_empty());
}
#[test]
fn current_root_lookup_terminates_on_a_direct_cycle() {
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, -1);
let first = ObjectHandle::dictionary(vec![]);
let second = ObjectHandle::dictionary(vec![]);
first.replace_key(b"/Second", second.clone()).unwrap();
second.replace_key(b"/First", first.clone()).unwrap();
owner.set_resolved(ObjectValue::Dictionary(
[(b"First".to_vec(), first.clone())].into_iter().collect(),
));
assert_eq!(second.containing_object_refs(), vec![owner_ref]);
}
#[test]
fn shallow_copy_is_always_direct_even_from_an_indirect_source() {
let indirect = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), -1);
indirect.set_resolved(ObjectValue::Dictionary(Default::default()));
let copy = indirect.shallow_copy().expect("dictionary copy");
assert!(copy.is_direct());
}
#[test]
fn shallow_copy_resolves_an_indirect_receiver_before_copying() {
let (indirect, _resolver) =
super::identity_tests::resolver_bearing_handle(ObjectValue::Dictionary(
[(b"/Value".to_vec(), ObjectHandle::integer(7))]
.into_iter()
.collect(),
));
assert!(!indirect.is_resolved());
let copy = indirect
.shallow_copy()
.expect("qpdf shallowCopy resolves its receiver before copying");
assert!(indirect.is_resolved());
assert!(copy.is_direct());
assert_eq!(copy.try_get_key(b"/Value").unwrap().as_integer(), Some(7));
}
#[test]
fn shallow_copy_of_an_uninitialized_handle_reports_qpdf_error() {
let error = ObjectHandle::uninitialized()
.shallow_copy()
.expect_err("qpdf shallowCopy rejects an uninitialized handle");
assert!(matches!(
error,
Error::Internal(message)
if message == "operation attempted on uninitialized QPDFObjectHandle"
));
}
#[test]
fn shallow_copy_mutation_does_not_affect_the_source() {
let original = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::integer(1))]);
let copy = original.shallow_copy().expect("dictionary copy");
copy.replace_key(b"/A", ObjectHandle::integer(2)).unwrap();
assert_eq!(original.try_get_key(b"/A").unwrap().as_integer(), Some(1));
assert_eq!(copy.try_get_key(b"/A").unwrap().as_integer(), Some(2));
}
// Despite the name, qpdf's shallowCopy() recursively copies through
// every *direct* array/dictionary descendant, stopping only at an
// *indirect* child (kept shared) -- see shallow_copy's own doc comment
// for the qpdf citations. These two tests pin that distinction.
#[test]
fn shallow_copy_of_a_direct_dictionary_child_produces_an_independent_copy() {
let original = ObjectHandle::dictionary(vec![(
b"A".to_vec(),
ObjectHandle::dictionary(vec![(b"Inner".to_vec(), ObjectHandle::integer(1))]),
)]);
let copy = original.shallow_copy().expect("dictionary copy");
copy.try_get_key(b"/A")
.unwrap()
.replace_key(b"/Inner", ObjectHandle::integer(2))
.unwrap();
assert_eq!(
original
.try_get_key(b"/A")
.unwrap()
.try_get_key(b"/Inner")
.unwrap()
.as_integer(),
Some(1)
);
assert_eq!(
copy.try_get_key(b"/A")
.unwrap()
.try_get_key(b"/Inner")
.unwrap()
.as_integer(),
Some(2)
);
}
#[test]
fn shallow_copy_of_an_indirect_dictionary_child_keeps_shared_identity() {
let child = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), -1);
child.set_resolved(ObjectValue::Integer(1));
let original = ObjectHandle::dictionary(vec![(b"A".to_vec(), child.clone())]);
let copy = original.shallow_copy().expect("dictionary copy");
assert!(copy.try_get_key(b"/A").unwrap().ptr_eq(&child));
}
#[test]
fn shallow_copy_of_a_non_container_clones_the_scalar_value() {
let original = ObjectHandle::integer(5);
let copy = original.shallow_copy().expect("scalar copy");
assert!(!copy.ptr_eq(&original));
assert_eq!(copy.as_integer(), Some(5));
}
#[test]
fn has_key_omits_a_present_null_value_like_qpdf() {
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::null())]);
assert!(!dict.try_has_key(b"/A").unwrap());
assert!(!dict.try_has_key(b"/Missing").unwrap());
}
#[test]
fn get_key_missing_key_carries_parent_context_like_qpdf() {
let dict = ObjectHandle::dictionary(vec![]);
let missing = dict.try_get_key(b"/Missing").unwrap();
let error = missing
.try_get_keys()
.expect_err("missing-key null should retain its dictionary context");
assert!(matches!(
error,
crate::Error::QpdfExc(ref error)
if error.get_object() == b" -> dictionary key /Missing"
&& error.get_message_detail()
== b"operation for dictionary attempted on object of type null: treating as empty"
));
}
#[test]
fn try_has_key_on_a_non_dictionary_handle_reports_qpdf_type_warning() {
let scalar = ObjectHandle::integer(1);
assert!(matches!(
scalar.try_has_key(b"/A"),
Err(crate::Error::QpdfExc(error))
if error.get_message_detail() == b"operation for dictionary attempted on object of type integer: returning false for a key containment request"
));
}
#[test]
fn merge_resources_is_a_no_op_unless_both_sides_are_dictionaries() {
let scalar = ObjectHandle::integer(1);
let dict = ObjectHandle::dictionary(vec![(b"A".to_vec(), ObjectHandle::integer(1))]);
scalar.merge_resources(&dict, None).expect("merge");
dict.merge_resources(&scalar, None).expect("merge");
assert_eq!(dict.try_get_key(b"/A").unwrap().as_integer(), Some(1));
assert!(dict.try_get_key(b"/B").unwrap().is_null());
}
#[test]
fn merge_resources_resolves_outer_operands_and_category_dictionaries_like_qpdf() {
// qpdf's mergeResources calls isDictionary() on the receiver, other,
// and each top-level category, and each call dereferences first
// (`QPDFObjectHandle.cc:431-434,1063-1087`). The merge-dict fixture
// relies on this for Dict2/k3 -> 8 0 R.
let destination_font =
ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(1))]);
let (destination, destination_resolver) = identity_tests::resolver_bearing_handle(
ObjectValue::Dictionary([(b"Font".to_vec(), destination_font)].into_iter().collect()),
);
let (other_font, other_font_resolver) =
identity_tests::resolver_bearing_handle(ObjectValue::Dictionary(
[(b"F2".to_vec(), ObjectHandle::integer(2))]
.into_iter()
.collect(),
));
let (other, other_resolver) =
identity_tests::resolver_bearing_handle(ObjectValue::Dictionary(
[(b"Font".to_vec(), other_font.clone())]
.into_iter()
.collect(),
));
destination
.merge_resources(&other, None)
.expect("unresolved qpdf resource operands must merge");
assert_eq!(
destination
.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/F2")
.unwrap()
.as_integer(),
Some(2)
);
assert!(destination.is_resolved());
assert!(other.is_resolved());
assert!(other_font.is_resolved());
drop(destination_resolver);
drop(other_font_resolver);
drop(other_resolver);
}
#[test]
fn merge_resources_resolves_an_indirect_top_level_category_array() {
let destination = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![ObjectHandle::name(b"PDF".to_vec())]),
)]);
let (other_procset, resolver) = identity_tests::resolver_bearing_handle(
ObjectValue::Array(vec![ObjectHandle::name(b"Text".to_vec())]),
);
let other = ObjectHandle::dictionary(vec![(b"ProcSet".to_vec(), other_procset)]);
destination
.merge_resources(&other, None)
.expect("an unresolved array category must merge");
let values: Vec<_> = destination
.try_get_key(b"/ProcSet")
.unwrap()
.as_array()
.expect("merged ProcSet array")
.into_iter()
.filter_map(|value| value.as_name())
.collect();
assert_eq!(values, vec![b"PDF".to_vec(), b"Text".to_vec()]);
assert!(other.try_get_key(b"/ProcSet").unwrap().is_resolved());
drop(resolver);
}
#[test]
fn merge_resources_propagates_outer_and_category_resolution_errors() {
let (unresolved_destination, destination_resolver) =
identity_tests::error_resolving_handle(ObjectRef::new(90, 0));
let other = ObjectHandle::dictionary(vec![]);
let error = unresolved_destination
.merge_resources(&other, None)
.expect_err("receiver resolution failure must propagate");
assert!(matches!(error, Error::System(message) if message == "resolver failed"));
drop(destination_resolver);
let destination = ObjectHandle::dictionary(vec![]);
let (unresolved_other, other_resolver) =
identity_tests::error_resolving_handle(ObjectRef::new(91, 0));
let error = destination
.merge_resources(&unresolved_other, None)
.expect_err("other resolution failure must propagate");
assert!(matches!(error, Error::System(message) if message == "resolver failed"));
drop(other_resolver);
let destination =
ObjectHandle::dictionary(vec![(b"Font".to_vec(), ObjectHandle::dictionary(vec![]))]);
let (unresolved_category, category_resolver) =
identity_tests::error_resolving_handle(ObjectRef::new(92, 0));
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), unresolved_category)]);
let error = destination
.merge_resources(&other, None)
.expect_err("category resolution failure must propagate");
assert!(matches!(error, Error::System(message) if message == "resolver failed"));
drop(category_resolver);
}
#[test]
fn merge_resources_resolves_an_unresolved_missing_category_before_shallow_copy() {
// qpdf's `shallowCopy` always dereferences before copying
// (`QPDFObjectHandle.cc:2073-2079`), so the missing-category branch
// (`replaceKey(rtype, other_val.shallowCopy())`,
// `QPDFObjectHandle.cc:1150-1152`) never installs an unresolved
// placeholder. The canonical flpdf primitive now owns that
// resolution boundary too.
let destination = ObjectHandle::dictionary(vec![]);
let (other_font, other_font_resolver) =
identity_tests::resolver_bearing_handle(ObjectValue::Dictionary(
[(b"F1".to_vec(), ObjectHandle::integer(1))]
.into_iter()
.collect(),
));
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
destination
.merge_resources(&other, None)
.expect("an unresolved missing category must still merge");
assert_eq!(
destination
.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/F1")
.unwrap()
.as_integer(),
Some(1),
"shallow-copying an unresolved category must not install a direct null"
);
drop(other_font_resolver);
}
#[test]
fn merge_resources_short_circuits_other_when_the_receiver_is_not_a_dictionary() {
// qpdf's outer guard is `isDictionary() && other.isDictionary()`
// (`QPDFObjectHandle.cc:1066`): a short-circuiting `&&` that never
// evaluates `other.isDictionary()` -- and so never dereferences
// `other` -- once `self` fails the check.
let destination = ObjectHandle::integer(1);
let (other, other_resolver) = identity_tests::error_resolving_handle(ObjectRef::new(93, 0));
destination
.merge_resources(&other, None)
.expect("a non-dictionary receiver must no-op without touching other");
drop(other_resolver);
}
#[test]
fn make_resources_indirect_promotes_direct_second_level_values_only() {
let mut pdf = crate::Pdf::empty().expect("empty PDF");
let direct_font = ObjectHandle::integer(1);
let direct_font_alias = direct_font.clone();
let direct_nested =
ObjectHandle::dictionary(vec![(b"/Child".to_vec(), ObjectHandle::integer(2))]);
let direct_nested_alias = direct_nested.clone();
let already_indirect = pdf
.make_indirect_from_object_handle(ObjectHandle::integer(3))
.expect("allocate an already-indirect resource");
let direct_category = ObjectHandle::dictionary(vec![
(b"/F1".to_vec(), direct_font),
(b"/F2".to_vec(), already_indirect.clone()),
(b"/Nested".to_vec(), direct_nested),
]);
let resources = ObjectHandle::dictionary(vec![
(b"/Font".to_vec(), direct_category),
(
b"/ProcSet".to_vec(),
ObjectHandle::array(vec![ObjectHandle::name(b"PDF".to_vec())]),
),
]);
resources
.make_resources_indirect(&mut pdf)
.expect("promote direct resource values");
let font = resources.try_get_key(b"/Font").unwrap();
let promoted_font = font.try_get_key(b"/F1").unwrap();
assert!(promoted_font.is_indirect());
assert!(direct_font_alias.is_indirect());
assert!(promoted_font.is_same_object_as(&direct_font_alias));
assert_eq!(promoted_font.as_integer(), Some(1));
assert!(font
.try_get_key(b"/F2")
.unwrap()
.is_same_object_as(&already_indirect));
let promoted_nested = font.try_get_key(b"/Nested").unwrap();
assert!(promoted_nested.is_indirect());
assert!(direct_nested_alias.is_indirect());
assert!(promoted_nested.is_same_object_as(&direct_nested_alias));
assert!(promoted_nested.try_get_key(b"/Child").unwrap().is_direct());
assert!(
font.is_direct(),
"the category dictionary itself stays direct"
);
assert!(resources.try_get_key(b"/ProcSet").unwrap().is_direct());
}
#[test]
fn make_resources_indirect_is_a_noop_for_non_dictionary_receivers() {
let mut pdf = crate::Pdf::empty().expect("empty PDF");
let value = ObjectHandle::integer(1);
value
.make_resources_indirect(&mut pdf)
.expect("non-dictionary receivers are ignored");
assert!(value.is_direct());
assert_eq!(value.as_integer(), Some(1));
}
// qpdf privatizes an incoming resource value with `shallowCopy`
// (`libqpdf/QPDFObjectHandle.cc:1090`, `:1113`, `:1122`), so a *direct*
// stream anywhere it reaches propagates `QPDF_Stream::copy`'s throw out
// of `mergeResources` rather than being merged. Both privatizing sites
// are covered: a whole rtype `self` lacks, and an inner key inside a
// shared rtype.
#[test]
fn merge_resources_propagates_the_stream_rejection_from_either_privatizing_site() {
let stream = || {
ObjectHandle::stream(
ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(3))]),
Rc::new(b"abc".to_vec()),
)
};
let new_rtype_dest = ObjectHandle::dictionary(vec![]);
let new_rtype_other = ObjectHandle::dictionary(vec![(
b"XObject".to_vec(),
ObjectHandle::dictionary(vec![(b"Im1".to_vec(), stream())]),
)]);
let inner_key_dest = ObjectHandle::dictionary(vec![(
b"XObject".to_vec(),
ObjectHandle::dictionary(vec![]),
)]);
let inner_key_other = ObjectHandle::dictionary(vec![(
b"XObject".to_vec(),
ObjectHandle::dictionary(vec![(b"Im1".to_vec(), stream())]),
)]);
for (dest, other) in [
(new_rtype_dest, new_rtype_other),
(inner_key_dest, inner_key_other),
] {
let error = dest
.merge_resources(&other, None)
.expect_err("a direct stream resource cannot be privatized");
assert!(
matches!(error, Error::System(ref message)
if message == "stream objects cannot be cloned"),
"{error:?}"
);
}
}
#[test]
fn merge_resources_installs_a_private_copy_of_a_top_level_key_self_lacks() {
let source_sub = ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(1))]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), source_sub.clone())]);
let dest = ObjectHandle::dictionary(vec![]);
dest.merge_resources(&other, None).expect("merge");
let installed = dest.try_get_key(b"/Font").unwrap();
assert_eq!(installed.try_get_key(b"/F1").unwrap().as_integer(), Some(1));
assert!(!installed.ptr_eq(&source_sub)); // privatized, not shared
}
#[test]
fn merge_resources_adds_a_new_inner_key_without_a_conflicts_map() {
let this_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(1))]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font = ObjectHandle::dictionary(vec![(b"F2".to_vec(), ObjectHandle::integer(2))]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
dest.merge_resources(&other, None).expect("merge");
let font = dest.try_get_key(b"/Font").unwrap();
assert_eq!(font.try_get_key(b"/F1").unwrap().as_integer(), Some(1));
assert_eq!(font.try_get_key(b"/F2").unwrap().as_integer(), Some(2));
}
#[test]
fn merge_resources_leaves_a_colliding_inner_key_untouched_without_a_conflicts_map() {
let this_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(1))]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font =
ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(99))]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
dest.merge_resources(&other, None).expect("merge");
assert_eq!(
dest.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/F1")
.unwrap()
.as_integer(),
Some(1)
);
}
#[test]
fn merge_resources_reuses_an_existing_key_for_the_same_indirect_object() {
let shared = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), -1);
shared.set_resolved(ObjectValue::Name(b"Shared".to_vec()));
let this_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), shared.clone())]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
// dest already has F1 -> shared. other also wants F1, but pointing at
// the same shared object identity -- reuse F1 verbatim, no conflict
// entry (existing_key == key), no new key minted.
let other_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), shared.clone())]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
let mut conflicts = std::collections::BTreeMap::new();
dest.merge_resources(&other, Some(&mut conflicts))
.expect("merge");
assert!(conflicts.is_empty());
assert!(dest
.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/F1")
.unwrap()
.ptr_eq(&shared));
}
#[test]
fn merge_resources_reuses_a_raw_generation_identity() {
let shared = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 65_535), -1);
shared.set_resolved(ObjectValue::Name(b"Shared".to_vec()));
let this_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), shared.clone())]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), shared)]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
let mut conflicts = std::collections::BTreeMap::new();
dest.merge_resources(&other, Some(&mut conflicts))
.expect("merge");
assert!(conflicts.is_empty());
assert!(!dest
.try_get_key(b"/Font")
.unwrap()
.try_has_key(b"/F1_1")
.unwrap());
}
#[test]
fn merge_resources_reuse_records_a_conflict_when_the_reused_name_differs() {
let shared = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), -1);
shared.set_resolved(ObjectValue::Name(b"Shared".to_vec()));
// dest already has this same shared object, but under a DIFFERENT
// key (F2) than what other asks for (F1) -- reuse F2, and DO record
// the rename since the reused name differs from the requested one.
let this_font = ObjectHandle::dictionary(vec![
(b"F2".to_vec(), shared.clone()),
(b"F1".to_vec(), ObjectHandle::integer(1)),
]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), shared.clone())]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
let mut conflicts = std::collections::BTreeMap::new();
dest.merge_resources(&other, Some(&mut conflicts))
.expect("merge");
assert_eq!(
conflicts
.get(b"/Font".as_slice())
.unwrap()
.get(b"/F1".as_slice()),
Some(&b"/F2".to_vec())
);
// F1 keeps its own original (unrelated) value; nothing overwrote it.
assert_eq!(
dest.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/F1")
.unwrap()
.as_integer(),
Some(1)
);
}
#[test]
fn merge_resources_mints_a_fresh_name_for_a_genuine_conflict() {
let this_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(1))]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(2))]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
let mut conflicts = std::collections::BTreeMap::new();
dest.merge_resources(&other, Some(&mut conflicts))
.expect("merge");
let new_name = conflicts
.get(b"/Font".as_slice())
.and_then(|m| m.get(b"/F1".as_slice()))
.expect("F1 conflict recorded");
assert_eq!(new_name, b"/F1_1");
assert_eq!(
dest.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/F1")
.unwrap()
.as_integer(),
Some(1)
);
assert_eq!(
dest.try_get_key(b"/Font")
.unwrap()
.try_get_key(new_name)
.unwrap()
.as_integer(),
Some(2)
);
}
#[test]
fn merge_resources_privatizes_an_indirect_existing_sub_dictionary() {
let indirect_font = ObjectHandle::new_indirect_unresolved(ObjectRef::new(3, 0), -1);
indirect_font.set_resolved(ObjectValue::Dictionary(
[(b"F1".to_vec(), ObjectHandle::integer(1))]
.into_iter()
.collect(),
));
let shared_dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), indirect_font.clone())]);
let another_holder =
ObjectHandle::dictionary(vec![(b"Font".to_vec(), indirect_font.clone())]);
let other_font = ObjectHandle::dictionary(vec![(b"F2".to_vec(), ObjectHandle::integer(2))]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
shared_dest.merge_resources(&other, None).expect("merge");
// shared_dest's own /Font is now a private direct copy...
assert!(shared_dest.try_get_key(b"/Font").unwrap().is_direct());
assert_eq!(
shared_dest
.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/F2")
.unwrap()
.as_integer(),
Some(2)
);
// ...and the other holder's /Font (and the original indirect object)
// is untouched.
assert!(another_holder
.try_get_key(b"/Font")
.unwrap()
.ptr_eq(&indirect_font));
assert!(indirect_font.try_get_key(b"/F2").unwrap().is_null());
}
#[test]
fn merge_resources_unions_scalar_array_items_by_unparsed_text() {
let dest = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![ObjectHandle::name(b"PDF".to_vec())]),
)]);
let other = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![
ObjectHandle::name(b"PDF".to_vec()),
ObjectHandle::name(b"Text".to_vec()),
]),
)]);
dest.merge_resources(&other, None).expect("merge");
let items = dest.try_get_key(b"/ProcSet").unwrap().as_array().unwrap();
let names: Vec<_> = items.iter().map(|i| i.as_name().unwrap()).collect();
assert_eq!(names, vec![b"PDF".to_vec(), b"Text".to_vec()]);
}
#[test]
fn merge_resources_resolves_indirect_scalar_array_items_before_union() {
// qpdf's `isScalar()` dereferences every array item before the
// unparsed-text union (`QPDFObjectHandle.cc:1130-1146,449-452`).
let (destination_item, destination_resolver) =
crate::object_handle::identity_tests::resolver_bearing_handle(ObjectValue::Name(
b"PDF".to_vec(),
));
let dest = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![destination_item.clone()]),
)]);
let other = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![ObjectHandle::name(b"Text".to_vec())]),
)]);
dest.merge_resources(&other, None)
.expect("indirect scalar array items merge");
let items = dest
.try_get_key(b"/ProcSet")
.unwrap()
.as_array()
.expect("merged ProcSet remains an array");
assert_eq!(items.len(), 2);
assert!(items[0].ptr_eq(&destination_item));
assert_eq!(items[0].as_name(), Some(b"PDF".to_vec()));
assert_eq!(items[1].as_name(), Some(b"Text".to_vec()));
drop(destination_resolver);
}
#[test]
fn merge_resources_propagates_indirect_array_item_resolution_errors() {
// A qpdf accessor failure escapes mergeResources; it is not converted
// into a non-scalar skip (`QPDFObjectHandle.cc:1130-1146`).
let unresolved = ObjectHandle::new_indirect_unresolved(ObjectRef::new(91, 0), -1);
let dest =
ObjectHandle::dictionary(vec![(b"ProcSet".to_vec(), ObjectHandle::array(vec![]))]);
let other = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![unresolved]),
)]);
let error = dest
.merge_resources(&other, None)
.expect_err("array item resolution failure must propagate");
assert!(matches!(
error,
Error::Internal(message) if message == "object 91 0 belongs to a dropped PDF"
));
}
#[test]
fn merge_resources_array_union_records_the_destination_owner() {
let owner_ref = ObjectRef::new(7, 0);
let owner =
ObjectHandle::new_indirect_unresolved_with_identity(owner_ref, -1, Some(41), None);
let dest = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![ObjectHandle::name(b"PDF".to_vec())]),
)]);
owner.set_resolved(ObjectValue::Dictionary(
[(b"Resources".to_vec(), dest.clone())]
.into_iter()
.collect(),
));
let retained = ObjectHandle::name(b"Text".to_vec());
let other = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![retained.clone()]),
)]);
dest.merge_resources(&other, None).expect("merge");
let merged = dest
.try_get_key(b"/ProcSet")
.unwrap()
.as_array()
.expect("merged ProcSet remains an array");
assert!(merged[1].is_same_object_as(&retained));
assert_eq!(retained.containing_object_refs_for_pdf(41), vec![owner_ref]);
}
#[test]
fn merge_resources_leaves_mismatched_or_non_container_rtype_shapes_untouched() {
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), ObjectHandle::integer(1))]);
let other = ObjectHandle::dictionary(vec![(
b"Font".to_vec(),
ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(2))]),
)]);
dest.merge_resources(&other, None).expect("merge");
assert_eq!(dest.try_get_key(b"/Font").unwrap().as_integer(), Some(1));
}
#[test]
fn replace_stream_data_updates_data_and_length() {
let dict = ObjectHandle::dictionary(vec![]);
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict.clone(),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 37,
})));
stream.replace_stream_data(Rc::new(b"new data".to_vec()), None, None);
assert_eq!(stream.as_stream_data(), Some(Rc::new(b"new data".to_vec())));
assert_eq!(dict.try_get_key(b"/Length").unwrap().as_integer(), Some(8));
assert_eq!(
stream.with_value(|value| match value {
Some(ObjectValue::Stream(stream)) => Some(stream.stream_length),
_ => None, // cov:ignore: this test constructs a stream above
}),
Some(37),
"replaceStreamData changes the dictionary /Length, not the stored original length"
);
}
#[test]
fn replace_stream_data_empty_buffer_removes_an_existing_length() {
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(37))]);
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict.clone(),
stream_data: Some(Rc::new(b"old".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 37,
})));
stream.replace_stream_data(Rc::new(Vec::new()), None, None);
assert!(!dict.try_has_key(b"/Length").unwrap());
}
#[test]
fn replace_stream_data_empty_buffer_keeps_a_missing_length_absent() {
let dict = ObjectHandle::dictionary(vec![]);
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict.clone(),
stream_data: Some(Rc::new(b"old".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 3,
})));
stream.replace_stream_data(Rc::new(Vec::new()), None, None);
assert!(!dict.try_has_key(b"/Length").unwrap());
}
#[test]
fn replace_stream_data_repeated_empty_and_nonempty_calls_follow_the_length_boundary() {
let dict = ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(3))]);
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict.clone(),
stream_data: Some(Rc::new(b"old".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 3,
})));
stream.replace_stream_data(Rc::new(Vec::new()), None, None);
assert!(!dict.try_has_key(b"/Length").unwrap());
stream.replace_stream_data(Rc::new(b"new data".to_vec()), None, None);
assert_eq!(dict.try_get_key(b"/Length").unwrap().as_integer(), Some(8));
stream.replace_stream_data(Rc::new(Vec::new()), None, None);
assert!(!dict.try_has_key(b"/Length").unwrap());
}
#[test]
fn replace_stream_data_sets_filter_and_decode_parms_when_given() {
let dict = ObjectHandle::dictionary(vec![]);
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict.clone(),
stream_data: Some(Rc::new(b"old".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let filter = ObjectHandle::name(b"FlateDecode".to_vec());
let parms =
ObjectHandle::dictionary(vec![(b"Predictor".to_vec(), ObjectHandle::integer(12))]);
stream.replace_stream_data(
Rc::new(b"x".to_vec()),
Some(filter.clone()),
Some(parms.clone()),
);
assert!(dict.try_get_key(b"/Filter").unwrap().ptr_eq(&filter));
assert!(dict.try_get_key(b"/DecodeParms").unwrap().ptr_eq(&parms));
}
#[test]
fn replace_stream_data_leaves_filter_untouched_when_not_given() {
let dict = ObjectHandle::dictionary(vec![(
b"Filter".to_vec(),
ObjectHandle::name(b"FlateDecode".to_vec()),
)]);
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: dict.clone(),
stream_data: Some(Rc::new(b"old".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
stream.replace_stream_data(Rc::new(b"new".to_vec()), None, None);
assert_eq!(
dict.try_get_key(b"/Filter").unwrap().as_name(),
Some(b"FlateDecode".to_vec())
);
}
#[test]
fn replace_stream_data_on_a_non_stream_handle_is_a_no_op() {
let scalar = ObjectHandle::integer(1);
scalar.replace_stream_data(Rc::new(b"x".to_vec()), None, None);
assert_eq!(scalar.as_integer(), Some(1));
}
#[test]
fn raw_stream_data_rejects_an_original_stream_with_parsed_offset_zero() {
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 3,
})));
stream.set_parsed_offset_if_unset(0);
let error = stream
.get_raw_stream_data()
.expect_err("qpdf rejects an original stream with no parsed offset");
assert!(matches!(error, Error::Internal(message)
if message == "pipeStreamData called for stream with no data"));
}
#[test]
fn stream_data_accessors_use_qpdf_stream_type_assertion_for_direct_and_indirect_values() {
let direct_decode_error = ObjectHandle::integer(7)
.get_stream_data(crate::writer::DecodeLevel::All)
.expect_err("get_stream_data must reject a direct non-stream");
assert!(matches!(
direct_decode_error,
Error::System(message)
if message == "operation for stream attempted on object of type integer"
));
let direct_raw_error = ObjectHandle::integer(7)
.get_raw_stream_data()
.expect_err("get_raw_stream_data must reject a direct non-stream");
assert!(matches!(
direct_raw_error,
Error::System(message)
if message == "operation for stream attempted on object of type integer"
));
let (indirect_decode, _decode_resolver) =
crate::object_handle::identity_tests::resolver_bearing_handle(ObjectValue::Integer(7));
let indirect_decode_error = indirect_decode
.get_stream_data(crate::writer::DecodeLevel::All)
.expect_err("get_stream_data must resolve before rejecting a non-stream");
assert!(matches!(
indirect_decode_error,
Error::System(message)
if message == "operation for stream attempted on object of type integer"
));
let (indirect_raw, _raw_resolver) =
crate::object_handle::identity_tests::resolver_bearing_handle(ObjectValue::Integer(7));
let indirect_raw_error = indirect_raw
.get_raw_stream_data()
.expect_err("get_raw_stream_data must resolve before rejecting a non-stream");
assert!(matches!(
indirect_raw_error,
Error::System(message)
if message == "operation for stream attempted on object of type integer"
));
}
#[test]
fn raw_stream_data_rejects_non_stream_values() {
let error = ObjectHandle::integer(1)
.get_raw_stream_data()
.expect_err("raw stream data is only available on streams");
assert!(matches!(error, Error::System(message)
if message == "operation for stream attempted on object of type integer"));
}
#[test]
fn raw_stream_data_rejects_an_original_direct_stream() {
let stream = ObjectHandle::from_value(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 3,
})));
let error = stream
.get_raw_stream_data()
.expect_err("qpdf streams with original bytes are always indirect");
assert!(matches!(error, Error::Internal(message)
if message == "pipeStreamData called for original direct stream"));
}
#[test]
fn raw_stream_data_rejects_a_dropped_original_stream_owner() {
let (stream, resolver) = super::identity_tests::resolver_bearing_handle(
ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 3,
})),
);
stream.set_parsed_offset_if_unset(9);
stream
.try_dereference()
.expect("resolve stream while owner lives");
drop(resolver);
let error = stream
.get_raw_stream_data()
.expect_err("original stream source is unavailable after document drop");
assert!(matches!(error, Error::Internal(message)
if message == "object 20 0 belongs to a dropped PDF"));
}
// --- Coverage closers: paths the tests above never happened to reach ---
#[test]
fn replace_key_and_remove_key_mutate_a_resolved_indirect_handle() {
let indirect = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), -1);
indirect.set_resolved(ObjectValue::Dictionary(Default::default()));
indirect
.replace_key(b"/A", ObjectHandle::integer(1))
.unwrap();
assert_eq!(indirect.try_get_key(b"/A").unwrap().as_integer(), Some(1));
indirect.remove_key(b"/A");
assert!(indirect.try_get_key(b"/A").unwrap().is_null());
}
#[test]
fn resolving_an_indirect_dictionary_records_its_direct_child_owner() {
// This fails if resolution leaves a direct child detached from the
// canonical indirect object that contains it. Pdf's incremental
// writer then has no local owner to schedule after the child mutates.
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, -1);
let child = ObjectHandle::dictionary(vec![]);
owner.set_resolved(ObjectValue::Dictionary(std::collections::BTreeMap::from([
(b"Child".to_vec(), child.clone()),
])));
assert_eq!(child.containing_object_refs(), vec![owner_ref]);
}
#[test]
fn an_indirect_handle_has_no_direct_containment_owner() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(7, 0), -1);
assert!(handle.containing_object_refs_for_pdf(1).is_empty());
}
#[test]
fn replacing_a_contained_direct_value_retains_its_live_owner_for_new_children() {
// A preserved direct stream dictionary is replaced in place by
// canonical replacement. New direct descendants must retain the same
// incremental-write containment owner rather than requiring a later
// graph scan.
let owner_ref = ObjectRef::new(7, 0);
let owner = ObjectHandle::new_indirect_unresolved(owner_ref, -1);
let direct = ObjectHandle::dictionary(vec![]);
owner.set_resolved(ObjectValue::Dictionary(std::collections::BTreeMap::from([
(b"Direct".to_vec(), direct.clone()),
])));
let child = ObjectHandle::integer(42);
direct.replace_direct_value(ObjectValue::Dictionary(std::collections::BTreeMap::from([
(b"Child".to_vec(), child.clone()),
])));
assert_eq!(child.containing_object_refs(), vec![owner_ref]);
}
#[test]
fn containment_owner_walk_stops_at_an_indirect_child() {
// Direct containment ends at an indirect identity. Traversing through
// this boundary would incorrectly make object 9's payload a direct
// child of object 7.
let owner = ObjectHandle::new_indirect_unresolved(ObjectRef::new(7, 0), -1);
let direct = ObjectHandle::dictionary(vec![]);
owner.set_resolved(ObjectValue::Dictionary(std::collections::BTreeMap::from([
(b"Direct".to_vec(), direct.clone()),
])));
let indirect = ObjectHandle::new_indirect_unresolved(ObjectRef::new(9, 0), -1);
direct.replace_key(b"/Indirect", indirect.clone()).unwrap();
assert!(direct
.try_get_key(b"/Indirect")
.unwrap()
.is_same_object_as(&indirect));
assert!(indirect.containing_object_refs().is_empty());
}
#[test]
fn replace_key_on_an_unresolved_indirect_handle_propagates_resolution_error() {
let indirect = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), -1);
let error = indirect
.replace_key(b"/A", ObjectHandle::integer(1))
.expect_err("qpdf resolves the receiver before replacing a key");
assert!(matches!(
error,
Error::Internal(message) if message == "object 1 0 belongs to a dropped PDF"
));
indirect.remove_key(b"/A"); // legacy no-resolution helper remains safe
assert!(indirect.try_get_key(b"/A").is_err());
}
#[test]
fn shallow_copy_of_a_contextless_unresolved_handle_reports_qpdf_error() {
let indirect = ObjectHandle::from_value(ObjectValue::Unresolved);
let error = indirect
.shallow_copy()
.expect_err("QPDF_Unresolved::copy is a logic error");
assert!(matches!(
error,
Error::Internal(message)
if message == "attempted to shallow copy an unresolved QPDFObjectHandle"
));
}
#[test]
fn shallow_copy_of_an_array_recurses_through_direct_elements() {
let inner = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
let original = ObjectHandle::array(vec![inner]);
let copy = original.shallow_copy().expect("array copy");
let copy_inner = copy.as_array().unwrap()[0].clone();
assert!(!copy_inner.ptr_eq(&original.as_array().unwrap()[0]));
assert_eq!(
copy.as_array().unwrap()[0].as_array().unwrap()[0].as_integer(),
Some(1)
);
}
#[test]
fn unsafe_shallow_copy_keeps_immediate_handles_and_qpdf_copy_errors() {
let array_child = ObjectHandle::dictionary(vec![]);
let array = ObjectHandle::array(vec![array_child.clone()]);
let array_copy = array
.unsafe_shallow_copy()
.expect("unsafe array copy keeps child handles");
assert!(array_copy.as_array().unwrap()[0].is_same_object_as(&array_child));
let dictionary_child = ObjectHandle::integer(7);
let dictionary =
ObjectHandle::dictionary(vec![(b"Child".to_vec(), dictionary_child.clone())]);
let dictionary_copy = dictionary
.unsafe_shallow_copy()
.expect("unsafe dictionary copy keeps child handles");
assert!(dictionary_copy
.try_get_key(b"/Child")
.unwrap()
.is_same_object_as(&dictionary_child));
let scalar_copy = ObjectHandle::integer(7)
.unsafe_shallow_copy()
.expect("unsafe scalar copy");
assert_eq!(scalar_copy.as_integer(), Some(7));
let uninitialized = ObjectHandle::uninitialized();
assert!(matches!(
uninitialized.unsafe_shallow_copy(),
Err(Error::Internal(message))
if message == "operation attempted on uninitialized QPDFObjectHandle"
));
let reserved = ObjectHandle::new_reserved_direct();
let reserved_copy = reserved
.unsafe_shallow_copy()
.expect("reserved values create a fresh reserved value");
assert!(reserved_copy.is_reserved());
assert!(!reserved_copy.is_same_object_as(&reserved));
let unresolved = ObjectHandle::from_value(ObjectValue::Unresolved);
assert!(matches!(
unresolved.unsafe_shallow_copy(),
Err(Error::Internal(message))
if message == "attempted to shallow copy an unresolved QPDFObjectHandle"
));
let destroyed = ObjectHandle::from_value(ObjectValue::Destroyed);
assert!(matches!(
destroyed.unsafe_shallow_copy(),
Err(Error::Internal(message))
if message == "attempted to shallow copy QPDFObjectHandle from destroyed QPDF"
));
let stream = ObjectHandle::stream(ObjectHandle::dictionary(vec![]), Rc::new(Vec::new()));
assert!(matches!(
stream.unsafe_shallow_copy(),
Err(Error::System(message)) if message == "stream objects cannot be cloned"
));
}
#[test]
fn shallow_copy_refuses_a_resolved_indirect_stream() {
// `shallowCopy` dereferences first (`libqpdf/QPDFObjectHandle.cc:2074-2078`)
// and only then calls `obj->copy()`, so an indirect handle whose
// resolved value is a stream reaches `QPDF_Stream::copy`'s throw just
// as a direct one does — the resolution state changes nothing.
let indirect = ObjectHandle::new_indirect_unresolved(ObjectRef::new(1, 0), -1);
indirect.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: Some(Rc::new(b"old".to_vec())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let error = indirect
.shallow_copy()
.expect_err("streams cannot be cloned");
assert!(
matches!(error, Error::System(ref message)
if message == "stream objects cannot be cloned"),
"{error:?}"
);
assert_eq!(indirect.as_stream_data(), Some(Rc::new(b"old".to_vec())));
}
#[test]
fn merge_resources_installs_an_already_indirect_new_key_without_shallow_copying() {
let shared = ObjectHandle::new_indirect_unresolved(ObjectRef::new(5, 0), -1);
shared.set_resolved(ObjectValue::Integer(1));
let this_font = ObjectHandle::dictionary(vec![]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), shared.clone())]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
dest.merge_resources(&other, None).expect("merge");
assert!(dest
.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/F1")
.unwrap()
.ptr_eq(&shared));
}
#[test]
fn merge_resources_array_union_skips_a_non_scalar_item() {
let dest =
ObjectHandle::dictionary(vec![(b"ProcSet".to_vec(), ObjectHandle::array(vec![]))]);
let other = ObjectHandle::dictionary(vec![(
b"ProcSet".to_vec(),
ObjectHandle::array(vec![ObjectHandle::dictionary(vec![])]),
)]);
dest.merge_resources(&other, None).expect("merge");
assert!(dest
.try_get_key(b"/ProcSet")
.unwrap()
.as_array()
.unwrap()
.is_empty());
}
#[test]
fn is_scalar_covers_every_disjunct() {
assert!(is_scalar(&ObjectHandle::boolean(true)).unwrap());
assert!(is_scalar(&ObjectHandle::integer(1)).unwrap());
assert!(is_scalar(&ObjectHandle::name(b"N".to_vec())).unwrap());
assert!(is_scalar(&ObjectHandle::null()).unwrap());
assert!(is_scalar(&ObjectHandle::real(1.0)).unwrap());
assert!(is_scalar(&ObjectHandle::string(b"S".to_vec())).unwrap());
assert!(!is_scalar(&ObjectHandle::array(vec![])).unwrap());
}
#[test]
fn merge_resources_mints_a_second_unique_name_when_the_first_candidate_is_taken() {
// this_val (the Font sub-dict itself) has a nested dictionary-valued
// entry ("Widths") whose own key happens to be "F1_1" --
// try_get_resource_names is called ON this_val (see merge_resources's
// own doc comment on why it is this level, not dest's), so its
// "grandchildren" pool picks this up, forcing unique_resource_name
// past its first candidate.
let this_font = ObjectHandle::dictionary(vec![
(b"F1".to_vec(), ObjectHandle::integer(1)),
(
b"Widths".to_vec(),
ObjectHandle::dictionary(vec![(b"F1_1".to_vec(), ObjectHandle::integer(0))]),
),
]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(2))]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
let mut conflicts = std::collections::BTreeMap::new();
dest.merge_resources(&other, Some(&mut conflicts))
.expect("merge");
let new_name = conflicts
.get(b"/Font".as_slice())
.and_then(|m| m.get(b"/F1".as_slice()))
.expect("F1 conflict recorded");
assert_eq!(new_name, b"/F1_2");
assert_eq!(
dest.try_get_key(b"/Font")
.unwrap()
.try_get_key(new_name)
.unwrap()
.as_integer(),
Some(2)
);
}
#[test]
fn merge_resources_resolves_nested_dictionary_values_for_unique_names() {
// qpdf's getResourceNames() calls isDictionary() on every value,
// which dereferences an indirect nested dictionary before collecting
// its keys (`QPDFObjectHandle.cc:1156-1170,431-434`).
let (indirect_widths, resolver) =
crate::object_handle::identity_tests::resolver_bearing_handle(ObjectValue::Dictionary(
[(b"F1_1".to_vec(), ObjectHandle::integer(0))]
.into_iter()
.collect(),
));
let this_font = ObjectHandle::dictionary(vec![
(b"F1".to_vec(), ObjectHandle::integer(1)),
(b"Widths".to_vec(), indirect_widths.clone()),
]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(2))]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
let mut conflicts = std::collections::BTreeMap::new();
dest.merge_resources(&other, Some(&mut conflicts))
.expect("nested dictionary value resolves");
let new_name = conflicts
.get(b"/Font".as_slice())
.and_then(|m| m.get(b"/F1".as_slice()))
.expect("F1 conflict recorded");
assert_eq!(new_name, b"/F1_2");
assert!(dest
.try_get_key(b"/Font")
.unwrap()
.try_get_key(b"/Widths")
.unwrap()
.ptr_eq(&indirect_widths));
drop(resolver);
}
#[test]
fn merge_resources_propagates_nested_dictionary_resolution_errors() {
let unresolved = ObjectHandle::new_indirect_unresolved(ObjectRef::new(92, 0), -1);
let this_font = ObjectHandle::dictionary(vec![
(b"F1".to_vec(), ObjectHandle::integer(1)),
(b"Widths".to_vec(), unresolved),
]);
let dest = ObjectHandle::dictionary(vec![(b"Font".to_vec(), this_font)]);
let other_font = ObjectHandle::dictionary(vec![(b"F1".to_vec(), ObjectHandle::integer(2))]);
let other = ObjectHandle::dictionary(vec![(b"Font".to_vec(), other_font)]);
let mut conflicts = std::collections::BTreeMap::new();
let error = dest
.merge_resources(&other, Some(&mut conflicts))
.expect_err("nested dictionary resolution failure must propagate");
assert!(matches!(
error,
Error::Internal(message) if message == "object 92 0 belongs to a dropped PDF"
));
}
}
#[cfg(test)]
mod stream_provider_contract_tests {
use super::*;
use std::cell::{Cell, RefCell};
#[derive(Default)]
struct LegacyProvider {
calls: Cell<usize>,
identities: RefCell<Vec<(u32, u16)>>,
}
impl StreamDataProvider for LegacyProvider {
fn provide_stream_data_by_id(
&self,
object_number: u32,
generation: u16,
_pipeline: &mut dyn Pipeline,
) -> Result<()> {
self.calls.set(self.calls.get() + 1);
self.identities
.borrow_mut()
.push((object_number, generation));
Ok(())
}
}
#[derive(Default)]
struct RetryProvider {
calls: Cell<usize>,
flags: RefCell<Vec<(bool, bool)>>,
}
impl StreamDataProvider for RetryProvider {
fn supports_retry(&self) -> bool {
true
}
fn provide_stream_data_with_retry_by_id(
&self,
_object_number: u32,
_generation: u16,
_pipeline: &mut dyn Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
self.calls.set(self.calls.get() + 1);
self.flags
.borrow_mut()
.push((suppress_warnings, will_retry));
Ok(true)
}
}
struct RetryOnlyProvider;
impl StreamDataProvider for RetryOnlyProvider {
fn provide_stream_data_with_retry_by_id(
&self,
_object_number: u32,
_generation: u16,
_pipeline: &mut dyn Pipeline,
_suppress_warnings: bool,
_will_retry: bool,
) -> Result<bool> {
Ok(true)
}
}
struct LegacyOnlyProviderWithRetryFlag;
impl StreamDataProvider for LegacyOnlyProviderWithRetryFlag {
fn supports_retry(&self) -> bool {
true
}
fn provide_stream_data_by_id(
&self,
_object_number: u32,
_generation: u16,
_pipeline: &mut dyn Pipeline,
) -> Result<()> {
Ok(())
}
}
struct FailingCallbackPipeline {
failure: &'static str,
}
impl Pipeline for FailingCallbackPipeline {
fn identifier(&self) -> &str {
"failing callback pipeline"
}
fn write(&mut self, _data: &[u8]) -> crate::pipeline::PipelineResult<()> {
Err(PipelineError::runtime(self.failure))
}
fn finish(&mut self) -> crate::pipeline::PipelineResult<()> {
Err(PipelineError::runtime(self.failure))
}
}
struct EmptyProvider;
impl StreamDataProvider for EmptyProvider {}
struct PipeProvider {
bytes: Rc<Vec<u8>>,
calls: Cell<usize>,
identities: RefCell<Vec<(u32, u16)>>,
}
impl PipeProvider {
fn new(bytes: Rc<Vec<u8>>) -> Self {
Self {
bytes,
calls: Cell::new(0),
identities: RefCell::new(Vec::new()),
}
}
}
impl StreamDataProvider for PipeProvider {
fn provide_stream_data_by_id(
&self,
object_number: u32,
generation: u16,
pipeline: &mut dyn Pipeline,
) -> Result<()> {
self.calls.set(self.calls.get() + 1);
self.identities
.borrow_mut()
.push((object_number, generation));
pipeline.write(&self.bytes).map_err(Error::from)?;
pipeline.finish().map_err(Error::from)
}
}
struct RetryPipeProvider {
bytes: Rc<Vec<u8>>,
success: bool,
flags: RefCell<Vec<(bool, bool)>>,
}
impl StreamDataProvider for RetryPipeProvider {
fn supports_retry(&self) -> bool {
true
}
fn provide_stream_data_with_retry_by_id(
&self,
_object_number: u32,
_generation: u16,
pipeline: &mut dyn Pipeline,
suppress_warnings: bool,
will_retry: bool,
) -> Result<bool> {
self.flags
.borrow_mut()
.push((suppress_warnings, will_retry));
pipeline.write(&self.bytes).map_err(Error::from)?;
pipeline.finish().map_err(Error::from)?;
Ok(self.success)
}
}
fn provider_stream() -> ObjectHandle {
ObjectHandle::stream(
ObjectHandle::dictionary(vec![(b"Length".to_vec(), ObjectHandle::integer(3))]),
Rc::new(b"old".to_vec()),
)
}
#[test]
fn provider_registration_is_lazy_and_retains_the_provider_allocation() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let provider = Rc::new(LegacyProvider::default());
let ownership = Rc::downgrade(&provider);
stream
.replace_stream_data_provider(provider.clone(), None, None)
.expect("stream provider replacement");
assert_eq!(provider.calls.get(), 0, "registration must be lazy");
assert!(
stream.as_stream_data().is_none(),
"provider clears buffer source"
);
assert!(stream.with_value(|value| matches!(
value,
Some(ObjectValue::Stream(stream)) if stream.stream_provider.is_some()
)));
drop(provider);
assert!(
ownership.upgrade().is_some(),
"stream must retain provider ownership"
);
}
#[test]
fn provider_registration_accepts_a_qpdf_owned_indirect_stream() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let object_ref = stream.object_ref().expect("new stream object identity");
stream
.replace_stream_data_provider(Rc::new(LegacyProvider::default()), None, None)
.expect("provider replacement");
assert!(stream.is_indirect());
assert_eq!(stream.object_ref(), Some(object_ref));
assert!(stream.as_stream_data().is_none());
assert!(stream.with_value(|value| matches!(
value,
Some(ObjectValue::Stream(stream)) if stream.stream_provider.is_some()
)));
}
#[test]
fn provider_source_is_piped_lazily_and_updates_the_measured_length() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let object_ref = stream.object_ref().expect("new stream object identity");
let bytes = Rc::new(b"provider bytes".to_vec());
let provider = Rc::new(PipeProvider::new(Rc::clone(&bytes)));
stream
.replace_stream_data_provider(provider.clone(), None, None)
.expect("provider replacement");
assert_eq!(provider.calls.get(), 0, "provider remains lazy");
let first = stream.get_raw_stream_data().expect("first provider pipe");
let second = stream.get_raw_stream_data().expect("second provider pipe");
assert_eq!(first.as_slice(), bytes.as_slice());
assert_eq!(second.as_slice(), bytes.as_slice());
assert_eq!(provider.calls.get(), 2);
assert_eq!(
*provider.identities.borrow(),
vec![(object_ref.number, object_ref.generation); 2]
);
assert_eq!(
stream
.as_stream_dict()
.expect("stream dictionary")
.try_get_key(b"/Length")
.unwrap()
.as_integer(),
Some(bytes.len() as i64)
);
}
#[test]
fn provider_retry_result_forwards_flags_and_skips_length_update_on_failure() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let bytes = Rc::new(b"retry bytes".to_vec());
let provider = Rc::new(RetryPipeProvider {
bytes: Rc::clone(&bytes),
success: false,
flags: RefCell::new(Vec::new()),
});
stream
.replace_stream_data_provider(provider.clone(), None, None)
.expect("provider replacement");
let mut sink = crate::pipeline::buffer::Buffer::new("provider", None);
let mut filtering_attempted = false;
let success = stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::None,
true,
true,
)
.expect("retry provider result");
assert!(!success);
assert!(!filtering_attempted);
assert_eq!(sink.take_buffer().expect("provider output"), *bytes);
assert_eq!(*provider.flags.borrow(), vec![(true, true)]);
assert!(!stream
.as_stream_dict()
.expect("stream dictionary")
.try_has_key(b"/Length")
.unwrap());
}
#[test]
fn provider_length_mismatch_uses_qpdf_system_error_text() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let object_ref = stream.object_ref().expect("new stream object identity");
let bytes = Rc::new(b"provider bytes".to_vec());
stream
.replace_stream_data_provider(Rc::new(PipeProvider::new(Rc::clone(&bytes))), None, None)
.expect("provider replacement");
stream
.as_stream_dict()
.expect("stream dictionary")
.replace_key(b"/Length", ObjectHandle::integer(99))
.unwrap();
let error = stream
.get_raw_stream_data()
.expect_err("provider length mismatch must fail");
assert!(matches!(
error,
Error::System(message)
if message == format!(
"stream data provider for {} {} provided {} bytes instead of expected 99 bytes",
object_ref.number,
object_ref.generation,
bytes.len()
)
));
}
#[test]
fn provider_default_error_propagates_from_the_pipe_boundary() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
stream
.replace_stream_data_provider(Rc::new(EmptyProvider), None, None)
.expect("provider replacement");
let error = stream
.get_raw_stream_data()
.expect_err("provider default method must fail");
assert!(matches!(
error,
Error::Internal(message)
if message == "you must override provideStreamData -- see QPDFObjectHandle.hh"
));
}
#[test]
fn provider_pipe_rejects_a_direct_stream_without_object_identity() {
let stream = provider_stream();
let error = stream
.replace_stream_data_provider(
Rc::new(PipeProvider::new(Rc::new(b"direct bytes".to_vec()))),
None,
None,
)
.expect_err("provider registration requires an indirect stream identity");
assert!(matches!(
error,
Error::System(message)
if message == STREAM_DATA_PROVIDER_REQUIRES_INDIRECT_ERROR
));
}
#[test]
fn supports_retry_does_not_fallback_between_callback_families() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let mut retry_only_pipeline = crate::pipeline::buffer::Buffer::new("retry-only", None);
RetryOnlyProvider
.provide_stream_data_with_retry_by_id(47, 0, &mut retry_only_pipeline, false, false)
.expect("retry-only override");
let normal_family_stream = pdf.new_stream().expect("normal-family stream");
normal_family_stream
.replace_stream_data_provider(Rc::new(RetryOnlyProvider), None, None)
.expect("normal-family provider replacement");
let error = normal_family_stream
.get_raw_stream_data()
.expect_err("normal family must not call retry-only override");
assert!(matches!(
error,
Error::Internal(message)
if message == STREAM_DATA_PROVIDER_DEFAULT_ERROR
));
let mut legacy_only_pipeline = crate::pipeline::buffer::Buffer::new("legacy-only", None);
LegacyOnlyProviderWithRetryFlag
.provide_stream_data_by_id(47, 0, &mut legacy_only_pipeline)
.expect("legacy-only override");
let retry_family_stream = pdf.new_stream().expect("retry-family stream");
retry_family_stream
.replace_stream_data_provider(Rc::new(LegacyOnlyProviderWithRetryFlag), None, None)
.expect("retry-family provider replacement");
let error = retry_family_stream
.get_raw_stream_data()
.expect_err("retry family must not call normal-only override");
assert!(matches!(
error,
Error::Internal(message)
if message == STREAM_DATA_PROVIDER_DEFAULT_ERROR
));
}
#[test]
fn callback_adapter_writes_through_the_provider_source_boundary() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let calls = Rc::new(Cell::new(0));
let callback_calls = Rc::clone(&calls);
stream
.replace_stream_data_with_callback(
move |pipeline| {
callback_calls.set(callback_calls.get() + 1);
pipeline.write(b"callback bytes").map_err(Error::from)?;
pipeline.finish().map_err(Error::from)
},
None,
None,
)
.expect("callback provider replacement");
assert_eq!(
stream
.get_raw_stream_data()
.expect("callback provider pipe")
.as_slice(),
b"callback bytes"
);
assert_eq!(calls.get(), 1);
}
#[test]
fn callback_adapters_propagate_errors_and_preserve_repeated_invocation() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let calls = Rc::new(Cell::new(0));
let callback_calls = Rc::clone(&calls);
stream
.replace_stream_data_with_callback(
move |_pipeline| {
callback_calls.set(callback_calls.get() + 1);
Err(Error::System("callback failure".to_owned()))
},
None,
None,
)
.expect("callback provider replacement");
for _ in 0..2 {
let error = stream
.get_raw_stream_data()
.expect_err("callback error must cross the provider boundary");
assert!(matches!(
error,
Error::System(message) if message == "callback failure"
));
}
assert_eq!(
calls.get(),
2,
"callback must remain reusable after an error"
);
}
#[test]
fn callback_adapters_propagate_pipeline_write_and_finish_errors() {
let mut write_pipeline = FailingCallbackPipeline {
failure: "callback write failure",
};
assert_eq!(write_pipeline.identifier(), "failing callback pipeline");
let write_provider = CallbackProvider {
callback: |pipeline: &mut dyn Pipeline| {
pipeline.write(b"write failure").map_err(Error::from)
},
};
assert!(matches!(
write_provider
.provide_stream_data(ObjectRef::new(47, 0), &mut write_pipeline)
.expect_err("callback write failure must propagate"),
Error::System(message) if message == "callback write failure"
));
let mut finish_pipeline = FailingCallbackPipeline {
failure: "callback finish failure",
};
let finish_provider = CallbackProvider {
callback: |pipeline: &mut dyn Pipeline| pipeline.finish().map_err(Error::from),
};
assert!(matches!(
finish_provider
.provide_stream_data(ObjectRef::new(47, 0), &mut finish_pipeline)
.expect_err("callback finish failure must propagate"),
Error::System(message) if message == "callback finish failure"
));
}
#[test]
fn retry_callback_adapter_forwards_both_flag_combinations() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let flags = Rc::new(RefCell::new(Vec::new()));
let callback_flags = Rc::clone(&flags);
stream
.replace_stream_data_with_retry_callback(
move |pipeline, suppress_warnings, will_retry| {
callback_flags
.borrow_mut()
.push((suppress_warnings, will_retry));
pipeline
.write(b"retry callback bytes")
.map_err(Error::from)?;
pipeline.finish().map_err(Error::from)?;
Ok(true)
},
None,
None,
)
.expect("retry callback provider replacement");
assert_eq!(
stream
.get_raw_stream_data()
.expect("default retry callback pipe")
.as_slice(),
b"retry callback bytes"
);
let mut sink = crate::pipeline::buffer::Buffer::new("retry callback", None);
let mut filtering_attempted = false;
assert!(stream
.pipe_stream_data(
&mut sink,
&mut filtering_attempted,
0,
crate::writer::DecodeLevel::None,
true,
true,
)
.expect("explicit retry callback pipe"));
assert_eq!(
sink.take_buffer().expect("retry callback output"),
b"retry callback bytes"
);
assert_eq!(*flags.borrow(), vec![(false, false), (true, true)]);
}
#[test]
fn replacing_a_provider_with_a_buffer_releases_the_provider_source() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let provider = Rc::new(LegacyProvider::default());
let ownership = Rc::downgrade(&provider);
stream
.replace_stream_data_provider(provider.clone(), None, None)
.expect("provider replacement");
drop(provider);
assert!(ownership.upgrade().is_some());
stream.replace_stream_data(Rc::new(b"new".to_vec()), None, None);
assert!(
ownership.upgrade().is_none(),
"buffer replacement must clear provider ownership"
);
assert_eq!(
stream.as_stream_data().expect("buffer source").as_slice(),
b"new"
);
assert!(stream.with_value(|value| matches!(
value,
Some(ObjectValue::Stream(stream))
if stream.stream_provider.is_none()
&& stream.filter_on_write
&& stream.stream_token_filters.is_empty()
&& !stream.content_normalization_applied
)));
}
#[test]
fn provider_replacement_uses_qpdf_filter_boundary_for_uninitialized_and_null_values() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf
.new_stream_with_data(Rc::new(b"old".to_vec()))
.expect("owned stream");
let dict = stream.as_stream_dict().expect("stream dictionary");
dict.replace_key(b"/Filter", ObjectHandle::name(b"Keep".to_vec()))
.expect("filter key");
dict.replace_key(b"/DecodeParms", ObjectHandle::dictionary(vec![]))
.expect("decode parms key");
stream
.replace_stream_data_provider(Rc::new(LegacyProvider::default()), None, None)
.expect("provider replacement");
assert!(dict.try_has_key(b"/Filter").unwrap());
assert!(dict.try_has_key(b"/DecodeParms").unwrap());
assert!(!dict.try_has_key(b"/Length").unwrap());
stream
.replace_stream_data_provider(
Rc::new(LegacyProvider::default()),
Some(ObjectHandle::null()),
Some(ObjectHandle::null()),
)
.expect("provider replacement with explicit nulls");
assert!(!dict.try_has_key(b"/Filter").unwrap());
assert!(!dict.try_has_key(b"/DecodeParms").unwrap());
}
#[test]
fn provider_replacement_rejects_a_non_stream_with_qpdf_assertion_error() {
let error = ObjectHandle::integer(7)
.replace_stream_data_provider(Rc::new(LegacyProvider::default()), None, None)
.expect_err("non-stream provider replacement must fail");
assert!(matches!(
error,
Error::System(message)
if message == "operation for stream attempted on object of type integer"
));
}
#[test]
fn legacy_object_identity_form_delegates_to_the_numeric_form() {
let provider = LegacyProvider::default();
let mut sink = crate::pipeline::buffer::Buffer::new("provider", None);
provider
.provide_stream_data(ObjectRef::new(17, 4), &mut sink)
.expect("legacy provider");
assert_eq!(provider.calls.get(), 1);
assert_eq!(*provider.identities.borrow(), vec![(17, 4)]);
provider
.provide_stream_data_by_qpdf_obj_gen(17, 4, &mut sink)
.expect("projectable raw provider");
provider
.provide_stream_data_by_qpdf_obj_gen(17, 65_536, &mut sink)
.expect("unprojectable raw provider fallback");
assert_eq!(provider.calls.get(), 3);
assert_eq!(
*provider.identities.borrow(),
vec![(17, 4), (17, 4), (17, 0)]
);
}
#[test]
fn retry_object_identity_form_delegates_flags_to_the_numeric_form() {
let provider = RetryProvider::default();
let mut sink = crate::pipeline::buffer::Buffer::new("provider", None);
assert!(provider
.provide_stream_data_with_retry(ObjectRef::new(23, 2), &mut sink, true, false,)
.expect("retry provider"));
assert!(provider.supports_retry());
assert_eq!(provider.calls.get(), 1);
assert_eq!(*provider.flags.borrow(), vec![(true, false)]);
assert!(provider
.provide_stream_data_with_retry_by_qpdf_obj_gen(23, 2, &mut sink, true, false)
.expect("projectable raw retry provider"));
assert!(provider
.provide_stream_data_with_retry_by_qpdf_obj_gen(23, 65_536, &mut sink, false, true)
.expect("unprojectable raw retry provider fallback"));
assert_eq!(provider.calls.get(), 3);
assert_eq!(
*provider.flags.borrow(),
vec![(true, false), (true, false), (false, true)]
);
}
#[test]
fn default_provider_methods_return_qpdf_contract_error() {
let provider = EmptyProvider;
let mut sink = crate::pipeline::buffer::Buffer::new("provider", None);
assert!(!provider.supports_retry());
let error = provider
.provide_stream_data(ObjectRef::new(1, 0), &mut sink)
.expect_err("default provider must reject missing implementation");
assert!(matches!(
error,
Error::Internal(message)
if message == "you must override provideStreamData -- see QPDFObjectHandle.hh"
));
let error = provider
.provide_stream_data_with_retry(ObjectRef::new(1, 0), &mut sink, false, true)
.expect_err("default retry provider must reject missing implementation");
assert!(matches!(
error,
Error::Internal(message)
if message == "you must override provideStreamData -- see QPDFObjectHandle.hh"
));
}
struct RawDefaultResolver;
// cov:ignore-start: this resolver only installs a value for the following
// test; the test intentionally exercises the default raw-identity route.
impl DocumentResolver for RawDefaultResolver {
fn resolve_indirect(&self, _object_ref: ObjectRef, handle: &ObjectHandle) -> Result<()> {
handle.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
Ok(())
}
}
// cov:ignore-end
#[test]
fn raw_resolver_default_rejects_an_unprojectable_stream_identity() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(RawDefaultResolver);
let stream = ObjectHandle::new_indirect_for_qpdf_obj_gen_with_resolver(
QpdfObjGen::new(5, 65_536),
-1,
0,
Rc::downgrade(&resolver),
);
stream.set_resolved(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
let error = stream
.get_raw_stream_data()
.expect_err("a resolver without a raw stream route must reject the identity");
assert!(matches!(
error,
Error::Internal(message)
if message == "object 5 65536 is not a valid indirect reference"
));
}
#[test]
fn provider_backed_direct_stream_rejects_missing_qpdf_identity() {
let stream = ObjectHandle::stream(ObjectHandle::dictionary(vec![]), Rc::new(Vec::new()));
stream.with_value_mut(|value| {
if let Some(ObjectValue::Stream(stream)) = value {
stream.stream_data = None;
stream.stream_provider = Some(Rc::new(LegacyProvider::default()));
}
});
let error = stream
.get_raw_stream_data()
.expect_err("a provider-backed direct stream has no qpdf identity");
assert!(matches!(
error,
Error::Internal(message)
if message == "pipeStreamData called for provider-backed direct stream"
));
}
#[test]
fn provider_debug_uses_qpdf_shaped_marker() {
let provider: Rc<dyn StreamDataProvider> = Rc::new(EmptyProvider);
assert_eq!(format!("{provider:?}"), "StreamDataProvider(..)");
}
fn registered_provider(value: Option<&ObjectValue>) -> Rc<dyn StreamDataProvider> {
match value {
Some(ObjectValue::Stream(stream)) => stream
.stream_provider
.as_ref()
.expect("callback test stream must retain its provider")
.clone(),
_ => unreachable!("callback test stream must retain its provider"), // cov:ignore: test fixture always registers a provider-backed stream
}
}
#[test]
fn callback_adapters_forward_pipeline_data_and_retry_flags() {
let mut void_sink = crate::pipeline::buffer::Buffer::new("void callback", None);
let void_provider = CallbackProvider {
callback: |pipeline: &mut dyn Pipeline| {
pipeline
.write(b"void callback bytes")
.map_err(Error::from)?;
pipeline.finish().map_err(Error::from)
},
};
void_provider
.provide_stream_data(ObjectRef::new(41, 2), &mut void_sink)
.expect("void callback provider");
assert_eq!(
void_sink.take_buffer().expect("void callback output"),
b"void callback bytes"
);
let mut retry_sink = crate::pipeline::buffer::Buffer::new("retry callback", None);
let retry_provider = RetryCallbackProvider {
callback: |pipeline: &mut dyn Pipeline, suppress_warnings: bool, will_retry: bool| {
assert!(suppress_warnings);
assert!(!will_retry);
pipeline
.write(b"retry callback bytes")
.map_err(Error::from)?;
pipeline.finish().map_err(Error::from)?;
Ok(true)
},
};
assert!(retry_provider.supports_retry());
assert!(retry_provider
.provide_stream_data_with_retry(ObjectRef::new(43, 1), &mut retry_sink, true, false,)
.expect("retry callback provider"));
assert_eq!(
retry_sink.take_buffer().expect("retry callback output"),
b"retry callback bytes"
);
}
#[test]
fn callback_adapters_are_deferred_and_retry_capability_is_retained() {
let pdf = crate::Pdf::empty().expect("empty PDF");
let stream = pdf.new_stream().expect("owned empty stream");
let void_calls = Rc::new(Cell::new(0));
let void_calls_for_callback = Rc::clone(&void_calls);
stream
.replace_stream_data_with_callback(
move |_pipeline| {
void_calls_for_callback.set(void_calls_for_callback.get() + 1);
Ok(())
},
None,
None,
)
.expect("void callback replacement");
assert_eq!(void_calls.get(), 0, "callback registration must be lazy");
let mut void_sink = crate::pipeline::buffer::Buffer::new("void callback", None);
stream
.with_value(registered_provider)
.provide_stream_data(ObjectRef::new(41, 2), &mut void_sink)
.expect("void callback provider");
assert_eq!(void_calls.get(), 1, "void callback runs only when piped");
let retry_calls = Rc::new(Cell::new(0));
let retry_calls_for_callback = Rc::clone(&retry_calls);
stream
.replace_stream_data_with_retry_callback(
move |_pipeline, _suppress_warnings, _will_retry| {
retry_calls_for_callback.set(retry_calls_for_callback.get() + 1);
Ok(true)
},
None,
None,
)
.expect("retry callback replacement");
assert_eq!(
retry_calls.get(),
0,
"retry callback registration must be lazy"
);
let mut retry_sink = crate::pipeline::buffer::Buffer::new("retry callback", None);
assert!(stream
.with_value(registered_provider)
.provide_stream_data_with_retry(ObjectRef::new(43, 1), &mut retry_sink, true, false)
.expect("retry callback provider"));
assert_eq!(retry_calls.get(), 1, "retry callback runs only when piped");
fn is_retry_provider(value: Option<&ObjectValue>) -> bool {
match value {
Some(ObjectValue::Stream(stream)) => stream
.stream_provider
.as_ref()
.is_some_and(|provider| provider.supports_retry()),
_ => false,
}
}
assert!(stream.with_value(is_retry_provider));
assert!(!ObjectHandle::integer(0).with_value(is_retry_provider));
}
}
#[cfg(test)]
pub(crate) mod warning_emission_tests {
use super::*;
use std::collections::BTreeMap;
/// A document that records every warning an object emits through it.
pub(crate) struct WarningRecorder {
value: ObjectValue,
warnings: RefCell<Vec<String>>,
}
impl DocumentResolver for WarningRecorder {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
handle.set_resolved(self.value.clone());
Ok(())
}
fn warn(&self, warning: QpdfExc) -> crate::Result<()> {
self.warnings
.borrow_mut()
.push(String::from_utf8_lossy(warning.what_bytes()).into_owned());
Ok(())
}
}
/// An indirect handle that resolves to `value`, paired with the document
/// it warns through.
pub(crate) fn handle_resolving(value: ObjectValue) -> (ObjectHandle, Rc<WarningRecorder>) {
let recorder = Rc::new(WarningRecorder {
value,
warnings: RefCell::new(Vec::new()),
});
// The erased `Rc` shares its allocation with `recorder`, so the
// returned recorder is what keeps the handle's `Weak` upgradable.
let erased: Rc<dyn DocumentResolver> = recorder.clone();
let handle =
ObjectHandle::new_indirect_with_resolver(ObjectRef::new(3, 0), Rc::downgrade(&erased));
(handle, recorder)
}
pub(crate) fn warnings(recorder: &Rc<WarningRecorder>) -> Vec<String> {
recorder.warnings.borrow().clone()
}
#[test]
fn type_warning_through_a_context_matches_qpdf_message_text() {
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
handle
.type_warning("dictionary", "treating as empty")
.unwrap();
assert_eq!(
warnings(&recorder),
["object 3 0: operation for dictionary attempted on object of type integer: treating as empty"]
);
}
#[test]
fn try_has_key_on_a_non_dictionary_emits_qpdf_warning_and_returns_false() {
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
assert!(!handle.try_has_key(b"/A").unwrap());
assert_eq!(
warnings(&recorder),
["object 3 0: operation for dictionary attempted on object of type integer: returning false for a key containment request"]
);
}
#[test]
fn try_get_key_on_a_non_dictionary_uses_qpdf_null_context_description() {
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
let null = handle.try_get_key(b"/A").unwrap();
assert!(null.is_null());
assert_eq!(
null.description(),
b"object 3 0 -> null returned from getting key from non-Dictionary"
);
assert_eq!(
warnings(&recorder),
["object 3 0: operation for dictionary attempted on object of type integer: returning null for attempted key retrieval"]
);
}
#[test]
fn shape_predicates_resolve_lazy_containers_without_snapshotting() {
let (array, _array_recorder) = handle_resolving(ObjectValue::Array(vec![]));
let (dictionary, _dictionary_recorder) =
handle_resolving(ObjectValue::Dictionary(BTreeMap::new()));
let (integer, _integer_recorder) = handle_resolving(ObjectValue::Integer(7));
let null = ObjectHandle::null();
assert!(array.as_array().is_none());
assert!(dictionary.as_dictionary().is_none());
assert!(array.try_is_array().unwrap());
assert!(!array.try_is_dictionary().unwrap());
assert!(dictionary.try_is_dictionary().unwrap());
assert!(!dictionary.try_is_array().unwrap());
assert!(!integer.try_is_array().unwrap());
assert!(!integer.try_is_dictionary().unwrap());
assert!(!null.try_is_array().unwrap());
assert!(!null.try_is_dictionary().unwrap());
}
#[test]
fn type_warning_names_the_type_it_actually_found() {
let (handle, recorder) = handle_resolving(ObjectValue::Name(b"Foo".to_vec()));
handle.type_warning("integer", "returning 0").unwrap();
assert_eq!(
warnings(&recorder),
["object 3 0: operation for integer attempted on object of type name: returning 0"]
);
}
#[test]
fn type_warning_without_a_context_returns_the_error_qpdf_throws() {
let handle = ObjectHandle::integer(7);
let error = handle
.type_warning("dictionary", "treating as empty")
.unwrap_err();
assert!(matches!(
error,
crate::Error::QpdfExc(ref error)
if error.get_message_detail()
== b"operation for dictionary attempted on object of type integer: \
treating as empty"
));
}
#[test]
fn qpdf_type_check_accessors_return_fallbacks_and_warn() {
let (integer, recorder) = handle_resolving(ObjectValue::Integer(7));
let (dictionary, dictionary_recorder) =
handle_resolving(ObjectValue::Dictionary(BTreeMap::new()));
assert!(!integer.try_get_bool_value().unwrap());
assert_eq!(integer.try_get_real_value().unwrap(), b"0.0");
assert_eq!(integer.try_get_name().unwrap(), b"/QPDFFakeName");
assert!(integer.try_get_string_value().unwrap().is_empty());
assert!(integer.try_get_utf8_value().unwrap().is_empty());
assert_eq!(integer.try_get_operator_value().unwrap(), b"QPDFFAKE");
assert!(integer.try_get_inline_image_value().unwrap().is_empty());
assert_eq!(dictionary.try_get_int_value().unwrap(), 0);
assert_eq!(dictionary.try_get_numeric_value().unwrap(), 0.0);
assert_eq!(warnings(&recorder).len(), 7);
assert_eq!(warnings(&dictionary_recorder).len(), 2);
assert!(warnings(&recorder)
.iter()
.all(|message| message.contains("object 3 0: operation for")));
assert!(warnings(&dictionary_recorder)
.iter()
.all(|message| message.contains("object 3 0: operation for")));
}
#[test]
fn qpdf_utf8_accessors_resolve_indirect_strings_through_as_string() {
let (warning, warning_recorder) =
handle_resolving(ObjectValue::String(b"warning".to_vec()));
assert!(!warning.is_resolved());
assert_eq!(warning.try_get_utf8_value().unwrap(), b"warning");
assert!(warning.is_resolved());
assert!(warnings(&warning_recorder).is_empty());
let (silent, silent_recorder) = handle_resolving(ObjectValue::String(b"silent".to_vec()));
assert!(!silent.is_resolved());
assert_eq!(
silent.try_get_value_as_utf8().unwrap(),
Some(b"silent".to_vec())
);
assert!(silent.is_resolved());
assert!(warnings(&silent_recorder).is_empty());
}
#[test]
fn qpdf_type_check_container_accessors_keep_qpdf_fallbacks() {
let (integer, recorder) = handle_resolving(ObjectValue::Integer(7));
let null = ObjectHandle::null();
assert_eq!(integer.try_get_array_n_items().unwrap(), 0);
assert!(integer.try_get_array_as_vector().unwrap().is_empty());
assert!(integer.try_get_array_item(-1).unwrap().is_null());
assert!(!integer.try_get_has_key(b"/Potato").unwrap());
assert!(integer.try_get_dict_as_map().unwrap().is_empty());
assert!(integer.try_get_key_if_dict(b"/Potato").unwrap().is_null());
assert!(null.try_get_key_if_dict(b"/Integer").unwrap().is_null());
assert_eq!(warnings(&recorder).len(), 6);
assert!(warnings(&recorder)
.iter()
.any(|message| message.contains("returning null")));
}
#[test]
fn qpdf_uninitialized_handles_are_distinct_from_null_and_unresolved_values() {
let handle = ObjectHandle::default();
assert!(!handle.is_initialized());
assert!(!handle.is_null());
assert!(!handle.is_resolved());
assert!(!handle.try_is_integer().unwrap());
assert!(!handle.try_is_array().unwrap());
assert!(!handle.try_is_dictionary().unwrap());
assert!(!handle.try_is_name().unwrap());
assert!(handle.try_as_dictionary().unwrap().is_none());
assert!(handle.try_as_name().unwrap().is_none());
assert!(handle.try_as_string().unwrap().is_none());
assert!(handle.try_as_integer().unwrap().is_none());
assert!(handle.try_as_real().unwrap().is_none());
assert!(handle.try_as_array().unwrap().is_none());
assert!(!handle.try_is_null().unwrap());
assert!(!handle.try_is_scalar().unwrap());
assert!(!handle.try_is_number().unwrap());
assert_eq!(handle.type_code().unwrap(), 0);
assert_eq!(handle.type_name().unwrap(), "uninitialized");
assert!(!handle.try_is_rectangle().unwrap());
assert_eq!(
handle.try_get_array_as_rectangle().unwrap(),
Rectangle::default()
);
assert!(!handle.try_is_matrix().unwrap());
assert_eq!(
handle.try_get_array_as_matrix().unwrap(),
ObjectHandleMatrix::default()
);
assert!(matches!(
handle.try_dereference(),
Err(crate::Error::Internal(message))
if message == "attempted to dereference an uninitialized QPDFObjectHandle"
));
let mut bytes = Vec::new();
let mut output = crate::pipeline::PlString::new("uninitialized", None, &mut bytes);
let error = handle
.write_json(2, &mut output, true, 0)
.expect_err("JSON dereference must reject an uninitialized handle");
assert_eq!(
error.to_string(),
"attempted to dereference an uninitialized QPDFObjectHandle"
);
}
#[test]
fn qpdf_geometry_helpers_use_zero_fallbacks_and_silent_number_checks() {
let rectangle = ObjectHandle::new_from_rectangle(Rectangle::new(7.8, 5.6, 1.2, 3.4));
assert!(rectangle.try_is_rectangle().unwrap());
assert_eq!(
rectangle.try_get_array_as_rectangle().unwrap(),
Rectangle::new(1.2, 3.4, 7.8, 5.6)
);
let invalid_rectangle = ObjectHandle::array(vec![
ObjectHandle::integer(1),
ObjectHandle::integer(2),
ObjectHandle::integer(3),
ObjectHandle::boolean(false),
]);
assert!(!invalid_rectangle.try_is_rectangle().unwrap());
assert_eq!(
invalid_rectangle.try_get_array_as_rectangle().unwrap(),
Rectangle::default()
);
let integer_rectangle = ObjectHandle::array(vec![
ObjectHandle::integer(1),
ObjectHandle::integer(2),
ObjectHandle::integer(3),
ObjectHandle::integer(4),
]);
assert!(integer_rectangle.try_is_rectangle().unwrap());
assert_eq!(
integer_rectangle.try_get_array_as_rectangle().unwrap(),
Rectangle::new(1.0, 2.0, 3.0, 4.0)
);
let literal_rectangle = ObjectHandle::array(vec![
ObjectHandle::real_literal(1.2, b"1.2".to_vec()),
ObjectHandle::real_literal(3.4, b"3.4".to_vec()),
ObjectHandle::real_literal(5.6, b"5.6".to_vec()),
ObjectHandle::real_literal(7.8, b"7.8".to_vec()),
]);
assert_eq!(
literal_rectangle.try_get_array_as_rectangle().unwrap(),
Rectangle::new(1.2, 3.4, 5.6, 7.8)
);
assert!(!ObjectHandle::integer(1).try_is_rectangle().unwrap());
let uninitialized_rectangle = ObjectHandle::array(vec![
ObjectHandle::uninitialized(),
ObjectHandle::integer(2),
ObjectHandle::integer(3),
ObjectHandle::integer(4),
]);
assert_eq!(
uninitialized_rectangle
.try_get_array_as_rectangle()
.unwrap(),
Rectangle::default()
);
let matrix =
ObjectHandle::new_from_matrix(ObjectHandleMatrix::new(1.2, 3.4, 5.6, 7.8, 9.1, 2.3));
assert!(matrix.try_is_matrix().unwrap());
assert_eq!(
matrix.try_get_array_as_matrix().unwrap(),
ObjectHandleMatrix::new(1.2, 3.4, 5.6, 7.8, 9.1, 2.3)
);
let qpdf_matrix =
ObjectHandle::new_from_qpdf_matrix(crate::Matrix::new(1.2, 3.4, 5.6, 7.8, 9.1, 2.3));
assert_eq!(
qpdf_matrix.try_get_array_as_matrix().unwrap(),
ObjectHandleMatrix::new(1.2, 3.4, 5.6, 7.8, 9.1, 2.3)
);
let invalid_matrix = ObjectHandle::array(vec![
ObjectHandle::integer(1),
ObjectHandle::integer(2),
ObjectHandle::integer(3),
ObjectHandle::boolean(false),
ObjectHandle::integer(5),
ObjectHandle::integer(6),
]);
assert!(!invalid_matrix.try_is_matrix().unwrap());
assert_eq!(
invalid_matrix.try_get_array_as_matrix().unwrap(),
ObjectHandleMatrix::default()
);
}
#[test]
fn qpdf_cursors_return_child_identity_and_uninitialized_end_values() {
let array = ObjectHandle::array(vec![
ObjectHandle::name(b"Item0".to_vec()),
ObjectHandle::name(b"Item1".to_vec()),
ObjectHandle::name(b"Item2".to_vec()),
]);
let items = array.try_array_items().unwrap();
let mut cursor = items.begin();
let held = cursor.current();
assert_eq!(held.try_get_name().unwrap(), b"/Item0");
assert!(held.is_same_object_as(&array.try_get_array_item(0).unwrap()));
cursor.previous();
assert_eq!(held.try_get_name().unwrap(), b"/Item0");
cursor.next();
cursor.next();
cursor.next();
assert!(cursor.is_end());
assert!(!cursor.current().is_initialized());
assert!(held.is_initialized());
assert_eq!(held.try_get_name().unwrap(), b"/Item0");
cursor.previous();
assert_eq!(cursor.current().try_get_name().unwrap(), b"/Item2");
assert_eq!(held.try_get_name().unwrap(), b"/Item0");
let dictionary = ObjectHandle::dictionary(vec![
(b"Key1".to_vec(), ObjectHandle::name(b"Value1".to_vec())),
(b"Key2".to_vec(), ObjectHandle::name(b"Value2".to_vec())),
]);
let items = dictionary.try_dict_items().unwrap();
let mut cursor = items.begin();
let entry = cursor.current();
assert_eq!(entry.key, b"/Key1");
assert_eq!(entry.value.try_get_name().unwrap(), b"/Value1");
assert!(entry
.value
.is_same_object_as(&dictionary.try_get_key(b"/Key1").unwrap()));
cursor.next();
cursor.next();
assert!(cursor.is_end());
assert!(!cursor.current().value.is_initialized());
assert!(entry.value.is_initialized());
assert_eq!(entry.value.try_get_name().unwrap(), b"/Value1");
cursor.previous();
assert_eq!(cursor.current().key, b"/Key2");
let empty_array_items = ObjectHandle::integer(7).try_array_items().unwrap();
assert!(empty_array_items.end().is_end());
let empty_dict_items = ObjectHandle::integer(7).try_dict_items().unwrap();
assert!(empty_dict_items.end().is_end());
}
#[test]
fn cursor_current_returns_child_identity_without_rebinding_held_value() {
let array = ObjectHandle::array(vec![
ObjectHandle::name(b"Item0".to_vec()),
ObjectHandle::name(b"Item1".to_vec()),
]);
let items = array.try_array_items().unwrap();
let mut cursor = items.begin();
let held = cursor.current();
assert!(held.is_same_object_as(&array.try_get_array_item(0).unwrap()));
cursor.next();
assert_eq!(held.try_get_name().unwrap(), b"/Item0");
assert_eq!(cursor.current().try_get_name().unwrap(), b"/Item1");
cursor.next();
assert!(cursor.is_end());
assert!(!cursor.current().is_initialized());
assert!(held.is_initialized());
assert_eq!(held.try_get_name().unwrap(), b"/Item0");
}
#[test]
fn dict_cursor_returns_identity_and_initialized_null_for_removed_key() {
let dictionary = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::name(b"ValueA".to_vec())),
(b"B".to_vec(), ObjectHandle::name(b"ValueB".to_vec())),
]);
let items = dictionary.try_dict_items().unwrap();
let mut cursor = items.begin();
let first = cursor.current();
assert_eq!(first.key, b"/A");
assert!(first
.value
.is_same_object_as(&dictionary.try_get_key(b"/A").unwrap()));
dictionary.remove_key(b"/A");
let removed = cursor.current();
assert_eq!(removed.key, b"/A");
assert!(!cursor.is_end());
assert!(removed.value.is_initialized());
assert!(removed.value.is_null());
cursor.next();
assert_eq!(cursor.current().key, b"/B");
cursor.next();
assert!(cursor.is_end());
assert!(!cursor.current().value.is_initialized());
}
#[test]
fn qpdf_type_check_accessors_cover_successful_values_and_live_containers() {
assert!(ObjectHandle::boolean(true).try_get_bool_value().unwrap());
assert!(ObjectHandle::integer(7).try_is_scalar().unwrap());
assert_eq!(
ObjectHandle::real(1.25).try_get_real_value().unwrap(),
b"1.25"
);
assert_eq!(
ObjectHandle::real_literal(0.4, b".4".to_vec())
.try_get_real_value()
.unwrap(),
b".4"
);
assert_eq!(
ObjectHandle::integer(7).try_get_numeric_value().unwrap(),
7.0
);
assert_eq!(
ObjectHandle::real(1.25).try_get_numeric_value().unwrap(),
1.25
);
assert_eq!(
ObjectHandle::real_literal(0.4, b".4".to_vec())
.try_get_numeric_value()
.unwrap(),
0.4
);
assert_eq!(
ObjectHandle::name(b"Name".to_vec()).try_get_name().unwrap(),
b"/Name"
);
assert_eq!(
ObjectHandle::string(vec![0xfe, 0xff, 0x00, b'A'])
.try_get_string_value()
.unwrap(),
vec![0xfe, 0xff, 0x00, b'A']
);
assert_eq!(
ObjectHandle::string(vec![0xfe, 0xff, 0x00, b'A'])
.try_get_utf8_value()
.unwrap(),
b"A"
);
assert_eq!(
ObjectHandle::operator(b"q".to_vec())
.try_get_operator_value()
.unwrap(),
b"q"
);
assert_eq!(
ObjectHandle::inline_image(b"raw".to_vec())
.try_get_inline_image_value()
.unwrap(),
b"raw"
);
let array = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
assert!(array.try_is_array().unwrap());
assert!(!array.try_is_integer().unwrap());
assert_eq!(array.try_get_array_n_items().unwrap(), 1);
assert_eq!(array.try_get_array_as_vector().unwrap().len(), 1);
assert_eq!(array.try_get_array_item(0).unwrap().as_integer(), Some(1));
let dictionary = ObjectHandle::dictionary(vec![
(b"A".to_vec(), ObjectHandle::integer(1)),
(b"B".to_vec(), ObjectHandle::null()),
]);
assert!(dictionary.try_is_dictionary().unwrap());
assert_eq!(dictionary.try_get_dict_as_map().unwrap().len(), 2);
assert!(dictionary.try_get_has_key(b"/A").unwrap());
assert!(!dictionary.try_get_has_key(b"/B").unwrap());
let mut items = dictionary.try_dict_items().unwrap().begin();
assert_eq!(items.current().key, b"/A");
items.next();
assert!(items.is_end());
}
#[test]
fn qpdf_get_value_as_accessors_have_a_canonical_object_handle_boundary() {
let source = include_str!("object_handle.rs");
for method in [
"try_get_value_as_bool",
"try_get_value_as_int",
"try_get_value_as_int_as_int",
"try_get_value_as_uint",
"try_get_value_as_uint_as_uint",
"try_get_value_as_real",
"try_get_value_as_number",
"try_get_value_as_name",
"try_get_value_as_string",
"try_get_value_as_utf8",
"try_get_value_as_operator",
"try_get_value_as_inline_image",
] {
assert!(
source.contains(&format!("pub fn {method}")),
"missing qpdf getValueAs primitive {method}"
);
}
}
#[test]
fn qpdf_get_value_as_accessors_are_silent_on_wrong_types_and_resolve_indirect_values() {
let (integer, recorder) = handle_resolving(ObjectValue::Integer(7));
assert!(!integer.is_resolved());
assert_eq!(integer.try_get_value_as_bool().unwrap(), None);
assert_eq!(integer.try_get_value_as_int().unwrap(), Some(7));
assert!(integer.is_resolved());
assert!(warnings(&recorder).is_empty());
let (name, recorder) = handle_resolving(ObjectValue::Name(b"WrongType".to_vec()));
assert_eq!(name.try_get_value_as_int().unwrap(), None);
assert_eq!(name.try_get_value_as_real().unwrap(), None);
assert_eq!(name.try_get_value_as_string().unwrap(), None);
assert!(warnings(&recorder).is_empty());
}
#[test]
fn qpdf_get_value_as_accessors_treat_uninitialized_handles_as_absent() {
let handle = ObjectHandle::uninitialized();
assert_eq!(handle.try_get_value_as_bool().unwrap(), None);
assert_eq!(handle.try_get_value_as_int().unwrap(), None);
assert_eq!(handle.try_get_value_as_int_as_int().unwrap(), None);
assert_eq!(handle.try_get_value_as_uint().unwrap(), None);
assert_eq!(handle.try_get_value_as_uint_as_uint().unwrap(), None);
assert_eq!(handle.try_get_value_as_real().unwrap(), None);
assert_eq!(handle.try_get_value_as_number().unwrap(), None);
assert_eq!(handle.try_get_value_as_name().unwrap(), None);
assert_eq!(handle.try_get_value_as_string().unwrap(), None);
assert_eq!(handle.try_get_value_as_utf8().unwrap(), None);
assert_eq!(handle.try_get_value_as_operator().unwrap(), None);
assert_eq!(handle.try_get_value_as_inline_image().unwrap(), None);
}
#[test]
fn qpdf_get_value_as_accessors_preserve_literals_and_type_specific_values() {
assert_eq!(
ObjectHandle::boolean(false)
.try_get_value_as_bool()
.unwrap(),
Some(false)
);
assert_eq!(
ObjectHandle::integer(1).try_get_value_as_int().unwrap(),
Some(1)
);
assert_eq!(
ObjectHandle::integer(1)
.try_get_value_as_int_as_int()
.unwrap(),
Some(1)
);
assert_eq!(
ObjectHandle::integer(1).try_get_value_as_uint().unwrap(),
Some(1)
);
assert_eq!(
ObjectHandle::integer(1)
.try_get_value_as_uint_as_uint()
.unwrap(),
Some(1)
);
assert_eq!(
ObjectHandle::real_literal(42.0, b"42.0".to_vec())
.try_get_value_as_real()
.unwrap(),
Some(b"42.0".to_vec())
);
assert_eq!(
ObjectHandle::real(1.25).try_get_value_as_real().unwrap(),
Some(b"1.25".to_vec())
);
assert_eq!(
ObjectHandle::integer(1).try_get_value_as_number().unwrap(),
Some(1.0)
);
assert_eq!(
ObjectHandle::name(b"Test".to_vec())
.try_get_value_as_name()
.unwrap(),
Some(b"/Test".to_vec())
);
assert_eq!(
ObjectHandle::string(b"/Test".to_vec())
.try_get_value_as_string()
.unwrap(),
Some(b"/Test".to_vec())
);
assert_eq!(
ObjectHandle::string(b"/Test".to_vec())
.try_get_value_as_utf8()
.unwrap(),
Some(b"/Test".to_vec())
);
assert_eq!(
ObjectHandle::operator(b"/Test".to_vec())
.try_get_value_as_operator()
.unwrap(),
Some(b"/Test".to_vec())
);
assert_eq!(
ObjectHandle::inline_image(b"/Test".to_vec())
.try_get_value_as_inline_image()
.unwrap(),
Some(b"/Test".to_vec())
);
}
#[test]
fn qpdf_get_value_as_integer_clamps_only_with_qpdf_warnings() {
let (too_large, large_recorder) =
handle_resolving(ObjectValue::Integer(i64::from(i32::MAX) + 1));
assert_eq!(
too_large.try_get_value_as_int_as_int().unwrap(),
Some(i32::MAX)
);
assert_eq!(
warnings(&large_recorder),
["object 3 0: requested value of integer is too big; returning INT_MAX"]
);
let (too_small, small_recorder) =
handle_resolving(ObjectValue::Integer(i64::from(i32::MIN) - 1));
assert_eq!(
too_small.try_get_value_as_int_as_int().unwrap(),
Some(i32::MIN)
);
assert_eq!(
warnings(&small_recorder),
["object 3 0: requested value of integer is too small; returning INT_MIN"]
);
let (too_large_unsigned, unsigned_recorder) =
handle_resolving(ObjectValue::Integer(i64::from(u32::MAX) + 1));
assert_eq!(
too_large_unsigned.try_get_value_as_uint_as_uint().unwrap(),
Some(u32::MAX)
);
assert_eq!(
warnings(&unsigned_recorder),
["object 3 0: requested value of unsigned integer is too big; returning UINT_MAX"]
);
let (negative, negative_recorder) = handle_resolving(ObjectValue::Integer(-1));
assert_eq!(negative.try_get_value_as_uint().unwrap(), Some(0));
assert_eq!(negative.try_get_value_as_uint_as_uint().unwrap(), Some(0));
assert_eq!(
warnings(&negative_recorder),
[
"object 3 0: unsigned value request for negative number; returning 0",
"object 3 0: unsigned integer value request for negative number; returning 0",
]
);
}
#[test]
fn qpdf_get_value_as_unsigned_clamp_warning_sink_failures_propagate() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
let too_large = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(3, 0),
Rc::downgrade(&resolver),
);
too_large.set_resolved(ObjectValue::Integer(i64::from(u32::MAX) + 1));
let error = too_large.try_get_value_as_uint_as_uint().unwrap_err();
assert!(matches!(
error,
crate::Error::Internal(ref message)
if message.contains("returning UINT_MAX")
));
let negative = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(3, 0),
Rc::downgrade(&resolver),
);
negative.set_resolved(ObjectValue::Integer(-1));
let error = negative.try_get_value_as_uint_as_uint().unwrap_err();
assert!(matches!(
error,
crate::Error::Internal(ref message)
if message.contains("unsigned integer value request for negative number")
));
}
#[test]
fn dict_item_cursor_returns_contextual_null_when_container_stops_being_a_dictionary() {
let (dictionary, recorder) = handle_resolving(ObjectValue::Dictionary(
[(b"/A".to_vec(), ObjectHandle::integer(1))]
.into_iter()
.collect(),
));
let mut cursor = dictionary.try_dict_items().unwrap().begin();
// The cursor keeps the same live dictionary handle rather than a
// frozen snapshot; if it stops being a dictionary mid-iteration
// (its Rc-shared slot is reassigned a scalar payload here), the
// cursor must keep the snapshotted key non-end and use qpdf's
// contextual warning/null lookup rather than a stale value.
let replacement = ObjectHandle::integer(2);
replacement.0.borrow().shared.borrow_mut().identity =
dictionary.0.borrow().shared.borrow().identity.clone();
dictionary.assign_value_state(&replacement);
let entry = cursor.current();
assert_eq!(entry.key, b"/A");
assert!(entry.value.is_initialized());
assert!(entry.value.is_null());
assert_eq!(
warnings(&recorder),
["object 3 0: operation for dictionary attempted on object of type integer: returning null for attempted key retrieval"]
);
}
#[test]
fn array_mutators_emit_qpdf_warning_text_for_invalid_domains() {
let (array, recorder) =
handle_resolving(ObjectValue::Array(vec![ObjectHandle::integer(1)]));
array.set_array_item(1, ObjectHandle::integer(2)).unwrap();
array
.insert_array_item(2, ObjectHandle::integer(3))
.unwrap();
let erased = array.erase_array_item_and_get_old(1).unwrap();
assert!(erased.is_null());
assert_eq!(
warnings(&recorder),
[
"object 3 0: ignoring attempt to set out of bounds array item",
"object 3 0: ignoring attempt to insert out of bounds array item",
"object 3 0: ignoring attempt to erase out of bounds array item",
]
);
}
#[test]
fn signed_array_mutators_cover_qpdf_bounds_and_success_paths() {
let array = ObjectHandle::array(vec![ObjectHandle::integer(1)]);
array
.try_set_array_item_at(0, ObjectHandle::integer(2))
.unwrap();
array
.try_append_array_item(ObjectHandle::integer(3))
.unwrap();
array
.try_set_array_items(vec![ObjectHandle::integer(4)])
.unwrap();
array
.try_insert_array_item_at(1, ObjectHandle::integer(5))
.unwrap();
array.try_erase_array_item_at(0).unwrap();
assert_eq!(array.as_array().unwrap().len(), 1);
let (array, recorder) =
handle_resolving(ObjectValue::Array(vec![ObjectHandle::integer(1)]));
array
.try_set_array_item_at(-1, ObjectHandle::integer(2))
.unwrap();
array
.try_set_array_item_at(42, ObjectHandle::integer(2))
.unwrap();
array
.try_insert_array_item_at(-1, ObjectHandle::integer(2))
.unwrap();
array
.try_insert_array_item_at(42, ObjectHandle::integer(2))
.unwrap();
array.try_erase_array_item_at(-1).unwrap();
array.try_erase_array_item_at(42).unwrap();
assert_eq!(warnings(&recorder).len(), 6);
let (integer, recorder) = handle_resolving(ObjectValue::Integer(7));
integer
.try_set_array_item_at(-1, ObjectHandle::null())
.unwrap();
integer
.try_set_array_item_at(0, ObjectHandle::null())
.unwrap();
integer
.try_insert_array_item_at(-1, ObjectHandle::null())
.unwrap();
integer
.try_insert_array_item_at(0, ObjectHandle::null())
.unwrap();
integer.try_erase_array_item_at(-1).unwrap();
integer.try_erase_array_item_at(0).unwrap();
assert_eq!(warnings(&recorder).len(), 6);
}
#[test]
fn array_mutators_emit_type_warning_text_for_non_arrays() {
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
handle.set_array_item(0, ObjectHandle::integer(1)).unwrap();
handle
.set_array_items(vec![ObjectHandle::integer(2)])
.unwrap();
handle
.insert_array_item(0, ObjectHandle::integer(3))
.unwrap();
handle.append_array_item(ObjectHandle::integer(4)).unwrap();
let erased = handle.erase_array_item_and_get_old(0).unwrap();
assert!(erased.is_null());
assert_eq!(warnings(&recorder), [
"object 3 0: operation for array attempted on object of type integer: ignoring attempt to set item",
"object 3 0: operation for array attempted on object of type integer: ignoring attempt to replace items",
"object 3 0: operation for array attempted on object of type integer: ignoring attempt to insert item",
"object 3 0: operation for array attempted on object of type integer: ignoring attempt to append item",
"object 3 0: operation for array attempted on object of type integer: ignoring attempt to erase item",
]);
}
/// A sink that appends every write to a shared buffer.
struct ErrorRecordingSink(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);
impl crate::pipeline::Pipeline for ErrorRecordingSink {
// cov:ignore-start: the default logger does not inspect a sink identifier
fn identifier(&self) -> &str {
"error recording sink"
}
// cov:ignore-end
fn write(&mut self, data: &[u8]) -> crate::pipeline::PipelineResult<()> {
self.0.lock().unwrap().extend_from_slice(data);
Ok(())
}
// cov:ignore-start: the default logger leaves caller-owned sinks unfinished
fn finish(&mut self) -> crate::pipeline::PipelineResult<()> {
Ok(())
}
// cov:ignore-end
}
/// Serializes the tests that redirect the process-global default logger.
///
/// `QPDFLogger::default_logger` is one shared instance, so two tests
/// swapping its error sink concurrently restore each other's sink and one
/// of them captures nothing.
static DEFAULT_LOGGER_ERROR_SINK: std::sync::Mutex<()> = std::sync::Mutex::new(());
/// Run `body` with the default logger's error stream captured, restoring
/// the previous sink afterwards. Returns what `body` returned alongside
/// the captured bytes as UTF-8.
fn with_captured_default_error<T>(body: impl FnOnce() -> T) -> (T, String) {
let guard = DEFAULT_LOGGER_ERROR_SINK
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
let logger = crate::QPDFLogger::default_logger();
let captured = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
let restore = logger.get_error().unwrap();
logger.set_error(Some(crate::pipeline::PipelineHandle::new(
ErrorRecordingSink(std::sync::Arc::clone(&captured)),
)));
let result = body();
logger.set_error(Some(restore));
drop(guard);
let captured = String::from_utf8(captured.lock().unwrap().clone()).unwrap();
(result, captured)
}
#[test]
fn as_dictionary_on_a_non_dictionary_stays_silent_like_qpdf() {
// `asDictionary()` is the silent internal helper; only `getKey`,
// `getKeys` and `getDictAsMap` warn.
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
assert!(handle.try_as_dictionary().unwrap().is_none());
assert!(warnings(&recorder).is_empty());
}
#[test]
fn dictionary_accessors_warn_on_a_non_dictionary_receiver() {
// qpdf raises `typeWarning("dictionary", "returning null for
// attempted key retrieval")` here (`libqpdf/QPDFObjectHandle.cc:984`)
// and its receiver always has a context, because `QPDFParser` stamps
// the owning document on every value it creates
// (`libqpdf/QPDFParser.cc:416-442`). Both accessors now call
// `type_warning`, while the result shapes remain qpdf's null/empty
// fallbacks.
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
assert!(handle.try_get_key(b"/Type").unwrap().is_null());
assert!(handle.try_get_keys().unwrap().is_empty());
assert_eq!(
warnings(&recorder),
[
"object 3 0: operation for dictionary attempted on object of type integer: returning null for attempted key retrieval",
"object 3 0: operation for dictionary attempted on object of type integer: treating as empty",
]
);
}
#[test]
fn dictionary_accessors_neither_warn_nor_change_their_result() {
let (handle, recorder) = handle_resolving(ObjectValue::Dictionary(
[
(b"A".to_vec(), ObjectHandle::integer(1)),
(b"B".to_vec(), ObjectHandle::null()),
]
.into_iter()
.collect(),
));
assert_eq!(
handle.try_get_keys().unwrap(),
[b"/A".to_vec()].into_iter().collect::<BTreeSet<_>>()
);
assert_eq!(handle.try_get_key(b"/A").unwrap().as_integer(), Some(1));
assert!(handle.try_get_key(b"/Missing").unwrap().is_null());
assert!(warnings(&recorder).is_empty());
}
#[test]
fn get_int_value_on_a_non_integer_warns_and_returns_zero() {
// `libqpdf/QPDFObjectHandle.cc:503-513`
let (handle, recorder) = handle_resolving(ObjectValue::Name(b"Foo".to_vec()));
assert_eq!(handle.try_get_int_value().unwrap(), 0);
assert_eq!(
warnings(&recorder),
["object 3 0: operation for integer attempted on object of type name: returning 0"]
);
}
#[test]
fn an_integer_below_int_min_saturates_and_warns() {
// `libqpdf/QPDFObjectHandle.cc:528-532`
let (handle, recorder) = handle_resolving(ObjectValue::Integer(i64::from(i32::MIN) - 1));
assert_eq!(handle.try_get_int_value_as_int().unwrap(), i32::MIN);
assert_eq!(
warnings(&recorder),
["object 3 0: requested value of integer is too small; returning INT_MIN"]
);
}
#[test]
fn an_integer_above_int_max_saturates_and_warns() {
// `libqpdf/QPDFObjectHandle.cc:532-536`
let (handle, recorder) = handle_resolving(ObjectValue::Integer(i64::from(i32::MAX) + 1));
assert_eq!(handle.try_get_int_value_as_int().unwrap(), i32::MAX);
assert_eq!(
warnings(&recorder),
["object 3 0: requested value of integer is too big; returning INT_MAX"]
);
}
#[test]
fn integer_size_accessors_match_qpdf_test_62() {
// `qpdf/test_driver.cc:2263-2287` exercises the same values and
// conversions. Keep each handle separate so the warning sequence
// remains the sequence of calls made by qpdf's test.
let q1_l = 3_u64 * u64::from(u32::try_from(i32::MAX).unwrap());
let q1 = i64::try_from(q1_l).unwrap();
let (q1_handle, q1_recorder) = handle_resolving(ObjectValue::Integer(q1));
assert_eq!(q1_handle.try_get_int_value().unwrap(), q1);
assert_eq!(q1_handle.try_get_uint_value().unwrap(), q1_l);
assert_eq!(q1_handle.try_get_int_value_as_int().unwrap(), i32::MAX);
assert_eq!(q1_handle.try_get_uint_value_as_uint().unwrap(), u32::MAX);
assert_eq!(
warnings(&q1_recorder),
[
"object 3 0: requested value of integer is too big; returning INT_MAX",
"object 3 0: requested value of unsigned integer is too big; returning UINT_MAX",
]
);
let q2 = 3_i64 * i64::from(i32::MIN);
let (q2_handle, q2_recorder) = handle_resolving(ObjectValue::Integer(q2));
assert_eq!(q2_handle.try_get_int_value().unwrap(), q2);
assert_eq!(q2_handle.try_get_uint_value().unwrap(), 0);
assert_eq!(q2_handle.try_get_int_value_as_int().unwrap(), i32::MIN);
assert_eq!(q2_handle.try_get_uint_value_as_uint().unwrap(), 0);
assert_eq!(
warnings(&q2_recorder),
[
"object 3 0: unsigned value request for negative number; returning 0",
"object 3 0: requested value of integer is too small; returning INT_MIN",
"object 3 0: unsigned integer value request for negative number; returning 0",
]
);
let (q3_handle, q3_recorder) = handle_resolving(ObjectValue::Integer(i64::from(u32::MAX)));
assert_eq!(q3_handle.try_get_int_value_as_int().unwrap(), i32::MAX);
assert_eq!(q3_handle.try_get_uint_value_as_uint().unwrap(), u32::MAX);
assert_eq!(
warnings(&q3_recorder),
["object 3 0: requested value of integer is too big; returning INT_MAX"]
);
}
#[test]
fn the_int_endpoints_themselves_neither_saturate_nor_warn() {
// qpdf compares strictly (`v < INT_MIN`, `v > INT_MAX`), so the
// endpoints pass through unwarned.
for value in [i32::MIN, -1, 0, 7, i32::MAX] {
let (handle, recorder) = handle_resolving(ObjectValue::Integer(i64::from(value)));
assert_eq!(handle.try_get_int_value_as_int().unwrap(), value);
assert_eq!(handle.try_get_int_value().unwrap(), i64::from(value));
assert!(warnings(&recorder).is_empty(), "{value} warned");
}
}
#[test]
fn a_clamp_warnings_sink_failure_propagates_instead_of_the_saturated_value() {
// warn_if_possible's context branch calls through to the resolver's
// own `warn`, which can fail — the trait default does, exactly the
// case `a_resolver_without_a_warning_sink_reports_rather_than_swallows`
// pins for type_warning. try_get_int_value_as_int must not swallow
// that failure and hand back a saturated value as if nothing warned.
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(3, 0),
Rc::downgrade(&resolver),
);
handle.set_resolved(ObjectValue::Integer(i64::from(i32::MAX) + 1));
let error = handle.try_get_int_value_as_int().unwrap_err();
assert!(matches!(
error,
crate::Error::Internal(ref message)
if message.contains("returning INT_MAX")
));
}
#[test]
fn a_non_integer_reached_as_an_int_warns_once_for_the_type_and_not_for_range() {
// getIntValueAsInt delegates to getIntValue, whose 0 fallback is in
// range, so only the type warning is emitted.
let (handle, recorder) = handle_resolving(ObjectValue::Name(b"Foo".to_vec()));
assert_eq!(handle.try_get_int_value_as_int().unwrap(), 0);
assert_eq!(
warnings(&recorder),
["object 3 0: operation for integer attempted on object of type name: returning 0"]
);
}
/// A document that resolves but never implements a warning sink, so the
/// trait default decides what happens.
struct SinklessResolver;
impl DocumentResolver for SinklessResolver {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
handle: &ObjectHandle,
) -> crate::Result<()> {
handle.set_resolved(ObjectValue::Integer(7));
Ok(())
}
}
/// A document whose resolution always fails, so a warning path can be
/// asked whether it propagates that or misreports it as no context.
struct FailingResolver;
impl DocumentResolver for FailingResolver {
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
_handle: &ObjectHandle,
) -> crate::Result<()> {
Err(crate::Error::System("resolver failed".to_owned()))
}
}
#[test]
fn warn_if_possible_propagates_a_live_documents_resolution_failure() {
// A reachable document that cannot resolve is not qpdf's null
// context, so this must not silently divert to the default logger.
let resolver: Rc<dyn DocumentResolver> = Rc::new(FailingResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(3, 0),
Rc::downgrade(&resolver),
);
let error = handle.warn_if_possible("damage").unwrap_err();
assert!(matches!(
error,
crate::Error::System(ref message) if message == "resolver failed"
));
}
#[test]
fn a_stream_receiver_warns_under_its_own_type_name() {
// `asDictionary()` is null for a stream just as it is for a scalar
// (`libqpdf/QPDFObjectHandle.cc:999-1003`), so the dictionary
// accessors reach this warning with `stream` as the actual type.
let (handle, recorder) = handle_resolving(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![(
b"Length".to_vec(),
ObjectHandle::integer(0),
)]),
stream_data: None,
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
handle
.type_warning("dictionary", "treating as empty")
.unwrap();
assert_eq!(
warnings(&recorder),
["object 3 0: operation for dictionary attempted on object of type stream: treating as empty"]
);
}
#[test]
fn a_resolver_without_a_warning_sink_reports_rather_than_swallows() {
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
let handle = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(3, 0),
Rc::downgrade(&resolver),
);
let error = handle
.type_warning("dictionary", "treating as empty")
.unwrap_err();
assert!(matches!(
error,
crate::Error::Internal(ref message)
if message
== "warning raised through a resolver with no document warning sink: \
object 3 0: operation for dictionary attempted on object of type integer: \
treating as empty"
));
}
#[test]
fn warn_if_possible_treats_a_dropped_document_as_no_context() {
// `warnIfPossible`'s guard fails on a handle it cannot dereference
// and takes the logger branch rather than reporting
// (`libqpdf/QPDFObjectHandle.cc:2195-2200`).
let handle = {
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
ObjectHandle::new_indirect_with_resolver(ObjectRef::new(3, 0), Rc::downgrade(&resolver))
};
assert!(
handle.try_dereference().is_err(),
"the document is gone, so resolution fails"
);
let (result, captured) =
with_captured_default_error(|| handle.warn_if_possible("dropped document warning"));
result.unwrap();
assert!(
captured.contains("dropped document warning\n"),
"default error stream captured {captured:?}"
);
}
#[test]
fn warn_if_possible_without_a_context_logs_instead_of_failing() {
// The else-branch of `warnIfPossible` writes the bare message to
// `QPDFLogger::defaultLogger()->getError()` and returns normally
// (`libqpdf/QPDFObjectHandle.cc:2196-2200`).
let handle = {
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
ObjectHandle::new_indirect_with_resolver(ObjectRef::new(3, 0), Rc::downgrade(&resolver))
};
let (result, captured) = with_captured_default_error(|| {
handle.warn_if_possible("requested value of integer is too big; returning INT_MAX")
});
result.unwrap();
// Every document opened without an explicit logger shares this sink,
// so assert the exact line is present rather than that it is alone.
assert!(
captured.contains("requested value of integer is too big; returning INT_MAX\n"),
"default error stream captured {captured:?}"
);
assert!(
!captured.contains("object 3 0:"),
"contextless warn_if_possible must log bare warning without object description prefix"
);
}
#[test]
fn warn_if_possible_through_a_context_reaches_the_document_sink() {
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
handle
.warn_if_possible("requested value of integer is too small; returning INT_MIN")
.unwrap();
assert_eq!(
warnings(&recorder),
["object 3 0: requested value of integer is too small; returning INT_MIN"]
);
}
#[test]
fn object_warning_passes_its_message_through_without_dereferencing() {
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
handle.object_warning("unresolved name object").unwrap();
assert_eq!(warnings(&recorder), ["object 3 0: unresolved name object"]);
assert!(
!handle.is_resolved(),
"objectWarning does not dereference its receiver"
);
}
#[test]
fn object_warning_without_a_context_returns_the_error_qpdf_throws() {
let handle = ObjectHandle::integer(7);
let error = handle.object_warning("unresolved name object").unwrap_err();
assert!(matches!(
error,
crate::Error::QpdfExc(ref error) if error.get_message_detail() == b"unresolved name object"
));
}
#[test]
fn two_warnings_from_one_handle_reach_the_sink_in_emission_order() {
let (handle, recorder) = handle_resolving(ObjectValue::Integer(7));
handle
.type_warning("dictionary", "treating as empty")
.unwrap();
handle.type_warning("array", "treating as empty").unwrap();
assert_eq!(
warnings(&recorder),
[
"object 3 0: operation for dictionary attempted on object of type integer: treating as empty",
"object 3 0: operation for array attempted on object of type integer: treating as empty",
]
);
}
#[test]
fn parser_values_share_one_description_template_owner() {
let parsed =
ObjectHandle::parse_with_description(b"[1 [2] << /K 3 >>]", "shared template").unwrap();
let scalar = parsed.try_get_array_item(0).unwrap();
let nested_scalar = parsed
.try_get_array_item(1)
.unwrap()
.try_get_array_item(0)
.unwrap();
let dictionary_value = parsed
.try_get_array_item(2)
.unwrap()
.try_get_key(b"/K")
.unwrap();
let first = scalar.description_template_owner().unwrap();
let second = nested_scalar.description_template_owner().unwrap();
let third = dictionary_value.description_template_owner().unwrap();
assert!(Rc::ptr_eq(&first, &second));
assert!(Rc::ptr_eq(&first, &third));
assert_eq!(
scalar.description(),
b"parsed object, shared template at offset 1"
);
assert_eq!(
nested_scalar.description(),
b"parsed object, shared template at offset 4"
);
assert_eq!(
dictionary_value.description(),
b"parsed object, shared template at offset 13"
);
}
#[test]
fn object_description_template_placeholders_and_offset_shifts() {
let dict = ObjectHandle::dictionary(vec![]);
dict.set_description("object $OG at offset $PO", 100);
// `$OG` needs indirect identity; qpdf only ever installs that
// together with the owning document (`QPDFValue::setDefaultDescription`,
// `libqpdf/qpdf/QPDFValue.hh:66-71`), so promote through the same
// atomic primitive flpdf already uses for that pairing rather than
// writing `object_ref` alone.
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
dict.promote_to_indirect(ObjectRef::new(5, 0), 1, Rc::downgrade(&resolver));
assert_eq!(dict.description(), b"object 5 0 at offset 102");
let arr = ObjectHandle::array(vec![]);
arr.set_description("array at offset $PO", 200);
assert_eq!(arr.description(), b"array at offset 201");
let scalar = ObjectHandle::integer(42);
scalar.set_description("scalar at offset $PO", 300);
assert_eq!(scalar.description(), b"scalar at offset 300");
}
#[test]
fn object_description_template_uses_raw_qpdf_identity() {
let handle = ObjectHandle::integer(42);
handle.set_description("object $OG at offset $PO", 100);
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
handle.promote_to_indirect_qpdf_obj_gen(
QpdfObjGen::new(5, 65_536),
1,
Rc::downgrade(&resolver),
);
assert_eq!(handle.description(), b"object 5 65536 at offset 100");
}
#[test]
fn object_description_template_preserves_partial_and_unknown_markers() {
let cases = [
("$$", "$$"),
("$PX", "$PX"),
("$P", "$P"),
("$OX", "$OX"),
("$O", "$O"),
("$X", "$X"),
("trailing$", "trailing$"),
];
for (template, expected) in cases {
let handle = ObjectHandle::integer(7);
handle.set_description(template, 300);
assert_eq!(
handle.description(),
expected.as_bytes(),
"template {template:?}"
);
}
}
#[test]
fn object_description_template_replaces_each_qpdf_marker_only_once() {
let handle = ObjectHandle::dictionary(vec![]);
handle.set_description("$$/$PO/$PO/$OG/$OG", 100);
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
handle.promote_to_indirect(ObjectRef::new(5, 0), 1, Rc::downgrade(&resolver));
assert_eq!(handle.description(), b"$$/102/$PO/5 0/$OG");
}
#[test]
fn set_description_does_not_overwrite_an_already_recorded_parsed_offset() {
// Mirrors a parsed stream: `ObjectSlot::parsed_offset` already holds
// the encoded stream-data start `pipe_stream_data` reads from before
// any description is attached. `QPDFValue::setDescription` routes
// through the same set-once `setParsedOffset` guard every other
// caller uses (`libqpdf/qpdf/QPDFValue.hh:60-65,90-100`), so the
// operational offset must survive.
let stream = ObjectHandle::integer(7);
stream.set_parsed_offset_if_unset(500);
stream.set_description("stream object $OG at offset $PO", 999);
assert_eq!(stream.get_parsed_offset(), 500);
assert_eq!(stream.description(), b"stream object at offset 500");
}
#[test]
fn set_description_json_does_not_overwrite_an_already_recorded_parsed_offset() {
let stream = ObjectHandle::integer(7);
stream.set_parsed_offset_if_unset(500);
stream.set_description_json("input.pdf", "object 1 0", 999);
assert_eq!(stream.get_parsed_offset(), 500);
assert_eq!(stream.description(), b"input.pdf, object 1 0 at offset 500");
}
#[test]
fn description_template_ignores_non_template_descriptions() {
let without_description = ObjectHandle::integer(7);
assert_eq!(without_description.description_template(), None);
let json = ObjectHandle::null();
json.set_description_json("input.pdf", "object 1 0", 123);
assert_eq!(json.description_template(), None);
let parent = ObjectHandle::dictionary(vec![]);
let child = ObjectHandle::null();
child.set_child_description(&parent, " -> dictionary key $VD", "/Value");
assert_eq!(child.description_template(), None);
}
#[test]
fn object_description_child_chaining_and_var_descr() {
let parent = ObjectHandle::dictionary(vec![]);
parent.set_description("object 5 0 at offset 253", 253);
let child = ObjectHandle::null();
child.set_child_description(&parent, " -> dictionary key $VD", "/EF");
assert_eq!(
child.description(),
b"object 5 0 at offset 253 -> dictionary key /EF"
);
}
#[test]
fn object_description_child_replaces_only_the_first_qpdf_marker() {
let parent = ObjectHandle::dictionary(vec![]);
parent.set_description("parent $VD", 253);
let child = ObjectHandle::null();
child.set_child_description(&parent, " -> dictionary key $VD", "/EF");
assert_eq!(child.description(), b"parent /EF -> dictionary key $VD");
}
#[test]
fn object_description_indirect_fallback() {
let handle = ObjectHandle::new_indirect_unresolved(ObjectRef::new(12, 0), NO_PARSED_OFFSET);
assert_eq!(handle.description(), b"object 12 0");
}
#[test]
fn object_description_type_warning_includes_parent_and_object_path() {
let (parent, recorder) =
handle_resolving(ObjectValue::Dictionary(std::collections::BTreeMap::new()));
parent.set_description("object 5 0 at offset 253", 253);
let child = parent.try_get_key(b"/EF").unwrap();
child
.type_warning("dictionary", "treating as empty")
.unwrap();
assert_eq!(
warnings(&recorder),
["object 5 0 at offset 253 -> dictionary key /EF: operation for dictionary attempted on object of type null: treating as empty"]
);
}
#[test]
fn nested_missing_key_warning_keeps_the_qpdf_document_context() {
let (root, recorder) =
handle_resolving(ObjectValue::Dictionary(std::collections::BTreeMap::new()));
let pages = root.try_get_key(b"/Pages").unwrap();
let count = pages.try_get_key(b"/Count").unwrap();
assert_eq!(count.try_get_int_value().unwrap(), 0);
assert_eq!(
warnings(&recorder),
[
"object 3 0 -> dictionary key /Pages: operation for dictionary attempted on object of type null: returning null for attempted key retrieval",
"object 3 0 -> dictionary key /Pages -> null returned from getting key from non-Dictionary: operation for integer attempted on object of type null: returning 0",
]
);
}
#[test]
fn missing_key_warning_context_survives_parent_shared_value_replacement() {
let (parent, recorder) =
handle_resolving(ObjectValue::Dictionary(std::collections::BTreeMap::new()));
let missing = parent.try_get_key(b"/Missing").unwrap();
let replacement = ObjectHandle::dictionary(Vec::new());
parent.assign_value_state(&replacement);
drop(replacement);
assert_eq!(missing.try_get_int_value().unwrap(), 0);
assert_eq!(
warnings(&recorder),
[" -> dictionary key /Missing: operation for integer attempted on object of type null: returning 0"]
);
}
#[test]
fn context_terminates_on_a_reciprocal_child_description_cycle() {
let first = ObjectHandle::integer(1);
let second = ObjectHandle::integer(2);
first.set_child_description(&second, " -> first $VD", "/First");
second.set_child_description(&first, " -> second $VD", "/Second");
assert!(first.context().is_none());
}
#[test]
fn programmatic_non_null_child_does_not_borrow_containment_context() {
let (_, recorder) = handle_resolving(ObjectValue::Array(vec![]));
let child = ObjectHandle::integer(10);
assert!(child.context().is_none());
let (result, captured) =
with_captured_default_error(|| child.warn_if_possible("programmatic child warning"));
result.unwrap();
assert!(warnings(&recorder).is_empty());
assert!(captured.contains("programmatic child warning\n"));
}
#[test]
fn object_description_json_and_negative_offset_and_unresolved() {
let handle1 = ObjectHandle::null();
handle1.set_description_json("input.pdf", "", 123);
assert_eq!(handle1.description(), b"input.pdf at offset 123");
let handle2 = ObjectHandle::null();
handle2.set_description_json("input.pdf", "object 1 0", 456);
assert_eq!(
handle2.description(),
b"input.pdf, object 1 0 at offset 456"
);
let handle3 = ObjectHandle::null();
handle3.set_description("item at offset $PO", -1);
assert_eq!(handle3.description(), b"item at offset -1");
let resolver: Rc<dyn DocumentResolver> = Rc::new(SinklessResolver);
let handle4 = ObjectHandle::new_indirect_with_resolver(
ObjectRef::new(3, 0),
Rc::downgrade(&resolver),
);
handle4.set_description("unresolved at offset $PO", 50);
assert_eq!(handle4.description(), b"unresolved at offset 50");
}
#[test]
fn programmatic_non_null_child_keeps_a_contextless_type_warning_route() {
let (_, recorder) = handle_resolving(ObjectValue::Array(vec![]));
let child = ObjectHandle::integer(10);
let error = child
.type_warning("dictionary", "treating as empty")
.expect_err("qpdf does not lend a containment parent to a direct value");
assert!(matches!(
error,
crate::Error::QpdfExc(error)
if error.get_message_detail() == b"operation for dictionary attempted on object of type integer: treating as empty"
));
assert!(warnings(&recorder).is_empty());
}
#[test]
fn nested_lifted_nulls_keep_qpdfs_contextless_dictionary_contract() {
fn assert_contextless_dictionary_access(handle: ObjectHandle) {
let error = handle
.try_get_keys()
.expect_err("qpdf newNull has no owning document context");
assert!(matches!(
error,
crate::Error::QpdfExc(ref error)
if error.get_message_detail()
== b"operation for dictionary attempted on object of type null: treating as empty"
));
}
let (array, array_recorder) =
handle_resolving(ObjectValue::Array(vec![ObjectHandle::null()]));
let array_null = array
.try_array_item(0)
.unwrap()
.expect("array contains the lifted null");
assert_contextless_dictionary_access(array_null);
assert!(warnings(&array_recorder).is_empty());
let (dictionary, dictionary_recorder) = handle_resolving(ObjectValue::Dictionary(
[(b"/Null".to_vec(), ObjectHandle::null())]
.into_iter()
.collect(),
));
let dictionary_null = dictionary.try_get_key(b"/Null").unwrap();
assert_contextless_dictionary_access(dictionary_null);
assert!(warnings(&dictionary_recorder).is_empty());
let contextless_dictionary = ObjectHandle::dictionary(vec![]);
let missing_key_null = contextless_dictionary.try_get_key(b"/Missing").unwrap();
let error = missing_key_null
.try_get_keys()
.expect_err("qpdf missing-key null has no context without a document");
assert!(matches!(
error,
crate::Error::QpdfExc(ref error)
if error.get_message_detail()
== b"operation for dictionary attempted on object of type null: treating as empty"
));
let (stream, stream_recorder) =
handle_resolving(ObjectValue::Stream(Box::new(StreamValue {
stream_dict: ObjectHandle::dictionary(vec![(
b"/Null".to_vec(),
ObjectHandle::null(),
)]),
stream_data: Some(Rc::new(Vec::new())),
stream_provider: None,
filter_on_write: true,
stream_token_filters: Default::default(),
content_normalization_applied: false,
stream_length: 0,
})));
stream.try_dereference().unwrap();
let stream_null = stream
.as_stream_dict()
.expect("stream has a dictionary")
.try_get_key(b"/Null")
.unwrap();
assert_contextless_dictionary_access(stream_null);
assert!(warnings(&stream_recorder).is_empty());
let (non_null, non_null_recorder) =
handle_resolving(ObjectValue::Array(vec![ObjectHandle::integer(7)]));
let non_null_child = non_null
.try_array_item(0)
.unwrap()
.expect("array contains the integer");
let error = non_null_child
.try_get_keys()
.expect_err("a programmatic direct child must remain contextless");
assert!(matches!(
error,
crate::Error::QpdfExc(error)
if error.get_message_detail() == b"operation for dictionary attempted on object of type integer: treating as empty"
));
assert!(non_null_child.context().is_none());
assert!(warnings(&non_null_recorder).is_empty());
}
#[test]
fn dictionary_accessors_keep_a_programmatic_direct_child_contextless() {
let (_, recorder) = handle_resolving(ObjectValue::Array(vec![]));
let child = ObjectHandle::integer(10);
let error = child
.try_get_keys()
.expect_err("qpdf typeWarning must stay on the contextless route");
assert!(matches!(
error,
crate::Error::QpdfExc(error)
if error.get_message_detail() == b"operation for dictionary attempted on object of type integer: treating as empty"
));
assert!(warnings(&recorder).is_empty());
}
#[test]
fn warn_if_possible_through_a_programmatic_child_uses_the_default_logger() {
// A direct value inserted into a qpdf container has no owning QPDF, so
// `warnIfPossible` must use the process-global default error logger
// (`libqpdf/QPDFObjectHandle.cc:2196-2199`) rather than a containment
// parent that was never assigned to the value.
let (_, recorder) = handle_resolving(ObjectValue::Array(vec![]));
let child = ObjectHandle::integer(10);
let (result, captured) =
with_captured_default_error(|| child.warn_if_possible("treating as empty"));
result.unwrap();
assert!(warnings(&recorder).is_empty());
assert!(captured.contains("treating as empty\n"));
}
#[test]
fn try_get_key_without_leading_slash_formats_key() {
let parent = ObjectHandle::dictionary(vec![]);
let child = parent.try_get_key(b"/NoSlash").unwrap();
assert_eq!(child.description(), b" -> dictionary key /NoSlash");
}
#[test]
fn try_get_key_with_leading_slash_formats_key() {
let parent = ObjectHandle::dictionary(vec![]);
let child = parent.try_get_key(b"/EF").unwrap();
assert_eq!(child.description(), b" -> dictionary key /EF");
}
#[test]
fn try_get_key_preserves_non_utf8_key_bytes_in_the_child_description() {
let parent = ObjectHandle::dictionary(vec![]);
let child = parent.try_get_key(b"/\xff").unwrap();
assert_eq!(child.description(), b" -> dictionary key /\xff");
}
}
#[cfg(test)]
mod qpdf_mutator_api_tests {
use super::*;
#[test]
fn and_get_dictionary_mutators_preserve_qpdf_order_and_identity() {
let dict = ObjectHandle::dictionary(vec![]);
let alias = dict.clone();
let inserted = dict
.replace_key_and_get_new(b"/Three", ObjectHandle::array(vec![]))
.expect("replaceKeyAndGetNew should insert into a dictionary");
assert!(inserted.is_same_object_as(&dict.try_get_key(b"/Three").unwrap()));
let old = dict
.replace_key_and_get_old(b"/Three", ObjectHandle::integer(3))
.expect("replaceKeyAndGetOld should replace a dictionary key");
assert!(old.is_same_object_as(&inserted));
assert_eq!(alias.try_get_key(b"/Three").unwrap().as_integer(), Some(3));
let missing = dict
.remove_key_and_get_old(b"/Missing")
.expect("removeKeyAndGetOld should return a null for a missing key");
assert!(missing.is_null());
let removed = dict
.remove_key_and_get_old(b"/Three")
.expect("removeKeyAndGetOld should return the existing value");
assert_eq!(removed.as_integer(), Some(3));
assert!(dict.try_get_key(b"/Three").unwrap().is_null());
}
#[test]
fn and_get_dictionary_mutators_keep_qpdf_type_warning_boundaries() {
let (handle, recorder) = warning_emission_tests::handle_resolving(ObjectValue::Integer(7));
let returned = handle
.replace_key_and_get_new(b"/Ignored", ObjectHandle::integer(1))
.expect("a contextful qpdf type warning is recoverable");
assert_eq!(returned.as_integer(), Some(1));
let old = handle
.remove_key_and_get_old(b"/Ignored")
.expect("removeKeyAndGetOld should return null after its warning");
assert!(old.is_null());
assert_eq!(
warning_emission_tests::warnings(&recorder),
[
"object 3 0: operation for dictionary attempted on object of type integer: ignoring key replacement request",
"object 3 0: operation for dictionary attempted on object of type integer: ignoring key removal request",
]
);
}
#[test]
fn set_object_description_routes_array_warning_through_the_document() {
let pdf = crate::Pdf::empty().expect("empty PDF should be constructible");
let array = ObjectHandle::array(vec![]);
array
.set_object_description(&pdf, "test array")
.expect("live document context should be attachable");
let erased = array
.erase_array_item_and_get_old(50)
.expect("qpdf reports an out-of-bounds erase as a warning");
assert!(erased.is_null());
assert_eq!(
pdf.repair_diagnostics()
.entries()
.iter()
.map(|diagnostic| String::from_utf8_lossy(diagnostic.what_bytes()).into_owned())
.collect::<Vec<_>>(),
["test array: ignoring attempt to erase out of bounds array item"]
);
}
}
#[cfg(test)]
mod filter_on_write_tests {
use super::*;
use std::rc::Rc;
#[test]
fn non_stream_values_do_not_carry_stream_normalization_state() {
let value = ObjectHandle::integer(7);
value.mark_content_normalization_applied();
assert!(
!value.content_normalization_applied(),
"stream normalization state must not be stored on a scalar value"
);
}
#[test]
fn filter_on_write_defaults_true_and_is_shared_by_aliases() {
let stream =
ObjectHandle::stream(ObjectHandle::dictionary(Vec::new()), Rc::new(Vec::new()));
let alias = stream.clone();
assert!(
stream
.get_filter_on_write()
.expect("stream getter should succeed"),
"qpdf streams enable filtering by default"
);
stream
.set_filter_on_write(false)
.expect("stream setter should succeed");
assert!(!alias
.get_filter_on_write()
.expect("alias getter should succeed"));
alias
.set_filter_on_write(true)
.expect("alias setter should succeed");
assert!(stream
.get_filter_on_write()
.expect("stream getter should observe alias mutation"));
}
#[test]
fn filter_on_write_accessors_reject_non_stream_values() {
let value = ObjectHandle::integer(7);
assert!(matches!(
value.set_filter_on_write(false),
Err(crate::Error::System(message))
if message == "operation for stream attempted on object of type integer"
));
assert!(matches!(
value.get_filter_on_write(),
Err(crate::Error::System(message))
if message == "operation for stream attempted on object of type integer"
));
}
}
#[cfg(test)]
mod drop_tests {
use super::*;
use std::process::Command;
use std::rc::Rc;
const DEEP_DROP_DEPTH: usize = 100_000;
fn assert_drop_probe_succeeds(test_name: &str, environment: &str) {
let output = Command::new(std::env::current_exe().unwrap())
.args(["--exact", test_name, "--ignored", "--nocapture"])
.env(environment, "1")
.output()
.unwrap();
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(
output.status.success(),
"drop probe failed: status={} stderr={}",
output.status,
stderr
);
}
#[test]
fn deep_direct_array_drop_is_stack_independent() {
assert_drop_probe_succeeds(
"object_handle::drop_tests::deep_direct_array_drop_probe",
"FLPDF_DEEP_DIRECT_ARRAY_DROP_PROBE",
);
}
#[test]
#[ignore = "subprocess-only stack-overflow regression probe"]
fn deep_direct_array_drop_probe() {
assert_eq!(
std::env::var_os("FLPDF_DEEP_DIRECT_ARRAY_DROP_PROBE").as_deref(),
Some(std::ffi::OsStr::new("1"))
);
let mut handle = ObjectHandle::integer(0);
for _ in 0..DEEP_DROP_DEPTH {
handle = ObjectHandle::array(vec![handle]);
}
drop(handle);
}
#[test]
fn deep_direct_disconnect_is_stack_independent() {
assert_drop_probe_succeeds(
"object_handle::drop_tests::deep_direct_disconnect_probe",
"FLPDF_DEEP_DIRECT_DISCONNECT_PROBE",
);
}
/// `disconnect` walks the same direct graph `Drop` does, so it owes the
/// same stack independence: qpdf's teardown reaches every direct child
/// (`QPDF_Dictionary.cc:50-56`, `QPDF_Array.cc:103-118`) and this module
/// pins the depth contract at `DEEP_DROP_DEPTH`.
#[test]
#[ignore = "subprocess-only stack-overflow regression probe"]
fn deep_direct_disconnect_probe() {
assert_eq!(
std::env::var_os("FLPDF_DEEP_DIRECT_DISCONNECT_PROBE").as_deref(),
Some(std::ffi::OsStr::new("1"))
);
let mut handle = ObjectHandle::integer(0);
for _ in 0..DEEP_DROP_DEPTH {
handle = ObjectHandle::array(vec![handle]);
}
handle.disconnect();
drop(handle);
}
/// A direct DAG: every level holds the same child twice. Walking once per
/// path would visit 2^depth nodes, so a visited set that only tracks the
/// active path turns a 28-level graph into hundreds of millions of visits.
/// Recording every allocation reached keeps this linear.
#[test]
fn direct_dag_disconnect_visits_each_node_once() {
let mut handle = ObjectHandle::integer(0);
for _ in 0..28 {
handle = ObjectHandle::array(vec![handle.clone(), handle]);
}
let start = std::time::Instant::now();
handle.disconnect();
assert!(
start.elapsed() < std::time::Duration::from_secs(5),
"disconnect must not walk a direct DAG once per path"
);
}
#[test]
fn disconnect_does_not_materialize_a_child_vector_for_each_node() {
let child = ObjectHandle::array(vec![ObjectHandle::integer(1), ObjectHandle::integer(2)]);
let root = ObjectHandle::dictionary(vec![(b"/Child".to_vec(), child)]);
super::STATE_CHILDREN_VECTOR_CALLS.with(|calls| calls.set(0));
root.disconnect();
assert_eq!(
super::STATE_CHILDREN_VECTOR_CALLS.with(std::cell::Cell::get),
0,
"disconnect must append direct children to its existing worklist"
);
}
/// `append_direct_children` must skip indirect children in every arm.
///
/// qpdf does not filter inside `QPDF_Dictionary::disconnect` or
/// `QPDF_Stream::disconnect` — both hand every child to
/// `QPDFObjectHandle::disconnect`, which drops the indirect ones itself with
/// `if (obj && !isIndirect())` (`QPDFObjectHandle.cc:230-238`).
/// `QPDF_Array::disconnect` does test `isIndirect()` inline
/// (`QPDF_Array.cc:104-119`), so the net effect is the same for all three:
/// an indirect child is never walked, because `QPDF::~QPDF` reaches those
/// through `obj_cache` instead (`QPDF.cc:229-235`).
///
/// Without this, only the Array arm's filter was covered: removing the
/// Stream arm's `if !stream.stream_dict.is_indirect()` left the whole
/// `object_handle` suite green.
#[test]
fn append_direct_children_skips_indirect_children_in_every_arm() {
// Only `promote_to_indirect` needs a resolver here; nothing in this test
// dereferences the promoted handles, so the method is never entered.
struct NeverResolves;
impl DocumentResolver for NeverResolves {
// cov:ignore-start: the promoted handles are only inspected with
// `is_indirect`, which never resolves.
fn resolve_indirect(
&self,
_object_ref: ObjectRef,
_handle: &ObjectHandle,
) -> Result<()> {
unreachable!("append_direct_children must not resolve a child")
}
// cov:ignore-end
}
fn indirect(number: u32) -> (ObjectHandle, Rc<dyn DocumentResolver>) {
let handle = ObjectHandle::integer(i64::from(number));
let resolver: Rc<dyn DocumentResolver> = Rc::new(NeverResolves);
handle.promote_to_indirect(
ObjectRef::new(number, 0),
u64::from(number),
Rc::downgrade(&resolver),
);
// The resolver must outlive the handle for the promotion to stick.
(handle, resolver)
}
let (array_child, _a) = indirect(11);
let (dict_child, _d) = indirect(12);
let (stream_dict, _s) = indirect(13);
let cases: [(&str, ObjectValue); 3] = [
(
"array",
ObjectValue::Array(vec![ObjectHandle::integer(1), array_child]),
),
(
"dictionary",
ObjectHandle::dictionary(vec![(b"/Indirect".to_vec(), dict_child)])
.with_value(|value| value.cloned())
.expect("dictionary value"),
),
(
"stream",
ObjectHandle::stream(stream_dict, Rc::new(Vec::new()))
.with_value(|value| value.cloned())
.expect("stream value"),
),
];
for (label, value) in cases {
let mut pending = Vec::new();
ObjectHandle::append_direct_children(&value, &mut pending);
assert!(
pending.iter().all(|child| !child.is_indirect()),
"{label} arm must not queue an indirect child for teardown"
);
}
}
#[test]
fn deep_direct_dictionary_drop_is_stack_independent() {
assert_drop_probe_succeeds(
"object_handle::drop_tests::deep_direct_dictionary_drop_probe",
"FLPDF_DEEP_DIRECT_DICTIONARY_DROP_PROBE",
);
}
#[test]
#[ignore = "subprocess-only stack-overflow regression probe"]
fn deep_direct_dictionary_drop_probe() {
assert_eq!(
std::env::var_os("FLPDF_DEEP_DIRECT_DICTIONARY_DROP_PROBE").as_deref(),
Some(std::ffi::OsStr::new("1"))
);
let mut handle = ObjectHandle::integer(0);
for _ in 0..DEEP_DROP_DEPTH {
handle = ObjectHandle::dictionary(vec![(b"/Next".to_vec(), handle)]);
}
drop(handle);
}
#[test]
fn deep_direct_stream_dictionary_drop_is_stack_independent() {
assert_drop_probe_succeeds(
"object_handle::drop_tests::deep_direct_stream_dictionary_drop_probe",
"FLPDF_DEEP_DIRECT_STREAM_DROP_PROBE",
);
}
#[test]
#[ignore = "subprocess-only stack-overflow regression probe"]
fn deep_direct_stream_dictionary_drop_probe() {
assert_eq!(
std::env::var_os("FLPDF_DEEP_DIRECT_STREAM_DROP_PROBE").as_deref(),
Some(std::ffi::OsStr::new("1"))
);
let data = Rc::new(Vec::new());
let mut handle = ObjectHandle::integer(0);
for _ in 0..DEEP_DROP_DEPTH {
let dictionary = ObjectHandle::dictionary(vec![(b"/Next".to_vec(), handle)]);
handle = ObjectHandle::stream(dictionary, Rc::clone(&data));
}
drop(handle);
assert_eq!(Rc::strong_count(&data), 1);
}
#[test]
fn dropping_a_parent_does_not_dismantle_a_shared_child_alias() {
let child = ObjectHandle::dictionary(vec![(b"/Value".to_vec(), ObjectHandle::integer(7))]);
let alias = child.clone();
let parent = ObjectHandle::array(vec![child]);
drop(parent);
assert_eq!(alias.try_get_key(b"/Value").unwrap().as_integer(), Some(7));
assert!(alias.containing_object_refs().is_empty());
drop(alias);
}
#[test]
fn an_identity_key_can_be_the_last_owner_of_a_direct_container() {
let root_ref = ObjectRef::new(12, 0);
let leaf = ObjectHandle::integer(3);
let root = ObjectHandle::new_indirect_unresolved(root_ref, -1);
root.set_resolved(ObjectValue::Array(vec![leaf.clone()]));
let identity = root.identity_key();
drop(root);
assert_eq!(leaf.containing_object_refs(), vec![root_ref]);
drop(identity);
assert!(leaf.containing_object_refs().is_empty());
}
}
#[cfg(test)]
mod direct_graph_walk_bound_tests {
use super::*;
// Two direct dictionaries holding each other: `a` under `/B` holds `b`,
// and `b` under `/A` holds `a`. Neither handle is indirect, so no walk
// ever meets the indirect boundary that normally terminates a descent.
// `replace_key` refuses only the single-hop self-insert, so this two-hop
// shape does close into a real cycle -- asserted here so the walk
// assertions below cannot pass against an unaliased pair.
fn reciprocal_direct_dictionary_cycle() -> Result<ObjectHandle> {
let a = ObjectHandle::dictionary(vec![]);
let b = ObjectHandle::dictionary(vec![]);
a.replace_key(b"/B", b.clone())?;
b.replace_key(b"/A", a.clone())?;
assert!(
a.try_get_key(b"/B")?
.try_get_key(b"/A")?
.is_same_object_as(&a),
"the reciprocal replace_key pair must close into a direct cycle"
);
Ok(a)
}
// `n` nested direct dictionaries around a scalar leaf. Both walkers in
// this family re-enter the hub for a direct scalar child as well
// (`shallow_copy_child` and `unparse_resolved_child` recurse for every
// non-indirect child), so the hub depth reached spans the whole chain,
// leaf included.
fn nested_direct_dictionaries(n: usize) -> ObjectHandle {
let mut handle = ObjectHandle::integer(1);
for _ in 0..n {
handle = ObjectHandle::dictionary(vec![(b"/K".to_vec(), handle)]);
}
handle
}
#[test]
fn direct_dictionary_cycle_is_rejected_by_the_direct_graph_walk_family() -> Result<()> {
let cycle = reciprocal_direct_dictionary_cycle()?;
let copied = cycle
.shallow_copy()
.expect_err("a direct cycle must not be walked by the shallow-copy hub");
assert!(
matches!(copied, Error::Unsupported(_)),
"unexpected error kind: {copied:?}"
);
assert!(
copied
.to_string()
.contains("direct object nesting exceeds maximum of"),
"unexpected message: {copied}"
);
let unparsed = cycle
.try_unparse_resolved()
.expect_err("a direct cycle must not be walked by the unparse hub");
assert!(
matches!(unparsed, Error::Unsupported(_)),
"unexpected error kind: {unparsed:?}"
);
assert!(
unparsed
.to_string()
.contains("direct object nesting exceeds maximum of"),
"unexpected message: {unparsed}"
);
// The non-fallible facade keeps its established null fallback for
// the refused walk instead of exhausting memory.
assert_eq!(cycle.unparse_resolved(), b"null".to_vec());
// `make_direct` stays outside the hub because it recurses through
// indirect boundaries; its own visited set already refuses the same
// shape, with qpdf's loop message rather than the nesting bound.
let mut direct = cycle.clone();
let loop_error = direct
.make_direct(false)
.expect_err("the visited set must still refuse a direct cycle");
assert!(
matches!(
&loop_error,
Error::System(message)
if message == "loop detected while converting object from indirect to direct"
),
"unexpected error: {loop_error:?}"
);
// Every rejected level restores the shared counter on its way out,
// so a later walk starts from zero instead of inheriting the
// exhausted budget of the refused one.
assert_eq!(DIRECT_GRAPH_WALK_DEPTH.with(std::cell::Cell::get), 0);
let deep = nested_direct_dictionaries(crate::parser::MAX_PARSE_DEPTH);
assert_eq!(
String::from_utf8_lossy(&deep.try_unparse_resolved()?)
.matches("/K")
.count(),
crate::parser::MAX_PARSE_DEPTH
);
Ok(())
}
#[test]
fn acyclic_direct_nesting_is_bounded_at_the_parser_limit() -> Result<()> {
let bound = crate::parser::MAX_PARSE_DEPTH;
let within_bound = nested_direct_dictionaries(bound);
assert_eq!(
String::from_utf8_lossy(&within_bound.try_unparse_resolved()?)
.matches("/K")
.count(),
bound,
"every level within the bound must still be serialized"
);
assert_eq!(
String::from_utf8_lossy(&within_bound.shallow_copy()?.try_unparse_resolved()?)
.matches("/K")
.count(),
bound,
"every level within the bound must still be copied"
);
let past_bound = nested_direct_dictionaries(bound + 1);
let unparse_error = past_bound
.try_unparse_resolved()
.expect_err("nesting past the bound must be reported by the unparse hub");
assert!(matches!(unparse_error, Error::Unsupported(_)));
assert_eq!(
unparse_error.to_string(),
format!(
"unsupported PDF feature: object handle: direct object nesting exceeds maximum of {bound}"
)
);
let copy_error = past_bound
.shallow_copy()
.expect_err("nesting past the bound must be reported by the shallow-copy hub");
assert!(matches!(copy_error, Error::Unsupported(_)));
assert_eq!(
copy_error.to_string(),
format!(
"unsupported PDF feature: object handle: direct object nesting exceeds maximum of {bound}"
)
);
Ok(())
}
}