Turn any document into clean, AI-ready Markdown. Local-first desktop app: reads scanned PDFs, batches folders, runs offline, and uses far fewer tokens than vision models.
Python desktop-appdocument-conversionllmlocal-firstmarkdownmarkitdownocrofflinepdf-to-markdownragrustsveltetauri
"""
Sidecar entry point — asyncio NDJSON IPC v1.
Three concurrent concerns on the same event loop:
1. Stdin reader — reads requests from Rust via run_in_executor (non-blocking).
2. Conversion tasks — one asyncio.Task per convert-one request; keyed by request id.
3. Provider checks — background tasks, separate from conversion.
IPC v1 protocol:
Request: {"v":1, "id":"<str>", "method":"<str>", "params":{}}
Success: {"v":1, "id":"<str>", "ok":true, "result":<value>}
Failure: {"v":1, "id":"<str>", "ok":false, "error":{"code","title","detail","suggested_action"}}
Progress: {"v":1, "id":"<conv-id>", "type":"progress", "stage":"<str>", "frac":<float|null>, "heartbeat":<int>}
Concurrent convert-one requests are supported. Each request gets its
own asyncio.Event for cancellation, keyed by request id. "cancel" with no id
cancels all; with an "id" param it cancels one specific conversion.
"""
import asyncio
import importlib
import json
import os
import sys
import time
from pathlib import Path
import capabilities as _caps
import cleanup as _cleanup_mod
import health
import preflight
import provider as _provider
from errors import (
CANCELLED,
FILE_NOT_FOUND,
INTERNAL_ERROR,
MISSING_EXTRA,
TIMEOUT,
UNSUPPORTED_FORMAT,
err,
)
TIMEOUT_SECS: int = 120
OCR_TIMEOUT_SECS: int = 600
AUDIO_TIMEOUT_SECS: int = 600
# Online-only cloud files (OneDrive Files On-Demand) must be downloaded on first read;
# a large one on a slow link can take a while, so a cloud file gets the long budget.
CLOUD_TIMEOUT_SECS: int = 600
# The worker returns the whole conversion result as one NDJSON line. asyncio's
# StreamReader defaults to a 64 KiB line limit, which a large document blows past
# ("Separator is not found, and chunk exceed the limit"). Raise it generously —
# input is already capped at 100 MB by preflight, so extracted text stays bounded.
WORKER_STREAM_LIMIT: int = 256 * 1024 * 1024
_SIDECAR_DIR: Path = Path(__file__).parent
class Sidecar:
def __init__(self) -> None:
self._write_lock: asyncio.Lock = asyncio.Lock()
self._background_tasks: set[asyncio.Task] = set()
# Per-conversion cancel events keyed by request id.
# Populated on convert-one, removed in _convert_safe's finally block.
self._cancel_events: dict[str, asyncio.Event] = {}
# Cap concurrent worker subprocesses so a 50-item batch doesn't spawn 50
# MarkItDown/OCR/Whisper processes at once (multi-GB RAM, thrash). Defense-in-depth
# even though Rust also serializes via its batch semaphore.
cpu = os.cpu_count() or 4
self._worker_sem = asyncio.Semaphore(max(2, min(8, cpu // 2)))
# Track active worker subprocesses so we can kill them on shutdown (M11).
self._active_procs: set[asyncio.subprocess.Process] = set()
def _spawn(self, coroutine) -> None:
"""Retain asynchronous requests until completion."""
task = asyncio.create_task(coroutine)
self._background_tasks.add(task)
task.add_done_callback(self._background_tasks.discard)
# ── Output ──────────────────────────────────────────────────────────────
async def write(self, obj: dict) -> None:
async with self._write_lock:
sys.stdout.write(json.dumps(obj) + "\n")
sys.stdout.flush()
# ── Dispatch ────────────────────────────────────────────────────────────
async def dispatch(self, req: dict) -> None:
method = req.get("method") or req.get("cmd", "")
req_id = req.get("id", "")
params = req.get("params") or {}
if method == "health":
# Run in executor so importing 7 format modules doesn't block the event
# loop (matters if health is called while conversions are in flight).
loop = asyncio.get_running_loop()
result = await loop.run_in_executor(None, health.check)
await self.write({"v": 1, "id": req_id, "ok": True, "result": result})
elif method == "capabilities":
loop = asyncio.get_running_loop()
result = await loop.run_in_executor(None, _caps.report)
await self.write({"v": 1, "id": req_id, "ok": True, "result": result})
elif method == "check-provider":
self._spawn(self._check_provider_safe(req_id, params))
elif method == "convert-one":
# Concurrent conversions are supported — no BUSY check.
cancel_event = asyncio.Event()
self._cancel_events[req_id] = cancel_event
self._spawn(self._convert_safe(req_id, params, cancel_event))
elif method == "cleanup":
# Deterministic + optional LLM cleanup. Cancellable via the same
# per-id event dict so batch cancel (cancel-all) stops the LLM pass.
cancel_event = asyncio.Event()
self._cancel_events[req_id] = cancel_event
self._spawn(self._cleanup_safe(req_id, params, cancel_event))
elif method == "cancel":
target_id = params.get("id")
cancelled_ids: list[str] = []
if target_id:
# Cancel one specific conversion.
if target_id in self._cancel_events:
self._cancel_events[target_id].set()
cancelled_ids.append(target_id)
else:
# No id → cancel all active conversions (backwards-compat +
# batch cancel path).
for eid, event in self._cancel_events.items():
event.set()
cancelled_ids.append(eid)
# Ack so the caller doesn't hang waiting for a response.
await self.write({"v": 1, "id": req_id, "ok": True, "result": {"cancelled": cancelled_ids}})
else:
await self.write({"v": 1, "id": req_id, **err(
"UNKNOWN_METHOD",
"Unknown method",
f"Unrecognised method: {method!r}",
"Update the app.",
)})
# ── Conversion ──────────────────────────────────────────────────────────
async def _convert_safe(
self, conv_id: str, params: dict, cancel_event: asyncio.Event
) -> None:
try:
await self._convert(conv_id, params, cancel_event)
except Exception as exc: # noqa: BLE001
await self.write({"v": 1, "id": conv_id, **err(
INTERNAL_ERROR,
"Internal error",
str(exc),
"Restart the app. If this keeps happening, re-install.",
)})
finally:
self._cancel_events.pop(conv_id, None)
async def _convert(
self, conv_id: str, params: dict, cancel_event: asyncio.Event
) -> None:
path: str = params.get("path", "")
llm_cfg: dict | None = params.get("llm")
if not path:
await self.write({"v": 1, "id": conv_id, **err(
FILE_NOT_FOUND, "No file path provided",
"The request did not include a file path.",
"Select a file and try again.",
)})
return
if not os.path.exists(path):
await self.write({"v": 1, "id": conv_id, **err(
FILE_NOT_FOUND, "File not found",
f"'{os.path.basename(path)}' does not exist at the given path.",
"Check that the file hasn't been moved or deleted, then try again.",
)})
return
ext = os.path.splitext(path)[1].lower()
fmt_entry = _caps.ext_to_format(ext)
if fmt_entry is None:
await self.write({"v": 1, "id": conv_id, **err(
UNSUPPORTED_FORMAT, "Format not supported",
f"'{ext or '(no extension)'}' files can't be converted.",
f"Use {_caps.SUPPORTED_LIST}.",
)})
return
mode = fmt_entry.get("mode", "markitdown")
# Online-only cloud file (OneDrive): reading it downloads it first, which counts
# against the time budget. Acknowledge it in the UI; the standard path also gets a
# longer timeout below (OCR/audio already have the long budget).
cloud = preflight._is_cloud_placeholder(path)
if cloud:
await self._emit_progress(conv_id, "downloading")
# ── OCR routing ────────────────────────────────────────────────────────
if mode == "ocr":
import ocr as _ocr
if not _ocr.is_available():
await self.write({"v": 1, "id": conv_id,
**_missing_engine_err("ocr", fmt_entry["key"])})
return
await self._convert_ocr(conv_id, path, fmt_entry, cancel_event)
return
# ── Audio routing ──────────────────────────────────────────────────────
if mode == "audio":
import audio as _audio
if not _audio.is_available():
await self.write({"v": 1, "id": conv_id,
**_missing_engine_err("audio", fmt_entry["key"])})
return
await self._convert_audio(conv_id, path, params, cancel_event)
return
# ── Standard MarkItDown routing ────────────────────────────────────────
fmt = fmt_entry["key"]
required_module = fmt_entry.get("module")
converter_path = fmt_entry.get("converter", "")
if cancel_event.is_set():
await self.write({"v": 1, "id": conv_id, **_cancelled_err()})
return
await self._emit_progress(conv_id, "preflight")
flight_err = preflight.check(path, ext)
if flight_err:
await self.write({"v": 1, "id": conv_id, **flight_err})
return
# Special case: PDF that appears to be scanned — route to OCR if available.
# The detection parses the PDF with pdfminer, which is a multi-second
# blocking call — run it in an executor so the event loop stays responsive
# to cancel requests and other concurrent conversions. Race it against the
# cancel event so Cancel is honoured immediately, not after the parse ends.
if ext == ".pdf" and required_module:
import ocr as _ocr
if _ocr.is_available():
loop = asyncio.get_running_loop()
detect = asyncio.ensure_future(
loop.run_in_executor(None, _ocr.is_scanned_pdf, path)
)
cancel_wait = asyncio.ensure_future(cancel_event.wait())
await asyncio.wait(
{detect, cancel_wait}, return_when=asyncio.FIRST_COMPLETED
)
cancel_wait.cancel()
if cancel_event.is_set():
# The detached executor finishes pdfminer in the background; we
# don't wait on it — the user already asked to stop.
await self.write({"v": 1, "id": conv_id, **_cancelled_err()})
return
if detect.result():
scanned_entry = {"key": "pdf-ocr", "converter": "ocr.RapidOCR"}
await self._convert_ocr(conv_id, path, scanned_entry, cancel_event, is_pdf=True)
return
if required_module:
try:
module_available = importlib.util.find_spec(required_module) is not None
except (ImportError, AttributeError, ValueError):
module_available = False
if not module_available:
e = err(
MISSING_EXTRA, "Required package missing",
f"The '{required_module}' package is not installed.",
"Open Diagnostics and click Repair to reinstall packages.",
)
e["error"]["diagnostics_key"] = fmt
await self.write({"v": 1, "id": conv_id, **e})
return
worker_params: dict = {"path": path, "fmt": fmt, "converter_path": converter_path}
if llm_cfg and llm_cfg.get("mode", "off") != "off":
worker_params["llm"] = llm_cfg
await self._run_worker_subprocess(
conv_id=conv_id,
worker_path=_SIDECAR_DIR / "worker.py",
worker_params=worker_params,
cancel_event=cancel_event,
timeout_secs=CLOUD_TIMEOUT_SECS if cloud else TIMEOUT_SECS,
timeout_msg=(
"The file may still be downloading from the cloud. Make it available "
"offline (right-click → Always keep on this device), then try again."
if cloud else
f"The conversion took longer than {TIMEOUT_SECS} seconds and was stopped."
),
)
# ── OCR conversion ──────────────────────────────────────────────────────────
async def _convert_ocr(
self,
conv_id: str,
path: str,
fmt_entry: dict,
cancel_event: asyncio.Event,
is_pdf: bool = False,
) -> None:
"""Spawn ocr_worker.py for image files and scanned PDFs."""
fmt = fmt_entry["key"]
converter_path = fmt_entry.get("converter", "ocr.RapidOCR")
worker_path = _SIDECAR_DIR / "ocr_worker.py"
await self._run_worker_subprocess(
conv_id=conv_id,
worker_path=worker_path,
worker_params={"path": path, "fmt": fmt, "is_pdf": is_pdf, "converter_path": converter_path},
cancel_event=cancel_event,
timeout_secs=OCR_TIMEOUT_SECS,
timeout_msg=f"OCR took longer than {OCR_TIMEOUT_SECS} seconds and was stopped.",
)
# ── Audio transcription ────────────────────────────────────────────────────
async def _convert_audio(
self,
conv_id: str,
path: str,
params: dict,
cancel_event: asyncio.Event,
) -> None:
"""Spawn audio_worker.py for audio files."""
model_size = params.get("audio_model", "base")
worker_path = _SIDECAR_DIR / "audio_worker.py"
await self._run_worker_subprocess(
conv_id=conv_id,
worker_path=worker_path,
worker_params={"path": path, "model_size": model_size},
cancel_event=cancel_event,
timeout_secs=AUDIO_TIMEOUT_SECS,
timeout_msg=f"Transcription took longer than {AUDIO_TIMEOUT_SECS} seconds and was stopped.",
)
# ── Generic worker subprocess runner ──────────────────────────────────────
async def _run_worker_subprocess(
self,
conv_id: str,
worker_path: Path,
worker_params: dict,
cancel_event: asyncio.Event,
timeout_secs: int,
timeout_msg: str,
) -> None:
"""
Spawn a worker script as a subprocess, stream its progress/heartbeat events,
and write the final result or error to the IPC channel.
Cancellable; emits heartbeats every 5 s to keep Rust's idle timeout alive.
"""
if cancel_event.is_set():
await self.write({"v": 1, "id": conv_id, **_cancelled_err()})
return
# CPU-thread budget. Batch items (conv_id "batch-…") get a limited thread count
# so N concurrent heavy workers (OCR/audio) don't oversubscribe the machine;
# single-file conversions use all cores. The budget is set by Rust per machine.
is_batch = conv_id.startswith("batch-")
cpu_threads = 0
sub_env = os.environ
if is_batch:
try:
cpu_threads = int(os.environ.get("MDFLUX_BATCH_THREADS", "0") or "0")
except ValueError:
cpu_threads = 0
if cpu_threads > 0:
sub_env = {**os.environ}
for _v in ("OMP_NUM_THREADS", "OPENBLAS_NUM_THREADS",
"MKL_NUM_THREADS", "NUMEXPR_NUM_THREADS"):
sub_env[_v] = str(cpu_threads)
params = {**worker_params, "cpu_threads": cpu_threads}
# Windows: CREATE_NO_WINDOW (0x08000000) so the worker (a console app) never
# flashes a command window. 0 elsewhere (ignored on POSIX).
no_window = 0x0800_0000 if sys.platform == "win32" else 0
# Acquire the semaphore so concurrent worker subprocesses are capped —
# without this a 50-item batch spawns 50 heavy processes (OOM risk).
async with self._worker_sem:
if cancel_event.is_set():
await self.write({"v": 1, "id": conv_id, **_cancelled_err()})
return
try:
proc = await asyncio.create_subprocess_exec(
sys.executable,
str(worker_path),
stdin=asyncio.subprocess.PIPE,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.DEVNULL,
limit=WORKER_STREAM_LIMIT,
env=sub_env,
creationflags=no_window,
)
except Exception as exc: # noqa: BLE001
await self.write({"v": 1, "id": conv_id, **err(
INTERNAL_ERROR, "Could not start worker process",
str(exc), "Restart the app.",
)})
return
self._active_procs.add(proc)
try:
proc.stdin.write((json.dumps(params) + "\n").encode())
await proc.stdin.drain()
proc.stdin.close()
final_msg: dict | None = None
loop = asyncio.get_running_loop()
deadline = loop.time() + timeout_secs
last_hb = loop.time()
try:
while True:
remaining = deadline - loop.time()
if remaining <= 0:
raise asyncio.TimeoutError()
if cancel_event.is_set():
await _kill(proc)
await self.write({"v": 1, "id": conv_id, **_cancelled_err()})
return
# Emit a heartbeat every 5 s to keep the Rust idle timeout alive.
if loop.time() - last_hb >= 5.0:
await self._emit_progress(conv_id, "processing")
last_hb = loop.time()
try:
raw = await asyncio.wait_for(
proc.stdout.readline(),
timeout=min(1.0, remaining),
)
except asyncio.TimeoutError:
if loop.time() >= deadline:
raise asyncio.TimeoutError()
continue
if not raw:
break
try:
msg = json.loads(raw)
except json.JSONDecodeError:
continue
if msg.get("type") == "progress":
last_hb = loop.time()
await self._emit_progress(
conv_id,
msg.get("stage", "processing"),
msg.get("frac"),
msg.get("heartbeat"),
)
elif msg.get("type") == "result":
final_msg = msg
break
except asyncio.TimeoutError:
await _kill(proc)
await self.write({"v": 1, "id": conv_id, **err(
TIMEOUT, "Timed out", timeout_msg,
"Try a smaller file, or split it into sections.",
)})
return
if cancel_event.is_set():
await self.write({"v": 1, "id": conv_id, **_cancelled_err()})
return
if final_msg is None:
await self.write({"v": 1, "id": conv_id, **err(
INTERNAL_ERROR,
"Worker stopped unexpectedly",
"The worker exited without producing a result.",
"Try the file again. If this keeps happening, restart the app.",
)})
else:
response: dict = {"v": 1, "id": conv_id, "ok": final_msg.get("ok", False)}
if "result" in final_msg:
response["result"] = final_msg["result"]
if "error" in final_msg:
response["error"] = final_msg["error"]
elif not response["ok"]:
# Malformed worker result: ok=false but no error envelope.
# Synthesize one so Rust doesn't NPE indexing error.code.
response["error"] = err(
INTERNAL_ERROR,
"Worker error",
"The worker returned an invalid response (no error detail).",
"Try the file again. If this keeps happening, restart the app.",
)["error"]
await self.write(response)
finally:
self._active_procs.discard(proc)
# ── Cleanup ──────────────────────────────────────────────────────────────
async def _cleanup_safe(
self, req_id: str, params: dict, cancel_event: asyncio.Event
) -> None:
try:
await self._cleanup(req_id, params, cancel_event)
except Exception as exc: # noqa: BLE001
await self.write({"v": 1, "id": req_id, **err(
INTERNAL_ERROR, "Cleanup failed",
str(exc), "Try again, or turn cleanup off to keep the raw result.",
)})
finally:
self._cancel_events.pop(req_id, None)
async def _cleanup(
self, req_id: str, params: dict, cancel_event: asyncio.Event
) -> None:
markdown: str = params.get("markdown", "")
source_format: str = params.get("source_format", "")
rules: dict = params.get("rules", {})
method: str = params.get("method", "rules")
provider_cfg: dict = params.get("provider", {})
if method == "ai":
# AI cleans the RAW extraction directly — no deterministic pass.
await self._cleanup_ai(req_id, markdown, provider_cfg, cancel_event)
return
# Rule-based: deterministic only.
cleaned, summary = _cleanup_mod.clean(markdown, source_format, rules)
await self.write({"v": 1, "id": req_id, "ok": True, "result": {
"markdown": cleaned,
"summary": summary,
"llm_applied": False,
"llm_notice": None,
}})
async def _cleanup_ai(
self, req_id: str, markdown: str, provider_cfg: dict, cancel_event: asyncio.Event
) -> None:
cleaned = markdown # fail-soft default: the raw text, never lost
llm_applied = False
llm_notice: str | None = None
if cancel_event.is_set():
await self.write({"v": 1, "id": req_id, **_cancelled_err()})
return
loop = asyncio.get_running_loop()
# Provider calls stream on this event loop. There is deliberately no overall
# generation deadline: the provider layer stops only when the response goes
# silent, while cancellation aborts the active HTTP stream immediately.
progress = {"done": 0, "total": 0}
work = asyncio.create_task(_cleanup_mod.llm_clean(
markdown,
provider_cfg,
progress_cb=lambda d, t: progress.update(done=d, total=t),
cancel_event=cancel_event,
))
try:
# Heartbeats keep the sidecar IPC alive independently of the provider's
# token cadence. They do not extend the provider's own inactivity timer.
last_hb = loop.time()
while True:
if cancel_event.is_set():
work.cancel()
try:
await work
except asyncio.CancelledError:
pass
await self.write({"v": 1, "id": req_id, **_cancelled_err()})
return
done, _ = await asyncio.wait({work}, timeout=1.0)
if work in done:
break
if loop.time() - last_hb >= 5.0:
frac = (progress["done"] / progress["total"]) if progress["total"] else None
await self._emit_progress(req_id, "ai-cleanup", frac)
last_hb = loop.time()
if cancel_event.is_set(): # cancel raced with the final chunk completing
await self.write({"v": 1, "id": req_id, **_cancelled_err()})
return
llm_text = work.result()
if isinstance(llm_text, str) and llm_text.strip():
# Always present the AI result — the user decides whether to keep it.
# The guardrail is advisory: it may attach a warning, never discards.
cleaned = llm_text
llm_applied = True
llm_notice = _cleanup_mod.data_loss_warning(markdown, llm_text)
elif not markdown.strip():
pass # empty input → empty output; no notice needed
else:
llm_notice = "AI cleanup returned nothing — kept the original text."
except _cleanup_mod.CleanupCancelled:
await self.write({"v": 1, "id": req_id, **_cancelled_err()})
return
except _provider.ProviderIdleTimeout as exc:
llm_notice = f"AI cleanup stopped because {exc} Kept the original text."
except _provider.ProviderEmptyOutput:
llm_notice = "AI cleanup returned no text — kept the original text."
except _provider.ProviderMalformedResponse:
llm_notice = (
"AI cleanup received an invalid provider response — "
"kept the original text."
)
except Exception as exc: # noqa: BLE001 — fail soft, never lose the result
_key = provider_cfg.get("key", "")
safe_exc = str(exc).replace(_key, "[key]") if _key else str(exc)
llm_notice = (
f"AI cleanup provider failed: {safe_exc} — kept the original text."
)
summary = {
"rules": [],
"char_delta": len(cleaned) - len(markdown),
"line_delta": (cleaned.count("\n") + 1) - (markdown.count("\n") + 1),
}
await self.write({"v": 1, "id": req_id, "ok": True, "result": {
"markdown": cleaned,
"summary": summary,
"llm_applied": llm_applied,
"llm_notice": llm_notice,
}})
async def _emit_progress(
self,
conv_id: str,
stage: str,
frac: float | None = None,
heartbeat: int | None = None,
) -> None:
await self.write({
"v": 1,
"id": conv_id,
"type": "progress",
"stage": stage,
"frac": frac,
"heartbeat": heartbeat or int(time.time()),
})
# ── Provider health check ────────────────────────────────────────────────
async def _check_provider_safe(self, req_id: str, params: dict) -> None:
try:
await self._check_provider(req_id, params)
except Exception as exc: # noqa: BLE001
await self.write({"v": 1, "id": req_id, "ok": True, "result": {
"reachable": False,
"detail": f"Check failed: {exc}",
"usable": False,
}})
async def _check_provider(self, req_id: str, params: dict) -> None:
ptype = params.get("provider", "local")
base_url = params.get("base_url", "http://localhost:11434")
key = params.get("key", "")
loop = asyncio.get_running_loop()
if ptype == "local":
result = await loop.run_in_executor(None, _provider.check_local, base_url)
elif ptype == "api_openai_compat":
result = await loop.run_in_executor(None, _provider.check_openai_compat, base_url, key)
elif ptype == "api_anthropic":
result = await loop.run_in_executor(None, _provider.check_anthropic, key)
else:
result = {
"reachable": False,
"detail": f"Unknown provider type: {ptype!r}",
"usable": False,
}
await self.write({"v": 1, "id": req_id, "ok": True, "result": result})
# ── Helpers ──────────────────────────────────────────────────────────────────
def _cancelled_err() -> dict:
return err(CANCELLED, "Conversion cancelled", "The conversion was stopped by the user.", "")
def _missing_engine_err(engine: str, diag_key: str) -> dict:
"""Optional engine (OCR/audio) needed but not installed — point at the installer."""
if engine == "ocr":
title = "OCR engine not installed"
detail = ("This image needs the OCR engine (RapidOCR), which isn't installed yet. "
"Scanned PDFs and image files require it.")
else:
title = "Audio engine not installed"
detail = ("This audio file needs the transcription engine (faster-whisper), "
"which isn't installed yet.")
e = err(MISSING_EXTRA, title, detail,
"Open Diagnostics → Optional capabilities and click Install.")
e["error"]["diagnostics_key"] = diag_key
return e
async def _kill(proc: asyncio.subprocess.Process) -> None:
try:
proc.terminate()
try:
await asyncio.wait_for(proc.wait(), timeout=2.0)
except asyncio.TimeoutError:
proc.kill()
await proc.wait()
except ProcessLookupError:
pass
# ── Entry ─────────────────────────────────────────────────────────────────────
async def async_main() -> None:
sidecar = Sidecar()
loop = asyncio.get_running_loop()
try:
while True:
try:
raw = await loop.run_in_executor(None, sys.stdin.readline)
except Exception:
break
if not raw:
break
raw = raw.strip()
if not raw:
continue
try:
req = json.loads(raw)
except json.JSONDecodeError as exc:
await sidecar.write({"v": 1, "id": "", "ok": False, "error": {
"code": "INVALID_JSON",
"title": "Invalid request",
"detail": f"Could not parse request: {exc}",
"suggested_action": "Re-install the app.",
}})
continue
# Guard against parseable-but-not-an-object JSON (e.g. "123", null, [],
# true) — these have no .get method and would crash the sidecar.
if not isinstance(req, dict):
await sidecar.write({"v": 1, "id": "", "ok": False, "error": {
"code": "INVALID_JSON",
"title": "Invalid request",
"detail": "Request must be a JSON object.",
"suggested_action": "Re-install the app.",
}})
continue
# Validate protocol version — a future v2 client must not be silently
# misinterpreted as v1.
req_v = req.get("v")
if req_v != 1:
req_id = req.get("id", "")
await sidecar.write({"v": 1, "id": req_id, "ok": False, "error": {
"code": "BAD_VERSION",
"title": "Unsupported protocol version",
"detail": f"Expected v:1, got v:{req_v!r}.",
"suggested_action": "Update the app.",
}})
continue
req_id = req.get("id", "")
try:
await sidecar.dispatch(req)
except Exception as exc: # noqa: BLE001
await sidecar.write({"v": 1, "id": req_id, **err(
INTERNAL_ERROR, "Internal error",
str(exc), "Restart the app. If this keeps happening, re-install.",
)})
finally:
# Kill any still-running worker subprocesses on shutdown so they don't
# orphan and consume CPU/RAM for up to 600s after the app closes.
for proc in list(sidecar._active_procs):
await _kill(proc)
sidecar._active_procs.clear()
for task in list(sidecar._background_tasks):
task.cancel()
if sidecar._background_tasks:
await asyncio.gather(*sidecar._background_tasks, return_exceptions=True)
def main() -> None:
asyncio.run(async_main())
if __name__ == "__main__":
main()