Skip to content

API

Jump to bottom
Seeker32 edited this page Aug 11, 2026 · 5 revisions

API 契约（invoke 命令与事件）

1. invoke 命令（请求/响应）

前端通过 @tauri-apps/api/core 的 invoke 调用。参数 camelCase，失败时返回 AppErrorInfo { code, detail }（语言无关的稳定错误 payload）。

Host

命令 参数 返回
list_hosts — HostConfig[]
save_host request: SaveHostRequest（含明文 password/passphrase，仅请求内存在） HostConfig[]（更新后的全量列表）
delete_host hostId: string HostConfig[]

Session

命令 参数 返回
open_session hostId: string SessionInfo
close_session sessionId: string —
write_terminal sessionId: string, data: string —
resize_terminal sessionId: string, cols: number, rows: number —
list_sessions — SessionInfo[]（状态直接来自后端运行时，无前端回写）

Monitor

命令 参数 返回
start_monitoring sessionId: string TaskInfo
stop_monitoring taskId: string —
get_monitor_status sessionId: string MonitorSnapshot

SFTP

命令 参数 返回
sftp_list_dir sessionId: string, path: string RemoteEntry[]
sftp_download sessionId: string, remotePath: string, localPath: string TransferTask（Pending 状态入队）
sftp_upload sessionId: string, localPath: string, remotePath: string TransferTask（remotePath 为目标目录，后端自动拼接文件名）
sftp_cancel_task taskId: string —

Logging

命令 参数 返回
set_log_level level: string（error / warn / info / debug / trace） —（运行时调整后端日志过滤等级）

2. 事件（后端 → 前端流式推送）

前端通过 listen 注册。所有 payload 与 Rust 模型严格对应。

session:status

{ sessionId: string; status: 'Connecting' | 'Connected' | 'AuthFailed' | 'Disconnected' | 'Timeout' | 'Error'; error: AppErrorInfo | null }

session:progress（连接阶段诊断）

{ sessionId: string; phase: 'LoadingCredentials' | 'ConnectingTcp' | 'SshHandshake' | 'Authenticating' | 'OpeningChannel' | 'RequestingPty' | 'StartingShell'; timestamp: number }

terminal:data

{ sessionId: string; data: string }   // UTF-8，可能包含 ANSI 控制序列

monitor:snapshot

{
  sessionId: string;
  timestamp: number;
  cpuUsage: number;
  memoryUsage: number;
  diskUsage: number;
  diskAvailableBytes: number;
  diskTotalBytes: number;
  network: { available: boolean; interfaces: Array<{ name: string; receiveBytesPerSecond: number | null; transmitBytesPerSecond: number | null }> };
}

task:status（监控长任务状态变更）

{ taskId: string; status: 'Pending' | 'Running' | 'Done' | 'Failed'; error: AppErrorInfo | null }

sftp:progress（约每 500ms）

{ taskId: string; sessionId: string; transferredBytes: number; totalBytes: number; speedBps: number }

sftp:task_status

{ taskId: string; sessionId: string; status: 'Pending' | 'Running' | 'Done' | 'Failed' | 'Cancelled'; error: AppErrorInfo | null }

AppErrorInfo

{ code: string; detail: string | null }
  • code：稳定英文错误码（如 SshConnectionError、AuthenticationError、SessionNotFound、SftpPathNotFound），由后端 AppError::code() 保证
  • detail：底层诊断文本，语言无关，供前端 formatAppError 本地化摘要后展示
  • 未知 code 前端回退到通用文案（error.Unknown），不因新增错误码而崩溃

3. 状态机

会话状态

Connecting ──成功──▶ Connected
     │
     ├─认证失败─▶ AuthFailed
     ├─超时────▶ Timeout
     ├─其他错误─▶ Error
     └─远端关闭─▶ Disconnected

长任务（TaskInfo / TransferTask）

Pending ─▶ Running ─▶ Done
               ├─▶ Failed（error 记录结构化原因）
               └─▶ Cancelled（主动取消，error 为 null）
  • 状态迁移由后端所属 module 校验并更新 registry（单一事实），非法/迟到迁移被拒绝且不发事件；终态为 Failed / Done（监控）或 Done / Failed / Cancelled（SFTP）
  • 前端在 invoke 返回前到达的任务状态事件会先缓存（latest-wins），任务元数据到达后补投，快速完成/快速失败不会卡在 Pending

4. 约定

  • 时间戳一律 Unix 毫秒（chrono::Utc::now().timestamp_millis()）
  • 枚举序列化：camelCase（serde rename_all = "camelCase"）
  • 事件名固定命名空间：terminal: / session: / monitor: / task: / sftp:
  • 命令失败统一返回 AppErrorInfo（不再回退到裸字符串），前端 toAppError 兜底规范化未知 rejection
  • 连接类错误同时通过 session:status 事件推送
  • 前端收到事件先校验存在性（如未知 taskId 忽略），不允许因过期事件崩溃

Clone this wiki locally