rpdfium_parser/

trailer.rs

// Derived from PDFium's cpdf_parser.cpp (trailer & startxref parsing)
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! Trailer parsing — locates `startxref`, parses trailer dictionary,
//! and follows the `/Prev` chain to build the full cross-reference table.

use std::collections::HashMap;

use rpdfium_core::error::PdfError;
use rpdfium_core::{Name, ParsingMode};

use crate::object::{Object, ObjectId};
use crate::object_parser::parse_object;
use crate::tokenizer::is_whitespace;
use crate::xref::parse_xref_table;
use crate::xref::{XrefSection, XrefTable};
use crate::xref_stream::parse_xref_stream;

/// Extracted information from the trailer dictionary.
#[derive(Debug, Clone)]
pub struct TrailerInfo {
    /// The indirect reference to the document catalog (`/Root`).
    pub root: ObjectId,
    /// Optional indirect reference to the document information dictionary (`/Info`).
    pub info: Option<ObjectId>,
    /// Optional indirect reference to the encryption dictionary (`/Encrypt`).
    pub encrypt: Option<ObjectId>,
    /// Optional file identifier array (`/ID`).
    pub id: Option<[Vec<u8>; 2]>,
    /// Total number of cross-reference entries (`/Size`).
    pub size: u32,
    /// Optional offset to the previous cross-reference section (`/Prev`).
    pub prev: Option<u64>,
}

impl TrailerInfo {
    /// Returns the object number of the document catalog (`/Root`).
    ///
    /// Corresponds to `CPDF_Parser::GetRootObjNum()` in PDFium.
    pub fn root_obj_num(&self) -> u32 {
        self.root.number
    }

    /// ADR-019 alias for [`root_obj_num()`](Self::root_obj_num).
    ///
    /// Corresponds to `CPDF_Parser::GetRootObjNum()` in PDFium.
    #[inline]
    pub fn get_root_obj_num(&self) -> u32 {
        self.root_obj_num()
    }

    /// Returns the object number of the document information dictionary
    /// (`/Info`), or `None` if not present.
    ///
    /// Corresponds to `CPDF_Parser::GetInfoObjNum()` in PDFium.
    pub fn info_obj_num(&self) -> Option<u32> {
        self.info.map(|id| id.number)
    }

    /// ADR-019 alias for [`info_obj_num()`](Self::info_obj_num).
    ///
    /// Corresponds to `CPDF_Parser::GetInfoObjNum()` in PDFium.
    #[inline]
    pub fn get_info_obj_num(&self) -> Option<u32> {
        self.info_obj_num()
    }

    /// Returns the object ID reference to the encryption dictionary
    /// (`/Encrypt`), or `None` if the document is not encrypted.
    ///
    /// Corresponds to `CPDF_Parser::GetEncryptDict()` in PDFium (returns the
    /// reference rather than resolving the dictionary itself).
    pub fn encrypt_dict(&self) -> Option<ObjectId> {
        self.encrypt
    }

    /// ADR-019 alias for [`encrypt_dict()`](Self::encrypt_dict).
    ///
    /// Corresponds to `CPDF_Parser::GetEncryptDict()` in PDFium.
    #[inline]
    pub fn get_encrypt_dict(&self) -> Option<ObjectId> {
        self.encrypt_dict()
    }

    /// Deprecated non-upstream alias for [`encrypt_dict()`](Self::encrypt_dict).
    ///
    /// There is no `CPDF_Trailer::GetEncryptId()` in PDFium upstream; the
    /// correct upstream method is `CPDF_Parser::GetEncryptDict()`, already
    /// covered by [`get_encrypt_dict()`](Self::get_encrypt_dict).
    /// Use [`get_encrypt_dict()`](Self::get_encrypt_dict) instead.
    #[deprecated(
        note = "use `get_encrypt_dict()` — matches upstream CPDF_Parser::GetEncryptDict()"
    )]
    #[inline]
    pub fn get_encrypt_id(&self) -> Option<ObjectId> {
        self.encrypt_dict()
    }

    /// Rust-idiomatic alias for [`encrypt_dict()`](Self::encrypt_dict).
    #[inline]
    #[deprecated(since = "0.0.0", note = "use `encrypt_dict()` or `get_encrypt_dict()`")]
    pub fn encrypt_id(&self) -> Option<ObjectId> {
        self.encrypt_dict()
    }

    /// Returns a reference to the file identifier byte-string pair (`/ID`),
    /// or `None` if not present.
    ///
    /// Corresponds to `CPDF_Parser::GetIDArray()` in PDFium.
    pub fn id_array(&self) -> Option<&[Vec<u8>; 2]> {
        self.id.as_ref()
    }

    /// ADR-019 alias for [`id_array()`](Self::id_array).
    ///
    /// Corresponds to `CPDF_Parser::GetIDArray()` in PDFium.
    #[inline]
    pub fn get_id_array(&self) -> Option<&[Vec<u8>; 2]> {
        self.id_array()
    }
}

