@livx.cc/appwrap 0.54.0 → 0.56.0

package/runtime-desktop/src-tauri/src/sidecar.rs

@@ -1,398 +0,0 @@
-//! Per-app extensibility: a Bun sidecar running the app's custom TS handlers (`desktop.handlers`).
-//!
-//! When `shell_config.json` carries a `handlers` path, `init()` spawns `bun <path>` with piped stdio at
-//! setup and reads its one-line `ready` announcement (methods it serves). The main bridge router then
-//! forwards any CLAIMED method to the sidecar over NDJSON and blocks on the matching response (per-call
-//! timeout). A single reader thread drains stdout and resolves the pending map by id; stderr is prefixed
-//! through to the shell's stderr.
-//!
-//! Wire protocol (appwrap sidecar protocol v1 — one JSON object per line):
-//!   sidecar → shell (spawn):  {"kind":"ready","methods":[…]}
-//!   shell   → sidecar:        {"kind":"request","id":"…","method":"…","params":{…}}
-//!   sidecar → shell:          {"kind":"response","id":"…","ok":true,"data":{…}}
-//!                       or:    {"kind":"response","id":"…","ok":false,"error":{"code":"…","message":"…"}}
-//!
-//! DEAD-SIDECAR SEMANTICS: a crash/EOF fails all in-flight calls with NATIVE_ERROR and marks the sidecar
-//! dead; subsequent calls to a still-CLAIMED method also return NATIVE_ERROR (not UNSUPPORTED). Rationale:
-//! these methods are app-custom — the kit has NO web fallback for them (its hybrid fallback only fires on
-//! UNSUPPORTED, and only for built-in kit modules), so returning UNSUPPORTED would gain no graceful
-//! web-degrade and would dishonestly report "feature absent" when the truth is "the handler backend
-//! crashed". NATIVE_ERROR lets the app detect the failure and degrade on its own terms.
-
-use serde_json::{json, Value};
-use std::collections::{HashMap, HashSet};
-use std::io::{BufRead, BufReader, Write};
-use std::process::{Child, ChildStdin, Command, Stdio};
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
-use std::sync::mpsc::{self, Receiver, Sender, SyncSender};
-use std::sync::{Arc, Mutex, OnceLock};
-use std::time::Duration;
-
-/// A dynamic-code error the app-custom sidecar can return (kit codes are open-ended app-side, so unlike
-/// the built-in handlers' `&'static str` codes we keep the sidecar's code string verbatim).
-pub type SidecarResult = Result<Value, (String, String)>;
-
-const READY_TIMEOUT: Duration = Duration::from_secs(5);
-const CALL_TIMEOUT: Duration = Duration::from_secs(30);
-
-struct Sidecar {
-    methods: HashSet<String>,
-    alive: Arc<AtomicBool>,
-    stdin: Mutex<ChildStdin>,
-    pending: Arc<Mutex<HashMap<String, Sender<Value>>>>,
-    child: Mutex<Child>,
-    next_id: AtomicU64,
-}
-
-static SIDECAR: OnceLock<Sidecar> = OnceLock::new();
-
-/// Parse one sidecar stdout line into a routable outcome. Pure — unit-tested.
-enum Line {
-    Ready(Vec<String>),
-    Response { id: String, value: Value },
-    Other,
-}
-
-fn parse_line(line: &str) -> Line {
-    let v: Value = match serde_json::from_str(line) {
-        Ok(v) => v,
-        Err(_) => return Line::Other,
-    };
-    match v["kind"].as_str() {
-        Some("ready") => {
-            let methods = v["methods"]
-                .as_array()
-                .map(|a| a.iter().filter_map(|m| m.as_str().map(str::to_string)).collect())
-                .unwrap_or_default();
-            Line::Ready(methods)
-        }
-        Some("response") => match v["id"].as_str() {
-            Some(id) => Line::Response { id: id.to_string(), value: v },
-            None => Line::Other,
-        },
-        _ => Line::Other,
-    }
-}
-
-/// Translate a sidecar `response` envelope into a router result. Pure — unit-tested.
-fn response_outcome(resp: &Value) -> SidecarResult {
-    if resp["ok"].as_bool() == Some(true) {
-        Ok(resp.get("data").cloned().unwrap_or(Value::Null))
-    } else {
-        let code = resp["error"]["code"].as_str().unwrap_or("NATIVE_ERROR").to_string();
-        let message = resp["error"]["message"].as_str().unwrap_or("handler error").to_string();
-        Err((code, message))
-    }
-}
-
-/// Resolve which Bun binary to spawn: the CLI-stamped absolute runtime (`handlersRuntime` =
-/// `process.execPath` of the bun that built the app) when it still exists, else a bare `bun`
-/// PATH lookup. The stamped path matters for GUI launches: Finder/launchd PATH is
-/// /usr/bin:/bin:/usr/sbin:/sbin — no ~/.bun/bin — so `bun` alone is unresolvable there.
-fn resolve_runtime(stamped: &str) -> String {
-    if !stamped.is_empty() && std::path::Path::new(stamped).exists() {
-        return stamped.to_string();
-    }
-    if !stamped.is_empty() {
-        eprintln!("[sidecar] stamped runtime missing ({stamped}) — falling back to `bun` (PATH lookup; GUI-launched apps have a minimal launchd PATH and may fail to spawn)");
-    } else {
-        eprintln!("[sidecar] no stamped runtime — falling back to `bun` (PATH lookup; GUI-launched apps have a minimal launchd PATH and may fail to spawn)");
-    }
-    "bun".to_string()
-}
-
-/// Drop any claimed method that falls under a built-in namespace so an app handler can never shadow
-/// a built-in (e.g. `storage.get`). Pure — unit-tested. Warns with the rejected list.
-fn filter_claims(methods: Vec<String>) -> Vec<String> {
-    let (rejected, kept): (Vec<String>, Vec<String>) = methods
-        .into_iter()
-        .partition(|m| crate::BUILTIN_METHOD_PREFIXES.iter().any(|p| m.starts_with(p)));
-    if !rejected.is_empty() {
-        eprintln!("[sidecar] rejecting handler method(s) that shadow built-ins: {rejected:?} — rename them outside the built-in namespaces");
-    }
-    kept
-}
-
-/// Spawn the Bun sidecar and block (≤5s, bounded by READY_TIMEOUT) on its `ready` line — intentional:
-/// sidecar methods must be claimable before the webview's first invoke. On timeout / malformed / spawn
-/// failure the error is logged and the shell runs WITHOUT a sidecar (the feature degrades to inert).
-/// Idempotent-ish: only the first successful init wins (OnceLock).
-pub fn init(path: &str, runtime: &str) {
-    if SIDECAR.get().is_some() {
-        return;
-    }
-    let bun = resolve_runtime(runtime);
-    let mut child = match Command::new(&bun)
-        .arg(path)
-        .stdin(Stdio::piped())
-        .stdout(Stdio::piped())
-        .stderr(Stdio::piped())
-        .spawn()
-    {
-        Ok(c) => c,
-        Err(e) => {
-            eprintln!("[sidecar] spawn `{bun} {path}` failed: {e} — running without custom handlers");
-            return;
-        }
-    };
-
-    let stdin = child.stdin.take().expect("piped stdin");
-    let stdout = child.stdout.take().expect("piped stdout");
-    let stderr = child.stderr.take();
-
-    let alive = Arc::new(AtomicBool::new(true));
-    let pending: Arc<Mutex<HashMap<String, Sender<Value>>>> = Arc::new(Mutex::new(HashMap::new()));
-
-    // stderr → shell stderr (prefixed).
-    if let Some(stderr) = stderr {
-        std::thread::spawn(move || {
-            for line in BufReader::new(stderr).lines().map_while(Result::ok) {
-                eprintln!("[sidecar:err] {line}");
-            }
-        });
-    }
-
-    // Reader thread: first line → ready (via ready_tx), then resolve responses by id.
-    let (ready_tx, ready_rx): (SyncSender<Option<Vec<String>>>, Receiver<Option<Vec<String>>>) =
-        mpsc::sync_channel(1);
-    let r_alive = alive.clone();
-    let r_pending = pending.clone();
-    std::thread::spawn(move || {
-        let mut reader = BufReader::new(stdout);
-        let mut got_ready = false;
-        let mut line = String::new();
-        loop {
-            line.clear();
-            match reader.read_line(&mut line) {
-                Ok(0) | Err(_) => break, // EOF or read error → sidecar gone
-                Ok(_) => {}
-            }
-            let trimmed = line.trim();
-            if trimmed.is_empty() {
-                continue;
-            }
-            match parse_line(trimmed) {
-                Line::Ready(methods) => {
-                    if !got_ready {
-                        got_ready = true;
-                        let _ = ready_tx.send(Some(methods));
-                    }
-                }
-                Line::Response { id, value } => {
-                    if let Some(tx) = r_pending.lock().unwrap().remove(&id) {
-                        let _ = tx.send(value);
-                    }
-                }
-                Line::Other => eprintln!("[sidecar] ignoring unrecognized line: {trimmed}"),
-            }
-        }
-        // Sidecar gone: mark dead and fail every in-flight call (dropping the senders makes the
-        // waiting recv_timeout return Disconnected → NATIVE_ERROR immediately).
-        r_alive.store(false, Ordering::SeqCst);
-        r_pending.lock().unwrap().clear();
-        if !got_ready {
-            let _ = ready_tx.send(None); // never announced → unblock init with a failure
-        }
-        eprintln!("[sidecar] reader exited — sidecar marked dead");
-    });
-
-    let methods = match ready_rx.recv_timeout(READY_TIMEOUT) {
-        Ok(Some(methods)) => filter_claims(methods),
-        Ok(None) => {
-            eprintln!("[sidecar] exited before announcing `ready` — running without custom handlers");
-            let _ = child.kill();
-            return;
-        }
-        Err(_) => {
-            eprintln!("[sidecar] no `ready` within {READY_TIMEOUT:?} — killing, running without custom handlers");
-            let _ = child.kill();
-            return;
-        }
-    };
-
-    eprintln!("[sidecar] ready — {} method(s): {:?}", methods.len(), methods);
-    let _ = SIDECAR.set(Sidecar {
-        methods: methods.into_iter().collect(),
-        alive,
-        stdin: Mutex::new(stdin),
-        pending,
-        child: Mutex::new(child),
-        next_id: AtomicU64::new(1),
-    });
-}
-
-/// True if a sidecar exists and ADVERTISED this method (regardless of liveness — a dead sidecar's
-/// methods still route here so they return NATIVE_ERROR, not UNSUPPORTED; see the module note).
-pub fn claims(method: &str) -> bool {
-    SIDECAR.get().is_some_and(|s| s.methods.contains(method))
-}
-
-/// Forward a claimed method to the sidecar and block on its response (≤30s). Called from a bridge
-/// worker thread (already off the main thread), so blocking here is fine.
-pub fn request(method: &str, params: &Value) -> SidecarResult {
-    let s = SIDECAR.get().ok_or_else(|| ("NATIVE_ERROR".into(), "no sidecar".into()))?;
-    if !s.alive.load(Ordering::SeqCst) {
-        return Err(("NATIVE_ERROR".into(), format!("handler sidecar is not running ({method})")));
-    }
-    let id = format!("sc-{}", s.next_id.fetch_add(1, Ordering::SeqCst));
-    let (tx, rx) = mpsc::channel::<Value>();
-    s.pending.lock().unwrap().insert(id.clone(), tx);
-
-    let envelope = json!({ "kind": "request", "id": id, "method": method, "params": params });
-    let line = format!("{envelope}\n");
-    if let Err(e) = (|| {
-        let mut w = s.stdin.lock().unwrap();
-        w.write_all(line.as_bytes())?;
-        w.flush()
-    })() {
-        s.pending.lock().unwrap().remove(&id);
-        return Err(("NATIVE_ERROR".into(), format!("sidecar write failed: {e}")));
-    }
-
-    match rx.recv_timeout(CALL_TIMEOUT) {
-        Ok(resp) => response_outcome(&resp),
-        Err(mpsc::RecvTimeoutError::Timeout) => {
-            s.pending.lock().unwrap().remove(&id);
-            Err(("NATIVE_ERROR".into(), format!("sidecar timeout after {CALL_TIMEOUT:?} ({method})")))
-        }
-        Err(mpsc::RecvTimeoutError::Disconnected) => {
-            // Reader thread dropped our sender = sidecar died mid-call.
-            Err(("NATIVE_ERROR".into(), format!("handler sidecar died during call ({method})")))
-        }
-    }
-}
-
-/// Kill the sidecar child (idempotent). Called on main-window teardown so the Bun process never outlives
-/// the shell. (`SIDECAR` is a `'static` OnceLock, so a Drop guard would never run at process exit — this
-/// explicit call is the reliable teardown; killing an already-dead child is a harmless no-op.)
-pub fn shutdown() {
-    if let Some(s) = SIDECAR.get() {
-        let _ = s.child.lock().unwrap().kill();
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn parse_ready_extracts_methods() {
-        match parse_line(r#"{"kind":"ready","methods":["a.b","a.c"]}"#) {
-            Line::Ready(m) => assert_eq!(m, vec!["a.b".to_string(), "a.c".to_string()]),
-            _ => panic!("expected Ready"),
-        }
-    }
-
-    #[test]
-    fn parse_ready_missing_methods_is_empty() {
-        match parse_line(r#"{"kind":"ready"}"#) {
-            Line::Ready(m) => assert!(m.is_empty()),
-            _ => panic!("expected Ready"),
-        }
-    }
-
-    #[test]
-    fn parse_response_carries_id_and_value() {
-        match parse_line(r#"{"kind":"response","id":"sc-1","ok":true,"data":{"x":1}}"#) {
-            Line::Response { id, value } => {
-                assert_eq!(id, "sc-1");
-                assert_eq!(value["data"]["x"], 1);
-            }
-            _ => panic!("expected Response"),
-        }
-    }
-
-    #[test]
-    fn parse_malformed_or_unknown_is_other() {
-        assert!(matches!(parse_line("not json"), Line::Other));
-        assert!(matches!(parse_line(r#"{"kind":"noise"}"#), Line::Other));
-        // response without id can't be routed → Other
-        assert!(matches!(parse_line(r#"{"kind":"response","ok":true}"#), Line::Other));
-    }
-
-    #[test]
-    fn outcome_ok_returns_data() {
-        let resp = json!({"kind":"response","id":"x","ok":true,"data":{"n":42}});
-        assert_eq!(response_outcome(&resp).unwrap(), json!({"n":42}));
-    }
-
-    #[test]
-    fn outcome_ok_missing_data_is_null() {
-        let resp = json!({"kind":"response","id":"x","ok":true});
-        assert_eq!(response_outcome(&resp).unwrap(), Value::Null);
-    }
-
-    #[test]
-    fn outcome_error_preserves_code_and_message() {
-        let resp = json!({"kind":"response","id":"x","ok":false,"error":{"code":"DENIED","message":"nope"}});
-        let (code, msg) = response_outcome(&resp).unwrap_err();
-        assert_eq!(code, "DENIED");
-        assert_eq!(msg, "nope");
-    }
-
-    #[test]
-    fn outcome_error_defaults_when_fields_absent() {
-        let resp = json!({"kind":"response","id":"x","ok":false});
-        let (code, msg) = response_outcome(&resp).unwrap_err();
-        assert_eq!(code, "NATIVE_ERROR");
-        assert_eq!(msg, "handler error");
-    }
-
-    /// Pending-map resolution: a response by id wakes exactly the matching waiter.
-    #[test]
-    fn pending_map_resolves_by_id() {
-        let pending: Arc<Mutex<HashMap<String, Sender<Value>>>> = Arc::new(Mutex::new(HashMap::new()));
-        let (tx, rx) = mpsc::channel::<Value>();
-        pending.lock().unwrap().insert("sc-1".into(), tx);
-
-        // Simulate the reader draining a response line for sc-1.
-        if let Line::Response { id, value } = parse_line(r#"{"kind":"response","id":"sc-1","ok":true,"data":5}"#) {
-            if let Some(t) = pending.lock().unwrap().remove(&id) {
-                t.send(value).unwrap();
-            }
-        }
-        let got = rx.recv_timeout(Duration::from_secs(1)).unwrap();
-        assert_eq!(response_outcome(&got).unwrap(), json!(5));
-        assert!(pending.lock().unwrap().is_empty());
-    }
-
-    /// Claims under a built-in namespace are dropped; app-namespaced ones survive.
-    #[test]
-    fn filter_claims_rejects_builtin_shadowing() {
-        let kept = filter_claims(vec![
-            "storage.get".into(),      // shadows built-in storage.*
-            "ui.alert".into(),         // shadows built-in ui.*
-            "app.handshake".into(),    // shadows built-in app.*
-            "push.x".into(),           // shadows built-in push.*
-            "biometrics.available".into(), // shadows built-in biometrics.*
-            "myapp.doThing".into(),    // fine
-            "storagex.get".into(),     // NOT under "storage." (prefix includes the dot)
-        ]);
-        assert_eq!(kept, vec!["myapp.doThing".to_string(), "storagex.get".to_string()]);
-    }
-
-    #[test]
-    fn filter_claims_keeps_all_when_no_shadowing() {
-        let kept = filter_claims(vec!["a.b".into(), "a.c".into()]);
-        assert_eq!(kept, vec!["a.b".to_string(), "a.c".to_string()]);
-    }
-
-    /// Runtime resolution: existing stamped path wins; missing/empty falls back to `bun`.
-    #[test]
-    fn resolve_runtime_prefers_existing_stamped_path() {
-        assert_eq!(resolve_runtime("/bin/ls"), "/bin/ls"); // any existing file
-        assert_eq!(resolve_runtime("/nonexistent/bun-xyz"), "bun");
-        assert_eq!(resolve_runtime(""), "bun");
-    }
-
-    /// Dropping the pending sender (sidecar death) makes the waiter observe Disconnected.
-    #[test]
-    fn dropped_sender_disconnects_waiter() {
-        let (tx, rx) = mpsc::channel::<Value>();
-        drop(tx);
-        assert!(matches!(
-            rx.recv_timeout(Duration::from_millis(50)),
-            Err(mpsc::RecvTimeoutError::Disconnected)
-        ));
-    }
-}

package/runtime-desktop/src-tauri/tauri.conf.json

@@ -1,14 +0,0 @@
-{
-  "$schema": "https://schema.tauri.app/config/2",
-  "productName": "hello-pwa-desktop",
-  "version": "0.1.0",
-  "identifier": "cc.livx.hellopwa.desktop",
-  "build": {
-    "frontendDist": "../../examples/hello-pwa/dist"
-  },
-  "app": {
-    "withGlobalTauri": true,
-    "security": { "csp": null }
-  },
-  "bundle": { "active": false }
-}