Wherry/docs/TAURI_BACKEND_API.md

Wherry Tauri backend API (design)

Goal: keep everything under src/domain, src/fs, src/protocols, src/storage, src/transfer as the Tauri backend. All of it already speaks in serde (camelCase) structs, so this is mostly a thin #[tauri::command] wrapper layer plus an event bus to replace the current per-frame egui polling.

State the current egui frontend polls every frame that the new frontend instead gets pushed to it via Tauri events (see "Events" below): state.queue_tasks (TransferQueue::all()), state.tabs[].status (ConnectionStatus).

Managed state (tauri::State)

Same objects lib.rs::run() already builds, handed to Tauri via .manage(...) instead of into FileManagerApp:

• Arc<Mutex<rusqlite::Connection>> — sqlite db (sites/bookmarks/history/settings)
• Arc<RemoteRegistry> — live connection_id -> Arc<dyn RemoteFs> map
• TransferQueue — shared transfer task list
• Arc<AtomicU32> — max_concurrent, mutated live by Settings → Transfers

transfer::worker::spawn_worker keeps running as-is inside tauri::Builder::setup, using the app handle to emit progress instead of the queue being polled.

Commands

Connections (src/protocols, src/fs/remote.rs)

• connect(params: ConnectionParams) -> Result<String, String> — dispatches to FtpClient::connect / SftpClient::connect_password|connect_key|connect_auto based on params.protocol/password/key_path; on success RemoteRegistry::insert(id, fs), db::add_history_entry(...), returns connection_id. Emits connection-status (Connecting then Connected/Error) — see Events.
• disconnect(connection_id: String) — RemoteRegistry::remove.

Remote file ops (RemoteFs trait, per connection_id)

• remote_list(connection_id: String, path: String) -> Result<Vec<FileEntry>, String>
• remote_stat(connection_id: String, path: String) -> Result<FileEntry, String>
• remote_mkdir(connection_id: String, path: String) -> Result<(), String>
• remote_rename(connection_id: String, from: String, to: String) -> Result<(), String>
• remote_delete(connection_id: String, path: String) -> Result<(), String>

All resolve Arc<dyn RemoteFs> from RemoteRegistry::get, return "connection not found" error if missing (mirrors worker.rs behavior).

Local file ops (src/fs/local.rs — already sync, no connection_id)

• local_list(path: String) -> Result<Vec<FileEntry>, String>
• local_home_dir() -> String
• local_mkdir(path: String) -> Result<(), String>
• local_rename(from: String, to: String) -> Result<(), String>
• local_delete(path: String) -> Result<(), String>
• local_open(path: String) -> Result<(), String> — reveal/open in system app
• local_move_into(src_path: String, dest_dir: String) -> Result<(), String> — drag&drop move

Transfers (src/transfer)

• enqueue_transfer(kind: TransferKind, connection_id: String, local_path: String, remote_path: String, file_name: String, total_bytes: u64) -> String — builds TransferTask::new(...), queue.push(task), returns task id. Worker picks it up same as today.
• list_tasks() -> Vec<TransferTask> — for initial load / reconnect after frontend refresh; live updates come from events, not polling.
• pause_task(id: String) / resume_task(id: String) — queue.update_state(id, TaskState::Paused/Queued) (worker's progress callback already checks for Paused/Cancelled each callback tick).
• cancel_task(id: String) — queue.update_state(id, TaskState::Cancelled).
• remove_task(id: String) — queue.remove(id) (for clearing completed/failed rows).
• set_max_concurrent(n: u32) — stores atomically + persists via db::set_u32.

Sites / bookmarks / history / settings (src/storage/db)

• list_sites, save_site(site: Site), delete_site(id: String)
• list_bookmarks() -> Vec<(i64, String, String)> (id, name, path), add_bookmark(name, path) -> i64, remove_bookmark(id: i64)
• list_history() -> Vec<HistoryRow>, clear_history(), find_history_conn_id(host, port, username) -> Option<String>
• get_pref_bool/str/u32(key), set_pref_bool/str/u32(key, value) — thin wrapper over storage::db::settings, used for confirm-before-delete, default local folder, language, transfer concurrency, panel visibility persistence if we decide to persist that (currently session-only in egui, per state/mod.rs comment) — confirm with FRONTEND_SPEC.md once written.

Credentials: keyring crate stays as-is; password storage keyed by ConnectionParams.id (stable id from history/sites), unchanged from current behavior — no new command needed beyond what connect already resolves internally.

Events (app -> frontend, app_handle.emit(...))

Replaces per-frame polling of queue.all() / tabs[].status in the egui loop:

• transfer-progress payload { id, transferredBytes, speed, etaSecs } — emitted from the same throttled callback in worker.rs::run_transfer (already rate-limited to ~10/s via ProgressThrottle), just add app_handle.emit(...) next to queue.update_progress(...).
• transfer-state-changed payload { id, state: TaskState } — emitted next to every queue.update_state(...) call (queued->running->completed/failed/cancelled/paused).
• connection-status-changed payload { connectionId, status: ConnectionStatus } — emitted from connect/disconnect and on unexpected drop (if/when we add liveness detection — not present today, egui doesn't detect mid-session drops either, so parity-only for v1).

Frontend subscribes once via @tauri-apps/api/event.listen, keeps a local task/connection map updated from these — no polling loop needed like queue.all() was in egui.

Serialization note

Every domain type already derives Serialize/Deserialize with #[serde(rename_all = "camelCase")] (ConnectionParams, FileEntry, Site, TransferTask, TaskState, Protocol, EntryKind, ConnectionStatus) — these cross the Tauri IPC boundary unchanged, no adapter layer needed. anyhow::Error doesn't implement Serialize, so every command returns Result<T, String> (.map_err(|e| e.to_string())), matching the existing convention of stringly-typed errors already used in TaskState::Failed(String).

Open question for scaffolding phase (task #3)

Whether to keep src/ as a single crate with a new src-tauri/ binary depending on it (wherry_lib is already staticlib/cdylib/rlib, so this fits cleanly), or fold src-tauri in place of main.rs/lib.rs::run(). Recommend the former — cleanest separation, no changes to domain/fs/protocols/storage/transfer needed at all, only lib.rs::run() and main.rs get replaced by Tauri's builder.