/// Maximum number of /Prev links to follow (prevents infinite loops).
const MAX_PREV_CHAIN: usize = 512;

/// Number of bytes from the end of file to search for `startxref`.
const STARTXREF_SEARCH_SIZE: usize = 1024;

/// Parse all cross-reference sections and trailer info from the source.
///
/// 1. Locate `startxref` near the end of the file.
/// 2. Parse the xref section (table or stream) at that offset.
/// 3. Follow `/Prev` chain to discover all xref sections.
/// 4. Return the merged `XrefTable` (newest-first) and `TrailerInfo` from the newest trailer.
pub fn parse_all_xrefs(
    source: &[u8],
    mode: ParsingMode,
) -> Result<(XrefTable, TrailerInfo), PdfError> {
    let startxref_offset = find_startxref(source)?;

    let mut xref_table = XrefTable::new();
    xref_table.start_offset = startxref_offset;
    let mut trailer_info: Option<TrailerInfo> = None;
    let mut current_offset = Some(startxref_offset);
    let mut visited_offsets = Vec::new();

    // Follow /Prev chain iteratively (no recursion)
    while let Some(offset) = current_offset {
        // Circular reference detection
        if visited_offsets.contains(&offset) {
            tracing::warn!(offset = offset, "circular /Prev reference in xref chain");
            break;
        }

        if visited_offsets.len() >= MAX_PREV_CHAIN {
            tracing::warn!("exceeded maximum /Prev chain length");
            break;
        }

        visited_offsets.push(offset);

        // Determine if this is a traditional xref table or an xref stream
        let (section, trailer_dict, prev) = parse_xref_at_offset(source, offset, mode)?;

        xref_table.push(section);

        // Extract trailer info from the first (newest) trailer
        if trailer_info.is_none() {
            trailer_info = Some(extract_trailer_info(&trailer_dict)?);
        }

        // Follow /Prev
        current_offset = prev;
    }

    let info = trailer_info.ok_or(PdfError::InvalidTrailer)?;
    Ok((xref_table, info))
}

/// Parse a single xref section at the given offset.
/// Handles both traditional xref tables and xref streams.
///
/// Returns (xref section, trailer dict, optional /Prev offset).
type XrefAtOffsetResult = Result<(XrefSection, HashMap<Name, Object>, Option<u64>), PdfError>;

fn parse_xref_at_offset(source: &[u8], offset: u64, mode: ParsingMode) -> XrefAtOffsetResult {
    // Peek at the data to determine format
    let start = offset as usize;
    if start >= source.len() {
        return Err(PdfError::InvalidXref);
    }

    // Skip whitespace
    let mut peek_pos = start;
    while peek_pos < source.len() && is_whitespace(source[peek_pos]) {
        peek_pos += 1;
    }

    if peek_pos + 4 <= source.len() && &source[peek_pos..peek_pos + 4] == b"xref" {
        // Traditional xref table + trailer
        let (section, trailer_offset) = parse_xref_table(source, offset)?;
        let (trailer_dict, prev) = parse_trailer_dict(source, trailer_offset, mode)?;
        Ok((section, trailer_dict, prev))
    } else {
        // Xref stream (the object at this offset is the stream)
        let (section, dict) = parse_xref_stream(source, offset, mode)?;
        let prev = extract_prev(&dict);

        // If there's a /XRefStm in the dict, we need to also parse that xref stream
        // For now, the dict serves as both the xref stream dict and the trailer dict
        Ok((section, dict, prev))
    }
}

