A fast, helpful, and open-source document parser
merge main, fix PR
Logan Markewich072eb638e7fb
diff --cc crates/liteparse/src/ocr_merge.rsindex b0744f0,ad7124a..6346f7e--- a/crates/liteparse/src/ocr_merge.rs+++ b/crates/liteparse/src/ocr_merge.rs@@@ -126,157 -126,6 +126,154 @@@ mod base64_bytes}}+type OcrTaskResult = Result<Vec<OcrResult>, Box<dyn std::error::Error + Send + Sync>>;- /// `(page_number, dpi, has_native_text, image_rects)` carried alongside a- /// running recognition so a completion can become a [`PageOcrOutcome`]- /// without the raster.- type OcrTaskMetadata = (usize, f32, bool, Vec<Rect>);- type OcrTaskOutput = (usize, f32, bool, Vec<Rect>, OcrTaskResult);+++impl PageOcrOutcome {++ /// The outcome for `raster` before recognition: its page facts, no++ /// results yet. Lets the pixels go to the engine while the small facts++ /// wait for the result.++ fn pending(raster: &OcrRaster) -> Self {++ Self {++ page_number: raster.page_number,++ dpi: raster.dpi,++ has_native_text: raster.has_native_text,++ image_rects: raster.image_rects.clone(),++ results: Vec::new(),++ error: None,++ }++ }++++ fn with_result(mut self, result: OcrTaskResult) -> Self {++ match result {++ Ok(results) => self.results = results,++ Err(error) => self.error = Some(error.to_string()),++ }++ self++ }++}++++/// At most `max_workers` recognitions in flight; a slot frees as soon as its++/// recognition finishes, so the caller can refill it without waiting on the++/// slowest request.++///++/// Each recognition runs on a blocking thread (Tesseract is CPU-bound). A++/// task is only spawned once a slot is free, so at most `max_workers`++/// blocking threads are ever in use. That bound is load-bearing: the HTTP++/// engine's client resolves DNS through its own `spawn_blocking`, and if++/// every pool thread were parked waiting for a slot, that lookup could never++/// run and the whole OCR pass would deadlock.++///++/// Dropping the pool aborts the async tasks, but a recognition already on a++/// blocking thread runs to completion in the background and is discarded.+#[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>,++ tasks: tokio::task::JoinSet<OcrTaskResult>,++ /// Submission index and pending outcome for each running task.++ running: HashMap<tokio::task::Id, (usize, PageOcrOutcome)>,++ completed: Vec<(usize, PageOcrOutcome)>,++ submitted: usize,+}++#[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(),++ running: HashMap::new(),+ completed: Vec::new(),++ submitted: 0,+ }+ }++ pub(crate) fn available_capacity(&self) -> usize {+ self.max_workers - self.tasks.len()+ }+- pub(crate) fn submit(&mut self, rendered: OcrRaster) {- assert!(- self.tasks.len() < self.max_workers,- "OCR task pool is at capacity"- );++ /// Start recognition for `raster`, first waiting for a free slot if the++ /// pool is full.++ pub(crate) async fn submit(&mut self, raster: OcrRaster) {++ while self.available_capacity() == 0 {++ self.complete_one().await;++ }+++ let pending = PageOcrOutcome::pending(&raster);+ let engine = self.engine.clone();- let language = self.language.clone();- let metadata = (- rendered.page_number,- rendered.dpi,- rendered.has_native_text,- rendered.image_rects.clone(),- );- let task_metadata = metadata.clone();++ let options = OcrOptions {++ language: self.language.clone(),++ dpi: raster.dpi,++ };+ 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 || {++ match tokio::task::spawn_blocking(move || {+ runtime.block_on(engine.recognize(- &rendered.pixels,- rendered.width,- rendered.height,++ &raster.pixels,++ raster.width,++ raster.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,- )++ Err(join_err) => Err(Box::new(join_err) as _),++ }+ });- self.task_metadata.insert(task.id(), metadata);++ self.running.insert(task.id(), (self.submitted, pending));++ self.submitted += 1;+ }+- 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);++ /// Wait for one running recognition to finish and record it. Returns++ /// `false` (without waiting) when nothing is running.++ pub(crate) async fn complete_one(&mut self) -> bool {++ match self.tasks.join_next_with_id().await {++ Some(joined) => {++ self.record_completion(joined);++ true++ }++ None => false,++ }+ }++ 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>,++ joined: Result<(tokio::task::Id, OcrTaskResult), 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;- }- let outcomes = self- .completed++ let (id, result) = match joined {++ Ok((id, result)) => (id, result),++ Err(join_err) => (join_err.id(), Err(Box::new(join_err) as _)),++ };++ let (order, pending) = self++ .running++ .remove(&id)++ .expect("every spawned OCR task is tracked");++ self.completed.push((order, pending.with_result(result)));++ }++++ /// Wait for the remaining recognitions. Outcomes come back in submission++ /// order, not completion order, so the result (and which failure the++ /// merge reports first) does not depend on request timing.++ pub(crate) async fn finish(mut self) -> Vec<PageOcrOutcome> {++ while self.complete_one().await {}++ self.completed.sort_by_key(|(order, _)| *order);++ self.completed+ .into_iter()- .map(|(page_number, dpi, has_native_text, image_rects, result)| {- let (results, error) = match result {- Ok(results) => (results, None),- Err(error) => (Vec::new(), Some(error.to_string())),- };- PageOcrOutcome {- page_number,- dpi,- has_native_text,- image_rects,- results,- error,- }- })- .collect();- merge_ocr_results(pages, outcomes, ocr_failure_fatal)++ .map(|(_, outcome)| outcome)++ .collect()+ }+}+/// 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.@@@ -824,9 -673,9 +821,22 @@@ pub fn render_pages_for_ocrpages: &[Page],start: usize,options: &OcrRenderOptions,++) -> Result<(Vec<OcrRaster>, usize), LiteParseError> {++ render_pages_for_ocr_capped(document, pages, start, options, options.max_rasters)++}++++/// [`render_pages_for_ocr`] with `max_rasters` overriding the one in++/// `options`, so a caller sizing each round to its free OCR slots need not++/// clone the options.++pub(crate) fn render_pages_for_ocr_capped(++ document: &Document,++ pages: &[Page],++ start: usize,++ options: &OcrRenderOptions,++ max_rasters: usize,) -> Result<(Vec<OcrRaster>, usize), LiteParseError> {let OcrRenderOptions {-- max_rasters,++ max_rasters: _,dpi,grayscale,render_form_fields,@@@ -834,8 -683,8 +844,7 @@@reflatten_pages: flatten_page_numbers,selection,} = options;-- let (max_rasters, dpi, grayscale, render_form_fields, continue_on_page_error) = (-- *max_rasters,++ let (dpi, grayscale, render_form_fields, continue_on_page_error) = (*dpi,*grayscale,*render_form_fields,@@@ -1010,121 -859,121 +1019,34 @@@ pub async fn recognize_rastersocr_language: &str,num_workers: usize,) -> Vec<PageOcrOutcome> {-- 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.#[cfg(target_arch = "wasm32")]-- let task_results: Vec<(usize, f32, (bool, Vec<Rect>), OcrTaskResult)> = {++ {let _ = num_workers;-- let mut results = Vec::with_capacity(rendered.len());++ let mut outcomes = Vec::with_capacity(rendered.len());for r in rendered {-- let page_number = r.page_number;-- let page_dpi = r.dpi;-- let native = (r.has_native_text, r.image_rects.clone());let options = OcrOptions {language: ocr_language.to_string(),-- dpi: page_dpi,++ dpi: r.dpi,};let result = ocr_engine.recognize(&r.pixels, r.width, r.height, &options).await;-- results.push((page_number, page_dpi, native, result));++ outcomes.push(PageOcrOutcome::pending(&r).with_result(result));}-- results-- };++ outcomes++ }-- // 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, f32, (bool, Vec<Rect>), 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 pool = 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 = r.page_number;-- let rt_handle = handle.clone();---- handles.push((-- 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>)-- }-- }-- }),-- ));- }-- let mut results = Vec::with_capacity(handles.len());- for (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((page_number, page_dpi, native, result));++ pool.submit(r).await;}-- let mut results = Vec::with_capacity(handles.len());- for (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((page_number, page_dpi, native, result));- }-- results-- };---- task_results-- .into_iter()-- .map(-- |(page_number, dpi, (has_native_text, image_rects), result)| {-- let (results, error) = match result {-- Ok(results) => (results, None),-- Err(e) => (Vec::new(), Some(e.to_string())),-- };-- PageOcrOutcome {-- page_number,-- dpi,-- has_native_text,-- image_rects,-- results,-- error,-- }-- },-- )-- .collect()++ pool.finish().await++ }}/// Merge recognition outcomes into `pages`, in place. Pure: needs neither the@@@ -2439,6 -2393,6 +2466,65 @@@ mod tests);}++ /// Sleeps longer for lower DPIs, then fails with a message naming the DPI,++ /// so completion order is the reverse of submission order and each++ /// outcome shows which raster it came from.++ struct ReverseLatencyEngine;++++ impl OcrEngine for ReverseLatencyEngine {++ fn name(&self) -> &str {++ "reverse-latency"++ }++++ fn recognize<'a, 'b: 'a, 'c: 'a>(++ &'a self,++ _image_data: &'c [u8],++ _width: u32,++ _height: u32,++ options: &'b OcrOptions,++ ) -> std::pin::Pin<Box<dyn std::future::Future<Output = OcrTaskResult> + Send + 'a>>++ {++ let dpi = options.dpi;++ Box::pin(async move {++ let delay = (100.0 - dpi).max(0.0) as u64 * 5;++ tokio::time::sleep(std::time::Duration::from_millis(delay)).await;++ Err(format!("dpi {dpi}").into())++ })++ }++ }++++ // Outcomes come back in submission order whatever order recognitions++ // finish in, with each result attached to its own raster's facts. Five++ // rasters over two workers also exercises `submit` waiting for a slot.++ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]++ async fn test_recognize_returns_submission_order() {++ let rendered = (0..5)++ .map(|i| OcrRaster {++ dpi: 72.0 + i as f32 * 4.0,++ ..make_rendered(i)++ })++ .collect();++ let engine: Arc<dyn OcrEngine> = Arc::new(ReverseLatencyEngine);++++ let outcomes = recognize_rasters(rendered, engine, "eng", 2).await;++++ let got: Vec<(usize, String)> = outcomes++ .iter()++ .map(|o| (o.page_number, o.error.clone().unwrap_or_default()))++ .collect();++ let want: Vec<(usize, String)> = (0..5)++ .map(|i| (i + 1, format!("dpi {}", 72.0 + i as f32 * 4.0)))++ .collect();++ assert_eq!(got, want);++ }++++ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]++ async fn test_empty_pool_complete_one_does_not_wait() {++ let mut pool = OcrTaskPool::new(Arc::new(FailingEngine), "eng", 2);++ assert!(!pool.complete_one().await);++ assert!(pool.finish().await.is_empty());++ }++// With no rendered pages there is nothing to OCR; this must remain a no-op// success rather than tripping the all-failed guard.#[tokio::test(flavor = "multi_thread", worker_threads = 2)]diff --cc crates/liteparse/src/parser.rsindex a05209a,6f1581d..6ba101f--- a/crates/liteparse/src/parser.rs+++ b/crates/liteparse/src/parser.rs@@@ -793,61 -790,10 +790,67 @@@ impl LiteParselet t1 = web_time::Instant::now();if let Some(engine) = ocr_engine {+ // `ocr_render_options` already carries the re-flatten set and a- // `max_rasters` cap of `num_workers`. Native parses override that- // cap with the number of free workers so a finished request- // refills the window without waiting out the rest of a batch.- #[cfg(not(target_arch = "wasm32"))]- let mut render_options = ocr_render_options;- #[cfg(target_arch = "wasm32")]++ // `max_rasters` cap of `num_workers`. Native parses ignore that++ // cap and render only as many pages as there are free workers,++ // so a finished request refills the window without waiting out++ // the rest of a batch.let render_options = ocr_render_options;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 = stages::OcrWindow::new(+ engine.clone(),+ &self.config.ocr_language,+ self.config.num_workers,+ );+ 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 {++ if ocr_tasks.available_capacity() == 0 {+ ocr_tasks.complete_one().await;+ continue;+ }+- render_options.max_rasters = render_capacity;++ // Each refill reopens the document, often for a single++ // page. That costs a few ms (measured 1-12 ms on large++ // PDFs), small next to one OCR request, and the PDFium++ // lock cannot be held across the awaits. A render error++ // returns here; dropping `ocr_tasks` abandons in-flight++ // recognitions.+ let (rendered, next_start) = {+ let lib = Library::init();+ let document = self.open_document(&lib, ocr_input, password)?;- stages::render_for_ocr(&document, &pages, scan_start, &render_options)?++ ocr_tasks.render_next(&document, &pages, scan_start, &render_options)?+ // `lib` drops here, releasing the PDFium lock before the+ // next await.+ };+ scan_start = next_start;++ for raster in rendered {- ocr_tasks.submit(raster);++ ocr_tasks.submit(raster).await;+ }+ }++ ocr_tasks- .finish_and_merge(&mut pages, self.config.ocr_failure_fatal)++ .finish_and_merge(++ &mut pages,++ self.config.ocr_failure_fatal,++ self.config.effective_emit_word_boxes(),++ )+ .await?;+ }++ #[cfg(target_arch = "wasm32")]+ while scan_start < pages.len() {let (rendered, next_start) = {let lib = Library::init();let document = self.open_document(&lib, ocr_input, password)?;diff --cc crates/liteparse/src/stages.rsindex 588bc90,7b46a32..a0472a8--- a/crates/liteparse/src/stages.rs+++ b/crates/liteparse/src/stages.rs@@@ -240,61 -240,6 +240,90 @@@ pub async fn recognizeocr_merge::recognize_rasters(rasters, engine, language, num_workers).await}+/// In-flight OCR recognitions for a sliding render window.+///+/// [`recognize`] waits for every raster in the batch it was given.+/// [`LiteParse::parse`](crate::LiteParse::parse) instead keeps at most+/// `num_workers` recognitions running and renders the next page as soon as+/// one finishes, so a slow page does not idle the other workers. Raster- /// memory stays bounded by `num_workers`: pass- /// [`OcrWindow::available_capacity`] as [`OcrRenderOptions::max_rasters`].++/// memory stays bounded by `num_workers` when each round is rendered with++/// [`OcrWindow::render_next`], which renders no more pages than there are++/// free slots.+///+/// Browser WASM has no blocking thread pool, so `parse` uses [`recognize`]+/// there. This type exists only on native targets.+#[cfg(not(target_arch = "wasm32"))]+pub struct OcrWindow {+ inner: ocr_merge::OcrTaskPool,+}++#[cfg(not(target_arch = "wasm32"))]+impl OcrWindow {+ /// Start a window that will run at most `num_workers` recognitions at once.+ pub fn new(engine: Arc<dyn OcrEngine>, language: &str, num_workers: usize) -> Self {+ Self {+ inner: ocr_merge::OcrTaskPool::new(engine, language, num_workers),+ }+ }+- /// How many more rasters can be submitted without exceeding `num_workers`.++ /// How many more rasters can be submitted without waiting.+ pub fn available_capacity(&self) -> usize {+ self.inner.available_capacity()+ }+++ /// [`render_for_ocr`] capped at [`available_capacity`](Self::available_capacity)++ /// (`options.max_rasters` is ignored). Renders nothing, and returns++ /// `start` unchanged, when the window is full.++ pub fn render_next(++ &self,++ document: &Document,++ pages: &[Page],++ start: usize,++ options: &OcrRenderOptions,++ ) -> Result<(Vec<OcrRaster>, usize), LiteParseError> {++ match self.available_capacity() {++ 0 => Ok((Vec::new(), start)),++ capacity => {++ ocr_merge::render_pages_for_ocr_capped(document, pages, start, options, capacity)++ }++ }++ }+++ /// Record recognitions that have already finished, without waiting.+ pub fn complete_ready(&mut self) {+ self.inner.complete_ready()+ }+- /// Wait until one in-flight recognition finishes and record it.- pub async fn complete_one(&mut self) {++ /// Wait until one in-flight recognition finishes and record it. Returns++ /// `false` without waiting when nothing is in flight.++ pub async fn complete_one(&mut self) -> bool {+ self.inner.complete_one().await+ }+- /// Start recognition for one raster. Panics if the window is already full.- pub fn submit(&mut self, raster: OcrRaster) {- self.inner.submit(raster)++ /// Start recognition for one raster, first waiting for a free slot if the++ /// window is full.++ pub async fn submit(&mut self, raster: OcrRaster) {++ self.inner.submit(raster).await+ }+- /// Wait for the remaining recognitions and merge them into `pages`.++ /// Wait for the remaining recognitions and return every outcome, in++ /// submission order.++ pub async fn finish(self) -> Vec<PageOcrOutcome> {++ self.inner.finish().await++ }++++ /// [`finish`](Self::finish), then [`merge_ocr`] the outcomes into `pages`.+ pub async fn finish_and_merge(+ self,+ pages: &mut [Page],+ ocr_failure_fatal: bool,++ emit_word_boxes: bool,+ ) -> Result<(), LiteParseError> {- self.inner.finish_and_merge(pages, ocr_failure_fatal).await++ let outcomes = self.finish().await;++ merge_ocr(pages, outcomes, ocr_failure_fatal, emit_word_boxes)+ }+}+/// Merge recognition outcomes into `pages` in place: drop unusable native/// text, filter engine artifacts, append the surviving results as `OCR`/// text items in viewport points. Errors only when every outcome failed and