flpdf 0.8.0

A pure-Rust PDF toolkit modeled on qpdf — read, rewrite, linearize, and inspect PDFs.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
//! Content-stream object callbacks (ISO 32000-1 §7.8.2).
//!
//! qpdf correspondence: `QPDFObjectHandle::ParserCallbacks` and `QPDFParser::warn` content boundary.
//!
//! A PDF content stream is a sequence of operands followed by an operator,
//! interleaved with inline images and comments. This module routes the shared
//! tokenizer and [`crate::parser`] through qpdf-shaped
//! [`ObjectHandleParserCallbacks`]. It contains orchestration and event accumulation only;
//! lexical boundaries remain owned by the tokenizer.
//!
//! [`parse_content_operations`] provides the common operand/operator adapter
//! for consumers that do not need inline-image payload events.
//!
//! When parsing a document-owned handle, recoverable tokenizer/parser
//! diagnostics are delivered through the owning `DocumentResolver`. This
//! mirrors qpdf's `QPDFObjectHandle::warn` path. Detached parses have no qpdf
//! warning sink, so the first recoverable diagnostic is returned as the
//! corresponding `QPDFExc` error.

use crate::parser::{parse_live_content_stream_object, ContentHandleResolver, SliceLiveInput};
use crate::tokenizer::{TokenType, Tokenizer, TokenizerStateError};
use crate::{
    object_handle::{DocumentResolver, ObjectHandle},
    Error, QpdfErrorCode, QpdfExc, Result,
};
use std::{cell::RefCell, rc::Rc};

/// Whether content-stream parsing should continue after an object callback.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ParseControl {
    /// Continue parsing the content stream.
    Continue,
    /// Stop immediately without calling [`ObjectHandleParserCallbacks::handle_eof`].
    Stop,
}

/// Receive objects parsed from a content stream, one at a time.
///
/// Parsed values are canonical [`ObjectHandle`]s, so callback code
/// can inspect identity and parsed offsets without introducing an
/// ObjectHandle-to-Object consumer bridge.
///
/// qpdf correspondence: `QPDFObjectHandle::ParserCallbacks`
/// (`include/qpdf/QPDFObjectHandle.hh:204-226`).
pub trait ObjectHandleParserCallbacks {
    /// Receive the full decoded content size before the first object.
    fn content_size(&mut self, _size: usize) -> Result<()> {
        Ok(())
    }

    /// Receive one parsed ObjectHandle and its qpdf content span.
    fn handle_object(
        &mut self,
        object: ObjectHandle,
        offset: usize,
        length: usize,
    ) -> Result<ParseControl>;

    /// Receive normal content EOF. A [`ParseControl::Stop`] return from
    /// `handle_object` skips this callback, matching qpdf's
    /// `terminateParsing` path.
    fn handle_eof(&mut self) -> Result<()>;
}

fn deliver_diagnostic(
    context: Option<&Rc<dyn DocumentResolver>>,
    source_description: &str,
    object_description: &str,
    offset: usize,
    message: &[u8],
) -> Result<()> {
    let warning = QpdfExc::new(
        QpdfErrorCode::DamagedPdf,
        source_description.as_bytes(),
        object_description.as_bytes(),
        i64::try_from(offset).unwrap_or(i64::MAX),
        message,
    );
    if let Some(context) = context {
        context.warn(warning)?;
        Ok(())
    } else {
        Err(Error::QpdfExc(warning))
    }
}

/// Parse an in-memory fragment with qpdf's warning-and-continue context.
///
/// qpdf's tolerant content consumers always parse through a document-owned
/// `QPDF`, even when the bytes are an in-memory fragment. This internal route
/// supplies only that warning boundary; the public detached route above still
/// throws when no context exists.
pub(crate) fn parse_content_stream_handles_with_recoverable_warnings<
    C: ObjectHandleParserCallbacks,
>(
    input: &[u8],
    source_description: &str,
    callbacks: &mut C,
) -> Result<()> {
    parse_content_stream_handles_with_recoverable_warnings_and_status(
        input,
        source_description,
        callbacks,
    )
    .map(|_| ())
}

