A fast, helpful, and open-source document parser
Make LiteParse safe to share across threads
Clelia (Astra) Bertellid7ccc5e58cdf
diff --git a/crates/liteparse/src/extract.rs b/crates/liteparse/src/extract.rsindex 09e9812..390eb5b 100644--- a/crates/liteparse/src/extract.rs+++ b/crates/liteparse/src/extract.rs@@ -3,11 +3,16 @@ use crate::types::{Page as LitePage, PdfInput, TextItem};use pdfium::{Document, Font, FontType, Library, Page, RectF, TextPage};/// Open a PDF from path or bytes with an optional password.-pub(crate) fn load_document_from_input(+///+/// The returned [`Document`] borrows from the provided [`Library`], which+/// holds the process-global PDFium lock. The lock is released when the+/// `Library` is dropped, so callers must keep `lib` alive for as long as any+/// `Document` / `Page` / `TextPage` etc. derived from it is in use.+pub(crate) fn load_document_from_input<'lib>(+ lib: &'lib Library,input: &PdfInput,password: Option<&str>,-) -> Result<Document, LiteParseError> {- let lib = Library::init();+) -> Result<Document<'lib>, LiteParseError> {match input {PdfInput::Path(path) => Ok(lib.load_document(path, password)?),PdfInput::Bytes(data) => Ok(lib.load_document_from_bytes(data, password)?),@@ -15,13 +20,19 @@ pub(crate) fn load_document_from_input(}/// Extract pages from a `PdfInput` (file path or bytes) with filtering.+///+/// This convenience entry point acquires the PDFium lock internally for the+/// full extraction. Callers that already hold a [`Library`] (e.g. because+/// they're also rendering bitmaps in the same critical section) should call+/// [`extract_pages_from_document`] directly.pub fn extract_pages_from_input(input: &PdfInput,target_pages: Option<&[u32]>,max_pages: usize,password: Option<&str>,) -> Result<Vec<LitePage>, LiteParseError> {- let document = load_document_from_input(input, password)?;+ let lib = Library::init();+ let document = load_document_from_input(&lib, input, password)?;extract_pages_from_document(&document, target_pages, max_pages)}diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rsindex 4a295ae..47159a6 100644--- a/crates/liteparse/src/parser.rs+++ b/crates/liteparse/src/parser.rs@@ -13,6 +13,7 @@ use crate::projection;#[cfg(not(target_arch = "wasm32"))]use crate::render;use crate::types::{ParsedPage, PdfInput};+use pdfium::Library;/// Result of parsing a document.pub struct ParseResult {@@ -32,6 +33,20 @@ pub struct ScreenshotResult {}/// Main LiteParse orchestrator.+///+/// ### Thread safety+///+/// `LiteParse` is `Send + Sync` and safe to share across threads (e.g.+/// behind an `Arc`, or used concurrently from a multi-threaded `tokio`+/// runtime).+///+/// PDFium itself is **not** thread-safe, so all PDFium FFI work — document+/// loading, page rendering, text extraction — is serialized through a+/// process-global lock held by [`pdfium::Library`]. From a caller's+/// perspective, this means concurrent `parse_*` / `screenshot*` calls are+/// safe but their PDFium portions run sequentially. The OCR pass and grid+/// projection (which dominate runtime for OCR-heavy documents) run outside+/// the lock and remain fully concurrent.pub struct LiteParse {config: LiteParseConfig,/// Optional caller-provided OCR engine. When set, this overrides the@@ -98,43 +113,52 @@ impl LiteParse {.map_err(|e| format!("invalid --target-pages: {}", e))?;// Extract text (and pre-render OCR pages in one PDF load when OCR is on).+ //+ // The PDFium lock is acquired for this entire critical section and+ // released before any `.await` below — OCR (network / CPU) and grid+ // projection (pure Rust) do not touch PDFium, so they can run+ // concurrently with other `LiteParse` calls.let password = self.config.password.as_deref();- let (mut pages, ocr_rendered) = if self.config.ocr_enabled {- let document = extract::load_document_from_input(&validated_input, password)?;- let pages = extract::extract_pages_from_document(- &document,- target_pages.as_deref(),- self.config.max_pages,- )?;- let t_extract = web_time::Instant::now();- log(&format!(- "[liteparse] extract: {:.1}ms ({} pages)",- t_extract.duration_since(t0).as_secs_f64() * 1000.0,- pages.len()- ));- let rendered = ocr_merge::render_pages_for_ocr(&document, &pages, self.config.dpi)?;- log(&format!(- "[liteparse] ocr render: {:.1}ms ({} pages)",- web_time::Instant::now()- .duration_since(t_extract)- .as_secs_f64()- * 1000.0,- rendered.len()- ));- (pages, rendered)- } else {- let pages = extract::extract_pages_from_input(- &validated_input,- target_pages.as_deref(),- self.config.max_pages,- password,- )?;- log(&format!(- "[liteparse] extract: {:.1}ms ({} pages)",- web_time::Instant::now().duration_since(t0).as_secs_f64() * 1000.0,- pages.len()- ));- (pages, Vec::new())+ let (mut pages, ocr_rendered) = {+ let lib = Library::init();+ if self.config.ocr_enabled {+ let document = extract::load_document_from_input(&lib, &validated_input, password)?;+ let pages = extract::extract_pages_from_document(+ &document,+ target_pages.as_deref(),+ self.config.max_pages,+ )?;+ let t_extract = web_time::Instant::now();+ log(&format!(+ "[liteparse] extract: {:.1}ms ({} pages)",+ t_extract.duration_since(t0).as_secs_f64() * 1000.0,+ pages.len()+ ));+ let rendered = ocr_merge::render_pages_for_ocr(&document, &pages, self.config.dpi)?;+ log(&format!(+ "[liteparse] ocr render: {:.1}ms ({} pages)",+ web_time::Instant::now()+ .duration_since(t_extract)+ .as_secs_f64()+ * 1000.0,+ rendered.len()+ ));+ (pages, rendered)+ } else {+ let document = extract::load_document_from_input(&lib, &validated_input, password)?;+ let pages = extract::extract_pages_from_document(+ &document,+ target_pages.as_deref(),+ self.config.max_pages,+ )?;+ log(&format!(+ "[liteparse] extract: {:.1}ms ({} pages)",+ web_time::Instant::now().duration_since(t0).as_secs_f64() * 1000.0,+ pages.len()+ ));+ (pages, Vec::new())+ }+ // `lib` is dropped here, releasing the PDFium lock.};let t1 = web_time::Instant::now();diff --git a/crates/liteparse/src/render.rs b/crates/liteparse/src/render.rsindex 53eb140..9328e04 100644--- a/crates/liteparse/src/render.rs+++ b/crates/liteparse/src/render.rs@@ -2,6 +2,7 @@ use crate::error::LiteParseError;use crate::extract::load_document_from_input;use crate::types::PdfInput;use image::ImageEncoder;+use pdfium::Library;use serde::Serialize;/// A single rendered page as PNG bytes.@@ -14,13 +15,19 @@ pub struct RenderedPage {}/// Render selected pages from a PDF input to PNG bytes.+///+/// Acquires the process-global PDFium lock for the entire render. The lock+/// is held until this function returns — PNG encoding happens inside the+/// critical section, which is fine because it is pure CPU work with no+/// `.await` points.pub fn render_pages_to_png(input: &PdfInput,page_numbers: Option<&[u32]>,dpi: f32,password: Option<&str>,) -> Result<Vec<RenderedPage>, LiteParseError> {- let document = load_document_from_input(input, password)?;+ let lib = Library::init();+ let document = load_document_from_input(&lib, input, password)?;render_document_pages(&document, page_numbers, dpi)}@@ -103,7 +110,8 @@ struct ImageBoundsOutput {/// Extract image bounding boxes and print as JSON to stdout.pub fn image_bounds(pdf_path: &str, page_num: Option<u32>) -> Result<(), LiteParseError> {- let document = load_document_from_input(&PdfInput::Path(pdf_path.to_string()), None)?;+ let lib = Library::init();+ let document = load_document_from_input(&lib, &PdfInput::Path(pdf_path.to_string()), None)?;let page_count = document.page_count();for page_index in 0..page_count {diff --git a/crates/liteparse/tests/integration_test.rs b/crates/liteparse/tests/integration_test.rsindex fe36746..186f2bd 100644--- a/crates/liteparse/tests/integration_test.rs+++ b/crates/liteparse/tests/integration_test.rs@@ -174,3 +174,54 @@ async fn test_parse_bytes_pdf_integration() {.expect("Should be able to parse");assert_eq!(parsed.pages.len(), 1);}++/// Stress test: many concurrent `parse_input` calls on a multi-threaded+/// tokio runtime through a single `Arc<LiteParse>`. Before the PDFium+/// process-global lock was introduced, this scenario caused malloc+/// double-free / heap corruption because PDFium FFI is not thread-safe.+///+/// We intentionally do **not** use `#[serial]` here — this test must run+/// concurrently with itself (across tasks within the test) to exercise the+/// lock. Other tests in this file are `#[serial]` so they won't race.+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]+async fn test_concurrent_parse_does_not_crash() {+ use std::sync::Arc;+ use tokio::task::JoinSet;++ let env_var = std::env::var("SKIP_INTEGRATION_TESTS");+ if let Ok(v) = env_var+ && v == "yes"+ {+ return;+ }++ let lit = Arc::new(LiteParse::new(LiteParseConfig {+ ocr_enabled: false,+ quiet: true,+ ..LiteParseConfig::default()+ }));++ let bytes = tokio::fs::read("../../integration_tests_data/sample.pdf")+ .await+ .expect("fixture exists");++ let mut set: JoinSet<usize> = JoinSet::new();+ for _ in 0..16 {+ let lit = lit.clone();+ let bytes = bytes.clone();+ set.spawn(async move {+ let parsed = lit+ .parse_input(PdfInput::Bytes(bytes))+ .await+ .expect("parse should succeed");+ parsed.pages.len()+ });+ }++ let mut total = 0;+ while let Some(joined) = set.join_next().await {+ total += joined.expect("task panicked");+ }+ // 16 tasks × 1 page each+ assert_eq!(total, 16);+}diff --git a/crates/pdfium/src/bitmap.rs b/crates/pdfium/src/bitmap.rsindex fc48ef5..011e0fc 100644--- a/crates/pdfium/src/bitmap.rs+++ b/crates/pdfium/src/bitmap.rs@@ -1,20 +1,37 @@+use std::marker::PhantomData;+use crate::error::PdfiumError;use crate::ffi;+use crate::library::Library;-pub struct Bitmap {+/// A BGRA pixel buffer owned by PDFium.+///+/// The `'lib` lifetime ties the bitmap to a held [`Library`] lock, so it+/// cannot be created (or destroyed via `Drop`) outside the PDFium critical+/// section.+pub struct Bitmap<'lib> {handle: pdfium_sys::FPDF_BITMAP,+ _lib: PhantomData<&'lib Library>,}-impl Bitmap {+impl<'lib> Bitmap<'lib> {/// Wrap an existing FPDF_BITMAP handle (takes ownership, will destroy on drop).////// # Safety- /// The handle must be a valid, non-null bitmap that the caller owns.+ /// The handle must be a valid, non-null bitmap that the caller owns,+ /// and the caller must hold a [`Library`] for at least `'lib`.pub unsafe fn from_handle(handle: pdfium_sys::FPDF_BITMAP) -> Self {- Bitmap { handle }+ Bitmap {+ handle,+ _lib: PhantomData,+ }}/// Create a new BGRA bitmap with the given dimensions.+ ///+ /// The caller must hold a [`Library`] for at least `'lib` — this is+ /// usually inferred from the call site (e.g. returning a `Bitmap<'lib>`+ /// from a method on `Page<'_, 'lib>`).pub fn new(width: i32, height: i32) -> Result<Self, PdfiumError> {let handle = unsafe {ffi!(FPDFBitmap_CreateEx(@@ -28,7 +45,10 @@ impl Bitmap {if handle.is_null() {return Err(PdfiumError::OperationFailed);}- Ok(Bitmap { handle })+ Ok(Bitmap {+ handle,+ _lib: PhantomData,+ })}pub fn handle(&self) -> pdfium_sys::FPDF_BITMAP {@@ -94,7 +114,7 @@ impl Bitmap {}}-impl Drop for Bitmap {+impl Drop for Bitmap<'_> {fn drop(&mut self) {unsafe { ffi!(FPDFBitmap_Destroy(self.handle)) };}diff --git a/crates/pdfium/src/document.rs b/crates/pdfium/src/document.rsindex 221809f..d511706 100644--- a/crates/pdfium/src/document.rs+++ b/crates/pdfium/src/document.rs@@ -1,17 +1,24 @@use crate::error::PdfiumError;use crate::ffi;+use crate::library::Library;use crate::page::Page;-pub struct Document {+/// An open PDF document.+///+/// The `'lib` lifetime ties this `Document` to the [`Library`] that opened+/// it, statically guaranteeing that no PDFium calls happen after the+/// process-wide PDFium lock has been released.+pub struct Document<'lib> {pub(crate) handle: pdfium_sys::FPDF_DOCUMENT,+ pub(crate) _lib: std::marker::PhantomData<&'lib Library>,}-impl Document {+impl<'lib> Document<'lib> {pub fn page_count(&self) -> i32 {unsafe { ffi!(FPDF_GetPageCount(self.handle)) }}- pub fn page(&self, index: i32) -> Result<Page<'_>, PdfiumError> {+ pub fn page(&self, index: i32) -> Result<Page<'_, 'lib>, PdfiumError> {let handle = unsafe { ffi!(FPDF_LoadPage(self.handle, index)) };if handle.is_null() {return Err(PdfiumError::PageNotFound);@@ -24,7 +31,7 @@ impl Document {}}-impl Drop for Document {+impl Drop for Document<'_> {fn drop(&mut self) {unsafe { ffi!(FPDF_CloseDocument(self.handle)) };}diff --git a/crates/pdfium/src/library.rs b/crates/pdfium/src/library.rsindex d6e7c64..a42dfde 100644--- a/crates/pdfium/src/library.rs+++ b/crates/pdfium/src/library.rs@@ -1,5 +1,7 @@use std::ffi::CString;use std::sync::Once;+#[cfg(not(target_arch = "wasm32"))]+use std::sync::{Mutex, MutexGuard, OnceLock};use crate::document::Document;use crate::error::PdfiumError;@@ -7,26 +9,101 @@ use crate::ffi;static INIT: Once = Once::new();+/// Process-global PDFium serialization lock.+///+/// PDFium's FFI is **not thread-safe**: concurrent calls (even across distinct+/// documents) corrupt internal state and cause heap UB (double-free / heap+/// corruption). Every [`Library`] handle holds this mutex for its entire+/// lifetime, and every PDFium resource ([`Document`], `Page`, `TextPage`,+/// `Bitmap`, `Font`) borrows from a [`Library`], so the borrow checker+/// statically prevents PDFium work outside the lock.+#[cfg(not(target_arch = "wasm32"))]+fn pdfium_lock() -> &'static Mutex<()> {+ static LOCK: OnceLock<Mutex<()>> = OnceLock::new();+ LOCK.get_or_init(|| Mutex::new(()))+}++/// A live, locked PDFium session.+///+/// Holding a `Library` proves the current thread has exclusive,+/// process-wide access to PDFium. All PDFium resources ([`Document`] etc.)+/// borrow from this handle, which makes it impossible to call into PDFium+/// without first acquiring the lock.+///+/// `Library` is intentionally **not `Clone`**. To use PDFium from a+/// different scope, call [`Library::init`] again — this will block until+/// any other in-flight PDFium work has finished.+///+/// On `wasm32` there is no threading, so the lock is elided.+///+/// The snippet below must fail to compile — a `Document` cannot outlive+/// the `Library` that opened it:+///+/// ```compile_fail+/// use liteparse_pdfium::{Library, Document};+/// let doc: Document<'static> = {+/// let lib = Library::init();+/// lib.load_document("x.pdf", None).unwrap()+/// };+/// // `lib` was dropped above — using `doc` here is a use-after-unlock.+/// let _ = doc.page_count();+/// ```pub struct Library {+ #[cfg(not(target_arch = "wasm32"))]+ _guard: MutexGuard<'static, ()>,+ #[cfg(target_arch = "wasm32")]_private: (),}impl Library {+ /// Acquire the process-wide PDFium lock, blocking the current thread+ /// until any other in-flight PDFium work has finished. Initializes the+ /// library on first call.+ ///+ /// Multiple concurrent callers are serialized; only one `Library`+ /// instance exists at a time.pub fn init() -> Library {#[cfg(not(target_arch = "wasm32"))]- pdfium_sys::dynamic::load_default().expect("failed to load pdfium shared library");+ {+ pdfium_sys::dynamic::load_default().expect("failed to load pdfium shared library");+ // Recover from poisoning: a panic mid-FFI may leave PDFium in+ // an odd state, but subsequent calls should still be allowed+ // (the worst case is that the next parse also fails cleanly).+ let guard = pdfium_lock()+ .lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner());+ INIT.call_once(|| unsafe { ffi!(FPDF_InitLibrary()) });+ Library { _guard: guard }+ }+ #[cfg(target_arch = "wasm32")]+ {+ INIT.call_once(|| unsafe { ffi!(FPDF_InitLibrary()) });+ Library { _private: () }+ }+ }- INIT.call_once(|| {- unsafe { ffi!(FPDF_InitLibrary()) };- });- Library { _private: () }+ /// Try to acquire the PDFium lock without blocking.+ ///+ /// Returns `None` if another thread currently holds the lock. Useful+ /// for callers that want to fail fast (or fall back to a worker queue)+ /// rather than block on contention.+ #[cfg(not(target_arch = "wasm32"))]+ pub fn try_init() -> Option<Library> {+ pdfium_sys::dynamic::load_default().expect("failed to load pdfium shared library");+ let guard = match pdfium_lock().try_lock() {+ Ok(g) => g,+ Err(std::sync::TryLockError::WouldBlock) => return None,+ Err(std::sync::TryLockError::Poisoned(p)) => p.into_inner(),+ };+ INIT.call_once(|| unsafe { ffi!(FPDF_InitLibrary()) });+ Some(Library { _guard: guard })}pub fn load_document(&self,path: &str,password: Option<&str>,- ) -> Result<Document, PdfiumError> {+ ) -> Result<Document<'_>, PdfiumError> {let c_path = CString::new(path).map_err(|_| PdfiumError::FileNotFound)?;let c_password = password.map(|p| CString::new(p).map_err(|_| PdfiumError::OperationFailed))@@ -43,14 +120,17 @@ impl Library {return Err(PdfiumError::from_last_error());}- Ok(Document { handle })+ Ok(Document {+ handle,+ _lib: std::marker::PhantomData,+ })}pub fn load_document_from_bytes(&self,data: &[u8],password: Option<&str>,- ) -> Result<Document, PdfiumError> {+ ) -> Result<Document<'_>, PdfiumError> {let c_password = password.map(|p| CString::new(p).map_err(|_| PdfiumError::OperationFailed)).transpose()?;@@ -71,6 +151,9 @@ impl Library {// The caller must ensure `data` lives long enough. For owned data,// consider passing a Vec and having the Document hold it.// For now, this is the caller's responsibility.- Ok(Document { handle })+ Ok(Document {+ handle,+ _lib: std::marker::PhantomData,+ })}}diff --git a/crates/pdfium/src/page.rs b/crates/pdfium/src/page.rsindex 2f36cd1..0f4ce55 100644--- a/crates/pdfium/src/page.rs+++ b/crates/pdfium/src/page.rs@@ -17,13 +17,18 @@ pub struct ImageBounds {pub height: f32,}-pub struct Page<'doc> {+/// A loaded page within a [`Document`].+///+/// The `'doc` lifetime ties the page to its owning document; `'lib` carries+/// the PDFium-lock lifetime through, ensuring no PDFium calls can occur+/// after the lock is released.+pub struct Page<'doc, 'lib: 'doc> {pub(crate) handle: pdfium_sys::FPDF_PAGE,pub(crate) doc_handle: pdfium_sys::FPDF_DOCUMENT,- pub(crate) _doc: PhantomData<&'doc Document>,+ pub(crate) _doc: PhantomData<&'doc Document<'lib>>,}-impl Page<'_> {+impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {pub fn width(&self) -> f32 {unsafe { ffi!(FPDF_GetPageWidthF(self.handle)) }}@@ -107,7 +112,7 @@ impl Page<'_> {}}- pub fn text(&self) -> Result<TextPage<'_>, PdfiumError> {+ pub fn text(&self) -> Result<TextPage<'_, 'lib>, PdfiumError> {let handle = unsafe { ffi!(FPDFText_LoadPage(self.handle)) };if handle.is_null() {return Err(PdfiumError::OperationFailed);@@ -119,7 +124,7 @@ impl Page<'_> {}/// Render the page to a BGRA bitmap at the given DPI.- pub fn render(&self, dpi: f32) -> Result<Bitmap, PdfiumError> {+ pub fn render(&self, dpi: f32) -> Result<Bitmap<'lib>, PdfiumError> {let scale = dpi / 72.0;let width = (self.width() * scale).round() as i32;let height = (self.height() * scale).round() as i32;@@ -209,7 +214,7 @@ impl Page<'_> {/// Get the rendered bitmap of a specific embedded image object by index./// The index corresponds to the order from iterating page objects (image objects only).- pub fn render_image_object(&self, image_obj_index: usize) -> Result<Bitmap, PdfiumError> {+ pub fn render_image_object(&self, image_obj_index: usize) -> Result<Bitmap<'lib>, PdfiumError> {let obj_count = unsafe { ffi!(FPDFPage_CountObjects(self.handle)) };let mut image_idx = 0usize;@@ -281,7 +286,7 @@ impl ViewportTransform {}}-impl Page<'_> {+impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {/// Build a `ViewportTransform` by probing 3 points through PDFium./// This makes 3 FFI calls total, after which all transforms are pure math.pub fn viewport_transform(&self, view_box: &RectF) -> ViewportTransform {@@ -300,7 +305,7 @@ impl Page<'_> {}}-impl Drop for Page<'_> {+impl Drop for Page<'_, '_> {fn drop(&mut self) {unsafe { ffi!(FPDF_ClosePage(self.handle)) };}diff --git a/crates/pdfium/src/text_page.rs b/crates/pdfium/src/text_page.rsindex 62b560b..876476e 100644--- a/crates/pdfium/src/text_page.rs+++ b/crates/pdfium/src/text_page.rs@@ -4,12 +4,16 @@ use crate::ffi;use crate::page::Page;use crate::types::{CharBox, Color, Matrix, RectF, TextRect};-pub struct TextPage<'page> {+/// Extracted text content of a [`Page`].+///+/// `'page` is the borrow of the parent page; `'lib` carries the PDFium-lock+/// lifetime through so that no FFI call can occur after the lock is released.+pub struct TextPage<'page, 'lib: 'page> {pub(crate) handle: pdfium_sys::FPDF_TEXTPAGE,- pub(crate) _page: PhantomData<&'page Page<'page>>,+ pub(crate) _page: PhantomData<&'page Page<'page, 'lib>>,}-impl TextPage<'_> {+impl<'page, 'lib: 'page> TextPage<'page, 'lib> {pub fn char_count(&self) -> i32 {unsafe { ffi!(FPDFText_CountChars(self.handle)) }}@@ -150,7 +154,7 @@ impl TextPage<'_> {}}-impl Drop for TextPage<'_> {+impl Drop for TextPage<'_, '_> {fn drop(&mut self) {unsafe { ffi!(FPDFText_ClosePage(self.handle)) };}@@ -159,7 +163,12 @@ impl Drop for TextPage<'_> {// -- TextChar: zero-cost view into a TextPage --pub struct TextChar<'tp> {- text_page: &'tp TextPage<'tp>,+ // We don't care about the inner lifetimes here — we only need to know+ // that we're borrowing the text page (and transitively the library lock)+ // for at least `'tp`. Using `'tp` for the inner params makes the type+ // covariant in `'tp` and lets borrow-checking flow naturally from the+ // outer borrow.+ text_page: &'tp TextPage<'tp, 'tp>,pub(crate) index: i32,}@@ -404,7 +413,7 @@ impl TextChar<'_> {// -- TextCharIter --pub struct TextCharIter<'tp> {- text_page: &'tp TextPage<'tp>,+ text_page: &'tp TextPage<'tp, 'tp>,index: i32,count: i32,}