1use std::error::Error;
27use std::ffi::OsString;
28use std::fmt;
29use std::io::{self, Read, Write};
30use std::path::PathBuf;
31use std::process::{Child, Command, ExitStatus, Stdio};
32use std::sync::atomic::{AtomicBool, Ordering};
33use std::sync::Arc;
34use std::thread::{self, JoinHandle};
35use std::time::{Duration, Instant};
36
37use serde::{Deserialize, Serialize};
38
39use crate::types::{OcrErrorKind, OcrLine};
40
41pub const MAX_INPUT_BYTES: usize = 32 * 1024 * 1024;
42pub const MAX_OUTPUT_BYTES: usize = 8 * 1024 * 1024;
43const MAX_STDERR_BYTES: usize = 1024 * 1024;
44pub const WORKER_DEADLINE: Duration = Duration::from_secs(90);
49pub const SELF_DEADLINE_EXIT: i32 = 124;
51pub const DEFAULT_WORKER_ARG: &str = "--rightkit-ocr-worker";
53
54#[derive(Debug, Serialize, Deserialize)]
55pub struct WorkerResponse {
56 pub ok: bool,
57 #[serde(default, skip_serializing_if = "Option::is_none")]
58 pub lines: Option<Vec<OcrLine>>,
59 #[serde(default, skip_serializing_if = "Option::is_none")]
60 pub error: Option<String>,
61}
62
63#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70#[non_exhaustive]
71pub enum WorkerEvent {
72 Spawned { pid: u32 },
74 Waiting,
76 Responded { bytes: usize, elapsed: Duration },
79 Exited { code: Option<i32>, success: bool },
82 TimedOut,
84}
85
86pub trait WorkerEvents {
91 fn on_event(&self, event: WorkerEvent);
92}
93
94impl<F> WorkerEvents for F
95where
96 F: Fn(WorkerEvent),
97{
98 fn on_event(&self, event: WorkerEvent) {
99 self(event)
100 }
101}
102
103#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
105#[serde(rename_all = "camelCase")]
106pub struct RunRecord {
107 pub pid: Option<u32>,
109 pub exit_code: Option<i32>,
111 pub exit_success: bool,
113 pub response_bytes: usize,
115 pub elapsed: Duration,
117 pub timed_out: bool,
119}
120
121#[derive(Debug, Clone, PartialEq)]
123pub struct WorkerRun {
124 pub lines: Vec<OcrLine>,
125 pub record: RunRecord,
126}
127
128#[derive(Debug, Clone, PartialEq, Eq)]
133pub struct WorkerFailure {
134 pub kind: OcrErrorKind,
135 pub message: String,
136 pub record: RunRecord,
137}
138
139impl fmt::Display for WorkerFailure {
140 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
141 f.write_str(&self.message)
142 }
143}
144
145impl Error for WorkerFailure {}
146
147#[derive(Debug, Clone)]
150pub struct WorkerCommand {
151 pub executable: PathBuf,
152 pub args: Vec<OsString>,
153 pub deadline: Duration,
155 pub canary_deadline: Duration,
160}
161
162impl WorkerCommand {
163 pub fn current_exe(arg: &str) -> Result<Self, String> {
165 let executable = std::env::current_exe()
166 .map_err(|_| "OCR worker executable path unavailable".to_string())?;
167 Ok(Self::new(executable, [arg]))
168 }
169
170 pub fn new<I, S>(executable: impl Into<PathBuf>, args: I) -> Self
171 where
172 I: IntoIterator<Item = S>,
173 S: Into<OsString>,
174 {
175 Self {
176 executable: executable.into(),
177 args: args.into_iter().map(Into::into).collect(),
178 deadline: WORKER_DEADLINE,
179 canary_deadline: WORKER_DEADLINE,
180 }
181 }
182
183 pub fn with_deadline(mut self, deadline: Duration) -> Self {
185 self.deadline = deadline;
186 self
187 }
188
189 pub fn with_canary_deadline(mut self, deadline: Duration) -> Self {
191 self.canary_deadline = deadline;
192 self
193 }
194
195 pub fn for_canary(&self) -> Self {
198 let mut canary = self.clone();
199 canary.deadline = self.canary_deadline;
200 canary
201 }
202
203 pub fn run(&self, bytes: &[u8]) -> Result<Vec<OcrLine>, String> {
205 let silent = |_: WorkerEvent| {};
206 self.run_observed(bytes, &silent)
207 .map(|run| run.lines)
208 .map_err(|failure| failure.message)
209 }
210
211 pub fn run_observed(
216 &self,
217 bytes: &[u8],
218 events: &dyn WorkerEvents,
219 ) -> Result<WorkerRun, WorkerFailure> {
220 run_isolated(self, bytes, events)
221 }
222}
223
224#[derive(Debug)]
225struct CapturedOutput {
226 bytes: Vec<u8>,
227 exceeded: bool,
228}
229
230pub fn run_if_requested(arg: &str) -> bool {
233 if std::env::args().nth(1).as_deref() != Some(arg) {
234 return false;
235 }
236 run_worker_process()
237}
238
239fn run_worker_process() -> ! {
240 worker_event("start", "stdin");
241 thread::spawn(|| {
244 thread::sleep(WORKER_DEADLINE);
245 worker_event("timeout", "self-deadline");
246 std::process::exit(SELF_DEADLINE_EXIT);
247 });
248 let result = read_input_from(io::stdin())
249 .and_then(|bytes| {
250 let img = crate::types::decode_encoded(&bytes)?;
251 worker_event("start", "recognize");
252 crate::native::recognize_once(&img)
253 })
254 .map(|lines| WorkerResponse {
255 ok: true,
256 lines: Some(lines),
257 error: None,
258 })
259 .unwrap_or_else(|error| WorkerResponse {
260 ok: false,
261 lines: None,
262 error: Some(error),
263 });
264 worker_event(if result.ok { "success" } else { "failure" }, "recognize");
265 std::process::exit(write_response(result));
266}
267
268fn read_input_from(reader: impl Read) -> Result<Vec<u8>, String> {
269 let mut input = Vec::new();
270 reader
271 .take((MAX_INPUT_BYTES + 1) as u64)
272 .read_to_end(&mut input)
273 .map_err(|_| "OCR worker could not read request".to_string())?;
274 if input.len() > MAX_INPUT_BYTES {
275 return Err("OCR worker request exceeds the 32 MiB limit".to_string());
276 }
277 Ok(input)
278}
279
280fn write_response(response: WorkerResponse) -> i32 {
281 let mut encoded = match serde_json::to_vec(&response) {
282 Ok(bytes) => bytes,
283 Err(_) => return 1,
284 };
285 if encoded.len() > MAX_OUTPUT_BYTES {
286 encoded = serde_json::to_vec(&WorkerResponse {
287 ok: false,
288 lines: None,
289 error: Some("OCR worker result exceeds the 8 MiB limit".to_string()),
290 })
291 .expect("fixed worker error must serialize");
292 }
293 encoded.push(b'\n');
294 if io::stdout().write_all(&encoded).is_err() {
295 worker_event("failure", "stdout");
296 return 1;
297 }
298 0
299}
300
301fn worker_event(event: &str, stage: &str) {
302 eprintln!(
303 "ocr_worker event={event} pid={} stage={stage}",
304 std::process::id()
305 );
306}
307
308fn spawn_reader<R: Read + Send + 'static>(
309 mut reader: R,
310 limit: usize,
311 exceeded: Arc<AtomicBool>,
312) -> JoinHandle<CapturedOutput> {
313 thread::spawn(move || {
314 let mut bytes = Vec::new();
315 let read_result = reader
316 .by_ref()
317 .take((limit + 1) as u64)
318 .read_to_end(&mut bytes);
319 let over = bytes.len() > limit;
320 if read_result.is_err() || over {
321 exceeded.store(true, Ordering::Release);
322 }
323 CapturedOutput {
324 bytes,
325 exceeded: over,
326 }
327 })
328}
329
330fn kill_and_reap(child: &mut Child) -> Option<ExitStatus> {
332 let _ = child.kill();
333 child.wait().ok()
334}
335
336enum Settled {
338 Exited(ExitStatus),
339 DeadlineExceeded(Option<ExitStatus>),
340 OutputExceeded(Option<ExitStatus>),
341 WaitFailed(Option<ExitStatus>),
342}
343
344impl Settled {
345 fn status(&self) -> Option<ExitStatus> {
346 match *self {
347 Self::Exited(status) => Some(status),
348 Self::DeadlineExceeded(status)
349 | Self::OutputExceeded(status)
350 | Self::WaitFailed(status) => status,
351 }
352 }
353
354 fn fault(&self) -> Option<(OcrErrorKind, &'static str)> {
356 match self {
357 Self::Exited(_) => None,
358 Self::DeadlineExceeded(_) => Some((
359 OcrErrorKind::WorkerTimeout,
360 "OCR worker exceeded its deadline",
361 )),
362 Self::OutputExceeded(_) => Some((
363 OcrErrorKind::WorkerOutputExceeded,
364 "OCR worker output exceeds the bounded protocol limit",
365 )),
366 Self::WaitFailed(_) => {
367 Some((OcrErrorKind::WorkerFailed, "OCR worker process wait failed"))
368 }
369 }
370 }
371}
372
373fn wait_with_deadline(child: &mut Child, exceeded: &AtomicBool, deadline: Duration) -> Settled {
374 let until = Instant::now() + deadline;
375 loop {
376 if exceeded.load(Ordering::Acquire) {
377 return Settled::OutputExceeded(kill_and_reap(child));
378 }
379 match child.try_wait() {
380 Ok(Some(status)) => return Settled::Exited(status),
381 Ok(None) if Instant::now() >= until => {
382 return Settled::DeadlineExceeded(kill_and_reap(child));
383 }
384 Ok(None) => thread::sleep(Duration::from_millis(10)),
385 Err(_) => return Settled::WaitFailed(kill_and_reap(child)),
386 }
387 }
388}
389
390fn parse_response(
391 stdout: &[u8],
392 child_succeeded: bool,
393) -> Result<Vec<OcrLine>, (OcrErrorKind, String)> {
394 if stdout.len() > MAX_OUTPUT_BYTES {
395 return Err((
396 OcrErrorKind::WorkerOutputExceeded,
397 "OCR worker stdout exceeds the 8 MiB limit".to_string(),
398 ));
399 }
400 let response: WorkerResponse = serde_json::from_slice(stdout).map_err(|_| {
401 (
402 OcrErrorKind::WorkerProtocol,
403 "OCR worker returned malformed JSON".to_string(),
404 )
405 })?;
406 if !child_succeeded {
407 return Err((
408 OcrErrorKind::WorkerFailed,
409 "OCR worker exited with a failure status".to_string(),
410 ));
411 }
412 if response.ok {
413 response.lines.ok_or_else(|| {
414 (
415 OcrErrorKind::WorkerProtocol,
416 "OCR worker success response omitted lines".to_string(),
417 )
418 })
419 } else {
420 let message = response
422 .error
423 .unwrap_or_else(|| "OCR worker returned an unspecified error".to_string());
424 let kind = OcrErrorKind::from_message(&message).unwrap_or(OcrErrorKind::Runtime);
425 Err((kind, message))
426 }
427}
428
429fn failure(record: &RunRecord, kind: OcrErrorKind, message: impl Into<String>) -> WorkerFailure {
430 WorkerFailure {
431 kind,
432 message: message.into(),
433 record: record.clone(),
434 }
435}
436
437fn report_exit(status: Option<ExitStatus>, record: &mut RunRecord, events: &dyn WorkerEvents) {
439 record.exit_code = status.and_then(|s| s.code());
440 record.exit_success = status.is_some_and(|s| s.success());
441 events.on_event(WorkerEvent::Exited {
442 code: record.exit_code,
443 success: record.exit_success,
444 });
445}
446
447fn run_isolated(
448 cmd: &WorkerCommand,
449 bytes: &[u8],
450 events: &dyn WorkerEvents,
451) -> Result<WorkerRun, WorkerFailure> {
452 let mut record = RunRecord::default();
453 if bytes.len() > MAX_INPUT_BYTES {
454 return Err(failure(
455 &record,
456 OcrErrorKind::RequestTooLarge,
457 "OCR worker request exceeds the 32 MiB limit",
458 ));
459 }
460 let mut command = Command::new(&cmd.executable);
461 command
462 .args(&cmd.args)
463 .stdin(Stdio::piped())
464 .stdout(Stdio::piped())
465 .stderr(Stdio::piped());
466 #[cfg(windows)]
467 {
468 use std::os::windows::process::CommandExt;
469 command.creation_flags(0x0800_0000); }
471 let mut child = command.spawn().map_err(|_| {
472 failure(
473 &record,
474 OcrErrorKind::WorkerFailed,
475 "OCR worker process could not start",
476 )
477 })?;
478 let spawned_at = Instant::now();
479 let pid = child.id();
480 record.pid = Some(pid);
481 events.on_event(WorkerEvent::Spawned { pid });
482
483 let (Some(stdin), Some(stdout), Some(stderr)) =
484 (child.stdin.take(), child.stdout.take(), child.stderr.take())
485 else {
486 let status = kill_and_reap(&mut child);
487 report_exit(status, &mut record, events);
488 record.elapsed = spawned_at.elapsed();
489 return Err(failure(
490 &record,
491 OcrErrorKind::WorkerFailed,
492 "OCR worker pipes unavailable",
493 ));
494 };
495
496 let exceeded = Arc::new(AtomicBool::new(false));
497 let out_reader = spawn_reader(stdout, MAX_OUTPUT_BYTES, exceeded.clone());
498 let err_reader = spawn_reader(stderr, MAX_STDERR_BYTES, exceeded.clone());
499 let payload = bytes.to_vec();
500 let writer = thread::spawn(move || {
501 let mut stdin = stdin;
502 stdin
503 .write_all(&payload)
504 .map_err(|_| "OCR worker request write failed".to_string())
505 });
506
507 events.on_event(WorkerEvent::Waiting);
508 let settled = wait_with_deadline(&mut child, &exceeded, cmd.deadline);
509 let status = settled.status();
510 let fault = settled.fault();
511 if matches!(settled, Settled::DeadlineExceeded(_)) {
512 record.timed_out = true;
513 events.on_event(WorkerEvent::TimedOut);
514 }
515 report_exit(status, &mut record, events);
516 record.elapsed = spawned_at.elapsed();
517 if status.and_then(|s| s.code()) == Some(SELF_DEADLINE_EXIT) {
518 record.timed_out = true;
519 events.on_event(WorkerEvent::TimedOut);
520 }
521
522 let write_result = writer
523 .join()
524 .unwrap_or(Err("OCR worker request writer panicked".to_string()));
525 let out = out_reader.join().map_err(|_| {
526 failure(
527 &record,
528 OcrErrorKind::WorkerFailed,
529 "OCR worker stdout reader panicked",
530 )
531 })?;
532 let err = err_reader.join().map_err(|_| {
533 failure(
534 &record,
535 OcrErrorKind::WorkerFailed,
536 "OCR worker stderr reader panicked",
537 )
538 })?;
539 record.response_bytes = out.bytes.len();
540 record.elapsed = spawned_at.elapsed();
541 events.on_event(WorkerEvent::Responded {
542 bytes: out.bytes.len(),
543 elapsed: record.elapsed,
544 });
545
546 if let Some((kind, message)) = fault {
547 return Err(failure(&record, kind, message));
548 }
549 if status.and_then(|s| s.code()) == Some(SELF_DEADLINE_EXIT) {
550 return Err(failure(
551 &record,
552 OcrErrorKind::WorkerTimeout,
553 "OCR worker exceeded its deadline",
554 ));
555 }
556 if let Err(message) = write_result {
557 return Err(failure(&record, OcrErrorKind::WorkerFailed, message));
558 }
559 if out.exceeded || err.exceeded {
560 return Err(failure(
561 &record,
562 OcrErrorKind::WorkerOutputExceeded,
563 "OCR worker output exceeds the bounded protocol limit",
564 ));
565 }
566 match parse_response(&out.bytes, status.is_some_and(|s| s.success())) {
567 Ok(lines) => Ok(WorkerRun { lines, record }),
568 Err((kind, message)) => Err(failure(&record, kind, message)),
569 }
570}