/// Parse through a synthetic warning sink and report whether a container EOF
/// stopped the scan. Detached ResourceReplacer callers retain their historical
/// structural-failure fallback, while document-owned callers use the qpdf
/// warning-and-EOF path directly.
pub(crate) fn parse_content_stream_handles_with_recoverable_warnings_and_status<
    C: ObjectHandleParserCallbacks,
>(
    input: &[u8],
    source_description: &str,
    callbacks: &mut C,
) -> Result<bool> {
    let context: Rc<dyn DocumentResolver> = Rc::new(RecoverableWarningResolver::default());
    parse_content_stream_handles_internal(input, Some(context), source_description, callbacks)
}

/// Parse decoded content bytes into ObjectHandle callbacks.
pub(crate) fn parse_content_stream_handles<C: ObjectHandleParserCallbacks>(
    input: &[u8],
    context: Option<Rc<dyn DocumentResolver>>,
    source_description: &str,
    callbacks: &mut C,
) -> Result<()> {
    parse_content_stream_handles_internal(input, context, source_description, callbacks).map(|_| ())
}

fn parse_content_stream_handles_internal<C: ObjectHandleParserCallbacks>(
    input: &[u8],
    context: Option<Rc<dyn DocumentResolver>>,
    source_description: &str,
    callbacks: &mut C,
) -> Result<bool> {
    callbacks.content_size(input.len())?;

    let mut tokenizer = Tokenizer::new(input);
    tokenizer.allow_eof();
    // A parallel, canonical `LiveInput` over the same bytes: content-stream
    // objects share `LiveFileParser`'s parser (`QPDFParser`'s own
    // `content_stream=true` mode, `parse_live_content_stream_object`), which
    // is driven by `LiveInput` rather than this module's own pull tokenizer.
    // The pull tokenizer above stays only for the probe/inline-image steps
    // below, which have no `LiveInput` equivalent; the two positions are
    // resynchronized at each loop boundary.
    let mut live_input = SliceLiveInput::new(input);
    let mut stopped_on_container_eof = false;

    while tokenizer.position() < input.len() {
        let probe = tokenizer.read_token(true, 0)?;
        let offset = probe.start;
        tokenizer.set_position(offset)?;
        live_input.seek_to(offset)?;

        let (object, length, diagnostics) = {
            let mut resolver = ContentHandleResolver::new(context.clone());
            let parsed = parse_live_content_stream_object(&mut live_input, &mut resolver)?;
            let length = live_input.position() - offset;
            (parsed.value, length, parsed.diagnostics)
        };
        tokenizer.set_position(live_input.position())?;
        for diagnostic in diagnostics {
            if diagnostic.message == b"parse error while reading object" {
                stopped_on_container_eof = true;
            }
            deliver_diagnostic(
                context.as_ref(),
                source_description,
                "content",
                diagnostic.relative_offset,
                &diagnostic.message,
            )?; // cov:ignore: LLVM attributes this successful diagnostic-delivery terminator to the fallible error edge.
        }
        if !object.is_initialized() {
            break;
        }
        let is_id = object.as_operator().as_deref() == Some(b"ID");

        if callbacks.handle_object(object, offset, length)? == ParseControl::Stop {
            return Ok(false);
        }

        if is_id {
            // qpdf discards the byte after ID without making a short read an
            // exception; the subsequent inline-image token read reports the
            // warning-only EOF case (QPDFObjectHandle.cc:1820-1848).
            if tokenizer.consume_one_byte().is_err() {
                deliver_diagnostic(
                    context.as_ref(),
                    source_description,
                    "stream data",
                    input.len(),
                    b"EOF found while reading inline image",
                )?;
                break;
            }
            let inline_offset = tokenizer.position();
            // The shared tokenizer is reset by consume_one_byte, so this
            // state failure is unreachable through this pull route. Keep the
            // defensive mapping documented for callers that change tokenizer
            // state handling.
            // cov:ignore-start: consume_one_byte resets the shared tokenizer; qpdf state errors are unreachable here
            tokenizer.expect_inline_image().map_err(|error| {
                let message = match error {
                    TokenizerStateError::TokenWaiting => "tokenizer already has a token waiting",
                    TokenizerStateError::ImproperInlineImageState => {
                        "tokenizer is in an improper inline image state"
                    }
                };
                Error::parse(inline_offset, message)
            })?;
            // cov:ignore-end
            let image = tokenizer.read_token(true, 0)?;
            if image.token_type == TokenType::Bad {
                // QPDFObjectHandle::parseContentStream_data warns and lets the
                // surrounding parseContentStream_internal deliver handleEOF;
                // an incomplete inline image is not a parser exception on this
                // owning ObjectHandle route (QPDFObjectHandle.cc:1826-1848).
                let diagnostic = "EOF found while reading inline image";
                deliver_diagnostic(
                    context.as_ref(),
                    source_description,
                    "stream data",
                    image.end,
                    diagnostic.as_bytes(),
                )?; // cov:ignore: LLVM attributes this successful diagnostic-delivery terminator to the fallible error edge.
                break;
            }
            let image_offset = image.start;
            let image_length = image.end - image.start;
            if callbacks.handle_object(
                ObjectHandle::inline_image(image.value),
                image_offset,
                image_length,
            )? == ParseControl::Stop
            {
                return Ok(false);
            }
        }
    }

    callbacks.handle_eof()?;
    Ok(stopped_on_container_eof)
}

