flpdf 0.5.0

A pure-Rust PDF toolkit modeled on qpdf — read, rewrite, linearize, and inspect PDFs.
Documentation
//! qpdf correspondence: QPDFWriter.cc object-stream body and container emission.
//! The emitter builds the pair table and member bodies, then wraps them in the
//! `/Type /ObjStm` stream container used by the writer.

use std::collections::HashSet;

use crate::ObjectHandle;
use crate::ObjectRef;
// ── ObjStm body emitter ───────────────────────────────────────────────────────

/// The serialised body of an ObjStm (ISO 32000-1 §7.5.7).
///
/// Contains the raw pair table concatenated with the objects section.
/// Compression (FlateDecode) and the stream dictionary wrapping are handled
/// by a subsequent step.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ObjStmBody {
    /// Raw concatenation: pair table || objects section.  To be deflate-wrapped later.
    pub bytes: Vec<u8>,
    /// Offset within `bytes` where the first object body starts.  Matches /First.
    pub first_offset: usize,
    /// Number of members.  Matches /N.
    pub n_members: usize,
}

/// Serialise a list of pre-resolved `(ObjectRef, Object)` pairs into an ObjStm
/// body following ISO 32000-1 §7.5.7.
///
/// This inner function does the real work without touching a `Pdf` reader; it
/// exists primarily to make unit-testing Pdf-free.
/// Serialise ObjStm members directly from the canonical ObjectHandle graph.
///
/// The member pair table is still supplied in output-number order by the
/// planner, but each body is emitted from its live handle. This is the qpdf
/// writer boundary: arrays and dictionaries retain indirect child identity,
/// dictionary nulls are suppressed by the handle unparser, and no temporary
/// [`ObjectHandle`] tree is materialised merely to calculate the body offsets.
/// Handle-backed ObjStm body emission with a caller-owned member serializer.
///
/// The callback is used for the encrypted full-rewrite route, where qpdf's
/// per-object data-key scope is applied while the ObjectHandle walker writes
/// strings. The callback receives the same two-pass member index used by the
/// ObjStm pair table and may therefore preserve qpdf's encryption boundary
/// without materialising a legacy object tree.
pub(crate) fn emit_objstm_body_from_handles_with_writer<F>(
    members: &[(ObjectRef, ObjectHandle)],
    write_member: &mut F,
) -> crate::Result<ObjStmBody>
where
    F: FnMut(&mut Vec<u8>, u32, ObjectRef, &ObjectHandle) -> crate::Result<()>,
{
    emit_objstm_body_from_members(members, write_member, false)
}

/// QDF-formatted ObjStm body emission. QPDFWriter writes the pair table with
/// one `<object> <offset>` row per line in QDF mode; the ordinary writer uses a
/// single space between pairs.
pub(crate) fn emit_objstm_body_from_handles_with_writer_qdf<F>(
    members: &[(ObjectRef, ObjectHandle)],
    write_member: &mut F,
) -> crate::Result<ObjStmBody>
where
    F: FnMut(&mut Vec<u8>, u32, ObjectRef, &ObjectHandle) -> crate::Result<()>,
{
    emit_objstm_body_from_members(members, write_member, true)
}

fn emit_objstm_body_from_members<T, F>(
    members: &[(ObjectRef, T)],
    write_member: &mut F,
    qdf: bool,
) -> crate::Result<ObjStmBody>
where
    F: FnMut(&mut Vec<u8>, u32, ObjectRef, &T) -> crate::Result<()>,
{
    if members.is_empty() {
        return Ok(ObjStmBody {
            bytes: vec![],
            first_offset: 0,
            n_members: 0,
        });
    }

    // Duplicate detection — fail fast before producing any output.
    let mut seen: HashSet<u32> = HashSet::with_capacity(members.len());
    for (obj_ref, _) in members {
        if !seen.insert(obj_ref.number) {
            return Err(crate::Error::Unsupported(format!(
                "duplicate member in ObjStm batch {}",
                obj_ref.number
            )));
        }
    }

    // Build the objects section and record per-member offsets.
    let mut objects_section: Vec<u8> = Vec::new();
    let mut offsets: Vec<usize> = Vec::with_capacity(members.len());

    for (member_index, (object_ref, object)) in members.iter().enumerate() {
        offsets.push(objects_section.len());
        // cov:ignore-start: a Vec cannot hold more than u32::MAX members in supported targets.
        let member_index = u32::try_from(member_index).map_err(|_| {
            crate::Error::Unsupported("ObjStm member index overflows u32".to_string())
        })?;
        // cov:ignore-end
        write_member(&mut objects_section, member_index, *object_ref, object)?;
        // Append exactly one newline after each object body (write_pdf has no trailing LF).
        objects_section.push(b'\n');
    }

    // Build the pair table: `<number> <offset>` for each member, all
    // space-separated on a single line with one trailing newline before the
    // objects section — qpdf 11.9.0's `/Type /ObjStm` layout (a newline after
    // each pair, as flpdf used to emit, is valid PDF but not byte-identical).
    let mut pair_table: Vec<u8> = Vec::new();
    use std::io::Write as _;
    for (i, ((obj_ref, _), offset)) in members.iter().zip(offsets.iter()).enumerate() {
        if i > 0 {
            pair_table.push(if qdf { b'\n' } else { b' ' });
        }
        // Write directly into `pair_table` to avoid a temporary `String`
        // allocation per member.
        let _ = write!(pair_table, "{} {}", obj_ref.number, offset);
    }
    pair_table.push(b'\n');

    let first_offset = pair_table.len();

    // Concatenate: pair table || objects section.
    let mut bytes = pair_table;
    bytes.extend_from_slice(&objects_section);

    Ok(ObjStmBody {
        bytes,
        first_offset,
        n_members: members.len(),
    })
}

