Skip to main content

rightkit_ocr/
worker.rs

1//! Isolated child-per-request native OCR worker (ViewRight `ocr_worker.rs`).
2//!
3//! Accurate Vision requests can fail on the target Mac with precompiled-
4//! operation errors once a process has served one, so each request runs in a
5//! short-lived child. Protocol: raw encoded image bytes on stdin, one bounded
6//! JSON [`WorkerResponse`] line on stdout. Paths, environment and recognized
7//! text are never written to stderr.
8//!
9//! Server side: call [`run_if_requested`] first thing in `main` (before any
10//! UI/single-instance init). Client side: [`WorkerCommand::run`], or
11//! [`WorkerCommand::run_observed`] when the host wants parent-side lifecycle events
12//! (child pid, wait, response, exit, timeout) and a [`RunRecord`] for diagnostics.
13//!
14//! ```rust,ignore
15//! let cmd = WorkerCommand::current_exe(DEFAULT_WORKER_ARG)?;
16//! let log = |event: WorkerEvent| tracing::info!(?event, "ocr_worker");
17//! match cmd.run_observed(&png, &log) {
18//!     Ok(run) => use_lines(run.lines),
19//!     Err(failure) => match failure.kind {
20//!         OcrErrorKind::WorkerTimeout => retry_later(),
21//!         _ => show_error(&failure.message),
22//!     },
23//! }
24//! ```
25
26use 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;
44/// Default deadline for one run and for one canary (see [`WorkerCommand::canary_deadline`]).
45///
46/// The child's own watchdog is fixed at this value and is not configurable through the
47/// parent: a larger `deadline` is still cut short by the child at 90 seconds.
48pub const WORKER_DEADLINE: Duration = Duration::from_secs(90);
49/// Exit code the worker uses when its own deadline fires.
50pub const SELF_DEADLINE_EXIT: i32 = 124;
51/// Default argv[1] selecting worker mode.
52pub 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/// One parent-side lifecycle fact from [`WorkerCommand::run_observed`].
64///
65/// Order for a child that was spawned: `Spawned`, `Waiting`, then either `TimedOut` followed by
66/// `Exited` (the parent's deadline killed it) or `Exited` followed by `TimedOut` (the child's own
67/// watchdog exited with [`SELF_DEADLINE_EXIT`]), and finally `Responded`. Every spawned child
68/// yields exactly one `Exited`. A run that never spawned emits no events.
69#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70#[non_exhaustive]
71pub enum WorkerEvent {
72    /// The child started. `pid` is its process id, for host diagnostics.
73    Spawned { pid: u32 },
74    /// The request was handed to the child and the parent is waiting within its deadline.
75    Waiting,
76    /// The child's stdout was captured. `bytes` is the captured length (up to the protocol limit)
77    /// and `elapsed` is measured from spawn.
78    Responded { bytes: usize, elapsed: Duration },
79    /// The child was reaped. `code` is `None` when it was killed by a signal or its status could
80    /// not be read; `success` is `true` only for a zero exit.
81    Exited { code: Option<i32>, success: bool },
82    /// The run ran out of time: the parent's deadline, or the child's watchdog exit code.
83    TimedOut,
84}
85
86/// Receives [`WorkerEvent`]s synchronously on the calling thread.
87///
88/// Any `Fn(WorkerEvent)` closure implements it, so `&|event| ...` works without a named type.
89/// Keep implementations quick and non-blocking, since the run waits on them.
90pub 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/// Facts about one isolated run, returned on success and carried by [`WorkerFailure`] on failure.
104#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
105#[serde(rename_all = "camelCase")]
106pub struct RunRecord {
107    /// Child process id; `None` when the child never started.
108    pub pid: Option<u32>,
109    /// Exit code; `None` for a signal kill or when the status was unavailable.
110    pub exit_code: Option<i32>,
111    /// `true` only when the child exited with status zero.
112    pub exit_success: bool,
113    /// Bytes captured from the child's stdout, up to the protocol limit.
114    pub response_bytes: usize,
115    /// Time from spawn to the end of the run (zero when the child never started).
116    pub elapsed: Duration,
117    /// `true` when the run ended by deadline, the parent's or the child's watchdog.
118    pub timed_out: bool,
119}
120
121/// A successful isolated run: the recognized lines and what happened.
122#[derive(Debug, Clone, PartialEq)]
123pub struct WorkerRun {
124    pub lines: Vec<OcrLine>,
125    pub record: RunRecord,
126}
127
128/// A failed isolated run: a typed kind, the legacy message text, and what happened.
129///
130/// `Display` is the legacy message (including any `...-unavailable:` prefix), so existing string
131/// comparisons keep working. Key on [`WorkerFailure::kind`].
132#[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/// How to launch the worker: the executable (usually the app itself, which
148/// calls [`run_if_requested`]) plus the selecting argument.
149#[derive(Debug, Clone)]
150pub struct WorkerCommand {
151    pub executable: PathBuf,
152    pub args: Vec<OsString>,
153    /// Deadline for one recognition run.
154    pub deadline: Duration,
155    /// Deadline for one canary run, separate from `deadline`. Defaults to [`WORKER_DEADLINE`],
156    /// so behavior is unchanged until a host sets it. A canary that gets only the budget left
157    /// after the request, as ViewRight does, can use [`WorkerCommand::with_canary_deadline`] to
158    /// give the check its own bound instead.
159    pub canary_deadline: Duration,
160}
161
162impl WorkerCommand {
163    /// Re-invoke the current executable with `arg` (the ViewRight shape).
164    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    /// Set the deadline for one recognition run.
184    pub fn with_deadline(mut self, deadline: Duration) -> Self {
185        self.deadline = deadline;
186        self
187    }
188
189    /// Set the deadline for canary runs, independently of [`WorkerCommand::with_deadline`].
190    pub fn with_canary_deadline(mut self, deadline: Duration) -> Self {
191        self.canary_deadline = deadline;
192        self
193    }
194
195    /// This command with its deadline replaced by [`WorkerCommand::canary_deadline`]. Use it for
196    /// canary requests (the embedded known-text PNG) so they get their own bound.
197    pub fn for_canary(&self) -> Self {
198        let mut canary = self.clone();
199        canary.deadline = self.canary_deadline;
200        canary
201    }
202
203    /// One isolated recognition request in a fresh child.
204    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    /// One isolated recognition request in a fresh child, reporting lifecycle events to `events`
212    /// as they happen and returning a [`RunRecord`] with the same facts.
213    ///
214    /// Use [`WorkerCommand::run`] when neither is needed; its behavior and messages are unchanged.
215    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
230/// If argv[1] equals `arg`, serve one request and exit; otherwise return
231/// `false` immediately. The worker never creates a window.
232pub 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    // The parent may die while Vision is inside its synchronous call; bound the
242    // child independently so losing the supervisor cannot leave it running.
243    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
330/// Kill and reap the child, returning its status when the reap succeeded.
331fn kill_and_reap(child: &mut Child) -> Option<ExitStatus> {
332    let _ = child.kill();
333    child.wait().ok()
334}
335
336/// How the parent's wait ended. Every variant carries the reaped status when it was available.
337enum 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    /// The fault that ended the wait before the child could answer, if any.
355    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        // The child reports its own failures as text; this is the one place they are typed.
421        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
437/// Emit `Exited` and fill the exit fields of the record.
438fn 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); // CREATE_NO_WINDOW: no visible console
470    }
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}