Skip to content

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 | payload

Version and capabilities are agreed inside the Noise handshake (the intersection of both sides’ capability bits wins), so nothing travels in the clear before it.

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
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.

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.

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.

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.

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.

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.