// ── ObjStm stream wrapper ────────────────────────────────────────────────────

/// Wrap an [`ObjStmBody`] and build the complete `/Type /ObjStm` stream
/// dictionary (ISO 32000-1 §7.5.7).
///
/// The returned stream handle is ready to be written as an indirect object.
/// Key order follows qpdf parity: `Type → N → First → Length → Filter`.
///
/// The `compress` parameter controls whether the body bytes are compressed with
/// FlateDecode (`CompressStreams::Yes`, the default) or emitted raw
/// (`CompressStreams::No`).  Passing the same [`crate::writer::CompressStreams`]
/// value that drives the surrounding full-rewrite loop ensures the ObjStm
/// container uses the same policy as every other stream in the document.
/// Build the synthetic ObjStm container as an ObjectHandle while retaining
/// the raw payload separately for the stream pipeline. The container has no
/// source object identity, but its dictionary is still emitted through the
/// same live-handle serializer as ordinary streams; `/Extends`, when present,
/// is already in output-number space and is therefore stored as a reference
/// token rather than a legacy `Object` value.
pub(crate) fn wrap_objstm_body_as_handle(
    body: &ObjStmBody,
    compress: crate::writer::CompressStreams,
    extends: Option<crate::ObjectRef>,
) -> crate::Result<(ObjectHandle, Vec<u8>)> {
    let (data, filter) = match compress {
        crate::writer::CompressStreams::Yes => {
            let encode_dict = ObjectHandle::dictionary(vec![(
                b"Filter".to_vec(),
                ObjectHandle::name(b"FlateDecode".to_vec()),
            )]);
            (
                crate::filters::encode_stream_data_from_handle(&encode_dict, &body.bytes)?,
                true,
            )
        }
        crate::writer::CompressStreams::No => (body.bytes.clone(), false),
    };

    let mut entries = vec![
        (b"Type".to_vec(), ObjectHandle::name(b"ObjStm".to_vec())),
        (
            b"N".to_vec(),
            ObjectHandle::integer(i64::try_from(body.n_members).unwrap_or(i64::MAX)),
        ),
        (
            b"First".to_vec(),
            ObjectHandle::integer(i64::try_from(body.first_offset).unwrap_or(i64::MAX)),
        ),
        (
            b"Length".to_vec(),
            ObjectHandle::integer(i64::try_from(data.len()).unwrap_or(i64::MAX)),
        ),
    ];
    if filter {
        entries.push((
            b"Filter".to_vec(),
            ObjectHandle::name(b"FlateDecode".to_vec()),
        ));
    }
    if let Some(extends) = extends {
        entries.push((
            b"Extends".to_vec(),
            ObjectHandle::new_indirect_unresolved(extends, -1),
        ));
    }
    let handle = ObjectHandle::stream(
        ObjectHandle::dictionary(entries),
        std::rc::Rc::new(data.clone()),
    );
    Ok((handle, data))
}

#[cfg(test)]
mod final_handle_tests {
    use super::{wrap_objstm_body_as_handle, ObjStmBody};
    use crate::writer::CompressStreams;
    use crate::ObjectRef;

    #[test]
    fn object_stream_wrapper_retains_an_extends_reference_handle() {
        let body = ObjStmBody {
            bytes: b"1 0\n7".to_vec(),
            first_offset: 4,
            n_members: 1,
        };
        let (stream, _) =
            wrap_objstm_body_as_handle(&body, CompressStreams::No, Some(ObjectRef::new(9, 0)))
                .expect("object stream wrapper");
        assert_eq!(
            stream
                .as_stream_dict()
                .expect("stream dictionary")
                .try_get_key(b"/Extends")
                .expect("Extends key")
                .object_ref(),
            Some(ObjectRef::new(9, 0))
        );
    }
}