Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Control channel: control.running lists what the app is running, across connections (#3654) (#3689)

Mateusz Sychfdec948abc49
diff --git a/apps/solidcraft/src/control_server.rs b/apps/solidcraft/src/control_server.rs
index c7ee296adf..5466f0b4e9 100644
--- a/apps/solidcraft/src/control_server.rs
+++ b/apps/solidcraft/src/control_server.rs
@@ -3,9 +3,10 @@
use std::io::{BufRead, BufReader, Write};
use std::net::{TcpListener, TcpStream};
-use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
use std::sync::mpsc::{Receiver, Sender, TryRecvError, channel};
-use std::time::Duration;
+use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
+use std::time::{Duration, Instant};
use serde_json::{Value, json};
use solidcraft_engine::MAX_LINE;
@@ -178,11 +179,137 @@ struct Pending {
reply: Receiver<Value>,
}
+/// Every request the app has been sent and not answered yet, from every connection, for
+/// `control.running` (#3654). Each connection's own thread answers that, so it never waits behind
+/// a running request.
+struct Running {
+ list: Mutex<Vec<InFlight>>,
+ connections: AtomicU64,
+ keys: AtomicU64,
+}
+
+/// What `control.running` says about a request: never its parameters beyond the command id.
+struct InFlight {
+ key: u64,
+ connection: u64,
+ id: Value,
+ method: String,
+ command: Option<&'static str>,
+ steps: Option<usize>,
+ since: Instant,
+ started: Arc<AtomicBool>,
+}
+
+/// The app's requests, from both of its listeners.
+static RUNNING: Running = Running::new();
+
+impl Running {
+ const fn new() -> Self {
+ Running { list: Mutex::new(Vec::new()), connections: AtomicU64::new(0), keys: AtomicU64::new(0) }
+ }
+
+ fn lock(&self) -> MutexGuard<'_, Vec<InFlight>> {
+ self.list.lock().unwrap_or_else(PoisonError::into_inner)
+ }
+
+ /// List `req`, sent on `connection`, until the returned ticket is dropped.
+ fn add(&'static self, connection: u64, id: &Value, req: &ControlRequest) -> Ticket {
+ let key = self.keys.fetch_add(1, Ordering::Relaxed);
+ // Ids and methods come from the client: only short ones are repeated to the others.
+ let id = match id {
+ Value::Number(_) => id.clone(),
+ Value::String(s) if s.len() <= 64 => id.clone(),
+ _ => Value::Null,
+ };
+ let p = &req.params;
+ let command = match req.method.as_str() {
+ "engine.execute" | "command" => p.get("command").and_then(Value::as_str).and_then(solidcraft_engine::find_command).map(|c| c.id),
+ _ => None,
+ };
+ let steps = match req.method.as_str() {
+ "engine.batch" | "engine.script" => p.get("commands").and_then(Value::as_array).map(Vec::len),
+ _ => None,
+ };
+ let method = req.method.chars().take(64).collect();
+ let started = req.started.clone();
+ self.lock().push(InFlight { key, connection, id, method, command, steps, since: Instant::now(), started });
+ Ticket { running: self, key }
+ }
+
+ /// The `control.running` result, as `asker`'s connection sees it.
+ fn result(&self, asker: u64) -> Value {
+ let rows: Vec<Value> = self
+ .lock()
+ .iter()
+ .map(|e| {
+ let mut r = json!({
+ "connection": e.connection,
+ "id": e.id,
+ "method": e.method,
+ "running_s": (e.since.elapsed().as_secs_f64() * 10.0).round() / 10.0,
+ "queued": !e.started.load(Ordering::Relaxed),
+ });
+ if let Some(c) = e.command {
+ r["command"] = json!(c);
+ }
+ if let Some(n) = e.steps {
+ r["steps"] = json!(n);
+ }
+ if e.connection == asker {
+ r["self"] = json!(true);
+ }
+ r
+ })
+ .collect();
+ json!({"running": rows})
+ }
+}
+
+/// A listed request; dropped when its reply arrives.
+struct Ticket {
+ running: &'static Running,
+ key: u64,
+}
+
+impl Drop for Ticket {
+ fn drop(&mut self) {
+ let key = self.key;
+ self.running.lock().retain(|e| e.key != key);
+ }
+}
+
+/// The reply to a timed-out request, received on a thread of its own so the request stays listed
+/// until the app answers, also once its connection has closed (#3654).
+fn watch(reply: Receiver<Value>, ticket: Ticket) -> Receiver<Value> {
+ let (late_tx, late_rx) = channel();
+ // A small thread per timed-out request (each connection has at most one). If none can be
+ // made, the reply is lost and `control.pending` says the app ended the request without one.
+ // The reply is passed on before the request leaves the list: once `control.running` no longer
+ // shows it, its connection's `control.pending` has it.
+ let _ = std::thread::Builder::new().stack_size(64 * 1024).spawn(move || {
+ if let Ok(v) = reply.recv() {
+ let _ = late_tx.send(v);
+ }
+ drop(late_tx);
+ drop(ticket);
+ });
+ late_rx
+}
+
fn serve(stream: TcpStream, token: &str, tx: Sender<ControlRequest>, ctx: egui::Context, patient: bool) {
- serve_with(stream, token, tx, ctx, patient, WAITS);
+ serve_with(stream, token, tx, ctx, patient, WAITS, &RUNNING);
}
-fn serve_with(stream: TcpStream, token: &str, tx: Sender<ControlRequest>, ctx: egui::Context, patient: bool, waits: Waits) {
+fn serve_with(
+ stream: TcpStream,
+ token: &str,
+ tx: Sender<ControlRequest>,
+ ctx: egui::Context,
+ patient: bool,
+ waits: Waits,
+ running: &'static Running,
+) {
+ let connection = running.connections.fetch_add(1, Ordering::Relaxed) + 1;
let Ok(read) = stream.try_clone() else { return };
let mut out = stream;
let mut reader = BufReader::new(read);
@@ -216,13 +343,16 @@ fn serve_with(stream: TcpStream, token: &str, tx: Sender<ControlRequest>, ctx: e
let id = msg.get("id").cloned().unwrap_or(Value::Null);
let method = msg.get("method").and_then(Value::as_str).unwrap_or("").to_string();
let params = msg.get("params").cloned().unwrap_or(json!({}));
- // A request that timed out may have finished since (#1618).
- let late = pending.as_ref().and_then(|p| match p.reply.try_recv() {
+ // A request that timed out may have finished since (#1618). `control.running` only
+ // looks, so it leaves that reply where it is.
+ let late = pending.as_ref().filter(|_| method != "control.running").and_then(|p| match p.reply.try_recv() {
Ok(reply) => Some(reply),
Err(TryRecvError::Disconnected) => Some(json!({"ok": false, "error": "the app ended the request without a reply"})),
Err(TryRecvError::Empty) => None,
});
- let mut r = if method == "control.pending" {
+ let mut r = if method == "control.running" {
+ json!({"ok": true, "result": running.result(connection)})
+ } else if method == "control.pending" {
match (pending.take(), late) {
(None, _) => json!({"ok": true, "result": {"pending": null}}),
(Some(p), Some(reply)) => json!({"ok": true, "result": {"pending": p.id, "method": p.method, "done": true, "reply": reply}}),
@@ -243,6 +373,7 @@ fn serve_with(stream: TcpStream, token: &str, tx: Sender<ControlRequest>, ctx: e
// A batch replaces many short requests: the whole of it may take long (#743).
let wait = if patient || method == "engine.batch" { waits.long } else { waits.short };
let (req, rrx) = ControlRequest::new(method.clone(), params);
+ let ticket = running.add(connection, &id, &req);
if tx.send(req).is_err() {
break;
}
@@ -251,7 +382,7 @@ fn serve_with(stream: TcpStream, token: &str, tx: Sender<ControlRequest>, ctx: e
Ok(r) => r,
Err(_) => {
let r = json!({"ok": false, "running": true, "error": format!("timeout: `{method}` is still running in the app and will still apply; ask `control.pending` for its result")});
- pending = Some(Pending { id: id.clone(), method, reply: rrx });
+ pending = Some(Pending { id: id.clone(), method, reply: watch(rrx, ticket) });
r
}
}
@@ -307,9 +438,10 @@ mod tests {
}
});
let waits = Waits { short: Duration::from_millis(100), long: Duration::from_millis(100) };
+ static RUNNING: Running = Running::new();
std::thread::spawn(move || {
if let Some(stream) = listener.incoming().flatten().next() {
- serve_with(stream, token, tx, egui::Context::default(), false, waits);
+ serve_with(stream, token, tx, egui::Context::default(), false, waits, &RUNNING);
}
});
let s = TcpStream::connect(addr).unwrap();
@@ -349,6 +481,102 @@ mod tests {
assert_eq!(*ran.lock().unwrap(), ["slow", "ui.view"], "the busy request never reached the app");
}
+ /// #3654: `control.running` answers on every connection, at once, with what any connection
+ /// has the app running or queued (command ids, never parameters); a timed-out request stays
+ /// listed until the app answers it, and an idle app lists nothing.
+ #[test]
+ fn every_connection_sees_what_the_app_is_running() {
+ static RUNNING: Running = Running::new();
+ let token = "0123456789abcdef0123456789abcdef";
+ let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+ let addr = listener.local_addr().unwrap();
+ let (tx, rx) = channel::<ControlRequest>();
+ // The window: one request at a time, as `drain_control` takes them; the export is held
+ // until the test lets it go.
+ let (gate_tx, gate_rx) = channel::<()>();
+ std::thread::spawn(move || {
+ for req in rx {
+ req.started.store(true, Ordering::Relaxed);
+ if req.method == "engine.execute" {
+ let _ = gate_rx.recv();
+ }
+ let _ = req.reply.send(json!({"ok": true, "result": req.method}));
+ }
+ });
+ let waits = Waits { short: Duration::from_millis(100), long: Duration::from_secs(60) };
+ std::thread::spawn(move || {
+ for stream in listener.incoming().flatten() {
+ let tx = tx.clone();
+ std::thread::spawn(move || serve_with(stream, token, tx, egui::Context::default(), false, waits, &RUNNING));
+ }
+ });
+ let open = || {
+ let s = TcpStream::connect(addr).unwrap();
+ s.set_read_timeout(Some(Duration::from_secs(10))).unwrap();
+ let mut out = s.try_clone().unwrap();
+ let mut lines = BufReader::new(s);
+ move |v: Value| -> Value {
+ writeln!(out, "{v}").unwrap();
+ let mut l = String::new();
+ lines.read_line(&mut l).unwrap();
+ serde_json::from_str(&l).unwrap()
+ }
+ };
+ let running = |ask: &mut dyn FnMut(Value) -> Value, until: &dyn Fn(&[Value]) -> bool| {
+ let deadline = Instant::now() + Duration::from_secs(10);
+ loop {
+ let r = ask(json!({"id": 0, "method": "control.running", "token": token}));
+ let rows = r["result"]["running"].as_array().cloned().unwrap_or_default();
+ if until(&rows) || Instant::now() > deadline {
+ return (r, rows);
+ }
+ std::thread::sleep(Duration::from_millis(10));
+ }
+ };
+ let mut watcher = open();
+ let (r, rows) = running(&mut watcher, &|_| true);
+ assert!(r["ok"] == true && rows.is_empty(), "idle: {r}");
+
+ let mut export = open();
+ let path = "/private/part.step";
+ let params = json!({"command": "file.export", "params": {"path": path}});
+ let r = export(json!({"id": 7, "method": "engine.execute", "params": params, "token": token}));
+ assert_eq!(r["running"], true, "{r}");
+ // A batch from another connection waits behind the export.
+ let mut batch = open();
+ let queued = std::thread::spawn(move || {
+ let steps = json!([{"command": "solid.box"}, {"command": "solid.box"}]);
+ batch(json!({"id": "b", "method": "engine.batch", "params": {"commands": steps}, "token": token}))
+ });
+ // The window may not have taken the export yet, even though it timed out.
+ let (r, rows) = running(&mut watcher, &|rows| rows.len() == 2 && rows[0]["queued"] == false);
+ assert_eq!(rows.len(), 2, "{r}");
+ let (e, b) = (&rows[0], &rows[1]);
+ assert_eq!(
+ (&e["id"], &e["method"], &e["command"], &e["queued"]),
+ (&json!(7), &json!("engine.execute"), &json!("file.export"), &json!(false)),
+ "{r}"
+ );
+ assert!(e["running_s"].as_f64().is_some_and(|s| s >= 0.1), "{r}");
+ assert_eq!((&b["id"], &b["method"], &b["steps"], &b["queued"]), (&json!("b"), &json!("engine.batch"), &json!(2), &json!(true)), "{r}");
+ assert_ne!(e["connection"], b["connection"], "{r}");
+ assert!(rows.iter().all(|row| row.get("self").is_none()), "{r}");
+ assert!(!r.to_string().contains(path), "parameters stay with their connection: {r}");
+ // The connection whose request timed out may ask too, and sees its own marked.
+ let r = export(json!({"id": 8, "method": "control.running"}));
+ let own: Vec<&Value> = r["result"]["running"].as_array().unwrap().iter().filter(|row| row["self"] == true).collect();
+ assert_eq!(own.len(), 1, "{r}");
+ assert_eq!(own[0]["command"], "file.export", "{r}");
+
+ gate_tx.send(()).unwrap();
+ assert_eq!(queued.join().unwrap()["result"], "engine.batch");
+ let (r, rows) = running(&mut watcher, &|rows| rows.is_empty());
+ assert!(rows.is_empty(), "done: {r}");
+ // Asking `control.running` did not take the export's reply from its connection.
+ let r = export(json!({"id": 9, "method": "control.pending"}));
+ assert_eq!((&r["result"]["pending"], &r["result"]["done"]), (&json!(7), &json!(true)), "{r}");
+ }
+
/// #205: a connection runs nothing until a request carries the launch's token; a wrong or
/// missing token, or garbage, is refused and the connection closed. Once shown, the token
/// need not be repeated on that connection.
diff --git a/crates/mcp/src/backend.rs b/crates/mcp/src/backend.rs
index e3b2c20780..585a2b0904 100644
--- a/crates/mcp/src/backend.rs
+++ b/crates/mcp/src/backend.rs
@@ -10,7 +10,7 @@ use solidcraft_engine::render::StandardView;
use solidcraft_engine::view::Guides;
/// Something that answers control-channel methods: `engine.execute`, `engine.commands`,
-/// `document.inspect`, `ui.view`, `ui.render`, `ui.screenshot`.
+/// `document.inspect`, `ui.view`, `ui.render`, `ui.screenshot`, `control.running`.
pub trait Backend {
fn call(&mut self, method: &str, params: Value) -> Result<Value, String>;
/// True when a real window is attached (`ui.screenshot` can capture it).
@@ -301,6 +301,8 @@ impl Backend for Headless {
}))
}
"ui.screenshot" => Err("no window in headless mode; use ui.render".into()),
+ // Calls run here one at a time: none is running while this one is asked.
+ "control.running" => Ok(json!({"running": []})),
other => Err(format!("unknown method `{other}`")),
}
}
diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rs
index 71cdb9513d..c17e332b6e 100644
--- a/crates/mcp/src/tests.rs
+++ b/crates/mcp/src/tests.rs
@@ -100,6 +100,7 @@ fn handshake_and_tools_list() {
"undo",
"redo",
"crash_reports",
+ "running",
"new_design",
"open",
"save",
@@ -114,6 +115,8 @@ fn handshake_and_tools_list() {
let cmds = tool(&mut s, "list_commands", json!({"filter": "fillet"}));
assert!(cmds.as_array().unwrap().iter().any(|c| c["id"] == "solid.fillet"), "{cmds}");
assert!(cmds.as_array().unwrap().len() < 5);
+ // Headless, calls run one at a time: none is running while `running` is asked (#3654).
+ assert_eq!(tool(&mut s, "running", json!({})), json!({"running": []}));
let res = call(&mut s, 5, "resources/list", json!({}));
assert_eq!(res["result"]["resources"].as_array().unwrap().len(), 2);
@@ -1348,6 +1351,17 @@ fn methods(b: &Recorder) -> Vec<&str> {
b.calls.iter().map(|(m, _)| m.as_str()).collect()
}
+/// #3654: bridged, `running` asks the app's `control.running`; an older app's refusal is the
+/// tool's error.
+#[test]
+fn running_asks_the_app() {
+ let mut b = Recorder { calls: Vec::new(), batch: Ok(json!({})) };
+ let r = crate::tools::call_tool(&mut b, "running", &json!({}));
+ assert_eq!(methods(&b), ["control.running"]);
+ assert_eq!(r["isError"], json!(true), "{r}");
+ assert!(r["content"][0]["text"].as_str().is_some_and(|t| t.starts_with("unknown method")), "{r}");
+}
+
/// #743: bridged to an app that has `engine.batch`, a batch is one control request.
#[test]
fn batch_is_one_engine_batch_call() {
@@ -1555,7 +1569,7 @@ fn tool_annotations_tell_the_whole_truth() {
for name in ["execute", "batch", "save", "export", "open", "screenshot"] {
assert_eq!(hints(name), (false, true, true), "{name}");
}
- for name in ["list_commands", "describe_command", "inspect_design", "measure", "body_topology", "crash_reports"] {
+ for name in ["list_commands", "describe_command", "inspect_design", "measure", "body_topology", "crash_reports", "running"] {
assert_eq!(hints(name), (true, false, false), "{name}");
}
assert_eq!(hints("new_design"), (false, true, false));
diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs
index 7ef0d822d0..5453c8031e 100644
--- a/crates/mcp/src/tools.rs
+++ b/crates/mcp/src/tools.rs
@@ -255,6 +255,16 @@ pub fn tool_definitions() -> Vec<Value> {
),
Effect::ReadOnly,
),
+ tool(
+ "running",
+ "What the app is running",
+ "What the app is running or has queued right now, for every client: each request's connection and id, method, \
+ command id (a batch's step count), seconds since it arrived (running_s) and whether it still waits its turn \
+ (queued); `self` marks a request sent on the connection that asks. Answers at once, even while the app is busy, \
+ and never shows parameters. Ask it when a call timed out or the app seems slow, before sending a change again.",
+ obj(json!({}), &[]),
+ Effect::ReadOnly,
+ ),
tool("undo", "Undo", "Undo the last change to the design.", obj(json!({}), &[]), Effect::Edits),
tool("redo", "Redo", "Redo the last undone change.", obj(json!({}), &[]), Effect::Edits),
tool(
@@ -454,6 +464,7 @@ fn dispatch(b: &mut dyn Backend, name: &str, a: &Map<String, Value>) -> Result<V
Some(_) => exec(b, "diagnostics.crash_report", pick(a, &["id"])),
None => exec(b, "diagnostics.crash_reports", pick(a, &["limit"])),
},
+ "running" => b.call("control.running", json!({})),
"undo" => exec(b, "edit.undo", json!({})),
"redo" => exec(b, "edit.redo", json!({})),
"new_design" => exec(b, "file.new", pick(a, &["name"])),
diff --git a/crates/ui-egui/src/control.rs b/crates/ui-egui/src/control.rs
index 932bb7f7fc..2576a58028 100644
--- a/crates/ui-egui/src/control.rs
+++ b/crates/ui-egui/src/control.rs
@@ -56,12 +56,14 @@ pub struct ControlRequest {
pub method: String,
pub params: Value,
pub reply: Sender<ControlResponse>,
+ /// Set once the window starts on it; until then it waits its turn (`control.running`, #3654).
+ pub started: std::sync::Arc<std::sync::atomic::AtomicBool>,
}
impl ControlRequest {
pub fn new(method: impl Into<String>, params: Value) -> (Self, std::sync::mpsc::Receiver<ControlResponse>) {
let (tx, rx) = std::sync::mpsc::channel();
- (Self { method: method.into(), params, reply: tx }, rx)
+ (Self { method: method.into(), params, reply: tx, started: Default::default() }, rx)
}
}
diff --git a/crates/ui-egui/src/lib.rs b/crates/ui-egui/src/lib.rs
index 9c8c3246c5..67b437b2bb 100644
--- a/crates/ui-egui/src/lib.rs
+++ b/crates/ui-egui/src/lib.rs
@@ -1706,6 +1706,7 @@ impl SolveApp {
}
continue;
}
+ req.started.store(true, std::sync::atomic::Ordering::Relaxed);
// Opening or importing a file: answered when the file is in, without freezing the window.
let Some(req) = file_load::control(self, req) else {
ctx.request_repaint();
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index b5ef79c2c1..5e852bb055 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -59,6 +59,25 @@ with `control.pending`: `{"pending": <id>, "method": …, "done": false}` while
connection is refused at once with `{"ok": false, "busy": true, "error": "busy: …"}` and not
run, so nothing is queued to apply unseen behind it.
+`control.pending` answers only for its own connection. `control.running` answers for the whole
+app, the same on every connection, at once (it never waits behind a running request, and a
+connection may ask it while it is `busy`): every request the app has been sent and has not
+answered yet, oldest first, from any connection, including a timed-out one whose connection has
+since closed:
+
+```text
+{"id":1,"method":"control.running","token":"…"}
+→ {"id":1,"ok":true,"result":{"running":[
+ {"connection":3,"id":17,"method":"engine.execute","command":"file.export","running_s":312.4,"queued":false},
+ {"connection":5,"id":2,"method":"engine.batch","steps":12,"running_s":4.1,"queued":true,"self":true}]}}
+```
+
+`running_s` counts seconds since the request arrived; `queued` is true while it still waits its
+turn behind another. `command` is the command id of `engine.execute` (a known one only) and
+`steps` the length of `engine.batch` or `engine.script`; parameters are never shown, so file
+paths and expressions stay with the connection that sent them. `self` marks the asking
+connection's own request. `{"running": []}` when the app is idle.
+
Any request's `params` may carry `allow_paths: ["/abs/folder", …]`: every file that request
reads, writes or deletes (command paths such as `file.export`'s `path` or `doc.recovery_*`'s
`dir`, `ui.render`, `ui.screenshot`) must then lie inside one of those folders after `..` and
diff --git a/docs/mcp.md b/docs/mcp.md
index c6db0875f1..5741e16954 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -164,6 +164,7 @@ They cover the workflow, the command shapes, how to verify with `measure`, and t
| `export` | `path`, `format?` (step, 3mf, 3mf-tagged, stl, stla, obj, urdf), `bodies?`, `mesh_prefix?`, `effort?`, `velocity?` | STEP, 3MF or mesh export; URDF writes the whole assembly with its meshes next to it (`docs/urdf.md`). |
| `undo`, `redo` | — | Undo / redo one change. |
| `crash_reports` | `id?`, `limit?` | The crash reports on this computer, newest first; with `id`, the whole report (backtrace, command, recent commands, `design_path`/`replay_path`). See [crash-reports.md](crash-reports.md). |
+| `running` | - | What the app is running or has queued, for every client (`control.running`, see [control-protocol.md](control-protocol.md#limits)): each request's connection and id, method, command id or a batch's step count, `running_s` and `queued`, never its parameters. Answers at once while the app is busy: ask it when a call timed out before sending a change again. Headless: always `{"running": []}`. |
| `new_design` | `name?` | Start an empty design. |
| `open` | `path` | Open a `.solidcraft` design, a STEP file (`.step`/`.stp`) as a new design holding its bodies (an Import base feature), or a 3MF/STL file as mesh bodies. |
| `save` | `path?` | Save the design (to its current file without `path`). |