1687a9c05b0c
control.rs
//! Programmatic control of the running app (agents, tests, MCP).
//!
//! Methods (JSON lines over the host's transport, see `docs/control-protocol.md`):
//! - `engine.execute {command, params}` β run any engine or UI command
//! - `engine.commands {search?}` β every command with enablement and params docs
//! - `document.inspect`, `sheet.read {range?}`, `cell.get {cell?}` β read state
//! - `ui.inspect` β UI state (ribbon tab, editor, dialog, selected object, grid geometry, perf)
//! - `ui.object.select {id?, kind?}` β select a floating object; replies with its rect
//! - `ui.click {x, y, button?, count?, shift?, cmd?, alt?}`, `ui.drag {x, y, toX, toY}`,
//! `ui.move {x, y}` β real pointer input in window points
//! - `ui.cell.click {cell}`, `ui.cell.drag {from, to}` β pointer input on a cell's centre
//! - `ui.key {key, shift?, cmd?, alt?, ctrl?}`, `ui.text {text}` β keyboard input
//! - `ui.ribbon {tab}`, `ui.dialog {name}`, `ui.dialog.set {field, value}`,
//! `ui.dialog.confirm`, `ui.dialog.cancel`, `ui.message.dismiss`
//! - `ui.edit.begin {text?}`, `ui.edit.commit {move?}`, `ui.edit.cancel`
//! - `ui.screenshot {path?}` β PNG of the window (base64 when no path); animations are settled
//! - `ui.resize {width, height}`, `ui.set {dark?, formulaBar?, ribbonCollapsed?, animations?}`
//! - `app.open {path, password?}`, `app.save {path?}`, `app.quit`
use std::sync::mpsc::Sender;
use craft_ui::capture::CaptureSlot;
use gridcraft_engine::core::CellRef;
use serde_json::{Value as Json, json};
use crate::SheetApp;
mod screenshots;
mod synthetic;
pub use screenshots::{
CaptureGeometry, SCREENSHOT_DOCUMENT_CHANGED, SCREENSHOT_MAX_AGGREGATE_BYTES, SCREENSHOT_MAX_BASE64_BYTES, SCREENSHOT_MAX_ENCODING_BYTES,
SCREENSHOT_MAX_IMAGE_BYTES, SCREENSHOT_MAX_PEAK_BYTES, SCREENSHOT_MAX_REQUESTS, SCREENSHOT_MAX_RETRIES, SCREENSHOT_VIEWPORT_CHANGED, Shots,
UNKNOWN_CAPTURE_BYTES, drain_screenshots, encoding_working_bytes, issue_screenshots, save_image,
};
use screenshots::{Shot, check_encoding_budget, check_peak_budget, reject_shot};
#[cfg(test)]
use screenshots::{base64_len, png_worst_bytes, validate_image};
pub(crate) use screenshots::{current_capture_geometry, note_capture_geometry};
pub use synthetic::{MAX_QUEUED_SYNTHETIC_BYTES, MAX_QUEUED_SYNTHETIC_EVENTS, MAX_SYNTHETIC_TEXT_BYTES};
use synthetic::{cell_center, key_from, modifiers, push_click, push_drag, push_key, push_move, push_text};
pub type ControlResponse = Json;
pub struct ControlRequest {
pub method: String,
pub params: Json,
pub reply: Sender<ControlResponse>,
/// Who has the request: [`PENDING`], [`TAKEN`] (the app runs it) or [`ABANDONED`] (the sender
/// gave up waiting, so the app must not run it late: a client told its request timed out had
/// it applied anyway on the next UI pass, and an agent that retried ran it twice (#1914).
pub state: std::sync::Arc<std::sync::atomic::AtomicU8>,
}
/// Queued, not yet run.
pub const PENDING: u8 = 0;
/// The app has started it: it will answer.
pub const TAKEN: u8 = 1;
/// Its sender gave up waiting (the reply timeout expired): it is dropped unrun.
pub const ABANDONED: u8 = 2;
impl ControlRequest {
pub fn new(method: impl Into<String>, params: Json) -> (Self, std::sync::mpsc::Receiver<ControlResponse>) {
let (tx, rx) = std::sync::mpsc::channel();
(Self { method: method.into(), params, reply: tx, state: Default::default() }, rx)
}
/// Claim the request for running; false when its sender already gave up on it.
pub fn take(&self) -> bool {
use std::sync::atomic::Ordering;
self.state.compare_exchange(PENDING, TAKEN, Ordering::SeqCst, Ordering::SeqCst).is_ok() || self.state.load(Ordering::SeqCst) == TAKEN
}
/// Give up on the request; false when the app has already started it (it will answer).
pub fn abandon(state: &std::sync::atomic::AtomicU8) -> bool {
use std::sync::atomic::Ordering;
state.compare_exchange(PENDING, ABANDONED, Ordering::SeqCst, Ordering::SeqCst).is_ok() || state.load(Ordering::SeqCst) == ABANDONED
}
}
pub enum Outcome {
Done(Json),
Screenshot { path: Option<String> },
}
fn ok(v: Json) -> Outcome {
Outcome::Done(json!({"ok": true, "result": v}))
}
fn err(e: impl std::fmt::Display) -> Outcome {
Outcome::Done(json!({"ok": false, "error": e.to_string()}))
}
fn wrap(r: Result<Json, String>) -> Outcome {
match r {
Ok(v) => ok(v),
Err(e) => err(e),
}
}
/// Runs a command for an agent. Commands that move the selection scroll the active cell into
/// view, as the Go To dialog, the Name Box and the arrow keys do.
fn run(app: &mut SheetApp, id: &str, params: Json) -> Result<Json, String> {
let r = app.run(id, params);
if r.is_ok() && matches!(id, "edit.goTo" | "edit.goToSpecial" | "selection.set" | "selection.move") {
app.grid.ensure_visible = true;
}
r
}
/// [`run`] in another window (`window` or `doc` from the request), bringing back the active
/// window afterwards unless the command itself switched windows.
fn run_in(app: &mut SheetApp, target: gridcraft_engine::Target, id: &str, params: Json) -> Result<Json, String> {
let guard = app.session.enter_target(target).map_err(|e| e.to_string())?;
let r = run(app, id, params);
app.session.leave_target(guard);
r
}
/// A command called by its id as the method. Its params may name a `window` or `doc` to act in,
/// except for the window commands, whose own params those are.
fn direct(app: &mut SheetApp, id: &str, p: &Json, via_app: bool) -> Result<Json, String> {
let mut params = p.clone();
let target = if gridcraft_engine::windows::is_window_command(id) {
gridcraft_engine::Target::Active
} else {
let t = gridcraft_engine::Target::from_json(p).map_err(|e| e.to_string())?;
if let Some(o) = params.as_object_mut() {
o.remove("window");
o.remove("doc");
}
t
};
if via_app {
return run_in(app, target, id, params);
}
let guard = app.session.enter_target(target).map_err(|e| e.to_string())?;
let r = app.session.run(id, params);
app.session.leave_target(guard);
r
}
pub fn inspect(app: &SheetApp, ctx: &egui::Context) -> Json {
let r = ctx.content_rect();
let v = app.view();
json!({
"ui": serde_json::to_value(&app.ui).unwrap_or_default(),
"window": [r.width(), r.height()],
"grid": app.grid.cells_rect.map(|c| json!([c.left(), c.top(), c.width(), c.height()])),
"scroll": [v.scroll.x, v.scroll.y],
"editor": app.editor.as_ref().map(|e| editor_json(app, e)),
"dialog": app.dialog.as_ref().map(|d| json!({"name": d.name, "title": d.title, "values": d.values, "tab": d.tab})),
"backstage": app.backstage.as_ref().map(|b| b.page.id()),
"message": app.message.as_ref().map(|(t, m)| json!({"title": t, "text": m})),
"selectedObject": app.selected_object,
// The id when the selection is a chart, as before `selectedObject`.
"selectedChart": app.selected_chart(),
"mode": format!("{:?}", app.session.mode),
"documents": app.session.documents().iter().map(|d| json!({"title": d.display_title(), "dirty": d.is_dirty()})).collect::<Vec<_>>(),
"activeDocument": app.session.active_index(),
"windows": app.session.window_list(),
"activeWindow": app.session.active_window(),
"perf": {"frameMs": app.perf.frame_ms, "gridMs": app.perf.grid_ms, "fps": app.perf.fps},
})
}
/// The open edit, for `ui.inspect`. The draft is left out (`text` is null, `hidden` true) while
/// its cell's code is hidden on a protected sheet, checked now: a protection command earlier in
/// the same batch runs before the next frame. That holds for a draft in Python mode, and for a
/// draft that began on a Python cell's code, since leaving Python mode keeps the code as an
/// ordinary draft; a draft typed over a Python cell holds only what was typed. The sheet is the
/// draft's own, found by identity: a sheet inserted, deleted or moved in the same batch puts
/// another at its index. With its sheet gone, such a draft is left out too.
fn editor_json(app: &SheetApp, e: &crate::editor::EditState) -> Json {
let code = e.python || e.py_cell;
let hidden = code
&& app.session.documents().iter().find(|d| d.uid == e.doc).is_some_and(|d| match e.sheet_in(&d.wb).and_then(|i| d.wb.sheet(i)) {
Some(sh) => gridcraft_engine::display::formula_hidden(&d.wb, sh, e.cell),
None => true,
});
let text = if hidden { Json::Null } else { json!(e.text) };
json!({"cell": e.cell.a1(), "text": text, "hidden": hidden, "formulaBar": e.from_formula_bar, "point": e.can_point(), "python": e.python})
}
/// `ui.dialog.cancel`: closes the open dialog as its Cancel button does, going back to the sheet
/// and selection from before a reference box picked.
fn dialog_cancel(app: &mut SheetApp) -> Outcome {
// The macro step editor's draft, overlays and debug run go with its own close.
if app.dialog.as_ref().is_some_and(|d| d.name == "macroEditor") {
return match crate::macro_editor::close_now(app) {
Ok(()) => ok(Json::Null),
Err(e) => err(e),
};
}
// Back to the sheet and selection from before a reference box picked, as Cancel does.
// When the dialog's sheet can't be shown again (a text-box draft on the picked sheet
// could not be saved), the dialog stays and the script gets the reason; the window's
// Cancel closes it and shows the reason, since a person can see the message.
// A dialog whose own sheet was deleted (found by identity, so a new sheet given its
// name does not count) replies `{"sheetDeleted": true}`: the sheet shown is not the
// dialog's, and a script stops before running the dialog's command itself.
let mut deleted = false;
if let Some(mut d) = app.dialog.take() {
deleted = d.home_sheet_deleted(app);
if let Err(e) = d.end_pick(app) {
app.dialog = Some(d);
return err(e);
}
}
ok(if deleted { json!({"sheetDeleted": true}) } else { Json::Null })
}
/// `ui.object.select {id?, kind?}`: selects the object with that id on the active sheet (its kind
/// is found from the id when left out, and must match when given); no `id` clears the selection.
/// Replies with the object and its rect in window points, for `ui.click` and `ui.drag`.
fn select_object(app: &mut SheetApp, p: &Json) -> Outcome {
use gridcraft_engine::model::{ObjKind, ObjRef};
let Some(id) = p.get("id").and_then(Json::as_u64) else {
app.selected_object = None;
return ok(Json::Null);
};
let Some(sh) = app.session.active().and_then(|d| d.wb.active()) else { return err("no document") };
let found = u32::try_from(id).ok().and_then(|id| match p.get("kind").and_then(Json::as_str) {
Some(k) => ObjKind::parse(k).map(|k| ObjRef::new(k, id)).filter(|o| sh.has_object(*o)),
None => sh.object_ref(id),
});
let Some(o) = found else { return err("no such object on the active sheet") };
let rect = app.grid.rect.and_then(|r| {
let geo = crate::grid::Geo::new(sh, r, app.view().scroll);
crate::chartview::object_rect(&geo, sh, o).map(|r| geo.mirror_rect(r))
});
app.selected_object = Some(o);
ok(json!({"selected": o, "rect": rect.map(|r| [r.left(), r.top(), r.width(), r.height()])}))
}
/// Keeps the commands whose id, label or ribbon path contains `search` (case-insensitive); `None` keeps all.
fn filter_commands(commands: Vec<Json>, search: Option<&str>) -> Vec<Json> {
let Some(q) = search.map(str::to_ascii_lowercase) else { return commands };
let has = |c: &Json, k: &str| c.get(k).and_then(Json::as_str).is_some_and(|v| v.to_ascii_lowercase().contains(&q));
let in_menu = |c: &Json| {
let menu = c.get("menu").and_then(Json::as_array);
menu.is_some_and(|m| m.iter().filter_map(Json::as_str).any(|v| v.to_ascii_lowercase().contains(&q)))
};
commands.into_iter().filter(|c| has(c, "id") || has(c, "label") || in_menu(c)).collect()
}
/// Dispatches one control request: commands, inspection, UI state, dialogs, editing, synthetic input, open/save/quit and screenshots. Unknown methods (and unknown command ids) return an error. Immediate answers request a repaint; `ui.screenshot` is admitted asynchronously instead of being answered here.
pub fn handle(app: &mut SheetApp, ctx: &egui::Context, method: &str, p: &Json) -> Outcome {
let s = |k: &str| p.get(k).and_then(Json::as_str);
let f = |k: &str| p.get(k).and_then(Json::as_f64).unwrap_or(0.0) as f32;
let out = match method {
"engine.execute" | "command" | "ui.menu.invoke" => {
let Some(id) = s("command").or(s("id")) else { return err("missing `command`") };
let params = p.get("params").cloned().unwrap_or(json!({}));
let target = match gridcraft_engine::Target::from_json(p) {
Ok(t) => t,
Err(e) => return err(e),
};
wrap(run_in(app, target, id, if params.is_null() { json!({}) } else { params }))
}
"engine.commands" => {
let mut v: Vec<Json> = app.session.commands().into_iter().map(|c| serde_json::to_value(c).unwrap_or_default()).collect();
let language_params = format!("{{language: {}}} (alias: code)", crate::i18n::Language::code_list("|"));
for (id, label, params) in [
("ui.ribbonTab", "Ribbon Tab", ""),
("app.checkForUpdates", "Check for Updatesβ¦", ""),
("view.collapseRibbon", "Collapse Ribbon", ""),
(
"view.expandFormulaBar",
"Expand Formula Bar",
"{on?: bool} (toggles without it) β {on}; {lines: int} sets the expanded height (1 collapses) β {on, lines}",
),
("ui.pythonMode", "Python Mode", "{on?: bool} (toggles without it) β {on}; a refused start is an error"),
("view.darkMode", "Dark Mode", ""),
("view.theme", "Display Theme", ""),
("view.animations", "Animations", "{on?: bool} (toggles without it) β {on}"),
("options.autoComplete", "Enable AutoComplete for cell values", "{on?: bool} (toggles without it) β {on}"),
("options.highlightActiveRow", "Highlight the active cell's row", "{on?: bool} (toggles without it) β {on}"),
("view.interfaceScale", "Interface Size", "{percent: 75β200 | \"auto\"} (100 = auto; clamped)"),
("ui.window.minimize", "Minimize Window", ""),
("ui.window.maximize", "Maximize Window", "{on: bool}"),
("ui.window.close", "Close Window", ""),
("ui.window.beginResize", "Resize Window", "{direction: north|south|east|west|northeast|northwest|southeast|southwest}"),
("ui.dialog", "Open Dialog", ""),
("ui.backstage", "File (Backstage view)", "{page?: home|new|open|info|saveAs|print|export|options|account|close}"),
(
"ui.printSettings",
"Print Settings",
"{printer?: discovered name, copies?: 1..999, duplex?: printerDefault|off|longEdge|shortEdge|null, grayscale?: bool, refresh?: bool} β {printer,copies,duplex,grayscale,printers,ready,busy,discovering,status,detail}; {} inspects without submitting",
),
(
"ui.printSubmit",
"Submit Print Job",
"existing file.print sheet/pagination params β {printing,bytes,pending}; submits without opening a dialog",
),
("app.language.set", "Interface Language", language_params.as_str()),
("app.language.english", "Interface Language: English", ""),
("app.language.japanese", "Interface Language: Japanese", ""),
] {
v.push(json!({"id": id, "label": label, "params": params, "enabled": true, "ui": true}));
}
ok(Json::Array(filter_commands(v, s("search"))))
}
"engine.journal" => ok(json!(app.session.journal.iter().map(|(id, p)| json!({"command": id, "params": p})).collect::<Vec<_>>())),
"document.inspect" | "sheet.read" | "cell.get" | "selection.stats" => wrap(direct(app, method, p, false)),
"ui.inspect" => ok(inspect(app, ctx)),
"ui.ribbon" => {
app.ui.ribbon_tab = s("tab").unwrap_or("Home").to_string();
app.ui.ribbon_collapsed = false;
ok(Json::Null)
}
"ui.set" => {
if let Some(v) = p.get("dark").and_then(Json::as_bool) {
app.ui.dark = v;
app.ui.system_theme = false;
}
if let Some(v) = p.get("formulaBar").and_then(Json::as_bool) {
let _ = app.run("view.formulaBar", json!({"on": v}));
}
if let Some(v) = p.get("ribbonCollapsed").and_then(Json::as_bool) {
app.ui.ribbon_collapsed = v;
}
if let Some(v) = p.get("animations").and_then(Json::as_bool) {
app.ui.animations = v;
}
let mut out = serde_json::to_value(&app.ui).unwrap_or_default();
if let Some(o) = out.as_object_mut() {
o.insert("formulaBar".into(), json!(app.session.prefs.formula_bar));
}
ok(out)
}
"ui.dialog" => {
app.open_dialog(s("name").unwrap_or(""), p.clone());
ok(json!({"dialog": app.dialog.as_ref().map(|d| d.name.clone())}))
}
"ui.dialog.set" => match app.dialog.as_mut() {
Some(d) => {
let Some(field) = s("field") else { return err("missing `field`") };
if field == "tab" {
d.tab = s("value").unwrap_or("").to_string();
} else if field == "search" {
d.search = s("value").unwrap_or("").to_string();
} else {
d.set_value(field, p.get("value").cloned().unwrap_or(Json::Null));
}
ok(json!(d.values))
}
None => err("no dialog is open"),
},
"ui.dialog.confirm" => match app.dialog.take() {
Some(mut d) => match d.command {
Some(cmd) => {
// References without a sheet name mean the sheet the dialog was opened on,
// as OK in the window has it: refused once that sheet is deleted, else shown
// again before the command runs.
if d.home_sheet_deleted(app) {
app.dialog = Some(d);
return err(crate::dialogs::SHEET_DELETED);
}
if let Err(e) = d.end_pick(app) {
// The dialog's sheet can't be shown again (a text-box draft on the picked
// sheet could not be saved): the command stays unrun, the dialog open.
app.dialog = Some(d);
return err(e);
}
let params = crate::dialogs::build_params(&d);
let home = app.ui_window();
let r = app.run(cmd, params);
if r.is_err() {
app.return_dialog(home, d);
}
wrap(r)
}
None => {
app.dialog = Some(d);
err("this dialog has no OK command; drive it with its own commands")
}
},
None => err("no dialog is open"),
},
"ui.dialog.cancel" => dialog_cancel(app),
"ui.object.select" => select_object(app, p),
"ui.message.dismiss" => {
app.message = None;
ok(Json::Null)
}
"ui.edit.begin" => {
app.begin_edit(s("text").map(str::to_string), false);
ok(Json::Null)
}
"ui.edit.text" => match app.editor.as_mut() {
Some(e) => {
e.text = s("text").unwrap_or("").to_string();
e.caret = e.text.chars().count();
ok(Json::Null)
}
None => err("not editing"),
},
"ui.edit.commit" => {
let (dr, dc) = match s("move") {
Some("right") => (0, 1),
Some("up") => (-1, 0),
Some("left") => (0, -1),
Some("none") => (0, 0),
_ => (1, 0),
};
if app.commit_edit(dr, dc, false, false) {
ok(Json::Null)
} else {
err(app.message.clone().map(|m| m.1).unwrap_or_else(|| "could not commit".into()))
}
}
"ui.edit.cancel" => {
app.cancel_edit();
ok(Json::Null)
}
"ui.key" => {
let Some(k) = s("key").and_then(key_from) else { return err("unknown or missing `key`") };
match push_key(app, k, modifiers(p)) {
Ok(()) => ok(Json::Null),
Err(e) => err(e),
}
}
"ui.text" => {
let text = s("text").unwrap_or("");
// Check the borrowed payload first: do not make a second, potentially large copy
// before the per-event bound is known to hold.
if text.len() > MAX_SYNTHETIC_TEXT_BYTES {
return err(format!("text input is {} bytes, over the {MAX_SYNTHETIC_TEXT_BYTES}-byte limit for one event", text.len()));
}
match push_text(app, text.to_string()) {
Ok(()) => ok(Json::Null),
Err(e) => err(e),
}
}
"ui.move" => match push_move(app, egui::pos2(f("x"), f("y"))) {
Ok(()) => ok(Json::Null),
Err(e) => err(e),
},
"ui.click" => {
let button = if s("button") == Some("right") { egui::PointerButton::Secondary } else { egui::PointerButton::Primary };
let count = p.get("count").and_then(Json::as_u64).unwrap_or(1).min(u64::from(u32::MAX)) as u32;
match push_click(app, egui::pos2(f("x"), f("y")), button, count, modifiers(p)) {
Ok(()) => ok(Json::Null),
Err(e) => err(e),
}
}
"ui.drag" => {
let steps = p.get("steps").and_then(Json::as_u64).unwrap_or(8).min(u64::from(u32::MAX)) as usize;
match push_drag(app, egui::pos2(f("x"), f("y")), egui::pos2(f("toX"), f("toY")), steps, modifiers(p)) {
Ok(()) => ok(Json::Null),
Err(e) => err(e),
}
}
"ui.cell.click" => {
let Some(c) = s("cell").and_then(CellRef::parse) else { return err("missing `cell`") };
let Some(pos) = cell_center(app, c) else { return err("no grid yet") };
let button = if s("button") == Some("right") { egui::PointerButton::Secondary } else { egui::PointerButton::Primary };
let count = p.get("count").and_then(Json::as_u64).unwrap_or(1).min(u64::from(u32::MAX)) as u32;
match push_click(app, pos, button, count, modifiers(p)) {
Ok(()) => ok(json!({"x": pos.x, "y": pos.y})),
Err(e) => err(e),
}
}
"ui.cell.drag" => {
let (Some(a), Some(b)) = (s("from").and_then(CellRef::parse), s("to").and_then(CellRef::parse)) else {
return err("missing `from`/`to`");
};
let (Some(pa), Some(pb)) = (cell_center(app, a), cell_center(app, b)) else { return err("no grid yet") };
match push_drag(app, pa, pb, 8, modifiers(p)) {
Ok(()) => ok(Json::Null),
Err(e) => err(e),
}
}
"ui.resize" => {
ctx.send_viewport_cmd(egui::ViewportCommand::InnerSize(egui::vec2(f("width").max(400.0), f("height").max(300.0))));
ok(Json::Null)
}
"ui.focus" => {
ctx.send_viewport_cmd(egui::ViewportCommand::Focus);
ok(Json::Null)
}
"ui.screenshot" => return Outcome::Screenshot { path: s("path").map(str::to_string) },
"app.open" => {
let Some(path) = s("path") else { return err("missing `path`") };
// Not `open_path`: that asks for a missing password in a dialog, and programmatic
// calls never open one. A password-protected workbook takes `password` instead.
let r = app.run("file.open", json!({"path": path, "password": s("password")}));
if let Ok(r) = &r {
app.after_open(Some(path), r);
}
app.after_engine();
match (r, app.message.take()) {
(Err(e), _) => err(crate::clean_error(&e)),
(Ok(_), Some((_, m))) => err(m),
(Ok(_), None) => ok(json!({"title": app.session.active().map(|d| d.display_title())})),
}
}
"app.save" => wrap(app.run("file.save", json!({"path": s("path")}))),
"app.quit" => {
// Programmatic calls never open dialogs: quitting from here doesn't ask about unsaved work.
app.allow_close = true;
ctx.send_viewport_cmd(egui::ViewportCommand::Close);
ok(Json::Null)
}
// Anything else that names a command runs it.
other if gridcraft_engine::find_command(other).is_some() => wrap(direct(app, other, p, true)),
other => err(format!("unknown method `{other}`")),
};
ctx.request_repaint();
out
}
/// Drains queued control requests, drops requests whose client stopped waiting, handles immediate outcomes and admits screenshots, then requests a repaint while synthetic input remains.
pub fn poll(app: &mut SheetApp, ctx: &egui::Context) {
let Some(rx) = app.control_rx.take() else { return };
while let Ok(req) = rx.try_recv() {
// A request whose sender stopped waiting is dropped unrun: running it would apply a
// command the client was told had failed, and its reply would go nowhere (#1914).
if !req.take() {
continue;
}
let outcome = handle(app, ctx, &req.method, &req.params);
match outcome {
Outcome::Done(v) => {
let _ = req.reply.send(v);
}
Outcome::Screenshot { path } => admit(app, ctx, path, req.reply),
}
}
app.control_rx = Some(rx);
if !app.synthetic.is_empty() {
ctx.request_repaint();
}
}
/// Put the request token on every screenshot reply (success, rejection, timeout), so a client can
/// correlate an asynchronous capture even when the reply order differs from the request order.
fn with_token(mut reply: Json, token: u64) -> Json {
if let Some(object) = reply.as_object_mut() {
object.insert("request".into(), json!(token));
}
reply
}
/// Returns the next screenshot token, wrapping and skipping zero.
fn next_token(app: &mut SheetApp) -> u64 {
let mut token = app.shots.token.wrapping_add(1);
if token == 0 {
token = 1;
}
app.shots.token = token;
token
}
/// Admit one screenshot request against the count and byte budgets **before** any capture is
/// issued. A rejected request gets one error reply and never evicts an earlier request.
fn admit(app: &mut SheetApp, ctx: &egui::Context, path: Option<String>, reply: Sender<ControlResponse>) {
let token = next_token(app);
let geometry = current_capture_geometry(app, ctx);
let expected = geometry.expected_size();
let base64 = path.is_none();
// A minimized or not-yet-laid-out window has no size: reserve the largest image the
// per-image limit allows and keep the request queued. Issuance waits for a real size, and the
// deadline reports a timeout if none arrives.
let bytes = match expected {
Some(size) => {
let Some(bytes) = geometry.retained_bytes() else {
reject_shot(reply, token, "screenshot failed: the window size overflows the screenshot budget");
return;
};
if bytes > SCREENSHOT_MAX_IMAGE_BYTES {
reject_shot(
reply,
token,
format!(
"screenshot budget exceeded: {bytes} bytes for one {}Γ{} image, over the {SCREENSHOT_MAX_IMAGE_BYTES}-byte per-image limit",
size[0], size[1]
),
);
return;
}
if let Err(message) = check_encoding_budget(size, base64) {
reject_shot(reply, token, message);
return;
}
bytes
}
None => UNKNOWN_CAPTURE_BYTES,
};
if app.shots.requests.len() >= SCREENSHOT_MAX_REQUESTS {
reject_shot(
reply,
token,
format!("screenshot budget exceeded: {} requests are already outstanding (limit {SCREENSHOT_MAX_REQUESTS})", app.shots.requests.len()),
);
return;
}
let reserved = app.shots.reserved().saturating_add(bytes);
if reserved > SCREENSHOT_MAX_AGGREGATE_BYTES {
reject_shot(
reply,
token,
format!(
"screenshot budget exceeded: {reserved} bytes reserved by outstanding requests, over the {SCREENSHOT_MAX_AGGREGATE_BYTES}-byte aggregate limit"
),
);
return;
}
if let Some(size) = expected
&& let Err(message) = check_peak_budget(reserved, size, base64)
{
reject_shot(reply, token, message);
return;
}
let now = crate::monotonic_ms();
let document = app.session.active().map(|d| d.uid);
let epoch = note_capture_geometry(app, geometry);
app.shots.requests.push(Shot {
token,
path,
reply,
deadline: now + 8000.0,
ready_at: now + 100.0,
frames: 0,
settle_pass: None,
issued: false,
retries: 0,
geometry,
viewport_id: geometry.viewport_id,
document,
epoch,
expected,
bytes,
// Issued only from `ui`, so the slot is created there against the geometry in force.
slot: None,
});
// A queued request with a capturable size has not issued a paint-requesting command yet;
// `logic` keeps asking for hidden paints until `issue_screenshots` runs. A size-less request
// asks for none (see `Shots::needs_hidden_paint`).
ctx.request_repaint();
}
/// Builds the standard token-carrying timeout reply for a screenshot request.
fn timeout_reply(message: &str, token: u64) -> Json {
json!({"ok": false, "error": message, "request": token})
}
#[cfg(test)]
mod tests;
No file is open. Choose one in the tree, or press Ctrl+O (βO on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.