mod child;
mod protocol;
#[cfg(test)]
mod tests;
use std::{
fmt,
path::{Path, PathBuf},
sync::{
Arc, Mutex as StdMutex,
atomic::{AtomicBool, Ordering},
},
time::Instant,
};
use tempfile::TempDir;
use tokio::{
sync::{OwnedSemaphorePermit, Semaphore, mpsc, oneshot, watch},
task::JoinHandle,
};
use super::{OfficialBundle, OfficialRequest, PACKAGE_VERSION, SCHEMA_VERSION};
use child::{PersistentChild, persistent_error_text, persistent_stderr_text};
use protocol::validate_persistent_request;
const LEGACY_INPUT_FORMATS: &[&str] = super::PERSISTENT_INPUT_FORMATS;
const SDK_INPUT_FORMATS: &[&str] = &[
"pdf", "png", "jpg", "jpeg", "webp", "gif", "bmp", "tiff", "jp2", "doc", "docx", "ppt", "pptx",
"xls", "xlsx", "rtf", "odt", "ods", "odp", "html", "htm", "shtml", "mhtml", "mht", "csv",
"tsv", "epub", "ofd",
];
#[derive(Clone)]
pub(crate) struct OfficialSessionConfig {
package_version: &'static str,
schema_version: &'static str,
model_base_dir: Option<PathBuf>,
config: Option<PathBuf>,
vlm_api_key: Option<String>,
vlm_model: Option<String>,
per_request_vlm: bool,
input_formats: &'static [&'static str],
}
impl fmt::Debug for OfficialSessionConfig {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("OfficialSessionConfig")
.field("package_version", &self.package_version)
.field("schema_version", &self.schema_version)
.field(
"model_base_dir",
&self.model_base_dir.as_ref().map(|_| "[configured]"),
)
.field("config", &self.config.as_ref().map(|_| "[configured]"))
.field(
"vlm_api_key",
&self.vlm_api_key.as_ref().map(|_| "[redacted]"),
)
.field("vlm_model", &self.vlm_model)
.field("per_request_vlm", &self.per_request_vlm)
.finish()
}
}
impl OfficialSessionConfig {
pub(crate) fn new(
model_base_dir: Option<PathBuf>,
config: Option<PathBuf>,
vlm_api_key: Option<String>,
vlm_model: Option<String>,
) -> Result<Self, String> {
Ok(Self {
package_version: PACKAGE_VERSION,
schema_version: SCHEMA_VERSION,
model_base_dir,
config,
vlm_api_key,
vlm_model,
per_request_vlm: false,
input_formats: LEGACY_INPUT_FORMATS,
})
}
pub(crate) fn for_official_sdk(
model_base_dir: Option<PathBuf>,
config: Option<PathBuf>,
) -> Result<Self, String> {
let mut session = Self::new(model_base_dir, config, None, None)?;
session.per_request_vlm = true;
session.input_formats = SDK_INPUT_FORMATS;
Ok(session)
}
fn matches_request(&self, request: &OfficialRequest) -> Result<(), String> {
if request.model_base_dir != self.model_base_dir
|| request.config != self.config
|| (!self.per_request_vlm
&& (request.vlm_api_key != self.vlm_api_key || request.vlm_model != self.vlm_model))
{
return Err("official persistent request does not match its session config".into());
}
Ok(())
}
}
pub(crate) struct OfficialPersistentWorker {
executable: PathBuf,
config: OfficialSessionConfig,
admission: Arc<Semaphore>,
commands: mpsc::Sender<PersistentCommand>,
shutdown: watch::Sender<bool>,
closed: AtomicBool,
receiver: Arc<StdMutex<Option<mpsc::Receiver<PersistentCommand>>>>,
owner: Arc<StdMutex<Option<JoinHandle<()>>>>,
}
struct PersistentCommand {
request: OfficialRequest,
temporary: TempDir,
permit: OwnedSemaphorePermit,
deadline: Instant,
cancel: oneshot::Receiver<()>,
response: oneshot::Sender<Result<OfficialBundle, String>>,
}
impl OfficialPersistentWorker {
pub(crate) fn new(
executable: Option<PathBuf>,
config: OfficialSessionConfig,
) -> Result<Self, String> {
let executable = super::process::official_executable(executable)?;
let (commands, receiver) = mpsc::channel(1);
let (shutdown, _) = watch::channel(false);
let owner = Arc::new(StdMutex::new(None));
let worker = Self {
executable,
config,
admission: Arc::new(Semaphore::new(1)),
commands,
shutdown,
closed: AtomicBool::new(false),
receiver: Arc::new(StdMutex::new(Some(receiver))),
owner,
};
Ok(worker)
}
fn spawn_owner(&self, shutdown: watch::Receiver<bool>) -> Result<(), String> {
let mut owner = self
.owner
.lock()
.map_err(|_| "official persistent owner lock poisoned".to_owned())?;
if owner.is_some() {
return Ok(());
}
if self.closed.load(Ordering::Acquire) {
return Err("official persistent worker is shut down".into());
}
let receiver = self
.receiver
.lock()
.map_err(|_| "official persistent receiver lock poisoned".to_owned())?
.take()
.ok_or_else(|| "official persistent owner receiver is unavailable".to_owned())?;
let executable = self.executable.clone();
let config = self.config.clone();
*owner = Some(tokio::spawn(async move {
persistent_owner_loop(receiver, executable, config, shutdown).await;
}));
Ok(())
}
pub(crate) async fn run(
&self,
input: &[u8],
suffix: &str,
request: OfficialRequest,
deadline: Instant,
) -> Result<OfficialBundle, String> {
self.run_owned(
bytes::Bytes::copy_from_slice(input),
suffix,
request,
deadline,
)
.await
}
pub(crate) async fn run_owned(
&self,
input: bytes::Bytes,
suffix: &str,
mut request: OfficialRequest,
deadline: Instant,
) -> Result<OfficialBundle, String> {
if self.closed.load(Ordering::Acquire) {
return Err("official persistent worker is shut down".into());
}
if input.is_empty() {
return Err("official Hybrid input is empty".into());
}
self.config.matches_request(&request)?;
validate_persistent_request(&request)?;
let permit = acquire_persistent_permit(&self.admission, &self.shutdown, deadline).await?;
if self.closed.load(Ordering::Acquire) {
drop(permit);
return Err("official persistent worker is shut down".into());
}
let stage = super::stage_input(input, suffix, Vec::new(), false, deadline).await?;
let temporary = stage.temporary;
let bundle = temporary.path().join(crate::hybrid_v4_output::BUNDLE_NAME);
request.input_path = stage.input_path;
request.bundle_path = bundle;
if Instant::now() >= deadline {
drop(permit);
return Err("official persistent worker deadline expired".into());
}
self.spawn_owner(self.shutdown.subscribe())?;
let (response, response_receiver) = oneshot::channel();
let (cancel, cancel_receiver) = oneshot::channel();
let command = PersistentCommand {
request,
temporary,
permit,
deadline,
cancel: cancel_receiver,
response,
};
let send = self.commands.send(command);
tokio::pin!(send);
let sleep = tokio::time::sleep_until(tokio::time::Instant::from_std(deadline));
tokio::pin!(sleep);
tokio::select! {
result = &mut send => {
result.map_err(|_| "official persistent owner task is unavailable".to_owned())?;
}
_ = &mut sleep => {
return Err("official persistent worker deadline expired".into());
}
}
match tokio::time::timeout_at(tokio::time::Instant::from_std(deadline), response_receiver)
.await
{
Ok(Ok(result)) => result,
Ok(Err(_)) => Err("official persistent owner task stopped".into()),
Err(_) => {
let _ = cancel.send(());
Err("official persistent worker deadline expired".into())
}
}
}
pub(crate) async fn shutdown(&self) -> Result<(), String> {
self.closed.store(true, Ordering::Release);
let _ = self.shutdown.send(true);
let handle = self
.owner
.lock()
.map_err(|_| "official persistent owner lock poisoned".to_owned())?
.take();
if let Some(handle) = handle {
handle
.await
.map_err(|error| format!("official persistent owner join failed: {error}"))?;
}
Ok(())
}
}
impl Drop for OfficialPersistentWorker {
fn drop(&mut self) {
self.closed.store(true, Ordering::Release);
let _ = self.shutdown.send(true);
let _ = self.owner.lock().ok().and_then(|mut owner| owner.take());
}
}
enum PersistentFailure {
Dead(String),
Document(String),
}
async fn ensure_persistent_session(
session: &mut Option<PersistentChild>,
executable: &Path,
config: &OfficialSessionConfig,
deadline: Instant,
cancel: &mut oneshot::Receiver<()>,
shutdown: &mut watch::Receiver<bool>,
) -> Result<(), PersistentFailure> {
if session.is_some() {
return Ok(());
}
let mut child = PersistentChild::spawn(executable).map_err(PersistentFailure::Dead)?;
if let Err(error) = child.handshake(config, deadline, cancel, shutdown).await {
let error = persistent_stderr_text(error, child.take_diagnostic());
child.shutdown().await;
return Err(PersistentFailure::Dead(error));
}
*session = Some(child);
Ok(())
}
async fn execute_persistent_request(
session: &mut Option<PersistentChild>,
executable: &Path,
config: &OfficialSessionConfig,
request: &OfficialRequest,
deadline: Instant,
cancel: &mut oneshot::Receiver<()>,
shutdown: &mut watch::Receiver<bool>,
) -> Result<(), PersistentFailure> {
ensure_persistent_session(session, executable, config, deadline, cancel, shutdown).await?;
let child = session
.as_mut()
.expect("persistent session was just initialized");
let frame = match child
.request(request, config, deadline, cancel, shutdown)
.await
{
Ok(frame) => frame,
Err(error) => {
return Err(PersistentFailure::Dead(persistent_stderr_text(
error,
child.take_diagnostic(),
)));
}
};
if frame.status == "error" {
return Err(PersistentFailure::Document(persistent_error_text(
"official persistent document failed".into(),
frame
.error
.as_deref()
.unwrap_or("official persistent document failed"),
frame.diagnostic.as_deref(),
child.take_diagnostic(),
)));
}
let _ = child.take_diagnostic();
Ok(())
}
async fn persistent_owner_loop(
mut receiver: mpsc::Receiver<PersistentCommand>,
executable: PathBuf,
config: OfficialSessionConfig,
mut shutdown: watch::Receiver<bool>,
) {
let mut session = None;
loop {
if *shutdown.borrow() {
break;
}
let command = tokio::select! {
changed = shutdown.changed() => {
let _ = changed;
break;
}
command = receiver.recv() => command,
};
let Some(command) = command else {
break;
};
let PersistentCommand {
request,
temporary,
permit,
deadline,
mut cancel,
response,
} = command;
let result = execute_persistent_request(
&mut session,
&executable,
&config,
&request,
deadline,
&mut cancel,
&mut shutdown,
)
.await;
let result = match result {
Ok(()) => Ok(OfficialBundle {
bundle: request.bundle_path.clone(),
_temporary: temporary,
_permit: Some(permit),
}),
Err(PersistentFailure::Document(error)) => Err(error),
Err(PersistentFailure::Dead(error)) => {
if let Some(child) = session.take() {
child.shutdown().await;
}
Err(error)
}
};
let _ = response.send(result);
}
if let Some(child) = session.take() {
child.shutdown().await;
}
}
async fn acquire_persistent_permit(
admission: &Arc<Semaphore>,
shutdown: &watch::Sender<bool>,
deadline: Instant,
) -> Result<OwnedSemaphorePermit, String> {
let mut shutdown = shutdown.subscribe();
if *shutdown.borrow() {
return Err("official persistent worker is shut down".into());
}
let acquire = admission.clone().acquire_owned();
tokio::pin!(acquire);
let sleep = tokio::time::sleep_until(tokio::time::Instant::from_std(deadline));
tokio::pin!(sleep);
tokio::select! {
permit = &mut acquire => permit.map_err(|_| "official persistent admission is closed".to_owned()),
_ = shutdown.changed() => Err("official persistent worker is shut down".into()),
_ = &mut sleep => Err("official persistent worker deadline expired".into()),
}
}