22 Commits

Author SHA1 Message Date
zhy200308 99be46acf7 release: v0.4.8 跨端 PC 互传封版;修复发送端进度直到结束才更新
实测 1.01 GB / 23.11 MB/s 传输成功,但发送端进度条全程 0%、
最后才跳到 100%,接收端却是实时的。两处原因,都已修复。

1. 请求体一次性写出
   16 MiB 的分块用单次 write_all 送出,中途没有任何可上报的点。
   改为 256 KiB 一片:足够小让进度看起来连续,又足够大不拖慢吞吐。
   put_chunk 逐片累加共享计数;失败重试时把本次尝试已计的字节扣回去,
   否则重试会让进度虚高甚至越过 100%。

2. on_progress 只在所有 worker 结束后调用一次
   主线程改为在 worker 运行期间轮询上报(40 ms 一次,对 UI 足够,
   代价可忽略),而不是等 thread::scope 返回。

测试拆成两层
- 确定性单测 body_progress_is_reported_incrementally:5 片请求体必须
  上报 5 次、总量吻合。回环速度太快时集成测试采样不到中间进度,
  只有这一层能稳定拦住回归
- 集成测试改为断言稳健性质:进度单调不减、且不超过文件总长
  (后者正是重试重复计数会破坏的)
- 配套的 mock 服务端按 Content-Length 精确读取。此前用 read_to_end
  会一直等客户端关闭写端,而客户端在等响应,两边互等直接死锁

封版
- 版本 0.5.0-m1 → 0.4.8,接续既有编号
- 界面与 README 里残留的「6 位配对码」文案更新为连接码

本版可用范围:mac / win / linux 桌面端互传,连接码内含地址,
不要求同一网段,只要 IP 层可路由到达即可。
2026-08-11 19:37:21 +08:00
zhy200308 375ae8a956 fix(desktop): 选择文件不再让程序崩溃;新增拖拽;macOS 产出 .app
macOS 上点「选择文件」直接退出:

  panicked at objc2-app-kit-0.3.2/.../NSOpenPanel.rs:127:
  unexpected NULL returned from +[NSOpenPanel openPanel]

rfd 在 openPanel 返回 NULL 时直接 panic,整个进程随之结束——用户只是
想选个文件,窗口就没了。三层处理,从"不该崩"到"不该发生":

1. 不该崩:pick_files/pick_folder/pick_file 全部包进 catch_unwind。
   文件对话框失败是可以恢复的情况,不该终止程序;失败时在状态栏说明
   并提示改用拖拽。

2. 提供不依赖对话框的路径:支持把文件直接拖进窗口。拖拽不经过
   NSOpenPanel,对话框失效时照样能用,而且本来就是桌面端更顺手的交互。
   悬停时给出"松手即可加入待发送列表"的提示。

3. 消除诱因:package.sh 在 macOS 上额外产出 QFT.app。AppKit 的若干行为
   依赖应用被正确注册为 GUI 程序,直接跑裸二进制正是这个 NULL 的高发场景。
   Info.plist 含 NSHighResolutionCapable,Retina 下不会被拉伸。

顺带修复 package.sh 的校验和步骤:此前 `sha256sum ./*` 会把 .app 目录
一起喂进去并报错,改为 find -type f 只处理普通文件。

验证:cargo test 35/35;package.sh 完整跑通并实际 open 了生成的 .app,
确认能启动存活;plutil 校验 Info.plist 通过。
2026-08-11 18:56:17 +08:00
zhy200308 bcadcf0b53 fix(firewall): 规则必须用 profile=any,否则在公用网络下完全不生效
实测发现的真 bug。用户机器上的规则列表:

  qft-windows  Allow Inbound Public           (旧版,能用)
  QFT Desktop  Allow Inbound Domain, Private  (新加,不生效)

Windows 对没见过的 Wi-Fi 默认归类为「公用网络」。规则只覆盖
Private,Domain 时,Get-NetFirewallRule 照样显示 Enabled: True,
但对当前网络根本不适用,连接依旧被拦——这种「配置看起来是对的却没有
效果」的失败最难排查。旧版之所以一直能用,是因为当初点系统安全警报的
「允许」时,Windows 按当时的 Public 配置自动建了规则。

改动
- grant() 生成的 netsh 规则改为 profile=any
- status() 不再只看「有没有同名规则」,还要求它是 any profile,
  否则同样报 Missing。避免出现「检测说已放行、实际仍被拦」
- README 补充排查步骤:先看 NetworkCategory 与规则的 Profile 两列,
  以及 Block 规则优先于 Allow 这个常见坑

关于收窄 profile 的取舍:限定到 private 并不能带来实际安全收益。
QFT 的入站真正靠的是连接码里的秘密加失败计数,没有秘密的连接一律被拒;
而按 profile 收窄只会在最常见的家用/公共 Wi-Fi 场景下静默失效。

验证:cargo test 35/35。Windows 分支仍无法在本机执行,
netsh 与 UAC 那条路径需要在 Windows 上实测。
2026-08-11 18:48:41 +08:00
zhy200308 0f0dbaef47 fix(desktop): 防火墙提权改为手动触发;构建前检测占用;清理警告
三个问题一起处理。

1. 提权改为手动
上一版会在点「启动接收」时自动弹 UAC。实际用下来太侵入——多数人
只是想收个文件,却先被要求管理员授权。现在:
- 检测保持自动,但**只读**,无任何副作用
- 提权只在用户点「放行防火墙(需要管理员授权)」时发生
- 按钮无条件保留,不再只在"检测到被拦"时出现:检测可能不准,
  而用户遇到「对方连不上」时需要有地方可点
- 同时移除了拒绝标记的持久化——提权已不自动发生,无需记忆

2. Windows 构建报 os error 5
  error: failed to remove file `...\target\release\qft-desktop.exe`
  Caused by: 拒绝访问。 (os error 5)
原因是 QFT 窗口还开着,运行中的 exe 锁住了产物文件,而 cargo 的报错
完全看不出这一层。VERIFY_WINDOWS_HOST.ps1 现在会在构建前检测
qft-desktop 进程,列出 PID 并询问是否结束;README 也补了说明
(含 Defender 扫描导致的偶发同类报错)。

3. 构建警告 15 → 5
长期堆积的警告会训练人忽略所有警告,所以逐条处理:
- 真实问题:if 条件多余的括号,已修
- 为后续里程碑准备但尚未接线的 API(client::ping、download_file、
  platform::direct_ap_support/ensure_dir),加 #[allow(dead_code)]
  并注明将在哪个阶段使用
- 仅特定平台构造的项(firewall::RULE_NAME 只用于 Windows,
  FirewallStatus::Unsupported 只在 Linux 返回),改用
  #[cfg_attr(not(...), allow(dead_code))],避免无条件放行
剩余 5 个均为本次改动之前既有(cache_mib、v/transport、security、
path),不属本次范围,未改动。

验证:cargo test 35/35,release 构建 5 个警告且全部是既有的。
2026-08-11 18:28:43 +08:00
zhy200308 bdb822233f feat(desktop): 启动接收时自动检测并申请防火墙放行
上一次实测卡在「连接码解析正确但连不上」,根因是对端 Windows 防火墙
拦截入站,而用户几乎不可能自己联想到这一层。新增 firewall.rs,
在点「启动接收」时自动检测,缺规则就申请一次放行。

三条设计约束
1. 只在确实缺规则时申请。每次启动都弹 UAC 属于骚扰。
2. 被拒绝就记住。写标记文件到配置目录,之后只在界面留一个手动按钮,
   不再自动弹窗;用户点「放行防火墙」会清除标记重新申请。
3. 规则尽量窄。只放行本程序、只放行专用/域网络,不碰公用网络,
   更不整体关闭防火墙。

提权全部交给操作系统的标准机制(Windows UAC、macOS 授权对话框),
程序不接触也不存储任何凭据。

各平台
- Windows:netsh 查规则;添加时把命令写进临时批处理再用
  Start-Process -Verb RunAs 提权执行。不把参数塞进 PowerShell 的
  -ArgumentList —— 程序路径含空格时会被二次分词,引号层层嵌套极易出错,
  批处理里的引号由我们自己写死,不再被重新解析
- macOS:先查 socketfilterfw 全局状态,防火墙没开就直接判定无需处理;
  否则查本程序是否被拦,需要时用 osascript 的管理员授权添加。
  路径含引号或反斜杠时拒绝拼接命令,改为提示手动操作
- Linux:只检测与给出 ufw / firewalld 的命令,不自动改规则。
  各发行版防火墙前端差异过大,自动修改风险高于收益

界面
接收页在检测到可能被拦时显示橙色提示,附「放行防火墙」与
「复制手动放行命令」两个按钮。已放行或防火墙未开启时不显示任何东西。

验证:cargo test 35/35。防火墙相关 3 项均为只读,不改动任何系统设置:
状态查询不 panic 且分类正确、手动说明包含可操作信息、拒绝标记可持久化
往返。本机实测返回 Allowed(防火墙未开启),符合预期。

未验证:Windows 与 Linux 分支在这台 Mac 上无法执行,
netsh/UAC 那条路径需要在 Windows 上实测。
2026-08-11 18:07:53 +08:00
zhy200308 3e4d5861aa fix(desktop): 连接失败给出可执行的排查方向,并分离配对与传输状态
实测中出现「连接码解析正确但连不上」。诊断结果不是代码问题:两台机器
同在 192.168.8.0/24,ARP 能解析对方 MAC(二层通),但 ICMP 100% 丢包、
TCP 39393 连接超时——典型的对端主机丢包,即 Windows 防火墙拦截入站。

顺带暴露的连带影响:二进制从 qft-windows.exe 改名为 qft-desktop.exe 后,
此前给旧名字放行的防火墙规则对新程序不生效,用户不会想到这一层。
README 已补充放行步骤与排查顺序。

代码侧的三个真实缺陷

1. 连接失败只说「失败」,等于什么都没说。现按 io::ErrorKind 分类:
   - TimedOut  → 包发出去没回应:防火墙 / AP 客户端隔离 / 对方已关闭
   - ConnectionRefused → 主机在线但端口没人监听:对方没点「启动接收」
   - Host/NetworkUnreachable → 本机没有到该地址的路由
   三者成因完全不同,给的建议也必须不同。

2. 配对超时从 10 秒缩到 4 秒。配对只是一次极小的请求,拖到 10 秒
   只会让用户以为程序卡死。

3. 配对阶段就显示「正在发送 0%」。此前用 busy 兼作「正在传输」,
   导致刚点连接就出现发送进度条。新增独立的 transferring 标志,
   进度块只在真正推送文件时出现;配对期间改为显示 spinner 与
   「正在建立连接…最多等 4 秒」。

验证:cargo test 32/32。新增两项针对错误分类的用例——
用 RFC 5737 文档网段 192.0.2.1 触发超时路径,用刚释放的本地端口
触发拒绝路径,分别断言提示里包含对应的排查方向。
2026-08-11 17:39:53 +08:00
zhy200308 84643bff5e feat(desktop): PC↔PC 改用连接码,一串搞定,不再单独输 IP
此前发送方要分别念/输三样东西:IP、端口、6 位配对码。现在合成一串
可口述的连接码,**地址就编在码里**,所以拿到码即可直连——不需要广播、
不需要在同一网段,只要 IP 层路由可达即可(同一路由器下的不同 VLAN /
网段正属于这种情况)。

新增 connect_code.rs
- 编码:version(3) | kind(3) | 默认端口位 | 地址 | [端口] | 24bit 秘密 | CRC-8
- 按网段压缩地址:192.168.a.b 只需 2 字节,10./172.16-31. 三字节,
  其余四字节,IPv6 十六字节
- Crockford Base32(去掉易混的 I/L/O/U),分组显示
- 典型 192.168.a.b:39393 → **12 个字符**,如 4849-3WT1-3ZS0
- 输入容错:大小写、分隔符、空格随意;I/L 归一为 1、O 归一为 0

接收侧
- 6 位配对码 → 3 字节秘密;UI 为**每个网卡各生成一个连接码**,
  对方在哪个网段就用哪一串(虚拟网卡排后面)
- 新增 pairing::local_ipv4_addresses(),按「最可能被对方看到」排序

发送侧
- 三个输入框(设备列表 / 手动 IP / 配对码)合并为**一个连接码输入框**
- 边打边校验:CRC 在连接之前就能发现输错,并实时显示「将连接 http://x.x.x.x:port」
- 广播搜索降级为可选的折叠项——同网段免输码是锦上添花,不再是主路径

一个被测试抓出来的真问题
最初单字符输错的拦截率只有 96%。原因是 12 个 Base32 字符携带 60 bit
而实际只用 56 bit,末尾 4 个填充位被解码器直接丢弃,改动最后一个字符
有 1/16 概率解出完全相同的字节,CRC 根本没机会发现。加上填充位必须为 0
的校验后拦截率 >99%。

必须说清的边界
连接码解决的是「找不到对方」和「输入太繁琐」,不能凭空制造可达性。
若两台机器在 IP 层互不可达(Wi-Fi 客户端隔离、各自在不同物理网络),
任何客户端侧协议都无法建立连接,只能换链路或引入第三方中转——
后者与 QFT「不经过外网」的定位冲突,本版不做。

验证:cargo test 30/30,含连接码往返(全部地址类型)、容错输入、
单字符输错拦截率统计、以及走完整连接码链路的端到端传输
(编码 → 解码 → 换令牌 → 9MB 并发上传 → SHA-256 比对)。
2026-08-11 17:29:00 +08:00
zhy200308 d2669fb2e4 fix(desktop): 修复 macOS/Linux 上的中文豆腐块与 HiDPI 缩放
macOS 首次构建暴露的两个独立问题。

中文全是豆腐块
- is_ttf_file 只按 `.ttf` 扩展名筛选,而 macOS 的中文字体清一色是
  .ttc 字体集合(PingFang/Hiragino/STHeiti),Linux 的 NotoSansCJK
  与新版 Windows 的 msyh 也是 .ttc —— 全部被拒。改为按文件魔数识别
  (ttcf / OTTO / 0x00010000 / true),同时支持 ttf、otf、ttc
- 候选路径此前只有三条 Windows 的,非 Windows 平台根本没有兜底。
  新增 platform::system_font_candidates(),三平台各自列出系统中文字体
- 报错信息里的 windows/assets 路径跟进为 desktop/assets

HiDPI 下整个界面缩成一半
- set_pixels_per_point(1.0) 写死了缩放。Retina 屏 ppp=2.0,
  强制 1.0 会让所有控件和文字按一半尺寸渲染,界面挤在窗口左上角。
  改为交给 eframe 从系统取
- 原先写死 1.0 应是为了让二维码纹理与物理像素 1:1。改用
  snap_to_physical() 在绘制时把尺寸吸附到物理像素整数上达到同样目的:
  NEAREST 采样下若落在半个物理像素,相邻模块占的像素数会一宽一窄,
  边缘产生锯齿,反而更难被手机解码

顺带
- 设备名去掉 mDNS 的 .local/.lan 后缀。这个名字会出现在对方的设备
  列表里,zdeMacBook-Air.local 既长又没有信息量

验证(macOS,Retina 2880x1864)
- cargo test 21/21,其中新增 4 项:
  * 系统字体候选中存在的文件必须被 is_font_file 接受
  * 本平台至少能找到一个中文字体
  * **把找到的字体真正装进 egui 并渲染 '中'**,断言字形宽度非零且
    宽于 'A' —— 只检查文件存在是不够的,.ttc 解析失败时宽度会是 0
  * snap_to_physical 在 ppp=1/1.5/2/3 下都落在整数物理像素上
- release 构建后实际启动截图确认:中文正常显示(Hiragino Sans GB),
  界面按 Retina 正确缩放
2026-08-11 16:51:50 +08:00
zhy200308 92237ff76f fix(package): package.sh 跟进 desktop/ 改名,并在 keg-only 安装下自动找到 cargo
上一个提交把 windows/ 改成 desktop/ 时漏掉了 package.sh —— 当时的
grep 只覆盖 .md/.py/.ps1/.toml/.yml,没有扫 .sh,导致打包脚本仍然
cd windows 并寻找 qft-windows 二进制。

- 路径与二进制名跟进 desktop/ 与 qft-desktop
- cargo 检测增加兜底:brew 的 rustup 是 keg-only,
  /opt/homebrew/opt/rustup/bin 不会自动进 PATH,此前会出现
  "明明装了工具链却报 cargo 未找到"。现在先在常见位置探一次,
  仍找不到时给出可直接执行的修复命令而不是一句干巴巴的报错
- .gitignore 忽略 /dist 打包产物(release 二进制 14 MB,不应入库)

已在 macOS 上完整跑通 ./package.sh:cargo test 17/17 通过、
release 构建成功、产出 QFT-Rust-0.5.0-m1-<时间戳>-darwin 目录与
tar.gz,内含 14 MB 的 Mach-O arm64 可执行文件与 SHA256SUMS.txt。
2026-08-11 16:43:55 +08:00
zhy200308 376ffba96e 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)
2026-08-11 16:36:33 +08:00
zhy a960ad91d8 合并 0.4.7 双向并发传输封版
# Conflicts:
#	README.md
#	android/app/src/main/java/com/qft/optical/DownloadClient.kt
#	android/app/src/main/java/com/qft/optical/UploadClient.kt
#	docs/PROTOCOL.md
#	windows/src/sender.rs
2026-08-11 14:27:30 +08:00
zhy 20ac4dc6c7 发布 0.4.7 双向并发传输封版 2026-08-11 13:49:27 +08:00
zhy200308 cb92397300 修正为仅打包Rust桌面端 2026-08-11 11:48:09 +08:00
zhy200308 dffee5365d Merge remote-tracking branch 'origin/main' 2026-08-11 11:31:44 +08:00
zhy200308 a4edf734b6 优化大文件稳定并发传输与打包流程 2026-08-11 11:27:40 +08:00
zhy e326611c82 发布 0.4.6 封版 2026-08-11 10:53:59 +08:00
kmcc f260ff4266 Merge pull request 'New test' (#1) from new-test into main
Reviewed-on: https://git.xskjhy.top/kmcc/QFT/pulls/1
2026-08-11 10:44:48 +08:00
zhy 34b8fdf050 合并直传接收与文件选择优化 2026-08-11 10:21:45 +08:00
zhy e9e51a4941 修复直传接收并优化文件选择提示 2026-08-11 10:21:37 +08:00
zhy200308 b444a39a63 修复传输问题 2026-08-11 09:44:26 +08:00
zhy200308 4d77ba6c91 feat: 新增 iPhone 客户端,含隔空投送式点对点互传
三条链路:
- 电脑 → iPhone:扫 QFTSEND2 码下载,流式落盘 + 增量 SHA-256,
  支持 Range 断点续传
- iPhone → 电脑:扫 QFTPAIR2 码后 init/chunk/finish 并行分块上传
- iPhone ↔ iPhone:QFTP2P1 扫码握手,Network.framework 开启
  includePeerToPeer(AirDrop 同款 BLE 发现 + AWDL 点对点 Wi-Fi),
  两台设备不需要连同一个 Wi-Fi,也不需要路由器

P2P 用 TLS-PSK 握手:32 字节预共享密钥由发送端随机生成并写进二维码,
扫码这个动作本身完成带外密钥交换与双向认证,无需证书体系与配对弹窗。
未扫到码的第三方连上来过不了握手。

核心层刻意不 import UIKit,可直接以 macOS 为目标编译测试,
不需要 Xcode 也不需要模拟器,已接入主自检套件,72 项全部通过:
- 端点白名单 11 种拒绝用例(域名、公网、172.32 边界、
  非规范八位组、IPv6、带凭据/路径/query)
- CoreTests/MockPCServer.py 严格复刻 receiver.rs / sender.rs 的线上语义
  (路径、header 名、JSON 字段、Range 行为、chunk 长度校验),
  构成 Swift 与 Rust 两端的线格式契约测试,任一端改协议即会失败
- 真实 TLS-PSK 握手下的 P2P 端到端传输,含错误密钥必须被拒

iOS 平台限制(已在 ios/README.md 说明):
NEHotspotConfiguration 需要付费账号 entitlement,故不实现 Direct AP
流程,与电脑互传要求同一局域网;AWDL 是苹果私有链路,Windows 无法参与。
上传块固定 4 MiB 而非 Android 的 4/8/16 MiB,因为 iOS 上
worker 数 × 块大小即内存峰值。

未验证部分:本机只有 Command Line Tools,无 Xcode 与 iOS SDK,
UI 层(SwiftUI/UIKit/AVFoundation)未经编译;.xcodeproj 已通过
plutil 解析与引用完整性校验(42 个对象无悬空引用),
但未在 Xcode 中实际打开过。
2026-08-11 09:08:37 +08:00
zhy200308 ea7b678b37 feat: 新增 QFT5 光学链路方案与分辨率楔形标定工具
当前光学链路传 3MB 需要 1 小时,瓶颈不是解码慢而是无反馈重传浪费:
按 320B 分片、45FPS 反推,每轮约捕获 44%,收齐需 16.5 轮,
约 86% 的信道被已收到的重复分片占用。

docs/OPTICAL_V5_PLAN.md 给出完整改造方案:
- 条带级喷泉码消除重传浪费,撕裂只损失 1/12 而非整帧
- MANIFEST 每 32~64 帧插播,消除平均 109 秒的启动空转
- 相机帧率三级锁定 + 手动短曝光(3px/模块下 33ms 自动曝光
  会产生 8.7px 运动模糊,等于抹掉近 3 个模块,必然解不出)
- 陀螺仪前馈跟踪四角单应,解决手持抖动丢锁
- 位阵列替代 QR,突破 v40 的 177 模块上限

scripts/wedge_*.py 是配套标定工具。方案里所有吞吐数字都建立在
「px/模块 的真实下限」这一未实测假设上,而合成实验显示该值仅因
对焦质量不同就能在 3.1~5.7 之间摆动,必须先实测:
- wedge_gen.py     生成 7 档 pitch 的伪随机标定图 + 1:1 全屏查看器
- wedge_analyze.py 照片 → 实测 px/模块 → 对比度 → 误码率曲线
- wedge_selftest.py 合成相机模型端到端自检,无需真实硬件

标定同时暴露了方案的一个缺口:条带只有 CRC 没有内码,1750B 条带
约 14000 bit,1 bit 错即整条报废,要求原始 BER 低于 1e-5。
故需改为「内码纠错 + 外层喷泉码纠删」的级联结构,已记入文档。
2026-08-11 09:08:04 +08:00
73 changed files with 10234 additions and 252 deletions
+11
View File
@@ -1,6 +1,8 @@
# Rust
/target
**/target
windows/target-*/
**/__pycache__/
# Android
.gradle/
**/build/
@@ -10,3 +12,12 @@ local.properties
# OS
.DS_Store
Thumbs.db
# 标定工具产物(wedge_gen.py 默认输出目录)
/out
# Xcode
ios/**/xcuserdata/
ios/**/*.xcworkspace/xcuserdata/
ios/build/
DerivedData/
# package.sh 打包产物
/dist
+13 -2
View File
@@ -1,4 +1,4 @@
# QFT v0.4.0-rc2 implementation status
# QFT v0.4.7 implementation status
## Windows → Android optical
@@ -44,13 +44,24 @@
- [x] local cleartext network security config
- [x] local/private IPv4 + session-token validation
- [x] Parallel v2 init/chunk/finish
- [x] adaptive 4/8/16 MiB chunks
- [x] adaptive 64 KiB–16 MiB chunks, targeting eight flows per file
- [x] up to 8 Android workers per file
- [x] Windows positioned concurrent writes
- [x] temporary `.qftpart`, final SHA-256 and rename
- [x] accepted sockets return to timeout-bound blocking I/O before file transfer
- [x] loopback UDP + HTTP + out-of-order parallel integration test
- [ ] physical Windows Wi-Fi Direct adapter / driver / firewall matrix
## Windows → Android local direct
- [x] direction-specific pairing QR starts automatic local download after scan
- [x] HTTP `Range` responses return the exact requested range (`206` + `Content-Range`)
- [x] Android parallel Range downloader targets eight workers per file
- [x] adaptive 64 KiB–16 MiB chunks
- [x] `.qftpart` completion ledger resumes only verified completed ranges
- [x] five retries per range, final SHA-256, then save to `Downloads/QFT`
- [x] regression test for delayed large download after nonblocking accept
## Android compatibility
- [x] minSdk 24 (Android 7.0)
+137 -10
View File
@@ -1,13 +1,125 @@
# QFT · 超速二维码文件传输 v0.4.0-rc2
# QFT · 超速二维码文件传输 v0.4.7
Windows + Android 双向候选版。v0.4 的核心目标不是继续堆“4 码理论吞吐”,而是解决 Android 端实际识别慢的问题:**删除 2×2/4 通道,改成一个大二维码 + 动态 ROI 锁定 + 高频局部解码**。
两个方向仍然采用不同链路:
v0.4.7 提供两套互不依赖的传输方式:
- **Windows → Android:纯光学**。文件数据只经过 Windows 屏幕 → Android 摄像头;Wi‑Fi、蓝牙、局域网和互联网都不参与文件数据传输。
- **Android → Windows:扫码本地直连**。Windows 选择保存目录并启动 QFT Direct/LAN 接收服务;Android 扫码、配网、自动发现电脑,然后并行分块上传,不经过外网。
- **电脑 → 手机(纯光学)**:文件数据只经过 Windows 屏幕 → Android 摄像头;Wi‑Fi、蓝牙、局域网和互联网都不参与文件数据传输。
- **扫码本地直传(双向)**:Windows 为“手机上传”和“电脑下发”分别生成方向明确的二维码。Android 扫码后连接 QFT 本地网络、通过 UDP/网关/子网探测定位电脑,并按二维码指定方向自动进入选文件上传或接收下载;文件数据不经过外网。
> rc2 已完成协议、图像合成解码、ROI、并行上传、UDP 发现、内存预算和关键 Kotlin 源码测试。当前生成环境没有真实 Windows 显示器、Android 相机或 Wi‑Fi Direct 适配器,因此物理 30/45/60 FPS 和真实扫码配网仍需在你的设备上跑 `VERIFY_WINDOWS_HOST.ps1` 后做最终验收;详见 `TEST_REPORT.md`。
### v0.4.7 直传稳定性与并发策略
- **双向均使用并行分块**:每个可分块文件以 8 路为目标并发数;分块大小根据文件大小自适应,范围为 **64 KiB–16 MiB**。小于一个最小分块的文件会自然只有一个请求。
- **手机 → 电脑**:Android 使用 offset 定位的 Parallel v2 上传;Windows 对每块进行定位写入,重复块与完成请求可安全重试,最终以 SHA-256 校验后原子改名。
- **电脑 → 手机**:Windows 支持精确的 HTTP `Range`(`206 Partial Content`);Android 对未完成块创建多个独立 Range 请求,并用 `.qftpart` 与完成位图恢复中断传输。每块最多重试 5 次,完成后校验 SHA-256 再保存至 `Downloads/QFT`。
- **连接稳定性**:Windows 监听器保持非阻塞以便及时停止服务,但已连接的文件套接字会切换为带读写超时的阻塞模式,避免 Windows `WSAEWOULDBLOCK (10035)` 造成大文件中途失败。
> v0.4.7 已完成协议、图像合成解码、ROI、双向并发传输、UDP 发现、内存预算和关键 Kotlin 源码测试。当前生成环境没有真实 Windows 显示器、Android 相机或 Wi‑Fi Direct 适配器,因此物理 30/45/60 FPS 和真实扫码配网仍需在你的设备上跑 `VERIFY_WINDOWS_HOST.ps1` 后做最终验收;详见 `TEST_REPORT.md`。
## v0.4.8:跨平台桌面端 + 电脑 ↔ 电脑互传
### macOS:请用 QFT.app 启动,不要直接跑裸二进制
`./package.sh` 在 macOS 上会同时产出 `QFT-Desktop`(裸二进制)和 `QFT.app`,
**推荐用 `QFT.app`**。
直接运行裸二进制时,AppKit 的部分行为会不稳定——最典型的是点「选择文件」时
`+[NSOpenPanel openPanel]` 返回 NULL:
```
panicked at objc2-app-kit/src/generated/NSOpenPanel.rs:
unexpected NULL returned from +[NSOpenPanel openPanel]
```
程序侧已经兜住了这个 panic(不会再崩溃,只提示"对话框没有返回结果"),
但要彻底避免,用 `.app` 启动即可。
任何情况下都可以**直接把文件拖进窗口**——拖拽不经过系统文件对话框。
### Windows 构建报 `os error 5 拒绝访问`
```
error: failed to remove file `...\target\release\qft-desktop.exe`
Caused by: 拒绝访问。 (os error 5)
```
**QFT 窗口还开着**,正在运行的 exe 锁住了产物文件。关掉窗口再构建即可。
`VERIFY_WINDOWS_HOST.ps1` 会在构建前检测并询问是否结束进程。
若关掉后仍然报错,通常是 Windows Defender 正在扫描刚生成的 exe,
稍等几秒重试;也可以把 `desktop\target` 加入 Defender 排除目录。
### 防火墙放行(手动)
接收端要监听入站 TCP,Windows 防火墙默认会拦截未授权程序,表现是
「对方能解析连接码但连接一直超时」。
程序在「电脑 ↔ 电脑 → 我要接收」页会**只读检测**防火墙状态,并提供
「放行防火墙(需要管理员授权)」按钮——**提权只在你点击时发生**,
不会在启动时自动弹 UAC。
也可以自己加规则。两个必须注意的点:
1. 二进制已从 `qft-windows.exe` 改名为 `qft-desktop.exe`,**此前给旧名字
放行的规则对新程序不生效**。
2. **profile 必须是 `Any`**。Windows 对没见过的 Wi-Fi 默认归类为
「公用网络」,此时只覆盖 `Private,Domain` 的规则根本不适用——
规则建了、`Get-NetFirewallRule` 也显示 Enabled,但连接照样被拦。
```powershell
$exe = "<完整路径>\qft-desktop.exe"
# 先清掉可能存在的阻止规则:Windows 里 Block 永远优先于 Allow
Get-NetFirewallApplicationFilter -Program $exe -ErrorAction SilentlyContinue |
Get-NetFirewallRule | Where-Object Action -eq 'Block' | Remove-NetFirewallRule
New-NetFirewallRule -DisplayName "QFT Desktop" -Direction Inbound `
-Program $exe -Action Allow -Profile Any
```
排查时先看这两列:
```powershell
Get-NetConnectionProfile | Format-List Name,NetworkCategory
Get-NetFirewallApplicationFilter | Where-Object Program -like "*qft*" |
ForEach-Object { $r = $_ | Get-NetFirewallRule
[PSCustomObject]@{ 规则=$r.DisplayName; 动作=$r.Action; 配置=$r.Profile } } | Format-Table
```
若 `NetworkCategory` 是 `Public` 而规则的 `配置` 只有 `Domain, Private`,
就是这个原因。
管理员 PowerShell:
```powershell
New-NetFirewallRule -DisplayName "QFT Desktop" -Direction Inbound `
-Program "<完整路径>\qft-desktop.exe" -Action Allow -Profile Private,Domain
```
或在「允许应用通过 Windows Defender 防火墙」里勾选 `qft-desktop.exe` 的**专用网络**。
排查顺序:对端 `ping` 不通且 TCP 端口连不上,但 `arp -a` 能看到对方 MAC,
基本可以判定是对端主机在丢包(防火墙),而不是网络不通。
桌面端目录从 `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 光学链路改动
@@ -93,7 +205,7 @@ Windows 光传页面已经改成“二维码优先”:
推荐初次真机测试从 **30 FPS** 开始,看 Android 的“新帧/s”,再切 45、60。目标不是 Windows 数字最大,而是 Android **实际新帧/s 最大**。
## Android → Windows
## 扫码本地直传(Android ↔ Windows)
v0.3 的稳定性优化继续保留:
@@ -103,8 +215,11 @@ v0.3 的稳定性优化继续保留:
- 扫码连接后 UDP `QFTDISC2` 快速发现;
- gateway / endpoint / 当前子网 fallback;
- HTTP 请求明确绑定扫码建立的 `Network`;
- 单文件最高 8 worker 并行;
- 4/8/16 MiB 自适应上传块;
- 配网请求在传输页持续持有,仅返回首页时释放;短暂网络波动会自动接入新的 `Network`;
- 手机上传和电脑下发均以 8 路为目标并发数;
- 64 KiB–16 MiB 自适应分块;
- 电脑下发使用精确 Range 响应,手机以 `.qftpart` + 位图断点续传;
- 手机上传使用定位写入和幂等完成确认;
- Windows positioned writes + `.qftpart` + SHA-256 + 最终 rename。
## Android 版本
@@ -119,7 +234,7 @@ v0.3 的稳定性优化继续保留:
### Windows
```powershell
cd windows
cd desktop
cargo check
cargo test
cargo build --release
@@ -139,9 +254,21 @@ APK:
`android/app/build/outputs/apk/debug/app-debug.apk`
## 一键打包
脚本只打包 `desktop/` 下的 Rust 桌面端:执行 `cargo test` 和 `cargo build --release`,随后把 Rust 二进制、协议说明和 SHA-256 校验文件收集到带时间戳的 `dist/QFT-Rust-*` 目录并生成压缩包。脚本不检查、下载或调用 Android SDK、Java、Gradle:
```bat
package.bat
```
```bash
./package.sh
```
## 字体
Windows UI 优先读取 `windows/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。
桌面端 UI 优先读取 `desktop/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。
## 自动验证
+5 -5
View File
@@ -1,4 +1,4 @@
# QFT v0.4.0-rc2 test report
# QFT v0.4.7 test report
Date: 2026-08-10
@@ -6,7 +6,7 @@ This report separates **tests actually executed in the current environment** fro
## What this RC changes
The rc2 optical path is deliberately simpler than v0.3:
The v0.4.7 optical path is deliberately simpler than v0.3:
- 2×2 / 4-channel QR removed;
- one large QR only;
@@ -152,7 +152,7 @@ The guard models the Windows single-QR 1024×1024 RGBA pre-render queue:
This is a design-budget check, not an OS-enforced RSS hard cap. GPU/runtime allocators can add platform-specific memory.
## Important implementation decisions validated during rc2
## Important implementation decisions validated during v0.4.7
### QFT2 uses Result.text, not ZXing rawBytes
@@ -160,7 +160,7 @@ The active path is Base45 text. Android reconstructs the QFT binary frame from `
### Duplicate camera hits are not duplicate assembler work
At 45/60 display FPS, a camera can observe the same displayed QR in multiple exposures. rc2 still counts every successful decode in diagnostics, but only a changed QFT2 text fingerprint is delivered to `SessionAssembler`.
At 45/60 display FPS, a camera can observe the same displayed QR in multiple exposures. v0.4.7 still counts every successful decode in diagnostics, but only a changed QFT2 text fingerprint is delivered to `SessionAssembler`.
### AF/AE does not run on a fixed periodic timer
@@ -170,7 +170,7 @@ The scanner performs initial focus/metering, then re-meters after first lock or
The current generation environment does not contain the Windows MSVC Rust toolchain, Android SDK, a physical Android camera, a Windows display or a Windows Wi-Fi Direct adapter. Therefore the following are **not claimed as passed here**:
1. Windows `cargo check/test/build --release` for rc2.
1. Windows `cargo check/test/build --release` for v0.4.7.
2. Android Gradle `:app:testDebugUnitTest :app:assembleDebug` against the real Android SDK.
3. Actual 30/45/60 displayed FPS → CameraX/ZXing effective new-frame throughput.
4. Lock acquisition/reacquisition timing on Android 7 and different phone camera pipelines.
+1 -1
View File
@@ -1,4 +1,4 @@
QFT v0.4.0-rc2 test results
QFT v0.4.7 test results
UTC 2026-08-10T08:45:56Z
== protocol_selftest.py ==
+23 -4
View File
@@ -1,7 +1,7 @@
$ErrorActionPreference = 'Stop'
$Root = Split-Path -Parent $MyInvocation.MyCommand.Path
Write-Host "== QFT v0.4.0-rc2 Windows host verification ==" -ForegroundColor Cyan
Write-Host "== QFT v0.4.7 Windows host verification ==" -ForegroundColor Cyan
if (Get-Command python -ErrorAction SilentlyContinue) {
Write-Host "[1/4] Core protocol/selftests"
@@ -14,8 +14,27 @@ 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"
# 正在运行的 qft-desktop.exe 会锁住产物文件,cargo 只会抛出
# "failed to remove file ... 拒绝访问 (os error 5)" 这种看不出原因的错误。
# 这里提前识别并说清楚,而不是让用户去猜。
$Running = Get-Process -Name 'qft-desktop' -ErrorAction SilentlyContinue
if ($Running) {
Write-Host ""
Write-Warning "检测到 qft-desktop.exe 正在运行(PID: $($Running.Id -join ', '))。"
Write-Warning "它会锁住 target\release\qft-desktop.exe,导致构建报 'os error 5 拒绝访问'。"
$Answer = Read-Host "是否结束这些进程后继续构建?(y/N)"
if ($Answer -eq 'y' -or $Answer -eq 'Y') {
$Running | Stop-Process -Force
Start-Sleep -Milliseconds 500
Write-Host "已结束,继续构建。"
} else {
throw "请先关闭 QFT 窗口再重新运行本脚本"
}
}
Push-Location "$Root\desktop"
try {
& cargo check
if ($LASTEXITCODE -ne 0) { throw "cargo check failed" }
@@ -37,7 +56,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."
+3 -2
View File
@@ -12,8 +12,8 @@ android {
applicationId = "com.qft.optical"
minSdk = 24
targetSdk = 35
versionCode = 16
versionName = "0.4.0-rc8"
versionCode = 19
versionName = "0.4.7"
testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
}
@@ -40,6 +40,7 @@ android {
dependencies {
implementation("androidx.activity:activity-ktx:1.10.1")
implementation("androidx.core:core-ktx:1.15.0")
implementation("androidx.camera:camera-core:1.4.2")
implementation("androidx.camera:camera-camera2:1.4.2")
implementation("androidx.camera:camera-lifecycle:1.4.2")
+9
View File
@@ -19,6 +19,15 @@
android:label="QFT"
android:supportsRtl="true"
android:theme="@style/QftTheme">
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}.files"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/qft_file_paths" />
</provider>
<activity
android:name=".MainActivity"
android:exported="true"
@@ -13,9 +13,14 @@ import java.io.File
import java.io.FileInputStream
import java.io.FileOutputStream
import java.io.OutputStream
import java.io.RandomAccessFile
import java.net.HttpURLConnection
import java.net.URL
import java.nio.ByteBuffer
import java.security.MessageDigest
import java.util.concurrent.Executors
import java.util.concurrent.atomic.AtomicInteger
import java.util.concurrent.atomic.AtomicLong
data class DownloadedFile(val name: String, val size: Long, val uri: Uri?)
@@ -24,15 +29,121 @@ data class DownloadedFile(val name: String, val size: Long, val uri: Uri?)
object DownloadClient {
private const val TAG = "QftDownload"
private const val BUFFER_SIZE = 1024 * 1024
private const val ATTEMPTS = 5
private const val SERIAL_ATTEMPTS = 3
// Kept only for the old sequential compatibility path below. New direct
// sessions always use the concurrent Range downloader.
private const val PARALLEL_MIN_FILE_SIZE = 32L * 1024L * 1024L
private const val PARALLEL_CHUNK_SIZE = 16L * 1024L * 1024L
private const val MAX_WORKERS = 8
private const val RANGE_WORKERS = 8
private const val RANGE_ATTEMPTS = 5
private const val MIN_RANGE_CHUNK = 64L * 1024L
private const val MAX_RANGE_CHUNK = 16L * 1024L * 1024L
/** 整份重下的轮数。仅在 SHA-256 不匹配(缓存已损坏)时才会用到第二轮。 */
private const val VERIFY_ROUNDS = 2
/** 落盘阶段的失败与「下载失败」是两回事,用独立异常类型区分。 */
class SaveFailure(message: String, cause: Throwable?) : Exception(message, cause)
/** Persistent received-range map. The data file is preallocated, so its
* length is not used as a completion signal; only an atomically replaced
* map entry marks a range safe to resume. */
private class ChunkLedger private constructor(
private val partial: File,
private val map: File,
private val size: Long,
val chunkSize: Long,
val totalChunks: Int,
private val completed: BooleanArray,
) {
private val lock = Any()
fun isComplete(index: Int): Boolean = synchronized(lock) { completed[index] }
fun allComplete(): Boolean = synchronized(lock) { completed.all { it } }
fun bytesComplete(): Long = synchronized(lock) {
completed.indices.sumOf { index -> if (completed[index]) chunkLength(index) else 0L }
}
fun chunkOffset(index: Int): Long = index.toLong() * chunkSize
fun chunkLength(index: Int): Long = minOf(chunkSize, size - chunkOffset(index))
fun markComplete(index: Int) = synchronized(lock) {
if (!completed[index]) {
completed[index] = true
persistLocked()
}
}
fun discard() = synchronized(lock) {
partial.delete()
map.delete()
File("${map.path}.tmp").delete()
}
private fun persistLocked() {
val temp = File("${map.path}.tmp")
temp.bufferedWriter().use { writer ->
writer.appendLine("$size:$chunkSize:$totalChunks")
writer.write(buildString(totalChunks) {
completed.forEach { append(if (it) '1' else '0') }
})
}
if (map.exists()) map.delete()
if (!temp.renameTo(map)) {
temp.copyTo(map, overwrite = true)
temp.delete()
}
}
companion object {
fun open(partial: File, size: Long, chunkSize: Long): ChunkLedger {
val totalLong = if (size == 0L) 0L else (size + chunkSize - 1L) / chunkSize
require(totalLong <= Int.MAX_VALUE) { "文件分块数过大" }
val total = totalLong.toInt()
val map = File("${partial.path}.map")
val restored = runCatching {
val pieces = map.readText().split('\n', limit = 2)
val header = pieces.firstOrNull()?.split(':') ?: emptyList()
val bits = pieces.getOrNull(1).orEmpty()
if (
partial.length() == size && header.size == 3 &&
header[0].toLong() == size && header[1].toLong() == chunkSize &&
header[2].toInt() == total && bits.length >= total
) {
BooleanArray(total) { bits[it] == '1' }
} else {
null
}
}.getOrNull()
val ledger = ChunkLedger(partial, map, size, chunkSize, total, restored ?: BooleanArray(total))
if (restored == null) {
partial.parentFile?.let { if (!it.exists()) it.mkdirs() }
RandomAccessFile(partial, "rw").use { file ->
file.setLength(0L)
file.setLength(size)
}
ledger.persistLocked()
}
return ledger
}
}
}
fun download(
context: Context,
resolver: ContentResolver,
network: Network?,
networkProvider: () -> Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
/** 返回非 null 表示应立刻中止(例如 QFT 临时网络已断开),并以该原因报错。 */
abortReason: () -> String? = { null },
/** 阶段提示。传输完成后还有校验与落盘两步,必须让 UI 有反馈,
* 否则用户看到的就是「进度条停在 100% 然后报错」。 */
onPhase: (String) -> Unit = {},
onProgress: (received: Long, total: Long) -> Unit,
): DownloadedFile {
require(pairing.direction == TransferDirection.DOWNLOAD_TO_PHONE)
@@ -41,27 +152,78 @@ object DownloadClient {
val expectedSha = requireNotNull(pairing.sha256)
val partial = partialFile(context, pairing.session)
partial.parentFile?.let { if (!it.exists() && !it.mkdirs()) error("无法创建接收缓存目录") }
if (partial.length() > expectedSize) partial.delete()
if (partial.length() > expectedSize) discardTransferState(partial)
// 落盘时缓存文件与目标文件同时存在,需要约 2 倍空间。
// 不预检的话,这里会在下载 100% 之后才失败,用户看到的是「快结束时失败」。
ensureSpaceForTransfer(partial, expectedSize)
repeat(VERIFY_ROUNDS) { round ->
receiveUntilComplete(networkProvider, baseUrl, pairing, deviceName, partial,
expectedSize, abortReason, onProgress)
onPhase("正在校验文件完整性…")
val actual = sha256(partial, onProgress)
if (actual.equals(expectedSha, ignoreCase = true)) {
onPhase("正在保存到 Downloads/QFT…")
ensureSpaceForSave(partial, expectedSize)
val result = try {
saveToDownloads(resolver, partial, expectedName, expectedSize, onProgress)
} catch (e: Exception) {
// 这一步失败与网络无关,重下多少次都没用,直接如实报错
throw SaveFailure("文件已完整收到,但保存到 Downloads/QFT 失败:${failureDetail(e)}", e)
}
discardTransferState(partial)
Log.i(TAG, "completed size=$expectedSize")
return result
}
Log.w(TAG, "sha mismatch round=${round + 1}/$VERIFY_ROUNDS expected=$expectedSha actual=$actual")
discardTransferState(partial)
if (round + 1 >= VERIFY_ROUNDS) {
error("文件校验失败:重新完整下载后 SHA-256 仍不匹配,请让电脑重新生成二维码")
}
onPhase("校验未通过,正在重新完整下载…")
}
error("下载未能完成")
}
/** 传输阶段:断点续传 + 有限重试。只有这一段的失败才算「下载失败」。 */
@Suppress("unused")
private fun receiveSequentialCompatibility(
networkProvider: () -> Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
partial: File,
expectedSize: Long,
abortReason: () -> String?,
onProgress: (received: Long, total: Long) -> Unit,
) {
if (expectedSize >= PARALLEL_MIN_FILE_SIZE && expectedSize > 0L) {
receiveParallel(networkProvider, baseUrl, pairing, deviceName, partial,
expectedSize, abortReason, onProgress)
return
}
var last: Exception? = null
repeat(ATTEMPTS) { attempt ->
repeat(SERIAL_ATTEMPTS) { attempt ->
abortReason()?.let { throw IllegalStateException(it, last) }
try {
Log.i(TAG, "attempt=${attempt + 1}/$ATTEMPTS partial=${partial.length()}/$expectedSize endpoint=$baseUrl")
Log.i(TAG, "serial attempt=${attempt + 1}/$SERIAL_ATTEMPTS partial=${partial.length()}/$expectedSize endpoint=$baseUrl")
if (partial.length() < expectedSize) {
receiveAttempt(network, baseUrl, pairing, deviceName, partial, expectedSize, onProgress)
receiveAttempt(networkProvider(), baseUrl, pairing, deviceName, partial,
expectedSize, abortReason, onProgress)
}
if (partial.length() != expectedSize) {
error("下载提前结束:${partial.length()}/$expectedSize")
}
verifySha256(partial, expectedSha)
val result = saveToDownloads(resolver, partial, expectedName, expectedSize)
partial.delete()
Log.i(TAG, "completed size=$expectedSize")
return result
return
} catch (e: Exception) {
last = e
Log.w(TAG, "attempt=${attempt + 1}/$ATTEMPTS failed partial=${partial.length()}/$expectedSize: ${failureDetail(e)}", e)
if (attempt + 1 < ATTEMPTS) {
Log.w(TAG, "serial attempt=${attempt + 1}/$SERIAL_ATTEMPTS failed partial=${partial.length()}/$expectedSize: ${failureDetail(e)}", e)
abortReason()?.let { throw IllegalStateException(it, e) }
if (attempt + 1 < SERIAL_ATTEMPTS) {
try {
Thread.sleep(250L * (attempt + 1))
} catch (interrupted: InterruptedException) {
@@ -71,7 +233,226 @@ object DownloadClient {
}
}
}
throw IllegalStateException("从电脑下载失败,已重试 $ATTEMPTS 次:${failureDetail(last)}", last)
val progressed = partial.length()
throw IllegalStateException(
"从电脑下载失败(断点 ${progressed}/$expectedSize 字节):${failureDetail(last)}",
last,
)
}
/**
* 大文件并行直传。每个 worker 请求一个有界 HTTP Range,并写入预分配文件的
* 固定 offset。完成位图单独落盘,所以应用进程或某条 TCP 流中断后只补缺块,
* 不会把 1 GB 文件从头再传一遍。
*/
private fun receiveParallel(
networkProvider: () -> Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
partial: File,
expectedSize: Long,
abortReason: () -> String?,
onProgress: (received: Long, total: Long) -> Unit,
) {
val totalChunks = ((expectedSize + PARALLEL_CHUNK_SIZE - 1L) / PARALLEL_CHUNK_SIZE).toInt()
val mapFile = completionMapFile(partial)
val completed = loadCompletionMap(mapFile, totalChunks)
// A partial from the old sequential downloader has no bitmap. Preserve
// only complete chunks; an incomplete tail is safely downloaded again.
val oldLength = partial.length()
if (!mapFile.exists() && oldLength in 1 until expectedSize) {
for (index in completed.indices) {
val endExclusive = minOf(expectedSize, (index + 1L) * PARALLEL_CHUNK_SIZE)
if (endExclusive <= oldLength) completed[index] = true
}
}
RandomAccessFile(partial, "rw").use { it.setLength(expectedSize) }
persistCompletionMap(mapFile, completed)
val initialBytes = completed.indices.sumOf { index ->
if (completed[index]) chunkLength(index, expectedSize) else 0L
}
val received = AtomicLong(initialBytes)
val lastReport = AtomicLong(0L)
val next = AtomicInteger(0)
onProgress(initialBytes, expectedSize)
val workers = totalChunks.coerceAtMost(
Runtime.getRuntime().availableProcessors().coerceIn(2, MAX_WORKERS)
).coerceAtLeast(1)
Log.i(TAG, "parallel download chunks=$totalChunks workers=$workers completed=$initialBytes/$expectedSize")
val pool = Executors.newFixedThreadPool(workers)
val futures = (0 until workers).map {
pool.submit {
RandomAccessFile(partial, "rw").use { output ->
while (!Thread.currentThread().isInterrupted) {
abortReason()?.let { error(it) }
val index = next.getAndIncrement()
if (index >= totalChunks) break
if (completed[index]) continue
val start = index.toLong() * PARALLEL_CHUNK_SIZE
val length = chunkLength(index, expectedSize)
receiveRangeWithRetry(
networkProvider, baseUrl, pairing, deviceName,
output, index, start, length, expectedSize, abortReason,
)
// Data reaches stable storage before its completion bit.
// A crash can therefore only cause a harmless re-download.
output.fd.sync()
synchronized(completed) {
completed[index] = true
persistCompletionMap(mapFile, completed)
}
val done = received.addAndGet(length)
val now = android.os.SystemClock.elapsedRealtime()
val previous = lastReport.get()
if (now - previous >= 80L && lastReport.compareAndSet(previous, now)) {
onProgress(done.coerceAtMost(expectedSize), expectedSize)
}
}
}
}
}
val failures = mutableListOf<Throwable>()
try {
futures.forEach { future ->
try { future.get() } catch (e: Exception) { failures += (e.cause ?: e) }
}
} finally {
pool.shutdownNow()
}
if (failures.isNotEmpty()) throw IllegalStateException(
"并行直传中断,已完成 ${received.get()}/$expectedSize 字节;下次将只补传缺块:${failureDetail(failures.first())}",
failures.first(),
)
if (completed.any { !it }) error("并行直传结束但仍有缺块")
onProgress(expectedSize, expectedSize)
}
private fun receiveRangeWithRetry(
networkProvider: () -> Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
output: RandomAccessFile,
index: Int,
start: Long,
length: Long,
expectedSize: Long,
abortReason: () -> String?,
) {
var last: Exception? = null
repeat(RANGE_ATTEMPTS) { attempt ->
abortReason()?.let { error(it) }
try {
receiveRange(
networkProvider(), baseUrl, pairing, deviceName, output,
start, length, expectedSize, abortReason,
)
return
} catch (e: Exception) {
last = e
Log.w(TAG, "range=$index attempt=${attempt + 1}/$RANGE_ATTEMPTS failed: ${failureDetail(e)}")
if (attempt + 1 < RANGE_ATTEMPTS) {
try { Thread.sleep((200L shl attempt).coerceAtMost(3_000L)) }
catch (_: InterruptedException) {
Thread.currentThread().interrupt()
throw e
}
}
}
}
throw IllegalStateException("区段 $index 传输失败:${failureDetail(last)}", last)
}
private fun receiveRange(
network: Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
output: RandomAccessFile,
start: Long,
length: Long,
expectedSize: Long,
abortReason: () -> String?,
) {
val end = start + length - 1L
val conn = open(network, URL("$baseUrl/qft/download"))
try {
conn.requestMethod = "GET"
conn.connectTimeout = 8_000
conn.readTimeout = 90_000
conn.useCaches = false
conn.setRequestProperty("Connection", "keep-alive")
conn.setRequestProperty("X-QFT-Token", pairing.session)
conn.setRequestProperty("X-QFT-Device", Base64Url.encode(deviceName.toByteArray(Charsets.UTF_8)))
conn.setRequestProperty("Range", "bytes=$start-$end")
val code = conn.responseCode
if (code != HttpURLConnection.HTTP_PARTIAL) {
val message = try { conn.errorStream?.bufferedReader()?.use { it.readText().take(300) } } catch (_: Exception) { null }
error("电脑端不支持并行 Range(HTTP $code)${message?.let { ": $it" } ?: ""}")
}
val contentRange = conn.getHeaderField("Content-Range").orEmpty()
if (contentRange != "bytes $start-$end/$expectedSize") {
error("下载服务返回了无效区段:$contentRange")
}
if (conn.contentLengthLong >= 0L && conn.contentLengthLong != length) {
error("区段长度不匹配:${conn.contentLengthLong} != $length")
}
output.seek(start)
var remaining = length
conn.inputStream.use { input ->
val buffer = ByteArray(BUFFER_SIZE)
while (remaining > 0L) {
abortReason()?.let { error(it) }
val n = input.read(buffer, 0, minOf(buffer.size.toLong(), remaining).toInt())
if (n < 0) error("区段提前结束:还缺 $remaining 字节")
if (n == 0) continue
output.write(buffer, 0, n)
remaining -= n.toLong()
}
}
} finally {
conn.disconnect()
}
}
private fun chunkLength(index: Int, total: Long): Long =
minOf(PARALLEL_CHUNK_SIZE, total - index.toLong() * PARALLEL_CHUNK_SIZE)
private fun completionMapFile(partial: File): File = File(partial.parentFile, partial.name + ".map")
private fun loadCompletionMap(file: File, count: Int): BooleanArray {
val result = BooleanArray(count)
val bytes = try { if (file.exists()) file.readBytes() else ByteArray(0) } catch (_: Exception) { ByteArray(0) }
if (bytes.size == count) bytes.indices.forEach { result[it] = bytes[it].toInt() == 1 }
return result
}
private fun persistCompletionMap(file: File, completed: BooleanArray) {
FileOutputStream(file, false).use { output ->
output.write(ByteArray(completed.size) { if (completed[it]) 1 else 0 })
output.fd.sync()
}
}
/** 传输 + 落盘阶段合计需要的可用空间。 */
private fun ensureSpaceForTransfer(partial: File, expectedSize: Long) {
val root = partial.parentFile ?: return
val needed = (expectedSize - partial.length()).coerceAtLeast(0L) + expectedSize
val usable = root.usableSpace
if (usable in 1 until needed) {
error("存储空间不足:本次接收约需 ${needed / 1024 / 1024} MB(含保存时的临时副本),当前可用 ${usable / 1024 / 1024} MB")
}
}
private fun ensureSpaceForSave(partial: File, expectedSize: Long) {
val usable = partial.parentFile?.usableSpace ?: return
if (usable in 1 until expectedSize) {
error("存储空间不足:保存副本还需 ${expectedSize / 1024 / 1024} MB,当前可用 ${usable / 1024 / 1024} MB")
}
}
private fun receiveAttempt(
@@ -81,6 +462,7 @@ object DownloadClient {
deviceName: String,
partial: File,
expectedSize: Long,
abortReason: () -> String?,
onProgress: (received: Long, total: Long) -> Unit,
) {
val requestedOffset = partial.length().coerceIn(0L, expectedSize)
@@ -88,13 +470,9 @@ object DownloadClient {
try {
conn.requestMethod = "GET"
conn.connectTimeout = 5_000
// A QFT LAN transfer should start immediately. The old 120-second
// read timeout let Huawei tear down a local-only Wi-Fi request
// before a retry could occur. A short timeout safely resumes from
// the persisted Range offset and finishes all retries sooner.
conn.readTimeout = 12_000
conn.readTimeout = 60_000
conn.useCaches = false
conn.setRequestProperty("Connection", "close")
conn.setRequestProperty("Connection", "keep-alive")
conn.setRequestProperty("X-QFT-Token", pairing.session)
conn.setRequestProperty("X-QFT-Device", Base64Url.encode(deviceName.toByteArray(Charsets.UTF_8)))
if (requestedOffset > 0L) conn.setRequestProperty("Range", "bytes=$requestedOffset-")
@@ -132,6 +510,8 @@ object DownloadClient {
FileOutputStream(partial, offset > 0L).use { output ->
val buffer = ByteArray(BUFFER_SIZE)
while (true) {
// 用户明确返回首页时才中止;普通 TCP 波动由 Range 续传恢复。
abortReason()?.let { error(it) }
val n = input.read(buffer)
if (n < 0) break
if (n == 0) continue
@@ -154,21 +534,209 @@ object DownloadClient {
}
}
private fun verifySha256(file: File, expectedSha: String) {
/** 校验也要报进度:大文件读一整遍是好几秒,静默的话看起来就是卡在 100%。 */
private fun receiveUntilComplete(
networkProvider: () -> Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
partial: File,
expectedSize: Long,
abortReason: () -> String?,
onProgress: (received: Long, total: Long) -> Unit,
) {
val ledger = ChunkLedger.open(partial, expectedSize, desiredRangeChunkSize(expectedSize))
val initial = ledger.bytesComplete()
onProgress(initial, expectedSize)
if (ledger.allComplete()) return
val workers = ledger.totalChunks.coerceAtMost(RANGE_WORKERS).coerceAtLeast(1)
Log.i(TAG, "parallel start: chunks=${ledger.totalChunks}, workers=$workers, completed=$initial/$expectedSize")
val pool = Executors.newFixedThreadPool(workers)
val next = AtomicInteger(0)
val futures = (0 until workers).map {
pool.submit {
while (!Thread.currentThread().isInterrupted) {
abortReason()?.let { error(it) }
val index = next.getAndIncrement()
if (index >= ledger.totalChunks) break
if (ledger.isComplete(index)) continue
receiveRangeWithRetry(
networkProvider,
baseUrl,
pairing,
deviceName,
partial,
expectedSize,
ledger,
index,
abortReason,
)
onProgress(ledger.bytesComplete(), expectedSize)
}
}
}
try {
futures.forEach { future -> future.get() }
} catch (e: Exception) {
futures.forEach { it.cancel(true) }
throw (e.cause ?: e)
} finally {
pool.shutdownNow()
}
if (!ledger.allComplete()) {
error("并行下载未完成:${ledger.bytesComplete()}/$expectedSize")
}
Log.i(TAG, "parallel complete: chunks=${ledger.totalChunks}, bytes=$expectedSize")
}
private fun receiveRangeWithRetry(
networkProvider: () -> Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
partial: File,
expectedSize: Long,
ledger: ChunkLedger,
index: Int,
abortReason: () -> String?,
) {
var last: Exception? = null
repeat(RANGE_ATTEMPTS) { attempt ->
abortReason()?.let { throw IllegalStateException(it, last) }
try {
receiveRange(
networkProvider(),
baseUrl,
pairing,
deviceName,
partial,
expectedSize,
ledger,
index,
)
ledger.markComplete(index)
return
} catch (e: Exception) {
last = e
Log.w(
TAG,
"range=$index/${ledger.totalChunks} attempt=${attempt + 1}/$RANGE_ATTEMPTS failed: ${failureDetail(e)}",
e,
)
if (attempt + 1 < RANGE_ATTEMPTS) {
try {
Thread.sleep(180L * (attempt + 1))
} catch (interrupted: InterruptedException) {
Thread.currentThread().interrupt()
throw e
}
}
}
}
throw IllegalStateException(
"分块 $index 下载失败,已重试 $RANGE_ATTEMPTS 次:${failureDetail(last)}",
last,
)
}
private fun receiveRange(
network: Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
partial: File,
expectedSize: Long,
ledger: ChunkLedger,
index: Int,
) {
val offset = ledger.chunkOffset(index)
val length = ledger.chunkLength(index)
val end = offset + length - 1L
val conn = open(network, URL("$baseUrl/qft/download"))
try {
conn.requestMethod = "GET"
conn.connectTimeout = 5_000
conn.readTimeout = 20_000
conn.useCaches = false
conn.setRequestProperty("Connection", "close")
conn.setRequestProperty("X-QFT-Token", pairing.session)
conn.setRequestProperty("X-QFT-Device", Base64Url.encode(deviceName.toByteArray(Charsets.UTF_8)))
conn.setRequestProperty("Range", "bytes=$offset-$end")
val code = conn.responseCode
if (code != HttpURLConnection.HTTP_PARTIAL) {
val message = try { conn.errorStream?.bufferedReader()?.use { it.readText().take(300) } } catch (_: Exception) { null }
error("电脑下载服务未返回并行 Range(HTTP $code)${message?.let { ": $it" } ?: ""}")
}
val expectedRange = "bytes $offset-$end/$expectedSize"
if (conn.getHeaderField("Content-Range") != expectedRange) {
error("下载服务返回了无效范围:${conn.getHeaderField("Content-Range")}")
}
if (conn.contentLengthLong >= 0L && conn.contentLengthLong != length) {
error("分块 $index 长度不匹配:${conn.contentLengthLong} != $length")
}
var received = 0L
conn.inputStream.use { input ->
RandomAccessFile(partial, "rw").use { output ->
output.channel.use { channel ->
channel.position(offset)
val buffer = ByteArray(BUFFER_SIZE)
while (received < length) {
val n = input.read(buffer, 0, minOf(buffer.size.toLong(), length - received).toInt())
if (n < 0) break
if (n == 0) continue
val bytes = ByteBuffer.wrap(buffer, 0, n)
while (bytes.hasRemaining()) channel.write(bytes)
received += n.toLong()
}
channel.force(false)
}
}
}
if (received != length) error("分块 $index 提前结束:$received/$length")
Log.d(TAG, "range=$index/${ledger.totalChunks} complete bytes=$length")
} finally {
conn.disconnect()
}
}
private fun desiredRangeChunkSize(fileSize: Long): Long {
if (fileSize <= 0L) return MIN_RANGE_CHUNK
return ((fileSize + RANGE_WORKERS - 1L) / RANGE_WORKERS)
.coerceIn(MIN_RANGE_CHUNK, MAX_RANGE_CHUNK)
}
private fun discardTransferState(partial: File) {
partial.delete()
File("${partial.path}.map").delete()
File("${partial.path}.map.tmp").delete()
}
private fun sha256(file: File, onProgress: (Long, Long) -> Unit): String {
val digest = MessageDigest.getInstance("SHA-256")
val total = file.length()
var done = 0L
var lastReport = 0L
FileInputStream(file).use { input ->
val buffer = ByteArray(BUFFER_SIZE)
while (true) {
val n = input.read(buffer)
if (n < 0) break
if (n > 0) digest.update(buffer, 0, n)
if (n > 0) {
digest.update(buffer, 0, n)
done += n.toLong()
val now = android.os.SystemClock.elapsedRealtime()
if (now - lastReport >= 80L) {
onProgress(done, total)
lastReport = now
}
}
}
}
val actual = digest.digest().toHex()
if (!actual.equals(expectedSha, ignoreCase = true)) {
file.delete()
error("文件校验失败,已清除不完整缓存;请重试")
}
onProgress(total, total)
return digest.digest().toHex()
}
private fun saveToDownloads(
@@ -176,6 +744,7 @@ object DownloadClient {
partial: File,
expectedName: String,
expectedSize: Long,
onProgress: (Long, Long) -> Unit,
): DownloadedFile {
var target: DownloadTarget? = null
try {
@@ -185,12 +754,18 @@ object DownloadClient {
createdTarget.output.use { output ->
val buffer = ByteArray(BUFFER_SIZE)
var copied = 0L
var lastReport = 0L
while (true) {
val n = input.read(buffer)
if (n < 0) break
if (n == 0) continue
output.write(buffer, 0, n)
copied += n.toLong()
val now = android.os.SystemClock.elapsedRealtime()
if (now - lastReport >= 80L) {
onProgress(copied, expectedSize)
lastReport = now
}
}
output.flush()
if (copied != expectedSize) error("保存下载文件时大小发生变化")
@@ -76,9 +76,11 @@ class MainActivity : ComponentActivity() {
private lateinit var progress: ProgressBar
private var pendingPair: PairingPayload? = null
private var connectedNetwork: Network? = null
@Volatile private var connectedNetwork: Network? = null
private var connectedBaseUrl: String? = null
private val selectedFiles = mutableListOf<SelectedFile>()
private var managingFilesForPair: PairingPayload? = null
private var managingFilesForBaseUrl: String? = null
private var sendStatusText: TextView? = null
private var sendFilesText: TextView? = null
private var sendProgress: ProgressBar? = null
@@ -86,6 +88,9 @@ class MainActivity : ComponentActivity() {
private var connectingStatusText: TextView? = null
private var downloadStatusText: TextView? = null
@Volatile private var downloadRunning = false
/** 非 null 表示当前传输应立刻中止(QFT 临时网络断开等)。
* 下载线程每读一个缓冲区就检查一次,避免在 readTimeout 上白等。 */
@Volatile private var transferAbortReason: String? = null
@Volatile private var pairConnectionAttempt = 0L
private val requestCamera = registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
@@ -112,13 +117,18 @@ class MainActivity : ComponentActivity() {
}
private val pickFiles = registerForActivityResult(ActivityResultContracts.OpenMultipleDocuments()) { uris ->
selectedFiles.clear()
var unknown = 0
for (uri in uris) {
val file = UploadClient.describeFile(contentResolver, uri)
if (file != null) selectedFiles += file else unknown++
if (file != null && selectedFiles.none { it.uri == file.uri }) selectedFiles += file else if (file == null) unknown++
}
renderSelectedFiles()
val pair = managingFilesForPair
val baseUrl = managingFilesForBaseUrl
if (pair != null && baseUrl != null) {
showFileSelection(pair, baseUrl)
return@registerForActivityResult
}
if (unknown > 0) {
sendStatusText?.text = "有 $unknown 个文件无法确定大小,已跳过"
} else if (selectedFiles.isNotEmpty()) {
@@ -136,6 +146,7 @@ class MainActivity : ComponentActivity() {
}
private fun showHome(message: String? = null) {
transferAbortReason = "已返回首页,传输已停止"
pairConnectionAttempt++
stopCamera()
scannerMode = ScannerMode.NONE
@@ -147,6 +158,8 @@ class MainActivity : ComponentActivity() {
downloadRunning = false
downloadStatusText = null
selectedFiles.clear()
managingFilesForPair = null
managingFilesForBaseUrl = null
val root = pageColumn()
root.addView(text("QFT", 30f, Color.WHITE, true))
@@ -172,9 +185,16 @@ class MainActivity : ComponentActivity() {
body = "扫描电脑二维码后自动连接 QFT 本地网络:接收二维码会进入手机选文件上传;下发二维码会自动下载并保存到 Downloads/QFT。",
buttonLabel = "扫描电脑二维码",
) { requestScanner(ScannerMode.PAIR) })
root.addView(space(16))
root.addView(modeCard(
title = "接收文件柜",
badge = "Downloads/QFT · 图片/视频/PDF/Office/压缩包等",
body = "查看 QFT 已接收的文件;点击后将使用手机中可用的阅读器或播放器打开。",
buttonLabel = "打开文件柜",
) { showReceivedFiles() })
root.addView(space(22))
root.addView(text("本机设备:$receiverDeviceLabel", 13f, MUTED))
root.addView(text("QFT v0.4.0-rc2 · Android 7+ 到最新", 12f, MUTED))
root.addView(text("QFT v0.4.7 · Android 7+ 到最新", 12f, MUTED))
setContentView(ScrollView(this).apply { setBackgroundColor(BG); addView(root) })
}
@@ -583,6 +603,7 @@ class MainActivity : ComponentActivity() {
private fun connectPair(pair: PairingPayload) {
val attempt = ++pairConnectionAttempt
transferAbortReason = null
showConnecting(pair, pair.wifi?.let { "正在请求连接 ${it.ssid}…" } ?: "正在使用当前局域网探测电脑…")
wifiConnector.connect(
pairing = pair,
@@ -592,6 +613,10 @@ class MainActivity : ComponentActivity() {
onAvailable = available@{ network ->
if (attempt != pairConnectionAttempt) return@available
connectedNetwork = network
// A retained WifiNetworkSpecifier request may deliver a fresh
// Network after a brief radio fluctuation. Do not restart the
// page or transfer; chunk retries will use this new handle.
if (connectedBaseUrl != null) return@available
transferExecutor.execute {
if (attempt != pairConnectionAttempt) return@execute
runOnUiThread { updateConnectingStatus("网络路由已就绪 · 正在 UDP 快速发现电脑…") }
@@ -638,11 +663,11 @@ class MainActivity : ComponentActivity() {
},
onUnavailable = { message -> runOnUiThread {
if (attempt != pairConnectionAttempt) return@runOnUiThread
// Huawei can report onLost while a bound local-only HTTP
// socket is unwinding. Let DownloadClient surface its precise
// HTTP/timeout cause instead of replacing it with this generic
// message mid-retry.
// onLost is recovered inside WifiConnector. onUnavailable is
// terminal (system/user rejected the retained request), so it
// is the only network callback that aborts an active transfer.
if (pair.direction == TransferDirection.DOWNLOAD_TO_PHONE && downloadRunning) {
transferAbortReason = message
downloadStatusText?.apply {
text = "QFT 本地网络已断开,正在结束当前下载请求…"
setTextColor(WARNING)
@@ -682,8 +707,8 @@ class MainActivity : ComponentActivity() {
private fun showPairError(pair: PairingPayload?, message: String) {
// Do not unregister here: Android may still be displaying its
// Wi-Fi-selection sheet, and unregistering at that moment produces
// "the app cancelled the device selection request". The next attempt
// (or returning home) releases the previous request safely.
// "the app cancelled the device selection request". A retry reuses
// this retained request; returning home is what explicitly releases it.
pairConnectionAttempt++
connectedNetwork = null
connectedBaseUrl = null
@@ -695,7 +720,7 @@ class MainActivity : ComponentActivity() {
root.addView(button("重试连接").apply { setOnClickListener { ensureWifiPermissionThenConnect(pair) } })
root.addView(space(10))
}
root.addView(button("重新扫码").apply { setOnClickListener { requestScanner(ScannerMode.PAIR) } })
root.addView(button("返回首页重新扫码").apply { setOnClickListener { showHome() } })
root.addView(space(10))
root.addView(button("返回首页").apply { setOnClickListener { showHome() } })
setContentView(ScrollView(this).apply { setBackgroundColor(BG); addView(root) })
@@ -709,29 +734,32 @@ class MainActivity : ComponentActivity() {
root.addView(card().apply {
addView(text("连接状态", 14f, MUTED))
addView(text("● 本地直连已就绪", 17f, SUCCESS, true), matchWrap(top = 8))
addView(text(if (pair.version >= 2) "Parallel v2 · 自适应最高 8 路并发 · 4/8/16 MiB 自适应分块" else "兼容单流模式", 13f, ACCENT), matchWrap(top = 5))
addView(text(if (pair.version >= 2) "Parallel v2 · 目标 8 路并发 · 64 KiB–16 MiB 自适应分块" else "兼容单流模式", 13f, ACCENT), matchWrap(top = 5))
addView(text("目标:$baseUrl", 12f, MUTED), matchWrap(top = 6))
pair.wifi?.let { addView(text("QFT 临时网络:${it.ssid}", 12f, MUTED), matchWrap(top = 4)) }
})
root.addView(space(14))
root.addView(card().apply {
addView(text("选择文件", 17f, Color.WHITE, true))
sendFilesText = text("尚未选择文件", 14f, MUTED)
sendFilesText = text("请先选择需要传输的文件", 14f, WARNING)
addView(sendFilesText, matchWrap(top = 8))
addView(button("选择文件(可多选)").apply {
setOnClickListener { pickFiles.launch(arrayOf("*/*")) }
setOnClickListener { showFileSelection(pair, baseUrl) }
}, matchWrap(top = 12))
})
root.addView(space(14))
root.addView(card().apply {
addView(text("传输进度", 17f, Color.WHITE, true))
sendStatusText = text("选择文件后点击开始传输", 14f, MUTED)
sendStatusText = text("请先选择需要传输的文件,再点击“开始传输”", 14f, WARNING)
addView(sendStatusText, matchWrap(top = 8))
sendProgress = ProgressBar(this@MainActivity, null, android.R.attr.progressBarStyleHorizontal).apply { max = 1000; progress = 0 }
addView(sendProgress, LinearLayout.LayoutParams(-1, dp(9)).apply { topMargin = dp(12) })
sendButton = button("开始传输").apply {
isEnabled = selectedFiles.isNotEmpty()
setOnClickListener { startUploads(pair, baseUrl) }
sendButton = button("选择传输文件").apply {
isEnabled = connectedBaseUrl != null
setOnClickListener {
if (selectedFiles.isEmpty()) showFileSelection(pair, baseUrl)
else startUploads(pair, baseUrl)
}
}
addView(sendButton, matchWrap(top = 14))
})
@@ -750,7 +778,13 @@ class MainActivity : ComponentActivity() {
root.addView(space(18))
root.addView(card().apply {
addView(text("扫码配置已完成", 17f, SUCCESS, true))
addView(text("电脑已自动确认会话,正在通过本地网络直接传输。", 14f, MUTED), matchWrap(top = 8))
addView(text(
if (total >= 32L * 1024L * 1024L)
"连接将保持到返回首页;正在通过本地网络进行最高 8 路并行直传。"
else
"连接将保持到返回首页;正在通过本地网络直接传输。",
14f, MUTED,
), matchWrap(top = 8))
addView(text(fileName, 15f, Color.WHITE), matchWrap(top = 12))
addView(text(humanBytes(total), 13f, MUTED), matchWrap(top = 4))
})
@@ -765,23 +799,33 @@ class MainActivity : ComponentActivity() {
setContentView(ScrollView(this).apply { setBackgroundColor(BG); addView(root) })
downloadRunning = true
transferAbortReason = null
transferExecutor.execute {
// 「传输 / 校验 / 保存」三个阶段各自的速率含义不同,
// 每进入一个新阶段就重新计时,否则显示出来的速率毫无意义。
var phaseLabel = "正在接收"
var phaseStartedAt = android.os.SystemClock.elapsedRealtime()
try {
val startedAt = android.os.SystemClock.elapsedRealtime()
val saved = DownloadClient.download(
context = this@MainActivity,
resolver = contentResolver,
network = connectedNetwork,
networkProvider = { connectedNetwork },
baseUrl = baseUrl,
pairing = pair,
deviceName = receiverDeviceLabel,
abortReason = { transferAbortReason },
onPhase = { label ->
phaseLabel = label
phaseStartedAt = android.os.SystemClock.elapsedRealtime()
runOnUiThread { status.text = label }
},
) { received, expected ->
runOnUiThread {
val fraction = if (expected <= 0) 0 else ((received * 1000L) / expected).toInt().coerceIn(0, 1000)
val elapsed = (android.os.SystemClock.elapsedRealtime() - startedAt).coerceAtLeast(1L)
val elapsed = (android.os.SystemClock.elapsedRealtime() - phaseStartedAt).coerceAtLeast(1L)
val rate = received * 1000.0 / elapsed
bar.progress = fraction
status.text = "${humanBytes(received)} / ${humanBytes(expected)} · ${humanBytes(rate.toLong())}/s"
status.text = "$phaseLabel ${humanBytes(received)} / ${humanBytes(expected)} · ${humanBytes(rate.toLong())}/s"
}
}
runOnUiThread {
@@ -792,7 +836,9 @@ class MainActivity : ComponentActivity() {
} catch (e: Exception) {
runOnUiThread {
downloadRunning = false
showPairError(pair, "从电脑接收失败:${e.message}")
// 落盘失败时文件其实已经完整收到了,别再说「接收失败」误导用户
val prefix = if (e is DownloadClient.SaveFailure) "保存失败" else "从电脑接收失败"
showPairError(pair, "$prefix:${e.message}")
}
} finally {
downloadRunning = false
@@ -800,10 +846,118 @@ class MainActivity : ComponentActivity() {
}
}
private fun showReceivedFiles(message: String? = null) {
val root = pageColumn()
root.addView(text("接收文件柜", 28f, Color.WHITE, true))
root.addView(text("QFT 已保存到 Downloads/QFT 的文件", 14f, MUTED))
message?.let { root.addView(text(it, 13f, WARNING), matchWrap(top = 10)) }
root.addView(space(16))
val files = try {
ReceivedFileCabinet.list(this)
} catch (e: Exception) {
emptyList()
}
if (files.isEmpty()) {
root.addView(card().apply {
addView(text("文件柜为空", 17f, Color.WHITE, true))
addView(text("完成电脑下发或光学接收后,文件会自动出现在这里。", 14f, MUTED), matchWrap(top = 8))
})
} else {
root.addView(text("共 ${files.size} 个文件", 13f, ACCENT, true))
files.forEach { file ->
val entry = card()
entry.addView(text(file.name, 16f, Color.WHITE, true))
entry.addView(
text("${humanBytes(file.size)} · ${file.mimeType.ifBlank { "未知格式" }}", 12f, MUTED),
matchWrap(top = 5),
)
entry.addView(button("打开文件").apply {
setOnClickListener {
try {
ReceivedFileCabinet.open(this@MainActivity, file)
} catch (e: Exception) {
showReceivedFiles("无法打开 ${file.name}:请安装支持该格式的阅读器。")
}
}
}, matchWrap(top = 10))
root.addView(entry, matchWrap(bottom = 10))
}
}
root.addView(space(12))
root.addView(button("返回首页").apply { setOnClickListener { showHome() } })
setContentView(ScrollView(this).apply { setBackgroundColor(BG); addView(root) })
}
private fun showFileSelection(pair: PairingPayload, baseUrl: String) {
managingFilesForPair = pair
managingFilesForBaseUrl = baseUrl
val root = pageColumn()
root.addView(text("选择发送文件", 28f, Color.WHITE, true))
root.addView(text("可多次添加文件,并在列表中单独移除。", 14f, MUTED))
root.addView(space(14))
val total = selectedFiles.sumOf { it.size }
root.addView(card().apply {
addView(text("已选 ${selectedFiles.size} 个 · ${humanBytes(total)}", 16f, ACCENT, true))
if (selectedFiles.isEmpty()) {
addView(text("请先选择需要传输的文件", 14f, WARNING), matchWrap(top = 8))
} else {
selectedFiles.toList().forEach { file ->
val row = LinearLayout(this@MainActivity).apply {
orientation = LinearLayout.HORIZONTAL
gravity = Gravity.CENTER_VERTICAL
}
row.addView(
text("${file.name}\n${humanBytes(file.size)}", 14f, Color.WHITE),
LinearLayout.LayoutParams(0, -2, 1f).apply { marginEnd = dp(8) },
)
row.addView(button("移除").apply {
setOnClickListener {
selectedFiles.removeAll { it.uri == file.uri }
showFileSelection(pair, baseUrl)
}
}, LinearLayout.LayoutParams(dp(82), dp(44)))
addView(row, matchWrap(top = 10))
}
}
})
root.addView(space(14))
root.addView(button("添加文件(可多选)").apply {
setOnClickListener { pickFiles.launch(arrayOf("*/*")) }
})
if (selectedFiles.isNotEmpty()) {
root.addView(space(10))
root.addView(button("清空选择").apply {
setOnClickListener {
selectedFiles.clear()
showFileSelection(pair, baseUrl)
}
})
}
root.addView(space(10))
root.addView(button("完成并返回传输").apply {
isEnabled = selectedFiles.isNotEmpty()
setOnClickListener {
managingFilesForPair = null
managingFilesForBaseUrl = null
showSendReady(pair, baseUrl)
}
})
root.addView(space(10))
root.addView(button("取消并返回传输").apply {
setOnClickListener {
managingFilesForPair = null
managingFilesForBaseUrl = null
showSendReady(pair, baseUrl)
}
})
setContentView(ScrollView(this).apply { setBackgroundColor(BG); addView(root) })
}
private fun renderSelectedFiles() {
val total = selectedFiles.sumOf { it.size }
sendFilesText?.text = if (selectedFiles.isEmpty()) {
"尚未选择文件"
"请先选择需要传输的文件"
} else {
buildString {
selectedFiles.take(8).forEach { append("• ${it.name} ${humanBytes(it.size)}\n") }
@@ -811,11 +965,17 @@ class MainActivity : ComponentActivity() {
append("共 ${selectedFiles.size} 个 · ${humanBytes(total)}")
}.trim()
}
sendButton?.isEnabled = selectedFiles.isNotEmpty() && connectedBaseUrl != null
sendButton?.text = if (selectedFiles.isEmpty()) "选择传输文件" else "开始传输"
sendButton?.isEnabled = connectedBaseUrl != null
}
private fun startUploads(pair: PairingPayload, baseUrl: String) {
if (selectedFiles.isEmpty()) return
if (selectedFiles.isEmpty()) {
sendStatusText?.setTextColor(WARNING)
sendStatusText?.text = "请先选择需要传输的文件"
showFileSelection(pair, baseUrl)
return
}
val files = selectedFiles.toList()
sendButton?.isEnabled = false
transferExecutor.execute {
@@ -828,11 +988,12 @@ class MainActivity : ComponentActivity() {
}
UploadClient.upload(
resolver = contentResolver,
network = connectedNetwork,
networkProvider = { connectedNetwork },
baseUrl = baseUrl,
pairing = pair,
deviceName = receiverDeviceLabel,
file = file,
abortReason = { transferAbortReason },
) { sent, total ->
runOnUiThread {
val p = if (total == 0L) 1000 else ((sent.toDouble() / total) * 1000).toInt().coerceIn(0, 1000)
@@ -0,0 +1,102 @@
package com.qft.optical
import android.content.ContentResolver
import android.content.ContentUris
import android.content.Context
import android.content.Intent
import android.net.Uri
import android.os.Build
import android.os.Environment
import android.provider.MediaStore
import android.webkit.MimeTypeMap
import androidx.core.content.FileProvider
import java.io.File
data class ReceivedFile(
val uri: Uri,
val name: String,
val size: Long,
val mimeType: String,
val modifiedAtSeconds: Long,
)
/** Lists only the files QFT has finished writing to Downloads/QFT. */
object ReceivedFileCabinet {
private const val RELATIVE_QFT_PATH = "Download/QFT/"
fun list(context: Context): List<ReceivedFile> =
if (Build.VERSION.SDK_INT >= 29) listModern(context.contentResolver) else listLegacy(context)
fun open(context: Context, file: ReceivedFile) {
val resolvedMime = mimeFor(file.name, file.mimeType)
val intent = Intent(Intent.ACTION_VIEW)
.setDataAndType(file.uri, resolvedMime)
.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
context.startActivity(Intent.createChooser(intent, "打开 ${file.name}"))
}
private fun listModern(resolver: ContentResolver): List<ReceivedFile> {
val projection = arrayOf(
MediaStore.Downloads._ID,
MediaStore.Downloads.DISPLAY_NAME,
MediaStore.Downloads.SIZE,
MediaStore.Downloads.MIME_TYPE,
MediaStore.Downloads.DATE_MODIFIED,
)
val out = mutableListOf<ReceivedFile>()
resolver.query(
MediaStore.Downloads.EXTERNAL_CONTENT_URI,
projection,
"${MediaStore.Downloads.RELATIVE_PATH}=? AND ${MediaStore.Downloads.IS_PENDING}=0",
arrayOf(RELATIVE_QFT_PATH),
"${MediaStore.Downloads.DATE_MODIFIED} DESC",
)?.use { cursor ->
val idIndex = cursor.getColumnIndexOrThrow(MediaStore.Downloads._ID)
val nameIndex = cursor.getColumnIndexOrThrow(MediaStore.Downloads.DISPLAY_NAME)
val sizeIndex = cursor.getColumnIndexOrThrow(MediaStore.Downloads.SIZE)
val mimeIndex = cursor.getColumnIndexOrThrow(MediaStore.Downloads.MIME_TYPE)
val timeIndex = cursor.getColumnIndexOrThrow(MediaStore.Downloads.DATE_MODIFIED)
while (cursor.moveToNext()) {
val id = cursor.getLong(idIndex)
val name = cursor.getString(nameIndex).orEmpty().ifBlank { "未命名文件" }
out += ReceivedFile(
uri = ContentUris.withAppendedId(MediaStore.Downloads.EXTERNAL_CONTENT_URI, id),
name = name,
size = cursor.getLong(sizeIndex).coerceAtLeast(0L),
mimeType = cursor.getString(mimeIndex).orEmpty(),
modifiedAtSeconds = cursor.getLong(timeIndex),
)
}
}
return out
}
@Suppress("DEPRECATION")
private fun listLegacy(context: Context): List<ReceivedFile> {
val directory = File(
Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS),
"QFT",
)
return directory.listFiles()
?.asSequence()
?.filter { it.isFile }
?.sortedByDescending { it.lastModified() }
?.map { file ->
ReceivedFile(
uri = FileProvider.getUriForFile(context, "${context.packageName}.files", file),
name = file.name,
size = file.length().coerceAtLeast(0L),
mimeType = mimeFor(file.name, ""),
modifiedAtSeconds = file.lastModified() / 1000L,
)
}
?.toList()
.orEmpty()
}
private fun mimeFor(name: String, supplied: String): String {
if (supplied.isNotBlank() && supplied != "application/octet-stream") return supplied
val extension = name.substringAfterLast('.', "").lowercase()
return MimeTypeMap.getSingleton().getMimeTypeFromExtension(extension) ?: "application/octet-stream"
}
}
@@ -5,6 +5,7 @@ import android.database.Cursor
import android.net.Network
import android.net.Uri
import android.provider.OpenableColumns
import android.util.Log
import org.json.JSONObject
import java.io.FileInputStream
import java.net.DatagramPacket
@@ -19,25 +20,27 @@ import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit
import java.util.concurrent.atomic.AtomicInteger
import java.util.concurrent.atomic.AtomicLong
import java.util.UUID
data class SelectedFile(
val uri: Uri,
val name: String,
val size: Long,
val uploadKey: String = UUID.randomUUID().toString(),
)
object UploadClient {
private const val TAG = "QftUpload"
private const val DISCOVERY_PORT = 39392
private const val CHUNK_SMALL = 4L * 1024L * 1024L
private const val CHUNK_DEFAULT = 8L * 1024L * 1024L
private const val CHUNK_LARGE = 16L * 1024L * 1024L
private const val MAX_WORKERS = 8
private const val MIN_PARALLEL_CHUNK = 64L * 1024L
private const val MAX_PARALLEL_CHUNK = 16L * 1024L * 1024L
private const val STREAM_BUFFER = 1024 * 1024
// QFT Direct can briefly reset a TCP flow while the Android network route
// settles. Chunk PUTs and the init/finish control calls are safe to retry;
// the Windows receiver treats a repeated chunk as an idempotent success.
private const val LOCAL_REQUEST_ATTEMPTS = 3
private const val LOCAL_REQUEST_ATTEMPTS = 8
fun describeFile(resolver: ContentResolver, uri: Uri): SelectedFile? {
var name = "qft-upload.bin"
@@ -215,16 +218,17 @@ object UploadClient {
fun upload(
resolver: ContentResolver,
network: Network?,
networkProvider: () -> Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
file: SelectedFile,
abortReason: () -> String? = { null },
onProgress: (sent: Long, total: Long) -> Unit,
) {
if (pairing.version >= 2 && isSeekable(resolver, file)) {
try {
uploadParallel(resolver, network, baseUrl, pairing, deviceName, file, onProgress)
uploadParallel(resolver, networkProvider, baseUrl, pairing, deviceName, file, abortReason, onProgress)
return
} catch (e: Exception) {
// Never mask a transient v2 failure by immediately switching to a
@@ -236,50 +240,90 @@ object UploadClient {
if (!message.contains("HTTP 404") && !message.contains("HTTP 501")) throw e
}
}
uploadLegacy(resolver, network, baseUrl, pairing, deviceName, file, onProgress)
Log.i(TAG, "using compatibility single-stream upload: size=${file.size}, endpoint=$baseUrl")
uploadLegacy(resolver, networkProvider(), baseUrl, pairing, deviceName, file, abortReason, onProgress)
}
private data class InitReply(val uploadId: String, val chunkSize: Long, val totalChunks: Int)
private data class InitReply(
val uploadId: String,
val chunkSize: Long,
val totalChunks: Int,
val pendingChunks: IntArray,
)
private fun <T> retryLocalRequest(label: String, block: () -> T): T {
private fun <T> retryLocalRequest(label: String, abortReason: () -> String?, block: () -> T): T {
var last: Throwable? = null
repeat(LOCAL_REQUEST_ATTEMPTS) { attempt ->
abortReason()?.let { throw IllegalStateException(it, last) }
try {
return block()
} catch (e: Throwable) {
last = e
Log.w(
TAG,
"$label: attempt=${attempt + 1}/$LOCAL_REQUEST_ATTEMPTS, ${failureSummary(e)}",
e,
)
if (attempt + 1 < LOCAL_REQUEST_ATTEMPTS) {
try { Thread.sleep(120L * (attempt + 1)) } catch (_: InterruptedException) {
try { Thread.sleep((250L shl attempt).coerceAtMost(3_000L)) } catch (_: InterruptedException) {
Thread.currentThread().interrupt()
throw e
}
}
}
}
throw IllegalStateException("$label after $LOCAL_REQUEST_ATTEMPTS attempts", last)
val failure = last ?: IllegalStateException("unknown local request failure")
throw IllegalStateException(
"$label,已重试 $LOCAL_REQUEST_ATTEMPTS 次:${failureSummary(failure)}",
failure,
)
}
private fun failureSummary(error: Throwable): String {
val chain = ArrayList<String>(3)
var current: Throwable? = error
while (current != null && chain.size < 3) {
val type = current.javaClass.simpleName.ifBlank { current.javaClass.name }
val detail = current.message?.replace(Regex("\\s+"), " ")?.take(240)
chain += if (detail.isNullOrBlank()) type else "$type: $detail"
current = current.cause
}
return chain.joinToString(" <- ")
}
private fun uploadParallel(
resolver: ContentResolver,
network: Network?,
networkProvider: () -> Network?,
baseUrl: String,
pairing: PairingPayload,
deviceName: String,
file: SelectedFile,
abortReason: () -> String?,
onProgress: (sent: Long, total: Long) -> Unit,
) {
val init = initUpload(network, baseUrl, pairing, deviceName, file)
Log.i(TAG, "parallel init: size=${file.size}, endpoint=$baseUrl")
val init = initUpload(networkProvider, baseUrl, pairing, deviceName, file, file.uploadKey, abortReason)
Log.i(TAG, "parallel init complete: chunks=${init.totalChunks}, pending=${init.pendingChunks.size}, chunkSize=${init.chunkSize}")
if (init.totalChunks == 0) {
finishUpload(network, baseUrl, pairing, deviceName, init.uploadId)
finishUpload(networkProvider, baseUrl, pairing, deviceName, init.uploadId, abortReason)
onProgress(0, 0)
return
}
val cpuWorkers = Runtime.getRuntime().availableProcessors().coerceIn(2, MAX_WORKERS)
val workerCount = init.totalChunks.coerceAtMost(cpuWorkers).coerceAtLeast(1)
// Upload workers are network/disk bound, not CPU bound. Large files
// therefore use all eight lanes even on a 4-core phone.
if (init.pendingChunks.isEmpty()) {
finishUpload(networkProvider, baseUrl, pairing, deviceName, init.uploadId, abortReason)
onProgress(file.size, file.size)
return
}
val workerCount = init.pendingChunks.size.coerceAtMost(MAX_WORKERS).coerceAtLeast(1)
val pool = Executors.newFixedThreadPool(workerCount)
val next = AtomicInteger(0)
val sent = AtomicLong(0)
val pendingBytes = init.pendingChunks.sumOf { index ->
minOf(init.chunkSize, file.size - index.toLong() * init.chunkSize)
}
val sent = AtomicLong((file.size - pendingBytes).coerceAtLeast(0L))
val lastReport = AtomicLong(0)
val failures = mutableListOf<Throwable>()
val futures = (0 until workerCount).map {
@@ -289,13 +333,15 @@ object UploadClient {
val channel = input.channel
val buffer = ByteBuffer.allocate(STREAM_BUFFER)
while (!Thread.currentThread().isInterrupted) {
val index = next.getAndIncrement()
if (index >= init.totalChunks) break
abortReason()?.let { error(it) }
val pendingIndex = next.getAndIncrement()
if (pendingIndex >= init.pendingChunks.size) break
val index = init.pendingChunks[pendingIndex]
val offset = index.toLong() * init.chunkSize
val length = minOf(init.chunkSize, file.size - offset)
sendChunk(
network, baseUrl, pairing, deviceName,
init.uploadId, index, channel, offset, length, buffer,
networkProvider, baseUrl, pairing, deviceName,
init.uploadId, index, channel, offset, length, buffer, abortReason,
)
val totalSent = sent.addAndGet(length)
val now = android.os.SystemClock.elapsedRealtime()
@@ -316,22 +362,25 @@ object UploadClient {
pool.shutdownNow()
}
if (failures.isNotEmpty()) throw failures.first()
finishUpload(network, baseUrl, pairing, deviceName, init.uploadId)
finishUpload(networkProvider, baseUrl, pairing, deviceName, init.uploadId, abortReason)
onProgress(file.size, file.size)
}
private fun desiredChunkSize(fileSize: Long): Long = when {
fileSize < 32L * 1024L * 1024L -> CHUNK_SMALL
fileSize >= 512L * 1024L * 1024L -> CHUNK_LARGE
else -> CHUNK_DEFAULT
private fun desiredChunkSize(fileSize: Long): Long {
if (fileSize <= 0L) return MIN_PARALLEL_CHUNK
// Aim for eight independent HTTP flows on every transferable file.
// The floor keeps QR Direct overhead reasonable for tiny files, while
// the ceiling protects memory and TCP fairness on very large files.
return ((fileSize + MAX_WORKERS - 1) / MAX_WORKERS)
.coerceIn(MIN_PARALLEL_CHUNK, MAX_PARALLEL_CHUNK)
}
private fun initUpload(
network: Network?, baseUrl: String, pairing: PairingPayload,
deviceName: String, file: SelectedFile,
): InitReply = retryLocalRequest("本地上传初始化失败") {
val conn = open(network, URL("$baseUrl/qft/upload/init"))
networkProvider: () -> Network?, baseUrl: String, pairing: PairingPayload,
deviceName: String, file: SelectedFile, requestKey: String, abortReason: () -> String?,
): InitReply = retryLocalRequest("本地上传初始化失败", abortReason) {
val conn = open(networkProvider(), URL("$baseUrl/qft/upload/init"))
try {
conn.requestMethod = "POST"
conn.doOutput = true
@@ -342,15 +391,27 @@ object UploadClient {
conn.setRequestProperty("X-QFT-Filename", b64(file.name))
conn.setRequestProperty("X-QFT-Size", file.size.toString())
conn.setRequestProperty("X-QFT-Chunk-Size", desiredChunkSize(file.size).toString())
conn.setRequestProperty("X-QFT-Upload-Key", requestKey)
conn.outputStream.close()
val code = conn.responseCode
if (code != 200) error("初始化并行上传失败 HTTP $code")
val body = conn.inputStream.bufferedReader().use { it.readText() }
val obj = JSONObject(body)
val totalChunks = obj.getInt("total_chunks")
val missing = obj.optJSONArray("missing")
val pending = if (missing == null) {
IntArray(totalChunks) { it }
} else {
IntArray(missing.length()) { missing.getInt(it) }
}
if (pending.any { it !in 0 until totalChunks } || pending.distinct().size != pending.size) {
error("电脑返回了无效的缺块列表")
}
InitReply(
uploadId = obj.getString("upload_id"),
chunkSize = obj.getLong("chunk_size"),
totalChunks = obj.getInt("total_chunks"),
totalChunks = totalChunks,
pendingChunks = pending,
)
} finally {
conn.disconnect()
@@ -358,16 +419,17 @@ object UploadClient {
}
private fun sendChunk(
network: Network?, baseUrl: String, pairing: PairingPayload, deviceName: String,
networkProvider: () -> Network?, baseUrl: String, pairing: PairingPayload, deviceName: String,
uploadId: String, index: Int, channel: FileChannel, offset: Long, length: Long,
buffer: ByteBuffer,
) = retryLocalRequest("分块 $index 上传失败") {
val conn = open(network, URL("$baseUrl/qft/upload/chunk/$uploadId/$index"))
buffer: ByteBuffer, abortReason: () -> String?,
) = retryLocalRequest("分块 $index 上传失败", abortReason) {
Log.d(TAG, "chunk start: index=$index, bytes=$length, endpoint=$baseUrl")
val conn = open(networkProvider(), URL("$baseUrl/qft/upload/chunk/$uploadId/$index"))
try {
conn.requestMethod = "POST"
conn.doOutput = true
conn.connectTimeout = 4_000
conn.readTimeout = 15_000
conn.connectTimeout = 8_000
conn.readTimeout = 90_000
conn.setFixedLengthStreamingMode(length)
conn.setRequestProperty("Content-Type", "application/octet-stream")
commonHeaders(conn, pairing, deviceName)
@@ -376,6 +438,7 @@ object UploadClient {
var remaining = length
val array = buffer.array()
while (remaining > 0) {
abortReason()?.let { error(it) }
buffer.clear()
buffer.limit(minOf(array.size.toLong(), remaining).toInt())
val n = channel.read(buffer)
@@ -391,16 +454,17 @@ object UploadClient {
error("分块 $index 上传失败 HTTP $code${message?.let { ": $it" } ?: ""}")
}
try { conn.inputStream.close() } catch (_: Exception) {}
Log.d(TAG, "chunk complete: index=$index, bytes=$length")
} finally {
conn.disconnect()
}
}
private fun finishUpload(
network: Network?, baseUrl: String, pairing: PairingPayload,
deviceName: String, uploadId: String,
) = retryLocalRequest("本地上传完成确认失败") {
val conn = open(network, URL("$baseUrl/qft/upload/finish/$uploadId"))
networkProvider: () -> Network?, baseUrl: String, pairing: PairingPayload,
deviceName: String, uploadId: String, abortReason: () -> String?,
) = retryLocalRequest("本地上传完成确认失败", abortReason) {
val conn = open(networkProvider(), URL("$baseUrl/qft/upload/finish/$uploadId"))
try {
conn.requestMethod = "POST"
conn.doOutput = true
@@ -427,6 +491,7 @@ object UploadClient {
pairing: PairingPayload,
deviceName: String,
file: SelectedFile,
abortReason: () -> String?,
onProgress: (sent: Long, total: Long) -> Unit,
) {
val conn = open(network, URL("$baseUrl/qft/upload"))
@@ -447,6 +512,7 @@ object UploadClient {
var sent = 0L
var lastReport = 0L
while (true) {
abortReason()?.let { error(it) }
val n = input.read(buf)
if (n <= 0) break
output.write(buf, 0, n)
@@ -489,7 +555,7 @@ object UploadClient {
private fun commonHeaders(conn: HttpURLConnection, pairing: PairingPayload, deviceName: String) {
conn.useCaches = false
conn.setRequestProperty("Connection", "close")
conn.setRequestProperty("Connection", "keep-alive")
conn.setRequestProperty("X-QFT-Token", pairing.session)
conn.setRequestProperty("X-QFT-Device", b64(deviceName))
}
@@ -26,53 +26,91 @@ class WifiConnector(context: Context) {
private val wifiManager = appContext.getSystemService(Context.WIFI_SERVICE) as WifiManager
private val handler = Handler(Looper.getMainLooper())
private var callback: ConnectivityManager.NetworkCallback? = null
@Volatile private var currentNetwork: Network? = null
private var generation = 0
private var legacyPreviousNetworkId: Int? = null
private var legacyTargetNetworkId: Int? = null
/**
* 回调经由这个可替换的收件人转发,而不是被 NetworkCallback 闭包捕获。
* 这样「用户点重试」时可以直接换掉 UI 回调、继续复用那个还挂着的
* WifiNetworkSpecifier 请求,不必 unregister —— 在系统选网弹窗还开着的
* 时候 unregister,Android 会弹「该应用已取消选择设备的请求」。
*/
private class Listener(
val onStatus: (String) -> Unit,
val onAvailable: (Network?) -> Unit,
val onUnavailable: (String) -> Unit,
)
private var listener: Listener? = null
private var pendingSsid: String? = null
private var pendingDelivered: AtomicBoolean? = null
private var pendingTerminal: AtomicBoolean? = null
private var pendingStartedAt = 0L
// 所有对外回调都只走这三个入口。直接调用捕获来的闭包会在「复用挂起请求」
// 时通知到上一次的界面,是很难查的一类 bug。
private fun notifyStatus(message: String) { listener?.onStatus?.invoke(message) }
private fun notifyAvailable(network: Network?) { listener?.onAvailable?.invoke(network) }
private fun notifyUnavailable(message: String) { listener?.onUnavailable?.invoke(message) }
fun connect(
pairing: PairingPayload,
onStatus: (String) -> Unit,
onAvailable: (Network?) -> Unit,
onUnavailable: (String) -> Unit,
) {
val wifi = pairing.wifi
// 同一个 SSID 的请求还挂在系统那里且没有终结:换掉 UI 回调即可,
// 千万不要 unregister 再重新 requestNetwork。
if (wifi != null && callback != null && pendingSsid == wifi.ssid &&
pendingTerminal?.get() == false) {
Log.i(TAG, "reuse outstanding request SSID=${wifi.ssid}")
listener = Listener(onStatus, onAvailable, onUnavailable)
val active = currentNetwork
if (active != null) {
notifyStatus("QFT 本地网络仍保持连接")
notifyAvailable(active)
} else {
notifyStatus("系统配网请求仍在进行中,正在自动恢复连接…")
scheduleWaitHints(generation, wifi.ssid)
}
return
}
release(restoreLegacy = false)
generation++
val run = generation
val wifi = pairing.wifi
listener = Listener(onStatus, onAvailable, onUnavailable)
if (wifi == null) {
onStatus("正在使用当前局域网发现电脑…")
notifyStatus("正在使用当前局域网发现电脑…")
val wifiNetwork = bestWifiNetwork()
onAvailable(wifiNetwork ?: connectivity.activeNetwork)
currentNetwork = wifiNetwork ?: connectivity.activeNetwork
notifyAvailable(currentNetwork)
return
}
if (Build.VERSION.SDK_INT >= 29) {
connectModern(run, wifi, onStatus, onAvailable, onUnavailable)
connectModern(run, wifi)
} else {
connectLegacy(run, wifi, onStatus, onAvailable, onUnavailable)
connectLegacy(run, wifi)
}
}
@RequiresApi(29)
@Suppress("MissingPermission")
private fun connectModern(
run: Int,
wifi: WifiCredentials,
onStatus: (String) -> Unit,
onAvailable: (Network?) -> Unit,
onUnavailable: (String) -> Unit,
) {
onStatus("正在请求连接 ${wifi.ssid}…")
private fun connectModern(run: Int, wifi: WifiCredentials) {
Log.i(TAG, "attempt=$run request SSID=${wifi.ssid}")
onStatus("正在等待 Android 系统连接确认;确认后本页将继续显示进度")
notifyStatus("正在等待 Android 系统连接确认;确认后本页将继续显示进度")
val specifier = try {
WifiNetworkSpecifier.Builder()
.setSsid(wifi.ssid)
.setWpa2Passphrase(wifi.passphrase)
.build()
} catch (e: Exception) {
onUnavailable("配网参数无效:${e.message}")
notifyUnavailable("配网参数无效:${e.message}")
return
}
val request = NetworkRequest.Builder()
@@ -86,39 +124,66 @@ class WifiConnector(context: Context) {
// launching a duplicate probe/download for the same Wi-Fi connection.
val delivered = AtomicBoolean(false)
val terminal = AtomicBoolean(false)
pendingSsid = wifi.ssid
pendingDelivered = delivered
pendingTerminal = terminal
pendingStartedAt = SystemClock.elapsedRealtime()
val startedAt = pendingStartedAt
val cb = object : ConnectivityManager.NetworkCallback() {
override fun onAvailable(network: Network) {
if (run != generation || terminal.get()) return
currentNetwork = network
Log.i(TAG, "attempt=$run framework onAvailable network=$network")
onStatus("Wi-Fi 已关联,正在等待本地 IP/路由…")
waitUntilUsable(run, network, onStatus) {
if (run == generation && !terminal.get() && delivered.compareAndSet(false, true)) {
notifyStatus("Wi-Fi 已关联,正在等待本地 IP/路由…")
waitUntilUsable(run, network, ::notifyStatus) {
if (run == generation && !terminal.get() && currentNetwork == network &&
delivered.compareAndSet(false, true)) {
Log.i(TAG, "attempt=$run route ready network=$network")
onStatus("QFT 本地网络已就绪,正在快速发现电脑…")
onAvailable(network)
notifyStatus("QFT 本地网络已就绪,正在快速发现电脑…")
notifyAvailable(network)
}
}
}
override fun onLinkPropertiesChanged(network: Network, linkProperties: LinkProperties) {
if (run != generation || terminal.get() || delivered.get()) return
if (run != generation || terminal.get() || delivered.get() || currentNetwork != network) return
if (hasIpv4(linkProperties) && delivered.compareAndSet(false, true)) {
currentNetwork = network
Log.i(TAG, "attempt=$run IPv4 ready network=$network")
onStatus("QFT 本地网络已就绪,正在快速发现电脑…")
onAvailable(network)
notifyStatus("QFT 本地网络已就绪,正在快速发现电脑…")
notifyAvailable(network)
}
}
override fun onUnavailable() {
if (run != generation || !terminal.compareAndSet(false, true)) return
Log.w(TAG, "attempt=$run framework onUnavailable")
if (run == generation) onUnavailable("未能连接 QFT 临时网络。请确认 Wi-Fi 已开启并批准系统连接请求。")
currentNetwork = null
val waited = SystemClock.elapsedRealtime() - startedAt
Log.w(TAG, "attempt=$run framework onUnavailable after ${waited}ms")
// Android 不区分「用户点了取消」和「始终没扫到这个热点」,
// 只能用等待时长推断,给出真正能指导用户下一步的提示。
notifyUnavailable(
if (waited < 4_000L) {
"已取消系统配网。请重新点击「重试连接」,并在系统弹窗里选择 ${wifi.ssid} 后点连接。"
} else {
"系统始终没有搜索到热点 ${wifi.ssid}。请确认:" +
"① 电脑上 QFT 接收页仍开着且显示 Direct 已启动;" +
"② 手机 Wi-Fi 列表里能看到这个名字;" +
"③ 电脑与手机距离不要太远。"
}
)
}
override fun onLost(network: Network) {
if (run != generation || !delivered.get() || !terminal.compareAndSet(false, true)) return
if (run != generation || terminal.get() || currentNetwork != network) return
Log.w(TAG, "attempt=$run network lost network=$network")
if (run == generation && delivered.get()) onUnavailable("QFT 临时网络已断开")
currentNetwork = null
delivered.set(false)
// requestNetwork stays registered. Android can therefore
// deliver a replacement Network without another system picker;
// range/chunk retries wait for and then use that new handle.
notifyStatus("QFT 网络短暂波动,正在保持会话并自动恢复…")
}
}
callback = cb
@@ -130,26 +195,37 @@ class WifiConnector(context: Context) {
// system sheet; otherwise keep this request alive while our page
// continues to show connection progress.
connectivity.requestNetwork(request, cb)
handler.postDelayed({
if (run == generation && !terminal.get() && !delivered.get()) {
onStatus("仍在等待系统完成配网…")
}
}, 8_000)
scheduleWaitHints(run, wifi.ssid)
} catch (e: Exception) {
callback = null
onUnavailable("系统配网请求失败:${e.message}")
pendingSsid = null
notifyUnavailable("系统配网请求失败:${e.message}")
}
}
/**
* 弹窗久久不出结果时逐级给出更具体的提示。
* 截图里那种「弹窗一直转圈」的情况,光说「仍在等待系统完成配网」
* 完全没有指导意义——真正的原因通常是电脑侧热点没起来。
*/
private fun scheduleWaitHints(run: Int, ssid: String) {
fun pending(): Boolean =
run == generation && pendingTerminal?.get() == false && pendingDelivered?.get() == false
handler.postDelayed({
if (pending()) listener?.onStatus?.invoke("仍在等待系统完成配网…")
}, 8_000)
handler.postDelayed({
if (pending()) listener?.onStatus?.invoke(
"系统仍在搜索 $ssid。若弹窗里一直没出现这个名字," +
"多半是电脑侧热点没启动——请检查 Windows 上 QFT 接收页是否显示 Direct 已就绪。"
)
}, 20_000)
}
@Suppress("DEPRECATION", "MissingPermission")
private fun connectLegacy(
run: Int,
wifi: WifiCredentials,
onStatus: (String) -> Unit,
onAvailable: (Network?) -> Unit,
onUnavailable: (String) -> Unit,
) {
onStatus("Android ${Build.VERSION.RELEASE} 兼容配网:正在连接 ${wifi.ssid}…")
private fun connectLegacy(run: Int, wifi: WifiCredentials) {
notifyStatus("Android ${Build.VERSION.RELEASE} 兼容配网:正在连接 ${wifi.ssid}…")
try {
if (!wifiManager.isWifiEnabled) {
wifiManager.isWifiEnabled = true
@@ -168,13 +244,13 @@ class WifiConnector(context: Context) {
wifiManager.addNetwork(config)
}
if (targetId < 0) {
onUnavailable("Android 7~9 无法写入 QFT Wi-Fi 配置;请确认已授予位置权限。")
notifyUnavailable("Android 7~9 无法写入 QFT Wi-Fi 配置;请确认已授予位置权限。")
return
}
legacyTargetNetworkId = targetId
wifiManager.disconnect()
if (!wifiManager.enableNetwork(targetId, true)) {
onUnavailable("系统拒绝启用 QFT Wi-Fi 网络")
notifyUnavailable("系统拒绝启用 QFT Wi-Fi 网络")
return
}
wifiManager.reconnect()
@@ -186,20 +262,21 @@ class WifiConnector(context: Context) {
if (matches) {
val network = bestWifiNetwork()
if (network != null && hasIpv4(connectivity.getLinkProperties(network))) {
onStatus("QFT Wi-Fi 已连接,正在快速发现电脑…")
onAvailable(network)
notifyStatus("QFT Wi-Fi 已连接,正在快速发现电脑…")
currentNetwork = network
notifyAvailable(network)
return
}
}
if (SystemClock.elapsedRealtime() - started > 15_000) {
onUnavailable("连接 QFT Wi-Fi 超时。请确认电脑热点仍在运行。")
notifyUnavailable("连接 QFT Wi-Fi 超时。请确认电脑热点仍在运行。")
} else {
handler.postDelayed({ poll() }, 250)
}
}
handler.postDelayed({ poll() }, 250)
} catch (e: Exception) {
onUnavailable("Android 7~9 配网失败:${e.message}")
notifyUnavailable("Android 7~9 配网失败:${e.message}")
}
}
@@ -316,6 +393,11 @@ class WifiConnector(context: Context) {
try { connectivity.unregisterNetworkCallback(it) } catch (_: Exception) {}
}
callback = null
currentNetwork = null
listener = null
pendingSsid = null
pendingDelivered = null
pendingTerminal = null
handler.removeCallbacksAndMessages(null)
if (restoreLegacy && Build.VERSION.SDK_INT < 29) {
val previous = legacyPreviousNetworkId
@@ -0,0 +1,4 @@
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
<external-path name="qft_downloads" path="Download/QFT/" />
</paths>
+20 -2
View File
@@ -2586,8 +2586,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
[[package]]
name = "qft-windows"
version = "0.4.0-rc6"
name = "qft-desktop"
version = "0.4.8"
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"
+5 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "qft-windows"
version = "0.4.0-rc6"
name = "qft-desktop"
version = "0.4.8"
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 = [
+798
View File
@@ -0,0 +1,798 @@
//! 桌面端的**发起侧**。
//!
//! 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,
/// 单个文件的总量。多文件发送时 UI 用的是跨文件的累计总量,
/// 因此当前没有读者;保留是为了让回调本身自洽,
/// 单文件场景(如 P2 的目录传输逐项进度)会用到。
#[allow(dead_code)]
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」。
// 供 P1.5 的发现流程与后续的可达性诊断使用,当前 UI 尚未接线
#[allow(dead_code)]
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(&[]),
// 配对只是一次极小的请求,4 秒还没建连基本就是不通了。
// 拖到 10 秒只会让用户以为程序卡死。
Duration::from_secs(4),
)?;
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 塞进多个线程。
// 主线程随后在此轮询上报——早先只在 scope 结束后报一次,
// 结果传 1 GB 的过程中进度条一直是 0%,最后才跳到 100%。
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)?;
}
}));
}
// worker 跑着的时候持续上报,不要等它们全部结束
while !handles.iter().all(|h| h.is_finished()) {
on_progress(Progress {
done: sent.load(Ordering::Relaxed).min(size),
total: size,
});
std::thread::sleep(Duration::from_millis(40));
}
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: size, 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],
sent: &AtomicU64,
) -> Result<()> {
let path = format!("/qft/upload/chunk/{upload_id}/{index}");
// 接收端对重复分块是幂等的,因此重试安全。
// 局域网上首次连接常被 Windows 防火墙首包丢弃,一次重试就能救回来。
let mut last = None;
for attempt in 0..3 {
// 本次尝试写出的字节单独计一份:失败时要从总数里扣回去,
// 否则重试会让进度虚高甚至超过 100%
let attempted = AtomicU64::new(0);
let mut sink = |n: usize| {
attempted.fetch_add(n as u64, Ordering::Relaxed);
sent.fetch_add(n as u64, Ordering::Relaxed);
};
let outcome = send_request_with_progress(
address,
"POST",
&path,
&self.auth_headers(),
Some(body),
Duration::from_secs(60),
Some(&mut sink),
);
drop(sink);
if outcome.is_err() || outcome.as_ref().is_ok_and(|r| r.status != 200) {
sent.fetch_sub(attempted.load(Ordering::Relaxed), Ordering::Relaxed);
}
match outcome {
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 起点。
// PC↔PC 目前只做「推送」,「主动拉取」在 P2 的会话模型里才用得上
#[allow(dead_code)]
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
}
}
#[allow(dead_code)] // 仅被尚未接线的 download_file 使用
fn platform_ensure_dir(path: &Path) -> Result<()> {
crate::platform::ensure_dir(path)
.with_context(|| format!("创建目录 {} 失败", path.display()))
}
/// 把底层 io 错误翻译成能指导下一步的说法。
///
/// 「超时」和「被拒绝」的成因完全不同:前者是包被丢了(防火墙、主机不可达、
/// AP 客户端隔离),后者是端口上没人监听(对方没点"启动接收")。
/// 给用户一句笼统的"连接失败"等于什么都没说。
fn describe_connect_failure(address: SocketAddr, error: &std::io::Error) -> anyhow::Error {
use std::io::ErrorKind;
let ip = address.ip();
match error.kind() {
ErrorKind::TimedOut => anyhow::anyhow!(
"连接 {address} 超时:数据包发出去了但没有任何回应。\n\
常见原因:① 对方电脑的防火墙拦截了入站连接(Windows 上需要放行 qft-desktop.exe 的专用网络);\
② Wi-Fi 开了客户端隔离,同网段设备之间不能互通;\
③ 对方已经关掉接收或换了网络。"
),
ErrorKind::ConnectionRefused => anyhow::anyhow!(
"{ip} 明确拒绝了连接:主机在线,但 {} 端口上没有程序在监听。\n\
请确认对方已经在「我要接收」里点了「启动接收」,并且连接码是最新的那一串。",
address.port()
),
ErrorKind::HostUnreachable | ErrorKind::NetworkUnreachable => anyhow::anyhow!(
"路由不可达:本机没有能到达 {ip} 的路由。请确认两台设备连在同一个网络里。"
),
_ => anyhow::anyhow!("连接 {address} 失败:{error}"),
}
}
// ---------------------------------------------------------------- 极简 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> {
send_request_with_progress(address, method, path, headers, body, timeout, None)
}
/// `on_body_written` 会在请求体每写出一片后被调用。
/// 大文件分块是 16 MiB,若等整块写完才计数,进度条就是一格一格跳的。
fn send_request_with_progress(
address: SocketAddr,
method: &str,
path: &str,
headers: &[(String, String)],
body: Option<&[u8]>,
timeout: Duration,
mut on_body_written: Option<&mut dyn FnMut(usize)>,
) -> Result<HttpResponse> {
let stream = TcpStream::connect_timeout(&address, timeout.min(Duration::from_secs(10)))
.map_err(|e| describe_connect_failure(address, &e))?;
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 {
// 256 KiB 一片:足够小,进度看起来是连续的;
// 又足够大,不会因为频繁 write 拖慢吞吐
const SLICE: usize = 256 * 1024;
for part in body.chunks(SLICE) {
writer.write_all(part)?;
if let Some(sink) = on_body_written.as_deref_mut() {
sink(part.len());
}
}
}
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);
// 走完整的连接码链路:编码 → 用户输入 → 解码 → 换令牌
let code = crate::connect_code::ConnectCode::new(
std::net::IpAddr::V4(std::net::Ipv4Addr::LOCALHOST),
server.port,
server.secret,
);
let typed = code.encode();
let parsed = crate::connect_code::ConnectCode::decode(&typed).expect("连接码应能解析");
assert_eq!(parsed.base_url(), base_url, "码里解出的地址应与实际服务一致");
// 错误秘密必须被拒
assert!(PeerClient::pair(&base_url, "000000", "tester").is_err());
let paired = PeerClient::pair(&base_url, &parsed.secret_hex(), "tester").unwrap();
assert_eq!(paired, token, "配对应返回真实会话令牌");
let client = PeerClient::new(base_url, paired, "tester");
let mut samples: Vec<Progress> = Vec::new();
let sha = client.upload_file(&source, |p| samples.push(p)).unwrap();
let last = *samples.last().expect("至少应有一次进度回调");
assert_eq!(last.done, payload.len() as u64, "进度应抵达文件全长");
// 回环传输太快,采样次数不稳定,这里只断言稳健的性质;
// 「边传边报」的机制由 body_progress_is_reported_incrementally 覆盖。
assert!(
samples.windows(2).all(|w| w[0].done <= w[1].done),
"进度必须单调不减:{samples:?}"
);
assert!(
samples.iter().all(|p| p.done <= payload.len() as u64),
"进度不得超过文件总长(重试重复计数会导致这种情况):{samples:?}"
);
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);
}
}
#[cfg(test)]
mod failure_message_tests {
use super::*;
/// 不可达地址必须给出「超时」类的排查建议,而不是一句空洞的失败。
#[test]
fn unreachable_host_yields_actionable_timeout_message() {
// 192.0.2.0/24 是 RFC 5737 保留的文档用网段,不会有真实主机应答
let error = PeerClient::pair("http://192.0.2.1:39393", "abcdef", "tester")
.expect_err("不可达地址必须失败");
let text = format!("{error:#}");
assert!(text.contains("防火墙") || text.contains("超时") || text.contains("路由"),
"应给出可执行的排查方向,实得:{text}");
}
/// 本机没人监听的端口会被内核直接拒绝,提示必须与"超时"区分开。
#[test]
fn refused_port_says_receiver_not_started() {
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let port = listener.local_addr().unwrap().port();
drop(listener); // 端口随即空出,连接会被拒绝
let error = PeerClient::pair(&format!("http://127.0.0.1:{port}"), "abcdef", "tester")
.expect_err("空端口必须失败");
let text = format!("{error:#}");
assert!(text.contains("启动接收") || text.contains("拒绝"),
"被拒绝时应提示对方没启动接收,实得:{text}");
}
}
#[cfg(test)]
mod progress_tests {
use super::*;
use std::io::{BufRead, Read, Write};
use std::sync::atomic::AtomicUsize;
/// 极简 mock:按 Content-Length 精确读完请求体再应答。
///
/// 不能用 read_to_end——那会一直等到客户端关闭写端,
/// 而客户端此时正在等响应,两边互等直接死锁。
fn serve_once(listener: std::net::TcpListener) -> std::thread::JoinHandle<usize> {
std::thread::spawn(move || {
let Ok((stream, _)) = listener.accept() else { return 0 };
let mut reader = std::io::BufReader::new(stream.try_clone().unwrap());
let mut length = 0usize;
loop {
let mut line = String::new();
if reader.read_line(&mut line).unwrap_or(0) == 0 {
break;
}
if line == "\r\n" || line == "\n" {
break;
}
if let Some((name, value)) = line.split_once(':') {
if name.trim().eq_ignore_ascii_case("content-length") {
length = value.trim().parse().unwrap_or(0);
}
}
}
let mut body = vec![0u8; length];
let _ = reader.read_exact(&mut body);
let mut out = stream;
let _ = out.write_all(
b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\n{}",
);
let _ = out.flush();
length
})
}
/// 锁住「边写边报」这个行为。
///
/// 早先 `on_progress` 只在所有 worker 结束后调用一次,传 1 GB 时
/// 进度条全程 0%、最后才跳到 100%。这里直接验证请求体是分片写出并
/// 逐片上报的——回环速度太快时集成测试采样不到,只有这一层能稳定拦住回归。
#[test]
fn body_progress_is_reported_incrementally() {
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = serve_once(listener);
let body = vec![7u8; 5 * 256 * 1024]; // 正好 5 片
let calls = AtomicUsize::new(0);
let total = AtomicU64::new(0);
let mut sink = |n: usize| {
calls.fetch_add(1, Ordering::Relaxed);
total.fetch_add(n as u64, Ordering::Relaxed);
};
let response = send_request_with_progress(
address, "POST", "/x", &[], Some(&body),
Duration::from_secs(10), Some(&mut sink),
);
drop(sink);
assert!(response.is_ok(), "请求应成功:{:?}", response.err());
assert_eq!(server.join().unwrap(), body.len(), "服务端应收到完整请求体");
assert_eq!(calls.load(Ordering::Relaxed), 5, "5 片体应上报 5 次");
assert_eq!(
total.load(Ordering::Relaxed),
body.len() as u64,
"上报总量应等于请求体长度"
);
}
#[test]
fn no_progress_sink_is_allowed() {
// init/finish/ping 都不需要进度,不传 sink 时不能出问题
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = serve_once(listener);
let result = send_request(address, "POST", "/x", &[], Some(b"hi"), Duration::from_secs(10));
assert!(result.is_ok(), "无 sink 时请求也应成功:{:?}", result.err());
assert_eq!(server.join().unwrap(), 2);
}
}
+425
View File
@@ -0,0 +1,425 @@
//! QFT 连接码:把「去哪连」和「凭什么连」压进一串可口述的短码。
//!
//! 此前 PC↔PC 要用户分别念 IP、端口、6 位配对码三样东西,既啰嗦又容易错。
//! 连接码把它们合成一串,**地址就编在码里**,所以发送方拿到码即可直连,
//! 不需要广播、不需要在同一网段——只要 IP 层路由可达即可。
//! 同一路由器下的不同 VLAN/网段正属于这种情况。
//!
//! 必须说清的边界:连接码解决的是「找不到对方」和「输入太繁琐」。
//! 如果两台机器在 IP 层根本互不可达(AP 客户端隔离、各自在不同的物理网络),
//! 任何客户端侧协议都无法凭空造出可达性,只能换链路或引入第三方中转。
//!
//! 编码
//! ```text
//! byte0 version(3) | kind(3) | default_port(1) | reserved(1)
//! addr 2~4 字节(按 kind 压缩私有网段)或 16 字节(IPv6)
//! port 2 字节,仅当非默认端口时存在
//! secret 3 字节(24 bit)
//! crc 1 字节 CRC-8
//! ```
//! 典型的 `192.168.a.b:39393` 共 7 字节 → Crockford Base32 → **12 个字符**。
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
/// Crockford Base32:去掉了容易混淆的 I、L、O、U。
const ALPHABET: &[u8; 32] = b"0123456789ABCDEFGHJKMNPQRSTVWXYZ";
const VERSION: u8 = 1;
pub const DEFAULT_PORT: u16 = 39393;
pub const SECRET_LEN: usize = 3;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum AddrKind {
/// 192.168.a.b —— 2 字节
Private192 = 0,
/// 10.a.b.c —— 3 字节
Private10 = 1,
/// 172.(16..=31).a.b —— 3 字节
Private172 = 2,
/// 任意 IPv4 —— 4 字节
FullV4 = 3,
/// IPv6 —— 16 字节。码会长到 32 字符左右,适合复制粘贴而非口述,
/// 但它是「双方都有公网 IPv6 时无需任何服务器即可直连」的唯一途径。
V6 = 4,
}
impl AddrKind {
fn from_bits(bits: u8) -> Option<Self> {
Some(match bits {
0 => Self::Private192,
1 => Self::Private10,
2 => Self::Private172,
3 => Self::FullV4,
4 => Self::V6,
_ => return None,
})
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct ConnectCode {
pub address: IpAddr,
pub port: u16,
pub secret: [u8; SECRET_LEN],
}
#[derive(Debug, PartialEq, Eq)]
pub enum CodeError {
/// 长度不对,多半是漏敲或多敲了字符
Length,
/// 出现了字母表之外的字符
Alphabet(char),
/// 校验位不匹配——几乎可以肯定是输错了某一位
Checksum,
/// 版本或地址类型无法识别
Unsupported,
}
impl std::fmt::Display for CodeError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Length => write!(f, "连接码长度不对,请检查是否漏敲或多敲了字符"),
Self::Alphabet(ch) => write!(f, "连接码里有无效字符 '{ch}'"),
Self::Checksum => write!(f, "连接码校验失败,请核对后重新输入"),
Self::Unsupported => write!(f, "无法识别的连接码版本"),
}
}
}
impl std::error::Error for CodeError {}
impl ConnectCode {
pub fn new(address: IpAddr, port: u16, secret: [u8; SECRET_LEN]) -> Self {
Self { address, port, secret }
}
/// 秘密的线上表示:6 个小写十六进制字符,放在 `X-QFT-Code` 头里。
pub fn secret_hex(&self) -> String {
self.secret.iter().map(|b| format!("{b:02x}")).collect()
}
pub fn base_url(&self) -> String {
match self.address {
IpAddr::V4(v4) => format!("http://{v4}:{}", self.port),
IpAddr::V6(v6) => format!("http://[{v6}]:{}", self.port),
}
}
/// 编码为分组显示的字符串,例如 `K7M2-9X4P-QR3T`。
pub fn encode(&self) -> String {
let bytes = self.to_bytes();
let raw = base32_encode(&bytes);
raw.as_bytes()
.chunks(4)
.map(|chunk| std::str::from_utf8(chunk).unwrap_or_default())
.collect::<Vec<_>>()
.join("-")
}
/// 解析用户输入。分隔符、大小写、以及 I/L→1、O→0 的手误都会被容忍。
pub fn decode(text: &str) -> Result<Self, CodeError> {
let (bytes, padding_ok) = base32_decode(text)?;
// 先判长度:码太短时「长度不对」比「校验失败」更能指导用户,
// 再判填充位与 CRC。
let code = Self::from_bytes(&bytes)?;
if !padding_ok {
return Err(CodeError::Checksum);
}
Ok(code)
}
fn to_bytes(&self) -> Vec<u8> {
let (kind, addr_bytes) = match self.address {
IpAddr::V4(v4) => {
let o = v4.octets();
match (o[0], o[1]) {
(192, 168) => (AddrKind::Private192, vec![o[2], o[3]]),
(10, _) => (AddrKind::Private10, vec![o[1], o[2], o[3]]),
(172, 16..=31) => (AddrKind::Private172, vec![o[1] - 16, o[2], o[3]]),
_ => (AddrKind::FullV4, o.to_vec()),
}
}
IpAddr::V6(v6) => (AddrKind::V6, v6.octets().to_vec()),
};
let default_port = self.port == DEFAULT_PORT;
let mut out = Vec::with_capacity(1 + addr_bytes.len() + 2 + SECRET_LEN + 1);
out.push((VERSION << 5) | ((kind as u8) << 2) | ((default_port as u8) << 1));
out.extend_from_slice(&addr_bytes);
if !default_port {
out.extend_from_slice(&self.port.to_be_bytes());
}
out.extend_from_slice(&self.secret);
out.push(crc8(&out));
out
}
fn from_bytes(bytes: &[u8]) -> Result<Self, CodeError> {
if bytes.len() < 1 + 2 + SECRET_LEN + 1 {
return Err(CodeError::Length);
}
let (payload, checksum) = bytes.split_at(bytes.len() - 1);
if crc8(payload) != checksum[0] {
return Err(CodeError::Checksum);
}
let header = payload[0];
if header >> 5 != VERSION {
return Err(CodeError::Unsupported);
}
let kind = AddrKind::from_bits((header >> 2) & 0b111).ok_or(CodeError::Unsupported)?;
let default_port = (header >> 1) & 1 == 1;
let addr_len = match kind {
AddrKind::Private192 => 2,
AddrKind::Private10 | AddrKind::Private172 => 3,
AddrKind::FullV4 => 4,
AddrKind::V6 => 16,
};
let port_len = if default_port { 0 } else { 2 };
if payload.len() != 1 + addr_len + port_len + SECRET_LEN {
return Err(CodeError::Length);
}
let addr_slice = &payload[1..1 + addr_len];
let address = match kind {
AddrKind::Private192 => {
IpAddr::V4(Ipv4Addr::new(192, 168, addr_slice[0], addr_slice[1]))
}
AddrKind::Private10 => {
IpAddr::V4(Ipv4Addr::new(10, addr_slice[0], addr_slice[1], addr_slice[2]))
}
AddrKind::Private172 => {
// 第二个八位组只可能是 16..=31,编码时减了 16
if addr_slice[0] > 15 {
return Err(CodeError::Unsupported);
}
IpAddr::V4(Ipv4Addr::new(172, addr_slice[0] + 16, addr_slice[1], addr_slice[2]))
}
AddrKind::FullV4 => IpAddr::V4(Ipv4Addr::new(
addr_slice[0], addr_slice[1], addr_slice[2], addr_slice[3],
)),
AddrKind::V6 => {
let mut octets = [0u8; 16];
octets.copy_from_slice(addr_slice);
IpAddr::V6(Ipv6Addr::from(octets))
}
};
let mut cursor = 1 + addr_len;
let port = if default_port {
DEFAULT_PORT
} else {
let value = u16::from_be_bytes([payload[cursor], payload[cursor + 1]]);
cursor += 2;
value
};
let mut secret = [0u8; SECRET_LEN];
secret.copy_from_slice(&payload[cursor..cursor + SECRET_LEN]);
Ok(Self { address, port, secret })
}
}
pub fn new_secret() -> [u8; SECRET_LEN] {
use rand::RngCore;
let mut secret = [0u8; SECRET_LEN];
rand::rng().fill_bytes(&mut secret);
secret
}
// ---------------------------------------------------------------- Base32
fn base32_encode(bytes: &[u8]) -> String {
let mut out = String::with_capacity(bytes.len() * 8 / 5 + 1);
let mut buffer: u32 = 0;
let mut bits = 0u32;
for &byte in bytes {
buffer = (buffer << 8) | byte as u32;
bits += 8;
while bits >= 5 {
bits -= 5;
out.push(ALPHABET[((buffer >> bits) & 0x1f) as usize] as char);
}
}
if bits > 0 {
out.push(ALPHABET[((buffer << (5 - bits)) & 0x1f) as usize] as char);
}
out
}
/// 返回 (字节, 末尾填充位是否为 0)。
fn base32_decode(text: &str) -> Result<(Vec<u8>, bool), CodeError> {
let mut buffer: u32 = 0;
let mut bits = 0u32;
let mut out = Vec::new();
let mut symbols = 0usize;
for ch in text.chars() {
// 分隔符与空白一律忽略,用户怎么断句都行
if ch == '-' || ch == ' ' || ch == '_' || ch == '\t' {
continue;
}
let upper = ch.to_ascii_uppercase();
// Crockford 的容错映射:手写/口述时 I、L 常被当成 1,O 被当成 0
let normalized = match upper {
'I' | 'L' => '1',
'O' => '0',
other => other,
};
let value = ALPHABET
.iter()
.position(|&c| c as char == normalized)
.ok_or(CodeError::Alphabet(ch))? as u32;
symbols += 1;
buffer = (buffer << 5) | value;
bits += 5;
if bits >= 8 {
bits -= 8;
out.push(((buffer >> bits) & 0xff) as u8);
}
}
if symbols == 0 {
return Err(CodeError::Length);
}
// 5 位一组和 8 位一字节对不齐,末尾会剩几个填充位。编码时填的是 0,
// 必须校验它们仍是 0:否则改动最后一个字符有 1/2^bits 的概率
// 解出完全相同的字节序列,CRC 根本没机会发现(修复前实测漏检率 4%)。
let padding_ok = bits == 0 || (buffer & ((1 << bits) - 1)) == 0;
Ok((out, padding_ok))
}
fn crc8(bytes: &[u8]) -> u8 {
let mut crc = 0u8;
for &byte in bytes {
crc ^= byte;
for _ in 0..8 {
crc = if crc & 0x80 != 0 { (crc << 1) ^ 0x07 } else { crc << 1 };
}
}
crc
}
#[cfg(test)]
mod tests {
use super::*;
fn code(ip: &str, port: u16) -> ConnectCode {
ConnectCode::new(ip.parse().unwrap(), port, [0xAB, 0xCD, 0xEF])
}
#[test]
fn typical_home_address_fits_in_twelve_characters() {
let encoded = code("192.168.1.20", DEFAULT_PORT).encode();
let symbols = encoded.chars().filter(|c| *c != '-').count();
assert_eq!(symbols, 12, "常见家庭网段应压到 12 个字符,实得 {encoded}");
assert_eq!(encoded.matches('-').count(), 2, "应分成三组便于口述");
}
#[test]
fn round_trips_every_address_kind() {
let cases = [
("192.168.1.20", DEFAULT_PORT),
("192.168.255.255", DEFAULT_PORT),
("10.0.0.5", DEFAULT_PORT),
("10.255.255.254", 8080),
("172.16.0.1", DEFAULT_PORT),
("172.31.255.254", 1),
("100.64.0.1", DEFAULT_PORT), // CGNAT,落到 FullV4
("127.0.0.1", 65535),
("2001:db8::1", DEFAULT_PORT),
("fe80::1", 39393),
];
for (ip, port) in cases {
let original = code(ip, port);
let decoded = ConnectCode::decode(&original.encode())
.unwrap_or_else(|e| panic!("{ip}:{port} 解码失败:{e}"));
assert_eq!(decoded, original, "{ip}:{port} 往返不一致");
}
}
#[test]
fn accepts_sloppy_user_input() {
let original = code("192.168.1.20", DEFAULT_PORT);
let canonical = original.encode();
let sloppy = [
canonical.to_lowercase(),
canonical.replace('-', ""),
canonical.replace('-', " "),
format!(" {canonical} "),
];
for text in sloppy {
assert_eq!(ConnectCode::decode(&text).unwrap(), original, "应容忍:{text}");
}
}
#[test]
fn confusable_letters_map_to_digits() {
// 口述时 I/L 常被听成 1,O 被听成 0。字母表里本就没有这些字母,
// 所以把它们映射回数字是安全的,不会和真实字符冲突。
let original = code("192.168.1.20", DEFAULT_PORT);
let canonical = original.encode();
let mangled = canonical.replace('1', "I").replace('0', "O");
if mangled != canonical {
assert_eq!(ConnectCode::decode(&mangled).unwrap(), original);
}
}
#[test]
fn single_character_typo_is_caught_by_checksum() {
let canonical = code("192.168.1.20", DEFAULT_PORT).encode();
let mut caught = 0;
let mut total = 0;
for (index, ch) in canonical.char_indices() {
if ch == '-' {
continue;
}
for &replacement in ALPHABET.iter() {
if replacement as char == ch {
continue;
}
let mut mangled: Vec<char> = canonical.chars().collect();
mangled[index] = replacement as char;
let text: String = mangled.into_iter().collect();
total += 1;
if ConnectCode::decode(&text).is_err() {
caught += 1;
}
}
}
// CRC-8 理论漏检率约 1/256;这里要求实测拦截率高于 99%
let rate = caught as f64 / total as f64;
assert!(rate > 0.99, "单字符输错的拦截率只有 {:.3},太低", rate);
}
#[test]
fn rejects_malformed_input() {
assert_eq!(ConnectCode::decode(""), Err(CodeError::Length));
assert_eq!(ConnectCode::decode("---"), Err(CodeError::Length));
assert!(matches!(ConnectCode::decode("K7M2!9X4"), Err(CodeError::Alphabet('!'))));
assert_eq!(ConnectCode::decode("K7M2"), Err(CodeError::Length));
}
#[test]
fn secret_hex_is_stable_and_lowercase() {
let value = code("192.168.1.20", DEFAULT_PORT);
assert_eq!(value.secret_hex(), "abcdef");
assert_eq!(value.base_url(), "http://192.168.1.20:39393");
}
#[test]
fn ipv6_code_is_long_but_valid() {
let value = code("2001:db8::1", DEFAULT_PORT);
let encoded = value.encode();
let symbols = encoded.chars().filter(|c| *c != '-').count();
// IPv6 地址本身就 16 字节,码必然长,适合复制粘贴而不是口述
assert!(symbols > 24, "IPv6 码应明显更长,实得 {symbols}");
assert_eq!(ConnectCode::decode(&encoded).unwrap(), value);
}
#[test]
fn secrets_differ_between_sessions() {
let a = new_secret();
let b = new_secret();
assert_ne!(a, b, "每次生成的秘密必须不同");
}
}
@@ -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::{
+201
View File
@@ -0,0 +1,201 @@
//! 局域网节点发现(v3 浏览)。
//!
//! 与既有的 `QFTDISC2:<token>` 不同:那是「我已经知道令牌,帮我找到那台机器」,
//! 用于手机扫码之后。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<u8> {
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<Vec<Peer>> {
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<Ipv4Addr> = 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<Peer> = 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<Peer> {
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<Ipv4Addr> {
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");
}
}
+292
View File
@@ -0,0 +1,292 @@
//! 系统防火墙放行。
//!
//! 接收端要监听入站 TCP,而 Windows 防火墙默认拦截未授权程序的入站连接,
//! 表现是「对方能解析连接码,但连接一直超时」——这类问题用户几乎不可能
//! 自己联想到防火墙。所以由程序主动检测并申请放行。
//!
//! 三条设计约束:
//! 1. **只在确实缺规则时申请**。每次启动都弹 UAC 是骚扰。
//! 2. **被拒绝就记住**。写一个标记文件,之后只在界面上留一个手动按钮,
//! 不再自动弹窗。
//! 3. **规则尽量窄**。只放行本程序这一个可执行文件,绝不整体关闭防火墙。
//! 但**不能按网络配置文件收窄**——见下方 `grant()` 里的说明。
//!
//! 提权本身由操作系统的标准机制完成(Windows 的 UAC、macOS 的
//! 授权对话框),程序不接触也不存储任何凭据。
use anyhow::{bail, Context, Result};
use std::path::PathBuf;
/// 规则显示名。检测与添加都用它,改名会导致旧规则失效。
// 仅 Windows 分支使用;其余平台整段被 cfg 编译掉
#[cfg_attr(not(target_os = "windows"), allow(dead_code))]
pub const RULE_NAME: &str = "QFT Desktop";
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum FirewallStatus {
/// 已放行,或系统防火墙未开启,总之入站不会被拦
Allowed,
/// 缺少放行规则,入站很可能被拦
Missing,
/// 查不出来(命令不可用、输出无法解析等),不要据此吓唬用户
Unknown(String),
/// 本平台不做自动放行(目前只有 Linux 会返回)
#[cfg_attr(not(all(unix, not(target_os = "macos"))), allow(dead_code))]
Unsupported(&'static str),
}
impl FirewallStatus {
pub fn needs_action(&self) -> bool {
matches!(self, Self::Missing)
}
}
fn current_exe() -> Result<PathBuf> {
std::env::current_exe().context("无法获取本程序路径")
}
// ---------------------------------------------------------------- Windows
#[cfg(target_os = "windows")]
pub fn status() -> FirewallStatus {
use std::os::windows::process::CommandExt;
const CREATE_NO_WINDOW: u32 = 0x0800_0000;
let output = std::process::Command::new("netsh")
.args([
"advfirewall",
"firewall",
"show",
"rule",
&format!("name={RULE_NAME}"),
])
.creation_flags(CREATE_NO_WINDOW)
.output();
match output {
Ok(out) if out.status.success() => {
// 光有同名规则还不够:规则若绑在不适用于当前网络的 profile 上,
// 会出现「显示已启用但照样被拦」。所以要求它是 profile=any。
let text = String::from_utf8_lossy(&out.stdout);
let any_profile = text.contains("Any") || text.contains("任何");
if any_profile {
FirewallStatus::Allowed
} else {
FirewallStatus::Missing
}
}
// netsh 在找不到规则时退出码非 0
Ok(_) => FirewallStatus::Missing,
Err(e) => FirewallStatus::Unknown(format!("无法执行 netsh:{e}")),
}
}
/// 触发 UAC 并添加入站放行规则。
///
/// 用临时批处理承载命令,而不是把参数塞进 PowerShell 的 `-ArgumentList`:
/// 程序路径里带空格时,经过 PowerShell 再到 netsh 会被重新分词,
/// 引号层层嵌套极易出错。批处理文件由我们自己写死引号,不再被二次解析。
///
/// `profile=any` 是刻意的,早先写成 `private,domain` 是个真实的 bug:
/// Windows 对没见过的 Wi-Fi 默认归类为**公用网络**,此时 private 规则
/// 根本不适用——规则建了、也显示已启用,但连接照样被拦,极难排查。
/// 收窄到某个 profile 并不能带来实际安全收益:QFT 的入站真正靠的是
/// 连接码里的秘密加失败计数,没有秘密的连接一律被拒。
#[cfg(target_os = "windows")]
pub fn grant() -> Result<()> {
use std::os::windows::process::CommandExt;
const CREATE_NO_WINDOW: u32 = 0x0800_0000;
let exe = current_exe()?;
let script = std::env::temp_dir().join(format!("qft-firewall-{}.bat", std::process::id()));
let content = format!(
"@echo off\r\n\
netsh advfirewall firewall delete rule name=\"{RULE_NAME}\" >nul 2>&1\r\n\
netsh advfirewall firewall add rule name=\"{RULE_NAME}\" dir=in action=allow \
program=\"{}\" enable=yes profile=any\r\n",
exe.display()
);
std::fs::write(&script, content).context("写入临时放行脚本失败")?;
let status = std::process::Command::new("powershell")
.args([
"-NoProfile",
"-WindowStyle",
"Hidden",
"-Command",
&format!(
"Start-Process -FilePath cmd -ArgumentList '/c','\"{}\"' -Verb RunAs -WindowStyle Hidden -Wait",
script.display()
),
])
.creation_flags(CREATE_NO_WINDOW)
.status();
let _ = std::fs::remove_file(&script);
match status {
// 用户在 UAC 上点了「否」时 Start-Process 会失败,退出码非 0
Ok(s) if s.success() => Ok(()),
Ok(_) => bail!("未获得管理员授权,防火墙规则没有添加"),
Err(e) => bail!("调用提权失败:{e}"),
}
}
// ---------------------------------------------------------------- macOS
#[cfg(target_os = "macos")]
pub fn status() -> FirewallStatus {
const TOOL: &str = "/usr/libexec/ApplicationFirewall/socketfilterfw";
if !std::path::Path::new(TOOL).exists() {
return FirewallStatus::Unknown("系统上没有 socketfilterfw".into());
}
// 应用层防火墙没开时,入站根本不会被拦,不需要做任何事
match std::process::Command::new(TOOL).arg("--getglobalstate").output() {
Ok(out) => {
let text = String::from_utf8_lossy(&out.stdout);
if text.contains("disabled") {
return FirewallStatus::Allowed;
}
}
Err(e) => return FirewallStatus::Unknown(format!("无法执行 socketfilterfw:{e}")),
}
let Ok(exe) = current_exe() else {
return FirewallStatus::Unknown("无法获取本程序路径".into());
};
match std::process::Command::new(TOOL)
.args(["--getappblocked", &exe.display().to_string()])
.output()
{
Ok(out) => {
let text = String::from_utf8_lossy(&out.stdout).to_lowercase();
if text.contains("blocked") && !text.contains("not blocked") {
FirewallStatus::Missing
} else {
FirewallStatus::Allowed
}
}
Err(e) => FirewallStatus::Unknown(format!("查询失败:{e}")),
}
}
/// 通过系统授权对话框把本程序加入放行列表。
///
/// macOS 通常会在首次监听时自己弹「是否允许接受传入网络连接」,
/// 那一步就够了;这里只处理用户当时点了「拒绝」的情况。
#[cfg(target_os = "macos")]
pub fn grant() -> Result<()> {
let exe = current_exe()?;
let path = exe.display().to_string();
if path.contains('"') || path.contains('\\') {
bail!("程序路径包含无法安全转义的字符,请手动在「系统设置 → 网络 → 防火墙」里放行")
}
let inner = format!(
"/usr/libexec/ApplicationFirewall/socketfilterfw --add '{path}' && \
/usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp '{path}'"
);
let script = format!("do shell script \"{inner}\" with administrator privileges");
let status = std::process::Command::new("osascript")
.args(["-e", &script])
.status()
.context("调用 osascript 失败")?;
if status.success() {
Ok(())
} else {
bail!("未获得授权,防火墙放行没有生效")
}
}
// ---------------------------------------------------------------- Linux
#[cfg(all(unix, not(target_os = "macos")))]
pub fn status() -> FirewallStatus {
// 各发行版的防火墙前端差异过大(ufw / firewalld / 裸 iptables / nftables),
// 自动改规则风险高于收益,只做检测与提示。
FirewallStatus::Unsupported("Linux 上请按下方提示手动放行")
}
#[cfg(all(unix, not(target_os = "macos")))]
pub fn grant() -> Result<()> {
bail!("Linux 上不自动修改防火墙,请按界面提示手动执行")
}
// ---------------------------------------------------------------- 手动说明
/// 自动放行失败或不支持时,给用户可以照抄的命令。
pub fn manual_instructions(port: u16) -> String {
let exe = current_exe()
.map(|p| p.display().to_string())
.unwrap_or_else(|_| "qft-desktop".into());
#[cfg(target_os = "windows")]
{
format!(
"以管理员身份打开 PowerShell,执行:\n\n\
New-NetFirewallRule -DisplayName \"{RULE_NAME}\" -Direction Inbound \\\n\
\x20 -Program \"{exe}\" -Action Allow -Profile Private,Domain\n\n\
或在「允许应用通过 Windows Defender 防火墙」里勾选该程序的专用网络。"
)
}
#[cfg(target_os = "macos")]
{
let _ = port;
format!(
"打开「系统设置 → 网络 → 防火墙 → 选项」,把下面这个程序设为\
「允许传入连接」:\n\n{exe}\n\n\
若防火墙本身是关闭的,则无需任何操作。"
)
}
#[cfg(all(unix, not(target_os = "macos")))]
{
let _ = exe;
format!(
"按你所用的防火墙执行其一:\n\n\
ufw: sudo ufw allow {port}/tcp && sudo ufw allow {}/udp\n\
firewalld: sudo firewall-cmd --add-port={port}/tcp --add-port={}/udp --permanent && sudo firewall-cmd --reload",
port - 1,
port - 1,
)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn status_query_never_panics_and_is_classified() {
// 只做只读查询,不改动任何系统设置
let value = status();
match &value {
FirewallStatus::Allowed
| FirewallStatus::Missing
| FirewallStatus::Unsupported(_) => {}
FirewallStatus::Unknown(reason) => assert!(!reason.is_empty(), "未知原因不能为空"),
}
// 只有 Missing 才该触发后续动作
assert_eq!(
value.needs_action(),
matches!(value, FirewallStatus::Missing)
);
}
#[test]
fn manual_instructions_mention_the_actual_program() {
let text = manual_instructions(39393);
assert!(!text.trim().is_empty());
// 说明里必须出现可操作的东西:程序路径或具体端口
assert!(
text.contains("qft") || text.contains("39393") || text.contains("防火墙"),
"说明应包含可操作信息:{text}"
);
}
#[test]
fn status_is_read_only_and_repeatable() {
// 检测必须无副作用:连续调用结果一致,且不改动任何系统设置
assert_eq!(status(), status());
}
}
+685 -20
View File
@@ -1,7 +1,12 @@
mod base45;
mod client;
mod connect_code;
mod direct_ap;
mod discovery;
mod firewall;
mod optical_cache;
mod pairing;
mod platform;
mod protocol;
mod qr;
mod receiver;
@@ -23,7 +28,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.0-rc6";
const APP_VERSION: &str = "0.4.8";
fn main() -> eframe::Result {
let options = eframe::NativeOptions {
@@ -46,6 +51,7 @@ enum Screen {
OpticalSend,
PhoneToPc,
PcToPhone,
PcToPc,
}
struct OpticalState {
@@ -101,6 +107,48 @@ struct SendState {
connected_device: String,
}
#[derive(Clone, Copy, PartialEq, Eq)]
enum PcMode {
Receive,
Send,
}
/// PC↔PC 传输的后台事件。传输跑在工作线程上,UI 只消费事件。
enum PcEvent {
Peers(Vec<discovery::Peer>),
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<PathBuf>,
server: Option<ReceiverServer>,
// 发送侧
peers: Vec<discovery::Peer>,
code_input: String,
token: Option<String>,
connected_base: Option<String>,
files: Vec<PathBuf>,
// 后台事件
events: Option<mpsc::Receiver<PcEvent>>,
busy: bool,
/// 仅在真正开始推送文件后为真。此前用 busy 兼作此用,
/// 导致配对阶段就显示「正在发送 0%」,误导用户以为传输已经开始。
transferring: bool,
current_file: String,
done: u64,
total: u64,
started: Option<Instant>,
status: String,
firewall: firewall::FirewallStatus,
firewall_note: String,
}
struct QftApp {
screen: Screen,
font_status: String,
@@ -108,11 +156,14 @@ struct QftApp {
optical: OpticalState,
receive: ReceiveState,
send: SendState,
pc: PcPeerState,
}
impl QftApp {
fn new(cc: &eframe::CreationContext<'_>) -> Self {
cc.egui_ctx.set_pixels_per_point(1.0);
// 不要写死 pixels_per_point。此前固定为 1.0,在 Retina/HiDPI 上会让
// 整个界面缩成实际尺寸的一半;缩放由 eframe 从系统取。
// 二维码需要的像素级精确由 snap_to_physical 在绘制时保证。
install_visuals(&cc.egui_ctx);
let font_status = match install_ttf_font(&cc.egui_ctx) {
Ok(path) => format!("字体:{}", path.display()),
@@ -172,6 +223,26 @@ 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(),
code_input: String::new(),
token: None,
connected_base: None,
files: Vec::new(),
events: None,
busy: false,
transferring: false,
current_file: String::new(),
done: 0,
total: 0,
started: None,
status: "接收方启动后会显示连接码;发送方输入该码即可传输。".into(),
firewall: firewall::FirewallStatus::Unknown("尚未检测".into()),
firewall_note: String::new(),
},
}
}
@@ -188,6 +259,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 +320,17 @@ impl QftApp {
});
});
ui.add_space(18.0);
ui.group(|ui| {
ui.horizontal_wrapped(|ui| {
ui.heading("电脑 ↔ 电脑");
ui.separator();
ui.label("输入对方的连接码即可 · 无需二维码");
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);
@@ -425,7 +508,8 @@ impl QftApp {
let base = avail.x.min((avail.y - reserved).max(220.0)).max(220.0);
let side = (base * self.optical.qr_zoom).clamp(220.0, base);
ui.vertical_centered(|ui| {
ui.image((texture.id(), egui::vec2(side, side)));
let side = snap_to_physical(side, ui.ctx().pixels_per_point());
ui.image((texture.id(), egui::vec2(side, side)));
if !self.optical.focus_qr {
ui.small("拖动左侧分隔条可继续放大二维码;也可点击顶部“专注二维码”占满可用区域。");
}
@@ -446,7 +530,7 @@ impl QftApp {
ui.horizontal_wrapped(|ui| {
ui.heading("Android → 电脑 · 扫码直连");
ui.separator();
ui.label("UDP 快速发现 · 4/8/16 MiB 自适应分块 · 最高 8 路并行 · 不经过外网");
ui.label("UDP 快速发现 · 64 KiB–16 MiB 自适应分块 · 目标 8 路并行 · 不经过外网");
});
ui.add_space(10.0);
let running = self.receive.server.is_some();
@@ -455,7 +539,7 @@ impl QftApp {
ui.heading("1 · 保存位置");
ui.horizontal_wrapped(|ui| {
if ui.add_enabled(!running, egui::Button::new("选择接收文件夹")).clicked() {
if let Some(dir) = rfd::FileDialog::new().pick_folder() {
if let Some(dir) = pick_folder_safely() {
self.receive.save_dir = Some(dir);
self.receive.status = "保存位置已选择,可以启动接收。".into();
}
@@ -506,7 +590,8 @@ impl QftApp {
ui.heading("手机扫码 · QFTPAIR2");
if let Some(texture) = &self.receive.pair_texture {
let side = ui.available_width().min(420.0).max(260.0);
ui.vertical_centered(|ui| { ui.image((texture.id(), egui::vec2(side, side))); });
ui.vertical_centered(|ui| { let side = snap_to_physical(side, ui.ctx().pixels_per_point());
ui.image((texture.id(), egui::vec2(side, side))); });
}
if let Some(ap) = &self.receive.direct_ap {
ui.label(format!("临时网络:{}", ap.ssid));
@@ -555,7 +640,7 @@ impl QftApp {
ui.heading("1 · 选择发送文件");
ui.horizontal_wrapped(|ui| {
if ui.add_enabled(!running, egui::Button::new("选择文件")).clicked() {
if let Some(path) = rfd::FileDialog::new().pick_file() {
if let Some(path) = pick_file_safely() {
match TransferSource::open(&path, DEFAULT_CHUNK_SIZE) {
Ok(source) => {
self.send.file_size = source.manifest.file_size;
@@ -605,7 +690,8 @@ impl QftApp {
ui.heading("手机扫码 · QFTSEND2");
if let Some(texture) = &self.send.pair_texture {
let side = ui.available_width().min(420.0).max(260.0);
ui.vertical_centered(|ui| { ui.image((texture.id(), egui::vec2(side, side))); });
ui.vertical_centered(|ui| { let side = snap_to_physical(side, ui.ctx().pixels_per_point());
ui.image((texture.id(), egui::vec2(side, side))); });
}
if let Some(ap) = &self.send.direct_ap {
ui.label(format!("临时网络:{}", ap.ssid));
@@ -623,7 +709,7 @@ impl QftApp {
}
fn optical_pick_file(&mut self, ctx: &egui::Context) {
let Some(path) = rfd::FileDialog::new().pick_file() else { return };
let Some(path) = pick_file_safely() else { return };
match TransferSource::open(&path, DEFAULT_CHUNK_SIZE) {
Ok(source) => {
self.optical.source = Some(Arc::new(source));
@@ -900,6 +986,444 @@ 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.transferring = 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("同一局域网或可路由到达 · 无需二维码 · 一串连接码");
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() {
match pick_folder_safely() {
Some(dir) => self.pc.save_dir = Some(dir),
None => self.pc.status =
"系统文件夹对话框没有返回结果。当前仍使用上方显示的目录。".into(),
}
}
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 secret = server.secret;
// 每个网卡各生成一个连接码:对方在哪个网段,就用哪一个。
// 地址已经编在码里,所以对方不需要再单独输入 IP。
let codes: Vec<(std::net::IpAddr, String)> = pairing::local_ipv4_addresses()
.into_iter()
.map(|address| {
let code = connect_code::ConnectCode::new(std::net::IpAddr::V4(address), port, secret);
(std::net::IpAddr::V4(address), code.encode())
})
.collect();
{
ui.add_space(10.0);
ui.group(|ui| {
let blocked = self.pc.firewall.needs_action();
let color = if blocked {
egui::Color32::from_rgb(220, 140, 60)
} else {
egui::Color32::from_rgb(80, 200, 120)
};
ui.horizontal_wrapped(|ui| {
ui.colored_label(color, if blocked { "⚠ 系统防火墙可能拦截入站连接" } else { "● 防火墙" });
if !self.pc.firewall_note.is_empty() {
ui.label(&self.pc.firewall_note);
}
});
ui.horizontal_wrapped(|ui| {
// 无论检测结果如何都保留入口:检测可能不准,
// 而用户遇到「对方连不上」时需要有地方可点。
if ui.button("放行防火墙(需要管理员授权)").clicked() {
self.request_firewall_grant();
}
if ui.small_button("复制手动放行命令").clicked() {
ui.ctx().copy_text(firewall::manual_instructions(port));
}
if ui.small_button("重新检测").clicked() {
self.refresh_firewall();
}
});
if !blocked {
ui.small("检测认为入站不会被拦。若对方仍连不上,可手动放行试试。");
}
});
}
ui.add_space(14.0);
ui.group(|ui| {
ui.heading("把连接码告诉发送方");
ui.small("码里已经包含地址,对方只需输入这一串,不用再报 IP 和端口。");
ui.add_space(8.0);
if codes.is_empty() {
ui.colored_label(egui::Color32::from_rgb(220, 120, 60), "没有可用的局域网地址,请检查网络连接。");
}
for (index, (address, code)) in codes.iter().enumerate() {
ui.horizontal(|ui| {
if index == 0 {
ui.heading(egui::RichText::new(code).monospace().strong());
} else {
ui.monospace(egui::RichText::new(code).strong());
}
if ui.small_button("复制").clicked() {
ui.ctx().copy_text(code.clone());
}
ui.weak(format!("({address})"));
});
}
ui.add_space(6.0);
ui.small("输错 5 次该码即作废,需要重新启动接收。");
if codes.len() > 1 {
ui.small("本机有多个网卡:对方在哪个网段就用对应的那一串。");
}
});
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| {
let response = ui.add(
egui::TextEdit::singleline(&mut self.pc.code_input)
.hint_text("K7M2-9X4P-QR3T")
.desired_width(240.0)
.font(egui::TextStyle::Monospace),
);
let submitted = response.lost_focus()
&& ui.input(|i| i.key_pressed(egui::Key::Enter));
let parsed = connect_code::ConnectCode::decode(&self.pc.code_input);
let can_connect = !self.pc.busy && parsed.is_ok();
if ui.add_enabled(can_connect, egui::Button::new("连接")).clicked()
|| (submitted && can_connect)
{
self.pair_pc_peer();
}
if self.pc.busy {
ui.spinner();
ui.weak("正在建立连接…最多等 4 秒");
} else if self.pc.token.is_some() {
ui.colored_label(egui::Color32::from_rgb(80, 200, 120), "● 已连接");
}
});
// 边打边校验:CRC 能在连接之前就发现输错,不用等超时
if !self.pc.code_input.trim().is_empty() {
match connect_code::ConnectCode::decode(&self.pc.code_input) {
Ok(code) => ui.weak(format!("将连接 {}", code.base_url())),
Err(e) => ui.colored_label(egui::Color32::from_rgb(220, 120, 60), e.to_string()),
};
}
ui.add_space(4.0);
ui.small("连接码里已包含对方地址,不需要在同一网段——只要网络能路由到对方即可。");
});
ui.add_space(12.0);
ui.collapsing("搜索同网段的设备(可选)", |ui| {
ui.small("同一网段时可以免输码。跨网段、或 Wi-Fi 开了客户端隔离时搜不到,请改用连接码。");
if ui.add_enabled(!self.pc.busy, egui::Button::new("搜索")).clicked() {
self.browse_pc_peers();
}
for peer in &self.pc.peers {
if ui.button(format!("{} · {} · {}", peer.name, peer.platform, peer.base_url())).clicked() {
// 直接把对端地址填进码输入框还不够——秘密只有对方屏幕上有,
// 所以这里只做地址提示,仍需用户补齐连接码
self.pc.status = format!("请输入 {} 屏幕上显示的连接码", peer.name);
}
}
if self.pc.peers.is_empty() {
ui.weak("尚未搜索到设备。");
}
});
// 拖进窗口的文件直接进待发列表。拖拽不依赖系统文件对话框,
// 因此在 NSOpenPanel 失效时仍然可用。
let dropped = dropped_paths(ui.ctx());
if !dropped.is_empty() {
for path in dropped {
if path.is_file() && !self.pc.files.contains(&path) {
self.pc.files.push(path);
}
}
self.pc.status = format!("已加入 {} 个文件。", self.pc.files.len());
}
ui.add_space(12.0);
ui.group(|ui| {
ui.heading("2 · 选择文件并发送");
if is_hovering_files(ui.ctx()) {
ui.colored_label(egui::Color32::from_rgb(80, 200, 120), "松手即可加入待发送列表");
} else {
ui.small("可以直接把文件拖进这个窗口。");
}
ui.horizontal_wrapped(|ui| {
if ui.button("选择文件").clicked() {
match pick_files_safely() {
Some(files) => self.pc.files = files,
None => self.pc.status =
"系统文件对话框没有返回结果。可以直接把文件拖进窗口。".into(),
}
}
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.transferring || 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)));
}
});
}
/// 只做**只读检测**,不申请任何权限。
///
/// 早先版本会在启动接收时自动弹 UAC。实际用下来这太侵入:
/// 多数人只是想收个文件,却先被要求管理员授权。
/// 现在提权一律由用户点按钮触发(`request_firewall_grant`)。
fn refresh_firewall(&mut self) {
self.pc.firewall = firewall::status();
if !self.pc.firewall.needs_action() {
self.pc.firewall_note.clear();
}
}
/// 用户显式点击后才提权。
fn request_firewall_grant(&mut self) {
match firewall::grant() {
Ok(()) => {
self.pc.firewall = firewall::status();
self.pc.firewall_note = "已放行系统防火墙。".into();
}
Err(e) => self.pc.firewall_note = format!("{e}"),
}
}
fn start_pc_receiver(&mut self) {
let Some(dir) = self.pc.save_dir.clone() else { return };
self.stop_pc();
self.refresh_firewall();
let token = pairing::new_session_token();
let (tx, rx) = mpsc::channel();
match ReceiverServer::start(dir, token, tx) {
Ok(server) => {
self.pc.status = "接收中。把下面的连接码告诉发送方即可。".into();
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:#}"))),
};
});
}
fn pair_pc_peer(&mut self) {
let Ok(code) = connect_code::ConnectCode::decode(&self.pc.code_input) else { return };
let base_url = code.base_url();
let secret = code.secret_hex();
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, &secret, &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.transferring = 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.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.transferring = false;
self.pc.current_file.clear();
self.pc.status = "全部发送完成。".into();
}
PcEvent::Failed(message) => {
self.pc.busy = false;
self.pc.transferring = 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 +1498,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),
}
});
@@ -988,7 +1513,7 @@ fn install_visuals(ctx: &egui::Context) {
fn install_ttf_font(ctx: &egui::Context) -> Result<PathBuf, String> {
let font_path = find_ttf_font().ok_or_else(|| {
"未找到可用 TTF。请把支持中文的字体复制到 windows/assets/qft-ui.ttf,或设置 QFT_FONT_PATH。".to_owned()
"未找到任何可用的中文字体。请把字体复制到 desktop/assets/qft-ui.ttf,或用 QFT_FONT_PATH 指定。".to_owned()
})?;
let bytes = std::fs::read(&font_path).map_err(|e| format!("读取 {} 失败:{e}", font_path.display()))?;
let mut fonts = FontDefinitions::default();
@@ -1011,18 +1536,31 @@ fn find_ttf_font() -> Option<PathBuf> {
}
}
candidates.push(PathBuf::from("assets").join("qft-ui.ttf"));
if cfg!(target_os = "windows") {
candidates.extend([
PathBuf::from(r"C:\Windows\Fonts\simhei.ttf"),
PathBuf::from(r"C:\Windows\Fonts\Deng.ttf"),
PathBuf::from(r"C:\Windows\Fonts\msyh.ttf"),
]);
}
candidates.into_iter().find(|path| is_ttf_file(path.as_path()))
// 仓库不带字体,最终依赖系统自带的中文字体
candidates.extend(platform::system_font_candidates());
candidates.into_iter().find(|path| is_font_file(path.as_path()))
}
fn is_ttf_file(path: &Path) -> bool {
path.is_file() && path.extension().and_then(|ext| ext.to_str()).is_some_and(|ext| ext.eq_ignore_ascii_case("ttf"))
/// 按文件魔数判断是否为可用字体,而不是看扩展名。
///
/// 旧实现只接受 `.ttf`,于是 macOS 的 PingFang.ttc、新版 Windows 的
/// msyh.ttc、Linux 的 NotoSansCJK.ttc 全部被拒,界面只能显示豆腐块。
fn is_font_file(path: &Path) -> bool {
if !path.is_file() {
return false;
}
let Ok(mut file) = std::fs::File::open(path) else { return false };
let mut magic = [0u8; 4];
if std::io::Read::read_exact(&mut file, &mut magic).is_err() {
return false;
}
matches!(
&magic,
b"ttcf" // TrueType 集合
| b"OTTO" // CFF / OpenType
| [0x00, 0x01, 0x00, 0x00] // TrueType
| b"true" // 旧版 Apple TrueType
)
}
fn human_duration(seconds: f64) -> String {
@@ -1033,6 +1571,57 @@ fn human_duration(seconds: f64) -> String {
if minutes > 0 { format!("{minutes} 分 {secs} 秒") } else { format!("{secs} 秒") }
}
/// 把逻辑点尺寸吸附到物理像素整数上。
///
/// 二维码纹理用 NEAREST 采样:绘制尺寸若落在半个物理像素上,
/// 相邻模块占用的物理像素数会一宽一窄,边缘出现锯齿,手机更难解码。
fn snap_to_physical(points: f32, pixels_per_point: f32) -> f32 {
if pixels_per_point <= 0.0 {
return points;
}
((points * pixels_per_point).round() / pixels_per_point).max(1.0)
}
/// 文件对话框的安全包装。
///
/// macOS 上 `+[NSOpenPanel openPanel]` 会偶发返回 NULL,rfd 遇到就直接 panic,
/// 整个程序随之退出——用户只是想选个文件,结果窗口没了。
/// 不管根因是什么,**选文件失败都不该终止程序**,所以在这里兜住。
///
/// 直接跑裸二进制(不是 .app 包)时更容易触发:AppKit 的若干行为依赖
/// 应用被正确注册为 GUI 程序。package.sh 现在会在 macOS 上额外产出 .app。
fn pick_files_safely() -> Option<Vec<PathBuf>> {
std::panic::catch_unwind(|| rfd::FileDialog::new().pick_files()).unwrap_or(None)
}
fn pick_folder_safely() -> Option<PathBuf> {
std::panic::catch_unwind(|| rfd::FileDialog::new().pick_folder()).unwrap_or(None)
}
fn pick_file_safely() -> Option<PathBuf> {
std::panic::catch_unwind(|| rfd::FileDialog::new().pick_file()).unwrap_or(None)
}
/// 取出本帧被拖进窗口的文件。
///
/// 拖拽不经过 NSOpenPanel,因此在文件对话框失效时仍然可用,
/// 同时它本来就是桌面端更顺手的交互。
fn dropped_paths(ctx: &egui::Context) -> Vec<PathBuf> {
ctx.input(|i| {
i.raw
.dropped_files
.iter()
.filter_map(|file| file.path.clone())
.collect()
})
}
/// 是否正有文件悬停在窗口上,用于给出放置提示。
fn is_hovering_files(ctx: &egui::Context) -> bool {
ctx.input(|i| !i.raw.hovered_files.is_empty())
}
fn human_bytes(v: u64) -> String {
const UNITS: [&str; 5] = ["B", "KB", "MB", "GB", "TB"];
let mut n = v as f64;
@@ -1040,3 +1629,79 @@ fn human_bytes(v: u64) -> String {
while n >= 1024.0 && i < UNITS.len() - 1 { n /= 1024.0; i += 1; }
if i == 0 { format!("{} {}", v, UNITS[i]) } else { format!("{n:.2} {}", UNITS[i]) }
}
#[cfg(test)]
mod font_tests {
use super::*;
#[test]
fn detects_ttc_collections_not_just_ttf() {
// 旧实现只看扩展名,把 macOS/Linux 清一色的 .ttc 全拒了
for candidate in platform::system_font_candidates() {
if candidate.exists() {
assert!(
is_font_file(&candidate),
"系统字体 {} 应被识别为可用字体",
candidate.display()
);
}
}
assert!(!is_font_file(Path::new("/etc/hosts")), "非字体文件不应通过");
assert!(!is_font_file(Path::new("/no/such/file")), "不存在的路径不应通过");
}
#[test]
fn a_usable_cjk_font_exists_on_this_platform() {
let found = find_ttf_font();
assert!(
found.is_some(),
"本平台未找到任何中文字体,界面会显示豆腐块。候选:{:?}",
platform::system_font_candidates()
);
}
/// 真正的验收:把找到的字体装进 egui,渲染一个汉字并确认它有宽度。
/// 只检查"文件存在"是不够的——.ttc 若解析失败,字形宽度会是 0。
#[test]
fn renders_chinese_glyphs_with_nonzero_width() {
let ctx = egui::Context::default();
let path = find_ttf_font().expect("应能找到字体");
install_ttf_font(&ctx).expect("字体应能装载");
// egui 0.35:用 begin_pass/end_pass 触发一次布局,字体才会真正加载
ctx.begin_pass(Default::default());
let _ = ctx.end_pass();
let font_id = egui::FontId::proportional(16.0);
let width_cjk = ctx.fonts_mut(|f| f.glyph_width(&font_id, '中'));
let width_latin = ctx.fonts_mut(|f| f.glyph_width(&font_id, 'A'));
assert!(
width_cjk > 0.0,
"字体 {} 无法渲染汉字'中'(宽度 {width_cjk}),界面会是豆腐块",
path.display()
);
assert!(width_latin > 0.0, "拉丁字母也应有宽度");
// 中文是全宽字形,应明显宽于拉丁字母
assert!(
width_cjk > width_latin,
"汉字宽度 {width_cjk} 应大于拉丁字母 {width_latin}"
);
}
#[test]
fn qr_side_snaps_to_whole_physical_pixels() {
// 2x 屏:逻辑点 × 2 必须落在整数物理像素上
for ppp in [1.0_f32, 1.5, 2.0, 3.0] {
for desired in [220.4_f32, 317.7, 480.1, 733.3] {
let snapped = snap_to_physical(desired, ppp);
let physical = snapped * ppp;
assert!(
(physical - physical.round()).abs() < 1e-3,
"ppp={ppp} desired={desired} → {snapped} 点 = {physical} 物理像素,未落在整数上"
);
assert!((snapped - desired).abs() <= 1.0, "吸附不应改变尺寸超过 1 点");
}
}
assert_eq!(snap_to_physical(100.0, 0.0), 100.0, "非法 ppp 时原样返回");
}
}
@@ -145,12 +145,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) {
@@ -170,6 +165,40 @@ fn new_direct_ap_credentials(pc_name: &str) -> (String, String) {
(ssid, password[..16.min(password.len())].to_owned())
}
/// 本机可用的私有 IPv4 地址,按「最可能是对方看得到的那一个」排序。
///
/// 连接码把地址编进码里,所以这里的排序直接决定了用户第一眼看到的那串码
/// 是否好用。虚拟网卡(Docker/VPN/虚拟机桥接)会排到后面。
pub fn local_ipv4_addresses() -> Vec<Ipv4Addr> {
let mut ips = Vec::<Ipv4Addr>::new();
if let Ok(addrs) = if_addrs::get_if_addrs() {
for iface in addrs {
let IpAddr::V4(ip) = iface.ip() else { continue };
if ip.is_loopback() || ip.is_unspecified() || ip.is_link_local() {
continue;
}
if !ip.is_private() {
continue;
}
if !ips.contains(&ip) {
ips.push(ip);
}
}
}
ips.sort_by_key(|ip| {
let o = ip.octets();
match (o[0], o[1]) {
// Windows 的 ICS / Wi-Fi Direct 固定网段,最可能是 QFT 自己拉起来的
(192, 168) if o[2] == 137 || o[2] == 49 => 0,
(192, 168) => 1,
(10, _) => 2,
(172, 16..=31) => 3,
_ => 4,
}
});
ips
}
pub fn local_ipv4_endpoints(port: u16) -> Vec<String> {
let mut ips = Vec::<Ipv4Addr>::new();
if let Ok(addrs) = if_addrs::get_if_addrs() {
+297
View File
@@ -0,0 +1,297 @@
//! 平台差异的唯一收敛点。
//!
//! 约定:除本文件与 `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 与对端的设备列表,
/// 必须去掉控制字符、去掉 mDNS 的 `.local` 后缀并限长。
pub fn sanitize_device_name(raw: &str) -> String {
let cleaned: String = raw
.chars()
.filter(|ch| !ch.is_control())
.take(64)
.collect();
// macOS/Linux 取到的常是 mDNS 主机名(如 zdeMacBook-Air.local),
// 后缀对用户没有意义,列在对方设备列表里只会更长更难认。
let cleaned = cleaned
.strip_suffix(".local")
.or_else(|| cleaned.strip_suffix(".lan"))
.unwrap_or(&cleaned)
.to_owned();
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"
}
}
/// 系统自带的中文字体候选,按优先级排列。
///
/// 仓库不附带第三方字体,界面文字全是中文,找不到字体就会满屏豆腐块。
/// 注意 macOS 与多数 Linux 发行版的中文字体是 **`.ttc` 字体集合**,
/// 只按 `.ttf` 扩展名筛选会把它们全部漏掉。
pub fn system_font_candidates() -> Vec<PathBuf> {
#[cfg(target_os = "macos")]
{
vec![
PathBuf::from("/System/Library/Fonts/PingFang.ttc"),
PathBuf::from("/System/Library/Fonts/Hiragino Sans GB.ttc"),
PathBuf::from("/System/Library/Fonts/STHeiti Medium.ttc"),
PathBuf::from("/System/Library/Fonts/STHeiti Light.ttc"),
PathBuf::from("/Library/Fonts/Arial Unicode.ttf"),
]
}
#[cfg(target_os = "windows")]
{
vec![
// 新版 Windows 的微软雅黑是 .ttc,旧的筛选逻辑正好漏掉它
PathBuf::from(r"C:\Windows\Fonts\msyh.ttc"),
PathBuf::from(r"C:\Windows\Fonts\msyh.ttf"),
PathBuf::from(r"C:\Windows\Fonts\simhei.ttf"),
PathBuf::from(r"C:\Windows\Fonts\Deng.ttf"),
PathBuf::from(r"C:\Windows\Fonts\simsun.ttc"),
]
}
#[cfg(all(unix, not(target_os = "macos")))]
{
vec![
PathBuf::from("/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc"),
PathBuf::from("/usr/share/fonts/opentype/noto/NotoSansCJKsc-Regular.otf"),
PathBuf::from("/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc"),
PathBuf::from("/usr/share/fonts/opentype/source-han-sans/SourceHanSansSC-Regular.otf"),
PathBuf::from("/usr/share/fonts/wqy-zenhei/wqy-zenhei.ttc"),
PathBuf::from("/usr/share/fonts/truetype/wqy/wqy-microhei.ttc"),
PathBuf::from("/usr/share/fonts/truetype/arphic/uming.ttc"),
]
}
}
/// 本机所属平台,用于 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 据此隐藏入口,
/// 而不是让用户点进去再失败。
// UI 尚未据此隐藏 Direct AP 入口,留待 P1.7 收尾
#[allow(dead_code)]
pub enum DirectApSupport {
Supported,
Unsupported(&'static str),
}
#[allow(dead_code)]
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 {
#[allow(dead_code)]
pub const fn is_supported(&self) -> bool {
matches!(self, DirectApSupport::Supported)
}
}
// ---------------------------------------------------------------- 内部工具
fn non_empty_env(key: &str) -> Option<String> {
std::env::var(key).ok().filter(|v| !v.trim().is_empty())
}
fn home_dir() -> Option<PathBuf> {
#[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<PathBuf> {
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
}
/// 确保目录存在,返回其路径。调用方负责处理失败。
#[allow(dead_code)] // 由 client 的下载路径使用,该路径尚未接线
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);
// mDNS 后缀不该出现在设备列表里
assert_eq!(sanitize_device_name("zdeMacBook-Air.local"), "zdeMacBook-Air");
assert_eq!(sanitize_device_name("ubuntu-dev.lan"), "ubuntu-dev");
// 只去掉结尾的后缀,名字中间含 .local 的不动
assert_eq!(sanitize_device_name("my.local.pc"), "my.local.pc");
}
#[test]
fn platform_tag_matches_direct_ap_capability() {
// Direct AP 目前只有 Windows 支持,两个常量必须保持一致
assert_eq!(
direct_ap_support().is_supported(),
platform_tag() == "windows"
);
}
}
@@ -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]> {
@@ -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,
},
@@ -21,6 +21,8 @@ use std::{
pub const PREFERRED_PORT: u16 = 39393;
pub const DISCOVERY_PORT: u16 = 39392;
pub const PARALLEL_CHUNK_SIZE: u64 = 8 * 1024 * 1024;
const MIN_PARALLEL_CHUNK_SIZE: u64 = 64 * 1024;
const MAX_PARALLEL_CHUNK_SIZE: u64 = 16 * 1024 * 1024;
const IO_BUFFER: usize = 1024 * 1024;
#[derive(Clone, Debug)]
@@ -34,6 +36,7 @@ pub enum ReceiverEvent {
#[derive(Debug)]
struct UploadSession {
upload_key: Option<String>,
device: String,
file_name: String,
size: u64,
@@ -56,6 +59,9 @@ struct CompletedUpload {
pub struct ReceiverServer {
pub port: u16,
/// PC↔PC 的配对秘密(3 字节)。UI 会把它和本机地址一起编成连接码,
/// 用户只需要念/粘贴那一串,不必再单独报 IP 和端口。
pub secret: [u8; crate::connect_code::SECRET_LEN],
stop: Arc<AtomicBool>,
tcp_thread: Option<JoinHandle<()>>,
udp_thread: Option<JoinHandle<()>>,
@@ -73,6 +79,11 @@ 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()));
// 24 bit 秘密对在线爆破仍然不够,靠严格失败计数兜底:
// 错 5 次即作废,必须重启接收重新生成。
let secret = crate::connect_code::new_secret();
let secret_hex: String = secret.iter().map(|b| format!("{b:02x}")).collect();
let pair_failures = Arc::new(AtomicU32::new(0));
let stop_tcp = stop.clone();
let sessions_tcp = sessions.clone();
@@ -80,6 +91,8 @@ impl ReceiverServer {
let token_tcp = session_token.clone();
let dir_tcp = save_dir.clone();
let events_tcp = events.clone();
let code_tcp = secret_hex.clone();
let failures_tcp = pair_failures.clone();
let tcp_thread = thread::spawn(move || {
while !stop_tcp.load(Ordering::Relaxed) {
match listener.accept() {
@@ -89,8 +102,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.
@@ -126,12 +141,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) => {}
@@ -144,6 +172,7 @@ impl ReceiverServer {
port,
stop,
tcp_thread: Some(tcp_thread),
secret,
udp_thread: Some(udp_thread),
})
}
@@ -161,14 +190,73 @@ impl Drop for ReceiverServer {
}
}
/// `POST /qft/pair`,请求头 `X-QFT-Code: 123456`。
///
/// 这是唯一不校验令牌的端点——它的作用就是用 6 位码换取令牌。
/// 6 位只有约 20 bit 熵,必须靠失败计数兜底:错 5 次即作废整个码,
/// 用户需要在电脑上重新启动接收才能拿到新码。
fn handle_pair(
stream: &mut TcpStream,
headers: &HashMap<String, String>,
token: &str,
pair_code: &str,
pair_failures: &AtomicU32,
events: &Sender<ReceiverEvent>,
) -> 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<ReceiverEvent>,
sessions: &SessionMap,
completed: &CompletedMap,
) -> Result<()> {
// The listener is non-blocking so the UI can poll for shutdown. On
// Windows an accepted socket may retain that mode, which made a body read
// race the next Wi-Fi Direct packet and fail with WSAEWOULDBLOCK (10035).
// File requests must instead wait under the explicit socket timeouts.
stream.set_nonblocking(false)?;
stream.set_nodelay(true).ok();
stream.set_read_timeout(Some(Duration::from_secs(120)))?;
stream.set_write_timeout(Some(Duration::from_secs(120)))?;
@@ -194,6 +282,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");
@@ -244,14 +337,39 @@ fn init_parallel_upload(
.parse().context("X-QFT-Size 无效")?;
let chunk_size = headers.get("x-qft-chunk-size")
.and_then(|v| v.parse::<u64>().ok())
.map(|v| v.clamp(1024 * 1024, 16 * 1024 * 1024))
.map(|v| v.clamp(MIN_PARALLEL_CHUNK_SIZE, MAX_PARALLEL_CHUNK_SIZE))
.unwrap_or(PARALLEL_CHUNK_SIZE);
let total_chunks_u64 = if size == 0 { 0 } else { (size + chunk_size - 1) / chunk_size };
if total_chunks_u64 > u32::MAX as u64 { bail!("文件分块数过大") }
let total_chunks = total_chunks_u64 as u32;
let upload_key = headers.get("x-qft-upload-key")
.map(|value| value.trim().to_owned())
.filter(|value| !value.is_empty() && value.len() <= 128);
let mut map = sessions.lock().map_err(|_| anyhow::anyhow!("上传会话锁损坏"))?;
// init is idempotent: if the response packet was lost, the Android client
// may repeat init. Return the existing session so already received chunks
// and the preallocated file are preserved instead of leaking a second part.
for (existing_id, existing) in map.iter() {
if let Ok(session) = existing.lock() {
if upload_key.is_some() && session.upload_key == upload_key {
let missing: Vec<usize> = session.received.iter().enumerate()
.filter_map(|(index, received)| if *received { None } else { Some(index) })
.collect();
let body = json!({
"ok": true,
"upload_id": existing_id,
"chunk_size": session.chunk_size,
"total_chunks": session.total_chunks,
"resumed": true,
"missing": missing,
}).to_string();
return write_response(stream, 200, "application/json", body.as_bytes());
}
}
}
let upload_id = random_id();
let mut map = sessions.lock().map_err(|_| anyhow::anyhow!("上传会话锁损坏"))?;
let final_path = unique_path_reserved(save_dir, &file_name, map.values());
let final_name = final_path.file_name().and_then(|v| v.to_str()).unwrap_or("qft-upload.bin");
let part_path = final_path.with_file_name(format!("{final_name}.{upload_id}.qftpart"));
@@ -261,6 +379,7 @@ fn init_parallel_upload(
drop(part);
let session = UploadSession {
upload_key,
device: device.to_owned(),
file_name: file_name.clone(),
size,
@@ -333,7 +452,7 @@ fn receive_parallel_chunk(
let mut out = OpenOptions::new().write(true).open(&part_path)?;
out.seek(SeekFrom::Start(offset))?;
copy_exact(reader, &mut out, content_len)?;
out.flush()?;
out.sync_data()?;
let received = {
let mut session = session_arc.lock().map_err(|_| anyhow::anyhow!("上传会话损坏"))?;
@@ -572,3 +691,65 @@ fn hex(bytes: &[u8]) -> String {
for &b in bytes { out.push(H[(b >> 4) as usize] as char); out.push(H[(b & 15) as usize] as char); }
out
}
#[cfg(test)]
mod tests {
use super::*;
use std::{
io::{Read, Write},
net::TcpListener,
sync::mpsc,
time::{SystemTime, UNIX_EPOCH},
};
#[test]
fn legacy_upload_waits_for_a_delayed_body_on_a_nonblocking_accepted_socket() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let dir = std::env::temp_dir().join(format!(
"qft-receiver-test-{}-{}",
std::process::id(),
SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos(),
));
fs::create_dir_all(&dir).unwrap();
let dir_for_server = dir.clone();
let (events, _updates) = mpsc::channel();
let sessions: SessionMap = Arc::new(Mutex::new(HashMap::new()));
let completed: CompletedMap = Arc::new(Mutex::new(HashMap::new()));
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
// This matches the Windows mode inheritance that previously made
// the body read return WSAEWOULDBLOCK between TCP packets.
stream.set_nonblocking(true).unwrap();
handle_client(
&mut stream,
&dir_for_server,
"session",
"000000",
&AtomicU32::new(0),
&events,
&sessions,
&completed,
)
});
let mut client = TcpStream::connect(address).unwrap();
client
.write_all(
b"POST /qft/upload HTTP/1.1\r\nHost: localhost\r\nX-QFT-Token: session\r\nContent-Length: 4\r\nX-QFT-Size: 4\r\n\r\n",
)
.unwrap();
client.flush().unwrap();
thread::sleep(Duration::from_millis(50));
client.write_all(b"qft!").unwrap();
client.flush().unwrap();
let mut response = String::new();
client.read_to_string(&mut response).unwrap();
server.join().unwrap().unwrap();
assert!(response.starts_with("HTTP/1.1 200"), "{response}");
assert_eq!(fs::read(dir.join("qft-upload.bin")).unwrap(), b"qft!");
let _ = fs::remove_dir_all(dir);
}
}
+99 -22
View File
@@ -128,6 +128,11 @@ fn handle_client(
token: &str,
events: &Sender<SenderEvent>,
) -> Result<()> {
// The listener is non-blocking so its owner can poll for shutdown. On
// Windows an accepted socket can retain that mode, causing a large Range
// response to fail with WSAEWOULDBLOCK (10035) between write calls.
// Downloads must wait under the explicit read/write timeouts instead.
stream.set_nonblocking(false)?;
stream.set_nodelay(true).ok();
stream.set_read_timeout(Some(Duration::from_secs(20)))?;
stream.set_write_timeout(Some(Duration::from_secs(120)))?;
@@ -168,18 +173,19 @@ fn handle_client(
if input.metadata()?.len() != size {
bail!("发送文件在二维码生成后发生变化,请重新选择文件并生成二维码")
}
let offset = parse_range_start(headers.get("range"), size)?;
let remaining = size.saturating_sub(offset);
let range = parse_range(headers.get("range"), size)?;
let offset = range.start;
let end = range.end;
let remaining = if size == 0 { 0 } else { end.saturating_sub(offset).saturating_add(1) };
let _ = events.send(SenderEvent::DownloadStarted { device: device.clone(), file_name: file_name.to_owned(), size });
if offset == 0 {
if headers.get("range").is_none() {
write!(stream,
"HTTP/1.1 200 OK\r\nContent-Type: application/octet-stream\r\nContent-Length: {remaining}\r\nAccept-Ranges: bytes\r\nConnection: close\r\nX-QFT-Filename: {}\r\n\r\n",
URL_SAFE_NO_PAD.encode(file_name.as_bytes()),
)?;
} else {
write!(stream,
"HTTP/1.1 206 Partial Content\r\nContent-Type: application/octet-stream\r\nContent-Length: {remaining}\r\nContent-Range: bytes {offset}-{}/{}\r\nAccept-Ranges: bytes\r\nConnection: close\r\nX-QFT-Filename: {}\r\n\r\n",
size - 1,
"HTTP/1.1 206 Partial Content\r\nContent-Type: application/octet-stream\r\nContent-Length: {remaining}\r\nContent-Range: bytes {offset}-{end}/{}\r\nAccept-Ranges: bytes\r\nConnection: close\r\nX-QFT-Filename: {}\r\n\r\n",
size,
URL_SAFE_NO_PAD.encode(file_name.as_bytes()),
)?;
@@ -187,10 +193,13 @@ fn handle_client(
use std::io::{Seek, SeekFrom};
input.seek(SeekFrom::Start(offset))?;
let mut buf = vec![0u8; IO_BUFFER];
loop {
let n = input.read(&mut buf)?;
if n == 0 { break }
let mut left = remaining;
while left > 0 {
let want = left.min(buf.len() as u64) as usize;
let n = input.read(&mut buf[..want])?;
if n == 0 { bail!("发送文件读取提前结束:还缺 {left} 字节") }
stream.write_all(&buf[..n])?;
left -= n as u64;
}
stream.flush()?;
let _ = events.send(SenderEvent::DownloadCompleted { device, file_name: file_name.to_owned() });
@@ -210,33 +219,53 @@ fn decode_header(value: Option<&String>) -> Option<String> {
String::from_utf8(bytes).ok()
}
fn parse_range_start(value: Option<&String>, size: u64) -> Result<u64> {
let Some(value) = value else { return Ok(0) };
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
struct ByteRange {
start: u64,
end: u64,
}
fn parse_range(value: Option<&String>, size: u64) -> Result<ByteRange> {
if size == 0 {
if value.is_some() { bail!("空文件没有可下载的字节范围") }
return Ok(ByteRange { start: 0, end: 0 });
}
let Some(value) = value else { return Ok(ByteRange { start: 0, end: size - 1 }) };
let suffix = value.trim().strip_prefix("bytes=").context("Range 格式无效")?;
let start = suffix.strip_suffix('-').context("只支持单段 Range")?
.parse::<u64>().context("Range 起点无效")?;
if start >= size { bail!("Range 超出文件范围") }
Ok(start)
let (start_text, end_text) = suffix.split_once('-').context("Range 格式无效")?;
if start_text.is_empty() { bail!("不支持后缀 Range") }
let start = start_text.parse::<u64>().context("Range 起点无效")?;
let end = if end_text.is_empty() {
size - 1
} else {
end_text.parse::<u64>().context("Range 终点无效")?
};
if start >= size || end >= size || end < start { bail!("Range 超出文件范围") }
Ok(ByteRange { start, end })
}
#[cfg(test)]
mod tests {
use super::{handle_client, parse_range_start, SenderEvent};
use super::{handle_client, parse_range, ByteRange, SenderEvent};
use std::{
fs,
io::{Read, Write},
net::{TcpListener, TcpStream},
sync::mpsc,
thread,
time::Duration,
};
#[test]
fn accepts_only_a_valid_resumable_byte_range() {
assert_eq!(parse_range_start(None, 10).unwrap(), 0);
assert_eq!(parse_range_start(Some(&"bytes=4-".to_owned()), 10).unwrap(), 4);
assert!(parse_range_start(Some(&"bytes=10-".to_owned()), 10).is_err());
assert!(parse_range_start(Some(&"bytes=-4".to_owned()), 10).is_err());
assert!(parse_range_start(Some(&"items=4-".to_owned()), 10).is_err());
fn accepts_open_and_bounded_byte_ranges() {
assert_eq!(parse_range(None, 10).unwrap(), ByteRange { start: 0, end: 9 });
assert_eq!(parse_range(None, 0).unwrap(), ByteRange { start: 0, end: 0 });
assert_eq!(parse_range(Some(&"bytes=4-".to_owned()), 10).unwrap(), ByteRange { start: 4, end: 9 });
assert_eq!(parse_range(Some(&"bytes=2-6".to_owned()), 10).unwrap(), ByteRange { start: 2, end: 6 });
assert!(parse_range(Some(&"bytes=10-".to_owned()), 10).is_err());
assert!(parse_range(Some(&"bytes=6-2".to_owned()), 10).is_err());
assert!(parse_range(Some(&"bytes=-4".to_owned()), 10).is_err());
assert!(parse_range(Some(&"items=4-".to_owned()), 10).is_err());
}
#[test]
@@ -248,7 +277,7 @@ mod tests {
let (events, _receiver) = mpsc::channel::<SenderEvent>();
let path_for_server = path.clone();
let server = thread::spawn(move || {
for _ in 0..2 {
for _ in 0..3 {
let (mut stream, _) = listener.accept().unwrap();
handle_client(&mut stream, &path_for_server, "range.bin", 6, "session", &events).unwrap();
}
@@ -260,11 +289,59 @@ mod tests {
assert_response(&resumed, "HTTP/1.1 206 Partial Content", "cdef");
let header = String::from_utf8_lossy(&resumed[..header_end(&resumed)]);
assert!(header.contains("Content-Range: bytes 2-5/6"));
let bounded = request(address, Some("bytes=2-4"));
assert_response(&bounded, "HTTP/1.1 206 Partial Content", "cde");
let header = String::from_utf8_lossy(&bounded[..header_end(&bounded)]);
assert!(header.contains("Content-Range: bytes 2-4/6"));
server.join().unwrap();
fs::remove_file(path).unwrap();
}
#[test]
fn large_download_waits_for_the_client_after_a_nonblocking_accept() {
let path = std::env::temp_dir().join(format!(
"qft-sender-{}-nonblocking.bin",
std::process::id(),
));
let payload = vec![0x5Au8; 2 * 1024 * 1024];
fs::write(&path, &payload).unwrap();
let file_size = payload.len() as u64;
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let (events, _receiver) = mpsc::channel::<SenderEvent>();
let path_for_server = path.clone();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
// Reproduce the Windows mode inheritance that caused Range
// writes to fail with WSAEWOULDBLOCK (10035).
stream.set_nonblocking(true).unwrap();
handle_client(
&mut stream,
&path_for_server,
"large.bin",
file_size,
"session",
&events,
)
});
let mut client = TcpStream::connect(address).unwrap();
client.write_all(
b"GET /qft/download HTTP/1.1\r\nHost: localhost\r\nX-QFT-Token: session\r\n\r\n",
).unwrap();
client.flush().unwrap();
thread::sleep(Duration::from_millis(50));
let mut response = Vec::new();
client.read_to_end(&mut response).unwrap();
server.join().unwrap().unwrap();
let body_start = header_end(&response);
assert!(String::from_utf8_lossy(&response[..body_start]).starts_with("HTTP/1.1 200 OK"));
assert_eq!(&response[body_start..], payload.as_slice());
fs::remove_file(path).unwrap();
}
fn request(address: std::net::SocketAddr, range: Option<&str>) -> Vec<u8> {
let mut stream = TcpStream::connect(address).unwrap();
write!(
+433
View File
@@ -0,0 +1,433 @@
# QFT5 光学链路方案(黑白 · 位阵列 · 陀螺仪稳定)
目标:
- **A**:相机 24 FPS 下,1 MB < 5 s(≥ 209.7 KB/s)
- **B**:相机 50~60 FPS 下,10 MB < 10 s(≥ 1048.6 KB/s)
- 相机帧率自动取系统最高值并锁死、稳定
- 手持抖动不导致丢锁重捕获
全程纯黑白(二值),不使用彩色或灰阶调制。
---
## 0. 选型结论:必须放弃 QR
| 方案 | B/画布 | @24fps | @60fps | 目标A | 目标B |
|---|---|---|---|---|---|
| QR 2×1 v40 @720p | 5 729 | 130 KB/s | 325 KB/s | 7.9 s ❌ | 32 s ❌ |
| QR 3×1 v40 @1080p | 8 593 | 193 KB/s | 463 KB/s | 5.3 s ❌ | 22.1 s ❌ |
| 位阵列 3.5 px/模块 @1080p | 15 571 | 350 KB/s | 839 KB/s | 2.9 s ✅ | 12.2 s ❌ |
| **位阵列 3.0 px/模块 @1080p** | **21 209** | 477 KB/s | **1143 KB/s** | **2.5 s ✅** | **9.0 s ✅** |
原因:QR 单符号上限 v40 = 177 模块。在 1080p 取景下相机能分辨约 330 模块/边,
单个 QR 只能用掉约 40% 的像素预算;横向排 3 个又受 16:9 宽度限制。
QR-L 本身还要付 finder/timing/format/RS 约 14% 的结构开销。
位阵列取消这三项限制:无版本上限、无 finder 图案、纠错交给喷泉码。
代价是不能再用 ZXing,需要自研采样解码器(见 §3.6,实际比 RS 解码更简单)。
**硬件前提(不满足则目标 B 无法达成,需在 App 内检测并提示):**
- 手机后摄支持 **1920×1080 ImageAnalysis @ 60 FPS**(用 `getOutputMinFrameDuration` 实测,非 flagship 常见只有 1080p30)
- 显示器 **≥ 60 Hz**,画布区可用宽度 **≥ 1824 逻辑像素**(3 显示 px/模块 × 608 模块)
- 取景需填满约 95% 画面 → 目标 B 建议使用支架
---
## 1. 需求一:相机帧率的获取、锁定与稳定
### 1.1 现有实现的三个缺陷
`MainActivity.chooseCameraFpsPlan()`(约 452 行):
1. **只读 `CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES`,没有按目标分辨率校验。**
该表是相机级能力,与具体输出尺寸无关。1080p 常见只支持 30 FPS,而 720p 支持 60。
现在的代码会对 1080p 请求一个它根本达不到的 `[60,60]`,结果要么被拒(走 fallback
丢失全部控制),要么被静默降频。
→ 必须用 `StreamConfigurationMap.getOutputMinFrameDuration(ImageFormat.YUV_420_888, size)`
算出**该尺寸的真实上限** `1e9 / minFrameDuration`,再与 AE 表求交集。
2. **没有优先选固定区间。** 排序是 `upper` 降序,所以 `[15,60]` 会排在 `[30,30]` 前面被选中。
可变区间授权 AE 在光线不足时把帧率降到 `lower`——这正是"不稳定"的根源。
→ 必须优先 `lower == upper` 的固定区间。
3. **没有验证实际达成帧率。** 请求 ≠ 实际。
### 1.2 三级锁定策略
```
L1 固定 AE 区间 CONTROL_AE_TARGET_FPS_RANGE = [max, max]
↓ 实测不达标
L2 全手动曝光(推荐) CONTROL_AE_MODE = OFF
SENSOR_FRAME_DURATION = 1e9 / fps
SENSOR_EXPOSURE_TIME = 2~4 ms
SENSOR_SENSITIVITY = ISO 200~400(按实测亮度标定一次)
↓ 设备拒绝该组合
L3 回退设备默认 + 降级目标(告知用户目标 B 不可达)
```
**L2 是真正的"锁死"**,也是本方案的推荐路径:屏幕是自发光强光源,2~4 ms 曝光完全够用;
AE 关闭后帧间隔由 `SENSOR_FRAME_DURATION` 精确决定,不再受测光波动影响。
更重要的是——**短曝光同时是防抖的第一杠杆**(见 §2.1)。
标定流程:启动时用 AE 自动跑 10 帧,读回 `CaptureResult` 的
`SENSOR_EXPOSURE_TIME` × `SENSOR_SENSITIVITY` 乘积作为曝光量基准,
再按"曝光缩到 3 ms、ISO 等比放大并夹到设备 `SENSOR_INFO_SENSITIVITY_RANGE` 上限"求解,
之后切 `AE_MODE_OFF` 固定住。
### 1.3 必须关闭 / 必须开启
| 项 | 设置 | 理由 |
|---|---|---|
| `CONTROL_VIDEO_STABILIZATION_MODE` | **OFF** | EIS 会逐帧裁切+几何形变,直接破坏单应矩阵跟踪 |
| `CONTROL_AE_ANTIBANDING_MODE` | **OFF** | 50 Hz 抗闪烁会把曝光量化到 10 ms 整数倍,与 2~4 ms 短曝光直接冲突,并把帧率钉死 |
| `NOISE_REDUCTION_MODE` | **OFF / FAST** | 强降噪会抹平单像素级模块边界 |
| `EDGE_MODE` | **OFF / FAST** | 锐化会产生振铃,制造伪模块边缘 |
| `LENS_OPTICAL_STABILIZATION_MODE` | **ON** | OIS 是光学补偿,不改成像几何,纯收益 |
| `CONTROL_AF_MODE` | 锁定后 **OFF** + 固定 `LENS_FOCUS_DISTANCE` | 连续 AF 每次搜索都产生几帧模糊 |
现有代码用 `AF_MODE_CONTINUOUS_PICTURE`(MainActivity 约 306 行)并在稳定锁定时
还周期性重新触发对焦(约 272 行)——对着固定距离的屏幕,这是纯负收益,必须改掉。
### 1.4 闭环验证("稳定下来"的判据)
用 `CaptureResult.SENSOR_TIMESTAMP` 做差分,滑动窗口 60 帧:
```
p50(Δt) → 实际帧率
p95(Δt) / p50(Δt) > 1.30 → 判定"不稳定",降一档重试
丢帧率 = count(Δt > 1.5 × p50) / N
```
三档实测都不稳定时,把目标降到"尽力而为"模式并在 UI 明示。
实测帧率必须回传给 Windows 端(通过配对二维码之外的一次性握手,或让用户手动选档),
**Windows 显示帧率 = 手机实测相机帧率**(见 §3.3,无需更精细的同步)。
---
## 2. 需求二:防抖 / 锁定不丢失
现有实现是"轴对齐矩形 + `smoothToward` 平滑 + 连续 miss 逐级扩大 + 10 次 miss 全幅重搜"
(`QrAnalyzer.decodeOptical` / `LockRect`)。三个结构性问题:
- 轴对齐矩形无法表达旋转与透视,手一歪矩形就被迫变大,分析面积和解码成本同时上升;
- ROI 只在**解码成功后**才更新,一旦 miss 就完全没有状态推进(无航位推算);
- 恢复策略是"扩大并祈祷"。
### 2.1 第一杠杆:短曝光(量化)
1080p、65° FOV → 等效焦距 **f ≈ 1507 px/rad**。运动模糊长度 = ω × t_exposure × f。
| 手持角速度 | 曝光 33 ms(自动) | 8 ms | 4 ms | 2 ms |
|---|---|---|---|---|
| 3 °/s(平稳) | 2.60 px = 0.87 模块 ❌ | 0.63 px ✅ | 0.32 px ✅ | 0.16 px ✅ |
| 10 °/s(典型手持) | **8.68 px = 2.89 模块 ❌** | 2.10 px ❌ | 1.05 px ⚠️ | 0.53 px ✅ |
| 20 °/s(明显晃动) | 17.36 px ❌ | 4.21 px ❌ | 2.10 px ❌ | 1.05 px ⚠️ |
**在 3 px/模块下,自动曝光的 33 ms 会抹掉近 3 个模块——必然解不出。**
这解释了当前"识别率不高"的相当一部分。锁到 2~4 ms 后模糊降到 1 px 以内。
判据:`blur = ω · t_exp · f < 0.7 模块`。
### 2.2 第二杠杆:陀螺仪前馈(真正的"防抖")
60 FPS 下 10 °/s 的帧间像素位移 = **4.4 px**,看似很小,但连续 10 帧漂移 44 px,
远超 `smoothToward` 的跟随带宽——这就是丢锁的直接机理。陀螺仪可以**提前**算出这个位移。
```
SensorManager.registerListener(TYPE_GYROSCOPE_UNCALIBRATED, SENSOR_DELAY_FASTEST) // ~200 Hz
环形缓冲 (timestampNanos, ωx, ωy, ωz)
对每个相机帧 t:
1. 校验 SENSOR_INFO_TIMESTAMP_SOURCE == REALTIME,
使 ImageProxy.imageInfo.timestamp 与陀螺时间戳同域(elapsedRealtimeNanos)
2. 积分 [t-1, t] 区间的角速度 → Δθ = (Δθx, Δθy, Δθz)
3. 小角近似的图像位移:
dx ≈ -f · Δθy dy ≈ f · Δθx roll ≈ Δθz
(需按 sensorOrientation / 显示旋转做一次坐标系映射)
4. 用 dx, dy, roll 预推上一帧的 4 个角标位置
5. 只在预测点 ±12 px 的窗口内做角标模板匹配
```
效果:搜索窗从"全幅" 降到 4 个 25×25 px 的小窗,即使剧烈晃动也能保持跟踪。
陀螺仪对**旋转**敏感,而手持抖动在 30 cm 距离上 90% 以上的像素位移来自旋转而非平移,
所以纯陀螺前馈就足够,不需要 IMU 融合。
### 2.3 第三杠杆:模糊门控
在解码前用陀螺仪算曝光窗口内的模糊长度。若 `blur > 0.7 模块`,
**直接跳过该帧的采样解码**,只更新位姿预测。省下的 CPU 留给清晰帧。
这比"试着解、失败、扩大 ROI"的现有策略便宜一个数量级。
### 2.4 跟踪 4 角单应,不跟踪矩形
画布四角放**同心方环**基准标(比 QR finder 更抗透视,且可做亚像素质心定位),
四边中点再各放一个辅助标 → 8 个点解 8-DOF 单应矩阵 H。
- H 直接给出"画布坐标 → 图像坐标"的完整映射,倾斜/旋转/透视全部被吸收;
- 采样时用 H 逆映射,**不需要把图像旋正**,省掉一次全帧变换;
- 8 点冗余 → 遮挡 1~2 个标仍可解(最小二乘 + RANSAC 剔除)。
### 2.5 永不完全丢锁:三级恢复
```
L1 窄窗跟踪 预测点 ±12 px 每帧,成本 ~4 × 625 px
↓ 连续 3 帧失败
L2 陀螺预测窗 预测点 ±40 px + 放宽阈值 成本 ~4 × 6400 px
↓ 持续 0.5 s 失败
L3 全幅重捕获 降采样 1/4 的粗搜 + 精定位
```
关键是**永远保留最后一次有效的 H**,L3 也以它为先验起点。
现有的"10 次 miss 后 `lockRegion = null` 全量重来"必须删掉。
### 2.6 诚实提醒
目标 B(3.0 px/模块 @1080p60)在手持下几乎不可能长时间守住。
App 应持续统计陀螺 RMS,超阈值时明确提示"请靠稳桌沿或使用支架",
并在支架模式下自动切到更激进的参数档。目标 A(3.5 px/模块 @24fps)手持可行。
---
## 3. 需求三:QFT5 位阵列格式
### 3.1 画布布局
```
┌─◎──────────────────────────────────────◎─┐ ◎ = 同心方环基准标(4 角 + 4 边中点)
│ ▓▓░░▓░▓▓░ 帧序号条纹(上) ░▓░▓▓░░▓▓ │ 帧计数 8 bit,撕裂检测用
├──────────────────────────────────────────┤
│ 条带 0 ← 独立喷泉包(头 + 数据 + CRC)│
│ 条带 1 │
◎ 条带 … ◎ 共 12 条(@1080p 每条约 28 模块高)
│ 条带 11 │
├──────────────────────────────────────────┤
│ ▓▓░░▓░▓▓░ 帧序号条纹(下) ░▓░▓▓░░▓▓ │
└─◎──────────────────────────────────────◎─┘
```
@1080p / 3.0 px/模块 → **608 × 342 模块 = 207 936 模块/画布**
减去基准标、条纹、参考网格(约 4%)与喷泉冗余(15%)→ **净 21 209 B/画布**。
### 3.2 抗撕裂的水平条带设计(本方案的关键)
卷帘快门自上而下扫描,读出耗时 T_r ≈ 16~20 ms。期间显示器换页会在某一行产生撕裂:
上半部分是显示帧 k,下半部分是 k+1。
**如果画布是一个整体(如单个大 QR),撕裂帧 100% 报废。**
改成 12 条独立水平条带后,每条带自带头部(条带序号 + 喷泉种子 + CRC),于是:
- 撕裂线只穿过 **1 条**条带 → 只损失 1/12;
- 撕裂线上方的 11 条属于帧 k,下方的属于帧 k+1,**两边都是有效的新数据**;
- 效率 = (B − T_r·f_display) / B。@60 FPS、T_r=16 ms、B=12 → **92%**。
**推论:显示帧率直接设成相机帧率即可,不需要任何显示/相机同步机制。**
这消除了整个方案里最难工程化的一环。
(条带数 B 的选择:B 越大抗撕裂越好,但每条带的头部开销占比上升。
B=12 时头部开销约 0.9%,是合理平衡点。)
### 3.3 帧序号条纹(tear guard)
上下各一条 8 格黑白条纹,编码同一个 8-bit 帧计数。解码时先读这 16 个采样点:
- 上下一致 → 整帧属于同一显示帧,全部 12 条带可信;
- 不一致 → 存在撕裂,用二分法在条带边界上定位撕裂行,只丢弃跨越它的那一条。
成本:16 次采样。收益:把"撕裂帧全废"变成"损失 1/12"。
### 3.4 参考模块网格(局部阈值)
屏幕亮度不均、镜头暗角、moiré 会让全局阈值失效。
每 **16×16 模块**嵌入一对已知的黑/白参考模块(开销 0.78%),解码时:
```
读取所有参考对 → 得到稀疏的 (black_level, white_level) 采样点
→ 双线性插值出全画布的阈值面 threshold(x,y) = (black + white) / 2
→ 每个数据模块与其所在位置的插值阈值比较
```
这同时天然抵抗屏幕 PWM 调光造成的整体亮度波动。
### 3.5 喷泉码(条带级)
每条带 = 一个独立喷泉包:
```
条带头(12 B):magic(2) | sessionId(4) | blockId(2) | seed(4)
条带数据:~1 750 B
CRC32(4 B)
```
- 文件按 **块(block)** 切分,每块 64 个源分片;
- 编码包 = 块内随机子集的 XOR,参与集合由 `seed` 经约定 PRNG 还原;
- 前 64 个包用系统码(原始分片本身),信道好时零解码开销;
- 接收端每块维护 64×64 的 GF(2) 矩阵,高斯消元求解;
- 冗余 15%(即平均收到 1.15×N 个包即可解出)。
Windows 端可直接用 `raptorq` crate;Android 端建议自研分组 XOR + 高斯消元,
两端算法必须逐位对齐(提供跨语言测试向量)。
### 3.6 采样解码器(替代 ZXing)
比 RS 解码更简单,纯整数运算:
```
1. tear guard 检查(16 次采样) → 决定丢弃哪条带
2. 模糊门控(陀螺仪) → 可能直接跳过整帧
3. 从跟踪状态取单应矩阵 H
4. 读参考网格 → 插值阈值面
5. 对每个模块:用 H 逆映射取中心点采样,与阈值比较 → 1 bit
(只取中心单点,不做邻域平均——3 px/模块下中心点信噪比已足够,速度快 3 倍)
6. 逐条带校验 CRC32 → 通过的送入喷泉解码器
```
复杂度 O(模块数),@1080p 每帧 208 K 次采样。可用 NEON 向量化,
或直接在 `ImageProxy` 的 Y 平面上按行做(内存访问连续)。
实测预算:60 FPS 下约 12.5 M 采样/s,中端 SoC 单核即可,不需要 GPU。
**并行结构**:`analyze()` 回调只做"按 H 计算 ROI 并 memcpy Y 平面"然后立即
`image.close()` 返回;采样解码与喷泉解码交给 2~3 个 worker 线程。
注意现有 `GrayFrameBuffer` 是单实例、非线程安全的,必须改成 per-worker 实例。
---
## 4. Windows 发送端
### 4.1 显示管线(必须先修)
现状:`qr.rs` 生成 1024×1024 的 `ColorImage`(RGBA)= **4 MiB/帧**,
每帧 `texture.set()` 上传 GPU;`optical_cache.rs` 按 4 MiB/页 计算容量,
最多占用 **768 MiB** 内存。60 FPS 下这是 240 MB/s 的分配与上传。
改法:上传 **模块级纹理**(608×342 = 208 KB 灰度),用 `TextureOptions::NEAREST`
让 GPU 放大。绘制矩形边长取模块数的整数倍(608 × 3 = 1824 px),避免不均匀缩放。
- 纹理上传:4 MiB → 208 KB(**减少 95%**,且不随显示尺寸增长)
- 预编码缓存:768 MiB → < 20 MiB
- 60 FPS 变得毫无压力
### 4.2 换页时序
现有 `last_advance.elapsed() >= interval` 轮询会产生抖动。
改为**按 vsync 计数换页**:60 Hz 屏每 1 个 vsync 换一页 = 精确 60 FPS;
每 2 个 vsync 换一页 = 精确 30 FPS。保证每帧显示时长完全一致。
### 4.3 显示器体检
启动光学模式时检测:刷新率、画布区可用逻辑像素宽度、DPI 缩放。
不满足"≥60 Hz 且 ≥1824 px"时,明确提示目标 B 不可达并给出当前档位的预计耗时。
### 4.4 编码吞吐
60 FPS × 21 KB = 1.27 MB/s 的 XOR + 位阵列打包。Rayon 并行下可忽略。
---
## 5. 分阶段落地
| 阶段 | 内容 | 可验证指标 | 风险 |
|---|---|---|---|
| **P1** | Windows 模块级纹理 + vsync 换页 | 稳定 60.0 页/s,内存 < 50 MiB | 低 |
| **P2** | 相机帧率三级锁定 + 闭环验证 + 关 EIS/抗闪烁 + 锁 AF | p95/p50 < 1.30,实测帧率 = 标称 | 低 |
| **P3** | 手动曝光 2~4 ms + 陀螺仪前馈 + 模糊门控 | 10 °/s 晃动下不丢锁,模糊 < 1 px | 中 |
| **P4** | QFT5 画布格式 + 单应跟踪 + 采样解码器 | 单帧 208 K 模块解码 < 12 ms | **高** |
| **P5** | 条带喷泉码(两端对齐 + 跨语言测试向量) | 收包 1.15×N 即可还原 | 中 |
| **P6** | 1080p60 + tear guard + 参数调优 | 目标 A / B 达标 | 中 |
P1、P2 可以立刻做且零协议风险;P4 是主要工程量(估计是全部工作量的一半)。
**建议在 P4 之前先做一个离线验证台**:Windows 端把画布导出成 PNG 序列,
Android 端加一个"从相册读图解码"的调试入口,先在无相机噪声的条件下
把采样解码器和喷泉码调通,再接实时相机。这能省掉大量难以复现的现场调试。
---
## 5.1 P0 · 分辨率楔形标定(已实现)
上表所有数字都建立在一个未经实测的假设上:**px/模块 的真实下限**。
合成实验显示这个值仅因对焦质量不同就能在 3.1~5.7 之间摆动,
所以它必须先测出来,不能靠推算。工具已在 `scripts/` 下:
```bash
# 1. 生成标定图(尺寸填显示器的设备像素)
python scripts/wedge_gen.py --width 1920 --height 1080 --out out/wedge
# 2. 用浏览器打开 out/wedge.html,按 F11 全屏
# 页面左上角必须显示「缩放 1.000 ✅」,否则测量无效
# 3. 手机拍照:大致正立,四个黑色角标全部入画并尽量填满画面
# 建议在 2~4 个不同距离各拍一张
# 4. 分析
python scripts/wedge_analyze.py --spec out/wedge.json --photo IMG_0001.jpg
```
输出每条带的 **实测 px/模块 → 对比度 → 误码率**,并给出 BER=1e-3 的临界点,
以及按该临界点换算的画布净载荷与各帧率下的预计传输耗时。
`--analysis-width` 默认 1920,即把 12MP 原片降采样到 1080p,模拟真实的
ImageAnalysis 流;改成 1280 可直接对比 720p 分析流的能力差距。
自检(合成相机模型,无需硬件):`python scripts/wedge_selftest.py`。
### 标定结果如何反馈到本方案
| 实测临界 px/模块 | 结论 |
|---|---|
| ≤ 2.6 | 目标 B 有余量,可考虑 §5.2 的六边形点阵进一步加码 |
| 2.6 ~ 3.2 | 按本方案原样实施,目标 B 余量约 10% |
| 3.2 ~ 4.0 | 目标 B 不可达;目标 A 仍可达。需下调指标或提高分析分辨率 |
| > 4.0 | 光学链路能力远低于预期,应优先排查对焦/曝光(§1.2、§2.1) |
### 一个必须修正的设计细节
标定工具的误码率输出暴露了 §3.5 的一个缺口:**条带只有 CRC,没有内码**。
1750 B 的条带有约 14 000 bit,只要 1 bit 错就整条报废。
若要求带错率 < 13%(喷泉码 15% 冗余能承受的上限),
原始 BER 必须低于 **1e-5**——这对光学信道是很苛刻的。
因此条带内部必须加**内码**,形成"内码纠错 + 外层喷泉码纠删"的级联结构
(与 QR 内部用 RS 是同一思路)。粗估所需冗余 ≈ 48 × BER:
| 实测原始 BER | 内码冗余 |
|---|---|
| 1e-5 | 可省略 |
| 1e-4 | ~0.5% |
| 1e-3 | ~4.8% |
| 1e-2 | ~48%(此工作点不可用) |
`wedge_analyze.py` 已按此公式输出所需内码冗余,并计入净载荷估算。
---
## 6. 达标核算与回退
### 达标条件(目标 B)
```
1080p ImageAnalysis @ 60 FPS × 21 209 B/画布 × 92% 撕裂效率
= 1 143 KB/s → 10 MB / 9.0 s ✅(余量 10%)
```
余量只有 10%,任一环节退化都会掉出指标。必须全部满足:
手机支持 1080p60 分析、显示器 ≥60 Hz、3.0 px/模块下解码成功率 > 95%、使用支架。
### 达标条件(目标 A)
```
1080p @ 24 FPS × 15 571 B/画布(3.5 px/模块) × 96%
= 350 KB/s → 1 MB / 2.9 s ✅(余量 42%)
```
余量充足,手持可行。**建议把 3.5 px/模块设为默认档。**
### 回退阶梯
App 应根据实测能力自动选档,并在 UI 明示当前档位与预计耗时:
| 档位 | 分析分辨率 | px/模块 | 相机 FPS | 吞吐 | 适用 |
|---|---|---|---|---|---|
| 极速(支架) | 1080p | 3.0 | 60 | 1143 KB/s | 目标 B |
| 标准(手持) | 1080p | 3.5 | 24~30 | 350~438 KB/s | 目标 A |
| 保守 | 720p | 3.5 | 30 | 167 KB/s | 老设备 |
| 兼容 | 720p | 4.0 | 30 | 128 KB/s | 最低保障 |
### 何时不该用光学
仓库已有 `QFTSEND2` 扫码直传(`desktop/src/sender.rs`:HTTP + Range 续传 + UDP 发现),
10 MB 在局域网下是亚秒级。光学链路应明确定位为**物理隔离场景专用**,
并在选择大文件时主动提示直传方案与两者的预计耗时对比。
+16 -4
View File
@@ -1,4 +1,4 @@
# QFT protocol notes — v0.4.0-rc2
# QFT protocol notes — v0.4.7
## 1. Windows → Android optical: QFT2
@@ -36,7 +36,7 @@ senderLen 2 u16 BE
senderDevice N UTF-8
```
### Optical parameters in rc2
### Optical parameters in v0.4.7
- one QR per display frame;
- DATA payload: **450 B**;
@@ -75,7 +75,7 @@ The overlay is derived from the same ROI used by the decoder, so the green/yello
Discovery order includes QR hint, UDP `QFTDISC2`, gateway/direct candidates and bounded current-subnet fallback.
## 4. Android → Windows upload
## 4. 扫码本地直传(Android ↔ Windows)
Parallel v2 flow:
@@ -85,4 +85,16 @@ POST /qft/upload/chunk (parallel, offset based)
POST /qft/upload/finish
```
Windows preallocates a `.qftpart`, writes chunks at explicit offsets, verifies SHA-256, then renames to the final file. Per-file worker count is capped at 8; chunk size is selected from 4/8/16 MiB by file size.
Windows preallocates a `.qftpart`, writes chunks at explicit offsets, verifies SHA-256, then renames to the final file. Uploads target 8 workers per file (bounded by the usable chunks and device capacity); the requested chunk size is derived from the file size and clamped to **64 KiB–16 MiB**. Repeated `init` requests carrying the same `X-QFT-Upload-Key` resume the matching active upload session; repeated chunk and finish requests are idempotent so a lost response can be retried safely. Chunk completion is recorded only after the positioned write reaches stable storage.
## 5. Windows → Android download
The same QFTPAIR2 local session can declare the download direction. Android discovers and verifies the Windows sender, then downloads `GET /qft/download` with exact single-range requests:
```text
Range: bytes=<start>-<end>
```
The sender returns `206 Partial Content`, the matching `Content-Range`, and the exact requested body length. Android splits the file toward 8 workers with **64 KiB–16 MiB** chunks, stores each completed chunk in a `.qftpart.map` ledger, and resumes only missing chunks after a reconnect. Each range retries with the currently available `Network`; the complete partial file must pass SHA-256 before it is published to `Downloads/QFT`.
For both direct-transfer directions, the Windows listener may accept connections non-blockingly for shutdown responsiveness, but each accepted file socket is switched to blocking I/O with explicit timeouts before reading or writing request bodies. This prevents `WSAEWOULDBLOCK (10035)` from turning an in-progress parallel transfer into an HTTP 500 failure.
+219
View File
@@ -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 收尾验证<br/>把半成品编译掉"] --> P1["P1 桌面跨平台 + PC↔PC<br/>走现有 v2 协议"]
P1 --> P2["P2 QFT-Stream v3<br/>目录直传 + 加密"]
P2 --> P3["P3 移动端接入 v3"]
P3 --> P4["P4 手机 ↔ 手机"]
P2 -.并行.-> P5["P5 一致性套件<br/>+ 性能回归"]
P0 -.独立并行轨.-> OPT["QFT5 光学<br/>阻塞于楔形标定"]
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<b>.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。
+297
View File
@@ -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(已在用) |
+24
View File
@@ -0,0 +1,24 @@
import Foundation
import CryptoKit
func sha256Hex(_ data: Data) -> String {
SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
}
/// 从管道里读一行,带超时。用来等 MockPCServer 打印 `READY <port>`。
func readReadyLine(from handle: FileHandle, timeout: TimeInterval) -> String? {
let deadline = Date().addingTimeInterval(timeout)
var buffer = Data()
while Date() < deadline {
let available = handle.availableData
if available.isEmpty {
Thread.sleep(forTimeInterval: 0.02)
continue
}
buffer.append(available)
if let index = buffer.firstIndex(of: 0x0a) {
return String(data: buffer[buffer.startIndex..<index], encoding: .utf8)
}
}
return nil
}
+241
View File
@@ -0,0 +1,241 @@
#!/usr/bin/env python3
"""按 desktop/src/{sender,receiver}.rs 的线上语义实现的假电脑端。
存在的意义:Swift 客户端的线格式必须和 Rust 端逐字节一致,
而 Rust 端在这台机器上编译不了。这个 mock 把两端的契约固定下来,
任何一边改了 header 名、路径或 JSON 字段,集成测试都会红。
用法:
python3 MockPCServer.py --token <session> --serve <文件> --save-dir <目录> --port 0
启动后在 stdout 打印一行 `READY <port>`,供测试脚本读取。
"""
import argparse
import base64
import hashlib
import json
import os
import socket
import sys
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
STATE = {}
def b64url_decode(text):
padding = "=" * (-len(text) % 4)
return base64.urlsafe_b64decode(text + padding)
def b64url_encode(data):
return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
class Handler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"
def log_message(self, *_args):
pass
# -------------------------------------------------- 工具
def _json(self, code, payload):
body = json.dumps(payload).encode("utf-8")
self.send_response(code)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.send_header("Connection", "close")
self.end_headers()
self.wfile.write(body)
def _authorized(self):
if self.headers.get("X-QFT-Token") != STATE["token"]:
self.send_response(403)
self.send_header("Content-Length", "0")
self.send_header("Connection", "close")
self.end_headers()
return False
# 设备名必须是 base64url,解不出来说明客户端编码错了
device = self.headers.get("X-QFT-Device")
if device is not None:
b64url_decode(device).decode("utf-8")
return True
# -------------------------------------------------- GET
def do_GET(self):
if not self._authorized():
return
if self.path == "/qft/ping":
return self._json(200, {"ok": True, "protocol": 2, "parallel": True})
if self.path == "/qft/download":
return self._download()
return self._json(404, {"ok": False})
def _download(self):
path = STATE["serve"]
size = os.path.getsize(path)
offset = 0
header = self.headers.get("Range")
if header:
assert header.startswith("bytes="), "只支持 bytes= 形式的 Range"
assert header.endswith("-"), "sender.rs 只支持单段开区间 Range"
offset = int(header[len("bytes="):-1])
assert 0 <= offset < size, "Range 越界"
remaining = size - offset
self.send_response(206 if offset else 200)
self.send_header("Content-Type", "application/octet-stream")
self.send_header("Content-Length", str(remaining))
self.send_header("Accept-Ranges", "bytes")
if offset:
self.send_header("Content-Range", "bytes %d-%d/%d" % (offset, size - 1, size))
self.send_header("X-QFT-Filename", b64url_encode(os.path.basename(path).encode("utf-8")))
self.send_header("Connection", "close")
self.end_headers()
with open(path, "rb") as fh:
fh.seek(offset)
while True:
block = fh.read(256 * 1024)
if not block:
break
self.wfile.write(block)
# -------------------------------------------------- POST
def do_POST(self):
if not self._authorized():
return
if self.path == "/qft/upload/init":
return self._upload_init()
if self.path.startswith("/qft/upload/chunk/"):
return self._upload_chunk()
if self.path.startswith("/qft/upload/finish/"):
return self._upload_finish()
return self._json(404, {"ok": False})
def _upload_init(self):
name = b64url_decode(self.headers["X-QFT-Filename"]).decode("utf-8")
size = int(self.headers["X-QFT-Size"])
chunk_size = int(self.headers.get("X-QFT-Chunk-Size", 8 * 1024 * 1024))
chunk_size = max(1024 * 1024, min(16 * 1024 * 1024, chunk_size))
total = 0 if size == 0 else (size + chunk_size - 1) // chunk_size
upload_id = base64.urlsafe_b64encode(os.urandom(9)).decode("ascii").rstrip("=")
part = os.path.join(STATE["save_dir"], "%s.%s.qftpart" % (name, upload_id))
with open(part, "wb") as fh:
fh.truncate(size)
STATE["uploads"][upload_id] = {
"name": name, "size": size, "chunk_size": chunk_size,
"total": total, "part": part, "received": [False] * total,
"lock": threading.Lock(),
}
return self._json(200, {"ok": True, "upload_id": upload_id,
"chunk_size": chunk_size, "total_chunks": total})
def _upload_chunk(self):
suffix = self.path[len("/qft/upload/chunk/"):]
upload_id, _, index_text = suffix.partition("/")
index = int(index_text)
session = STATE["uploads"].get(upload_id)
if session is None:
return self._json(500, {"ok": False, "error": "unknown upload"})
length = int(self.headers["Content-Length"])
offset = index * session["chunk_size"]
expected = min(session["chunk_size"], session["size"] - offset)
assert length == expected, "chunk 长度不匹配:%d != %d" % (length, expected)
body = b""
while len(body) < length:
block = self.rfile.read(length - len(body))
if not block:
break
body += block
assert len(body) == length, "chunk 体不完整"
with session["lock"]:
if session["received"][index]:
return self._json(200, {"ok": True, "duplicate": True})
with open(session["part"], "r+b") as fh:
fh.seek(offset)
fh.write(body)
session["received"][index] = True
return self._json(200, {"ok": True})
def _upload_finish(self):
upload_id = self.path[len("/qft/upload/finish/"):]
session = STATE["uploads"].get(upload_id)
if session is None:
return self._json(500, {"ok": False, "error": "unknown upload"})
missing = session["received"].count(False)
if missing:
return self._json(409, {"ok": False, "missing": missing})
digest = hashlib.sha256()
with open(session["part"], "rb") as fh:
while True:
block = fh.read(1024 * 1024)
if not block:
break
digest.update(block)
final = os.path.join(STATE["save_dir"], session["name"])
os.replace(session["part"], final)
del STATE["uploads"][upload_id]
return self._json(200, {"ok": True, "sha256": digest.hexdigest(), "size": session["size"]})
def udp_responder(token, http_port, stop):
"""QFTDISC2:<token> → QFTHERE2:<token>:<port>,对应 sender.rs 的发现线程。"""
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
try:
sock.bind(("0.0.0.0", 39392))
except OSError:
return
sock.settimeout(0.25)
expected = ("QFTDISC2:%s" % token).encode("ascii")
reply = ("QFTHERE2:%s:%d" % (token, http_port)).encode("ascii")
while not stop.is_set():
try:
data, peer = sock.recvfrom(512)
except socket.timeout:
continue
except OSError:
break
if data == expected:
sock.sendto(reply, peer)
sock.close()
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--token", required=True)
parser.add_argument("--serve", required=True, help="供 /qft/download 下发的文件")
parser.add_argument("--save-dir", required=True, help="接收上传的目录")
parser.add_argument("--port", type=int, default=0)
parser.add_argument("--udp", action="store_true", help="同时启动 UDP 发现应答")
args = parser.parse_args()
STATE.update(token=args.token, serve=args.serve, save_dir=args.save_dir, uploads={})
os.makedirs(args.save_dir, exist_ok=True)
server = ThreadingHTTPServer(("127.0.0.1", args.port), Handler)
port = server.server_address[1]
stop = threading.Event()
if args.udp:
threading.Thread(target=udp_responder, args=(args.token, port, stop), daemon=True).start()
print("READY %d" % port, flush=True)
try:
server.serve_forever()
except KeyboardInterrupt:
pass
finally:
stop.set()
if __name__ == "__main__":
main()
+377
View File
@@ -0,0 +1,377 @@
import Foundation
// QFT iOS 核心层测试。刻意不依赖 XCTest:这样在只有 Command Line Tools、
// 没有 Xcode 的机器上也能 `swiftc` 直接编译运行,CI 与本地一致。
//
// 集成测试跑在 MockPCServer.py 上,该 mock 严格复刻 receiver.rs / sender.rs
// 的线上语义,因此这里通过 == 线格式与 Windows 端兼容。
var failures = 0
var checks = 0
func check(_ condition: Bool, _ message: String) {
checks += 1
if condition {
print(" ok \(message)")
} else {
failures += 1
print(" FAIL \(message)")
}
}
func checkEqual<T: Equatable>(_ actual: T, _ expected: T, _ message: String) {
check(actual == expected, "\(message)(实得 \(actual))")
}
func section(_ title: String) { print("\n== \(title) ==") }
// ---------------------------------------------------------------- Base64URL
section("Base64URL")
checkEqual(Base64URL.encode("QFT"), "UUZU", "编码无填充")
checkEqual(Base64URL.decodeString("UUZU"), "QFT", "解码往返")
check(Base64URL.decode("a+b/c") == nil, "拒绝标准 Base64 字母表")
check(Base64URL.decode("A") == nil, "拒绝不可能的长度")
checkEqual(Base64URL.encode(Data([0xfb, 0xff])), "-_8", "- 与 _ 替换正确")
checkEqual(Base64URL.decode("-_8"), Data([0xfb, 0xff]), "- 与 _ 解码正确")
for _ in 0..<200 {
let raw = Data((0..<Int.random(in: 0...64)).map { _ in UInt8.random(in: 0...255) })
if Base64URL.decode(Base64URL.encode(raw)) != raw {
check(false, "随机往返失败")
break
}
}
check(true, "200 组随机字节往返一致")
// ---------------------------------------------------------------- 配对二维码
section("配对二维码解析")
func makePairingText(prefix: String, _ object: [String: Any]) -> String {
let data = try! JSONSerialization.data(withJSONObject: object)
return prefix + Base64URL.encode(data)
}
let session = "abcdefghijklmnopqrstuvwxyz012345"
let uploadText = makePairingText(prefix: "QFTPAIR2:", [
"v": 2, "s": session, "n": "DESKTOP-QFT", "p": 39393,
"e": ["http://192.168.1.20:39393"],
])
let upload = PairingProtocol.parse(uploadText)
check(upload != nil, "解析 QFTPAIR2")
checkEqual(upload?.direction, .uploadToPC, "方向为上传")
checkEqual(upload?.session, session, "会话令牌")
checkEqual(upload?.port, 39393, "端口")
checkEqual(upload?.pcName, "DESKTOP-QFT", "电脑名")
checkEqual(upload?.endpoints.count, 1, "端点数量")
let downloadText = makePairingText(prefix: "QFTSEND2:", [
"v": 2, "s": session, "n": "DESKTOP-QFT", "p": 39393,
"e": ["http://10.0.0.5:39393"], "d": "d",
"f": "报告.pdf", "z": 1_234_567, "h": String(repeating: "ab", count: 32),
])
let download = PairingProtocol.parse(downloadText)
check(download != nil, "解析 QFTSEND2")
checkEqual(download?.direction, .downloadToPhone, "方向为下载")
checkEqual(download?.fileName, "报告.pdf", "文件名支持中文")
checkEqual(download?.fileSize, 1_234_567, "文件大小")
check(PairingProtocol.parse("QFTPAIR2:" + Base64URL.encode(
try! JSONSerialization.data(withJSONObject: [
"v": 2, "s": session, "p": 39393, "e": ["http://192.168.1.20:39393"], "d": "d",
]))) == nil, "前缀与方向不符时拒绝")
check(PairingProtocol.parse(makePairingText(prefix: "QFTSEND2:", [
"v": 2, "s": session, "p": 39393, "e": ["http://10.0.0.5:39393"], "d": "d",
"f": "x.bin", "z": 1, "h": "not-a-hash",
])) == nil, "SHA-256 格式错误时拒绝")
check(PairingProtocol.parse(makePairingText(prefix: "QFTPAIR2:", [
"v": 1, "s": session, "p": 39393, "e": ["http://192.168.1.20:39393"],
])) == nil, "版本号不是 2 时拒绝")
check(PairingProtocol.parse(makePairingText(prefix: "QFTPAIR2:", [
"v": 2, "s": "short", "p": 39393, "e": ["http://192.168.1.20:39393"],
])) == nil, "会话令牌过短时拒绝")
// ---------------------------------------------------------------- 端点白名单
section("端点白名单(二维码是不可信输入)")
let allowed = [
"http://192.168.1.1:39393", "http://10.1.2.3:39393",
"http://172.16.0.1:39393", "http://172.31.255.254:39393",
"http://127.0.0.1:39393", "http://169.254.1.2:39393",
]
for endpoint in allowed {
check(PairingProtocol.isAllowedLocalHTTPEndpoint(endpoint, expectedPort: 39393), "接受 \(endpoint)")
}
let rejected = [
"https://192.168.1.1:39393", // 只允许 http
"http://evil.com:39393", // 域名
"http://8.8.8.8:39393", // 公网
"http://172.32.0.1:39393", // 172 段边界外
"http://192.168.1.1:1234", // 端口不符
"http://user@192.168.1.1:39393", // 带凭据
"http://192.168.1.1:39393/path", // 带路径
"http://192.168.1.1:39393?a=b", // 带 query
"http://192.168.01.1:39393", // 非规范八位组
"http://192.168.1:39393", // 段数不足
"http://[::1]:39393", // IPv6
]
for endpoint in rejected {
check(!PairingProtocol.isAllowedLocalHTTPEndpoint(endpoint, expectedPort: 39393), "拒绝 \(endpoint)")
}
// ---------------------------------------------------------------- 本地网络
section("本机网络推导")
checkEqual(LocalNetwork.ipv4("192.168.1.20"), 0xC0A80114, "IPv4 转整数")
checkEqual(LocalNetwork.format(0xC0A80114), "192.168.1.20", "整数转 IPv4")
check(LocalNetwork.ipv4("192.168.1.256") == nil, "拒绝越界八位组")
// ---------------------------------------------------------------- 集成测试
section("集成:与 MockPCServer 的完整传输")
let root = URL(fileURLWithPath: CommandLine.arguments.count > 1 ? CommandLine.arguments[1]
: NSTemporaryDirectory()).appendingPathComponent("qft-ios-test", isDirectory: true)
try? FileManager.default.removeItem(at: root)
try! FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
let mockScript = URL(fileURLWithPath: #filePath)
.deletingLastPathComponent().appendingPathComponent("MockPCServer.py")
// 3 MiB + 一点零头,确保最后一块是不完整块
let payloadSize = 3 * 1024 * 1024 + 4321
var payload = Data(count: payloadSize)
payload.withUnsafeMutableBytes { buffer in
guard let base = buffer.bindMemory(to: UInt8.self).baseAddress else { return }
var state: UInt64 = 0x2026_0810
for index in 0..<payloadSize {
state = state &* 6364136223846793005 &+ 1442695040888963407
base[index] = UInt8((state >> 33) & 0xff)
}
}
let sourceURL = root.appendingPathComponent("payload.bin")
try! payload.write(to: sourceURL)
let payloadHash = sha256Hex(payload)
let saveDir = root.appendingPathComponent("received", isDirectory: true)
let downloadDir = root.appendingPathComponent("downloads", isDirectory: true)
try! FileManager.default.createDirectory(at: downloadDir, withIntermediateDirectories: true)
let token = "testsession0123456789abcdefghijk"
let process = Process()
process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
process.arguments = ["python3", mockScript.path, "--token", token,
"--serve", sourceURL.path, "--save-dir", saveDir.path, "--port", "0"]
let pipe = Pipe()
process.standardOutput = pipe
try! process.run()
var port = 0
let readyLine = readReadyLine(from: pipe.fileHandleForReading, timeout: 10)
if let readyLine, readyLine.hasPrefix("READY ") {
port = Int(readyLine.dropFirst("READY ".count).trimmingCharacters(in: .whitespaces)) ?? 0
}
check(port > 0, "mock 电脑端已启动(端口 \(port))")
if port > 0 {
let base = "http://127.0.0.1:\(port)"
let host = QFTHost(baseURL: base)
let sendPairing = PairingPayload(
version: 2, session: token, pcName: "MOCK-PC", port: port,
endpoints: [base], wifi: nil, direction: .downloadToPhone,
fileName: "payload.bin", fileSize: UInt64(payloadSize), sha256: payloadHash)
let semaphore = DispatchSemaphore(value: 0)
Task {
defer { semaphore.signal() }
// --- 发现 ---
let discovery = HostDiscovery(pairing: sendPairing, deviceName: "iPhone 测试机")
let located = try? await discovery.locate()
check(located?.baseURL == base, "通过二维码端点定位到电脑")
// --- 下载 ---
var lastFraction = 0.0
let downloader = DownloadClient(host: host, pairing: sendPairing,
deviceName: "iPhone 测试机",
destinationDirectory: downloadDir)
do {
let saved = try await downloader.run { lastFraction = $0.fraction }
let received = try Data(contentsOf: saved)
checkEqual(received.count, payloadSize, "下载字节数一致")
checkEqual(sha256Hex(received), payloadHash, "下载内容 SHA-256 一致")
check(lastFraction > 0.99, "进度回调抵达 100%")
checkEqual(saved.lastPathComponent, "payload.bin", "落盘文件名正确")
check(!FileManager.default.fileExists(atPath: saved.path + ".qftpart"), "临时文件已清理")
} catch {
check(false, "下载失败:\(error.localizedDescription)")
}
// --- 下载续传 ---
do {
let partURL = downloadDir.appendingPathComponent("payload.bin.qftpart")
try? FileManager.default.removeItem(at: partURL)
try payload.prefix(1_000_000).write(to: partURL)
let resumed = try await DownloadClient(host: host, pairing: sendPairing,
deviceName: "iPhone",
destinationDirectory: downloadDir).run { _ in }
let data = try Data(contentsOf: resumed)
checkEqual(sha256Hex(data), payloadHash, "从 1,000,000 字节处续传后内容仍正确")
try? FileManager.default.removeItem(at: resumed)
} catch {
check(false, "续传失败:\(error.localizedDescription)")
}
// --- 上传 ---
let uploadPairing = PairingPayload(
version: 2, session: token, pcName: "MOCK-PC", port: port,
endpoints: [base], wifi: nil, direction: .uploadToPC,
fileName: nil, fileSize: nil, sha256: nil)
do {
var seen = 0.0
let uploader = UploadClient(host: host, pairing: uploadPairing, deviceName: "iPhone 测试机")
let sha = try await uploader.run(fileURL: sourceURL) { seen = $0.fraction }
checkEqual(sha, payloadHash, "上传后电脑侧 SHA-256 与本地一致")
check(seen > 0.99, "上传进度回调抵达 100%")
let landed = saveDir.appendingPathComponent("payload.bin")
let data = try Data(contentsOf: landed)
checkEqual(data.count, payloadSize, "电脑侧落盘大小一致")
checkEqual(sha256Hex(data), payloadHash, "电脑侧落盘内容一致")
} catch {
check(false, "上传失败:\(error.localizedDescription)")
}
// --- 错误令牌必须被拒 ---
let badPairing = PairingPayload(
version: 2, session: "wrongsession0123456789abcdefghij", pcName: "MOCK-PC",
port: port, endpoints: [base], wifi: nil, direction: .uploadToPC,
fileName: nil, fileSize: nil, sha256: nil)
do {
_ = try await UploadClient(host: host, pairing: badPairing,
deviceName: "iPhone").run(fileURL: sourceURL) { _ in }
check(false, "错误令牌本应失败")
} catch {
check(true, "错误令牌被拒绝:\(error.localizedDescription)")
}
}
semaphore.wait()
}
process.terminate()
// ---------------------------------------------------------------- P2P 配对码
section("隔空投送式配对码")
let peerSample = PeerPairing(
version: 1, key: Data((0..<32).map { UInt8($0) }), instance: "qft-abcdefghijkl",
senderName: "我的 iPhone", fileName: "视频.mov", fileSize: 987_654_321,
sha256: String(repeating: "cd", count: 32))
let peerRoundTrip = PeerPairing.parse(peerSample.encode())
checkEqual(peerRoundTrip, peerSample, "QFTP2P1 编解码往返一致")
check(PeerPairing.isPeerText(peerSample.encode()), "前缀识别")
check(PairingProtocol.parse(peerSample.encode()) == nil, "P2P 码不会被误判为 QFTPAIR2")
func mutatedPeer(_ change: (inout [String: Any]) -> Void) -> String? {
var object: [String: Any] = [
"v": 1, "k": Base64URL.encode(Data(repeating: 7, count: 32)),
"i": "qft-abcdefghijkl", "n": "iPhone", "f": "a.bin",
"z": 10, "h": String(repeating: "ab", count: 32),
]
change(&object)
let data = try! JSONSerialization.data(withJSONObject: object)
return PeerPairing.prefix + Base64URL.encode(data)
}
check(PeerPairing.parse(mutatedPeer { $0["k"] = Base64URL.encode(Data(repeating: 7, count: 16)) }!) == nil,
"密钥不足 32 字节时拒绝")
check(PeerPairing.parse(mutatedPeer { $0["i"] = "bad instance!" }!) == nil, "非法实例名时拒绝")
check(PeerPairing.parse(mutatedPeer { $0["f"] = "../../etc/passwd" }!) == nil, "文件名含路径分隔符时拒绝")
check(PeerPairing.parse(mutatedPeer { $0["h"] = "zz" }!) == nil, "摘要格式错误时拒绝")
check(PeerPairing.newKey().count == 32, "新密钥为 32 字节")
check(PeerPairing.isValidInstance(PeerPairing.newInstance()), "新实例名合法")
check(PeerPairing.newKey() != PeerPairing.newKey(), "密钥每次不同")
// ---------------------------------------------------------------- P2P 传输
section("隔空投送式点对点传输(TLS-PSK 真实握手)")
let peerDir = root.appendingPathComponent("peer", isDirectory: true)
try! FileManager.default.createDirectory(at: peerDir, withIntermediateDirectories: true)
let peerSemaphore = DispatchSemaphore(value: 0)
Task {
defer { peerSemaphore.signal() }
let sender = PeerSender(fileURL: sourceURL, deviceName: "发送端 iPhone")
do {
let pairing = try sender.start()
checkEqual(pairing.fileSize, UInt64(payloadSize), "配对码里的文件大小")
checkEqual(pairing.sha256, payloadHash, "配对码里的 SHA-256 由发送端实算")
let port = try await sender.listeningPort()
check(port > 0, "监听器就绪(端口 \(port))")
// 二维码在真机上是扫出来的,这里模拟:编码 → 解码 → 用解出来的配对码连接
guard let scanned = PeerPairing.parse(pairing.encode()) else {
check(false, "配对码无法解析"); return
}
var receiver = PeerReceiver(pairing: scanned, destinationDirectory: peerDir)
receiver.directPort = port // 测试跳过 Bonjour,直连回环
async let sendSide: Void = sender.waitAndSend { _ in }
var peerFraction = 0.0
let saved = try await receiver.run { peerFraction = $0.fraction }
try await sendSide
let data = try Data(contentsOf: saved)
checkEqual(data.count, payloadSize, "P2P 收到字节数一致")
checkEqual(sha256Hex(data), payloadHash, "P2P 收到内容 SHA-256 一致")
check(peerFraction > 0.99, "P2P 进度回调抵达 100%")
check(!FileManager.default.fileExists(atPath: saved.path + ".qftpart"), "P2P 临时文件已清理")
} catch {
check(false, "P2P 传输失败:\(error.localizedDescription)")
}
sender.stop()
}
if peerSemaphore.wait(timeout: .now() + 60) == .timedOut {
check(false, "P2P 传输超时")
}
// 错误密钥必须握手失败
let wrongKeySemaphore = DispatchSemaphore(value: 0)
Task {
defer { wrongKeySemaphore.signal() }
let sender = PeerSender(fileURL: sourceURL, deviceName: "发送端")
do {
let pairing = try sender.start()
let port = try await sender.listeningPort()
let tampered = PeerPairing(version: 1, key: PeerPairing.newKey(),
instance: pairing.instance, senderName: pairing.senderName,
fileName: pairing.fileName, fileSize: pairing.fileSize,
sha256: pairing.sha256)
var receiver = PeerReceiver(pairing: tampered, destinationDirectory: peerDir)
receiver.directPort = port
_ = try await receiver.run { _ in }
check(false, "错误密钥本应握手失败")
} catch {
check(true, "错误密钥被 TLS-PSK 拒绝")
}
sender.stop()
}
if wrongKeySemaphore.wait(timeout: .now() + 30) == .timedOut {
check(false, "错误密钥用例超时(握手未在预期时间内失败)")
}
// 测试全程只写 root 下的临时目录,不碰 Documents
try? FileManager.default.removeItem(at: root)
print("\n检查 \(checks) 项,失败 \(failures) 项")
if failures > 0 {
print("IOS CORE TESTS FAILED")
exit(1)
}
print("IOS CORE TESTS PASSED")
+18
View File
@@ -0,0 +1,18 @@
#!/bin/bash
# 在只有 Command Line Tools 的机器上编译并运行 iOS 核心层测试。
#
# 核心层刻意不 import UIKit/AVFoundation,因此可以直接以 macOS 为目标编译,
# 在没有 Xcode / 没有模拟器的环境里也能验证协议、发现与传输逻辑。
set -euo pipefail
cd "$(dirname "$0")/.."
OUT="$(mktemp -d)"
trap 'rm -rf "$OUT"' EXIT
echo "== 编译 =="
swiftc -swift-version 5 -O \
QFT/Core/*.swift CoreTests/*.swift \
-o "$OUT/qft-core-tests"
echo "== 运行 =="
"$OUT/qft-core-tests" "$OUT"
+316
View File
@@ -0,0 +1,316 @@
// !$*UTF8*$!
{
archiveVersion = 1;
classes = {
};
objectVersion = 56;
objects = {
/* Begin PBXBuildFile section */
0469B1106E6746B3BE56007D /* UploadClient.swift in Sources */ = {isa = PBXBuildFile; fileRef = B8FB8A4A9482DB8F1234AE39 /* UploadClient.swift */; };
38E462342111ACFA8775D17B /* PairingProtocol.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5459D124A555B0E4121361E5 /* PairingProtocol.swift */; };
4D2B05655C76F69F32349834 /* PeerPairing.swift in Sources */ = {isa = PBXBuildFile; fileRef = 06E1A38EC22BBFED928C8EB6 /* PeerPairing.swift */; };
554512A1FC8A6F66E2784787 /* QFTApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 453B172D654B3AEDE4E36D1E /* QFTApp.swift */; };
6B2EB3BCEDA4855168DB4ACE /* HostDiscovery.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3776FFCC2817EF6BF3EEC4FD /* HostDiscovery.swift */; };
78FD5CF5E04D7E2483B90BAA /* HomeView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0B6863D13BC7270D7FCE21E7 /* HomeView.swift */; };
978F01FFFFF69591E44C8528 /* DownloadClient.swift in Sources */ = {isa = PBXBuildFile; fileRef = EAA81C375609633BD8DB42F3 /* DownloadClient.swift */; };
A80B2E7BF8035E27D115EF59 /* PeerLink.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8DD16686BB19417EDC0B611A /* PeerLink.swift */; };
BDCF0D82F0BD0328770A8ABD /* ScannerView.swift in Sources */ = {isa = PBXBuildFile; fileRef = F3B15455554D7647B44D5038 /* ScannerView.swift */; };
C0C0B5440A627CE758643A9F /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = C628A05E9C83375781E165EB /* Assets.xcassets */; };
E26487D1146FDF6DD5F92D80 /* TransferModel.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3017489412A6FCAE8995B32E /* TransferModel.swift */; };
EE5510DAC5BBB7F9D41A8F26 /* Base64URL.swift in Sources */ = {isa = PBXBuildFile; fileRef = 848334DC6B2D30622C7E2A45 /* Base64URL.swift */; };
/* End PBXBuildFile section */
/* Begin PBXFileReference section */
06E1A38EC22BBFED928C8EB6 /* PeerPairing.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PeerPairing.swift; sourceTree = "<group>"; };
0B6863D13BC7270D7FCE21E7 /* HomeView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = HomeView.swift; sourceTree = "<group>"; };
3017489412A6FCAE8995B32E /* TransferModel.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = TransferModel.swift; sourceTree = "<group>"; };
3776FFCC2817EF6BF3EEC4FD /* HostDiscovery.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = HostDiscovery.swift; sourceTree = "<group>"; };
453B172D654B3AEDE4E36D1E /* QFTApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = QFTApp.swift; sourceTree = "<group>"; };
5459D124A555B0E4121361E5 /* PairingProtocol.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PairingProtocol.swift; sourceTree = "<group>"; };
7E4A60F8CA5D515103446ED3 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
848334DC6B2D30622C7E2A45 /* Base64URL.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Base64URL.swift; sourceTree = "<group>"; };
8DD16686BB19417EDC0B611A /* PeerLink.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PeerLink.swift; sourceTree = "<group>"; };
928818DCDA72C62B2D8288D5 /* QFT.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = QFT.app; sourceTree = BUILT_PRODUCTS_DIR; };
B8FB8A4A9482DB8F1234AE39 /* UploadClient.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UploadClient.swift; sourceTree = "<group>"; };
C628A05E9C83375781E165EB /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
EAA81C375609633BD8DB42F3 /* DownloadClient.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DownloadClient.swift; sourceTree = "<group>"; };
F3B15455554D7647B44D5038 /* ScannerView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ScannerView.swift; sourceTree = "<group>"; };
/* End PBXFileReference section */
/* Begin PBXFrameworksBuildPhase section */
019BAB185F97B56993A7087D /* Frameworks */ = {
isa = PBXFrameworksBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
/* End PBXFrameworksBuildPhase section */
/* Begin PBXGroup section */
32AAB6DFB51CD1888CC4883B /* App */ = {
isa = PBXGroup;
children = (
0B6863D13BC7270D7FCE21E7 /* HomeView.swift */,
453B172D654B3AEDE4E36D1E /* QFTApp.swift */,
F3B15455554D7647B44D5038 /* ScannerView.swift */,
3017489412A6FCAE8995B32E /* TransferModel.swift */,
);
path = App;
sourceTree = "<group>";
};
36EDFB66685EBD501D3910CE /* QFT */ = {
isa = PBXGroup;
children = (
32AAB6DFB51CD1888CC4883B /* App */,
C628A05E9C83375781E165EB /* Assets.xcassets */,
EC599E8CF455428A5E3179CE /* Core */,
7E4A60F8CA5D515103446ED3 /* Info.plist */,
);
path = QFT;
sourceTree = "<group>";
};
47C128B82C29A60341C3928E = {
isa = PBXGroup;
children = (
36EDFB66685EBD501D3910CE /* QFT */,
83E44493474BECB586AAD962 /* Products */,
);
sourceTree = "<group>";
};
83E44493474BECB586AAD962 /* Products */ = {
isa = PBXGroup;
children = (
928818DCDA72C62B2D8288D5 /* QFT.app */,
);
name = Products;
sourceTree = "<group>";
};
EC599E8CF455428A5E3179CE /* Core */ = {
isa = PBXGroup;
children = (
848334DC6B2D30622C7E2A45 /* Base64URL.swift */,
EAA81C375609633BD8DB42F3 /* DownloadClient.swift */,
3776FFCC2817EF6BF3EEC4FD /* HostDiscovery.swift */,
5459D124A555B0E4121361E5 /* PairingProtocol.swift */,
8DD16686BB19417EDC0B611A /* PeerLink.swift */,
06E1A38EC22BBFED928C8EB6 /* PeerPairing.swift */,
B8FB8A4A9482DB8F1234AE39 /* UploadClient.swift */,
);
path = Core;
sourceTree = "<group>";
};
/* End PBXGroup section */
/* Begin PBXNativeTarget section */
497CBF7ECF21FFA362230876 /* QFT */ = {
isa = PBXNativeTarget;
buildConfigurationList = A886B50DF087AEF7B87CDC65 /* Build configuration list for PBXNativeTarget "QFT" */;
buildPhases = (
C2511B36F0F0E810A9E46328 /* Sources */,
019BAB185F97B56993A7087D /* Frameworks */,
C2112B99FC6905E49DE55430 /* Resources */,
);
buildRules = (
);
dependencies = (
);
name = QFT;
productName = QFT;
productReference = 928818DCDA72C62B2D8288D5 /* QFT.app */;
productType = "com.apple.product-type.application";
};
/* End PBXNativeTarget section */
/* Begin PBXProject section */
98F54143AB4E86B28C3AFEE0 /* Project object */ = {
isa = PBXProject;
attributes = {
BuildIndependentTargetsInParallel = 1;
LastSwiftUpdateCheck = 1600;
LastUpgradeCheck = 1600;
TargetAttributes = {
497CBF7ECF21FFA362230876 = {
CreatedOnToolsVersion = 16.0;
};
};
};
buildConfigurationList = 26E84C2B3712F7DFAC8AD93F /* Build configuration list for PBXProject "QFT" */;
compatibilityVersion = "Xcode 14.0";
developmentRegion = en;
hasScannedForEncodings = 0;
knownRegions = (
en,
Base,
"zh-Hans",
);
mainGroup = 47C128B82C29A60341C3928E;
productRefGroup = 83E44493474BECB586AAD962 /* Products */;
projectDirPath = "";
projectRoot = "";
targets = (
497CBF7ECF21FFA362230876 /* QFT */,
);
};
/* End PBXProject section */
/* Begin PBXResourcesBuildPhase section */
C2112B99FC6905E49DE55430 /* Resources */ = {
isa = PBXResourcesBuildPhase;
buildActionMask = 2147483647;
files = (
C0C0B5440A627CE758643A9F /* Assets.xcassets in Resources */,
);
runOnlyForDeploymentPostprocessing = 0;
};
/* End PBXResourcesBuildPhase section */
/* Begin PBXSourcesBuildPhase section */
C2511B36F0F0E810A9E46328 /* Sources */ = {
isa = PBXSourcesBuildPhase;
buildActionMask = 2147483647;
files = (
554512A1FC8A6F66E2784787 /* QFTApp.swift in Sources */,
78FD5CF5E04D7E2483B90BAA /* HomeView.swift in Sources */,
BDCF0D82F0BD0328770A8ABD /* ScannerView.swift in Sources */,
E26487D1146FDF6DD5F92D80 /* TransferModel.swift in Sources */,
EE5510DAC5BBB7F9D41A8F26 /* Base64URL.swift in Sources */,
38E462342111ACFA8775D17B /* PairingProtocol.swift in Sources */,
6B2EB3BCEDA4855168DB4ACE /* HostDiscovery.swift in Sources */,
978F01FFFFF69591E44C8528 /* DownloadClient.swift in Sources */,
0469B1106E6746B3BE56007D /* UploadClient.swift in Sources */,
4D2B05655C76F69F32349834 /* PeerPairing.swift in Sources */,
A80B2E7BF8035E27D115EF59 /* PeerLink.swift in Sources */,
);
runOnlyForDeploymentPostprocessing = 0;
};
/* End PBXSourcesBuildPhase section */
/* Begin XCBuildConfiguration section */
032222C0BAA33BC7119DFAF1 /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 47;
ENABLE_PREVIEWS = YES;
GENERATE_INFOPLIST_FILE = NO;
INFOPLIST_FILE = QFT/Info.plist;
IPHONEOS_DEPLOYMENT_TARGET = 18.6;
LD_RUNPATH_SEARCH_PATHS = (
"$(inherited)",
"@executable_path/Frameworks",
);
MARKETING_VERSION = 0.4.7;
PRODUCT_BUNDLE_IDENTIFIER = com.qft.transfer;
PRODUCT_NAME = "$(TARGET_NAME)";
SWIFT_EMIT_LOC_STRINGS = NO;
TARGETED_DEVICE_FAMILY = "1,2";
};
name = Release;
};
70DCC1EB255A5F3C8D9ED349 /* Debug */ = {
isa = XCBuildConfiguration;
buildSettings = {
ALWAYS_SEARCH_USER_PATHS = NO;
CLANG_ANALYZER_NONNULL = YES;
CLANG_ENABLE_MODULES = YES;
CLANG_ENABLE_OBJC_ARC = YES;
CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
COPY_PHASE_STRIP = NO;
DEBUG_INFORMATION_FORMAT = dwarf;
ENABLE_STRICT_OBJC_MSGSEND = YES;
ENABLE_TESTABILITY = YES;
GCC_NO_COMMON_BLOCKS = YES;
GCC_OPTIMIZATION_LEVEL = 0;
GCC_PREPROCESSOR_DEFINITIONS = (
"DEBUG=1",
"$(inherited)",
);
IPHONEOS_DEPLOYMENT_TARGET = 18.6;
MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
MTL_FAST_MATH = YES;
ONLY_ACTIVE_ARCH = YES;
SDKROOT = iphoneos;
SWIFT_ACTIVE_COMPILATION_CONDITIONS = "DEBUG $(inherited)";
SWIFT_OPTIMIZATION_LEVEL = "-Onone";
SWIFT_VERSION = 5.0;
};
name = Debug;
};
C3DCEEC1E0EB17A5583B8E94 /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ALWAYS_SEARCH_USER_PATHS = NO;
CLANG_ANALYZER_NONNULL = YES;
CLANG_ENABLE_MODULES = YES;
CLANG_ENABLE_OBJC_ARC = YES;
CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
COPY_PHASE_STRIP = NO;
DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
ENABLE_NS_ASSERTIONS = NO;
ENABLE_STRICT_OBJC_MSGSEND = YES;
GCC_NO_COMMON_BLOCKS = YES;
IPHONEOS_DEPLOYMENT_TARGET = 18.6;
MTL_ENABLE_DEBUG_INFO = NO;
MTL_FAST_MATH = YES;
ONLY_ACTIVE_ARCH = YES;
SDKROOT = iphoneos;
SWIFT_COMPILATION_MODE = wholemodule;
SWIFT_VERSION = 5.0;
VALIDATE_PRODUCT = YES;
};
name = Release;
};
DB189EBE9D4E38495C3C7EF5 /* Debug */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 47;
ENABLE_PREVIEWS = YES;
GENERATE_INFOPLIST_FILE = NO;
INFOPLIST_FILE = QFT/Info.plist;
IPHONEOS_DEPLOYMENT_TARGET = 18.6;
LD_RUNPATH_SEARCH_PATHS = (
"$(inherited)",
"@executable_path/Frameworks",
);
MARKETING_VERSION = 0.4.7;
PRODUCT_BUNDLE_IDENTIFIER = com.qft.transfer;
PRODUCT_NAME = "$(TARGET_NAME)";
SWIFT_EMIT_LOC_STRINGS = NO;
TARGETED_DEVICE_FAMILY = "1,2";
};
name = Debug;
};
/* End XCBuildConfiguration section */
/* Begin XCConfigurationList section */
26E84C2B3712F7DFAC8AD93F /* Build configuration list for PBXProject "QFT" */ = {
isa = XCConfigurationList;
buildConfigurations = (
70DCC1EB255A5F3C8D9ED349 /* Debug */,
C3DCEEC1E0EB17A5583B8E94 /* Release */,
);
defaultConfigurationIsVisible = 0;
defaultConfigurationName = Release;
};
A886B50DF087AEF7B87CDC65 /* Build configuration list for PBXNativeTarget "QFT" */ = {
isa = XCConfigurationList;
buildConfigurations = (
DB189EBE9D4E38495C3C7EF5 /* Debug */,
032222C0BAA33BC7119DFAF1 /* Release */,
);
defaultConfigurationIsVisible = 0;
defaultConfigurationName = Release;
};
/* End XCConfigurationList section */
};
rootObject = 98F54143AB4E86B28C3AFEE0 /* Project object */;
}
@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<Workspace
version = "1.0">
<FileRef
location = "self:">
</FileRef>
</Workspace>
+197
View File
@@ -0,0 +1,197 @@
import SwiftUI
import UniformTypeIdentifiers
struct HomeView: View {
/// 同一个 view 上挂多个 .fileImporter 会互相覆盖,只能有一个,
/// 所以用这个枚举区分「选完文件之后要干什么」。
private enum PickPurpose: Equatable {
case peerSend
case uploadToPC(PairingPayload)
}
@StateObject private var model = TransferModel()
@State private var pickPurpose: PickPurpose?
var body: some View {
NavigationStack {
content
.navigationTitle("QFT 快传")
.navigationBarTitleDisplayMode(.inline)
}
.fullScreenCover(isPresented: isScanning) {
ScannerView(onFound: { model.handleScanned($0) }, onCancel: { model.cancel() })
.ignoresSafeArea()
}
.fileImporter(isPresented: isPicking,
allowedContentTypes: [UTType.item], allowsMultipleSelection: false) { result in
let purpose = pickPurpose
pickPurpose = nil
guard case .success(let urls) = result, let url = urls.first else {
model.reset()
return
}
switch purpose {
case .peerSend: model.startPeerSend(fileURL: url)
case .uploadToPC(let pairing): model.startUpload(pairing, fileURL: url)
case nil: break
}
}
.onAppear { model.refreshReceivedFiles() }
.onChange(of: model.stage) { _, stage in
// 扫到 QFTPAIR2 之后才知道要选文件,所以选择器由 stage 驱动
if case .pickFileForUpload(let pairing) = stage {
pickPurpose = .uploadToPC(pairing)
}
}
}
private var isScanning: Binding<Bool> {
Binding(get: { model.stage == .scanning }, set: { if !$0 { model.cancel() } })
}
private var isPicking: Binding<Bool> {
Binding(get: { pickPurpose != nil }, set: { if !$0 { pickPurpose = nil } })
}
@ViewBuilder
private var content: some View {
switch model.stage {
case .idle, .scanning, .pickFileForUpload:
landing
case .connecting(let message):
StatusCard(icon: "antenna.radiowaves.left.and.right", title: message) {
ProgressView()
Button("取消", role: .cancel) { model.cancel() }
}
case .running(let message):
StatusCard(icon: "arrow.left.arrow.right", title: message) {
if let progress = model.progress {
ProgressView(value: progress.fraction)
Text("\(progress.readableSize) · \(progress.readableRate)")
.font(.footnote.monospacedDigit())
.foregroundStyle(.secondary)
} else {
ProgressView()
}
Button("取消", role: .cancel) { model.cancel() }
}
case .showingPeerCode(let pairing):
peerCode(pairing)
case .finished(let message, let url):
StatusCard(icon: "checkmark.circle.fill", title: message) {
if let url {
Text(url.lastPathComponent).font(.footnote).foregroundStyle(.secondary)
ShareLink(item: url) { Label("分享", systemImage: "square.and.arrow.up") }
}
Button("完成") { model.reset() }.buttonStyle(.borderedProminent)
}
case .failed(let message):
StatusCard(icon: "exclamationmark.triangle.fill", title: "传输失败") {
Text(message).font(.footnote).multilineTextAlignment(.center)
.foregroundStyle(.secondary)
Button("返回") { model.reset() }.buttonStyle(.borderedProminent)
}
}
}
private var landing: some View {
List {
Section {
ActionRow(icon: "qrcode.viewfinder", title: "扫码",
detail: "扫电脑上的二维码收发文件,或扫另一台 iPhone 的码接收") {
model.beginScan()
}
ActionRow(icon: "iphone.gen3.radiowaves.left.and.right", title: "发给附近的 iPhone",
detail: "选文件后显示二维码,对方扫一下即可,无需连同一个 Wi-Fi") {
pickPurpose = .peerSend
}
} footer: {
Text("与电脑互传需要手机和电脑连在同一个 Wi-Fi。iPhone 之间使用点对点直连,不经过路由器。")
}
if !model.receivedFiles.isEmpty {
Section("已接收") {
ForEach(model.receivedFiles, id: \.self) { url in
ShareLink(item: url) {
Label(url.lastPathComponent, systemImage: "doc")
.lineLimit(1)
}
}
}
}
}
}
private func peerCode(_ pairing: PeerPairing) -> some View {
VStack(spacing: 20) {
Text("让对方用 QFT 扫这个码")
.font(.headline)
if let image = QRRenderer.image(from: pairing.encode()) {
Image(uiImage: image)
.interpolation(.none)
.resizable()
.scaledToFit()
.frame(maxWidth: 300)
.padding()
.background(.white)
.clipShape(RoundedRectangle(cornerRadius: 16))
}
VStack(spacing: 4) {
Text(pairing.fileName).font(.subheadline).lineLimit(1)
Text(TransferProgress.readable(pairing.fileSize))
.font(.footnote).foregroundStyle(.secondary)
}
if let progress = model.progress {
ProgressView(value: progress.fraction)
.padding(.horizontal, 40)
Text("\(progress.readableSize) · \(progress.readableRate)")
.font(.footnote.monospacedDigit()).foregroundStyle(.secondary)
} else {
Label("等待对方扫码…", systemImage: "hourglass")
.font(.footnote).foregroundStyle(.secondary)
}
Button("取消", role: .cancel) { model.cancel() }
}
.padding()
}
}
private struct ActionRow: View {
let icon: String
let title: String
let detail: String
let action: () -> Void
var body: some View {
Button(action: action) {
HStack(spacing: 14) {
Image(systemName: icon)
.font(.title2)
.frame(width: 34)
VStack(alignment: .leading, spacing: 3) {
Text(title).font(.body.weight(.medium))
Text(detail).font(.caption).foregroundStyle(.secondary)
}
}
.padding(.vertical, 4)
}
.buttonStyle(.plain)
}
}
private struct StatusCard<Content: View>: View {
let icon: String
let title: String
@ViewBuilder let content: Content
var body: some View {
VStack(spacing: 18) {
Image(systemName: icon).font(.system(size: 44))
Text(title).font(.headline).multilineTextAlignment(.center)
content
}
.padding(32)
.frame(maxWidth: .infinity, maxHeight: .infinity)
}
}
+10
View File
@@ -0,0 +1,10 @@
import SwiftUI
@main
struct QFTApp: App {
var body: some Scene {
WindowGroup {
HomeView()
}
}
}
+137
View File
@@ -0,0 +1,137 @@
import SwiftUI
import AVFoundation
/// 二维码扫描。用 AVCaptureMetadataOutput 而不是 Vision:
/// 硬件解码路径延迟更低,而且这里只需要识别静态配对码,
/// 不需要 QFT2 光学链路那套 ROI 锁定与高频解码。
struct ScannerView: UIViewControllerRepresentable {
/// 只在识别到我们认识的前缀时回调,且只回调一次。
let onFound: (String) -> Void
let onCancel: () -> Void
func makeCoordinator() -> Coordinator { Coordinator(onFound: onFound) }
func makeUIViewController(context: Context) -> ScannerController {
let controller = ScannerController()
controller.coordinator = context.coordinator
controller.onCancel = onCancel
return controller
}
func updateUIViewController(_ controller: ScannerController, context: Context) {}
final class Coordinator: NSObject, AVCaptureMetadataOutputObjectsDelegate {
private let onFound: (String) -> Void
private var consumed = false
init(onFound: @escaping (String) -> Void) { self.onFound = onFound }
func metadataOutput(_ output: AVCaptureMetadataOutput,
didOutput objects: [AVMetadataObject],
from connection: AVCaptureConnection) {
guard !consumed else { return }
for object in objects {
guard let readable = object as? AVMetadataMachineReadableCodeObject,
readable.type == .qr, let text = readable.stringValue else { continue }
guard PairingProtocol.isPairingText(text) || PeerPairing.isPeerText(text) else { continue }
consumed = true
UINotificationFeedbackGenerator().notificationOccurred(.success)
DispatchQueue.main.async { self.onFound(text) }
return
}
}
}
}
final class ScannerController: UIViewController {
var coordinator: ScannerView.Coordinator?
var onCancel: (() -> Void)?
private let session = AVCaptureSession()
private var preview: AVCaptureVideoPreviewLayer?
private let hintLabel = UILabel()
override func viewDidLoad() {
super.viewDidLoad()
view.backgroundColor = .black
configureSession()
configureOverlay()
}
private func configureSession() {
guard let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back),
let input = try? AVCaptureDeviceInput(device: device),
session.canAddInput(input) else {
showFailure("无法打开相机")
return
}
session.addInput(input)
let output = AVCaptureMetadataOutput()
guard session.canAddOutput(output) else {
showFailure("无法启动二维码识别")
return
}
session.addOutput(output)
output.setMetadataObjectsDelegate(coordinator, queue: .main)
output.metadataObjectTypes = [.qr]
let layer = AVCaptureVideoPreviewLayer(session: session)
layer.videoGravity = .resizeAspectFill
layer.frame = view.bounds
view.layer.insertSublayer(layer, at: 0)
preview = layer
}
private func configureOverlay() {
hintLabel.text = "对准电脑或另一台 iPhone 上的二维码"
hintLabel.textColor = .white
hintLabel.font = .systemFont(ofSize: 15, weight: .medium)
hintLabel.textAlignment = .center
hintLabel.numberOfLines = 0
hintLabel.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(hintLabel)
let cancel = UIButton(type: .system)
cancel.setTitle("取消", for: .normal)
cancel.setTitleColor(.white, for: .normal)
cancel.titleLabel?.font = .systemFont(ofSize: 17, weight: .semibold)
cancel.addTarget(self, action: #selector(cancelTapped), for: .touchUpInside)
cancel.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(cancel)
NSLayoutConstraint.activate([
hintLabel.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 32),
hintLabel.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -32),
hintLabel.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -96),
cancel.centerXAnchor.constraint(equalTo: view.centerXAnchor),
cancel.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -32),
])
}
@objc private func cancelTapped() { onCancel?() }
private func showFailure(_ message: String) {
hintLabel.text = message
}
override func viewWillAppear(_ animated: Bool) {
super.viewWillAppear(animated)
guard !session.isRunning else { return }
// startRunning 会阻塞,必须离开主线程
DispatchQueue.global(qos: .userInitiated).async { [session] in session.startRunning() }
}
override func viewWillDisappear(_ animated: Bool) {
super.viewWillDisappear(animated)
guard session.isRunning else { return }
DispatchQueue.global(qos: .userInitiated).async { [session] in session.stopRunning() }
}
override func viewDidLayoutSubviews() {
super.viewDidLayoutSubviews()
preview?.frame = view.bounds
}
}
+242
View File
@@ -0,0 +1,242 @@
import SwiftUI
import CoreImage.CIFilterBuiltins
@MainActor
final class TransferModel: ObservableObject {
enum Stage: Equatable {
case idle
case scanning
/// 扫到 QFTPAIR2:需要用户挑一个文件传给电脑
case pickFileForUpload(PairingPayload)
case connecting(String)
case running(String)
case showingPeerCode(PeerPairing)
case finished(String, URL?)
case failed(String)
}
@Published private(set) var stage: Stage = .idle
@Published private(set) var progress: TransferProgress?
@Published private(set) var receivedFiles: [URL] = []
private var task: Task<Void, Never>?
private var sender: PeerSender?
private var scopedURL: URL?
private let deviceName = DeviceInfo.name
// MARK: - 入口
func beginScan() { stage = .scanning }
func cancel() {
task?.cancel()
task = nil
sender?.stop()
sender = nil
releaseScope()
progress = nil
stage = .idle
}
func reset() {
progress = nil
stage = .idle
refreshReceivedFiles()
}
/// 扫到码之后的统一分发
func handleScanned(_ text: String) {
if let peer = PeerPairing.parse(text) {
startPeerReceive(peer)
return
}
guard let pairing = PairingProtocol.parse(text) else {
stage = .failed("这不是 QFT 的二维码,或二维码里的地址不是局域网地址。")
return
}
switch pairing.direction {
case .downloadToPhone: startDownload(pairing)
case .uploadToPC: stage = .pickFileForUpload(pairing)
}
}
// MARK: - 电脑 → 手机
private func startDownload(_ pairing: PairingPayload) {
stage = .connecting("正在找 \(pairing.pcName)…")
task = Task {
do {
let host = try await HostDiscovery(pairing: pairing, deviceName: deviceName).locate()
guard !Task.isCancelled else { return }
stage = .running("正在从 \(pairing.pcName) 接收 \(pairing.fileName ?? "文件")")
let client = DownloadClient(host: host, pairing: pairing, deviceName: deviceName)
let saved = try await client.run { [weak self] value in
Task { @MainActor in self?.progress = value }
}
finish("已保存到「文件」App 的 QFT 文件夹", saved)
} catch {
fail(error)
}
}
}
// MARK: - 手机 → 电脑
func startUpload(_ pairing: PairingPayload, fileURL: URL) {
guard claimScope(fileURL) else {
stage = .failed("没有权限读取这个文件,请换一个位置再试。")
return
}
stage = .connecting("正在找 \(pairing.pcName)…")
task = Task {
defer { releaseScope() }
do {
let host = try await HostDiscovery(pairing: pairing, deviceName: deviceName).locate()
guard !Task.isCancelled else { return }
stage = .running("正在发送 \(fileURL.lastPathComponent) 到 \(pairing.pcName)")
let client = UploadClient(host: host, pairing: pairing, deviceName: deviceName)
_ = try await client.run(fileURL: fileURL) { [weak self] value in
Task { @MainActor in self?.progress = value }
}
finish("已发送到 \(pairing.pcName)", nil)
} catch {
fail(error)
}
}
}
// MARK: - iPhone ↔ iPhone(隔空投送式)
func startPeerSend(fileURL: URL) {
guard claimScope(fileURL) else {
stage = .failed("没有权限读取这个文件,请换一个位置再试。")
return
}
stage = .connecting("正在准备…")
task = Task {
defer { releaseScope() }
do {
let sender = PeerSender(fileURL: fileURL, deviceName: deviceName)
// start() 里要完整读一遍文件算摘要,别卡住主线程
let pairing = try await Task.detached { try sender.start() }.value
guard !Task.isCancelled else { sender.stop(); return }
self.sender = sender
stage = .showingPeerCode(pairing)
try await sender.waitAndSend { [weak self] value in
Task { @MainActor in self?.progress = value }
}
finish("已发送给对方", nil)
} catch {
fail(error)
}
sender?.stop()
sender = nil
}
}
private func startPeerReceive(_ pairing: PeerPairing) {
stage = .connecting("正在连接 \(pairing.senderName)…")
task = Task {
do {
let directory = try DownloadClient.defaultDestinationDirectory()
let receiver = PeerReceiver(pairing: pairing, destinationDirectory: directory)
stage = .running("正在接收 \(pairing.fileName)")
let saved = try await receiver.run { [weak self] value in
Task { @MainActor in self?.progress = value }
}
finish("已保存到「文件」App 的 QFT 文件夹", saved)
} catch {
fail(error)
}
}
}
// MARK: - 收尾
private func finish(_ message: String, _ url: URL?) {
progress = nil
stage = .finished(message, url)
refreshReceivedFiles()
}
private func fail(_ error: Error) {
guard !(error is CancellationError) else { return }
progress = nil
stage = .failed(error.localizedDescription)
}
func refreshReceivedFiles() {
guard let directory = try? DownloadClient.defaultDestinationDirectory(),
let entries = try? FileManager.default.contentsOfDirectory(
at: directory, includingPropertiesForKeys: [.contentModificationDateKey]) else {
receivedFiles = []
return
}
receivedFiles = entries
.filter { $0.pathExtension != "qftpart" }
.sorted { lhs, rhs in
let l = (try? lhs.resourceValues(forKeys: [.contentModificationDateKey]))?
.contentModificationDate ?? .distantPast
let r = (try? rhs.resourceValues(forKeys: [.contentModificationDateKey]))?
.contentModificationDate ?? .distantPast
return l > r
}
}
// MARK: - 安全作用域
/// 文件选择器给的 URL 属于其他进程的沙盒,读之前必须声明作用域,
/// 而且整个传输期间都要持有。
private func claimScope(_ url: URL) -> Bool {
releaseScope()
guard url.startAccessingSecurityScopedResource() else { return false }
scopedURL = url
return true
}
private func releaseScope() {
scopedURL?.stopAccessingSecurityScopedResource()
scopedURL = nil
}
}
// MARK: - 二维码渲染
enum QRRenderer {
/// 配对码只有几百字节,用 M 级纠错换取更好的首次识别率。
static func image(from text: String) -> UIImage? {
let filter = CIFilter.qrCodeGenerator()
filter.message = Data(text.utf8)
filter.correctionLevel = "M"
guard let output = filter.outputImage else { return nil }
// 放大用最近邻,避免插值把模块边缘糊掉
let scaled = output.transformed(by: CGAffineTransform(scaleX: 12, y: 12))
let context = CIContext()
guard let cgImage = context.createCGImage(scaled, from: scaled.extent) else { return nil }
return UIImage(cgImage: cgImage)
}
}
extension TransferProgress {
var readableRate: String {
let units = ["B/s", "KB/s", "MB/s", "GB/s"]
var value = bytesPerSecond
var index = 0
while value >= 1024, index < units.count - 1 { value /= 1024; index += 1 }
return String(format: "%.1f %@", value, units[index])
}
var readableSize: String {
Self.readable(completed) + " / " + Self.readable(total)
}
static func readable(_ bytes: UInt64) -> String {
let units = ["B", "KB", "MB", "GB"]
var value = Double(bytes)
var index = 0
while value >= 1024, index < units.count - 1 { value /= 1024; index += 1 }
return String(format: index == 0 ? "%.0f %@" : "%.1f %@", value, units[index])
}
}
@@ -0,0 +1,4 @@
{
"colors" : [ { "idiom" : "universal" } ],
"info" : { "author" : "xcode", "version" : 1 }
}
@@ -0,0 +1,6 @@
{
"images" : [
{ "idiom" : "universal", "platform" : "ios", "size" : "1024x1024" }
],
"info" : { "author" : "xcode", "version" : 1 }
}
+3
View File
@@ -0,0 +1,3 @@
{
"info" : { "author" : "xcode", "version" : 1 }
}
+46
View File
@@ -0,0 +1,46 @@
import Foundation
/// RFC 4648 §5 的 URL-safe Base64,无填充。
/// Windows 端用 `URL_SAFE_NO_PAD` 编码设备名、文件名与配对载荷,
/// Android 端对应 `Base64Url`,三端必须逐字节一致。
enum Base64URL {
static func encode(_ data: Data) -> String {
var text = data.base64EncodedString()
text = text.replacingOccurrences(of: "+", with: "-")
text = text.replacingOccurrences(of: "/", with: "_")
while text.hasSuffix("=") { text.removeLast() }
return text
}
static func encode(_ text: String) -> String {
encode(Data(text.utf8))
}
static func decode(_ text: String) -> Data? {
// 只接受合法字母表,避免把任意输入喂给 Data(base64Encoded:)
// 后得到一个「解出来了但不是原意」的结果。
guard !text.isEmpty else { return Data() }
for scalar in text.unicodeScalars {
switch scalar {
case "A"..."Z", "a"..."z", "0"..."9", "-", "_":
continue
default:
return nil
}
}
var padded = text.replacingOccurrences(of: "-", with: "+")
padded = padded.replacingOccurrences(of: "_", with: "/")
let remainder = padded.count % 4
if remainder == 1 { return nil } // 不可能出现的长度
if remainder != 0 {
padded.append(String(repeating: "=", count: 4 - remainder))
}
return Data(base64Encoded: padded)
}
static func decodeString(_ text: String) -> String? {
guard let data = decode(text) else { return nil }
return String(data: data, encoding: .utf8)
}
}
+210
View File
@@ -0,0 +1,210 @@
import Foundation
import CryptoKit
struct TransferProgress {
let completed: UInt64
let total: UInt64
let bytesPerSecond: Double
var fraction: Double {
total == 0 ? 1 : min(1, Double(completed) / Double(total))
}
}
/// 电脑 → 手机下载(QFTSEND2)。
///
/// 边收边写盘、边算 SHA-256,中断后用 `Range: bytes=N-` 续传。
/// Windows 端 `sender.rs` 只支持单段 Range,这里也只发单段。
final class DownloadClient: NSObject {
private let host: QFTHost
private let pairing: PairingPayload
private let deviceName: String
/// 落盘目录。默认 Documents/QFT(会出现在「文件」App 里);
/// 测试注入临时目录,避免碰到用户真实的文档目录。
private let destinationDirectory: URL?
private var fileHandle: FileHandle?
private var hasher = SHA256()
private var written: UInt64 = 0
private var expectedTotal: UInt64 = 0
private var startedAt = Date()
private var lastReport = Date.distantPast
private var onProgress: ((TransferProgress) -> Void)?
private var continuation: CheckedContinuation<Void, Error>?
private var session: URLSession?
init(host: QFTHost, pairing: PairingPayload, deviceName: String,
destinationDirectory: URL? = nil) {
self.host = host
self.pairing = pairing
self.deviceName = deviceName
self.destinationDirectory = destinationDirectory
super.init()
}
/// 下载到目标目录,返回最终文件 URL。
func run(onProgress: @escaping (TransferProgress) -> Void) async throws -> URL {
let name = pairing.fileName ?? "qft-download.bin"
let directory = try destinationDirectory ?? Self.defaultDestinationDirectory()
let partURL = directory.appendingPathComponent(name + ".qftpart")
// 续传:已经落盘多少就从多少开始要
var resumeFrom: UInt64 = 0
if let attributes = try? FileManager.default.attributesOfItem(atPath: partURL.path),
let size = attributes[.size] as? NSNumber {
resumeFrom = UInt64(truncating: size)
}
if resumeFrom > 0, let declared = pairing.fileSize, resumeFrom >= declared {
// 断点比声明的文件还大,说明这个 .qftpart 不是本次会话的,丢弃重来
try? FileManager.default.removeItem(at: partURL)
resumeFrom = 0
}
if resumeFrom > 0 {
// 续传时无法复用之前的哈希中间态,重新扫一遍已落盘的部分
hasher = SHA256()
let handle = try FileHandle(forReadingFrom: partURL)
defer { try? handle.close() }
while let block = try handle.read(upToCount: 4 * 1024 * 1024), !block.isEmpty {
hasher.update(data: block)
}
} else {
FileManager.default.createFile(atPath: partURL.path, contents: nil)
}
self.written = resumeFrom
self.expectedTotal = pairing.fileSize ?? 0
self.onProgress = onProgress
self.startedAt = Date()
self.fileHandle = try FileHandle(forWritingTo: partURL)
try fileHandle?.seekToEnd()
guard let url = URL(string: host.baseURL + "/qft/download") else {
throw QFTError.malformedResponse("下载地址无效")
}
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = 30
request.setValue(pairing.session, forHTTPHeaderField: "X-QFT-Token")
request.setValue(Base64URL.encode(deviceName), forHTTPHeaderField: "X-QFT-Device")
if resumeFrom > 0 {
request.setValue("bytes=\(resumeFrom)-", forHTTPHeaderField: "Range")
}
let configuration = URLSessionConfiguration.ephemeral
configuration.timeoutIntervalForRequest = 30
configuration.timeoutIntervalForResource = 3600
let urlSession = URLSession(configuration: configuration, delegate: self, delegateQueue: nil)
self.session = urlSession
defer {
try? fileHandle?.close()
fileHandle = nil
urlSession.invalidateAndCancel()
session = nil
}
try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
self.continuation = continuation
urlSession.dataTask(with: request).resume()
}
if let declared = pairing.fileSize, written != declared {
throw QFTError.integrity("收到 \(written) 字节,电脑声明 \(declared) 字节")
}
if let expected = pairing.sha256 {
let actual = hasher.finalize().map { String(format: "%02x", $0) }.joined()
guard actual == expected else {
try? FileManager.default.removeItem(at: partURL)
throw QFTError.integrity("SHA-256 不匹配,文件已丢弃")
}
}
let finalURL = Self.uniqueURL(in: directory, name: name)
try FileManager.default.moveItem(at: partURL, to: finalURL)
return finalURL
}
// MARK: - 落盘目录
static func defaultDestinationDirectory() throws -> URL {
let documents = try FileManager.default.url(for: .documentDirectory, in: .userDomainMask,
appropriateFor: nil, create: true)
let directory = documents.appendingPathComponent("QFT", isDirectory: true)
try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
return directory
}
static func uniqueURL(in directory: URL, name: String) -> URL {
var candidate = directory.appendingPathComponent(name)
guard FileManager.default.fileExists(atPath: candidate.path) else { return candidate }
let stem = (name as NSString).deletingPathExtension
let ext = (name as NSString).pathExtension
var index = 1
while FileManager.default.fileExists(atPath: candidate.path) {
let suffix = ext.isEmpty ? "\(stem) (\(index))" : "\(stem) (\(index)).\(ext)"
candidate = directory.appendingPathComponent(suffix)
index += 1
}
return candidate
}
}
extension DownloadClient: URLSessionDataDelegate {
func urlSession(_ session: URLSession, dataTask: URLSessionDataTask,
didReceive response: URLResponse,
completionHandler: @escaping (URLSession.ResponseDisposition) -> Void) {
guard let http = response as? HTTPURLResponse else {
finish(with: QFTError.malformedResponse("非 HTTP 响应"))
completionHandler(.cancel)
return
}
guard http.statusCode == 200 || http.statusCode == 206 else {
finish(with: QFTError.httpStatus(http.statusCode, http.statusCode == 403 ? "会话已失效,请让电脑重新生成二维码" : ""))
completionHandler(.cancel)
return
}
if expectedTotal == 0 {
let length = http.expectedContentLength
if length > 0 { expectedTotal = written + UInt64(length) }
}
completionHandler(.allow)
}
func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
do {
try fileHandle?.write(contentsOf: data)
} catch {
finish(with: error)
dataTask.cancel()
return
}
hasher.update(data: data)
written &+= UInt64(data.count)
report()
}
func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
if let error, (error as NSError).code != NSURLErrorCancelled {
finish(with: error)
} else {
report(force: true)
finish(with: nil)
}
}
private func report(force: Bool = false) {
let now = Date()
guard force || now.timeIntervalSince(lastReport) > 0.1 else { return }
lastReport = now
let elapsed = max(0.001, now.timeIntervalSince(startedAt))
onProgress?(TransferProgress(completed: written, total: expectedTotal,
bytesPerSecond: Double(written) / elapsed))
}
private func finish(with error: Error?) {
guard let continuation else { return }
self.continuation = nil
if let error { continuation.resume(throwing: error) } else { continuation.resume() }
}
}
+271
View File
@@ -0,0 +1,271 @@
import Foundation
#if canImport(UIKit)
import UIKit
#endif
enum DeviceInfo {
static var name: String {
#if canImport(UIKit)
let raw = UIDevice.current.name
#else
let raw = Host.current().localizedName ?? "iPhone"
#endif
let cleaned = raw.filter { !$0.isNewline }
return cleaned.isEmpty ? "iPhone" : String(cleaned.prefix(64))
}
}
struct QFTHost: Equatable {
let baseURL: String // 形如 http://192.168.1.20:39393
}
enum QFTError: LocalizedError {
case hostNotFound
case httpStatus(Int, String)
case malformedResponse(String)
case integrity(String)
case cancelled
var errorDescription: String? {
switch self {
case .hostNotFound:
return "找不到电脑。请确认手机和电脑连在同一个 Wi-Fi,并且电脑上的 QFT 正在等待连接。"
case .httpStatus(let code, let detail):
return "电脑返回 HTTP \(code)\(detail.isEmpty ? "" : ":\(detail)")"
case .malformedResponse(let detail):
return "电脑返回的数据无法解析:\(detail)"
case .integrity(let detail):
return "校验失败:\(detail)"
case .cancelled:
return "已取消"
}
}
}
/// 在局域网里定位 Windows 端。
///
/// 顺序:二维码自带的 endpoint → UDP QFTDISC2 广播 → 当前子网有界扫描。
/// 与 Android 端同一套策略,但去掉了 Direct-AP 相关的分支:iOS 连不上指定 AP。
struct HostDiscovery {
let pairing: PairingPayload
let deviceName: String
static let discoveryPort: UInt16 = 39392
func locate() async throws -> QFTHost {
if let host = await probe(pairing.endpoints, timeout: 1.2) {
return host
}
if let hinted = await udpDiscover(timeout: 1.5),
let host = await probe([hinted], timeout: 1.5) {
return host
}
let candidates = LocalNetwork.subnetCandidates(port: pairing.port, limit: 254)
if !candidates.isEmpty, let host = await probe(candidates, timeout: 0.7) {
return host
}
throw QFTError.hostNotFound
}
/// 并发 ping 全部候选,返回第一个应答的。
func probe(_ endpoints: [String], timeout: TimeInterval) async -> QFTHost? {
guard !endpoints.isEmpty else { return nil }
return await withTaskGroup(of: QFTHost?.self) { group in
for endpoint in endpoints {
group.addTask { await Self.ping(endpoint, session: pairing.session,
deviceName: deviceName, timeout: timeout) }
}
for await result in group {
if let result {
group.cancelAll()
return result
}
}
return nil
}
}
static func ping(_ baseURL: String, session: String,
deviceName: String, timeout: TimeInterval) async -> QFTHost? {
guard let url = URL(string: baseURL + "/qft/ping") else { return nil }
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = timeout
request.setValue(session, forHTTPHeaderField: "X-QFT-Token")
request.setValue(Base64URL.encode(deviceName), forHTTPHeaderField: "X-QFT-Device")
let configuration = URLSessionConfiguration.ephemeral
configuration.timeoutIntervalForRequest = timeout
configuration.waitsForConnectivity = false
let urlSession = URLSession(configuration: configuration)
defer { urlSession.finishTasksAndInvalidate() }
guard let (data, response) = try? await urlSession.data(for: request),
let http = response as? HTTPURLResponse, http.statusCode == 200,
let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
(object["ok"] as? Bool) == true else { return nil }
return QFTHost(baseURL: baseURL)
}
/// 向广播地址发 `QFTDISC2:<session>`,等待 `QFTHERE2:<session>:<port>`。
/// 返回可用的 base URL;iOS 首次调用会触发「本地网络」权限弹窗。
func udpDiscover(timeout: TimeInterval) async -> String? {
let expected = "QFTHERE2:\(pairing.session):"
let request = Data("QFTDISC2:\(pairing.session)".utf8)
return await withCheckedContinuation { continuation in
DispatchQueue.global(qos: .userInitiated).async {
let result = Self.udpRoundTrip(request: request,
expectedPrefix: expected,
timeout: timeout)
continuation.resume(returning: result)
}
}
}
private static func udpRoundTrip(request: Data, expectedPrefix: String,
timeout: TimeInterval) -> String? {
let fd = socket(AF_INET, SOCK_DGRAM, 0)
guard fd >= 0 else { return nil }
defer { close(fd) }
var enable: Int32 = 1
setsockopt(fd, SOL_SOCKET, SO_BROADCAST, &enable, socklen_t(MemoryLayout<Int32>.size))
var tv = timeval(tv_sec: Int(timeout), tv_usec: Int32((timeout - floor(timeout)) * 1_000_000))
setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &tv, socklen_t(MemoryLayout<timeval>.size))
var targets = ["255.255.255.255"]
if let broadcast = LocalNetwork.subnetBroadcastAddress() { targets.insert(broadcast, at: 0) }
for target in targets {
var address = sockaddr_in()
address.sin_family = sa_family_t(AF_INET)
address.sin_port = discoveryPort.bigEndian
address.sin_addr.s_addr = inet_addr(target)
let sent = request.withUnsafeBytes { buffer -> Int in
withUnsafePointer(to: &address) { pointer in
pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) { sockPointer in
sendto(fd, buffer.baseAddress, buffer.count, 0,
sockPointer, socklen_t(MemoryLayout<sockaddr_in>.size))
}
}
}
if sent < 0 { continue }
}
let deadline = Date().addingTimeInterval(timeout)
var buffer = [UInt8](repeating: 0, count: 512)
while Date() < deadline {
var from = sockaddr_in()
var fromLength = socklen_t(MemoryLayout<sockaddr_in>.size)
let received = withUnsafeMutablePointer(to: &from) { pointer -> Int in
pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) { sockPointer in
recvfrom(fd, &buffer, buffer.count, 0, sockPointer, &fromLength)
}
}
if received <= 0 { break }
guard let text = String(bytes: buffer[0..<received], encoding: .utf8),
text.hasPrefix(expectedPrefix),
let port = Int(text.dropFirst(expectedPrefix.count)),
(1...65535).contains(port) else { continue }
var raw = from.sin_addr
var host = [CChar](repeating: 0, count: Int(INET_ADDRSTRLEN))
guard inet_ntop(AF_INET, &raw, &host, socklen_t(INET_ADDRSTRLEN)) != nil else { continue }
let ip = String(cString: host)
// 应答来源同样必须是私有地址:广播回包也属于不可信输入
guard PairingProtocol.isPrivateIPv4(ip) else { continue }
return "http://\(ip):\(port)"
}
return nil
}
}
/// 本机 IPv4 与子网推导(getifaddrs)。
enum LocalNetwork {
struct Interface {
let name: String
let address: String
let netmask: String
}
static func activeInterfaces() -> [Interface] {
var head: UnsafeMutablePointer<ifaddrs>?
guard getifaddrs(&head) == 0, let first = head else { return [] }
defer { freeifaddrs(head) }
var result: [Interface] = []
var cursor: UnsafeMutablePointer<ifaddrs>? = first
while let entry = cursor {
defer { cursor = entry.pointee.ifa_next }
guard let rawAddress = entry.pointee.ifa_addr,
rawAddress.pointee.sa_family == UInt8(AF_INET) else { continue }
let flags = Int32(entry.pointee.ifa_flags)
guard flags & IFF_UP != 0, flags & IFF_LOOPBACK == 0 else { continue }
guard let address = describe(rawAddress),
let maskPointer = entry.pointee.ifa_netmask,
let netmask = describe(maskPointer) else { continue }
guard PairingProtocol.isPrivateIPv4(address) else { continue }
result.append(Interface(name: String(cString: entry.pointee.ifa_name),
address: address, netmask: netmask))
}
// en0 是 iPhone 的 Wi-Fi 接口,优先于蜂窝/热点接口
return result.sorted { lhs, _ in lhs.name == "en0" }
}
private static func describe(_ address: UnsafeMutablePointer<sockaddr>) -> String? {
var host = [CChar](repeating: 0, count: Int(NI_MAXHOST))
let length = socklen_t(MemoryLayout<sockaddr_in>.size)
guard getnameinfo(address, length, &host, socklen_t(host.count),
nil, 0, NI_NUMERICHOST) == 0 else { return nil }
return String(cString: host)
}
static func subnetBroadcastAddress() -> String? {
guard let iface = activeInterfaces().first,
let ip = ipv4(iface.address), let mask = ipv4(iface.netmask) else { return nil }
return format(ip | ~mask)
}
/// 当前子网内的候选地址。仅在 /24 或更小的子网上启用,
/// 避免在大网段里做无意义的上千次探测。
static func subnetCandidates(port: Int, limit: Int) -> [String] {
guard let iface = activeInterfaces().first,
let ip = ipv4(iface.address), let mask = ipv4(iface.netmask) else { return [] }
let hostBits = (~mask).nonzeroBitCount
guard hostBits > 0, hostBits <= 8 else { return [] }
let network = ip & mask
let broadcast = ip | ~mask
var result: [String] = []
var candidate = network &+ 1
while candidate < broadcast && result.count < limit {
if candidate != ip { result.append("http://\(format(candidate)):\(port)") }
candidate &+= 1
}
// 网关通常是 .1,多半就是那台开热点/路由的机器,放最前面
if let gatewayIndex = result.firstIndex(of: "http://\(format(network &+ 1)):\(port)") {
result.swapAt(0, gatewayIndex)
}
return result
}
static func ipv4(_ text: String) -> UInt32? {
let parts = text.split(separator: ".", omittingEmptySubsequences: false)
guard parts.count == 4 else { return nil }
var value: UInt32 = 0
for part in parts {
guard let octet = UInt32(part), octet <= 255 else { return nil }
value = (value << 8) | octet
}
return value
}
static func format(_ value: UInt32) -> String {
"\((value >> 24) & 0xff).\((value >> 16) & 0xff).\((value >> 8) & 0xff).\(value & 0xff)"
}
}
+188
View File
@@ -0,0 +1,188 @@
import Foundation
enum TransferDirection: String {
case uploadToPC = "u" // QFTPAIR2:手机把文件传给电脑
case downloadToPhone = "d" // QFTSEND2:电脑已选好文件,手机扫码后下载
}
struct WifiCredentials: Equatable {
let ssid: String
let passphrase: String
}
struct PairingPayload: Equatable {
let version: Int
let session: String
let pcName: String
let port: Int
let endpoints: [String]
let wifi: WifiCredentials?
let direction: TransferDirection
let fileName: String?
let fileSize: UInt64?
let sha256: String?
}
/// QFTPAIR2 / QFTSEND2 配对二维码解析。
///
/// 二维码是**不可信输入**:它决定了 App 接下来去连哪个地址。因此这里只接受
/// 字面量私有 IPv4 + 二维码自称的端口,任何域名、公网地址、带 query/fragment
/// 的 URL 一律拒绝——与 Windows/Android 两端的校验保持一致。
enum PairingProtocol {
static let prefixUpload = "QFTPAIR2:"
static let prefixDownload = "QFTSEND2:"
static func isPairingText(_ text: String) -> Bool {
text.hasPrefix(prefixUpload) || text.hasPrefix(prefixDownload)
}
static func parse(_ text: String) -> PairingPayload? {
guard text.count <= 4096 else { return nil }
if text.hasPrefix(prefixUpload) {
return parseV2(String(text.dropFirst(prefixUpload.count)), expected: .uploadToPC)
}
if text.hasPrefix(prefixDownload) {
return parseV2(String(text.dropFirst(prefixDownload.count)), expected: .downloadToPhone)
}
return nil
}
private static func parseV2(_ encoded: String, expected: TransferDirection) -> PairingPayload? {
guard let data = Base64URL.decode(encoded), data.count <= 2048 else { return nil }
guard let root = try? JSONSerialization.jsonObject(with: data),
let object = root as? [String: Any] else { return nil }
guard (object["v"] as? Int) == 2 else { return nil }
// 缺省为 "u",与 Windows 端「上传 QR 不写 d 字段」的编码方式对应
let rawDirection = (object["d"] as? String) ?? "u"
guard let direction = TransferDirection(rawValue: rawDirection),
direction == expected else { return nil }
guard let session = object["s"] as? String, isValidSession(session) else { return nil }
guard let port = object["p"] as? Int, (1...65535).contains(port) else { return nil }
var wifi: WifiCredentials?
if let array = object["w"] as? [Any], array.count >= 2,
let ssid = array[0] as? String, let passphrase = array[1] as? String {
guard isValidWifi(ssid: ssid, passphrase: passphrase) else { return nil }
wifi = WifiCredentials(ssid: ssid, passphrase: passphrase)
}
var endpoints: [String] = []
if let array = object["e"] as? [Any] {
for item in array {
guard let raw = item as? String else { continue }
var value = raw.trimmingCharacters(in: .whitespaces)
while value.hasSuffix("/") { value.removeLast() }
if isAllowedLocalHTTPEndpoint(value, expectedPort: port), !endpoints.contains(value) {
endpoints.append(value)
}
}
}
// iOS 无法用代码加入指定 Wi-Fi(NEHotspotConfiguration 需要付费账号的
// entitlement),所以 Direct-AP 二维码在本端必须自带可用 endpoint。
if endpoints.isEmpty { return nil }
var fileName: String?
var fileSize: UInt64?
var sha256: String?
if direction == .downloadToPhone {
guard let name = (object["f"] as? String)?.trimmingCharacters(in: .whitespaces),
isValidFileName(name) else { return nil }
guard let size = object["z"] as? NSNumber, size.int64Value >= 0 else { return nil }
guard let hash = (object["h"] as? String)?.lowercased(), isValidSHA256(hash) else { return nil }
fileName = name
fileSize = UInt64(size.int64Value)
sha256 = hash
}
let pcName = String(((object["n"] as? String) ?? "Windows-PC").prefix(80))
return PairingPayload(
version: 2,
session: session,
pcName: pcName,
port: port,
endpoints: endpoints,
wifi: wifi,
direction: direction,
fileName: fileName,
fileSize: fileSize,
sha256: sha256
)
}
// MARK: - 校验
static func isValidSession(_ value: String) -> Bool {
guard (20...64).contains(value.count) else { return false }
for scalar in value.unicodeScalars {
switch scalar {
case "A"..."Z", "a"..."z", "0"..."9", "-", "_": continue
default: return false
}
}
return true
}
static func isValidWifi(ssid: String, passphrase: String) -> Bool {
!ssid.trimmingCharacters(in: .whitespaces).isEmpty
&& Data(ssid.utf8).count <= 32
&& (8...63).contains(passphrase.count)
}
static func isValidFileName(_ value: String) -> Bool {
guard !value.isEmpty, value.count <= 180 else { return false }
let forbidden: Set<Unicode.Scalar> = ["\\", "/", ":", "*", "?", "\"", "<", ">", "|"]
for scalar in value.unicodeScalars {
if scalar.value <= 31 || scalar.value == 127 { return false }
if forbidden.contains(scalar) { return false }
}
return true
}
static func isValidSHA256(_ value: String) -> Bool {
guard value.count == 64 else { return false }
for scalar in value.unicodeScalars {
switch scalar {
case "0"..."9", "a"..."f": continue
default: return false
}
}
return true
}
/// 只允许 `http://<私有 IPv4 字面量>:<期望端口>`。
/// 故意不使用 URL/URLComponents 的宽松解析:它会接受域名、IPv6、
/// 带凭据的 URL 等本协议不该出现的形态。
static func isAllowedLocalHTTPEndpoint(_ value: String, expectedPort: Int) -> Bool {
guard value.hasPrefix("http://") else { return false }
let rest = String(value.dropFirst("http://".count))
guard !rest.contains("@"), !rest.contains("?"), !rest.contains("#"),
!rest.contains("/") else { return false }
let parts = rest.split(separator: ":", omittingEmptySubsequences: false)
guard parts.count == 2, let port = Int(parts[1]), port == expectedPort else { return false }
return isPrivateIPv4(String(parts[0]))
}
static func isPrivateIPv4(_ host: String) -> Bool {
let octets = host.split(separator: ".", omittingEmptySubsequences: false)
guard octets.count == 4 else { return false }
var values: [Int] = []
for octet in octets {
// 拒绝 "01"、"+1"、空段这类非规范写法
guard !octet.isEmpty, octet.count <= 3, octet.allSatisfy({ $0.isASCII && $0.isNumber }),
let value = Int(octet), (0...255).contains(value),
octet.count == 1 || !octet.hasPrefix("0") else { return false }
values.append(value)
}
switch (values[0], values[1]) {
case (10, _): return true
case (127, _): return true
case (169, 254): return true
case (172, 16...31): return true
case (192, 168): return true
default: return false
}
}
}
+469
View File
@@ -0,0 +1,469 @@
import Foundation
import Network
import CryptoKit
/// 点对点链路:Bonjour 发现 + TLS-PSK 加密 + 长度前缀分帧。
///
/// `includePeerToPeer = true` 让 Network.framework 在没有路由器时
/// 自动使用 BLE 发现 + AWDL 点对点 Wi-Fi,也就是 AirDrop 用的同一条链路。
/// 两台设备在同一个 Wi-Fi 下时它会优先走基础网络,速度同样很快。
///
/// AWDL 是苹果私有链路,Windows 无法参与——PC 方向仍走 HTTP 局域网路径。
enum PeerLink {
static let frameHeaderSize = 5 // 1 字节类型 + 4 字节 BE 长度
static let chunkSize = 256 * 1024
static let maxFrameSize = 4 * 1024 * 1024
enum FrameType: UInt8 {
case manifest = 1
case data = 2
case eof = 3
case result = 4
}
enum PeerError: LocalizedError {
case handshake(String)
case protocolViolation(String)
case rejected(String)
case timeout
var errorDescription: String? {
switch self {
case .handshake(let detail): return "建立加密连接失败:\(detail)"
case .protocolViolation(let detail): return "对方发来的数据不符合协议:\(detail)"
case .rejected(let detail): return "对方拒绝了传输:\(detail)"
case .timeout: return "等待对方超时"
}
}
}
/// TLS-PSK 参数。密钥来自二维码,因此不需要任何证书体系,
/// 且扫码这个动作本身就完成了双向认证——中间人拿不到密钥就握不了手。
static func parameters(key: Data, identity: String) -> NWParameters {
let tls = NWProtocolTLS.Options()
let keyData = key.withUnsafeBytes { DispatchData(bytes: $0) }
let identityData = Data(identity.utf8).withUnsafeBytes { DispatchData(bytes: $0) }
sec_protocol_options_add_pre_shared_key(
tls.securityProtocolOptions,
keyData as __DispatchData,
identityData as __DispatchData)
if let suite = tls_ciphersuite_t(rawValue: UInt16(TLS_PSK_WITH_AES_128_GCM_SHA256)) {
sec_protocol_options_append_tls_ciphersuite(tls.securityProtocolOptions, suite)
}
let tcp = NWProtocolTCP.Options()
tcp.noDelay = true
// 传输是一次性的,对端消失时不要长时间挂着
tcp.connectionTimeout = 10
tcp.enableKeepalive = true
tcp.keepaliveIdle = 5
let parameters = NWParameters(tls: tls, tcp: tcp)
parameters.includePeerToPeer = true
return parameters
}
// MARK: - 分帧收发
static func send(_ connection: NWConnection, type: FrameType, payload: Data) async throws {
var header = Data([type.rawValue])
var length = UInt32(payload.count).bigEndian
withUnsafeBytes(of: &length) { header.append(contentsOf: $0) }
try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
connection.send(content: header + payload,
completion: .contentProcessed { error in
if let error { continuation.resume(throwing: error) } else { continuation.resume() }
})
}
}
static func receiveFrame(_ connection: NWConnection) async throws -> (FrameType, Data) {
let header = try await receiveExactly(connection, count: frameHeaderSize)
guard let type = FrameType(rawValue: header[header.startIndex]) else {
throw PeerError.protocolViolation("未知帧类型 \(header[header.startIndex])")
}
let length = header[(header.startIndex + 1)...].withUnsafeBytes {
UInt32(bigEndian: $0.loadUnaligned(as: UInt32.self))
}
guard length <= UInt32(maxFrameSize) else {
throw PeerError.protocolViolation("帧长度 \(length) 超出上限")
}
if length == 0 { return (type, Data()) }
return (type, try await receiveExactly(connection, count: Int(length)))
}
static func receiveExactly(_ connection: NWConnection, count: Int) async throws -> Data {
var buffer = Data()
buffer.reserveCapacity(count)
while buffer.count < count {
let remaining = count - buffer.count
let block = try await withCheckedThrowingContinuation {
(continuation: CheckedContinuation<Data, Error>) in
connection.receive(minimumIncompleteLength: 1, maximumLength: remaining) {
content, _, isComplete, error in
if let error { continuation.resume(throwing: error); return }
if let content, !content.isEmpty { continuation.resume(returning: content); return }
if isComplete {
continuation.resume(throwing: PeerError.protocolViolation("连接提前关闭"))
} else {
continuation.resume(returning: Data())
}
}
}
buffer.append(block)
}
return buffer
}
static func waitReady(_ connection: NWConnection, queue: DispatchQueue,
timeout: TimeInterval = 15) async throws {
try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
let resumed = Locked(false)
func finish(_ error: Error?) {
guard resumed.exchange(true) == false else { return }
if let error { continuation.resume(throwing: error) } else { continuation.resume() }
}
connection.stateUpdateHandler = { state in
switch state {
case .ready:
finish(nil)
case .failed(let error):
finish(error)
case .waiting(let error):
// NWConnection 默认会在 .waiting 里无限重试。对一次性传输来说:
// TLS 类错误(密钥不匹配、对端拒绝)不可能自愈,立刻失败;
// 而链路层的暂时不可达在 AWDL/Bonjour 起来之前是正常现象,继续等。
if case .tls = error {
finish(PeerError.handshake("预共享密钥不匹配,或对方已结束这次会话"))
}
case .cancelled:
finish(PeerError.handshake("连接被取消"))
default:
break
}
}
queue.asyncAfter(deadline: .now() + timeout) { finish(PeerError.timeout) }
connection.start(queue: queue)
}
}
}
/// 极简互斥包装。continuation 只能 resume 一次,而 stateUpdateHandler
/// 可能在多个状态里触发,需要一个原子的「是否已 resume」。
final class Locked<Value> {
private var value: Value
private let lock = NSLock()
init(_ value: Value) { self.value = value }
func exchange(_ newValue: Value) -> Value {
lock.lock(); defer { lock.unlock() }
let old = value
value = newValue
return old
}
var current: Value {
lock.lock(); defer { lock.unlock() }
return value
}
}
// MARK: - 发送端
/// 展示二维码的一方。持有文件,等待对方扫码后连入。
final class PeerSender {
/// 监听器的状态与排队中的连接。stateUpdateHandler / newConnectionHandler
/// 在任意线程触发,而等待方是 async,所以两边都要经过这把锁。
private final class Box {
let lock = NSLock()
var readyPort: UInt16?
var failure: Error?
var pending: [NWConnection] = []
var portWaiter: CheckedContinuation<UInt16, Error>?
var connectionWaiter: CheckedContinuation<NWConnection, Error>?
/// 同步方法:async 上下文里不允许直接调用 NSLock.lock()
func drainPending() -> [NWConnection] {
lock.lock(); defer { lock.unlock() }
let extras = pending
pending = []
return extras
}
}
private let fileURL: URL
private let deviceName: String
private let queue = DispatchQueue(label: "qft.peer.sender")
private let box = Box()
private var listener: NWListener?
private var pairing: PeerPairing?
init(fileURL: URL, deviceName: String) {
self.fileURL = fileURL
self.deviceName = deviceName
}
/// 等待监听就绪并返回实际端口。P2P 场景下对端靠 Bonjour 实例名找过来,
/// 端口只在测试直连时才需要。
func listeningPort() async throws -> UInt16 {
try await withCheckedThrowingContinuation { continuation in
box.lock.lock()
if let port = box.readyPort {
box.lock.unlock(); continuation.resume(returning: port)
} else if let failure = box.failure {
box.lock.unlock(); continuation.resume(throwing: failure)
} else {
box.portWaiter = continuation
box.lock.unlock()
}
}
}
/// 计算文件摘要、启动监听并广播 Bonjour 服务,返回要显示成二维码的配对码。
func start() throws -> PeerPairing {
let attributes = try FileManager.default.attributesOfItem(atPath: fileURL.path)
let size = UInt64(truncating: (attributes[.size] as? NSNumber) ?? 0)
var hasher = SHA256()
let handle = try FileHandle(forReadingFrom: fileURL)
while let block = try handle.read(upToCount: 4 * 1024 * 1024), !block.isEmpty {
hasher.update(data: block)
}
try handle.close()
let digest = hasher.finalize().map { String(format: "%02x", $0) }.joined()
let pairing = PeerPairing(
version: 1,
key: PeerPairing.newKey(),
instance: PeerPairing.newInstance(),
senderName: deviceName,
fileName: fileURL.lastPathComponent,
fileSize: size,
sha256: digest)
let parameters = PeerLink.parameters(key: pairing.key, identity: pairing.instance)
let listener = try NWListener(using: parameters)
listener.service = NWListener.Service(name: pairing.instance,
type: PeerPairing.serviceType)
listener.stateUpdateHandler = { [box] state in
switch state {
case .ready:
box.lock.lock()
box.readyPort = listener.port?.rawValue
let waiter = box.portWaiter
box.portWaiter = nil
box.lock.unlock()
if let port = listener.port?.rawValue { waiter?.resume(returning: port) }
case .failed(let error):
box.lock.lock()
box.failure = error
let portWaiter = box.portWaiter
let connectionWaiter = box.connectionWaiter
box.portWaiter = nil
box.connectionWaiter = nil
box.lock.unlock()
portWaiter?.resume(throwing: error)
connectionWaiter?.resume(throwing: error)
default:
break
}
}
listener.newConnectionHandler = { [box] connection in
box.lock.lock()
if let waiter = box.connectionWaiter {
box.connectionWaiter = nil
box.lock.unlock()
waiter.resume(returning: connection)
} else {
box.pending.append(connection)
box.lock.unlock()
}
}
listener.start(queue: queue)
self.listener = listener
self.pairing = pairing
return pairing
}
/// 等待一个连接并把文件推过去。
func waitAndSend(onProgress: @escaping (TransferProgress) -> Void) async throws {
guard let listener, let pairing else {
throw PeerLink.PeerError.handshake("尚未调用 start()")
}
let connection = try await withCheckedThrowingContinuation {
(continuation: CheckedContinuation<NWConnection, Error>) in
box.lock.lock()
if !box.pending.isEmpty {
let first = box.pending.removeFirst()
box.lock.unlock()
continuation.resume(returning: first)
} else if let failure = box.failure {
box.lock.unlock()
continuation.resume(throwing: failure)
} else {
box.connectionWaiter = continuation
box.lock.unlock()
}
}
// 一次会话只服务一个对端,其余排队的连接直接断开
box.drainPending().forEach { $0.cancel() }
defer { connection.cancel(); listener.cancel() }
try await PeerLink.waitReady(connection, queue: queue)
let manifest: [String: Any] = [
"name": pairing.fileName,
"size": NSNumber(value: pairing.fileSize),
"sha256": pairing.sha256,
"sender": pairing.senderName,
]
try await PeerLink.send(connection, type: .manifest,
payload: try JSONSerialization.data(withJSONObject: manifest))
let handle = try FileHandle(forReadingFrom: fileURL)
defer { try? handle.close() }
var sent: UInt64 = 0
let startedAt = Date()
var lastReport = Date.distantPast
while let block = try handle.read(upToCount: PeerLink.chunkSize), !block.isEmpty {
try Task.checkCancellation()
try await PeerLink.send(connection, type: .data, payload: block)
sent &+= UInt64(block.count)
let now = Date()
if now.timeIntervalSince(lastReport) > 0.1 || sent >= pairing.fileSize {
lastReport = now
onProgress(TransferProgress(
completed: sent, total: pairing.fileSize,
bytesPerSecond: Double(sent) / max(0.001, now.timeIntervalSince(startedAt))))
}
}
try await PeerLink.send(connection, type: .eof, payload: Data())
let (type, payload) = try await PeerLink.receiveFrame(connection)
guard type == .result,
let object = try? JSONSerialization.jsonObject(with: payload) as? [String: Any] else {
throw PeerLink.PeerError.protocolViolation("收尾帧无效")
}
if (object["ok"] as? Bool) != true {
throw PeerLink.PeerError.rejected((object["error"] as? String) ?? "对方未说明原因")
}
}
func stop() {
listener?.cancel()
listener = nil
}
}
// MARK: - 接收端
/// 扫码的一方。按实例名找到对端并接收文件。
struct PeerReceiver {
let pairing: PeerPairing
let destinationDirectory: URL
/// 测试用:跳过 Bonjour,直接连指定端口。
var directPort: UInt16?
func run(onProgress: @escaping (TransferProgress) -> Void) async throws -> URL {
let queue = DispatchQueue(label: "qft.peer.receiver")
let parameters = PeerLink.parameters(key: pairing.key, identity: pairing.instance)
let endpoint: NWEndpoint
if let directPort {
endpoint = .hostPort(host: .ipv4(.loopback), port: .init(rawValue: directPort)!)
} else {
endpoint = .service(name: pairing.instance, type: PeerPairing.serviceType,
domain: "local", interface: nil)
}
let connection = NWConnection(to: endpoint, using: parameters)
defer { connection.cancel() }
try await PeerLink.waitReady(connection, queue: queue)
// --- 清单 ---
let (manifestType, manifestPayload) = try await PeerLink.receiveFrame(connection)
guard manifestType == .manifest,
let manifest = try? JSONSerialization.jsonObject(with: manifestPayload) as? [String: Any],
let declaredSize = (manifest["size"] as? NSNumber)?.uint64Value,
let declaredHash = manifest["sha256"] as? String else {
throw PeerLink.PeerError.protocolViolation("清单帧无效")
}
// 清单必须与二维码一致,否则说明连到的不是扫码时看到的那个文件
guard declaredSize == pairing.fileSize, declaredHash == pairing.sha256 else {
try? await PeerLink.send(connection, type: .result, payload: Data(
#"{"ok":false,"error":"manifest mismatch"}"#.utf8))
throw PeerLink.PeerError.protocolViolation("对方声明的文件与二维码不符")
}
try FileManager.default.createDirectory(at: destinationDirectory,
withIntermediateDirectories: true)
let partURL = destinationDirectory.appendingPathComponent(pairing.fileName + ".qftpart")
try? FileManager.default.removeItem(at: partURL)
FileManager.default.createFile(atPath: partURL.path, contents: nil)
let handle = try FileHandle(forWritingTo: partURL)
var hasher = SHA256()
var received: UInt64 = 0
let startedAt = Date()
var lastReport = Date.distantPast
// --- 数据 ---
do {
loop: while true {
try Task.checkCancellation()
let (type, payload) = try await PeerLink.receiveFrame(connection)
switch type {
case .data:
guard received &+ UInt64(payload.count) <= pairing.fileSize else {
throw PeerLink.PeerError.protocolViolation("收到的数据超出声明大小")
}
try handle.write(contentsOf: payload)
hasher.update(data: payload)
received &+= UInt64(payload.count)
let now = Date()
if now.timeIntervalSince(lastReport) > 0.1 || received >= pairing.fileSize {
lastReport = now
onProgress(TransferProgress(
completed: received, total: pairing.fileSize,
bytesPerSecond: Double(received) / max(0.001, now.timeIntervalSince(startedAt))))
}
case .eof:
break loop
default:
throw PeerLink.PeerError.protocolViolation("数据阶段收到 \(type)")
}
}
try handle.close()
} catch {
try? handle.close()
try? FileManager.default.removeItem(at: partURL)
throw error
}
// --- 校验 ---
let actual = hasher.finalize().map { String(format: "%02x", $0) }.joined()
guard received == pairing.fileSize, actual == pairing.sha256 else {
try? FileManager.default.removeItem(at: partURL)
try? await PeerLink.send(connection, type: .result, payload: Data(
#"{"ok":false,"error":"integrity"}"#.utf8))
throw QFTError.integrity("收到 \(received)/\(pairing.fileSize) 字节,SHA-256 \(actual == pairing.sha256 ? "一致" : "不一致")")
}
let finalURL = DownloadClient.uniqueURL(in: destinationDirectory, name: pairing.fileName)
try FileManager.default.moveItem(at: partURL, to: finalURL)
try await PeerLink.send(connection, type: .result, payload: Data(#"{"ok":true}"#.utf8))
return finalURL
}
}
+94
View File
@@ -0,0 +1,94 @@
import Foundation
import Security
/// 隔空投送式点对点配对码。
///
/// 与 QFTPAIR2/QFTSEND2 的关键区别:那两个是「连到某个 IP」,
/// 这个是「连到某个 Bonjour 服务实例,并用二维码里的预共享密钥做 TLS 认证」。
/// 二维码在这里充当带外信道——和 AirDrop 用 BLE 交换身份是同一个作用,
/// 只是我们把身份交换搬到了用户可见的扫码动作上,不需要任何配对弹窗。
struct PeerPairing: Equatable {
static let prefix = "QFTP2P1:"
let version: Int
/// 32 字节预共享密钥。既是 TLS-PSK,也是服务实例的唯一凭据。
let key: Data
/// Bonjour 服务实例名,由发送端随机生成
let instance: String
let senderName: String
let fileName: String
let fileSize: UInt64
let sha256: String
static let serviceType = "_qft-p2p._tcp"
func encode() -> String {
let object: [String: Any] = [
"v": version,
"k": Base64URL.encode(key),
"i": instance,
"n": senderName,
"f": fileName,
"z": NSNumber(value: fileSize),
"h": sha256,
]
let data = (try? JSONSerialization.data(withJSONObject: object)) ?? Data()
return Self.prefix + Base64URL.encode(data)
}
static func isPeerText(_ text: String) -> Bool { text.hasPrefix(prefix) }
static func parse(_ text: String) -> PeerPairing? {
guard text.hasPrefix(prefix), text.count <= 4096 else { return nil }
guard let data = Base64URL.decode(String(text.dropFirst(prefix.count))),
data.count <= 2048,
let object = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {
return nil
}
guard (object["v"] as? Int) == 1 else { return nil }
guard let keyText = object["k"] as? String,
let key = Base64URL.decode(keyText), key.count == 32 else { return nil }
guard let instance = object["i"] as? String, isValidInstance(instance) else { return nil }
guard let fileName = (object["f"] as? String)?.trimmingCharacters(in: .whitespaces),
PairingProtocol.isValidFileName(fileName) else { return nil }
guard let size = object["z"] as? NSNumber, size.int64Value >= 0 else { return nil }
guard let hash = (object["h"] as? String)?.lowercased(),
PairingProtocol.isValidSHA256(hash) else { return nil }
return PeerPairing(
version: 1,
key: key,
instance: instance,
senderName: String(((object["n"] as? String) ?? "iPhone").prefix(80)),
fileName: fileName,
fileSize: UInt64(size.int64Value),
sha256: hash
)
}
/// Bonjour 实例名:只允许我们自己生成的字符集,避免把任意字符串
/// 交给 mDNS 解析。
static func isValidInstance(_ value: String) -> Bool {
guard (8...48).contains(value.count) else { return false }
for scalar in value.unicodeScalars {
switch scalar {
case "A"..."Z", "a"..."z", "0"..."9", "-": continue
default: return false
}
}
return true
}
static func newKey() -> Data {
var bytes = [UInt8](repeating: 0, count: 32)
_ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
return Data(bytes)
}
static func newInstance() -> String {
let alphabet = Array("abcdefghijklmnopqrstuvwxyz0123456789")
var bytes = [UInt8](repeating: 0, count: 16)
_ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
return "qft-" + String(bytes.map { alphabet[Int($0) % alphabet.count] })
}
}
+189
View File
@@ -0,0 +1,189 @@
import Foundation
/// 手机 → 电脑并行上传(QFTPAIR2)。
///
/// 与 Android 端同一套 v2 流程:init → 并行 chunk → finish。
/// Windows 端 `receiver.rs` 会预分配 `.qftpart`、按 offset 定位写入、
/// 校验 SHA-256 后 rename,因此 chunk 之间没有顺序要求,重复 chunk 也是幂等的。
///
/// 与 Android 的唯一差异是**块大小固定 4 MiB**:Android 会按文件大小选 4/8/16 MiB,
/// 但 iOS 上 `workers × chunkSize` 就是内存峰值,16 MiB × 6 会在旧机型上触发
/// jetsam。4 MiB × 6 = 24 MiB 峰值,在局域网速度下每块的往返开销可以忽略。
struct UploadClient {
let host: QFTHost
let pairing: PairingPayload
let deviceName: String
static let chunkSize: UInt64 = 4 * 1024 * 1024
static let maxWorkers = 6
struct Session {
let uploadID: String
let chunkSize: UInt64
let totalChunks: Int
}
func run(fileURL: URL, onProgress: @escaping (TransferProgress) -> Void) async throws -> String {
let attributes = try FileManager.default.attributesOfItem(atPath: fileURL.path)
let size = UInt64(truncating: (attributes[.size] as? NSNumber) ?? 0)
let name = fileURL.lastPathComponent
let session = try await initUpload(name: name, size: size)
if session.totalChunks == 0 {
return try await finishUpload(session)
}
let counter = ByteCounter(total: size, onProgress: onProgress)
let queue = IndexQueue(count: session.totalChunks)
try await withThrowingTaskGroup(of: Void.self) { group in
let workers = min(session.totalChunks, Self.maxWorkers)
for _ in 0..<workers {
group.addTask {
let handle = try FileHandle(forReadingFrom: fileURL)
defer { try? handle.close() }
while let index = await queue.next() {
try Task.checkCancellation()
let offset = UInt64(index) * session.chunkSize
let length = min(session.chunkSize, size - offset)
try handle.seek(toOffset: offset)
let body = try handle.read(upToCount: Int(length)) ?? Data()
guard UInt64(body.count) == length else {
throw QFTError.integrity("读取本地文件第 \(index) 块失败")
}
try await uploadChunk(session, index: index, body: body)
await counter.add(length)
}
}
}
try await group.waitForAll()
}
return try await finishUpload(session)
}
// MARK: - 三个端点
private func initUpload(name: String, size: UInt64) async throws -> Session {
var request = try makeRequest(path: "/qft/upload/init")
request.setValue(Base64URL.encode(name), forHTTPHeaderField: "X-QFT-Filename")
request.setValue(String(size), forHTTPHeaderField: "X-QFT-Size")
request.setValue(String(Self.chunkSize), forHTTPHeaderField: "X-QFT-Chunk-Size")
request.setValue("0", forHTTPHeaderField: "Content-Length")
let object = try await sendJSON(request, body: Data())
guard let uploadID = object["upload_id"] as? String, !uploadID.isEmpty,
let chunkSize = (object["chunk_size"] as? NSNumber)?.uint64Value, chunkSize > 0,
let totalChunks = (object["total_chunks"] as? NSNumber)?.intValue, totalChunks >= 0 else {
throw QFTError.malformedResponse("init 响应缺少字段")
}
return Session(uploadID: uploadID, chunkSize: chunkSize, totalChunks: totalChunks)
}
private func uploadChunk(_ session: Session, index: Int, body: Data) async throws {
var request = try makeRequest(path: "/qft/upload/chunk/\(session.uploadID)/\(index)")
request.setValue(String(body.count), forHTTPHeaderField: "Content-Length")
// 重复的 chunk 在接收端是幂等的,因此重试是安全的。
// Wi-Fi 漫游或 Windows 防火墙首次放行都可能吃掉第一次请求。
var lastError: Error = QFTError.malformedResponse("未知错误")
for attempt in 0..<3 {
do {
_ = try await sendJSON(request, body: body)
return
} catch {
lastError = error
if case QFTError.httpStatus(let code, _) = error, code == 403 || code == 404 { throw error }
try? await Task.sleep(nanoseconds: UInt64(120_000_000 << attempt))
}
}
throw lastError
}
private func finishUpload(_ session: Session) async throws -> String {
var request = try makeRequest(path: "/qft/upload/finish/\(session.uploadID)")
request.setValue("0", forHTTPHeaderField: "Content-Length")
let object = try await sendJSON(request, body: Data())
guard let sha = object["sha256"] as? String else {
throw QFTError.malformedResponse("finish 响应缺少 sha256")
}
return sha
}
// MARK: - HTTP
private func makeRequest(path: String) throws -> URLRequest {
guard let url = URL(string: host.baseURL + path) else {
throw QFTError.malformedResponse("上传地址无效:\(path)")
}
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.timeoutInterval = 60
request.setValue(pairing.session, forHTTPHeaderField: "X-QFT-Token")
request.setValue(Base64URL.encode(deviceName), forHTTPHeaderField: "X-QFT-Device")
request.setValue("application/octet-stream", forHTTPHeaderField: "Content-Type")
return request
}
private func sendJSON(_ request: URLRequest, body: Data) async throws -> [String: Any] {
let configuration = URLSessionConfiguration.ephemeral
configuration.timeoutIntervalForRequest = request.timeoutInterval
let urlSession = URLSession(configuration: configuration)
defer { urlSession.finishTasksAndInvalidate() }
let (data, response) = try await urlSession.upload(for: request, from: body)
guard let http = response as? HTTPURLResponse else {
throw QFTError.malformedResponse("非 HTTP 响应")
}
guard http.statusCode == 200 else {
let detail = String(data: data.prefix(200), encoding: .utf8) ?? ""
throw QFTError.httpStatus(http.statusCode, detail)
}
guard let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
throw QFTError.malformedResponse("响应不是 JSON")
}
if let ok = object["ok"] as? Bool, ok == false {
throw QFTError.malformedResponse("电脑拒绝了请求:\(object)")
}
return object
}
}
/// 分发块序号。
actor IndexQueue {
private var current = 0
private let count: Int
init(count: Int) { self.count = count }
func next() -> Int? {
guard current < count else { return nil }
defer { current += 1 }
return current
}
}
/// 汇总各 worker 的已传字节并限频回调。
actor ByteCounter {
private var completed: UInt64 = 0
private let total: UInt64
private let startedAt = Date()
private var lastReport = Date.distantPast
private let onProgress: (TransferProgress) -> Void
init(total: UInt64, onProgress: @escaping (TransferProgress) -> Void) {
self.total = total
self.onProgress = onProgress
}
func add(_ bytes: UInt64) {
completed &+= bytes
let now = Date()
guard now.timeIntervalSince(lastReport) > 0.1 || completed >= total else { return }
lastReport = now
let elapsed = max(0.001, now.timeIntervalSince(startedAt))
onProgress(TransferProgress(completed: completed, total: total,
bytesPerSecond: Double(completed) / elapsed))
}
}
+68
View File
@@ -0,0 +1,68 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleDevelopmentRegion</key>
<string>zh_CN</string>
<key>CFBundleDisplayName</key>
<string>QFT 快传</string>
<key>CFBundleExecutable</key>
<string>$(EXECUTABLE_NAME)</string>
<key>CFBundleIdentifier</key>
<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundleName</key>
<string>$(PRODUCT_NAME)</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
<string>$(MARKETING_VERSION)</string>
<key>CFBundleVersion</key>
<string>$(CURRENT_PROJECT_VERSION)</string>
<!-- 扫描配对二维码 -->
<key>NSCameraUsageDescription</key>
<string>QFT 需要使用相机扫描电脑或另一台 iPhone 上的配对二维码。相机画面不会离开本机。</string>
<!-- iOS 14+ 访问局域网设备必须声明;首次连接时系统会弹窗询问 -->
<key>NSLocalNetworkUsageDescription</key>
<string>QFT 需要在本地网络里找到你的电脑,才能直接传输文件。所有数据只在本地网络内传输,不经过互联网。</string>
<!-- 隔空投送式点对点传输所用的 Bonjour 服务,未声明则 NWBrowser 无法发现对端 -->
<key>NSBonjourServices</key>
<array>
<string>_qft-p2p._tcp</string>
</array>
<!-- Windows 端是局域网内的明文 HTTP。仅放开本地网络,不全局关闭 ATS。 -->
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsLocalNetworking</key>
<true/>
</dict>
<!-- 让接收到的文件出现在「文件」App 里,用户可以自行导出 -->
<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
<key>UILaunchScreen</key>
<dict>
<key>UIColorName</key>
<string></string>
</dict>
<key>UISupportedInterfaceOrientations</key>
<array>
<string>UIInterfaceOrientationPortrait</string>
</array>
<key>UISupportedInterfaceOrientations~ipad</key>
<array>
<string>UIInterfaceOrientationPortrait</string>
<string>UIInterfaceOrientationPortraitUpsideDown</string>
<string>UIInterfaceOrientationLandscapeLeft</string>
<string>UIInterfaceOrientationLandscapeRight</string>
</array>
</dict>
</plist>
+118
View File
@@ -0,0 +1,118 @@
# QFT iOS 客户端 v0.4.7
三种传输方式:
| 方向 | 链路 | 说明 |
|---|---|---|
| 电脑 → iPhone | 局域网 HTTP | 扫 Windows 端的 `QFTSEND2` 码,自动下载,支持断点续传 |
| iPhone → 电脑 | 局域网 HTTP | 扫 `QFTPAIR2` 码,选文件后并行分块上传 |
| **iPhone ↔ iPhone** | **点对点直连** | 发送方显示二维码,接收方扫码,**不需要连同一个 Wi-Fi** |
## 打开工程
```bash
open ios/QFT.xcodeproj
```
工程已提交到仓库,不需要 XcodeGen 之类的额外工具。首次构建前在
Target → Signing & Capabilities 里选一下你自己的开发者账号(免费账号即可,
生成的描述文件 7 天有效)。
增删源文件后重新生成工程:
```bash
python3 ios/tools/generate_xcodeproj.py
```
- 最低系统:iOS 17.0
- Bundle ID:`com.qft.transfer`(按需改 `generate_xcodeproj.py` 里的常量)
## 隔空投送式点对点传输
`PeerLink` 用 `Network.framework` 并打开 `includePeerToPeer`。底层就是
AirDrop 用的那条链路——BLE 发现 + AWDL 点对点 Wi-Fi,两台设备不需要路由器,
也不需要连同一个 Wi-Fi。两端在同一个 Wi-Fi 下时它会自动优先走基础网络。
握手用 **TLS-PSK**:预共享密钥(32 字节)由发送端随机生成并写进二维码,
扫码这个动作本身就完成了带外密钥交换与双向认证。没扫到码的第三方
连上来也过不了 TLS 握手,因此不需要任何证书体系,也不需要配对弹窗。
```
发送方 接收方
选文件 → 算 SHA-256
启动 NWListener(Bonjour: _qft-p2p._tcp)
生成 32 字节 PSK
显示 QFTP2P1 二维码 ──────扫码────→ 解析出 PSK + 服务实例名
NWBrowser 找到实例
←──────── TLS-PSK 握手 ────────→
MANIFEST(JSON) ─────────────────────→ 校验与二维码是否一致
DATA × N ─────────────────────→ 落盘 + 增量 SHA-256
EOF ─────────────────────→
←──────── RESULT(JSON) ──────── 校验通过才 rename
```
**AWDL 是苹果私有链路,Windows 无法参与**,所以与电脑互传仍走局域网 HTTP。
如果现场没有路由器,可行的替代是让 iPhone 开个人热点、电脑连上来。
## 已知的 iOS 平台限制
1. **无法用代码连接指定 Wi-Fi。** Android 端用 `WifiNetworkSpecifier` 自动加入
Windows 的 QFT Direct AP,iOS 对应的 `NEHotspotConfiguration` 需要
HotspotConfiguration entitlement,免费开发者账号拿不到。因此 iOS 端
**不实现 Direct AP 流程**,`PairingProtocol` 在二维码不带可用 endpoint 时
会直接拒绝,而不是给用户一个连不上的假成功。
2. **首次访问局域网会弹权限窗。** 已在 `Info.plist` 声明
`NSLocalNetworkUsageDescription` 与 `NSBonjourServices`。
若用户误点了拒绝,需要去 设置 → 隐私与安全性 → 本地网络 里重新打开。
3. **没有「下载」文件夹。** 收到的文件存在 App 的 Documents/QFT 下,
通过 `UIFileSharingEnabled` + `LSSupportsOpeningDocumentsInPlace`
暴露到「文件」App,也可以在 App 内直接分享出去。
4. **上传块固定 4 MiB。** Android 端按文件大小选 4/8/16 MiB,但 iOS 上
`worker 数 × 块大小` 就是内存峰值,16 MiB × 6 会在旧机型触发 jetsam。
4 MiB × 6 = 24 MiB 峰值,局域网速度下每块的往返开销可以忽略。
## 测试
核心层(协议、发现、上传、下载、P2P 链路)不依赖 UIKit,
可以直接以 macOS 为目标编译运行,**不需要 Xcode,也不需要模拟器**:
```bash
./ios/CoreTests/run.sh
```
也已接入主自检套件(`python scripts/run_all_selftests.py`)。
测试内容:
- `Base64URL` 与三端一致性(含 200 组随机字节往返)
- `QFTPAIR2` / `QFTSEND2` / `QFTP2P1` 解析,含各类畸形输入
- **端点白名单**:二维码是不可信输入,只接受字面量私有 IPv4 + 声明端口。
已覆盖域名、公网地址、`172.32` 边界、非规范八位组、IPv6、带凭据/路径/query 等 11 种拒绝用例
- **与 `MockPCServer.py` 的完整传输**:该 mock 严格复刻 `receiver.rs` / `sender.rs`
的线上语义(路径、header 名、JSON 字段、Range 行为、chunk 长度校验),
因此这组测试就是 Swift 端与 Rust 端的**线格式契约测试**——任何一边改了协议都会红
- **真实 TLS-PSK 握手**下的 P2P 端到端传输,含错误密钥必须被拒
## 目录
```
ios/
QFT.xcodeproj/ 生成的工程(已提交)
QFT/
Info.plist 权限声明、Bonjour 服务、ATS 本地网络例外
App/ SwiftUI 界面 + 相机扫码(需要 Xcode 才能构建)
Core/ 纯 Foundation,可在 macOS 上编译测试
Base64URL.swift
PairingProtocol.swift QFTPAIR2 / QFTSEND2 + 端点白名单
HostDiscovery.swift endpoint 探测 → UDP 广播 → 子网扫描
DownloadClient.swift 流式落盘 + 增量 SHA-256 + Range 续传
UploadClient.swift init/chunk/finish 并行上传
PeerPairing.swift QFTP2P1 配对码
PeerLink.swift TLS-PSK + 分帧的点对点链路
CoreTests/
run.sh 编译并运行(swiftc,无需 Xcode)
main.swift 测试用例
MockPCServer.py 复刻 Windows 端线上语义的假电脑
tools/
generate_xcodeproj.py 工程生成器
```
+371
View File
@@ -0,0 +1,371 @@
#!/usr/bin/env python3
"""生成 ios/QFT.xcodeproj,不依赖 XcodeGen 等外部工具。
生成结果已提交到仓库,正常情况下双击 QFT.xcodeproj 即可。
只有在**增删源文件**之后才需要重跑:
python3 ios/tools/generate_xcodeproj.py
对象 ID 由文件路径哈希得到,因此同样的文件集合总是产出同样的工程,
diff 干净,不会每次生成都全量变动。
"""
import hashlib
import os
HERE = os.path.dirname(os.path.abspath(__file__))
IOS_ROOT = os.path.dirname(HERE)
APP_NAME = "QFT"
BUNDLE_ID = "com.qft.transfer"
DEPLOYMENT_TARGET = "17.0"
MARKETING_VERSION = "0.4.7"
SOURCES = [
"QFT/App/QFTApp.swift",
"QFT/App/HomeView.swift",
"QFT/App/ScannerView.swift",
"QFT/App/TransferModel.swift",
"QFT/Core/Base64URL.swift",
"QFT/Core/PairingProtocol.swift",
"QFT/Core/HostDiscovery.swift",
"QFT/Core/DownloadClient.swift",
"QFT/Core/UploadClient.swift",
"QFT/Core/PeerPairing.swift",
"QFT/Core/PeerLink.swift",
]
RESOURCES = ["QFT/Assets.xcassets"]
OTHER_FILES = ["QFT/Info.plist"]
def oid(*parts):
"""由稳定字符串派生 24 位十六进制对象 ID。"""
digest = hashlib.sha1("::".join(parts).encode("utf-8")).hexdigest()
return digest[:24].upper()
def file_type(path):
if path.endswith(".swift"):
return "sourcecode.swift"
if path.endswith(".xcassets"):
return "folder.assetcatalog"
if path.endswith(".plist"):
return "text.plist.xml"
return "text"
def build_tree(paths):
"""把扁平路径列表折成 {目录: {...}} 的嵌套结构。"""
tree = {}
for path in paths:
node = tree
segments = path.split("/")
for segment in segments[:-1]:
node = node.setdefault(segment, {})
node[segments[-1]] = None
return tree
def emit_groups(tree, prefix, lines):
"""深度优先输出 PBXGroup,返回本层 group 的 ID。"""
children = []
for name in sorted(tree.keys()):
path = "%s/%s" % (prefix, name) if prefix else name
if tree[name] is None:
children.append((oid("file", path), name))
else:
children.append((emit_groups(tree[name], path, lines), name))
group_id = oid("group", prefix or "<root>")
lines.append("\t\t%s /* %s */ = {" % (group_id, prefix.split("/")[-1] if prefix else APP_NAME))
lines.append("\t\t\tisa = PBXGroup;")
lines.append("\t\t\tchildren = (")
for child_id, child_name in children:
lines.append("\t\t\t\t%s /* %s */," % (child_id, child_name))
lines.append("\t\t\t);")
if prefix:
lines.append("\t\t\tpath = %s;" % prefix.split("/")[-1])
lines.append("\t\t\tsourceTree = \"<group>\";")
lines.append("\t\t};")
return group_id
def generate():
all_files = SOURCES + RESOURCES + OTHER_FILES
project_id = oid("project")
target_id = oid("target", APP_NAME)
product_id = oid("product", APP_NAME)
products_group_id = oid("group", "<products>")
sources_phase_id = oid("phase", "sources")
resources_phase_id = oid("phase", "resources")
frameworks_phase_id = oid("phase", "frameworks")
project_config_list = oid("configlist", "project")
target_config_list = oid("configlist", "target")
lines = []
add = lines.append
add("// !$*UTF8*$!")
add("{")
add("\tarchiveVersion = 1;")
add("\tclasses = {")
add("\t};")
add("\tobjectVersion = 56;")
add("\tobjects = {")
# ---------------- PBXBuildFile
add("")
add("/* Begin PBXBuildFile section */")
for path in SOURCES + RESOURCES:
name = path.split("/")[-1]
add("\t\t%s /* %s in %s */ = {isa = PBXBuildFile; fileRef = %s /* %s */; };"
% (oid("buildfile", path), name,
"Resources" if path in RESOURCES else "Sources",
oid("file", path), name))
add("/* End PBXBuildFile section */")
# ---------------- PBXFileReference
add("")
add("/* Begin PBXFileReference section */")
add("\t\t%s /* %s.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; "
"includeInIndex = 0; path = %s.app; sourceTree = BUILT_PRODUCTS_DIR; };"
% (product_id, APP_NAME, APP_NAME))
for path in all_files:
name = path.split("/")[-1]
add("\t\t%s /* %s */ = {isa = PBXFileReference; lastKnownFileType = %s; path = %s; "
"sourceTree = \"<group>\"; };" % (oid("file", path), name, file_type(path), name))
add("/* End PBXFileReference section */")
# ---------------- PBXFrameworksBuildPhase
add("")
add("/* Begin PBXFrameworksBuildPhase section */")
add("\t\t%s /* Frameworks */ = {" % frameworks_phase_id)
add("\t\t\tisa = PBXFrameworksBuildPhase;")
add("\t\t\tbuildActionMask = 2147483647;")
add("\t\t\tfiles = (")
add("\t\t\t);")
add("\t\t\trunOnlyForDeploymentPostprocessing = 0;")
add("\t\t};")
add("/* End PBXFrameworksBuildPhase section */")
# ---------------- PBXGroup
add("")
add("/* Begin PBXGroup section */")
group_lines = []
app_group_id = emit_groups(build_tree(all_files)[APP_NAME], APP_NAME, group_lines)
lines.extend(group_lines)
root_group_id = oid("group", "<root-main>")
add("\t\t%s = {" % root_group_id)
add("\t\t\tisa = PBXGroup;")
add("\t\t\tchildren = (")
add("\t\t\t\t%s /* %s */," % (app_group_id, APP_NAME))
add("\t\t\t\t%s /* Products */," % products_group_id)
add("\t\t\t);")
add("\t\t\tsourceTree = \"<group>\";")
add("\t\t};")
add("\t\t%s /* Products */ = {" % products_group_id)
add("\t\t\tisa = PBXGroup;")
add("\t\t\tchildren = (")
add("\t\t\t\t%s /* %s.app */," % (product_id, APP_NAME))
add("\t\t\t);")
add("\t\t\tname = Products;")
add("\t\t\tsourceTree = \"<group>\";")
add("\t\t};")
add("/* End PBXGroup section */")
# ---------------- PBXNativeTarget
add("")
add("/* Begin PBXNativeTarget section */")
add("\t\t%s /* %s */ = {" % (target_id, APP_NAME))
add("\t\t\tisa = PBXNativeTarget;")
add("\t\t\tbuildConfigurationList = %s;" % target_config_list)
add("\t\t\tbuildPhases = (")
add("\t\t\t\t%s /* Sources */," % sources_phase_id)
add("\t\t\t\t%s /* Frameworks */," % frameworks_phase_id)
add("\t\t\t\t%s /* Resources */," % resources_phase_id)
add("\t\t\t);")
add("\t\t\tbuildRules = (")
add("\t\t\t);")
add("\t\t\tdependencies = (")
add("\t\t\t);")
add("\t\t\tname = %s;" % APP_NAME)
add("\t\t\tproductName = %s;" % APP_NAME)
add("\t\t\tproductReference = %s /* %s.app */;" % (product_id, APP_NAME))
add("\t\t\tproductType = \"com.apple.product-type.application\";")
add("\t\t};")
add("/* End PBXNativeTarget section */")
# ---------------- PBXProject
add("")
add("/* Begin PBXProject section */")
add("\t\t%s /* Project object */ = {" % project_id)
add("\t\t\tisa = PBXProject;")
add("\t\t\tattributes = {")
add("\t\t\t\tBuildIndependentTargetsInParallel = 1;")
add("\t\t\t\tLastSwiftUpdateCheck = 1600;")
add("\t\t\t\tLastUpgradeCheck = 1600;")
add("\t\t\t\tTargetAttributes = {")
add("\t\t\t\t\t%s = {" % target_id)
add("\t\t\t\t\t\tCreatedOnToolsVersion = 16.0;")
add("\t\t\t\t\t};")
add("\t\t\t\t};")
add("\t\t\t};")
add("\t\t\tbuildConfigurationList = %s;" % project_config_list)
add("\t\t\tcompatibilityVersion = \"Xcode 14.0\";")
add("\t\t\tdevelopmentRegion = en;")
add("\t\t\thasScannedForEncodings = 0;")
add("\t\t\tknownRegions = (")
add("\t\t\t\ten,")
add("\t\t\t\tBase,")
add("\t\t\t\t\"zh-Hans\",")
add("\t\t\t);")
add("\t\t\tmainGroup = %s;" % root_group_id)
add("\t\t\tproductRefGroup = %s /* Products */;" % products_group_id)
add("\t\t\tprojectDirPath = \"\";")
add("\t\t\tprojectRoot = \"\";")
add("\t\t\ttargets = (")
add("\t\t\t\t%s /* %s */," % (target_id, APP_NAME))
add("\t\t\t);")
add("\t\t};")
add("/* End PBXProject section */")
# ---------------- PBXResourcesBuildPhase
add("")
add("/* Begin PBXResourcesBuildPhase section */")
add("\t\t%s /* Resources */ = {" % resources_phase_id)
add("\t\t\tisa = PBXResourcesBuildPhase;")
add("\t\t\tbuildActionMask = 2147483647;")
add("\t\t\tfiles = (")
for path in RESOURCES:
add("\t\t\t\t%s /* %s in Resources */," % (oid("buildfile", path), path.split("/")[-1]))
add("\t\t\t);")
add("\t\t\trunOnlyForDeploymentPostprocessing = 0;")
add("\t\t};")
add("/* End PBXResourcesBuildPhase section */")
# ---------------- PBXSourcesBuildPhase
add("")
add("/* Begin PBXSourcesBuildPhase section */")
add("\t\t%s /* Sources */ = {" % sources_phase_id)
add("\t\t\tisa = PBXSourcesBuildPhase;")
add("\t\t\tbuildActionMask = 2147483647;")
add("\t\t\tfiles = (")
for path in SOURCES:
add("\t\t\t\t%s /* %s in Sources */," % (oid("buildfile", path), path.split("/")[-1]))
add("\t\t\t);")
add("\t\t\trunOnlyForDeploymentPostprocessing = 0;")
add("\t\t};")
add("/* End PBXSourcesBuildPhase section */")
# ---------------- XCBuildConfiguration
shared_project = [
"ALWAYS_SEARCH_USER_PATHS = NO",
"CLANG_ANALYZER_NONNULL = YES",
"CLANG_ENABLE_MODULES = YES",
"CLANG_ENABLE_OBJC_ARC = YES",
"CLANG_WARN_DOCUMENTATION_COMMENTS = YES",
"CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE",
"COPY_PHASE_STRIP = NO",
"ENABLE_STRICT_OBJC_MSGSEND = YES",
"GCC_NO_COMMON_BLOCKS = YES",
"IPHONEOS_DEPLOYMENT_TARGET = %s" % DEPLOYMENT_TARGET,
"MTL_FAST_MATH = YES",
"SDKROOT = iphoneos",
"SWIFT_VERSION = 5.0",
]
shared_target = [
"ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon",
"ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor",
"CODE_SIGN_STYLE = Automatic",
"CURRENT_PROJECT_VERSION = 47",
"ENABLE_PREVIEWS = YES",
"GENERATE_INFOPLIST_FILE = NO",
"INFOPLIST_FILE = QFT/Info.plist",
"LD_RUNPATH_SEARCH_PATHS = \"$(inherited) @executable_path/Frameworks\"",
"MARKETING_VERSION = %s" % MARKETING_VERSION,
"PRODUCT_BUNDLE_IDENTIFIER = %s" % BUNDLE_ID,
"PRODUCT_NAME = \"$(TARGET_NAME)\"",
"SWIFT_EMIT_LOC_STRINGS = NO",
"TARGETED_DEVICE_FAMILY = \"1,2\"",
]
variants = {
"Debug": {
"project": ["DEBUG_INFORMATION_FORMAT = dwarf",
"ENABLE_TESTABILITY = YES",
"GCC_OPTIMIZATION_LEVEL = 0",
"GCC_PREPROCESSOR_DEFINITIONS = \"DEBUG=1 $(inherited)\"",
"MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE",
"ONLY_ACTIVE_ARCH = YES",
"SWIFT_ACTIVE_COMPILATION_CONDITIONS = \"DEBUG $(inherited)\"",
"SWIFT_OPTIMIZATION_LEVEL = \"-Onone\""],
"target": [],
},
"Release": {
"project": ["DEBUG_INFORMATION_FORMAT = \"dwarf-with-dsym\"",
"ENABLE_NS_ASSERTIONS = NO",
"MTL_ENABLE_DEBUG_INFO = NO",
"SWIFT_COMPILATION_MODE = wholemodule",
"VALIDATE_PRODUCT = YES"],
"target": [],
},
}
add("")
add("/* Begin XCBuildConfiguration section */")
for name, extra in variants.items():
for scope, base in (("project", shared_project), ("target", shared_target)):
config_id = oid("config", scope, name)
add("\t\t%s /* %s */ = {" % (config_id, name))
add("\t\t\tisa = XCBuildConfiguration;")
add("\t\t\tbuildSettings = {")
for setting in sorted(base + extra[scope]):
add("\t\t\t\t%s;" % setting)
add("\t\t\t};")
add("\t\t\tname = %s;" % name)
add("\t\t};")
add("/* End XCBuildConfiguration section */")
# ---------------- XCConfigurationList
add("")
add("/* Begin XCConfigurationList section */")
for scope, list_id in (("project", project_config_list), ("target", target_config_list)):
add("\t\t%s = {" % list_id)
add("\t\t\tisa = XCConfigurationList;")
add("\t\t\tbuildConfigurations = (")
for name in variants:
add("\t\t\t\t%s /* %s */," % (oid("config", scope, name), name))
add("\t\t\t);")
add("\t\t\tdefaultConfigurationIsVisible = 0;")
add("\t\t\tdefaultConfigurationName = Release;")
add("\t\t};")
add("/* End XCConfigurationList section */")
add("\t};")
add("\trootObject = %s /* Project object */;" % project_id)
add("}")
return "\n".join(lines) + "\n"
def main():
project_dir = os.path.join(IOS_ROOT, "%s.xcodeproj" % APP_NAME)
os.makedirs(project_dir, exist_ok=True)
target = os.path.join(project_dir, "project.pbxproj")
with open(target, "w", encoding="utf-8") as fh:
fh.write(generate())
print("已生成 %s" % target)
missing = [p for p in SOURCES + RESOURCES + OTHER_FILES
if not os.path.exists(os.path.join(IOS_ROOT, p))]
if missing:
print("警告:以下文件在工程里被引用但不存在:")
for path in missing:
print(" " + path)
return 1
return 0
if __name__ == "__main__":
raise SystemExit(main())
+46
View File
@@ -0,0 +1,46 @@
@echo off
setlocal EnableExtensions
cd /d "%~dp0"
echo == QFT Rust one-click package ==
where cargo >nul 2>nul
if errorlevel 1 (
echo ERROR: Rust cargo was not found in PATH.
exit /b 1
)
echo [1/3] Testing and building the Rust Windows release...
pushd windows
cargo test
if errorlevel 1 (popd & exit /b 1)
cargo build --release
if errorlevel 1 (popd & exit /b 1)
popd
for /f "tokens=3" %%V in ('findstr /R /C:"^version =" "windows\Cargo.toml"') do set "QFT_VERSION=%%~V"
for /f "usebackq delims=" %%T in (`powershell -NoProfile -Command "Get-Date -Format yyyyMMdd-HHmmss"`) do set "QFT_STAMP=%%T"
if not defined QFT_VERSION set "QFT_VERSION=unknown"
set "QFT_PACKAGE=QFT-Rust-%QFT_VERSION%-%QFT_STAMP%-windows"
set "QFT_PACKAGE_DIR=%CD%\dist\%QFT_PACKAGE%"
echo [2/3] Collecting Rust artifacts...
mkdir "%QFT_PACKAGE_DIR%" || exit /b 1
copy /y "windows\target\release\qft-windows.exe" "%QFT_PACKAGE_DIR%\QFT-Windows.exe" >nul || exit /b 1
copy /y "README.md" "%QFT_PACKAGE_DIR%\README.md" >nul || exit /b 1
copy /y "TEST_REPORT.md" "%QFT_PACKAGE_DIR%\TEST_REPORT.md" >nul || exit /b 1
copy /y "docs\PROTOCOL.md" "%QFT_PACKAGE_DIR%\PROTOCOL.md" >nul || exit /b 1
echo [3/3] Writing SHA-256 checksums and ZIP archive...
powershell -NoProfile -Command ^
"$dir = [IO.Path]::GetFullPath('%QFT_PACKAGE_DIR%');" ^
"$lines = Get-ChildItem -LiteralPath $dir -File ^| Sort-Object Name ^| ForEach-Object { '{0} {1}' -f (Get-FileHash -Algorithm SHA256 -LiteralPath $_.FullName).Hash.ToLower(), $_.Name };" ^
"[IO.File]::WriteAllLines((Join-Path $dir 'SHA256SUMS.txt'), $lines, [Text.UTF8Encoding]::new($false));" ^
"Compress-Archive -LiteralPath $dir -DestinationPath ($dir + '.zip') -Force"
if errorlevel 1 exit /b 1
echo.
echo PACKAGE COMPLETE
echo Folder: %QFT_PACKAGE_DIR%
echo ZIP: %QFT_PACKAGE_DIR%.zip
exit /b 0
Executable
+95
View File
@@ -0,0 +1,95 @@
#!/usr/bin/env sh
set -eu
QFT_ROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
cd "$QFT_ROOT"
echo "== QFT Rust one-click package =="
if ! command -v cargo >/dev/null 2>&1; then
# rustup 装在 keg-only 目录里时不会自动进 PATH,这里兜一下,
# 避免用户明明装了工具链却被告知"没装"。
for QFT_CANDIDATE in "/opt/homebrew/opt/rustup/bin" "$HOME/.cargo/bin"; do
if [ -x "$QFT_CANDIDATE/cargo" ]; then
PATH="$QFT_CANDIDATE:$PATH"
export PATH
break
fi
done
fi
command -v cargo >/dev/null 2>&1 || {
echo "ERROR: Rust cargo was not found in PATH." >&2
echo " brew 安装:brew install rustup && rustup default stable" >&2
echo " 并把 /opt/homebrew/opt/rustup/bin 加入 PATH" >&2
exit 1
}
echo "[1/3] Testing and building the Rust desktop release..."
(
cd desktop
cargo test
cargo build --release
)
QFT_VERSION=$(awk -F'"' '/^\[package\]/{package=1; next} package && /^version[[:space:]]*=/{print $2; exit} /^\[/{package=0}' desktop/Cargo.toml)
[ -n "$QFT_VERSION" ] || QFT_VERSION=unknown
QFT_STAMP=$(date '+%Y%m%d-%H%M%S')
QFT_PLATFORM=$(uname -s | tr '[:upper:]' '[:lower:]')
QFT_PACKAGE="QFT-Rust-${QFT_VERSION}-${QFT_STAMP}-${QFT_PLATFORM}"
QFT_PACKAGE_DIR="$QFT_ROOT/dist/$QFT_PACKAGE"
echo "[2/3] Collecting Rust artifacts..."
mkdir -p "$QFT_PACKAGE_DIR"
if [ -f "desktop/target/release/qft-desktop.exe" ]; then
cp "desktop/target/release/qft-desktop.exe" "$QFT_PACKAGE_DIR/QFT-Windows.exe"
elif [ -f "desktop/target/release/qft-desktop" ]; then
cp "desktop/target/release/qft-desktop" "$QFT_PACKAGE_DIR/QFT-Desktop"
# macOS 上额外产出 .app 包。AppKit 的若干行为(其中就包括
# NSOpenPanel)依赖应用被正确注册为 GUI 程序,直接跑裸二进制时
# openPanel 会偶发返回 NULL 并导致崩溃。
if [ "$QFT_PLATFORM" = "darwin" ]; then
QFT_APP="$QFT_PACKAGE_DIR/QFT.app"
mkdir -p "$QFT_APP/Contents/MacOS"
cp "desktop/target/release/qft-desktop" "$QFT_APP/Contents/MacOS/QFT"
chmod +x "$QFT_APP/Contents/MacOS/QFT"
cat > "$QFT_APP/Contents/Info.plist" <<'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleName</key><string>QFT</string>
<key>CFBundleDisplayName</key><string>QFT 超速文件传输</string>
<key>CFBundleIdentifier</key><string>com.qft.desktop</string>
<key>CFBundleExecutable</key><string>QFT</string>
<key>CFBundlePackageType</key><string>APPL</string>
<key>CFBundleShortVersionString</key><string>0.5.0</string>
<key>CFBundleVersion</key><string>1</string>
<key>NSHighResolutionCapable</key><true/>
<key>LSMinimumSystemVersion</key><string>11.0</string>
</dict>
</plist>
PLIST
echo " 已生成 QFT.app(推荐用它启动,比裸二进制稳定)"
fi
else
echo "ERROR: desktop release binary was not produced." >&2
exit 1
fi
cp README.md TEST_REPORT.md "$QFT_PACKAGE_DIR/"
cp docs/PROTOCOL.md "$QFT_PACKAGE_DIR/PROTOCOL.md"
echo "[3/3] Writing SHA-256 checksums and archive..."
(
cd "$QFT_PACKAGE_DIR"
# 只对普通文件求校验和:.app 是目录,直接喂给 sha256sum 会报错
if command -v sha256sum >/dev/null 2>&1; then
find . -type f ! -name SHA256SUMS.txt | sort | xargs sha256sum > SHA256SUMS.txt
else
find . -type f ! -name SHA256SUMS.txt | sort | xargs shasum -a 256 > SHA256SUMS.txt
fi
)
tar -C "$QFT_ROOT/dist" -czf "$QFT_PACKAGE_DIR.tar.gz" "$QFT_PACKAGE"
echo
echo "PACKAGE COMPLETE"
echo "Folder: $QFT_PACKAGE_DIR"
echo "Archive: $QFT_PACKAGE_DIR.tar.gz"
+3
View File
@@ -4,6 +4,7 @@ import re
ROOT=Path(__file__).resolve().parents[1]
gradle=(ROOT/'android/app/build.gradle.kts').read_text(); manifest=(ROOT/'android/app/src/main/AndroidManifest.xml').read_text()
wifi=(ROOT/'android/app/src/main/java/com/qft/optical/WifiConnector.kt').read_text(); upload=(ROOT/'android/app/src/main/java/com/qft/optical/UploadClient.kt').read_text()
download=(ROOT/'android/app/src/main/java/com/qft/optical/DownloadClient.kt').read_text()
main=(ROOT/'android/app/src/main/java/com/qft/optical/MainActivity.kt').read_text(); analyzer=(ROOT/'android/app/src/main/java/com/qft/optical/QrAnalyzer.kt').read_text()
gray=(ROOT/'android/app/src/main/java/com/qft/optical/GrayFrame.kt').read_text(); protocol=(ROOT/'android/app/src/main/java/com/qft/optical/Protocol.kt').read_text(); base45=(ROOT/'android/app/src/main/java/com/qft/optical/Base45.kt').read_text(); overlay=(ROOT/'android/app/src/main/java/com/qft/optical/QrLockOverlay.kt').read_text(); security=(ROOT/'android/app/src/main/res/xml/network_security_config.xml').read_text()
assert re.search(r'minSdk\s*=\s*24',gradle)
@@ -12,6 +13,8 @@ assert 'ACCESS_FINE_LOCATION" android:maxSdkVersion="32"' in manifest and 'NEARB
assert 'networkSecurityConfig="@xml/network_security_config"' in manifest and 'cleartextTrafficPermitted="true"' in security
assert 'Build.VERSION.SDK_INT >= 29' in wifi and 'connectLegacy' in wifi and 'subnetEndpoints' in wifi and 'directedBroadcast' in wifi
assert 'MAX_WORKERS = 8' in upload and 'QFTDISC2:' in upload
assert 'MAX_WORKERS = 8' in download and 'bytes=$start-$end' in download and 'completionMapFile' in download
assert 'requestNetwork(request, cb)' in wifi and 'delivered.set(false)' in wifi
assert 'val targetSize = Size(640, 480)' in main and 'Size(960, 540)' not in main
assert 'Camera2Interop.Extender' in main and 'CONTROL_AE_TARGET_FPS_RANGE' in main and 'STRATEGY_KEEP_ONLY_LATEST' in main
assert '设备拒绝显式高帧率请求' in main and 'fallbackAnalysis' in main
+40
View File
@@ -0,0 +1,40 @@
#!/usr/bin/env python3
"""把 iOS 核心层测试接进主自检套件。
iOS 核心层(协议解析、局域网发现、上传/下载、P2P 链路)刻意不 import
UIKit/AVFoundation,因此可以直接以 macOS 为目标编译运行,
不需要 Xcode,也不需要模拟器。
非 macOS 主机或没有 swiftc 时跳过,不让整套自检失败。
"""
import platform
import shutil
import subprocess
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
RUNNER = ROOT / "ios" / "CoreTests" / "run.sh"
def main() -> int:
if platform.system() != "Darwin":
print("SKIP:iOS 核心层测试需要 macOS")
return 0
if shutil.which("swiftc") is None:
print("SKIP:未找到 swiftc(安装 Xcode 或 Command Line Tools 后可运行)")
return 0
if not RUNNER.exists():
print("SKIP:%s 不存在" % RUNNER)
return 0
result = subprocess.run(["bash", str(RUNNER)], cwd=str(ROOT))
if result.returncode != 0:
print("iOS 核心层测试失败")
return result.returncode
return 0
if __name__ == "__main__":
sys.exit(main())
+107
View File
@@ -0,0 +1,107 @@
#!/usr/bin/env python3
"""Bounded Range + retry + out-of-order positioned-write download self-test."""
import hashlib
import http.client
import random
import tempfile
import threading
from concurrent.futures import ThreadPoolExecutor
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
SIZE = 64 * 1024 * 1024 + 12345
CHUNK = 16 * 1024 * 1024
WORKERS = 8
TOKEN = "parallel_download_test"
def digest(path):
value = hashlib.sha256()
with open(path, "rb", buffering=0) as stream:
while block := stream.read(4 * 1024 * 1024):
value.update(block)
return value.hexdigest()
def main():
assert (1024 * 1024 * 1024 + CHUNK - 1) // CHUNK == 64
with tempfile.TemporaryDirectory() as temp:
root = Path(temp)
source = root / "source.bin"
target = root / "target.qftpart"
pattern = bytes((index * 73 + 19) & 0xFF for index in range(1024 * 1024))
with source.open("wb", buffering=0) as stream:
remaining = SIZE
while remaining:
block = pattern[:min(len(pattern), remaining)]
stream.write(block)
remaining -= len(block)
with target.open("wb") as stream:
stream.truncate(SIZE)
class Handler(BaseHTTPRequestHandler):
def log_message(self, *_):
pass
def do_GET(self):
if self.path != "/qft/download" or self.headers.get("X-QFT-Token") != TOKEN:
self.send_error(403)
return
value = self.headers.get("Range", "")
assert value.startswith("bytes=") and "-" in value
start_text, end_text = value[6:].split("-", 1)
start, end = int(start_text), int(end_text)
assert 0 <= start <= end < SIZE
length = end - start + 1
self.send_response(206)
self.send_header("Content-Length", str(length))
self.send_header("Content-Range", f"bytes {start}-{end}/{SIZE}")
self.end_headers()
with source.open("rb", buffering=0) as stream:
stream.seek(start)
remaining = length
while remaining:
block = stream.read(min(1024 * 1024, remaining))
assert block
self.wfile.write(block)
remaining -= len(block)
server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
host, port = server.server_address
indices = list(range((SIZE + CHUNK - 1) // CHUNK))
random.Random(42).shuffle(indices)
def receive(index):
start = index * CHUNK
end = min(SIZE, start + CHUNK) - 1
connection = http.client.HTTPConnection(host, port, timeout=10)
connection.request("GET", "/qft/download", headers={
"X-QFT-Token": TOKEN,
"Range": f"bytes={start}-{end}",
})
response = connection.getresponse()
assert response.status == 206
assert response.getheader("Content-Range") == f"bytes {start}-{end}/{SIZE}"
offset = start
with target.open("r+b", buffering=0) as output:
output.seek(start)
while block := response.read(1024 * 1024):
assert output.write(block) == len(block)
offset += len(block)
connection.close()
assert offset == end + 1
try:
with ThreadPoolExecutor(max_workers=WORKERS) as pool:
list(pool.map(receive, indices))
finally:
server.shutdown()
server.server_close()
assert digest(source) == digest(target)
print(f"PASS parallel download: {SIZE} bytes, 16 MiB bounded ranges, {WORKERS} workers, SHA-256 identical; 1 GiB maps to 64 resumable ranges")
if __name__ == "__main__":
main()
+3
View File
@@ -7,12 +7,15 @@ scripts = [
'optical_image_decode_selftest.py',
'pairing_selftest.py',
'parallel_upload_selftest.py',
'parallel_download_selftest.py',
'udp_discovery_selftest.py',
'local_transfer_integration_selftest.py',
'memory_budget_selftest.py',
'android_compat_selftest.py',
'single_channel_guard_selftest.py',
'kotlin_host_smoke.py',
'wedge_selftest.py',
'ios_core_selftest.py',
]
for name in scripts:
print(f'== {name} ==', flush=True)
+14 -7
View File
@@ -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')
+446
View File
@@ -0,0 +1,446 @@
#!/usr/bin/env python3
"""分析楔形标定图的照片,输出「每模块相机像素数 → 误码率」曲线。
python scripts/wedge_analyze.py --spec out/wedge.json --photo IMG_0001.jpg
流程与真实解码器完全一致,所以测出来的就是真实可用的下限:
检测四角基准标 → 解单应矩阵 → 按模块中心单点采样
→ 局部均值阈值面 → 判决 → 与期望比特比对
--analysis-width 用来模拟手机 ImageAnalysis 流的分辨率(默认 1920,即 1080p)。
照片本身通常是 12MP,直接分析会高估能力;先降采样到分析流分辨率才有意义。
"""
import argparse
import os
import sys
import numpy as np
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from wedge_common import WedgeSpec, band_bits, module_centers_active # noqa: E402
# ---------------------------------------------------------------- 图像载入
def load_gray(path, analysis_width):
from PIL import Image, ImageOps
image = Image.open(path)
image = ImageOps.exif_transpose(image)
image = image.convert("L")
original = image.size
if analysis_width and image.width > analysis_width:
height = max(1, int(round(image.height * analysis_width / image.width)))
# BOX(面积平均)最接近相机 ISP 的降采样行为
image = image.resize((analysis_width, height), Image.BOX)
return np.asarray(image, dtype=np.float32), original
# ---------------------------------------------------------------- 连通域
def otsu(gray):
hist, _ = np.histogram(gray, bins=256, range=(0, 256))
total = hist.sum()
if total == 0:
return 128.0
levels = np.arange(256, dtype=np.float64)
w0 = np.cumsum(hist).astype(np.float64)
w1 = total - w0
s0 = np.cumsum(hist * levels)
total_sum = s0[-1]
valid = (w0 > 0) & (w1 > 0)
if not valid.any():
return 128.0
m0 = np.where(w0 > 0, s0 / np.maximum(w0, 1), 0.0)
m1 = np.where(w1 > 0, (total_sum - s0) / np.maximum(w1, 1), 0.0)
between = w0 * w1 * (m0 - m1) ** 2
between[~valid] = -1.0
return float(np.argmax(between))
def label_components(mask):
"""行程 + 并查集的连通域标记(4 连通)。返回 (labels, count)。"""
height, width = mask.shape
parent = [0]
def find(a):
while parent[a] != a:
parent[a] = parent[parent[a]]
a = parent[a]
return a
def union(a, b):
ra, rb = find(a), find(b)
if ra != rb:
parent[max(ra, rb)] = min(ra, rb)
labels = np.zeros((height, width), dtype=np.int32)
prev_runs = []
for y in range(height):
row = mask[y]
if not row.any():
prev_runs = []
continue
diff = np.diff(np.concatenate(([0], row.view(np.int8), [0])))
starts = np.flatnonzero(diff == 1)
ends = np.flatnonzero(diff == -1)
runs = []
for x0, x1 in zip(starts, ends):
parent.append(len(parent))
current = len(parent) - 1
for px0, px1, plabel in prev_runs:
if px0 < x1 and x0 < px1:
union(current, plabel)
labels[y, x0:x1] = current
runs.append((x0, x1, current))
prev_runs = runs
flat = labels.reshape(-1)
nonzero = flat > 0
if nonzero.any():
roots = np.array([find(i) for i in range(len(parent))], dtype=np.int32)
flat[nonzero] = roots[flat[nonzero]]
unique, remapped = np.unique(flat[nonzero], return_inverse=True)
flat[nonzero] = remapped + 1
count = len(unique)
else:
count = 0
return labels, count
def find_markers(gray, debug=None):
"""返回四个基准标中心(照片像素),顺序 TL, TR, BR, BL。"""
height, width = gray.shape
scale = max(1.0, width / 1200.0)
if scale > 1.0:
from PIL import Image
small = np.asarray(
Image.fromarray(gray.astype(np.uint8)).resize(
(int(width / scale), int(height / scale)), Image.BOX),
dtype=np.float32)
else:
small = gray
threshold = otsu(small)
mask = small < threshold
labels, count = label_components(mask)
if count == 0:
raise RuntimeError("照片里找不到任何暗色区域")
area_image = small.shape[0] * small.shape[1]
candidates = []
for index in range(1, count + 1):
ys, xs = np.nonzero(labels == index)
area = len(xs)
if area < 24 or area > area_image * 0.02:
continue
x0, x1 = xs.min(), xs.max() + 1
y0, y1 = ys.min(), ys.max() + 1
bw, bh = x1 - x0, y1 - y0
aspect = bw / float(bh)
if not 0.55 < aspect < 1.8:
continue
if area / float(bw * bh) < 0.72: # 实心方块
continue
# 外围一圈必须是白的(黑方块落在白底上),排除画面外的暗区与数据模块
pad = int(max(bw, bh) * 0.6) + 2
ry0, ry1 = max(0, y0 - pad), min(small.shape[0], y1 + pad)
rx0, rx1 = max(0, x0 - pad), min(small.shape[1], x1 + pad)
ring = small[ry0:ry1, rx0:rx1].copy()
inner = ring[y0 - ry0:y1 - ry0, x0 - rx0:x1 - rx0]
ring_sum = ring.sum() - inner.sum()
ring_n = ring.size - inner.size
if ring_n <= 0 or ring_sum / ring_n < threshold * 1.15:
continue
candidates.append((area, (xs.mean() + 0.5) * scale, (ys.mean() + 0.5) * scale,
bw * scale, bh * scale))
if len(candidates) < 4:
raise RuntimeError("只找到 %d 个候选基准标(需要 4 个)。"
"请让四个黑色角标全部进入画面,并保持画面明亮、对焦清晰。"
% len(candidates))
candidates.sort(key=lambda c: -c[0])
pool = candidates[:24]
pts = np.array([[c[1], c[2]] for c in pool])
sizes = np.array([max(c[3], c[4]) for c in pool])
def pick(score):
return int(np.argmax(score))
tl = pick(-(pts[:, 0] + pts[:, 1]))
br = pick(pts[:, 0] + pts[:, 1])
tr = pick(pts[:, 0] - pts[:, 1])
bl = pick(pts[:, 1] - pts[:, 0])
chosen = [tl, tr, br, bl]
if len(set(chosen)) != 4:
raise RuntimeError("角标定位歧义,请正对屏幕重拍,避免过大的倾斜")
refined = []
for index in chosen:
cx, cy, size = pts[index, 0], pts[index, 1], sizes[index]
refined.append(refine_centroid(gray, cx, cy, size))
if debug is not None:
debug["markers_raw"] = pts[chosen].tolist()
return refined
def refine_centroid(gray, cx, cy, size):
"""在全分辨率图上做灰度加权质心,取得亚像素中心。"""
half = max(4.0, size * 0.9)
x0 = int(max(0, np.floor(cx - half)))
x1 = int(min(gray.shape[1], np.ceil(cx + half)))
y0 = int(max(0, np.floor(cy - half)))
y1 = int(min(gray.shape[0], np.ceil(cy + half)))
patch = gray[y0:y1, x0:x1]
if patch.size == 0:
return (float(cx), float(cy))
level = otsu(patch)
weight = np.clip(level - patch, 0, None)
total = weight.sum()
if total <= 0:
return (float(cx), float(cy))
ys, xs = np.mgrid[y0:y1, x0:x1]
return (float((weight * xs).sum() / total) + 0.5,
float((weight * ys).sum() / total) + 0.5)
# ---------------------------------------------------------------- 几何
def homography(src, dst):
"""求解 src(4×2) → dst(4×2) 的 3×3 单应矩阵(h8 = 1)。"""
a = np.zeros((8, 8), dtype=np.float64)
b = np.zeros(8, dtype=np.float64)
for i in range(4):
x, y = src[i]
u, v = dst[i]
a[2 * i] = [x, y, 1, 0, 0, 0, -x * u, -y * u]
b[2 * i] = u
a[2 * i + 1] = [0, 0, 0, x, y, 1, -x * v, -y * v]
b[2 * i + 1] = v
h = np.linalg.solve(a, b)
return np.append(h, 1.0).reshape(3, 3)
def project(h, points):
"""单应变换。逐分量展开而非 matmul:大点集下更省内存,
也避开 BLAS 在大矩阵乘法上偶发的伪浮点警告。"""
pts = np.asarray(points, dtype=np.float64)
x = pts[..., 0]
y = pts[..., 1]
u = h[0, 0] * x + h[0, 1] * y + h[0, 2]
v = h[1, 0] * x + h[1, 1] * y + h[1, 2]
w = h[2, 0] * x + h[2, 1] * y + h[2, 2]
# w 趋近 0 表示该点被映射到无穷远(逆映射时落在画面之外),
# 夹住分母避免 inf/nan 污染后续采样。
w = np.where(np.abs(w) < 1e-12, 1e-12, w)
return np.stack([u / w, v / w], axis=-1)
def local_scale(h, x, y):
"""单应矩阵在 (x, y) 处的各向同性放大率:照片像素 / 显示像素。"""
u = h[0, 0] * x + h[0, 1] * y + h[0, 2]
v = h[1, 0] * x + h[1, 1] * y + h[1, 2]
w = h[2, 0] * x + h[2, 1] * y + h[2, 2]
dudx = (h[0, 0] * w - u * h[2, 0]) / w ** 2
dudy = (h[0, 1] * w - u * h[2, 1]) / w ** 2
dvdx = (h[1, 0] * w - v * h[2, 0]) / w ** 2
dvdy = (h[1, 1] * w - v * h[2, 1]) / w ** 2
return float(np.sqrt(abs(dudx * dvdy - dudy * dvdx)))
def bilinear(gray, points):
height, width = gray.shape
x = np.clip(points[..., 0], 0, width - 1.001)
y = np.clip(points[..., 1], 0, height - 1.001)
x0 = np.floor(x).astype(np.int32)
y0 = np.floor(y).astype(np.int32)
fx = x - x0
fy = y - y0
v00 = gray[y0, x0]
v01 = gray[y0, x0 + 1]
v10 = gray[y0 + 1, x0]
v11 = gray[y0 + 1, x0 + 1]
return (v00 * (1 - fx) * (1 - fy) + v01 * fx * (1 - fy) +
v10 * (1 - fx) * fy + v11 * fx * fy)
def box_mean(values, ky, kx):
"""边界收缩的滑动平均,用作局部阈值面。"""
rows, cols = values.shape
ky = max(1, min(ky if ky % 2 == 1 else ky - 1, rows if rows % 2 == 1 else rows - 1))
kx = max(1, min(kx if kx % 2 == 1 else kx - 1, cols if cols % 2 == 1 else cols - 1))
ry, rx = ky // 2, kx // 2
padded = np.pad(values, ((ry, ry), (rx, rx)), mode="edge")
integral = np.zeros((padded.shape[0] + 1, padded.shape[1] + 1), dtype=np.float64)
integral[1:, 1:] = padded.cumsum(axis=0).cumsum(axis=1)
total = (integral[ky:ky + rows, kx:kx + cols]
- integral[0:rows, kx:kx + cols]
- integral[ky:ky + rows, 0:cols]
+ integral[0:rows, 0:cols])
return total / float(ky * kx)
# ---------------------------------------------------------------- 分析
def analyze_band(gray, spec, band, h, threshold_window):
centers = module_centers_active(band, spec)
photo = project(h, centers)
samples = bilinear(gray, photo)
expected = band_bits(band) # 1 = 黑
threshold = box_mean(samples, threshold_window, threshold_window)
decoded = (samples < threshold).astype(np.uint8) # 比阈值暗 → 判为黑(1)
errors = int(np.count_nonzero(decoded != expected))
total = expected.size
ber = errors / float(total)
white = samples[expected == 0]
black = samples[expected == 1]
if white.size and black.size:
mw, mb = float(white.mean()), float(black.mean())
contrast = (mw - mb) / (mw + mb) if (mw + mb) > 0 else 0.0
else:
mw = mb = contrast = 0.0
cx = band.x + band.width_px / 2.0
cy = band.y + band.height_px / 2.0
px_per_module = local_scale(h, cx, cy) * band.pitch_px
return {
"index": band.index,
"pitch_px": band.pitch_px,
"px_per_module": px_per_module,
"modules": total,
"errors": errors,
"ber": ber,
"contrast": contrast,
"white": mw,
"black": mb,
}
def inner_fec_overhead(ber):
"""把给定原始误码率压到可忽略的带错率,所需的内码冗余(粗估)。
条带级 CRC 下,1750 B 的条带只要有 1 bit 错就整条报废,
因此必须用内码(RS/LDPC)先把原始 BER 吃掉,外层喷泉码只负责丢包。
GF(256) 的 RS:字节错率 ≈ 8·BER,留 3 倍余量 → 冗余 ≈ 48·BER。
"""
if ber <= 0:
return 0.0
return min(1.0, 48.0 * ber)
def verdict(ber):
if ber == 0:
return "✅ 无误码"
if ber < 1e-3:
return "✅ 可用"
if ber < 1e-2:
return "⚠️ 勉强"
return "❌ 不可用"
def crossing(rows, limit):
"""在 BER-px/模块 曲线上插值出 BER 恰好等于 limit 的位置。"""
ordered = sorted(rows, key=lambda r: r["px_per_module"])
for a, b in zip(ordered, ordered[1:]):
if a["ber"] > limit >= b["ber"]:
ya, yb = np.log10(max(a["ber"], 1e-9)), np.log10(max(b["ber"], 1e-9))
if abs(yb - ya) < 1e-12:
return b["px_per_module"]
t = (np.log10(limit) - ya) / (yb - ya)
return a["px_per_module"] + t * (b["px_per_module"] - a["px_per_module"])
return None
def write_debug_image(path, gray, spec, h, markers):
from PIL import Image, ImageDraw
image = Image.fromarray(gray.astype(np.uint8)).convert("RGB")
draw = ImageDraw.Draw(image)
for x, y in markers:
draw.ellipse([x - 9, y - 9, x + 9, y + 9], outline=(255, 40, 40), width=3)
corners = project(h, spec.active_corners())
draw.polygon([tuple(p) for p in corners], outline=(40, 220, 255))
for band in spec.bands:
rect = [(band.x, band.y),
(band.x + band.width_px, band.y),
(band.x + band.width_px, band.y + band.height_px),
(band.x, band.y + band.height_px)]
pts = project(h, rect)
draw.polygon([tuple(p) for p in pts], outline=(80, 255, 120))
image.save(path)
def main() -> int:
parser = argparse.ArgumentParser(description="分析楔形标定图照片")
parser.add_argument("--spec", required=True, help="wedge_gen.py 产出的 .json")
parser.add_argument("--photo", required=True, help="手机拍摄的照片")
parser.add_argument("--analysis-width", type=int, default=1920,
help="模拟 ImageAnalysis 流宽度,0 表示不降采样")
parser.add_argument("--threshold-window", type=int, default=17,
help="局部阈值面的窗口边长(模块数)")
parser.add_argument("--debug-image", type=str, default=None,
help="写出一张叠加了定位结果的诊断图")
args = parser.parse_args()
spec = WedgeSpec.load(args.spec)
gray, original = load_gray(args.photo, args.analysis_width)
debug = {}
markers = find_markers(gray, debug)
h = homography(spec.active_corners(), markers)
rows = [analyze_band(gray, spec, band, h, args.threshold_window) for band in spec.bands]
if args.debug_image:
write_debug_image(args.debug_image, gray, spec, h, markers)
width_px = float(np.hypot(markers[1][0] - markers[0][0], markers[1][1] - markers[0][1]))
print("照片:%s" % os.path.basename(args.photo))
print("原始尺寸 %d×%d → 分析尺寸 %d×%d" % (original[0], original[1], gray.shape[1], gray.shape[0]))
print("标定图 active 宽 %d 显示像素 → 照片中 %.1f 像素(放大率 %.3f)"
% (spec.active_w, width_px, width_px / spec.active_w))
print()
print("%-6s %-9s %-11s %-9s %-10s %-11s %s"
% ("条带", "显示pitch", "px/模块", "对比度", "模块数", "误码率", "判定"))
for row in rows:
print("%-6d %-9d %-11.2f %-9.3f %-10d %-11s %s"
% (row["index"], row["pitch_px"], row["px_per_module"], row["contrast"],
row["modules"],
"0" if row["ber"] == 0 else "%.2e" % row["ber"],
verdict(row["ber"])))
print()
limit = crossing(rows, 1e-3)
if limit is not None:
print("BER=1e-3 的临界点:约 %.2f px/模块" % limit)
usable = [r for r in rows if r["ber"] < 1e-3]
if usable:
best = min(usable, key=lambda r: r["px_per_module"])
print("本次实测可用下限:%.2f px/模块(BER %s,内码冗余需 %.1f%%)"
% (best["px_per_module"],
"0" if best["ber"] == 0 else "%.1e" % best["ber"],
inner_fec_overhead(best["ber"]) * 100))
area = gray.shape[0] * gray.shape[1] * 0.95
modules = area / best["px_per_module"] ** 2
payload = modules * (1 - 0.04) * (1 - 0.15 - inner_fec_overhead(best["ber"])) / 8
print("→ 按此下限,%d×%d 分析流每画布净载荷约 %.0f B"
% (gray.shape[1], gray.shape[0], max(payload, 0)))
for fps in (24, 30, 60):
rate = payload * fps * 0.92
if rate > 0:
print(" @%d FPS:%.0f KB/s 1MB %.2fs 10MB %.2fs"
% (fps, rate / 1024, 1048576 / rate, 10485760 / rate))
else:
print("所有条带都超过 1e-3,请靠近屏幕重拍,或改用更大的 --pitches")
return 0
if __name__ == "__main__":
raise SystemExit(main())
+229
View File
@@ -0,0 +1,229 @@
#!/usr/bin/env python3
"""QFT 分辨率楔形标定图 —— 共享规格、PRNG 与渲染。
用途:在屏幕上显示一张同时包含多种模块尺寸(pitch)的伪随机二值图案,
手机拍一张照片,由 wedge_analyze.py 反解出「每模块相机像素数 → 误码率」曲线,
从而实测出本套硬件真正的 px/模块 下限。这个下限直接决定 QFT5 位阵列的容量。
坐标系
------
canvas 坐标:整张标定图的像素坐标,原点左上。
active 坐标:以左上角基准标**中心**为原点的坐标系;四个基准标中心构成 active 矩形。
分析端解出的单应矩阵就是 active → 照片像素 的映射,因此所有条带几何
都用 active 坐标描述,与画布边距无关。
约定
----
- 模块 bit == 1 → 黑 (0),bit == 0 → 白 (255)。
- PRNG 为 SplitMix64,Rust / Kotlin 移植时必须逐位一致(见 splitmix64)。
- 模块 (r, c) 的比特序号 k = r * cols + c;取第 k//64 个 64 位输出的第 k%64 位(LSB 起)。
"""
from dataclasses import dataclass, asdict
from typing import List, Optional
import json
MASK64 = (1 << 64) - 1
GOLDEN = 0x9E3779B97F4A7C15
SPEC_VERSION = 1
DEFAULT_PITCHES = [10, 8, 6, 5, 4, 3, 2]
DEFAULT_SEED = 20260810
# 画布留白与基准标尺寸(canvas 像素)
MARGIN_PX = 40
MARKER_PX = 56
INSET_PX = 64 # 数据区相对 active 矩形的内缩,保证基准标周围留白
GUTTER_PX = 8 # 条带间隔
def splitmix64(state: int):
"""SplitMix64 生成器。返回 (下一状态, 64 位输出)。"""
state = (state + GOLDEN) & MASK64
z = state
z = ((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9) & MASK64
z = ((z ^ (z >> 27)) * 0x94D049BB133111EB) & MASK64
return state, z ^ (z >> 31)
def band_seed(seed: int, index: int) -> int:
return (seed ^ ((GOLDEN * (index + 1)) & MASK64)) & MASK64
@dataclass
class BandSpec:
index: int
pitch_px: int
cols: int
rows: int
x: int # active 坐标
y: int
seed: int
@property
def width_px(self) -> int:
return self.cols * self.pitch_px
@property
def height_px(self) -> int:
return self.rows * self.pitch_px
@property
def modules(self) -> int:
return self.cols * self.rows
@dataclass
class WedgeSpec:
version: int
canvas_w: int
canvas_h: int
margin_px: int
marker_px: int
inset_px: int
gutter_px: int
seed: int
active_w: int # active 矩形尺寸(= 基准标中心间距)
active_h: int
bands: List[BandSpec]
def to_json(self, indent: Optional[int] = 2) -> str:
payload = asdict(self)
return json.dumps(payload, indent=indent, ensure_ascii=False)
@staticmethod
def from_dict(payload: dict) -> "WedgeSpec":
bands = [BandSpec(**b) for b in payload["bands"]]
rest = {k: v for k, v in payload.items() if k != "bands"}
return WedgeSpec(bands=bands, **rest)
@staticmethod
def load(path) -> "WedgeSpec":
with open(path, "r", encoding="utf-8") as fh:
return WedgeSpec.from_dict(json.load(fh))
def marker_centers_canvas(self):
"""四个基准标中心在 canvas 坐标下的位置,顺序 TL, TR, BR, BL。"""
half = self.marker_px / 2.0
x0 = self.margin_px + half
y0 = self.margin_px + half
x1 = self.canvas_w - self.margin_px - half
y1 = self.canvas_h - self.margin_px - half
return [(x0, y0), (x1, y0), (x1, y1), (x0, y1)]
def active_corners(self):
"""active 坐标下的四角,顺序与 marker_centers_canvas 一致。"""
return [(0.0, 0.0), (float(self.active_w), 0.0),
(float(self.active_w), float(self.active_h)), (0.0, float(self.active_h))]
def build_spec(canvas_w: int = 1920,
canvas_h: int = 1080,
pitches: Optional[List[int]] = None,
seed: int = DEFAULT_SEED,
margin_px: int = MARGIN_PX,
marker_px: int = MARKER_PX,
inset_px: int = INSET_PX,
gutter_px: int = GUTTER_PX) -> WedgeSpec:
pitches = list(pitches or DEFAULT_PITCHES)
if not pitches:
raise ValueError("至少需要一个 pitch")
if any(p < 1 for p in pitches):
raise ValueError("pitch 必须 >= 1 显示像素")
active_w = canvas_w - 2 * margin_px - marker_px
active_h = canvas_h - 2 * margin_px - marker_px
data_w = active_w - 2 * inset_px
data_h = active_h - 2 * inset_px
if data_w < 64 or data_h < 64:
raise ValueError("画布太小,数据区不足")
n = len(pitches)
band_h = (data_h - (n - 1) * gutter_px) // n
if band_h < max(pitches):
raise ValueError("画布高度不足以容纳全部条带")
bands: List[BandSpec] = []
for i, pitch in enumerate(pitches):
cols = data_w // pitch
rows = band_h // pitch
if cols < 8 or rows < 2:
raise ValueError("pitch %d 下条带尺寸过小" % pitch)
bands.append(BandSpec(
index=i,
pitch_px=pitch,
cols=cols,
rows=rows,
x=inset_px,
y=inset_px + i * (band_h + gutter_px),
seed=band_seed(seed, i),
))
return WedgeSpec(
version=SPEC_VERSION,
canvas_w=canvas_w,
canvas_h=canvas_h,
margin_px=margin_px,
marker_px=marker_px,
inset_px=inset_px,
gutter_px=gutter_px,
seed=seed,
active_w=active_w,
active_h=active_h,
bands=bands,
)
def band_bits(band: BandSpec):
"""返回形状 (rows, cols) 的 uint8 数组,1 = 黑模块。"""
import numpy as np
total = band.modules
words = (total + 63) // 64
state = band.seed
out = np.empty(words, dtype=np.uint64)
for i in range(words):
state, value = splitmix64(state)
out[i] = value
bits = np.unpackbits(out.view(np.uint8).reshape(words, 8), axis=1, bitorder="little")
# view(uint8) 在小端机器上给出 LSB->MSB 的字节序,配合 bitorder="little"
# 即得到 k 递增方向的比特流。
bits = bits.reshape(-1)[:total]
return bits.reshape(band.rows, band.cols)
def render(spec: WedgeSpec):
"""渲染整张标定图,返回 (H, W) 的 uint8 灰度数组。"""
import numpy as np
canvas = np.full((spec.canvas_h, spec.canvas_w), 255, dtype=np.uint8)
# active 原点在 canvas 中的位置 = 左上基准标中心
ox = spec.margin_px + spec.marker_px / 2.0
oy = spec.margin_px + spec.marker_px / 2.0
# 四个实心黑方块基准标,中心落在 active 四角
half = spec.marker_px // 2
for cx, cy in spec.marker_centers_canvas():
x0, y0 = int(round(cx)) - half, int(round(cy)) - half
canvas[y0:y0 + spec.marker_px, x0:x0 + spec.marker_px] = 0
for band in spec.bands:
bits = band_bits(band)
block = np.repeat(np.repeat(bits, band.pitch_px, axis=0), band.pitch_px, axis=1)
px = int(round(ox + band.x))
py = int(round(oy + band.y))
canvas[py:py + block.shape[0], px:px + block.shape[1]] = np.where(block == 1, 0, 255)
return canvas
def module_centers_active(band: BandSpec, spec: WedgeSpec):
"""返回该条带全部模块中心的 active 坐标,形状 (rows, cols, 2)。"""
import numpy as np
del spec # 条带 x/y 已是 active 坐标,无需画布信息
cx = band.x + (np.arange(band.cols) + 0.5) * band.pitch_px
cy = band.y + (np.arange(band.rows) + 0.5) * band.pitch_px
gx, gy = np.meshgrid(cx, cy)
return np.stack([gx, gy], axis=-1)
+132
View File
@@ -0,0 +1,132 @@
#!/usr/bin/env python3
"""生成 QFT 分辨率楔形标定图。
python scripts/wedge_gen.py --width 1920 --height 1080 --out out/wedge
产出三个文件:
<out>.png 标定图本体(必须 1:1 显示,任何缩放都会让测量失效)
<out>.json 规格,wedge_analyze.py 用它反解几何与期望比特
<out>.html 全屏 1:1 查看器,自带缩放校验
显示方法(二选一):
A. 用浏览器打开 <out>.html,按 F11 全屏。页面会显示「缩放 1.000 ✅」才算有效。
B. 任何能保证 100% 原始像素显示的看图工具,且系统 DPI 缩放为 100%。
拍摄方法:
- 手机大致正立(旋转 < 45°),让四个黑色角标都在画面内且尽量填满画面;
- 关闭闪光灯,对焦到屏幕上;
- 建议在 2~4 个不同距离各拍一张,这样能把 px/模块 曲线的采样点连起来。
"""
import argparse
import os
import sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from wedge_common import build_spec, render, DEFAULT_PITCHES, DEFAULT_SEED # noqa: E402
VIEWER_HTML = """<!doctype html>
<meta charset="utf-8">
<title>QFT 标定图 1:1 查看器</title>
<style>
html,body{margin:0;padding:0;background:#fff;overflow:hidden}
#wrap{position:absolute;inset:0;display:flex;align-items:center;justify-content:center}
img{image-rendering:pixelated;image-rendering:crisp-edges}
#hud{position:fixed;left:8px;top:8px;font:13px/1.5 ui-monospace,Consolas,monospace;
background:rgba(0,0,0,.82);color:#fff;padding:8px 12px;border-radius:6px;z-index:9}
#hud.bad{background:rgba(150,20,20,.92)}
#hud b{color:#8f8}
#hud.bad b{color:#fbb}
</style>
<div id="wrap"><img id="img" src="__PNG__" alt=""></div>
<div id="hud">测量中…(按 H 隐藏此框,F11 全屏)</div>
<script>
const img = document.getElementById('img'), hud = document.getElementById('hud');
function check(){
const dpr = window.devicePixelRatio || 1;
// 让 1 个图像像素 == 1 个设备像素
img.style.width = (img.naturalWidth / dpr) + 'px';
img.style.height = (img.naturalHeight / dpr) + 'px';
const rect = img.getBoundingClientRect();
const shownDevicePx = rect.width * dpr;
const scale = shownDevicePx / img.naturalWidth;
const screenW = Math.round(window.screen.width * dpr);
const screenH = Math.round(window.screen.height * dpr);
const fits = img.naturalWidth <= screenW && img.naturalHeight <= screenH;
const ok = Math.abs(scale - 1) < 0.002 && fits;
hud.className = ok ? '' : 'bad';
hud.innerHTML =
'图像 ' + img.naturalWidth + '×' + img.naturalHeight +
' · 屏幕设备像素 ' + screenW + '×' + screenH +
' · DPR ' + dpr.toFixed(3) +
' · 缩放 <b>' + scale.toFixed(3) + (ok ? ' ✅</b>' : ' ❌</b>') +
(fits ? '' : '<br>标定图大于屏幕,请用 --width/--height 重新生成为屏幕设备像素尺寸') +
(Math.abs(scale-1) < 0.002 ? '' : '<br>浏览器缩放不是 100%,请按 Ctrl+0 复位');
}
img.complete ? check() : img.addEventListener('load', check);
addEventListener('resize', check);
addEventListener('keydown', e => {
if (e.key === 'h' || e.key === 'H') hud.style.display = hud.style.display === 'none' ? '' : 'none';
});
</script>
"""
def main() -> int:
parser = argparse.ArgumentParser(description="生成 QFT 分辨率楔形标定图")
parser.add_argument("--width", type=int, default=1920, help="画布宽(显示设备像素)")
parser.add_argument("--height", type=int, default=1080, help="画布高(显示设备像素)")
parser.add_argument("--pitches", type=str, default=",".join(str(p) for p in DEFAULT_PITCHES),
help="各条带的模块尺寸,单位显示像素,逗号分隔(必须为整数)")
parser.add_argument("--seed", type=int, default=DEFAULT_SEED)
parser.add_argument("--out", type=str, default="out/wedge", help="输出前缀,不带扩展名")
args = parser.parse_args()
try:
pitches = [int(p) for p in args.pitches.split(",") if p.strip()]
except ValueError:
print("--pitches 必须是逗号分隔的整数", file=sys.stderr)
return 2
try:
spec = build_spec(args.width, args.height, pitches, args.seed)
except ValueError as exc:
print("规格无效:%s" % exc, file=sys.stderr)
return 2
from PIL import Image
canvas = render(spec)
out_dir = os.path.dirname(os.path.abspath(args.out))
if out_dir:
os.makedirs(out_dir, exist_ok=True)
png_path = args.out + ".png"
json_path = args.out + ".json"
html_path = args.out + ".html"
Image.fromarray(canvas).save(png_path, optimize=True)
with open(json_path, "w", encoding="utf-8") as fh:
fh.write(spec.to_json())
with open(html_path, "w", encoding="utf-8") as fh:
fh.write(VIEWER_HTML.replace("__PNG__", os.path.basename(png_path)))
print("已生成:")
print(" %s %d×%d" % (png_path, spec.canvas_w, spec.canvas_h))
print(" %s" % json_path)
print(" %s ← 用浏览器打开并按 F11 全屏" % html_path)
print()
print("条带(模块尺寸以显示像素计):")
total = 0
for band in spec.bands:
total += band.modules
print(" #%d pitch=%2d px %4d×%-3d = %6d 模块"
% (band.index, band.pitch_px, band.cols, band.rows, band.modules))
print(" 合计 %d 模块" % total)
print()
print("拍摄后运行:python scripts/wedge_analyze.py --spec %s --photo <照片>" % json_path)
return 0
if __name__ == "__main__":
raise SystemExit(main())
+162
View File
@@ -0,0 +1,162 @@
#!/usr/bin/env python3
"""楔形标定工具自检:用合成相机模型端到端验证,无需真实硬件。
合成链路刻意模拟真实拍摄里会出问题的每一环:
透视倾斜 → 镜头模糊 → 传感器面积平均降采样 → 亮度梯度 + 暗角 → 噪声 → JPEG
通过判据:
1. 四个基准标能在暗背景 + 亮度不均的场景里被找到;
2. 单应矩阵反解出的放大率与合成时用的真值一致(误差 < 1%);
3. 大 pitch 条带零误码,小 pitch 条带明显劣化(曲线单调);
4. BER=1e-3 的临界点落在合理区间。
"""
import os
import subprocess
import sys
import tempfile
import numpy as np
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from wedge_common import build_spec, render # noqa: E402
import wedge_analyze as wa # noqa: E402
def warp_into_scene(canvas, scene_size, corners_dst):
"""把画布按给定四角透视贴进场景(逆映射 + 双线性)。"""
scene_w, scene_h = scene_size
src = [(0, 0), (canvas.shape[1], 0), (canvas.shape[1], canvas.shape[0]), (0, canvas.shape[0])]
inverse = wa.homography(corners_dst, src)
ys, xs = np.mgrid[0:scene_h, 0:scene_w]
pts = np.stack([xs.ravel(), ys.ravel()], axis=-1).astype(np.float64)
mapped = wa.project(inverse, pts)
mx, my = mapped[:, 0], mapped[:, 1]
inside = (mx >= 0) & (mx < canvas.shape[1] - 1) & (my >= 0) & (my < canvas.shape[0] - 1)
scene = np.full(scene_h * scene_w, 26.0, dtype=np.float32) # 暗背景 = 房间/边框
if inside.any():
sample = wa.bilinear(canvas.astype(np.float32), mapped[inside])
scene[inside] = sample
return scene.reshape(scene_h, scene_w)
def synth_photo(canvas, tilt=0.018, blur=1.1, scene_scale=1.5,
analysis_width=1920, noise=1.6, seed=7):
rng = np.random.default_rng(seed)
scene_w = int(canvas.shape[1] * scene_scale)
scene_h = int(canvas.shape[0] * scene_scale)
# 画布占场景约 92%,并带一点透视倾斜
mx = scene_w * 0.04
my = scene_h * 0.04
dx = scene_w * tilt
dy = scene_h * tilt
corners = [
(mx + dx, my + dy * 0.6),
(scene_w - mx, my),
(scene_w - mx - dx * 0.4, scene_h - my),
(mx, scene_h - my - dy * 0.5),
]
scene = warp_into_scene(canvas, (scene_w, scene_h), corners)
# 屏幕亮度梯度 + 镜头暗角
ys, xs = np.mgrid[0:scene_h, 0:scene_w]
gradient = 1.0 - 0.16 * (xs / scene_w) - 0.10 * (ys / scene_h)
cx, cy = scene_w / 2.0, scene_h / 2.0
radius = np.sqrt(((xs - cx) / cx) ** 2 + ((ys - cy) / cy) ** 2)
vignette = 1.0 - 0.18 * np.clip(radius, 0, 1.4) ** 2
scene = scene * gradient * vignette
from PIL import Image, ImageFilter
image = Image.fromarray(np.clip(scene, 0, 255).astype(np.uint8))
image = image.filter(ImageFilter.GaussianBlur(radius=blur)) # 镜头 PSF + 轻微失焦
height = int(round(scene_h * analysis_width / scene_w))
image = image.resize((analysis_width, height), Image.BOX) # 传感器面积平均
array = np.asarray(image, dtype=np.float32)
array = array + rng.normal(0.0, noise, array.shape)
photo = Image.fromarray(np.clip(array, 0, 255).astype(np.uint8))
# 合成时画布 active 宽在场景中的真值放大率
active_dst = np.hypot(corners[1][0] - corners[0][0], corners[1][1] - corners[0][1])
truth_scale = active_dst / canvas.shape[1] * (analysis_width / float(scene_w))
return photo, truth_scale
def check(condition, message):
if not condition:
raise AssertionError(message)
print(" ok %s" % message)
def main() -> int:
print("== 生成标定图 ==")
spec = build_spec(1920, 1080)
canvas = render(spec)
check(canvas.shape == (1080, 1920), "画布尺寸 1920×1080")
check(set(np.unique(canvas).tolist()) == {0, 255}, "画布为纯二值")
print("== 合成相机拍摄 ==")
photo, truth_scale = synth_photo(canvas)
with tempfile.TemporaryDirectory() as tmp:
spec_path = os.path.join(tmp, "wedge.json")
photo_path = os.path.join(tmp, "photo.jpg")
with open(spec_path, "w", encoding="utf-8") as fh:
fh.write(spec.to_json())
photo.save(photo_path, quality=92)
print("== 定位与解码 ==")
gray, _ = wa.load_gray(photo_path, 0)
markers = wa.find_markers(gray)
check(len(markers) == 4, "找到 4 个基准标")
h = wa.homography(spec.active_corners(), markers)
measured = wa.local_scale(h, spec.active_w / 2.0, spec.active_h / 2.0)
expected = truth_scale
error = abs(measured - expected) / expected
print(" 放大率 真值 %.4f / 实测 %.4f / 偏差 %.2f%%" % (expected, measured, error * 100))
check(error < 0.01, "单应矩阵放大率与真值一致(<1%%)")
rows = [wa.analyze_band(gray, spec, band, h, 17) for band in spec.bands]
print()
print(" %-9s %-11s %-9s %-11s" % ("显示pitch", "px/模块", "对比度", "误码率"))
for row in rows:
print(" %-9d %-11.2f %-9.3f %-11s"
% (row["pitch_px"], row["px_per_module"], row["contrast"],
"0" if row["ber"] == 0 else "%.2e" % row["ber"]))
print()
coarse = [r for r in rows if r["px_per_module"] >= 4.0]
fine = [r for r in rows if r["px_per_module"] <= 2.2]
check(bool(coarse) and all(r["ber"] == 0 for r in coarse),
"px/模块 >= 4.0 的条带零误码")
check(bool(fine) and max(r["ber"] for r in fine) > 1e-3,
"px/模块 <= 2.2 的条带出现明显误码")
ordered = sorted(rows, key=lambda r: r["px_per_module"])
check(ordered[0]["ber"] >= ordered[-1]["ber"], "误码率随 px/模块 增大而下降")
check(all(r["contrast"] > 0.05 for r in rows), "各条带对比度为正")
limit = wa.crossing(rows, 1e-3)
check(limit is not None and 1.5 < limit < 5.0,
"BER=1e-3 临界点落在 1.5~5.0 区间(实测 %.2f)" % (limit or 0))
print()
print("== CLI 冒烟 ==")
result = subprocess.run(
[sys.executable, os.path.join(os.path.dirname(os.path.abspath(__file__)), "wedge_analyze.py"),
"--spec", spec_path, "--photo", photo_path, "--analysis-width", "0"],
capture_output=True, text=True)
check(result.returncode == 0, "wedge_analyze.py 正常退出")
check("px/模块" in result.stdout, "输出包含结果表格")
print()
print("WEDGE SELFTEST PASSED")
return 0
if __name__ == "__main__":
raise SystemExit(main())