pdfluent_lopdf/
load_options.rs

1/// Default maximum input size: 256 MiB.
2///
3/// Chosen so that a single document load can never exceed ~2 GB of RSS on
4/// realistic input (the worst-case amplification ratio measured across the
5/// corpus is ~20×, so 256 MiB × 20 ≈ 5 GB — still above the default, but
6/// the limit is a first-line guard, not a tight memory cap).  Callers that
7/// need larger files can pass a higher limit via `LoadOptions::max_file_bytes`.
8pub const DEFAULT_MAX_FILE_BYTES: usize = 256 * 1024 * 1024;
9
10/// Options that control how a PDF document is loaded into memory.
11///
12/// All options have safe defaults:
13/// - `max_file_bytes`: `Some(256 MiB)` — rejects enormous inputs before
14///   allocating the full object graph.
15/// - `lazy_objstm`: `false` — ObjStm streams are decompressed eagerly, but
16///   their container streams are dropped immediately after extraction
17///   (saves the decompressed container bytes; Phase 2a optimisation).
18///
19/// # Example
20///
21/// ```rust,ignore
22/// let opts = LoadOptions::new()
23///     .max_file_bytes(64 * 1024 * 1024)   // 64 MiB hard limit
24///     .lazy_objstm(true);                  // defer ObjStm extraction
25/// let doc = Document::load_mem_with_options(data, &opts)?;
26/// doc.resolve_pending_object_streams()?;   // required when lazy_objstm = true
27/// ```
28#[derive(Debug, Clone)]
29pub struct LoadOptions {
30    /// Maximum allowed size of the input buffer in bytes.
31    ///
32    /// When `Some(limit)`, `load_mem_with_options` / `load_with_options` return
33    /// `Err(Error::DocumentTooLarge)` without allocating the object graph if the
34    /// input exceeds `limit`.  `None` disables the check entirely.
35    pub(crate) max_file_bytes: Option<usize>,
36
37    /// When `true`, ObjStm streams are **not** decompressed during loading.
38    ///
39    /// Their container objects are kept in `Document::objects` and their IDs
40    /// are stored in `Document::pending_obj_streams`.  The caller must invoke
41    /// `Document::resolve_pending_object_streams` before accessing any object
42    /// that lives inside an ObjStm container.
43    ///
44    /// When `false` (default), ObjStm streams are decompressed eagerly during
45    /// load and their container streams are discarded immediately after
46    /// extraction (Phase 2a memory optimisation).
47    pub(crate) lazy_objstm: bool,
48}
49
50impl Default for LoadOptions {
51    fn default() -> Self {
52        Self {
53            max_file_bytes: Some(DEFAULT_MAX_FILE_BYTES),
54            lazy_objstm: false,
55        }
56    }
57}
58
59impl LoadOptions {
60    /// Create options with default values.
61    pub fn new() -> Self {
62        Self::default()
63    }
64
65    /// Set the maximum allowed input size in bytes.
66    ///
67    /// Pass `None` to remove the limit (not recommended in worker-pool contexts).
68    pub fn max_file_bytes(mut self, limit: impl Into<Option<usize>>) -> Self {
69        self.max_file_bytes = limit.into();
70        self
71    }
72
73    /// Enable or disable lazy ObjStm decompression.
74    ///
75    /// When `true`, ObjStm streams are kept compressed in `Document::objects`
76    /// and their IDs accumulate in `Document::pending_obj_streams`.  The caller
77    /// must call `Document::resolve_pending_object_streams` before using the
78    /// document.
79    pub fn lazy_objstm(mut self, lazy: bool) -> Self {
80        self.lazy_objstm = lazy;
81        self
82    }
83}
pdfluent_lopdf/load_options.rs

pdfluent_lopdf/
load_options.rs
