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 中实际打开过。
This commit is contained in:
+118
@@ -0,0 +1,118 @@
|
||||
# QFT iOS 客户端 v0.1.0
|
||||
|
||||
三种传输方式:
|
||||
|
||||
| 方向 | 链路 | 说明 |
|
||||
|---|---|---|
|
||||
| 电脑 → 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 工程生成器
|
||||
```
|
||||
Reference in New Issue
Block a user