Files
QFT/docs/PROTOCOL.md
T
2026-08-12 16:40:43 +08:00

128 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# QFT protocol notes — v0.4.7
## 1. Windows → Android optical: QFT2
Active display text:
```text
QFT2:<Base45(binary-frame)>
```
Base45 is used because its alphabet fits QR alphanumeric encoding, while Android can consume a normal ZXing `Result.text`. The receiver also keeps legacy `QFT1:<base64url(...)>` parsing for old senders.
### Binary frame
```text
magic 4 "QFT2"
version 1 2
kind 1 1=MANIFEST / 2=DATA / 3=END
session 8 u64 BE
sequence 4 u32 BE
total 4 u32 BE
payloadLen 2 u16 BE
payload N
crc32 4 u32 BE over everything before crc32
```
### MANIFEST payload
```text
fileSize 8 u64 BE
chunkSize 2 u16 BE
sha256 32
fileNameLen 2 u16 BE
fileName N UTF-8
senderLen 2 u16 BE
senderDevice N UTF-8
```
### Optical parameters in v0.4.7
- one QR per display frame;
- DATA payload: **450 B**;
- QR error correction: L;
- full 4-module quiet zone;
- Windows display target: 5~60 FPS, default 45;
- synthetic representative DATA frame: 722 text chars / QR-L v15;
- theoretical payload at 60 display FPS: 27,000 B/s ≈ 26.4 KiB/s before camera misses/replay.
Sender continuously loops `MANIFEST → DATA 0..N-1 → END`. Android deduplicates by sequence number and reconstructs once all chunks are present. No reverse ACK/network channel exists for this direction.
## 2. Android optical ROI state machine
```text
ACQUIRE
center search
occasional full frame
↓ success
LOCKED
copy Y-plane ROI only
GlobalHistogram every frame
sparse Hybrid fallback
↓ finder points
smooth ROI position/size
↓ misses
expand ROI
↓ sustained misses
REACQUIRE
```
The overlay is derived from the same ROI used by the decoder, so the green/yellow box is not decorative—it reflects the actual analysis area.
## 3. Android → Windows pairing
`QFTPAIR2` remains the active pairing format from v0.3. It contains local-only session/network metadata. Android validates the pairing endpoint as a literal local/private IPv4 and binds subsequent discovery/upload to the selected local `Network`.
Discovery order includes QR hint, UDP `QFTDISC2`, gateway/direct candidates and bounded current-subnet fallback.
## 4. 扫码本地直传(Android ↔ Windows)
Parallel v2 flow:
```text
POST /qft/upload/init
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. 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.
## 6. Android → Android (`QFTPHONE2`, v0.5.0-dev4)
The sender starts an authenticated local HTTP service and encodes only session,
port, sender identity and optional dedicated-network credentials in the QR. The
file queue is fetched after pairing so QR density is independent of queue size:
```text
GET /qft/ping
GET /qft/phone/manifest
GET /qft/phone/download/<queue-index>
Range: bytes=<start>-<end>
X-QFT-Token: <one-time session>
```
The manifest contains a bounded ordered list of `name`, `size`, `sha256` and a
server-generated fixed download path. The receiver does not accept arbitrary
paths from the QR or manifest: entry `N` must use `/qft/phone/download/N`.
Android prefers a 2.4 GHz WPA2 Wi-Fi Direct group-owner AP that accepts legacy
Wi-Fi stations. An OEM P2P failure falls back to LocalOnlyHotspot, then literal
private IPv4 endpoints on the current LAN. WPA2/WPA3
credentials are distinguished in `w[2]`. The receiver reuses the existing Range
ledger, retries and SHA-256-before-publish behavior for every file, processing
items in manifest order. Phone senders use one deterministic Range worker to
avoid concurrent-read corruption in older Android document providers; desktop
senders retain up to eight workers.