feat(desktop): 跨平台桌面端 + 电脑↔电脑互传(v0.5.0-m1)

对应 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)
This commit is contained in:
zhy200308
2026-08-11 16:36:33 +08:00
parent a960ad91d8
commit 376ffba96e
26 changed files with 2139 additions and 44 deletions
+575
View File
@@ -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<String>, token: impl Into<String>, device_name: impl Into<String>) -> Self {
Self {
base_url: base_url.into(),
token: token.into(),
device_name: device_name.into(),
}
}
fn address(&self) -> Result<SocketAddr> {
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<serde_json::Value> {
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<String> {
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<String> {
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<UploadSession> {
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<String> {
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<u64>,
mut on_progress: impl FnMut(Progress),
) -> Result<PathBuf> {
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::<u64>().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<String, String>,
reader: BufReader<TcpStream>,
}
impl HttpResponse {
/// 读完整个响应体。服务端总是发 `Connection: close`,
/// 所以按 Content-Length 读,没有该头则读到 EOF。
fn read_body(&mut self) -> Result<Vec<u8>> {
let mut body = Vec::new();
match self.headers.get("content-length").and_then(|v| v.parse::<u64>().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<HttpResponse> {
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<u8> = (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::<ReceiverEvent>();
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);
}
}