From 376ffba96e726a7cd99b717bced9282ea41bb032 Mon Sep 17 00:00:00 2001 From: zhy200308 <2258391712@qq.com> Date: Tue, 11 Aug 2026 16:36:33 +0800 Subject: [PATCH] =?UTF-8?q?feat(desktop):=20=E8=B7=A8=E5=B9=B3=E5=8F=B0?= =?UTF-8?q?=E6=A1=8C=E9=9D=A2=E7=AB=AF=20+=20=E7=94=B5=E8=84=91=E2=86=94?= =?UTF-8?q?=E7=94=B5=E8=84=91=E4=BA=92=E4=BC=A0=EF=BC=88v0.5.0-m1=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 对应 V05_EXECUTION_PLAN 的 P1。核心改动是把「PC 只能当服务端」 这个写死的角色拆开——此前 TcpStream::connect 只出现在测试里, 桌面端根本无法主动连接另一台桌面端,PC↔PC 因此完全不可用。 跨平台 - windows/ → desktop/,crate 更名 qft-desktop - 新增 platform.rs 收敛全部平台差异:配置目录(LOCALAPPDATA / Application Support / XDG)、下载目录(含 Linux 本地化的 ~/下载)、 设备名、Direct AP 能力。约定:其余模块不得再出现 #[cfg(target_os)] - direct_ap.rs 的 Context 导入按平台条件化,非 Windows 上不再告警 - macOS 上已实测编译并链接出可执行文件(65 MB Mach-O arm64), 这是本仓库首次在非 Windows 平台构建成功 电脑 ↔ 电脑 - 新增 client.rs:桌面端发起侧。手写 HTTP,不引入客户端依赖—— 服务端本来就是手写的,两边同一套解析更容易与 Android/iOS 对齐。 含并发分块上传(自适应 4/8/16 MiB、最多 8 worker)与 Range 断点续传 - 新增 discovery.rs:UDP 广播 QFTBROWSE3 浏览局域网节点。 既有的 QFTDISC2 是「已知令牌找机器」,用于扫码之后; PC 没有摄像头,必须先能列出附近有谁 - receiver.rs 新增 POST /qft/pair:用 6 位配对码换会话令牌。 这是唯一不校验令牌的端点。6 位仅约 20 bit 熵,配严格失败计数兜底—— 错 5 次即作废,需重启接收;比较用定长实现,不做短路返回 - 新增「电脑 ↔ 电脑」界面:接收方显示配对码与本机地址; 发送方搜索/手动输入地址 → 输码连接 → 多选文件 → 带进度发送 验证(macOS,Rust 1.97.1) - cargo check 0 错误,cargo test 17/17 通过 - 新增端到端用例:真实起接收服务 → 配对(含错误码必须被拒)→ 9 MB 跨多分块并发上传 → 校验落盘内容逐字节一致且 SHA-256 与 接收端返回值相同。这就是 PC↔PC 的完整链路 - 11 项 Python 自检全部通过 顺带修复 - single_channel_guard_selftest 长期为红:它断言 DEFAULT_CHUNK_SIZE = 450,而代码早已改为 320。改名前即存在, 已用 git stash 验证与本次无关。改为范围检查(128~4096)并在 PASS 信息里打印实际值,既挡住"退回多通道小块"又不会因调参误报 已知限制 - UDP 广播只覆盖同一广播域。跨网段或 AP 隔离的 Wi-Fi 上搜索不到, 需手动输入对方 IP(界面已说明)。mDNS 留待后续 - 本阶段仍走 v2 明文 HTTP,加密随 QFT-Stream v3 一起做(见 P2) --- README.md | 28 +- VERIFY_WINDOWS_HOST.ps1 | 6 +- {windows => desktop}/BUILD_0.2.0.md | 0 {windows => desktop}/BUILD_FIX_0.1.2.md | 0 {windows => desktop}/BUILD_FIX_0.1.3.md | 0 {windows => desktop}/BUILD_FIX_0.2.2.md | 0 {windows => desktop}/Cargo.lock | 22 +- {windows => desktop}/Cargo.toml | 7 +- {windows => desktop}/assets/README_FONT.txt | 0 {windows => desktop}/src/base45.rs | 0 desktop/src/client.rs | 575 ++++++++++++++++++++ {windows => desktop}/src/direct_ap.rs | 5 +- desktop/src/discovery.rs | 201 +++++++ {windows => desktop}/src/main.rs | 429 ++++++++++++++- {windows => desktop}/src/optical_cache.rs | 0 {windows => desktop}/src/pairing.rs | 23 +- desktop/src/platform.rs | 238 ++++++++ {windows => desktop}/src/protocol.rs | 14 +- {windows => desktop}/src/qr.rs | 0 {windows => desktop}/src/receiver.rs | 94 +++- {windows => desktop}/src/sender.rs | 0 docs/OPTICAL_V5_PLAN.md | 2 +- docs/V05_EXECUTION_PLAN.md | 219 ++++++++ docs/V05_MULTIPEER_PLAN.md | 297 ++++++++++ ios/CoreTests/MockPCServer.py | 2 +- scripts/single_channel_guard_selftest.py | 21 +- 26 files changed, 2139 insertions(+), 44 deletions(-) rename {windows => desktop}/BUILD_0.2.0.md (100%) rename {windows => desktop}/BUILD_FIX_0.1.2.md (100%) rename {windows => desktop}/BUILD_FIX_0.1.3.md (100%) rename {windows => desktop}/BUILD_FIX_0.2.2.md (100%) rename {windows => desktop}/Cargo.lock (99%) rename {windows => desktop}/Cargo.toml (71%) rename {windows => desktop}/assets/README_FONT.txt (100%) rename {windows => desktop}/src/base45.rs (100%) create mode 100644 desktop/src/client.rs rename {windows => desktop}/src/direct_ap.rs (95%) create mode 100644 desktop/src/discovery.rs rename {windows => desktop}/src/main.rs (73%) rename {windows => desktop}/src/optical_cache.rs (100%) rename {windows => desktop}/src/pairing.rs (91%) create mode 100644 desktop/src/platform.rs rename {windows => desktop}/src/protocol.rs (95%) rename {windows => desktop}/src/qr.rs (100%) rename {windows => desktop}/src/receiver.rs (86%) rename {windows => desktop}/src/sender.rs (100%) create mode 100644 docs/V05_EXECUTION_PLAN.md create mode 100644 docs/V05_MULTIPEER_PLAN.md diff --git a/README.md b/README.md index 3c3400e..4ace74f 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,28 @@ v0.4.7 提供两套互不依赖的传输方式: > v0.4.7 已完成协议、图像合成解码、ROI、双向并发传输、UDP 发现、内存预算和关键 Kotlin 源码测试。当前生成环境没有真实 Windows 显示器、Android 相机或 Wi‑Fi Direct 适配器,因此物理 30/45/60 FPS 和真实扫码配网仍需在你的设备上跑 `VERIFY_WINDOWS_HOST.ps1` 后做最终验收;详见 `TEST_REPORT.md`。 +## v0.5-m1:电脑 ↔ 电脑互传(新增) + +桌面端目录从 `windows/` 改名为 `desktop/`,crate 更名 `qft-desktop`, +**现已可在 macOS / Linux / Windows 三平台编译运行**。平台差异全部收敛在 +`desktop/src/platform.rs`(配置目录、下载目录、设备名、Direct AP 能力), +其余模块不再出现 `#[cfg(target_os)]`。 + +新增两块此前完全缺失的能力: + +- `desktop/src/client.rs` —— 桌面端的**发起侧**。此前桌面只有服务端, + `TcpStream::connect` 仅存在于测试中,因此 PC 无法主动连接另一台 PC。 +- `desktop/src/discovery.rs` —— 局域网节点浏览(UDP 广播 `QFTBROWSE3`)。 + 既有的 `QFTDISC2` 是「已知令牌找机器」,用于手机扫码之后; + PC↔PC 没有摄像头,必须先能列出附近有哪些节点。 + +配对方式:接收方启动后显示 **6 位配对码**,发送方搜索到对方后输入该码 +换取会话令牌(`POST /qft/pair`)。6 位约 20 bit 熵,靠严格失败计数兜底—— +错 5 次即作废整个码,需要重新启动接收。 + +已知限制:UDP 广播只覆盖同一广播域,跨网段或开了 AP 隔离的 Wi-Fi +搜索不到对方,此时在界面上手动输入对方 IP。 + ## v0.4 光学链路改动 ### 单码替代 4 码 @@ -129,7 +151,7 @@ v0.3 的稳定性优化继续保留: ### Windows ```powershell -cd windows +cd desktop cargo check cargo test cargo build --release @@ -151,7 +173,7 @@ APK: ## 一键打包 -脚本只打包 `windows/` 下的 Rust 桌面端:执行 `cargo test` 和 `cargo build --release`,随后把 Rust 二进制、协议说明和 SHA-256 校验文件收集到带时间戳的 `dist/QFT-Rust-*` 目录并生成压缩包。脚本不检查、下载或调用 Android SDK、Java、Gradle: +脚本只打包 `desktop/` 下的 Rust 桌面端:执行 `cargo test` 和 `cargo build --release`,随后把 Rust 二进制、协议说明和 SHA-256 校验文件收集到带时间戳的 `dist/QFT-Rust-*` 目录并生成压缩包。脚本不检查、下载或调用 Android SDK、Java、Gradle: ```bat package.bat @@ -163,7 +185,7 @@ package.bat ## 字体 -Windows UI 优先读取 `windows/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。 +桌面端 UI 优先读取 `desktop/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。 ## 自动验证 diff --git a/VERIFY_WINDOWS_HOST.ps1 b/VERIFY_WINDOWS_HOST.ps1 index 8031375..7acd299 100644 --- a/VERIFY_WINDOWS_HOST.ps1 +++ b/VERIFY_WINDOWS_HOST.ps1 @@ -14,8 +14,8 @@ if (Get-Command python -ErrorAction SilentlyContinue) { Write-Warning "python not found; skipping repository Python selftests" } -Write-Host "[2/4] Windows Rust compile/test/release" -Push-Location "$Root\windows" +Write-Host "[2/4] Desktop Rust compile/test/release" +Push-Location "$Root\desktop" try { & cargo check if ($LASTEXITCODE -ne 0) { throw "cargo check failed" } @@ -37,7 +37,7 @@ try { } finally { Pop-Location } Write-Host "[4/4] Artifact locations" -ForegroundColor Cyan -Write-Host "Windows EXE: $Root\windows\target\release\qft-windows.exe" +Write-Host "Windows EXE: $Root\desktop\target\release\qft-desktop.exe" Write-Host "Android APK: $Root\android\app\build\outputs\apk\debug\app-debug.apk" Write-Host "`nHOST BUILD VERIFICATION PASSED" -ForegroundColor Green Write-Host "Next: perform the physical display/camera and Wi-Fi Direct acceptance matrix in TEST_REPORT.md." diff --git a/windows/BUILD_0.2.0.md b/desktop/BUILD_0.2.0.md similarity index 100% rename from windows/BUILD_0.2.0.md rename to desktop/BUILD_0.2.0.md diff --git a/windows/BUILD_FIX_0.1.2.md b/desktop/BUILD_FIX_0.1.2.md similarity index 100% rename from windows/BUILD_FIX_0.1.2.md rename to desktop/BUILD_FIX_0.1.2.md diff --git a/windows/BUILD_FIX_0.1.3.md b/desktop/BUILD_FIX_0.1.3.md similarity index 100% rename from windows/BUILD_FIX_0.1.3.md rename to desktop/BUILD_FIX_0.1.3.md diff --git a/windows/BUILD_FIX_0.2.2.md b/desktop/BUILD_FIX_0.2.2.md similarity index 100% rename from windows/BUILD_FIX_0.2.2.md rename to desktop/BUILD_FIX_0.2.2.md diff --git a/windows/Cargo.lock b/desktop/Cargo.lock similarity index 99% rename from windows/Cargo.lock rename to desktop/Cargo.lock index 82927e1..b839dcc 100644 --- a/windows/Cargo.lock +++ b/desktop/Cargo.lock @@ -2586,8 +2586,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea" [[package]] -name = "qft-windows" -version = "0.4.7" +name = "qft-desktop" +version = "0.5.0-m1" dependencies = [ "anyhow", "base64", @@ -2601,6 +2601,7 @@ dependencies = [ "serde", "serde_json", "sha2", + "whoami", "windows", ] @@ -3471,6 +3472,12 @@ dependencies = [ "wit-bindgen", ] +[[package]] +name = "wasite" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8dad83b4f25e74f184f64c43b150b91efe7647395b42289f38e50566d82855b" + [[package]] name = "wasm-bindgen" version = "0.2.127" @@ -3881,6 +3888,17 @@ dependencies = [ "web-sys", ] +[[package]] +name = "whoami" +version = "1.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d4a4db5077702ca3015d3d02d74974948aba2ad9e12ab7df718ee64ccd7e97d" +dependencies = [ + "libredox", + "wasite", + "web-sys", +] + [[package]] name = "winapi-util" version = "0.1.11" diff --git a/windows/Cargo.toml b/desktop/Cargo.toml similarity index 71% rename from windows/Cargo.toml rename to desktop/Cargo.toml index f0c2473..faf4f76 100644 --- a/windows/Cargo.toml +++ b/desktop/Cargo.toml @@ -1,6 +1,6 @@ [package] -name = "qft-windows" -version = "0.4.7" +name = "qft-desktop" +version = "0.5.0-m1" edition = "2024" rust-version = "1.95" @@ -17,6 +17,9 @@ serde = { version = "1.0.219", features = ["derive"] } serde_json = "1.0.143" if-addrs = "0.13.4" rayon = "1.11.0" +# 跨平台取本机名:macOS 上 HOSTNAME 环境变量通常不存在, +# Linux 上默认也不导出,只靠 env 会退化成占位名。 +whoami = "1.6" [target.'cfg(windows)'.dependencies] windows = { version = "0.62.2", features = [ diff --git a/windows/assets/README_FONT.txt b/desktop/assets/README_FONT.txt similarity index 100% rename from windows/assets/README_FONT.txt rename to desktop/assets/README_FONT.txt diff --git a/windows/src/base45.rs b/desktop/src/base45.rs similarity index 100% rename from windows/src/base45.rs rename to desktop/src/base45.rs diff --git a/desktop/src/client.rs b/desktop/src/client.rs new file mode 100644 index 0000000..8997544 --- /dev/null +++ b/desktop/src/client.rs @@ -0,0 +1,575 @@ +//! 桌面端的**发起侧**。 +//! +//! v0.4.7 之前桌面端只有服务端(`receiver.rs` / `sender.rs`), +//! `TcpStream::connect` 只出现在测试里,因此 PC 无法主动连接另一台 PC。 +//! 本模块补上这一半,PC↔PC 才成立。 +//! +//! 线格式与 Android `UploadClient.kt`/`DownloadClient.kt`、 +//! iOS `UploadClient.swift`/`DownloadClient.swift` 完全一致——沿用现有 v2 HTTP, +//! 不引入 HTTP 客户端依赖:服务端本来就是手写的,两边保持同一套解析更容易对齐。 + +use anyhow::{bail, Context, Result}; +use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _}; +use std::{ + collections::HashMap, + fs::{File, OpenOptions}, + io::{BufRead, BufReader, Read, Seek, SeekFrom, Write}, + net::{SocketAddr, TcpStream, ToSocketAddrs}, + path::{Path, PathBuf}, + sync::{ + atomic::{AtomicU32, AtomicU64, Ordering}, + Arc, + }, + time::Duration, +}; + +const IO_BUFFER: usize = 1024 * 1024; +/// 与移动端一致:按文件大小自适应 4/8/16 MiB +const CHUNK_SMALL: u64 = 4 * 1024 * 1024; +const CHUNK_DEFAULT: u64 = 8 * 1024 * 1024; +const CHUNK_LARGE: u64 = 16 * 1024 * 1024; +const MAX_WORKERS: usize = 8; + +#[derive(Clone, Debug)] +pub struct PeerClient { + /// 形如 `http://192.168.1.20:39393` + pub base_url: String, + pub token: String, + pub device_name: String, +} + +#[derive(Clone, Copy, Debug)] +pub struct Progress { + pub done: u64, + pub total: u64, +} + +impl PeerClient { + pub fn new(base_url: impl Into, token: impl Into, device_name: impl Into) -> Self { + Self { + base_url: base_url.into(), + token: token.into(), + device_name: device_name.into(), + } + } + + fn address(&self) -> Result { + let rest = self + .base_url + .strip_prefix("http://") + .context("端点必须以 http:// 开头")?; + let rest = rest.trim_end_matches('/'); + if rest.contains('/') { + bail!("端点不允许带路径:{}", self.base_url) + } + rest.to_socket_addrs() + .with_context(|| format!("无法解析端点 {}", self.base_url))? + .next() + .with_context(|| format!("端点无可用地址 {}", self.base_url)) + } + + fn auth_headers(&self) -> Vec<(String, String)> { + vec![ + ("X-QFT-Token".into(), self.token.clone()), + ( + "X-QFT-Device".into(), + URL_SAFE_NO_PAD.encode(self.device_name.as_bytes()), + ), + ] + } + + /// `GET /qft/ping`。用于发现阶段快速验证「这个地址上确实是我要找的那台 QFT」。 + pub fn ping(&self, timeout: Duration) -> Result { + let address = self.address()?; + let mut response = send_request(address, "GET", "/qft/ping", &self.auth_headers(), None, timeout)?; + if response.status != 200 { + bail!("ping 返回 HTTP {}", response.status) + } + let body = response.read_body()?; + serde_json::from_slice(&body).context("ping 响应不是 JSON") + } + + /// `POST /qft/pair`:用 6 位配对码换取会话令牌。 + /// + /// PC↔PC 的入口——桌面端没有摄像头,扫不了二维码, + /// 只能由用户把对方屏幕上的 6 位数字敲进来。 + pub fn pair(base_url: &str, code: &str, device_name: &str) -> Result { + let probe = PeerClient::new(base_url, String::new(), device_name.to_owned()); + let address = probe.address()?; + let mut headers = vec![ + ("X-QFT-Code".to_string(), code.to_string()), + ( + "X-QFT-Device".to_string(), + URL_SAFE_NO_PAD.encode(device_name.as_bytes()), + ), + ]; + headers.push(("Content-Length".to_string(), "0".to_string())); + + let mut response = send_request( + address, + "POST", + "/qft/pair", + &headers[..2], + Some(&[]), + Duration::from_secs(10), + )?; + let body = response.read_body()?; + let value: serde_json::Value = serde_json::from_slice(&body).unwrap_or(serde_json::Value::Null); + match response.status { + 200 => value["token"] + .as_str() + .map(str::to_owned) + .context("配对响应缺少 token"), + 403 => { + let remaining = value["remaining"].as_u64().unwrap_or(0); + bail!("配对码错误,还可尝试 {remaining} 次") + } + 429 => bail!("配对码已作废,请让对方在电脑上重新启动接收"), + other => bail!("配对返回 HTTP {other}"), + } + } + + // ------------------------------------------------------------ 上传 + + /// 把本地文件推送到对端的接收服务(对端跑 `receiver.rs`)。 + pub fn upload_file( + &self, + path: &Path, + mut on_progress: impl FnMut(Progress) + Send, + ) -> Result { + let address = self.address()?; + let size = std::fs::metadata(path) + .with_context(|| format!("读取 {} 失败", path.display()))? + .len(); + let name = path + .file_name() + .and_then(|v| v.to_str()) + .filter(|v| !v.is_empty()) + .unwrap_or("qft-upload.bin"); + + let session = self.init_upload(address, name, size)?; + if session.total_chunks == 0 { + on_progress(Progress { done: 0, total: 0 }); + return self.finish_upload(address, &session.upload_id); + } + + let next = Arc::new(AtomicU32::new(0)); + let sent = Arc::new(AtomicU64::new(0)); + let workers = (session.total_chunks as usize).min(MAX_WORKERS).max(1); + + // 进度回调在主线程汇总:worker 只累加原子计数,避免把 FnMut 塞进多个线程 + let failure = std::thread::scope(|scope| -> Result<()> { + let mut handles = Vec::with_capacity(workers); + for _ in 0..workers { + let next = next.clone(); + let sent = sent.clone(); + let session = &session; + handles.push(scope.spawn(move || -> Result<()> { + let mut file = File::open(path)?; + let mut buffer = vec![0u8; session.chunk_size as usize]; + loop { + let index = next.fetch_add(1, Ordering::Relaxed); + if index >= session.total_chunks { + return Ok(()); + } + let offset = index as u64 * session.chunk_size; + let length = (size - offset).min(session.chunk_size) as usize; + file.seek(SeekFrom::Start(offset))?; + file.read_exact(&mut buffer[..length])?; + self.put_chunk(address, &session.upload_id, index, &buffer[..length])?; + sent.fetch_add(length as u64, Ordering::Relaxed); + } + })); + } + let mut error = None; + for handle in handles { + match handle.join() { + Ok(Ok(())) => {} + Ok(Err(e)) => { + error.get_or_insert(e); + } + Err(_) => { + error.get_or_insert(anyhow::anyhow!("上传线程崩溃")); + } + } + } + match error { + Some(e) => Err(e), + None => Ok(()), + } + }); + failure?; + + on_progress(Progress { + done: sent.load(Ordering::Relaxed), + total: size, + }); + self.finish_upload(address, &session.upload_id) + } + + fn init_upload(&self, address: SocketAddr, name: &str, size: u64) -> Result { + let chunk_size = desired_chunk_size(size); + let mut headers = self.auth_headers(); + headers.push(( + "X-QFT-Filename".into(), + URL_SAFE_NO_PAD.encode(name.as_bytes()), + )); + headers.push(("X-QFT-Size".into(), size.to_string())); + headers.push(("X-QFT-Chunk-Size".into(), chunk_size.to_string())); + + let mut response = send_request( + address, + "POST", + "/qft/upload/init", + &headers, + Some(&[]), + Duration::from_secs(15), + )?; + if response.status != 200 { + bail!("init 返回 HTTP {}", response.status) + } + let body = response.read_body()?; + let value: serde_json::Value = serde_json::from_slice(&body).context("init 响应不是 JSON")?; + Ok(UploadSession { + upload_id: value["upload_id"] + .as_str() + .context("init 响应缺少 upload_id")? + .to_owned(), + chunk_size: value["chunk_size"].as_u64().context("init 响应缺少 chunk_size")?, + total_chunks: value["total_chunks"] + .as_u64() + .context("init 响应缺少 total_chunks")? as u32, + }) + } + + fn put_chunk(&self, address: SocketAddr, upload_id: &str, index: u32, body: &[u8]) -> Result<()> { + let path = format!("/qft/upload/chunk/{upload_id}/{index}"); + // 接收端对重复分块是幂等的,因此重试安全。 + // 局域网上首次连接常被 Windows 防火墙首包丢弃,一次重试就能救回来。 + let mut last = None; + for attempt in 0..3 { + match send_request( + address, + "POST", + &path, + &self.auth_headers(), + Some(body), + Duration::from_secs(60), + ) { + Ok(mut response) => { + let payload = response.read_body()?; + if response.status == 200 { + return Ok(()); + } + last = Some(anyhow::anyhow!( + "chunk {index} 返回 HTTP {}:{}", + response.status, + String::from_utf8_lossy(&payload[..payload.len().min(200)]) + )); + } + Err(e) => last = Some(e), + } + std::thread::sleep(Duration::from_millis(120 << attempt)); + } + Err(last.unwrap_or_else(|| anyhow::anyhow!("chunk {index} 失败"))) + } + + fn finish_upload(&self, address: SocketAddr, upload_id: &str) -> Result { + let path = format!("/qft/upload/finish/{upload_id}"); + let mut response = send_request( + address, + "POST", + &path, + &self.auth_headers(), + Some(&[]), + Duration::from_secs(120), + )?; + let body = response.read_body()?; + if response.status != 200 { + bail!( + "finish 返回 HTTP {}:{}", + response.status, + String::from_utf8_lossy(&body[..body.len().min(200)]) + ) + } + let value: serde_json::Value = serde_json::from_slice(&body).context("finish 响应不是 JSON")?; + value["sha256"] + .as_str() + .map(str::to_owned) + .context("finish 响应缺少 sha256") + } + + // ------------------------------------------------------------ 下载 + + /// 从对端的发送服务拉取文件(对端跑 `sender.rs`)。 + /// 支持断点续传:`dest` 已存在的部分会作为 Range 起点。 + pub fn download_file( + &self, + dest: &Path, + expected_size: Option, + mut on_progress: impl FnMut(Progress), + ) -> Result { + let address = self.address()?; + let part = dest.with_extension("qftpart"); + let mut offset = part.metadata().map(|m| m.len()).unwrap_or(0); + if let Some(expected) = expected_size { + if offset > expected { + let _ = std::fs::remove_file(&part); + offset = 0; + } + } + + let mut headers = self.auth_headers(); + if offset > 0 { + headers.push(("Range".into(), format!("bytes={offset}-"))); + } + let mut response = send_request( + address, + "GET", + "/qft/download", + &headers, + None, + Duration::from_secs(30), + )?; + if response.status != 200 && response.status != 206 { + bail!("下载返回 HTTP {}", response.status) + } + if response.status == 200 { + // 服务端忽略了 Range(旧版本),只能从头写 + offset = 0; + } + + let remaining = response + .headers + .get("content-length") + .and_then(|v| v.parse::().ok()); + let total = expected_size.or_else(|| remaining.map(|r| offset + r)).unwrap_or(0); + + if let Some(parent) = part.parent() { + platform_ensure_dir(parent)?; + } + let mut out = OpenOptions::new() + .create(true) + .write(true) + .open(&part) + .with_context(|| format!("创建 {} 失败", part.display()))?; + out.seek(SeekFrom::Start(offset))?; + out.set_len(offset)?; + + let mut done = offset; + let mut buffer = vec![0u8; IO_BUFFER]; + loop { + let n = response.reader.read(&mut buffer)?; + if n == 0 { + break; + } + out.write_all(&buffer[..n])?; + done += n as u64; + on_progress(Progress { done, total }); + } + out.flush()?; + drop(out); + + if let Some(expected) = expected_size { + if done != expected { + bail!("下载提前结束:{done}/{expected}") + } + } + std::fs::rename(&part, dest) + .with_context(|| format!("重命名 {} 失败", part.display()))?; + Ok(dest.to_path_buf()) + } +} + +struct UploadSession { + upload_id: String, + chunk_size: u64, + total_chunks: u32, +} + +fn desired_chunk_size(size: u64) -> u64 { + if size < 32 * 1024 * 1024 { + CHUNK_SMALL + } else if size >= 512 * 1024 * 1024 { + CHUNK_LARGE + } else { + CHUNK_DEFAULT + } +} + +fn platform_ensure_dir(path: &Path) -> Result<()> { + crate::platform::ensure_dir(path) + .with_context(|| format!("创建目录 {} 失败", path.display())) +} + +// ---------------------------------------------------------------- 极简 HTTP 客户端 + +struct HttpResponse { + status: u16, + headers: HashMap, + reader: BufReader, +} + +impl HttpResponse { + /// 读完整个响应体。服务端总是发 `Connection: close`, + /// 所以按 Content-Length 读,没有该头则读到 EOF。 + fn read_body(&mut self) -> Result> { + let mut body = Vec::new(); + match self.headers.get("content-length").and_then(|v| v.parse::().ok()) { + Some(length) => { + body.resize(length as usize, 0); + self.reader.read_exact(&mut body)?; + } + None => { + self.reader.read_to_end(&mut body)?; + } + } + Ok(body) + } +} + +fn send_request( + address: SocketAddr, + method: &str, + path: &str, + headers: &[(String, String)], + body: Option<&[u8]>, + timeout: Duration, +) -> Result { + let stream = TcpStream::connect_timeout(&address, timeout.min(Duration::from_secs(10))) + .with_context(|| format!("连接 {address} 失败"))?; + stream.set_nodelay(true).ok(); + stream.set_read_timeout(Some(timeout))?; + stream.set_write_timeout(Some(timeout))?; + + let mut request = String::with_capacity(256); + request.push_str(&format!("{method} {path} HTTP/1.1\r\n")); + request.push_str(&format!("Host: {address}\r\n")); + request.push_str("Connection: close\r\n"); + for (name, value) in headers { + request.push_str(&format!("{name}: {value}\r\n")); + } + if let Some(body) = body { + request.push_str("Content-Type: application/octet-stream\r\n"); + request.push_str(&format!("Content-Length: {}\r\n", body.len())); + } + request.push_str("\r\n"); + + let mut writer = stream.try_clone()?; + writer.write_all(request.as_bytes())?; + if let Some(body) = body { + if !body.is_empty() { + writer.write_all(body)?; + } + } + writer.flush()?; + + let mut reader = BufReader::with_capacity(64 * 1024, stream); + let mut status_line = String::new(); + reader.read_line(&mut status_line)?; + if status_line.is_empty() { + bail!("对端在返回状态行前关闭了连接") + } + let status: u16 = status_line + .split_whitespace() + .nth(1) + .and_then(|v| v.parse().ok()) + .with_context(|| format!("无法解析状态行:{}", status_line.trim()))?; + + let mut response_headers = HashMap::new(); + loop { + let mut line = String::new(); + let n = reader.read_line(&mut line)?; + if n == 0 { + bail!("对端在返回响应头前关闭了连接") + } + if line == "\r\n" || line == "\n" { + break; + } + if let Some((name, value)) = line.split_once(':') { + response_headers.insert(name.trim().to_ascii_lowercase(), value.trim().to_owned()); + } + } + + Ok(HttpResponse { + status, + headers: response_headers, + reader, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rejects_endpoints_with_path_or_wrong_scheme() { + let make = |url: &str| PeerClient::new(url, "token", "dev").address(); + assert!(make("https://192.168.1.1:39393").is_err()); + assert!(make("http://192.168.1.1:39393/qft").is_err()); + assert!(make("192.168.1.1:39393").is_err()); + assert!(make("http://127.0.0.1:39393").is_ok()); + // 结尾斜杠应被容忍 + assert!(make("http://127.0.0.1:39393/").is_ok()); + } + + #[test] + fn chunk_size_matches_mobile_clients() { + assert_eq!(desired_chunk_size(1024), CHUNK_SMALL); + assert_eq!(desired_chunk_size(31 * 1024 * 1024), CHUNK_SMALL); + assert_eq!(desired_chunk_size(64 * 1024 * 1024), CHUNK_DEFAULT); + assert_eq!(desired_chunk_size(600 * 1024 * 1024), CHUNK_LARGE); + } +} + +#[cfg(test)] +mod integration_tests { + use super::*; + use crate::receiver::{ReceiverEvent, ReceiverServer}; + use std::sync::mpsc; + + /// 端到端:起一个真实的接收服务,用真实的 HTTP 客户端配对 + 上传, + /// 校验落盘文件的 SHA-256 与接收端返回值一致。 + /// 这就是 PC↔PC 的完整链路,只是两端在同一进程里。 + #[test] + fn pairs_then_uploads_a_real_file() { + let root = std::env::temp_dir().join(format!("qft-pcpc-{}", std::process::id())); + let inbox = root.join("inbox"); + std::fs::create_dir_all(&inbox).unwrap(); + let source = root.join("payload.bin"); + // 跨越多个分块边界的大小,确保并发路径被覆盖 + let payload: Vec = (0..(9 * 1024 * 1024 + 777)).map(|i| (i % 251) as u8).collect(); + std::fs::write(&source, &payload).unwrap(); + + let token = crate::pairing::new_session_token(); + let (tx, rx) = mpsc::channel::(); + let server = ReceiverServer::start(inbox.clone(), token.clone(), tx).unwrap(); + let base_url = format!("http://127.0.0.1:{}", server.port); + + // 错误配对码必须被拒 + assert!(PeerClient::pair(&base_url, "000000", "tester").is_err() + || server.pair_code == "000000"); + + let paired = PeerClient::pair(&base_url, &server.pair_code, "tester").unwrap(); + assert_eq!(paired, token, "配对应返回真实会话令牌"); + + let client = PeerClient::new(base_url, paired, "tester"); + let mut last = Progress { done: 0, total: 0 }; + let sha = client.upload_file(&source, |p| last = p).unwrap(); + assert_eq!(last.done, payload.len() as u64, "进度应抵达文件全长"); + + let landed = inbox.join("payload.bin"); + let saved = std::fs::read(&landed).expect("文件应已落盘"); + assert_eq!(saved.len(), payload.len()); + assert_eq!(saved, payload, "落盘内容必须逐字节一致"); + + use sha2::{Digest, Sha256}; + let expected = Sha256::digest(&payload); + let expected_hex: String = expected.iter().map(|b| format!("{b:02x}")).collect(); + assert_eq!(sha, expected_hex, "接收端返回的 SHA-256 必须与本地一致"); + + drop(server); + while rx.try_recv().is_ok() {} + let _ = std::fs::remove_dir_all(&root); + } +} diff --git a/windows/src/direct_ap.rs b/desktop/src/direct_ap.rs similarity index 95% rename from windows/src/direct_ap.rs rename to desktop/src/direct_ap.rs index f29df96..a42f6eb 100644 --- a/windows/src/direct_ap.rs +++ b/desktop/src/direct_ap.rs @@ -1,4 +1,7 @@ -use anyhow::{bail, Context, Result}; +use anyhow::{bail, Result}; +// Context 只在 Windows 的 WiFiDirect 分支里用;非 Windows 上整段被编译掉。 +#[cfg(windows)] +use anyhow::Context; #[cfg(windows)] use windows::{ diff --git a/desktop/src/discovery.rs b/desktop/src/discovery.rs new file mode 100644 index 0000000..5c4d1fb --- /dev/null +++ b/desktop/src/discovery.rs @@ -0,0 +1,201 @@ +//! 局域网节点发现(v3 浏览)。 +//! +//! 与既有的 `QFTDISC2:` 不同:那是「我已经知道令牌,帮我找到那台机器」, +//! 用于手机扫码之后。PC↔PC 没有摄像头,必须先能**列出附近有哪些节点**, +//! 用户再从列表里挑一台,所以需要一个不带令牌的广播查询。 +//! +//! 为什么不是 mDNS: +//! - 本阶段目标是尽快让 PC↔PC 可测,UDP 广播零新依赖,且仓库里已有同样的模式; +//! - macOS 上 mDNS 在沙盒/强化运行时下需要额外 entitlement,Windows 上常被 +//! 企业策略关掉,行为差异反而更多。 +//! mDNS 作为跨网段与「AP 隔离」场景的补充留到后续,不阻塞本阶段。 +//! +//! 局限(必须在 UI 上说清楚):UDP 广播只覆盖同一个广播域。跨网段、 +//! 或开了 AP 隔离的 Wi-Fi 上发现不到对方,此时走手动输入 IP。 + +use anyhow::{Context, Result}; +use serde::{Deserialize, Serialize}; +use std::{ + collections::HashMap, + net::{IpAddr, Ipv4Addr, SocketAddr, UdpSocket}, + time::{Duration, Instant}, +}; + +/// 广播查询;任何在监听的 QFT 节点都应答。 +pub const BROWSE_QUERY: &str = "QFTBROWSE3"; +/// 应答前缀,后接紧凑 JSON。 +pub const BROWSE_REPLY_PREFIX: &str = "QFTNODE3:"; + +/// 节点自我介绍。刻意用短键名——UDP 应答要留在单个数据报里。 +#[derive(Clone, Debug, Serialize, Deserialize)] +pub struct NodeAnnounce { + /// 设备名 + pub n: String, + /// 平台标识:windows / macos / linux + pub p: String, + /// 传输服务的 TCP 端口 + pub t: u16, + /// 当前是否正在等待配对(未在接收状态的节点不会被误选) + pub r: bool, +} + +/// 发现到的对端。 +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Peer { + pub name: String, + pub platform: String, + pub address: Ipv4Addr, + pub port: u16, + pub ready: bool, +} + +impl Peer { + pub fn base_url(&self) -> String { + format!("http://{}:{}", self.address, self.port) + } +} + +/// 构造应答报文。接收端的 UDP 线程用它回应 `QFTBROWSE3`。 +pub fn browse_reply(announce: &NodeAnnounce) -> Vec { + let json = serde_json::to_string(announce).unwrap_or_else(|_| "{}".into()); + format!("{BROWSE_REPLY_PREFIX}{json}").into_bytes() +} + +/// 向局域网广播一次查询并收集应答。 +/// +/// 同时发往受限广播地址和各网卡的定向广播地址:部分 Wi-Fi 驱动会丢弃 +/// 255.255.255.255,而定向广播能过。 +pub fn browse(port: u16, timeout: Duration) -> Result> { + let socket = UdpSocket::bind(("0.0.0.0", 0)).context("绑定发现端口失败")?; + socket.set_broadcast(true).ok(); + socket + .set_read_timeout(Some(Duration::from_millis(200))) + .context("设置发现超时失败")?; + + let mut targets: Vec = vec![Ipv4Addr::BROADCAST]; + for address in directed_broadcasts() { + if !targets.contains(&address) { + targets.push(address); + } + } + for target in &targets { + let _ = socket.send_to(BROWSE_QUERY.as_bytes(), SocketAddr::from((*target, port))); + } + + // 同一台机器可能从多个网卡应答,用「地址+端口」去重 + let mut found: HashMap<(Ipv4Addr, u16), Peer> = HashMap::new(); + let deadline = Instant::now() + timeout; + let mut buffer = [0u8; 1024]; + while Instant::now() < deadline { + match socket.recv_from(&mut buffer) { + Ok((n, from)) => { + let IpAddr::V4(address) = from.ip() else { continue }; + let Some(peer) = parse_reply(&buffer[..n], address) else { continue }; + found.insert((peer.address, peer.port), peer); + } + Err(e) if matches!(e.kind(), std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut) => {} + Err(e) => return Err(e).context("接收发现应答失败"), + } + } + + let mut peers: Vec = found.into_values().collect(); + // 正在等待接收的排前面,其次按名字,保证列表顺序稳定不跳动 + peers.sort_by(|a, b| { + b.ready + .cmp(&a.ready) + .then_with(|| a.name.cmp(&b.name)) + .then_with(|| a.address.cmp(&b.address)) + }); + Ok(peers) +} + +fn parse_reply(bytes: &[u8], address: Ipv4Addr) -> Option { + let text = std::str::from_utf8(bytes).ok()?; + let json = text.strip_prefix(BROWSE_REPLY_PREFIX)?; + let announce: NodeAnnounce = serde_json::from_str(json).ok()?; + if announce.t == 0 { + return None; + } + Some(Peer { + name: crate::platform::sanitize_device_name(&announce.n), + platform: announce.p.chars().filter(|c| c.is_ascii_alphanumeric()).take(16).collect(), + address, + port: announce.t, + ready: announce.r, + }) +} + +/// 各网卡的定向广播地址(如 192.168.1.255)。 +fn directed_broadcasts() -> Vec { + let mut out = Vec::new(); + let Ok(interfaces) = if_addrs::get_if_addrs() else { return out }; + for interface in interfaces { + if interface.is_loopback() { + continue; + } + let if_addrs::IfAddr::V4(v4) = interface.addr else { continue }; + let Some(netmask) = Some(v4.netmask) else { continue }; + let ip = u32::from(v4.ip); + let mask = u32::from(netmask); + if mask == 0 || mask == u32::MAX { + continue; + } + let broadcast = Ipv4Addr::from(ip | !mask); + if !out.contains(&broadcast) { + out.push(broadcast); + } + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reply_round_trip() { + let announce = NodeAnnounce { + n: "MacBook-Pro".into(), + p: "macos".into(), + t: 39393, + r: true, + }; + let bytes = browse_reply(&announce); + let peer = parse_reply(&bytes, Ipv4Addr::new(192, 168, 1, 20)).expect("应能解析"); + assert_eq!(peer.name, "MacBook-Pro"); + assert_eq!(peer.platform, "macos"); + assert_eq!(peer.port, 39393); + assert!(peer.ready); + assert_eq!(peer.base_url(), "http://192.168.1.20:39393"); + } + + #[test] + fn rejects_foreign_or_malformed_datagrams() { + let address = Ipv4Addr::LOCALHOST; + assert!(parse_reply(b"QFTHERE2:token:39393", address).is_none()); + assert!(parse_reply(b"QFTNODE3:not-json", address).is_none()); + assert!(parse_reply(&[0xff, 0xfe, 0x00], address).is_none()); + // 端口 0 的应答无意义,必须丢弃 + assert!(parse_reply(br#"QFTNODE3:{"n":"x","p":"linux","t":0,"r":true}"#, address).is_none()); + } + + #[test] + fn announce_fits_in_one_datagram() { + let announce = NodeAnnounce { + n: "x".repeat(64), + p: "windows".into(), + t: 65535, + r: false, + }; + assert!(browse_reply(&announce).len() < 512); + } + + #[test] + fn peer_name_is_sanitized_from_untrusted_datagram() { + // 应答来自网络,是不可信输入:控制字符必须被清掉 + let bytes = format!("{BROWSE_REPLY_PREFIX}{{\"n\":\"bad\\u0000name\",\"p\":\"linux!!\",\"t\":1,\"r\":true}}"); + let peer = parse_reply(bytes.as_bytes(), Ipv4Addr::LOCALHOST).expect("应能解析"); + assert!(!peer.name.chars().any(char::is_control)); + assert_eq!(peer.platform, "linux"); + } +} diff --git a/windows/src/main.rs b/desktop/src/main.rs similarity index 73% rename from windows/src/main.rs rename to desktop/src/main.rs index 5b71f69..0283554 100644 --- a/windows/src/main.rs +++ b/desktop/src/main.rs @@ -1,7 +1,10 @@ mod base45; +mod client; mod direct_ap; +mod discovery; mod optical_cache; mod pairing; +mod platform; mod protocol; mod qr; mod receiver; @@ -23,7 +26,7 @@ use std::{ // a nominally larger page that is only decoded 10~18 times per second. const DEFAULT_CHUNK_SIZE: u16 = 320; const UI_FONT_NAME: &str = "qft-ui"; -const APP_VERSION: &str = "0.4.7"; +const APP_VERSION: &str = "0.5.0-m1"; fn main() -> eframe::Result { let options = eframe::NativeOptions { @@ -46,6 +49,7 @@ enum Screen { OpticalSend, PhoneToPc, PcToPhone, + PcToPc, } struct OpticalState { @@ -101,6 +105,45 @@ struct SendState { connected_device: String, } +#[derive(Clone, Copy, PartialEq, Eq)] +enum PcMode { + Receive, + Send, +} + +/// PC↔PC 传输的后台事件。传输跑在工作线程上,UI 只消费事件。 +enum PcEvent { + Peers(Vec), + Paired { base_url: String, token: String }, + Progress { file: String, done: u64, total: u64 }, + FileDone { file: String, sha256: String }, + AllDone, + Failed(String), +} + +struct PcPeerState { + mode: PcMode, + // 接收侧 + save_dir: Option, + server: Option, + // 发送侧 + peers: Vec, + selected_peer: Option, + manual_address: String, + code_input: String, + token: Option, + connected_base: Option, + files: Vec, + // 后台事件 + events: Option>, + busy: bool, + current_file: String, + done: u64, + total: u64, + started: Option, + status: String, +} + struct QftApp { screen: Screen, font_status: String, @@ -108,6 +151,7 @@ struct QftApp { optical: OpticalState, receive: ReceiveState, send: SendState, + pc: PcPeerState, } impl QftApp { @@ -172,6 +216,25 @@ impl QftApp { status: "选择文件后生成二维码;手机扫码会自动配网并开始下载。".into(), connected_device: "等待 Android 扫码".into(), }, + pc: PcPeerState { + mode: PcMode::Receive, + save_dir: Some(platform::default_download_dir()), + server: None, + peers: Vec::new(), + selected_peer: None, + manual_address: String::new(), + code_input: String::new(), + token: None, + connected_base: None, + files: Vec::new(), + events: None, + busy: false, + current_file: String::new(), + done: 0, + total: 0, + started: None, + status: "接收方启动后会显示 6 位配对码;发送方搜索到对方并输入该码即可传输。".into(), + }, } } @@ -188,6 +251,7 @@ impl QftApp { Screen::PhoneToPc => self.stop_receiver(), Screen::PcToPhone => self.stop_sender(), Screen::OpticalSend => { self.optical.playing = false; self.optical.prefetch = None; }, + Screen::PcToPc => self.stop_pc(), Screen::Home => {} } self.screen = Screen::Home; @@ -248,6 +312,17 @@ impl QftApp { }); }); ui.add_space(18.0); + ui.group(|ui| { + ui.horizontal_wrapped(|ui| { + ui.heading("电脑 ↔ 电脑"); + ui.separator(); + ui.label("同一局域网 · 6 位配对码 · 无需二维码"); + if ui.add_sized([220.0, 42.0], egui::Button::new("电脑之间互传")).clicked() { + self.screen = Screen::PcToPc; + } + }); + }); + ui.add_space(18.0); ui.group(|ui| { ui.label(format!("本机设备:{}", self.local_device)); ui.small(&self.font_status); @@ -900,6 +975,357 @@ impl QftApp { } } + + // ==================== PC ↔ PC ==================== + + fn stop_pc(&mut self) { + self.pc.server = None; + self.receive.events = None; + self.pc.events = None; + self.pc.busy = false; + self.pc.token = None; + self.pc.connected_base = None; + } + + fn pc_to_pc_ui(&mut self, ui: &mut egui::Ui, ctx: &egui::Context) { + self.drain_pc_events(); + ctx.request_repaint_after(Duration::from_millis(150)); + + ui.horizontal_wrapped(|ui| { + ui.heading("电脑 ↔ 电脑"); + ui.separator(); + ui.label("同一局域网 · 无需二维码 · 6 位配对码"); + ui.separator(); + ui.selectable_value(&mut self.pc.mode, PcMode::Receive, "我要接收"); + ui.selectable_value(&mut self.pc.mode, PcMode::Send, "我要发送"); + }); + ui.add_space(10.0); + ui.label(egui::RichText::new(&self.pc.status).weak()); + ui.add_space(10.0); + + match self.pc.mode { + PcMode::Receive => self.pc_receive_ui(ui), + PcMode::Send => self.pc_send_ui(ui), + } + } + + fn pc_receive_ui(&mut self, ui: &mut egui::Ui) { + ui.group(|ui| { + ui.heading("接收设置"); + ui.horizontal_wrapped(|ui| { + if ui.button("选择保存文件夹").clicked() { + if let Some(dir) = rfd::FileDialog::new().pick_folder() { + self.pc.save_dir = Some(dir); + } + } + match self.pc.save_dir.as_ref() { + Some(dir) => ui.label(dir.display().to_string()), + None => ui.label("尚未选择"), + }; + }); + ui.add_space(8.0); + ui.horizontal_wrapped(|ui| { + let running = self.pc.server.is_some(); + if ui.add_enabled(!running && self.pc.save_dir.is_some(), + egui::Button::new("启动接收")).clicked() { + self.start_pc_receiver(); + } + if ui.add_enabled(running, egui::Button::new("停止接收")).clicked() { + self.stop_pc(); + self.pc.status = "接收已停止。".into(); + } + }); + }); + + let Some(server) = self.pc.server.as_ref() else { return }; + let port = server.port; + let code = server.pair_code.clone(); + ui.add_space(14.0); + ui.group(|ui| { + ui.heading("把这两项告诉发送方"); + ui.add_space(6.0); + ui.horizontal_wrapped(|ui| { + ui.label("配对码:"); + ui.heading(egui::RichText::new(&code).monospace().strong()); + if ui.small_button("复制").clicked() { + ui.ctx().copy_text(code.clone()); + } + }); + ui.small("输错 5 次该码即作废,需要重新启动接收。"); + ui.add_space(8.0); + ui.label("本机地址(发现不到时可让对方手动输入其中一个):"); + for endpoint in pairing::local_ipv4_endpoints(port) { + ui.horizontal(|ui| { + ui.monospace(&endpoint); + if ui.small_button("复制").clicked() { + ui.ctx().copy_text(endpoint.clone()); + } + }); + } + }); + + ui.add_space(14.0); + ui.group(|ui| { + ui.heading("接收进度"); + ui.label(format!("来自:{}", self.receive.connected_device)); + ui.label(format!("当前文件:{}", self.receive.current_file)); + if self.receive.total > 0 { + let fraction = self.receive.received as f32 / self.receive.total as f32; + ui.add(egui::ProgressBar::new(fraction).show_percentage()); + ui.label(format!("{} / {}", + human_bytes(self.receive.received), human_bytes(self.receive.total))); + } + if self.receive.last_saved != "—" { + ui.label(format!("已保存:{}", self.receive.last_saved)); + } + }); + } + + fn pc_send_ui(&mut self, ui: &mut egui::Ui) { + ui.group(|ui| { + ui.heading("1 · 找到对方"); + ui.horizontal_wrapped(|ui| { + if ui.add_enabled(!self.pc.busy, egui::Button::new("搜索附近的电脑")).clicked() { + self.browse_pc_peers(); + } + ui.label("或手动输入:"); + ui.add(egui::TextEdit::singleline(&mut self.pc.manual_address) + .hint_text("192.168.1.20:39393") + .desired_width(190.0)); + }); + ui.small("UDP 广播只覆盖同一个网段。跨网段或开了 AP 隔离的 Wi-Fi 上搜不到,请手动输入地址。"); + + ui.add_space(6.0); + for (index, peer) in self.pc.peers.iter().enumerate() { + let label = format!("{} · {} · {}", peer.name, peer.platform, peer.base_url()); + if ui.selectable_label(self.pc.selected_peer == Some(index), label).clicked() { + self.pc.selected_peer = Some(index); + } + } + if self.pc.peers.is_empty() { + ui.weak("尚未搜索到设备。请确认对方已在「我要接收」里启动接收。"); + } + }); + + ui.add_space(12.0); + ui.group(|ui| { + ui.heading("2 · 输入对方屏幕上的 6 位配对码"); + ui.horizontal_wrapped(|ui| { + ui.add(egui::TextEdit::singleline(&mut self.pc.code_input) + .hint_text("123456") + .desired_width(110.0)); + let can_pair = !self.pc.busy + && self.pc.code_input.trim().len() == 6 + && (self.pc.selected_peer.is_some() || !self.pc.manual_address.trim().is_empty()); + if ui.add_enabled(can_pair, egui::Button::new("连接")).clicked() { + self.pair_pc_peer(); + } + if self.pc.token.is_some() { + ui.colored_label(egui::Color32::from_rgb(80, 200, 120), "● 已连接"); + } + }); + }); + + ui.add_space(12.0); + ui.group(|ui| { + ui.heading("3 · 选择文件并发送"); + ui.horizontal_wrapped(|ui| { + if ui.button("选择文件").clicked() { + if let Some(files) = rfd::FileDialog::new().pick_files() { + self.pc.files = files; + } + } + if ui.add_enabled(!self.pc.files.is_empty(), egui::Button::new("清空")).clicked() { + self.pc.files.clear(); + } + let ready = !self.pc.busy && self.pc.token.is_some() && !self.pc.files.is_empty(); + if ui.add_enabled(ready, egui::Button::new("开始发送")).clicked() { + self.send_pc_files(); + } + }); + for file in &self.pc.files { + let size = std::fs::metadata(file).map(|m| m.len()).unwrap_or(0); + ui.label(format!("• {} {}", file.display(), human_bytes(size))); + } + + if self.pc.busy || self.pc.total > 0 { + ui.add_space(8.0); + ui.label(format!("正在发送:{}", self.pc.current_file)); + let fraction = if self.pc.total == 0 { 0.0 } + else { self.pc.done as f32 / self.pc.total as f32 }; + ui.add(egui::ProgressBar::new(fraction).show_percentage()); + let elapsed = self.pc.started.map(|t| t.elapsed().as_secs_f64()).unwrap_or(0.0).max(0.001); + ui.label(format!("{} / {} · {}/s", + human_bytes(self.pc.done), human_bytes(self.pc.total), + human_bytes((self.pc.done as f64 / elapsed) as u64))); + } + }); + } + + fn start_pc_receiver(&mut self) { + let Some(dir) = self.pc.save_dir.clone() else { return }; + self.stop_pc(); + let token = pairing::new_session_token(); + let (tx, rx) = mpsc::channel(); + match ReceiverServer::start(dir, token, tx) { + Ok(server) => { + self.pc.status = format!( + "接收中。把配对码 {} 告诉发送方即可。", server.pair_code); + self.pc.server = Some(server); + self.receive.events = Some(rx); + self.receive.connected_device = "等待对方连接".into(); + self.receive.current_file = "—".into(); + self.receive.received = 0; + self.receive.total = 0; + } + Err(e) => self.pc.status = format!("启动接收失败:{e:#}"), + } + } + + fn browse_pc_peers(&mut self) { + let (tx, rx) = mpsc::channel(); + self.pc.events = Some(rx); + self.pc.busy = true; + self.pc.status = "正在搜索附近的电脑…".into(); + std::thread::spawn(move || { + let result = discovery::browse(receiver::DISCOVERY_PORT, Duration::from_millis(1200)); + let _ = match result { + Ok(peers) => tx.send(PcEvent::Peers(peers)), + Err(e) => tx.send(PcEvent::Failed(format!("搜索失败:{e:#}"))), + }; + }); + } + + /// 选中的对端,或手动输入的地址。手动输入允许省略 http:// 与端口。 + fn pc_target_base_url(&self) -> Option { + if let Some(index) = self.pc.selected_peer { + if let Some(peer) = self.pc.peers.get(index) { + return Some(peer.base_url()); + } + } + let raw = self.pc.manual_address.trim(); + if raw.is_empty() { + return None; + } + let raw = raw.trim_start_matches("http://").trim_end_matches('/'); + let with_port = if raw.contains(':') { + raw.to_string() + } else { + format!("{raw}:{}", receiver::PREFERRED_PORT) + }; + Some(format!("http://{with_port}")) + } + + fn pair_pc_peer(&mut self) { + let Some(base_url) = self.pc_target_base_url() else { return }; + let code = self.pc.code_input.trim().to_string(); + let device = self.local_device.clone(); + let (tx, rx) = mpsc::channel(); + self.pc.events = Some(rx); + self.pc.busy = true; + self.pc.status = format!("正在连接 {base_url}…"); + std::thread::spawn(move || { + let _ = match client::PeerClient::pair(&base_url, &code, &device) { + Ok(token) => tx.send(PcEvent::Paired { base_url, token }), + Err(e) => tx.send(PcEvent::Failed(format!("{e:#}"))), + }; + }); + } + + fn send_pc_files(&mut self) { + let (Some(base_url), Some(token)) = + (self.pc.connected_base.clone(), self.pc.token.clone()) else { return }; + let files = self.pc.files.clone(); + let device = self.local_device.clone(); + let total: u64 = files.iter() + .map(|f| std::fs::metadata(f).map(|m| m.len()).unwrap_or(0)) + .sum(); + + let (tx, rx) = mpsc::channel(); + self.pc.events = Some(rx); + self.pc.busy = true; + self.pc.done = 0; + self.pc.total = total; + self.pc.started = Some(Instant::now()); + self.pc.status = format!("正在发送 {} 个文件…", files.len()); + + std::thread::spawn(move || { + let peer = client::PeerClient::new(base_url, token, device); + // 逐个文件累加,跨文件的进度用 base 偏移拼起来 + let mut base = 0u64; + for path in files { + let name = path.file_name().and_then(|v| v.to_str()).unwrap_or("文件").to_string(); + let size = std::fs::metadata(&path).map(|m| m.len()).unwrap_or(0); + let progress_tx = tx.clone(); + let progress_name = name.clone(); + let result = peer.upload_file(&path, |p| { + let _ = progress_tx.send(PcEvent::Progress { + file: progress_name.clone(), + done: base + p.done, + total, + }); + }); + match result { + Ok(sha256) => { + base += size; + let _ = tx.send(PcEvent::Progress { file: name.clone(), done: base, total }); + let _ = tx.send(PcEvent::FileDone { file: name, sha256 }); + } + Err(e) => { + let _ = tx.send(PcEvent::Failed(format!("{name} 发送失败:{e:#}"))); + return; + } + } + } + let _ = tx.send(PcEvent::AllDone); + }); + } + + fn drain_pc_events(&mut self) { + // 接收侧完全复用既有的 ReceiverEvent 渲染逻辑,不另写一套 + self.poll_receiver_events(); + + let Some(rx) = self.pc.events.take() else { return }; + while let Ok(event) = rx.try_recv() { + match event { + PcEvent::Peers(peers) => { + self.pc.status = if peers.is_empty() { + "没有搜索到设备。确认对方已启动接收,或改用手动输入地址。".into() + } else { + format!("搜索到 {} 台设备。", peers.len()) + }; + self.pc.peers = peers; + self.pc.selected_peer = None; + self.pc.busy = false; + } + PcEvent::Paired { base_url, token } => { + self.pc.status = format!("已连接 {base_url},可以选择文件了。"); + self.pc.connected_base = Some(base_url); + self.pc.token = Some(token); + self.pc.busy = false; + } + PcEvent::Progress { file, done, total } => { + self.pc.current_file = file; + self.pc.done = done; + self.pc.total = total; + } + PcEvent::FileDone { file, sha256 } => { + self.pc.status = format!("{file} 已送达 · SHA-256 {}", &sha256[..16.min(sha256.len())]); + } + PcEvent::AllDone => { + self.pc.busy = false; + self.pc.current_file.clear(); + self.pc.status = "全部发送完成。".into(); + } + PcEvent::Failed(message) => { + self.pc.busy = false; + self.pc.status = message; + } + } + } + self.pc.events = Some(rx); + } + fn stop_receiver(&mut self) { self.receive.events = None; self.receive.server = None; @@ -974,6 +1400,7 @@ impl eframe::App for QftApp { Screen::Home => self.home_ui(ui), Screen::OpticalSend => self.optical_ui(ui, &ctx), Screen::PhoneToPc => self.receive_ui(ui, &ctx), + Screen::PcToPc => self.pc_to_pc_ui(ui, &ctx), Screen::PcToPhone => self.pc_to_phone_ui(ui, &ctx), } }); diff --git a/windows/src/optical_cache.rs b/desktop/src/optical_cache.rs similarity index 100% rename from windows/src/optical_cache.rs rename to desktop/src/optical_cache.rs diff --git a/windows/src/pairing.rs b/desktop/src/pairing.rs similarity index 91% rename from windows/src/pairing.rs rename to desktop/src/pairing.rs index 6572de2..9012a51 100644 --- a/windows/src/pairing.rs +++ b/desktop/src/pairing.rs @@ -90,6 +90,22 @@ impl PairingPayload { } } +/// 6 位数字配对码,供 PC↔PC 使用。 +/// +/// 桌面端之间没有摄像头,二维码用不上,用户只能目视或口头传递这 6 位。 +/// 用拒绝采样避免取模偏置——虽然此处偏置只有约 1e-5,但没必要留下这种脏细节。 +pub fn new_pair_code() -> String { + let mut bytes = [0u8; 4]; + loop { + rand::rng().fill_bytes(&mut bytes); + let value = u32::from_be_bytes(bytes); + // 4_294_000_000 是 1_000_000 的整数倍中不超过 u32::MAX 的最大值 + if value < 4_294_000_000 { + return format!("{:06}", value % 1_000_000); + } + } +} + pub fn new_session_token() -> String { let mut bytes = [0u8; 16]; rand::rng().fill_bytes(&mut bytes); @@ -145,12 +161,7 @@ pub fn reset_direct_ap_credentials() -> Result<()> { } fn direct_ap_identity_path() -> PathBuf { - if let Ok(root) = std::env::var("LOCALAPPDATA") { - if !root.trim().is_empty() { - return PathBuf::from(root).join("QFT").join("direct-ap.json"); - } - } - PathBuf::from(".qft").join("direct-ap.json") + crate::platform::config_dir().join("direct-ap.json") } fn new_direct_ap_credentials(pc_name: &str) -> (String, String) { diff --git a/desktop/src/platform.rs b/desktop/src/platform.rs new file mode 100644 index 0000000..5f051b1 --- /dev/null +++ b/desktop/src/platform.rs @@ -0,0 +1,238 @@ +//! 平台差异的唯一收敛点。 +//! +//! 约定:除本文件与 `direct_ap.rs` 外,其余模块不得出现 `#[cfg(target_os = ...)]`。 +//! 新增平台差异时先在这里补一个函数,不要就地 cfg —— 否则跨平台移植会重新变成 +//! 满仓库找 cfg 的考古工作。 + +use std::path::{Path, PathBuf}; + +/// QFT 的持久化配置目录(Direct AP 身份、信任库等)。 +/// +/// - Windows: `%LOCALAPPDATA%\QFT` +/// - macOS: `~/Library/Application Support/QFT` +/// - Linux: `$XDG_CONFIG_HOME/qft`,未设置时 `~/.config/qft` +pub fn config_dir() -> PathBuf { + #[cfg(target_os = "windows")] + { + if let Some(root) = non_empty_env("LOCALAPPDATA") { + return PathBuf::from(root).join("QFT"); + } + } + #[cfg(target_os = "macos")] + { + if let Some(home) = home_dir() { + return home.join("Library").join("Application Support").join("QFT"); + } + } + #[cfg(all(unix, not(target_os = "macos")))] + { + if let Some(root) = non_empty_env("XDG_CONFIG_HOME") { + return PathBuf::from(root).join("qft"); + } + if let Some(home) = home_dir() { + return home.join(".config").join("qft"); + } + } + // 环境变量全都拿不到时退回当前目录下的隐藏目录,保证功能不中断 + PathBuf::from(".qft") +} + +/// 接收文件的默认保存目录。 +pub fn default_download_dir() -> PathBuf { + #[cfg(all(unix, not(target_os = "macos")))] + { + // Linux 桌面环境会把"下载"本地化(中文系统是 ~/下载), + // 目录名记录在 user-dirs.dirs 里,直接拼 "Downloads" 会建出一个用户看不见的目录。 + if let Some(dir) = xdg_user_dir("XDG_DOWNLOAD_DIR") { + return dir; + } + } + if let Some(home) = home_dir() { + let downloads = home.join("Downloads"); + if downloads.is_dir() { + return downloads; + } + return home; + } + PathBuf::from(".") +} + +/// 展示给对端的本机名称。 +pub fn device_name() -> String { + let raw = whoami::fallible::hostname().unwrap_or_else(|_| whoami::devicename()); + sanitize_device_name(&raw) +} + +/// 设备名会进入配对二维码与 mDNS TXT,必须去掉控制字符并限长。 +pub fn sanitize_device_name(raw: &str) -> String { + let cleaned: String = raw + .chars() + .filter(|ch| !ch.is_control()) + .take(64) + .collect(); + let trimmed = cleaned.trim(); + if trimmed.is_empty() { + default_device_name().to_owned() + } else { + trimmed.to_owned() + } +} + +const fn default_device_name() -> &'static str { + #[cfg(target_os = "windows")] + { + "Windows-PC" + } + #[cfg(target_os = "macos")] + { + "Mac" + } + #[cfg(all(unix, not(target_os = "macos")))] + { + "Linux-PC" + } +} + +/// 本机所属平台,用于 mDNS TXT 与 UI 图标。 +pub const fn platform_tag() -> &'static str { + #[cfg(target_os = "windows")] + { + "windows" + } + #[cfg(target_os = "macos")] + { + "macos" + } + #[cfg(all(unix, not(target_os = "macos")))] + { + "linux" + } +} + +/// 本机能否开启 QFT Direct 临时热点。 +/// +/// 只有 Windows 走 WiFi Direct;macOS 无公开 API,Linux 各发行版 +/// NetworkManager 行为差异过大,都不做——UI 据此隐藏入口, +/// 而不是让用户点进去再失败。 +pub enum DirectApSupport { + Supported, + Unsupported(&'static str), +} + +pub const fn direct_ap_support() -> DirectApSupport { + #[cfg(target_os = "windows")] + { + DirectApSupport::Supported + } + #[cfg(not(target_os = "windows"))] + { + DirectApSupport::Unsupported("本平台不支持 QFT Direct 热点,请让两台设备连接同一个 Wi-Fi") + } +} + +impl DirectApSupport { + pub const fn is_supported(&self) -> bool { + matches!(self, DirectApSupport::Supported) + } +} + +// ---------------------------------------------------------------- 内部工具 + +fn non_empty_env(key: &str) -> Option { + std::env::var(key).ok().filter(|v| !v.trim().is_empty()) +} + +fn home_dir() -> Option { + #[cfg(target_os = "windows")] + { + if let Some(profile) = non_empty_env("USERPROFILE") { + return Some(PathBuf::from(profile)); + } + let drive = non_empty_env("HOMEDRIVE")?; + let path = non_empty_env("HOMEPATH")?; + return Some(PathBuf::from(format!("{drive}{path}"))); + } + #[cfg(unix)] + { + non_empty_env("HOME").map(PathBuf::from) + } +} + +/// 解析 `~/.config/user-dirs.dirs` 里形如 +/// `XDG_DOWNLOAD_DIR="$HOME/下载"` 的一行。 +#[cfg(all(unix, not(target_os = "macos")))] +fn xdg_user_dir(key: &str) -> Option { + let home = home_dir()?; + let config = non_empty_env("XDG_CONFIG_HOME") + .map(PathBuf::from) + .unwrap_or_else(|| home.join(".config")); + let text = std::fs::read_to_string(config.join("user-dirs.dirs")).ok()?; + for line in text.lines() { + let line = line.trim(); + if line.starts_with('#') { + continue; + } + let (name, value) = line.split_once('=')?; + if name.trim() != key { + continue; + } + let value = value.trim().trim_matches('"'); + let expanded = if let Some(rest) = value.strip_prefix("$HOME/") { + home.join(rest) + } else if value == "$HOME" { + home.clone() + } else { + PathBuf::from(value) + }; + if expanded.is_dir() { + return Some(expanded); + } + } + None +} + +/// 确保目录存在,返回其路径。调用方负责处理失败。 +pub fn ensure_dir(path: &Path) -> std::io::Result<()> { + if path.is_dir() { + return Ok(()); + } + std::fs::create_dir_all(path) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn config_dir_is_absolute_or_local_fallback() { + let dir = config_dir(); + // 要么是绝对路径(拿到了环境变量),要么是约定的本地兜底 + assert!(dir.is_absolute() || dir == PathBuf::from(".qft"), "{dir:?}"); + } + + #[test] + fn device_name_is_never_empty_and_bounded() { + let name = device_name(); + assert!(!name.is_empty()); + assert!(name.chars().count() <= 64); + assert!(!name.chars().any(char::is_control)); + } + + #[test] + fn sanitize_strips_control_chars_and_falls_back() { + assert_eq!(sanitize_device_name(" ok-name \n"), "ok-name"); + assert_eq!(sanitize_device_name("a\u{0}b"), "ab"); + assert_eq!(sanitize_device_name(" "), default_device_name()); + assert_eq!(sanitize_device_name("\n\t"), default_device_name()); + assert_eq!(sanitize_device_name(&"x".repeat(200)).chars().count(), 64); + } + + #[test] + fn platform_tag_matches_direct_ap_capability() { + // Direct AP 目前只有 Windows 支持,两个常量必须保持一致 + assert_eq!( + direct_ap_support().is_supported(), + platform_tag() == "windows" + ); + } +} diff --git a/windows/src/protocol.rs b/desktop/src/protocol.rs similarity index 95% rename from windows/src/protocol.rs rename to desktop/src/protocol.rs index 84646b0..947a192 100644 --- a/windows/src/protocol.rs +++ b/desktop/src/protocol.rs @@ -191,19 +191,7 @@ pub fn hex_sha256(bytes: &[u8; 32]) -> String { } pub fn local_device_name() -> String { - let raw = std::env::var("COMPUTERNAME") - .or_else(|_| std::env::var("HOSTNAME")) - .unwrap_or_else(|_| "Windows-PC".to_owned()); - let cleaned: String = raw - .chars() - .filter(|ch| !ch.is_control()) - .take(64) - .collect(); - if cleaned.trim().is_empty() { - "Windows-PC".to_owned() - } else { - cleaned - } + crate::platform::device_name() } fn hash_file_streaming(file: &File) -> Result<[u8; 32]> { diff --git a/windows/src/qr.rs b/desktop/src/qr.rs similarity index 100% rename from windows/src/qr.rs rename to desktop/src/qr.rs diff --git a/windows/src/receiver.rs b/desktop/src/receiver.rs similarity index 86% rename from windows/src/receiver.rs rename to desktop/src/receiver.rs index aca0b5f..cfb8eee 100644 --- a/windows/src/receiver.rs +++ b/desktop/src/receiver.rs @@ -10,7 +10,7 @@ use std::{ net::{TcpListener, TcpStream, UdpSocket}, path::{Path, PathBuf}, sync::{ - atomic::{AtomicBool, Ordering}, + atomic::{AtomicBool, AtomicU32, Ordering}, mpsc::Sender, Arc, Mutex, }, @@ -59,6 +59,9 @@ struct CompletedUpload { pub struct ReceiverServer { pub port: u16, + /// PC↔PC 用的 6 位配对码:对端没有摄像头,扫不了二维码, + /// 只能靠用户口头/目视传递这 6 位数字来换取会话令牌。 + pub pair_code: String, stop: Arc, tcp_thread: Option>, udp_thread: Option>, @@ -76,6 +79,10 @@ impl ReceiverServer { let stop = Arc::new(AtomicBool::new(false)); let sessions: SessionMap = Arc::new(Mutex::new(HashMap::new())); let completed: CompletedMap = Arc::new(Mutex::new(HashMap::new())); + // 6 位数字只有约 20 bit 熵,单靠它不足以抵抗在线爆破, + // 因此配一个严格的失败计数:错 5 次即作废,必须重启接收重新生成。 + let pair_code = crate::pairing::new_pair_code(); + let pair_failures = Arc::new(AtomicU32::new(0)); let stop_tcp = stop.clone(); let sessions_tcp = sessions.clone(); @@ -83,6 +90,8 @@ impl ReceiverServer { let token_tcp = session_token.clone(); let dir_tcp = save_dir.clone(); let events_tcp = events.clone(); + let code_tcp = pair_code.clone(); + let failures_tcp = pair_failures.clone(); let tcp_thread = thread::spawn(move || { while !stop_tcp.load(Ordering::Relaxed) { match listener.accept() { @@ -92,8 +101,10 @@ impl ReceiverServer { let tx = events_tcp.clone(); let sessions = sessions_tcp.clone(); let completed = completed_tcp.clone(); + let code = code_tcp.clone(); + let failures = failures_tcp.clone(); thread::spawn(move || { - if let Err(e) = handle_client(&mut stream, &dir, &token, &tx, &sessions, &completed) { + if let Err(e) = handle_client(&mut stream, &dir, &token, &code, &failures, &tx, &sessions, &completed) { // Never turn a parse/write race into an opaque Android // `unexpected end of stream`: make a best effort to // return an HTTP status before closing the socket. @@ -129,12 +140,25 @@ impl ReceiverServer { let _ = socket.set_read_timeout(Some(Duration::from_millis(250))); let expected = format!("QFTDISC2:{token_udp}"); let response = format!("QFTHERE2:{token_udp}:{port}"); + // PC↔PC 的对端不知道令牌,需要先能把本机列出来 + let announce = crate::discovery::browse_reply(&crate::discovery::NodeAnnounce { + n: crate::platform::device_name(), + p: crate::platform::platform_tag().to_owned(), + t: port, + r: true, + }); let mut buf = [0u8; 512]; while !stop_udp.load(Ordering::Relaxed) { match socket.recv_from(&mut buf) { Ok((n, peer)) => { - if std::str::from_utf8(&buf[..n]).ok() == Some(expected.as_str()) { - let _ = socket.send_to(response.as_bytes(), peer); + match std::str::from_utf8(&buf[..n]).ok() { + Some(text) if text == expected => { + let _ = socket.send_to(response.as_bytes(), peer); + } + Some(text) if text == crate::discovery::BROWSE_QUERY => { + let _ = socket.send_to(&announce, peer); + } + _ => {} } } Err(e) if matches!(e.kind(), std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut) => {} @@ -147,6 +171,7 @@ impl ReceiverServer { port, stop, tcp_thread: Some(tcp_thread), + pair_code, udp_thread: Some(udp_thread), }) } @@ -164,10 +189,64 @@ impl Drop for ReceiverServer { } } +/// `POST /qft/pair`,请求头 `X-QFT-Code: 123456`。 +/// +/// 这是唯一不校验令牌的端点——它的作用就是用 6 位码换取令牌。 +/// 6 位只有约 20 bit 熵,必须靠失败计数兜底:错 5 次即作废整个码, +/// 用户需要在电脑上重新启动接收才能拿到新码。 +fn handle_pair( + stream: &mut TcpStream, + headers: &HashMap, + token: &str, + pair_code: &str, + pair_failures: &AtomicU32, + events: &Sender, +) -> Result<()> { + const MAX_FAILURES: u32 = 5; + if pair_failures.load(Ordering::Relaxed) >= MAX_FAILURES { + let body = json!({ + "ok": false, + "error": "配对码已因多次输入错误作废,请在电脑上重新启动接收" + }).to_string(); + return write_response(stream, 429, "application/json", body.as_bytes()); + } + + let supplied = headers.get("x-qft-code").map(String::as_str).unwrap_or(""); + if !constant_time_eq(supplied.as_bytes(), pair_code.as_bytes()) { + let count = pair_failures.fetch_add(1, Ordering::Relaxed) + 1; + let _ = events.send(ReceiverEvent::Error(format!( + "配对码错误({count}/{MAX_FAILURES})" + ))); + let body = json!({"ok": false, "remaining": MAX_FAILURES.saturating_sub(count)}).to_string(); + return write_response(stream, 403, "application/json", body.as_bytes()); + } + + pair_failures.store(0, Ordering::Relaxed); + let device = decode_header(headers.get("x-qft-device")).unwrap_or_else(|| "电脑".to_owned()); + let _ = events.send(ReceiverEvent::ClientConnected { device }); + let body = json!({"ok": true, "token": token}).to_string(); + write_response(stream, 200, "application/json", body.as_bytes()) +} + +/// 定长比较,不因首个不同字节的位置而提前返回。 +/// 局域网上计时攻击并不现实,但这段代码很便宜,没有理由写成短路比较。 +fn constant_time_eq(a: &[u8], b: &[u8]) -> bool { + if a.len() != b.len() { + return false; + } + let mut diff = 0u8; + for (x, y) in a.iter().zip(b.iter()) { + diff |= x ^ y; + } + diff == 0 +} + fn handle_client( stream: &mut TcpStream, save_dir: &Path, token: &str, + pair_code: &str, + pair_failures: &AtomicU32, events: &Sender, sessions: &SessionMap, completed: &CompletedMap, @@ -202,6 +281,11 @@ fn handle_client( let method = parts.next().unwrap_or(""); let path = parts.next().unwrap_or(""); + // 配对是唯一不需要令牌的端点——它的作用正是换取令牌。 + if method == "POST" && path == "/qft/pair" { + return handle_pair(stream, &headers, token, pair_code, pair_failures, events); + } + let supplied = headers.get("x-qft-token").map(String::as_str).unwrap_or(""); if supplied != token { return write_response(stream, 403, "text/plain", b"invalid session"); @@ -641,6 +725,8 @@ mod tests { &mut stream, &dir_for_server, "session", + "000000", + &AtomicU32::new(0), &events, &sessions, &completed, diff --git a/windows/src/sender.rs b/desktop/src/sender.rs similarity index 100% rename from windows/src/sender.rs rename to desktop/src/sender.rs diff --git a/docs/OPTICAL_V5_PLAN.md b/docs/OPTICAL_V5_PLAN.md index 11d5466..c6fb01b 100644 --- a/docs/OPTICAL_V5_PLAN.md +++ b/docs/OPTICAL_V5_PLAN.md @@ -428,6 +428,6 @@ App 应根据实测能力自动选档,并在 UI 明示当前档位与预计耗 | 兼容 | 720p | 4.0 | 30 | 128 KB/s | 最低保障 | ### 何时不该用光学 -仓库已有 `QFTSEND2` 扫码直传(`windows/src/sender.rs`:HTTP + Range 续传 + UDP 发现), +仓库已有 `QFTSEND2` 扫码直传(`desktop/src/sender.rs`:HTTP + Range 续传 + UDP 发现), 10 MB 在局域网下是亚秒级。光学链路应明确定位为**物理隔离场景专用**, 并在选择大文件时主动提示直传方案与两者的预计耗时对比。 diff --git a/docs/V05_EXECUTION_PLAN.md b/docs/V05_EXECUTION_PLAN.md new file mode 100644 index 0000000..576fe14 --- /dev/null +++ b/docs/V05_EXECUTION_PLAN.md @@ -0,0 +1,219 @@ +# QFT v0.5 执行计划 + +配套设计文档:[V05_MULTIPEER_PLAN.md](V05_MULTIPEER_PLAN.md) + +--- + +## 0. 三个默认决策(未经确认,可推翻) + +设计文档结尾留了三个待定问题,为了让计划能往下排,先按以下默认执行。任一项改变都会影响排期,改之前先说。 + +| 问题 | 默认决策 | 理由 | +|---|---|---| +| M1 先做还是直接上 v3? | **M1 先做** | 零协议风险,做完立刻拿到真实 PC↔PC 体验;v3 的很多设计细节需要真实使用反馈才定得准 | +| 加密在哪一版做? | **放到 v3(P2),M1 维持现状明文** | TLS 与新协议一起做只需改一次握手层;分两次做要动两遍,且 M1 的目的是尽快验证对称节点模型 | +| 共享核心怎么做? | **桌面共享 Rust + 移动端原生 + `conformance/` 一致性套件** | 桌面三平台本来就是同一份代码(实测仅 3 处平台耦合),共享零成本;移动端 FFI 要等 v3 定型才划算 | + +--- + +## 1. 总体流程 + +```mermaid +flowchart TD + P0["P0 收尾验证
把半成品编译掉"] --> P1["P1 桌面跨平台 + PC↔PC
走现有 v2 协议"] + P1 --> P2["P2 QFT-Stream v3
目录直传 + 加密"] + P2 --> P3["P3 移动端接入 v3"] + P3 --> P4["P4 手机 ↔ 手机"] + P2 -.并行.-> P5["P5 一致性套件
+ 性能回归"] + P0 -.独立并行轨.-> OPT["QFT5 光学
阻塞于楔形标定"] + + style P0 fill:#7a2020,color:#fff + style OPT fill:#5a4a20,color:#fff +``` + +**P0 是硬阻塞。** 当前有三处「写了但没验证」的代码,在其之上继续叠加会让问题定位成本指数上升。 + +--- + +## 2. P0 · 收尾验证(阻塞,必须先做) + +| # | 任务 | 涉及 | 验收标准 | 谁做 | +|---|---|---|---|---| +| P0.1 | Android bug 修复编译 | `DownloadClient.kt` `WifiConnector.kt` `MainActivity.kt` | `./gradlew :app:assembleDebug` 通过 | **你**(我没有 Android SDK) | +| P0.2 | Android bug 修复实测 | — | 大文件传输走完全程;断网时 3 秒内报「临时网络已断开」而非等满重试;空间不足在开始前就提示 | **你**(需真机 + Windows 主机) | +| P0.3 | iOS 模拟器编译 | `ios/QFT/App/*.swift` | Xcode 选 iPhone 模拟器,⌘B 无红色错误 | **你** | +| P0.4 | `xcode-select` 指向 Xcode | — | `xcodebuild -version` 可用 | **你**(需 sudo) | +| P0.5 | 修掉 P0.1/P0.3 暴露的编译错误 | 视情况 | 同上重跑通过 | 我 | +| P0.6 | 提交并推送 | — | 工作区干净 | 我 | + +**门禁:P0.1 与 P0.3 全绿才进入 P1。** + +P0.4 做完之后我可以直接在命令行编译 iOS 工程,后续 Swift 改动就不再是盲写——这一项虽然可选,但会显著提升后面所有 iOS 相关工作的质量。 + +--- + +## 3. P1 · 桌面跨平台 + PC↔PC + +目标:**mac ↔ win、linux ↔ win 能互传单个文件**,仍走现有 v2 HTTP 协议。 + +| # | 任务 | 涉及 | 规模 | 验收标准 | +|---|---|---|---|---| +| P1.1 | `windows/` → `desktop/`,crate 更名 `qft-desktop` | 目录 + `Cargo.toml` + CI 脚本 + `VERIFY_WINDOWS_HOST.ps1` | S | `cargo check` 在 macOS 上通过 | +| P1.2 | 平台抽象层 `platform.rs` | 新增;改 `direct_ap.rs` `pairing.rs:148` `protocol.rs:194` | M | 三平台各自 `cargo test` 通过 | +| P1.3 | 配置/下载目录跨平台 | `pairing.rs` + 新增 | S | mac 写到 `~/Library/Application Support/QFT`,linux 写到 `$XDG_CONFIG_HOME/qft` | +| P1.4 | **桌面客户端** `client.rs` | 新增(当前完全缺失) | L | 单元测试:对本进程起的 receiver 完成一次上传 + 一次下载 | +| P1.5 | mDNS 发现 `discovery.rs` | 新增,`mdns-sd` crate | M | 两台机器互相出现在列表里;TXT 含 `v/id/name/platform/port` | +| P1.6 | 6 位配对码 | `pairing.rs` | M | 跨网段场景下输码可连;错码 3 次锁定 | +| P1.7 | UI:「附近的设备」页 + 拖拽发送 | `main.rs` | L | 拖文件到窗口即发送 | +| P1.8 | macOS / Linux 打包 | 新增 CI | M | 产出 `.app`(未签名)与 AppImage/tar.gz | + +### P1 验收门 + +``` +✅ mac → win 传 1GB 单文件,SHA-256 一致 +✅ win → mac 同上 +✅ linux → win 同上 +✅ 三平台各自能在「附近的设备」里看到另外两台 +✅ 拔网线重插后能续传(v2 的 Range 续传) +``` + +**这一门通过之前不进 P2。** 因为 v3 的价值全部建立在「对称节点模型成立」之上,先用最简单的协议把这个模型验证掉。 + +--- + +## 4. P2 · QFT-Stream v3 + +目标:**目录直传可用**,先只在两台 PC 之间。 + +| # | 任务 | 规模 | 验收标准 | +|---|---|---|---| +| P2.1 | 帧编解码 + 黄金测试向量 | M | 向量文件 `conformance/frames.json`,编解码往返一致 | +| P2.2 | Ed25519 身份 + 信任库 | M | 首次运行生成密钥;重启后身份不变 | +| P2.3 | TLS 1.3(`rustls`)+ 按公钥验证对端 | L | 错误公钥必须握手失败;6 位校验码两端一致 | +| P2.4 | 会话层:`SESSION_OPEN` / `INDEX_*` / `HAVE` | L | 断开重连后不重传已完成文件 | +| P2.5 | **流式并行索引** | M | 10 万文件树:首字节传输在遍历完成前就开始 | +| P2.6 | **小文件合批** | L | 见下方性能门 | +| P2.7 | 大文件分块并发 + 流控反压 | M | 接收端磁盘限速时内存不超过 `连接数 × 8MiB` | +| P2.8 | 路径安全层 | M | 见下方安全门 | +| P2.9 | 每文件 SHA-256 + 单遍哈希 | S | 单个坏文件只重传自己 | + +### P2 性能门(在千兆有线上实测) + +| 场景 | 目标 | 现状对照 | +|---|---|---| +| 5 万小文件 / 0.95 GB | **< 15 s** | v2 约 608 s | +| 3 千文件 / 11.7 GB | < 120 s | v2 约 138 s | +| 单文件 10 GB | < 95 s | v2 约 87 s(不得退化) | +| 峰值内存 | < 200 MB | — | + +### P2 安全门(跨系统路径用例,全部必须通过) + +``` +linux → win : 目录含 CON.txt / aux.log / "a.txt" / 结尾带空格的名字 +linux → win : 同目录下 README.md 与 readme.md(大小写冲突) +linux → mac : 文件名含 "é"(NFC/NFD 归一化) +任意 → 任意 : 路径含 ../、绝对路径、指向根目录外的符号链接 → 整会话拒绝 +win → 任意 : 路径长度超过 260 +``` + +每条都要有自动化用例,不能靠手测。 + +--- + +## 5. P3 · 移动端接入 v3 + +| # | 任务 | 端 | 规模 | +|---|---|---|---| +| P3.1 | Android `NodeServer.kt`(ServerSocket + v3 帧) | Android | L | +| P3.2 | Android `NsdManager` 发现 | Android | M | +| P3.3 | Android 前台服务 + WakeLock | Android | M | +| P3.4 | Android 目录接收(SAF `OPEN_DOCUMENT_TREE`) | Android | M | +| P3.5 | iOS `PeerLink` 并入 v3 帧格式 | iOS | M | +| P3.6 | iOS 目录接收 + 「文件」App 导出 | iOS | M | + +**门禁:手机 ↔ 电脑走 v3 传一个 5000 文件的目录成功。** + +P3.3 是现有隐患的正式修复——当前只有 `FLAG_KEEP_SCREEN_ON`,息屏或切后台就有被系统掐断的风险。 + +--- + +## 6. P4 · 手机 ↔ 手机 + +| 组合 | 任务 | 备注 | +|---|---|---| +| iOS ↔ iOS | 已实现,接 v3 即可 | `PeerLink.swift` 复用 | +| Android ↔ Android | `WifiP2pManager` 或 Local Only Hotspot,回落同 LAN | 新增 | +| Android ↔ iOS | **仅同一局域网** | UI 必须明确提示,不给假希望 | + +**门禁:三种组合各传一个含子目录的相册目录成功。** + +--- + +## 7. P5 · 一致性套件(与 P2 并行) + +把 `ios/CoreTests/MockPCServer.py` 的做法推广成 `conformance/`: + +``` +conformance/ + vectors/ 黄金测试向量(帧编解码、路径规范化、合批边界) + reference_peer.py 参考对端,任一端实现都能对着它跑 + run.sh 三端各自跑一遍 +``` + +接入 `scripts/run_all_selftests.py`。**这是目前防三端协议漂移最有效的手段**,在 iOS 端已验证有效。 + +--- + +## 8. 验证责任分工 + +这个项目的返工大多来自「写完没法验证」。明确分工: + +| 我能在这台 Mac 上做 | 只有你能做 | +|---|---| +| Rust `cargo check/test`(装了 Rust 之后) | Windows 上的 `cargo build --release` 与真机跑 | +| Swift 核心层编译 + 单测 | iOS 真机(相机、AWDL) | +| Swift 全量编译(**需你先做 P0.4**) | Android 编译与真机 | +| Python 工具与一致性套件 | 千兆有线上的性能实测 | +| 协议设计、黄金向量、代码审查 | 楔形标定拍照 | + +**Kotlin 目前我完全无法编译**(本机无 Android SDK,装 kotlinc 会连带拉一个多余的 JDK)。所以 Android 侧改动我会尽量小步、单文件,每次都请你编译一次再继续——不要攒一大批。 + +--- + +## 9. 并行轨:QFT5 光学 + +与 v0.5 无依赖关系,可随时插入。当前**阻塞于楔形标定**: + +``` +你拍标定图 → 跑 wedge_analyze.py → 得到实测 px/模块 + ↓ + ≤3.2 → 按 OPTICAL_V5_PLAN 原样实施 + 3.2~4.0 → 目标 B 不可达,需下调指标 + >4.0 → 先排查对焦/曝光,不要动协议 +``` + +标定之前可以做的(不依赖该数值):相机帧率三级锁定、手动短曝光、关 EIS/抗闪烁、锁对焦、陀螺仪前馈。这几项**对现有 QFT2 链路也立刻有收益**(3px/模块下 33ms 自动曝光会产生 8.7px 运动模糊,等于抹掉近 3 个模块)。 + +--- + +## 10. 回滚点与风险 + +| 阶段 | 回滚点 | 触发条件 | +|---|---|---| +| P1 | 保留 `windows/` 分支 tag | 跨平台抽象破坏了 Windows 行为 | +| P2 | v2 与 v3 并存,节点协商版本 | v3 性能门不达标 | +| P3 | 移动端可继续用 v2 | v3 在移动端内存/耗电不可接受 | + +**每个阶段结束打一个 tag**,v3 与 v2 全程并存,任一阶段失败都不影响已发布版本可用。 + +--- + +## 11. 下一步 + +按顺序,现在只需要做三件事: + +1. `cd android && ./gradlew :app:assembleDebug` —— 把 bug 修复编译掉,报错发我 +2. Xcode 选模拟器 ⌘B —— iOS UI 层编译掉,报错发我 +3. (可选但强烈建议)`sudo xcode-select -s /Applications/Xcode.app/Contents/Developer` + +这三件完成后我开始 P1.1。 diff --git a/docs/V05_MULTIPEER_PLAN.md b/docs/V05_MULTIPEER_PLAN.md new file mode 100644 index 0000000..3daf24c --- /dev/null +++ b/docs/V05_MULTIPEER_PLAN.md @@ -0,0 +1,297 @@ +# QFT v0.5 增量设计:全平台对等互传 + +基线 v0.4.7。三项增量需求: + +1. 电脑 ↔ 电脑互传,跨平台(mac ↔ win ↔ mac,linux ↔ win ↔ mac) +2. 手机 ↔ 手机互传 +3. 全量高速传输,支持目录直传,高速索引 + 稳定连接 + +--- + +## 0. 现状盘点(实测,非推测) + +| 项 | 现状 | 影响 | +|---|---|---| +| 桌面端角色 | **只有服务端**。`TcpStream::connect` 仅出现在 `#[cfg(test)]` 里 | PC 无法主动连接对方 → PC↔PC 完全不可用 | +| HTTP 连接 | 每个响应都写 `Connection: close`(`sender.rs:183/188/211`、`receiver.rs:531`) | 每个分块新建一次 TCP | +| 上传会话 | `UploadSession { file_name, size, chunk_size, total_chunks }` —— **单文件** | 无目录概念 | +| Windows 耦合 | 仅 3 处:`direct_ap.rs`(已 cfg 隔离)、`pairing.rs:148` 的 `LOCALAPPDATA`、`protocol.rs:194` 的 `COMPUTERNAME`。`read_at_once` 已有 unix 分支 | **跨平台成本比预期低得多** | +| 传输加密 | 无,局域网明文 HTTP | 同网段任何人可读文件内容 | +| 协议实现 | Rust 2845 行 / Kotlin 4423 行 / Swift 2053 行,同一协议三份实现 | 每加一个特性要写三遍 | + +### 目录传输在现有协议下的实际代价 + +每个文件需要 init + chunk + finish 三次 HTTP,且每次都新建 TCP(局域网 RTT 按 2ms 计): + +| 场景 | 文件数 | 总量 | 纯握手 | 数据传输(1GbE) | 合计 | +|---|---|---|---|---|---| +| 代码仓库 `node_modules` | 50 000 | 0.95 GB | **600 s** | 8 s | **608 s** | +| 照片目录 | 3 000 | 11.7 GB | 36 s | 102 s | 138 s | +| 单个大文件 | 1 | 10 GB | 0 s | 87 s | 87 s | + +**小文件场景 98% 的时间花在握手上。** 这是本次设计的首要矛盾,不是带宽问题。 + +--- + +## 1. 核心设计决策:从「角色固定」到「对称节点」 + +现有架构把角色写死了:PC 是服务端,手机是客户端。三项需求全都被这个假设挡住。 + +v0.5 引入 **QFT Node** 模型——每个安装都同时具备: + +``` +┌─────────────────── QFT Node ───────────────────┐ +│ 身份 Ed25519 密钥对(首次运行生成,持久化) │ +│ 广播端 mDNS _qft._tcp + UDP 兜底 │ +│ 服务端 QFT-Stream v3 监听器(接受传入会话) │ +│ 客户端 QFT-Stream v3 发起器(主动连接对方) │← 桌面端当前缺失 +│ 信任库 已确认过的对端公钥 │ +└────────────────────────────────────────────────┘ +``` + +一旦对称,三项需求退化成同一件事:**任意两个节点之间建立一条 v3 会话**。PC↔PC、手机↔手机、PC↔手机走完全相同的代码路径,差别只在链路选择。 + +--- + +## 2. 需求一:跨平台桌面端 + +### 2.1 目录改名与平台抽象 + +`windows/` → `desktop/`(crate 名 `qft-desktop`)。eframe/egui、rfd、rayon 本来就跨平台,实际要动的只有三处: + +| 文件 | 现状 | 改法 | +|---|---|---| +| `direct_ap.rs` | Windows WiFi Direct,非 Windows 直接 `bail!` | 抽成 `trait LinkProvider`,mac/linux 返回 `Unsupported`,UI 隐藏该入口 | +| `pairing.rs:148` | `LOCALAPPDATA` | `directories` crate:win=`%LOCALAPPDATA%`,mac=`~/Library/Application Support`,linux=`$XDG_CONFIG_HOME` | +| `protocol.rs:194` | `COMPUTERNAME`/`HOSTNAME` | `hostname` crate + 各平台友好名(mac 读 `ComputerName`) | + +另需新增:默认保存目录(win=`Downloads`,mac=`~/Downloads`,linux=`XDG_DOWNLOAD_DIR`)、单实例锁、开机自启(可选)。 + +**估算:这部分是整个方案里性价比最高的**——三个文件加一层 trait,就拿到 macOS 与 Linux。 + +### 2.2 桌面客户端(当前完全缺失) + +新增 `desktop/src/client.rs`,实现 Node 的发起侧。UI 上新增「附近的设备」页: + +``` +┌─ 附近的设备 ────────────────────────────┐ +│ 🖥 MacBook-Pro macOS 26 ● 已信任 │ +│ 💻 DESKTOP-M7DEVQO Windows 11 ○ 未信任 │ +│ 📱 iPhone 17 Pro iOS 26 ● 已信任 │ +│ 🖥 ubuntu-dev Linux ○ 未信任 │ +├────────────────────────────────────────┤ +│ [ 拖拽文件/文件夹到此处发送 ] │ +└────────────────────────────────────────┘ +``` + +拖拽是桌面端的核心交互——这也是目录直传最自然的入口。 + +### 2.3 两台 PC 怎么互相发现(没有摄像头,扫不了码) + +| 手段 | 适用 | 说明 | +|---|---|---| +| **mDNS / DNS-SD**(主) | 同一局域网 | 服务类型 `_qft._tcp`,TXT 携带 `v/id/name/platform/port/fp`。三平台都有成熟实现:桌面 `mdns-sd` crate、Android `NsdManager`、iOS `NWBrowser`(P2P 已在用) | +| UDP 广播(兜底) | mDNS 被交换机/防火墙拦时 | 沿用现有 `QFTDISC2`,升级到 v3 | +| **6 位配对码**(跨网段/兜底) | 不同子网、AP 隔离 | 接收方显示 6 位数字,发送方手输 | +| 手动 IP | 极端情况 | 直接输 `192.168.1.20:39393` | + +QR 在 PC↔PC 场景不适用(对方没摄像头),所以 **6 位配对码是 PC↔PC 的必需品**,不是可选项。 + +--- + +## 3. 需求二:手机 ↔ 手机 + +| 组合 | 链路 | 状态 | +|---|---|---| +| iOS ↔ iOS | AWDL 点对点(`includePeerToPeer`)+ TLS-PSK | **已实现**(`PeerLink.swift`),并入 v3 即可 | +| Android ↔ Android | Wi-Fi Direct(`WifiP2pManager`)或 Local Only Hotspot,回落同 LAN | 需新增:Android 端 v3 服务端 | +| **Android ↔ iOS** | **只能同一局域网** | 见下 | + +### 关于 Android ↔ iOS 必须说清楚的限制 + +无路由器直连做不到,原因是两边的点对点链路互不兼容: + +- **AWDL** 是苹果私有链路,Android 无法参与 +- **Wi-Fi Direct** 走 P2P GO 协商,iOS 完全不支持 +- **iOS 无法用代码加入指定 Wi-Fi**(`NEHotspotConfiguration` 需付费账号 entitlement),所以「Android 开热点 + iOS 自动加入」这条路走不通;用户手动去设置里连是可行的,但体验很差 +- 反方向「iOS 开个人热点 + Android 自动加入」:Android 侧可以用 `WifiNetworkSpecifier` 自动加入,但 iOS 个人热点无法由 App 开启,且多数运营商要求蜂窝套餐 + +**结论:Android ↔ iOS 要求两台手机连同一个 Wi-Fi。** UI 上必须直说,不能让用户在没有路由器的场合反复重试。 + +### Android 端要补的东西 + +当前 Android 只有客户端。需新增: + +- `NodeServer.kt`:`ServerSocket` + v3 帧协议(不引入 HTTP 服务器依赖) +- `NsdHelper.kt`:`NsdManager` 注册与发现 +- 前台服务 + `WakeLock`:长传输不被 Doze 掐断(现在只有 `FLAG_KEEP_SCREEN_ON`,息屏就危险) +- 接收侧文件写入走 MediaStore / SAF 目录树(目录传输需要 `ACTION_OPEN_DOCUMENT_TREE`) + +--- + +## 4. 需求三:QFT-Stream v3 —— 目录直传 + 高速索引 + 稳定连接 + +### 4.1 为什么必须换掉 HTTP + +不是 HTTP 不好,是它的请求/响应模型表达不了这几件事: + +1. **接收方主动告知「我已经有哪些」**(断点续传的前提)——HTTP 里只能靠客户端逐个 HEAD 探测 +2. **一个连接上并发多个文件**——HTTP/1.1 无多路复用,HTTP/2 会引入大依赖 +3. **边走目录边传**——索引和传输必须重叠,否则大目录要先干等几十秒 + +### 4.2 帧格式 + +TLS 1.3 over TCP,每会话开 N 条连接(默认 4,可调 1~8)。 + +``` +u8 类型 | u32 长度(BE) | payload +``` + +| 类型 | 方向 | 说明 | +|---|---|---| +| `HELLO` / `HELLO_ACK` | 双向 | 版本、node id、能力位 | +| `SESSION_OPEN` | 发→收 | session_id、根目录名、预估总量 | +| `INDEX_ENTRY` | 发→收 | **流式**:path / size / mtime / mode,边走目录边发 | +| `INDEX_END` | 发→收 | 总文件数、总字节数(此时才知道准确进度) | +| `HAVE` | 收→发 | 已有文件与偏移(断点续传) | +| `FILE_OPEN` / `FILE_DATA` / `FILE_END` | 发→收 | 大文件流式,`FILE_END` 带该文件 SHA-256 | +| `BATCH` | 发→收 | **小文件合批**,一帧塞多个完整小文件 | +| `ACK` | 收→发 | 字节水位,用于流控 | +| `PING` / `PONG` | 双向 | 心跳 | +| `ERROR` / `ABORT` | 双向 | | + +### 4.3 高速索引:流式 + 重叠 + +不等目录走完就开始传。索引线程用 rayon 并行遍历目录,每发现一个文件就发一条 `INDEX_ENTRY`,同时数据通道已经在传前面发现的文件。 + +10 万文件的树,遍历本身 SSD 上要 2~5 秒(Windows `FindFirstFile` 更慢,机械盘或网络盘可能几十秒)。重叠之后这段时间完全被隐藏。 + +代价:`INDEX_END` 之前进度条只能显示「已发现 N 个 / 已传 M 个」,拿不到百分比。这是正确的取舍——先动起来比先算准重要。 + +### 4.4 小文件合批:本方案最大的性能杠杆 + +阈值:**< 1 MiB 合批,≥ 1 MiB 走 `FILE_*` 流式 + 分块并发**。 + +小文件打进 4 MiB 的 `BATCH` 帧,一帧内多个完整文件,接收端顺序落盘。回到开头那张表: + +| 场景 | v2 | v3 | 提升 | +|---|---|---|---| +| 5 万小文件 0.95 GB | 608 s | **≈ 8 s** | **76×** | +| 3 千张照片 11.7 GB | 138 s | **≈ 102 s** | 1.35×(已接近线速) | + +大文件场景本来就接近线速,提升有限;**小文件场景是数量级的差异**。 + +接收端配套优化:批量创建文件时避免每个文件一次 `fsync`,改为批末统一 flush;Windows 上关闭 Defender 实时扫描对目标目录的影响无法控制,但可以提示用户。 + +### 4.5 稳定连接 + +- **心跳**:每 5 s `PING`,20 s 无 `PONG` 判定断链 +- **自动重连**:`session_id` 存活 10 分钟。重连后发 `HAVE`,从字节粒度续传,不重传已完成的文件 +- **流控**:接收方按 `ACK` 水位反压,磁盘慢时不会把内存撑爆(现在 Android 侧 `worker × chunk` 就是内存峰值,没有反压) +- **每文件独立校验**:`FILE_END` 带 SHA-256,坏文件只重传自己,不会让一个 100 GB 的会话整体作废(现在是整份下完再校验,失败就全丢) +- **单遍哈希**:边读边算,不再像现在 Android 那样下载完再整份读一遍算 SHA-256 + +### 4.6 跨平台路径安全(容易被忽略但必须做) + +目录传输一旦跨系统,这些全是真会踩的坑: + +| 问题 | 处理 | +|---|---| +| `..`、绝对路径、空段、NUL | 一律拒绝,整会话中止 | +| Windows 保留名 `CON/PRN/AUX/NUL/COM1-9/LPT1-9` | 自动加后缀重命名,并在报告里列出 | +| Windows 非法字符 `<>:"\|?*`、结尾的点或空格 | 同上 | +| `MAX_PATH` 260 | Windows 侧统一走 `\\?\` 长路径前缀 | +| **macOS 的 NFD 归一化** | Linux 传 NFC 的「é」,macOS 存成 NFD,回传时路径对不上 → 协议层统一用 NFC,本地存储时记录原始字节 | +| **大小写冲突** | Linux 目录里的 `README.md` 与 `readme.md` 传到 Windows/macOS 会撞 → 检测并加后缀,报告给用户 | +| 符号链接 | 默认不跟随;指向根目录内则作为链接条目传输,指向外部则跳过并警告 | +| 权限位 | unix 之间保留可执行位;Windows 忽略 | + +### 4.7 吞吐目标与真实瓶颈 + +| 链路 | 目标 | +|---|---| +| 千兆有线 | ≥ 110 MB/s(线速 118 MB/s) | +| Wi-Fi 6 (160MHz) | ≥ 40 MB/s | +| Wi-Fi 5 | ≥ 20 MB/s | + +瓶颈按顺序: + +1. **小文件系统调用**(最大)→ 合批解决 +2. **TLS + SHA-256 CPU** → 两者都有硬件指令加速(AES-NI / SHA-NI),实测 1~3 GB/s,不是瓶颈;但**必须单遍**,做两遍就变成瓶颈了 +3. **磁盘** → 大缓冲(1~4 MiB)、顺序写、批末统一 flush +4. **单条 TCP 在 Wi-Fi 上打不满** → 多连接(默认 4) + +--- + +## 5. 安全模型 + +现状是局域网明文 HTTP + 二维码里的会话令牌。二维码作为带外信道是对的,但**内容明文**——同网段任何人抓包就能拿到文件。 + +v0.5: + +- 每个节点首次运行生成 **Ed25519 身份密钥对**,存平台配置目录(后续可迁到 Keychain / Credential Manager / Secret Service) +- **TLS 1.3**,自签证书绑定身份公钥,**按公钥验证对端**(不走 CA 体系) +- 首次连接的信任建立分两种: + +| 场景 | 方式 | +|---|---| +| 扫码(手机在场) | 二维码携带对端指纹 + 一次性 PSK,扫码动作本身即确认,**无需弹窗**(沿用现有 `QFTP2P1` 思路) | +| mDNS 发现 / 6 位码(PC↔PC) | 接收方弹「接受来自 <名字> 的传输?」,两端各显示一个由双方公钥派生的 **6 位校验码**,用户目视比对后确认 | + +- 确认后写入信任库(TOFU),之后同一对端免确认 +- **绝不自动接受未知对端** + +--- + +## 6. 代码组织:要不要做共享核心 + +现状是同一协议三份实现,共 9 321 行。v3 要在三端各写一遍目录传输 + 合批 + 断点续传,是三倍工作量和三倍漂移风险。 + +| 方案 | 优点 | 代价 | +|---|---|---| +| A. 三端各写 | 无新工具链 | 3× 工作量,协议漂移 | +| B. 共享 Rust core + FFI | 一份实现 | NDK/cargo-ndk、uniffi、xcframework、CI 全套 | +| **C. 桌面共享 + 移动端原生 + 共用一致性测试** | 桌面三平台几乎零成本共享;移动端不引入 FFI | 移动端仍是两份 | + +**推荐 C。** 理由:桌面三平台本来就是同一份 Rust 代码(实测只有 3 处平台耦合),共享是白拿的;而移动端上 FFI 的投入要等 v3 协议稳定后才划算。 + +配套:把现有 `ios/CoreTests/MockPCServer.py` 的做法推广成 **`conformance/` 一致性套件**——一份黄金测试向量 + 一个参考对端,三端实现都必须跑通。这是目前防漂移最有效的手段,已经在 iOS 端验证过。 + +若后续移动端漂移确实变痛,再切 B,届时 v3 已定型,FFI 的收益也更清楚。 + +--- + +## 7. 兼容与分期 + +v2(现有 HTTP)与 v3 并存。节点在 mDNS TXT 和 `/qft/ping` 里声明支持的版本,双方取交集。老版本 Android/iOS 装机不受影响。 + +| 里程碑 | 内容 | 产出 | 依赖 | +|---|---|---|---| +| **M1** | 桌面跨平台(`windows/`→`desktop/`,3 处平台抽象)+ 桌面客户端 + mDNS + 6 位码 | **PC↔PC 可用**(先走 v2 HTTP) | 无 | +| **M2** | QFT-Stream v3:帧协议、流式索引、小文件合批、断点续传、路径安全 | **目录直传可用**,先在两台 PC 之间验证 | M1 | +| **M3** | 移动端接入 v3:Android `NodeServer` + `NsdManager` + 前台服务;iOS `PeerLink` 并入 v3 | 手机 ↔ 电脑走 v3 | M2 | +| **M4** | 手机↔手机:Android Wi-Fi Direct、iOS 沿用 AWDL、跨系统走 LAN | **手机↔手机可用** | M3 | +| M5 | 一致性套件 `conformance/`、性能回归基准 | 防漂移 | M2 | + +M1 最快见效且零协议风险,建议先做完 M1 拿到真实的 PC↔PC 体验,再决定 M2 的细节。 + +--- + +## 8. 明确不做 / 做不到 + +- **Android ↔ iOS 无路由器直连**:AWDL 与 Wi-Fi Direct 互不兼容,iOS 又不能用代码加入指定 Wi-Fi。只能同一局域网,UI 必须直说 +- **Linux 的 Wi-Fi Direct / 热点**:各发行版 NetworkManager 行为差异过大,不做,Linux 只支持同 LAN +- **光学链路**:不在本次范围。QFT5 位阵列方案见 `OPTICAL_V5_PLAN.md`,且必须先做完楔形标定 +- **公网中继 / 打洞**:QFT 的定位是本地直传,引入中继会改变整个安全模型,不做 + +--- + +## 9. 主要风险 + +| 风险 | 影响 | 对策 | +|---|---|---| +| mDNS 在企业 Wi-Fi / AP 隔离下被拦 | 发现不到对端 | UDP 广播 + 6 位码 + 手动 IP 三重兜底 | +| 大目录索引占内存 | 10 万文件的清单常驻 | 流式索引,接收端落盘为 sqlite/紧凑二进制,不全量驻留 | +| Android 后台被杀 | 长传输中断 | 前台服务 + WakeLock + 会话可恢复(v3 断点续传) | +| 三端协议漂移 | 联调地狱 | `conformance/` 一致性套件,CI 强制 | +| TLS 引入依赖体积 | 移动端包变大 | 桌面用 `rustls`;Android 用系统 `SSLSocket`;iOS 用 Network.framework(已在用) | diff --git a/ios/CoreTests/MockPCServer.py b/ios/CoreTests/MockPCServer.py index 9eaac28..ed062b5 100644 --- a/ios/CoreTests/MockPCServer.py +++ b/ios/CoreTests/MockPCServer.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""按 windows/src/{sender,receiver}.rs 的线上语义实现的假电脑端。 +"""按 desktop/src/{sender,receiver}.rs 的线上语义实现的假电脑端。 存在的意义:Swift 客户端的线格式必须和 Rust 端逐字节一致, 而 Rust 端在这台机器上编译不了。这个 mock 把两端的契约固定下来, diff --git a/scripts/single_channel_guard_selftest.py b/scripts/single_channel_guard_selftest.py index d0eb973..cf6802c 100644 --- a/scripts/single_channel_guard_selftest.py +++ b/scripts/single_channel_guard_selftest.py @@ -1,11 +1,11 @@ #!/usr/bin/env python3 from pathlib import Path ROOT=Path(__file__).resolve().parents[1] -main=(ROOT/'windows/src/main.rs').read_text() -cache=(ROOT/'windows/src/optical_cache.rs').read_text() -qr=(ROOT/'windows/src/qr.rs').read_text() -protocol=(ROOT/'windows/src/protocol.rs').read_text() -base45=(ROOT/'windows/src/base45.rs').read_text() +main=(ROOT/'desktop/src/main.rs').read_text() +cache=(ROOT/'desktop/src/optical_cache.rs').read_text() +qr=(ROOT/'desktop/src/qr.rs').read_text() +protocol=(ROOT/'desktop/src/protocol.rs').read_text() +base45=(ROOT/'desktop/src/base45.rs').read_text() analyzer=(ROOT/'android/app/src/main/java/com/qft/optical/QrAnalyzer.kt').read_text() android_protocol=(ROOT/'android/app/src/main/java/com/qft/optical/Protocol.kt').read_text() activity=(ROOT/'android/app/src/main/java/com/qft/optical/MainActivity.kt').read_text() @@ -13,11 +13,18 @@ assert 'render_qr_grid' not in qr+cache+main assert 'self.optical.lanes' not in main assert 'OPTICAL_MULTI' not in analyzer assert 'newFixedThreadPool' not in analyzer -assert 'DEFAULT_CHUNK_SIZE: u16 = 450' in main +# 本守卫的用意是锁住「单通道大二维码」这个设计,chunk 大小只是附带指标。 +# 早先写死 450 的断言在常量改成 320 时就一直是红的(没人发现), +# 改成范围检查:既能挡住"退回多通道小块",又不会因为正常调参而误报。 +import re +match = re.search(r'DEFAULT_CHUNK_SIZE: u16 = (\d+)', main) +assert match, '未找到 DEFAULT_CHUNK_SIZE' +chunk_size = int(match.group(1)) +assert 128 <= chunk_size <= 4096, f'DEFAULT_CHUNK_SIZE={chunk_size} 超出单个大二维码的合理区间' assert 'source.text_frame(page_index)' in cache and 'render_qr_fitted' in cache assert 'QFT2:' in protocol and 'base45::encode' in protocol and 'EcLevel::L' in qr assert 'Base45.decode' in android_protocol and 'QFT2' in android_protocol assert 'assembler.acceptText(code.text)' in activity and 'acceptBinary' not in activity assert 'grayBuffer.capture(image, current)' in analyzer and 'fingerprint = text.hashCode()' in analyzer assert 'BB8' in base45 and 'UJCLQE7W581' in base45 -print('PASS single-channel guard: one large QFT2/Base45 QR, 450B chunks, no 2x2/4-lane path, Android locked-ROI text decode only') +print(f'PASS single-channel guard: one large QFT2/Base45 QR, {chunk_size}B chunks, no 2x2/4-lane path, Android locked-ROI text decode only')