Ferry Link
Everything between the computer and the phone travels over one TCP connection, encrypted
with Noise, as length-prefixed frames. The crate is ferry-link, and the same code runs on
both sides.
frame = length:u32 | kind:u8 | id:u32 | payloadVersion and capabilities are agreed inside the Noise handshake (the intersection of both sides’ capability bits wins), so nothing travels in the clear before it.
Frames
Section titled “Frames”| Kind | Direction | Payload |
|---|---|---|
OPEN |
PC → phone | Port and host (a name or an address) |
OPENED / REFUSED |
phone → PC | Result, or an error code |
DATA |
both | Bytes of a stream |
CREDIT |
both | How many more bytes the peer may send |
FIN / RESET |
both | Half-close and abort |
DGRAM |
both | A UDP datagram; the destination only on a flow’s first one |
DGRAM_CLOSE |
PC → phone | The PC ended a datagram flow |
DNS_QUERY / DNS_ANSWER |
PC → phone → PC | A raw DNS message, resolved on the phone’s network |
PING / PONG |
PC → phone → PC | Target and timeout, then round trip or failure |
STATUS |
phone → PC, every second | Upstream online, transport, signal, battery |
KEEPALIVE |
PC → phone | Sent after a second with nothing else to send |
REPORT |
phone → PC, every 10 s | What the link costs the phone |
DEVICE |
phone → PC, once | Static facts about the phone |
A TCP connection through Ferry
Section titled “A TCP connection through Ferry”sequenceDiagram participant App as App on the PC participant Stack as ferry-pcstack participant Phone as ferry-phone participant Site as example.com App->>Stack: SYN (captured by the adapter) Stack->>Phone: OPEN id=7, example.com:443 Phone->>Site: connect() as an ordinary app Site-->>Phone: connected Phone-->>Stack: OPENED id=7 Stack-->>App: SYN-ACK App->>Stack: data Stack->>Phone: DATA id=7 Phone-->>Stack: CREDIT id=7 (window reopened) App->>Stack: FIN Stack->>Phone: FIN id=7
One round trip on the link replaces SOCKS5’s extra handshake per connection.
Flow control
Section titled “Flow control”Each stream starts with a 16 KB window, and the receiver returns CREDIT as the application
reads. A busy stream’s window doubles, up to 256 KB, while the link’s 16 MB budget has room,
so a peer can never make the other side hold more than that. One slow download can’t stall
the others. This is yamux’s model, kept small and specific to Ferry.
Datagrams and DNS
Section titled “Datagrams and DNS”A UDP flow is opened once with its destination; later datagrams carry only the flow id. Calls and games ride on this. DNS has frames of its own: the computer forwards the raw query, and the phone resolves it on its own network.
Liveness
Section titled “Liveness”Both directions are always talking: the phone sends STATUS every second, and the computer
sends KEEPALIVE when it has had nothing else to send for a second. After 3 seconds of
silence the link shows as degraded; after 8 it closes itself and the computer redials at
once. The computer learns “the phone has no internet” from STATUS in about a second,
without probing any outside address.
Resumption
Section titled “Resumption”After a short dropout the computer resumes the session against the same phone key. UDP flows survive, so a call can continue; TCP connections end, and apps reconnect as they would after any network change. A new pairing is never used as a fallback.
Why TCP and not QUIC
Section titled “Why TCP and not QUIC”QUIC was measured against TCP over real Wi-Fi Direct. TCP carried 187–251 Mbit/s at 13–19% of the phone’s CPU; QUIC used 5–9× the CPU per Mbit for 0.45–0.72× of the goodput, and with the screen off it was held at 72 Mbit/s with one core at 100%. TCP with our own multiplexer won.