#[derive(Default)]
struct RecoverableWarningResolver {
    warnings: RefCell<Vec<QpdfExc>>,
}

impl DocumentResolver for RecoverableWarningResolver {
    fn resolve_indirect(
        &self,
        _object_ref: crate::ObjectRef,
        _handle: &ObjectHandle,
    ) -> Result<()> {
        Err(Error::Internal(
            "indirect resolution requested from an in-memory content warning sink".to_owned(),
        ))
    }

    fn warn(&self, warning: QpdfExc) -> Result<()> {
        self.warnings.borrow_mut().push(warning);
        Ok(())
    }
}

/// Accumulates content objects until an operator event is received.
///
/// This adapter deliberately sees only parser events. Lexical boundaries and
/// inline-image discovery remain owned by [`parse_content_stream_handles`].
pub(crate) struct OperationCallbacks<F> {
    operands: Vec<ObjectHandle>,
    on_operation: F,
}

pub(crate) fn parse_content_operations_with_recoverable_warnings<F>(
    input: &[u8],
    on_operation: F,
) -> Result<()>
where
    F: FnMut(&[ObjectHandle], &[u8]) -> Result<ParseControl>,
{
    let mut callbacks = OperationCallbacks {
        operands: Vec::new(),
        on_operation,
    };
    parse_content_stream_handles_with_recoverable_warnings(input, "", &mut callbacks)
}

impl<F> ObjectHandleParserCallbacks for OperationCallbacks<F>
where
    F: FnMut(&[ObjectHandle], &[u8]) -> Result<ParseControl>,
{
    fn handle_object(
        &mut self,
        object: ObjectHandle,
        _offset: usize,
        _length: usize,
    ) -> Result<ParseControl> {
        if let Some(operator) = object.as_operator() {
            let control = (self.on_operation)(&self.operands, &operator)?;
            self.operands.clear();
            Ok(control)
        } else if object.as_inline_image().is_some() {
            Ok(ParseControl::Continue)
        } else {
            self.operands.push(object);
            Ok(ParseControl::Continue)
        }
    }

    fn handle_eof(&mut self) -> Result<()> {
        Ok(())
    }
}

