A fast, helpful, and open-source document parser
feat: implement bounded sliding window for OCR tasks
Vivek Patel1d8a93c7c1db
diff --git a/crates/liteparse/src/ocr_merge.rs b/crates/liteparse/src/ocr_merge.rsindex 6ea2cbd..2a8a4b9 100644--- a/crates/liteparse/src/ocr_merge.rs+++ b/crates/liteparse/src/ocr_merge.rs@@ -56,6 +56,136 @@ pub(crate) struct RenderedPage {pub image_rects: Vec<ImageBounds>,}+type OcrTaskResult = Result<Vec<OcrResult>, Box<dyn std::error::Error + Send + Sync>>;+type OcrTaskMetadata = (usize, usize, f32, (bool, Vec<ImageBounds>));+type OcrTaskOutput = (usize, usize, f32, (bool, Vec<ImageBounds>), OcrTaskResult);++#[cfg(not(target_arch = "wasm32"))]+pub(crate) struct OcrTaskPool {+ max_workers: usize,+ engine: Arc<dyn OcrEngine>,+ language: String,+ tasks: tokio::task::JoinSet<OcrTaskOutput>,+ task_metadata: HashMap<tokio::task::Id, OcrTaskMetadata>,+ completed: Vec<OcrTaskOutput>,+}++#[cfg(not(target_arch = "wasm32"))]+impl OcrTaskPool {+ pub(crate) fn new(engine: Arc<dyn OcrEngine>, language: &str, num_workers: usize) -> Self {+ Self {+ max_workers: num_workers.max(1),+ engine,+ language: language.to_string(),+ tasks: tokio::task::JoinSet::new(),+ task_metadata: HashMap::new(),+ completed: Vec::new(),+ }+ }++ pub(crate) fn available_capacity(&self) -> usize {+ self.max_workers - self.tasks.len()+ }++ pub(crate) fn submit(&mut self, rendered: RenderedPage, page_number: usize) {+ assert!(+ self.tasks.len() < self.max_workers,+ "OCR task pool is at capacity"+ );++ let engine = self.engine.clone();+ let language = self.language.clone();+ let metadata = (+ rendered.idx,+ page_number,+ rendered.dpi,+ (rendered.has_native_text, rendered.image_rects.clone()),+ );+ let task_metadata = metadata.clone();+ let runtime = tokio::runtime::Handle::current();+ let task = self.tasks.spawn(async move {+ let options = OcrOptions {+ language,+ dpi: rendered.dpi,+ };+ let result = match tokio::task::spawn_blocking(move || {+ runtime.block_on(engine.recognize(+ &rendered.pixels,+ rendered.width,+ rendered.height,+ &options,+ ))+ })+ .await+ {+ Ok(result) => result,+ Err(join_err) => {+ Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)+ }+ };+ (+ task_metadata.0,+ task_metadata.1,+ task_metadata.2,+ task_metadata.3,+ result,+ )+ });+ self.task_metadata.insert(task.id(), metadata);+ }++ pub(crate) async fn complete_one(&mut self) {+ let joined = self+ .tasks+ .join_next_with_id()+ .await+ .expect("OCR task pool is empty");+ self.record_completion(joined);+ }++ pub(crate) fn complete_ready(&mut self) {+ while let Some(joined) = self.tasks.try_join_next_with_id() {+ self.record_completion(joined);+ }+ }++ fn record_completion(+ &mut self,+ joined: Result<(tokio::task::Id, OcrTaskOutput), tokio::task::JoinError>,+ ) {+ match joined {+ Ok((id, output)) => {+ self.task_metadata.remove(&id);+ self.completed.push(output);+ }+ Err(join_err) => {+ let metadata = self+ .task_metadata+ .remove(&join_err.id())+ .expect("OCR task metadata is missing");+ self.completed.push((+ metadata.0,+ metadata.1,+ metadata.2,+ metadata.3,+ Err(Box::new(join_err)),+ ));+ }+ }+ }++ pub(crate) async fn finish_and_merge(+ mut self,+ pages: &mut [Page],+ ocr_failure_fatal: bool,+ ) -> Result<(), LiteParseError> {+ while !self.tasks.is_empty() {+ self.complete_one().await;+ }+ merge_ocr_task_results(pages, self.completed, ocr_failure_fatal)+ }+}+/// Why a page was flagged as needing more than the cheap text-only path./// Multiple reasons can apply to one page (e.g. a sparse page whose little/// text is also garbled). Empty exactly when `needs_ocr` is false.@@ -724,6 +854,7 @@ pub(crate) fn render_pages_for_ocr(}/// Run OCR on pre-rendered page bitmaps and merge results into `pages`.+#[cfg(any(target_arch = "wasm32", test))]pub(crate) async fn ocr_and_merge_rendered(pages: &mut [Page],rendered: Vec<RenderedPage>,@@ -732,8 +863,6 @@ pub(crate) async fn ocr_and_merge_rendered(num_workers: usize,ocr_failure_fatal: bool,) -> Result<(), LiteParseError> {- type OcrTaskResult = Result<Vec<OcrResult>, Box<dyn std::error::Error + Send + Sync>>;-// Browser WASM uses the JavaScript event loop. It has no Tokio runtime or// blocking thread pool. Run each JavaScript OCR callback directly so the// returned Promise can make progress on the browser event loop.@@ -758,79 +887,29 @@ pub(crate) async fn ocr_and_merge_rendered(results};- // Phase 1: spawn one async task per page. A semaphore limits how many run- // `recognize` concurrently to `num_workers`.- //- // The permit MUST be acquired in async context (`acquire_owned().await`),- // not inside `spawn_blocking` via `block_on`. Acquiring it on a blocking- // thread parks that OS thread until a permit is free; with more pages than- // tokio's blocking pool (default `max_blocking_threads = 512`), every pool- // thread ends up parked waiting on the semaphore. The single task holding- // the permit then calls `recognize`, whose HTTP client resolves DNS via its- // own internal `spawn_blocking` — which can never get a thread, so the- // request never goes out, the permit is never released, and the whole OCR- // pass deadlocks. Acquiring the permit asynchronously parks the lightweight- // task instead, so only `num_workers` blocking threads are ever consumed.#[cfg(not(target_arch = "wasm32"))]- let task_results: Vec<(usize, usize, f32, (bool, Vec<ImageBounds>), OcrTaskResult)> = {- let num_workers = num_workers.max(1);- let semaphore = Arc::new(tokio::sync::Semaphore::new(num_workers));- let mut handles = Vec::with_capacity(rendered.len());-- let handle = tokio::runtime::Handle::current();-+ {+ let mut tasks = OcrTaskPool::new(ocr_engine, ocr_language, num_workers);for r in rendered {- let engine = ocr_engine.clone();- let sem = semaphore.clone();- let language = ocr_language.to_string();let page_number = pages[r.idx].page_number;- let rt_handle = handle.clone();-- handles.push((- r.idx,- page_number,- r.dpi,- (r.has_native_text, r.image_rects.clone()),- tokio::spawn(async move {- // Park the task (not an OS thread) until a permit is available.- let _permit = sem.acquire_owned().await.expect("semaphore closed");- let options = OcrOptions {- language,- dpi: r.dpi,- };- // Offload the (possibly CPU-blocking, e.g. Tesseract) recognize- // onto a blocking thread. Because the permit is already held,- // at most `num_workers` blocking threads are in use at once,- // leaving the rest of the pool free for the HTTP client's- // internal DNS resolution.- match tokio::task::spawn_blocking(move || {- rt_handle.block_on(engine.recognize(&r.pixels, r.width, r.height, &options))- })- .await- {- Ok(result) => result,- Err(join_err) => {- Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)- }- }- }),- ));+ if tasks.available_capacity() == 0 {+ tasks.complete_one().await;+ }+ tasks.submit(r, page_number);}+ return tasks.finish_and_merge(pages, ocr_failure_fatal).await;+ }- let mut results = Vec::with_capacity(handles.len());- for (idx, page_number, page_dpi, native, handle) in handles {- let result = match handle.await {- Ok(result) => result,- Err(join_err) => {- Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)- }- };- results.push((idx, page_number, page_dpi, native, result));- }- results- };+ #[cfg(target_arch = "wasm32")]+ merge_ocr_task_results(pages, task_results, ocr_failure_fatal)+}- // Phase 3: collect results and merge into pages.+fn merge_ocr_task_results(+ pages: &mut [Page],+ task_results: Vec<OcrTaskOutput>,+ ocr_failure_fatal: bool,+) -> Result<(), LiteParseError> {+ // Collect results and merge them into their source pages.// Track OCR task outcomes so we can distinguish a systemic failure (e.g.// missing Tesseract language data, which fails identically on every page)diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rsindex ed364ce..0574d46 100644--- a/crates/liteparse/src/parser.rs+++ b/crates/liteparse/src/parser.rs@@ -798,10 +798,9 @@ impl LiteParse {let t1 = web_time::Instant::now();if let Some(engine) = ocr_engine {- let round_rasters = self.config.num_workers.max(1);// Extraction may have flattened SOME pages' form widgets into- // page content in its (now dropped) document instance; re-apply- // per round on exactly those pages so the rasters match what+ // page content in its (now dropped) document instance; re-apply on+ // exactly those pages so the rasters match what// extraction saw. With `render_form_fields` the form environment// paints the widgets instead, so no re-flatten is needed.let reflatten_pages: std::collections::HashSet<u32> =@@ -811,16 +810,67 @@ impl LiteParse {std::collections::HashSet::new()};let ocr_input = repaired_input.as_ref().unwrap_or(validated_input);- let mut round_start = 0usize;- while round_start < pages.len() {+ let mut scan_start = 0usize;++ #[cfg(not(target_arch = "wasm32"))]+ let mut ocr_tasks = ocr_merge::OcrTaskPool::new(+ engine.clone(),+ &self.config.ocr_language,+ self.config.num_workers,+ );+ #[cfg(not(target_arch = "wasm32"))]+ loop {+ // Reap completions before deciding whether to render so every+ // available worker can be refilled immediately.+ ocr_tasks.complete_ready();++ if scan_start >= pages.len() {+ break;+ }++ let render_capacity = ocr_tasks.available_capacity();+ if render_capacity == 0 {+ ocr_tasks.complete_one().await;+ continue;+ }++ let (rendered, next_start) = {+ let lib = Library::init();+ let document = self.open_document(&lib, ocr_input, password)?;+ ocr_merge::render_pages_for_ocr(+ &document,+ &pages,+ scan_start,+ render_capacity,+ self.config.dpi,+ ocr_grayscale,+ self.config.render_form_fields,+ self.config.continue_on_page_error,+ &reflatten_pages,+ )?+ // `lib` drops here, releasing the PDFium lock before the+ // next await.+ };+ scan_start = next_start;++ for page in rendered {+ let page_number = pages[page.idx].page_number;+ ocr_tasks.submit(page, page_number);+ }+ }++ #[cfg(target_arch = "wasm32")]+ while scan_start < pages.len() {+ let render_capacity = self.config.num_workers.max(1);+let (rendered, next_start) = {let lib = Library::init();let document = self.open_document(&lib, ocr_input, password)?;ocr_merge::render_pages_for_ocr(&document,&pages,- round_start,- round_rasters,+ scan_start,+ render_capacity,self.config.dpi,ocr_grayscale,self.config.render_form_fields,@@ -830,14 +880,14 @@ impl LiteParse {// `lib` drops here, releasing the PDFium lock before the// engine's async recognition below.};- round_start = next_start;+ scan_start = next_start;if rendered.is_empty() {// The scan reached the end without finding another page// that needs OCR.continue;}- // `RenderedPage::idx` is absolute, so the whole slice is- // passed regardless of where this round started.++ // Browser callbacks run serially on the JavaScript event loop.ocr_merge::ocr_and_merge_rendered(&mut pages,rendered,@@ -848,6 +898,11 @@ impl LiteParse {).await?;}++ #[cfg(not(target_arch = "wasm32"))]+ ocr_tasks+ .finish_and_merge(&mut pages, self.config.ocr_failure_fatal)+ .await?;}let t_ocr = web_time::Instant::now();log(&format!(diff --git a/crates/liteparse/tests/integration_test.rs b/crates/liteparse/tests/integration_test.rsindex 1b0e5eb..658f61d 100644--- a/crates/liteparse/tests/integration_test.rs+++ b/crates/liteparse/tests/integration_test.rs@@ -741,14 +741,106 @@ impl liteparse::ocr::OcrEngine for ProbeEngine {}}-/// OCR runs in render→recognize rounds of `num_workers` pages. Whatever the-/// round size, every page must be recognized exactly once and each page's OCR-/// text must land on the page whose raster produced it — distinct page sizes-/// make a misroute visible, which is the failure mode the per-round document-/// reopen and form-widget re-flatten could introduce. `num_workers: 1` forces-/// one page per round (four rounds over four pages) and must also serialize-/// recognition; `num_workers: 4` covers the whole document in a single round-/// with overlapping recognition. Both must agree page-for-page.+struct RefillProbeEngine {+ calls: std::sync::Arc<std::sync::atomic::AtomicUsize>,+ in_flight: std::sync::Arc<std::sync::atomic::AtomicUsize>,+ peak_in_flight: std::sync::Arc<std::sync::atomic::AtomicUsize>,+ first_in_flight: std::sync::Arc<std::sync::atomic::AtomicBool>,+ refilled_while_first_in_flight: std::sync::Arc<std::sync::atomic::AtomicBool>,+}++impl liteparse::ocr::OcrEngine for RefillProbeEngine {+ fn name(&self) -> &str {+ "refill-probe"+ }++ fn recognize<'a, 'b: 'a, 'c: 'a>(+ &'a self,+ _image_data: &'c [u8],+ _width: u32,+ _height: u32,+ _options: &'b liteparse::ocr::OcrOptions,+ ) -> std::pin::Pin<+ Box<+ dyn Future<+ Output = Result<+ Vec<liteparse::ocr::OcrResult>,+ Box<dyn std::error::Error + Send + Sync>,+ >,+ > + Send+ + '_,+ >,+ > {+ use std::sync::atomic::Ordering;++ let call = self.calls.fetch_add(1, Ordering::SeqCst);+ let active = self.in_flight.fetch_add(1, Ordering::SeqCst) + 1;+ self.peak_in_flight.fetch_max(active, Ordering::SeqCst);+ if call == 0 {+ self.first_in_flight.store(true, Ordering::SeqCst);+ } else if call >= 2 && self.first_in_flight.load(Ordering::SeqCst) {+ self.refilled_while_first_in_flight+ .store(true, Ordering::SeqCst);+ }++ let first_in_flight = self.first_in_flight.clone();+ let in_flight = self.in_flight.clone();+ Box::pin(async move {+ if call == 0 {+ tokio::time::sleep(std::time::Duration::from_millis(200)).await;+ first_in_flight.store(false, Ordering::SeqCst);+ } else {+ tokio::time::sleep(std::time::Duration::from_millis(20)).await;+ }+ in_flight.fetch_sub(1, Ordering::SeqCst);+ Ok(Vec::new())+ })+ }+}++#[tokio::test]+#[serial]+async fn test_ocr_worker_is_refilled_before_slowest_request_finishes() {+ use std::sync::Arc;+ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};++ let calls = Arc::new(AtomicUsize::new(0));+ let peak = Arc::new(AtomicUsize::new(0));+ let refilled = Arc::new(AtomicBool::new(false));+ let parser = LiteParse::new(LiteParseConfig {+ ocr_enabled: true,+ num_workers: 2,+ dpi: 72.0,+ quiet: true,+ ..Default::default()+ })+ .with_ocr_engine(Arc::new(RefillProbeEngine {+ calls: calls.clone(),+ in_flight: Arc::new(AtomicUsize::new(0)),+ peak_in_flight: peak.clone(),+ first_in_flight: Arc::new(AtomicBool::new(false)),+ refilled_while_first_in_flight: refilled.clone(),+ }));++ parser+ .parse_input(PdfInput::Bytes(blank_pdf(&[(200, 200); 4])))+ .await+ .expect("OCR parse should succeed");++ assert_eq!(calls.load(Ordering::SeqCst), 4);+ assert_eq!(peak.load(Ordering::SeqCst), 2);+ assert!(+ refilled.load(Ordering::SeqCst),+ "a free OCR worker should start the next page without waiting for the slowest request"+ );+}++/// OCR keeps a bounded window of `num_workers` rendered pages. Every page must+/// be recognized exactly once and each page's OCR text must land on the page+/// whose raster produced it — distinct page sizes make a misroute visible when+/// the document is reopened to refill the window. `num_workers: 1` serializes+/// recognition; `num_workers: 4` overlaps the whole four-page document. Both+/// must agree page-for-page.#[tokio::test]#[serial]async fn test_ocr_rounds_cover_every_page_once() {@@ -804,7 +896,7 @@ async fn test_ocr_rounds_cover_every_page_once() {}};- // One page per round: four rounds, recognition fully serialized.+ // A one-page window keeps recognition fully serialized.let (parser, calls, peak) = run(1);let serialized = parser.parse_input(PdfInput::Bytes(blank_pdf(&page_sizes)))@@ -822,8 +914,8 @@ async fn test_ocr_rounds_cover_every_page_once() {"num_workers=1 must serialize recognition");- // Round wide enough for the whole document: one round, overlapping- // recognition, identical routing.+ // A window wide enough for the document overlaps recognition while+ // preserving identical routing.let (parser, calls, peak) = run(4);let overlapped = parser.parse_input(PdfInput::Bytes(blank_pdf(&page_sizes)))@@ -837,9 +929,9 @@ async fn test_ocr_rounds_cover_every_page_once() {);}-/// A round is bounded by rasters rendered, not by page span, so OCR-needing-/// pages that are sparsely scattered through a mostly-native-text document-/// still fill a round and recognize concurrently.+/// The initial window is bounded by rasters rendered, not by page span, so+/// OCR-needing pages sparsely scattered through a mostly-native-text document+/// still fill the worker pool and recognize concurrently.////// This guards a real regression: bounding the round by page span instead/// made each round contain only the OCR-needing pages that happened to fall@@ -883,13 +975,13 @@ async fn test_ocr_rounds_fill_across_sparse_pages() {among its {} pages",result.pages.len());- // The scan-ahead must gather a full round even though the OCR-needing+ // The scan-ahead must fill the worker pool even though the OCR-needing// pages are interleaved with native-text pages it skips.assert_eq!(peak.load(Ordering::SeqCst),8,- "rounds must fill to num_workers across skipped pages; a lower peak means \- rounds are being cut short by page span"+ "the OCR window must fill to num_workers across skipped pages; a lower peak means \+ the window is being cut short by page span");}