voussoir

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

kindRaised byWhat the page should do
unknownno handler, or the allowlist withheld ittreat the command as absent; do not retry
payloadthe request did not match the typed argumenta bug in the page; log it
handlerthe handler returned Errshow the message; it is meant for a user
panicthe handler panickedshow the message, keep the window; report it
busyevery worker-thread slot was takenretry shortly; nothing was started
timeoutthe shim stopped waiting (raised in the page, not in Rust)the command may still be running; do not assume it failed
runtimethe webview or event loop failedfatal 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.

Edit this page on GitHub