Errors the page can branch on
A failed call answers an envelope, never a thrown transport error:
{"error": {"message": "invalid payload: missing field `name`", "kind": "payload", "method": "greet"}}
The shim turns that into a rejected promise, so ordinary try/catch works:
try {
await window.voussoir.invoke("save", { path });
} catch (error) {
const { kind, method, message } = error as {
kind: "unknown" | "payload" | "handler" | "panic" | "busy" | "timeout" | "runtime";
method: string;
message: string;
};
if (kind === "unknown") hideSaveButton();
else showToast(`${method}: ${message}`);
}
The seven kinds
kind | Raised by | What the page should do |
|---|---|---|
unknown | no handler, or the allowlist withheld it | treat the command as absent; do not retry |
payload | the request did not match the typed argument | a bug in the page; log it |
handler | the handler returned Err | show the message; it is meant for a user |
panic | the handler panicked | show the message, keep the window; report it |
busy | every worker-thread slot was taken | retry shortly; nothing was started |
timeout | the shim stopped waiting (raised in the page, not in Rust) | the command may still be running; do not assume it failed |
runtime | the webview or event loop failed | fatal for the window; offer a restart |
unknown covers both a missing command and a denied one on purpose. A page must
not be able to probe which commands exist but were withheld, so the two are
indistinguishable from inside the webview.
Writing an error
fn save(payload: &Value) -> Result<Value, voussoir::Error> {
let path = payload
.get("path")
.and_then(Value::as_str)
.ok_or_else(|| voussoir::Error::Payload("save needs a \"path\" string".to_owned()))?;
std::fs::write(path, b"")
.map_err(|error| voussoir::Error::Handler(format!("could not write {path}: {error}")))?;
Ok(Value::Null)
}
Use Payload for a malformed request and Handler for everything a user might
see. A Handler message is rendered verbatim in a toast by most apps, so write it
as a sentence, not a debug string.
Panics
A panic inside a handler is caught before it crosses the webview's FFI boundary,
where unwinding would abort the process. The page gets kind: "panic" and the app
keeps running with its windows and unsaved work intact. The panic is also recorded
in the diagnostics buffer and in __voussoir_reports, which is why a crash in the
field is diagnosable rather than a blank window.
Errors that never reach the page
A request dropped by the allowlist check and a bridge message that is not JSON are
recorded in voussoir dev --verbose instead. They are programming errors in the shell
or the page, not something a user action can cause, and answering them would leak
which commands exist.