Skip to content

Protocol

mrrizkin edited this page Oct 31, 2026 · 2 revisions

Protocol

QUIC on UDP 53320, discovery on UDP 53321, ALPN quicdrop/1.

Control stream

One connection per transfer, with length-prefixed postcard frames:

Frame Direction Purpose
Hello sender → receiver → sender version, device id, name, platform
Offer sender → receiver session id, FileMeta{id,name,size,hash?}
Accept / Reject receiver → sender per-file resume offset, or reason
Complete receiver → sender bytes written
Error / Bye either terminal

File data

Each file is cut into 8 MiB chunks. A pool of up to 4 workers sends each chunk over its own bidirectional stream:

  1. FileHeader{session,id,offset,size,index,count}
  2. payload
  3. FileTrailer{id,hash}
  4. FileAck{ok,hash,message}

A chunk is acked as soon as it is written; the last ack settles the whole-file digest.

Discovery

mDNS and a UDP beacon run in parallel. Both stay on the local link, so tailnet peers are addressed directly by hostname or IP instead.

Why QUIC

One stream per file removes the request queue and TCP head-of-line blocking that per-file HTTP transfers pay. A lost packet stalls one file, not the session. Byte offsets make resume free, and connection migration survives a Wi-Fi to hotspot switch.

Clone this wiki locally