/// Parse the trailer dictionary that follows a traditional xref table.
///
/// Expected format: `trailer\n<< ... >>`
fn parse_trailer_dict(
    source: &[u8],
    offset: u64,
    mode: ParsingMode,
) -> Result<(HashMap<Name, Object>, Option<u64>), PdfError> {
    let mut pos = offset as usize;

    // Skip whitespace
    while pos < source.len() && is_whitespace(source[pos]) {
        pos += 1;
    }

    // Expect "trailer" keyword
    if pos + 7 > source.len() || &source[pos..pos + 7] != b"trailer" {
        return Err(PdfError::InvalidTrailer);
    }
    pos += 7;

    // Skip whitespace
    while pos < source.len() && is_whitespace(source[pos]) {
        pos += 1;
    }

    // Parse the trailer dictionary
    let dict_obj = parse_object(source, pos as u64, mode)?;
    let dict = match dict_obj {
        Object::Dictionary(d) => d,
        _ => return Err(PdfError::InvalidTrailer),
    };

    let prev = extract_prev(&dict);
    Ok((dict, prev))
}

/// Extract the `/Prev` offset from a trailer dictionary.
fn extract_prev(dict: &HashMap<Name, Object>) -> Option<u64> {
    match dict.get(&Name::prev()) {
        Some(Object::Integer(n)) if *n >= 0 => Some(*n as u64),
        _ => None,
    }
}

/// Extract `TrailerInfo` from a trailer dictionary.
fn extract_trailer_info(dict: &HashMap<Name, Object>) -> Result<TrailerInfo, PdfError> {
    // /Root is required
    let root = match dict.get(&Name::root()) {
        Some(Object::Reference(id)) => *id,
        _ => return Err(PdfError::InvalidTrailer),
    };

    // /Size is required
    let size = match dict.get(&Name::size()) {
        Some(Object::Integer(n)) if *n > 0 => *n as u32,
        _ => return Err(PdfError::InvalidTrailer),
    };

    // /Info is optional
    let info = match dict.get(&Name::info()) {
        Some(Object::Reference(id)) => Some(*id),
        _ => None,
    };

    // /Encrypt is optional
    let encrypt = match dict.get(&Name::encrypt()) {
        Some(Object::Reference(id)) => Some(*id),
        _ => None,
    };

    // /ID is optional (array of two strings)
    let id = extract_id_array(dict);

    let prev = extract_prev(dict);

    Ok(TrailerInfo {
        root,
        info,
        encrypt,
        id,
        size,
        prev,
    })
}

/// Extract the /ID array (two byte strings) from the trailer dictionary.
fn extract_id_array(dict: &HashMap<Name, Object>) -> Option<[Vec<u8>; 2]> {
    let arr = match dict.get(&Name::id()) {
        Some(Object::Array(a)) if a.len() >= 2 => a,
        _ => return None,
    };

    let id0 = match &arr[0] {
        Object::String(s) => s.as_bytes().to_vec(),
        _ => return None,
    };
    let id1 = match &arr[1] {
        Object::String(s) => s.as_bytes().to_vec(),
        _ => return None,
    };

    Some([id0, id1])
}