/// Parse content and invoke `on_operation` with each operator's accumulated
/// operands.
///
/// Inline-image payload events are ignored by this convenience adapter.
/// Consumers that need inline-image headers or payloads should implement
/// [`ObjectHandleParserCallbacks`] directly.
///
/// # Errors
///
/// Recoverable object-token errors use qpdf's document warning sink when the
/// content belongs to a document, and become `Error::System` values carrying
/// qpdf's formatted `QPDFExc::what()` for detached parsing. Inline-image/
/// tokenizer state errors and callback errors are propagated.
pub fn parse_content_operations<F>(input: &[u8], on_operation: F) -> Result<()>
where
    F: FnMut(&[ObjectHandle], &[u8]) -> Result<ParseControl>,
{
    let mut callbacks = OperationCallbacks {
        operands: Vec::new(),
        on_operation,
    };
    parse_content_stream_handles(input, None, "", &mut callbacks)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[derive(Default)]
    struct RecordingResolver {
        warnings: RefCell<Vec<Vec<u8>>>,
    }

    impl DocumentResolver for RecordingResolver {
        fn resolve_indirect(
            &self,
            _object_ref: crate::ObjectRef,
            _handle: &ObjectHandle,
        ) -> Result<()> {
            Err(Error::Internal("unexpected indirect resolution".to_owned()))
        }

        fn warn(&self, warning: QpdfExc) -> Result<()> {
            self.warnings
                .borrow_mut()
                .push(warning.what_bytes().to_vec());
            Ok(())
        }
    }

    #[derive(Default)]
    struct RecordingCallbacks {
        objects: usize,
        eof: bool,
    }

    impl ObjectHandleParserCallbacks for RecordingCallbacks {
        fn handle_object(
            &mut self,
            _object: ObjectHandle,
            _offset: usize,
            _length: usize,
        ) -> Result<ParseControl> {
            self.objects += 1;
            Ok(ParseControl::Continue)
        }

        fn handle_eof(&mut self) -> Result<()> {
            self.eof = true;
            Ok(())
        }
    }

    #[test]
    fn recoverable_warning_resolver_rejects_indirect_resolution() {
        let resolver = RecoverableWarningResolver::default();
        let object_ref = crate::ObjectRef::new(9, 0);
        let handle = ObjectHandle::new_indirect_unresolved(object_ref, -1);

        let error = resolver
            .resolve_indirect(object_ref, &handle)
            .expect_err("an in-memory warning sink cannot resolve indirect objects");
        assert!(matches!(
            error,
            Error::Internal(message)
                if message == "indirect resolution requested from an in-memory content warning sink"
        ));
    }

    #[test]
    fn recording_warning_resolver_rejects_indirect_resolution() {
        let resolver = RecordingResolver::default();
        let error = resolver
            .resolve_indirect(crate::ObjectRef::new(7, 0), &ObjectHandle::null())
            .expect_err("the test warning resolver must reject indirect resolution");
        assert!(matches!(
            error,
            Error::Internal(message) if message == "unexpected indirect resolution"
        ));
    }

    #[test]
    fn container_eof_warns_and_finishes_content_parsing_like_qpdf() {
        for input in [b"/F1 12 Tf [".as_slice(), b"/F1 12 Tf << /A 1".as_slice()] {
            let resolver = Rc::new(RecordingResolver::default());
            let context: Rc<dyn DocumentResolver> = resolver.clone();
            let mut callbacks = RecordingCallbacks::default();

            parse_content_stream_handles(
                input,
                Some(context),
                "page object 14 0 stream 14 0",
                &mut callbacks,
            )
            .expect("content EOF is a warning, not a hard parser error");

            assert_eq!(callbacks.objects, 3, "qpdf keeps the complete prefix");
            assert!(
                callbacks.eof,
                "qpdf invokes handleEOF after the truncated object"
            );
            let warnings = resolver.warnings.borrow();
            assert_eq!(warnings.len(), 1, "qpdf emits one container EOF warning");
            let warning = String::from_utf8_lossy(&warnings[0]);
            let expected = format!(
                "page object 14 0 stream 14 0 (content, offset {}): parse error while reading object",
                input.len()
            );
            assert!(
                warning.contains(&expected),
                "warning must use qpdf's content description: {warning}"
            );
        }
    }

    #[test]
    fn nested_container_eof_propagates_to_the_outer_content_parse() {
        for input in [
            b"<< /A [".as_slice(),
            b"<< 1 [".as_slice(),
            b"[[".as_slice(),
        ] {
            let resolver = Rc::new(RecordingResolver::default());
            let context: Rc<dyn DocumentResolver> = resolver.clone();
            let mut callbacks = RecordingCallbacks::default();

            parse_content_stream_handles(input, Some(context), "nested", &mut callbacks)
                .expect("nested content EOF is a warning, not a hard parser error");

            assert_eq!(
                callbacks.objects, 0,
                "the incomplete outer object is discarded"
            );
            assert!(callbacks.eof, "qpdf completes the scan after the warning");
            let warnings = resolver.warnings.borrow();
            assert_eq!(
                warnings.len(),
                1,
                "qpdf emits one nested container EOF warning"
            );
            assert!(String::from_utf8_lossy(&warnings[0]).contains(&format!(
                "nested (content, offset {}): parse error while reading object",
                input.len()
            )));
        }
    }
}