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:
zhy200308
2026-08-11 09:08:37 +08:00
parent ea7b678b37
commit 4d77ba6c91
25 changed files with 3633 additions and 0 deletions
+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")