/// Find the `startxref` offset from near the end of the file.
///
/// PDF files end with:
/// ```text
/// startxref
/// <offset>
/// %%EOF
/// ```
pub fn find_startxref(source: &[u8]) -> Result<u64, PdfError> {
    let search_start = source.len().saturating_sub(STARTXREF_SEARCH_SIZE);
    let tail = &source[search_start..];

    // Search backwards for "startxref"
    let marker = b"startxref";

    let mut found_pos = None;
    for i in (0..tail.len().saturating_sub(marker.len())).rev() {
        if &tail[i..i + marker.len()] == marker {
            found_pos = Some(i);
            break;
        }
    }

    let pos = found_pos.ok_or(PdfError::InvalidTrailer)?;

    // Skip past "startxref" and whitespace to read the offset
    let mut offset_start = pos + marker.len();
    while offset_start < tail.len() && is_whitespace(tail[offset_start]) {
        offset_start += 1;
    }

    // Read digits
    let mut offset_end = offset_start;
    while offset_end < tail.len() && tail[offset_end] >= b'0' && tail[offset_end] <= b'9' {
        offset_end += 1;
    }

    if offset_end == offset_start {
        return Err(PdfError::InvalidTrailer);
    }

    let offset_str = std::str::from_utf8(&tail[offset_start..offset_end])
        .map_err(|_| PdfError::InvalidTrailer)?;
    let offset: u64 = offset_str.parse().map_err(|_| PdfError::InvalidTrailer)?;

    Ok(offset)
}

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

    #[test]
    fn test_find_startxref_simple() {
        let source = b"some content\nstartxref\n1234\n%%EOF";
        let offset = find_startxref(source).unwrap();
        assert_eq!(offset, 1234);
    }

    #[test]
    fn test_find_startxref_with_extra_whitespace() {
        let source = b"content\nstartxref\n  5678  \n%%EOF\n";
        let offset = find_startxref(source).unwrap();
        assert_eq!(offset, 5678);
    }

    #[test]
    fn test_find_startxref_missing() {
        let source = b"no start xref here %%EOF";
        let result = find_startxref(source);
        assert!(result.is_err());
    }

    #[test]
    fn test_extract_trailer_info_valid() {
        let mut dict = HashMap::new();
        dict.insert(Name::root(), Object::Reference(ObjectId::new(1, 0)));
        dict.insert(Name::size(), Object::Integer(10));
        dict.insert(Name::info(), Object::Reference(ObjectId::new(2, 0)));

        let info = extract_trailer_info(&dict).unwrap();
        assert_eq!(info.root, ObjectId::new(1, 0));
        assert_eq!(info.size, 10);
        assert_eq!(info.info, Some(ObjectId::new(2, 0)));
        assert!(info.encrypt.is_none());
        assert!(info.id.is_none());
    }

    #[test]
    fn test_extract_trailer_info_missing_root() {
        let mut dict = HashMap::new();
        dict.insert(Name::size(), Object::Integer(10));
        let result = extract_trailer_info(&dict);
        assert!(result.is_err());
    }

    #[test]
    fn test_extract_trailer_info_missing_size() {
        let mut dict = HashMap::new();
        dict.insert(Name::root(), Object::Reference(ObjectId::new(1, 0)));
        let result = extract_trailer_info(&dict);
        assert!(result.is_err());
    }

    #[test]
    fn test_extract_prev_present() {
        let mut dict = HashMap::new();
        dict.insert(Name::prev(), Object::Integer(500));
        assert_eq!(extract_prev(&dict), Some(500));
    }

    #[test]
    fn test_extract_prev_absent() {
        let dict = HashMap::new();
        assert_eq!(extract_prev(&dict), None);
    }

    #[test]
    fn test_extract_id_array_valid() {
        use rpdfium_core::PdfString;
        let mut dict = HashMap::new();
        dict.insert(
            Name::id(),
            Object::Array(vec![
                Object::String(PdfString::from_bytes(b"abc".to_vec())),
                Object::String(PdfString::from_bytes(b"def".to_vec())),
            ]),
        );
        let id = extract_id_array(&dict).unwrap();
        assert_eq!(id[0], b"abc");
        assert_eq!(id[1], b"def");
    }

    #[test]
    fn test_extract_id_array_missing() {
        let dict = HashMap::new();
        assert!(extract_id_array(&dict).is_none());
    }

    #[test]
    fn test_parse_trailer_dict() {
        let source = b"trailer\n<< /Size 10 /Root 1 0 R >>\nstartxref\n0\n%%EOF";
        let (dict, prev) = parse_trailer_dict(source, 0, ParsingMode::Strict).unwrap();
        assert!(dict.contains_key(&Name::size()));
        assert!(dict.contains_key(&Name::root()));
        assert!(prev.is_none());
    }

    #[test]
    fn test_parse_trailer_dict_with_prev() {
        let source = b"trailer\n<< /Size 10 /Root 1 0 R /Prev 500 >>";
        let (dict, prev) = parse_trailer_dict(source, 0, ParsingMode::Strict).unwrap();
        assert!(dict.contains_key(&Name::size()));
        assert_eq!(prev, Some(500));
    }
}