Filecast wire protocol (v3)

Four packet types over UDP. All multi-byte fields are big-endian.

Common header

Every packet starts with the same 10-byte header:

Field	Size	Value
magic	4	"FCST"
version	1	3
type	1	1 ANNOUNCE · 2 TRANSFER · 3 FINISH · 4 RESEND
session	4	random id chosen by the sender per transfer

The magic keeps stray UDP traffic on the port from being misparsed (and is still recognizable to a human reading a tcpdump hex dump). The session id is stamped into every packet so a receiver ignores traffic from a different (or restarted) sender. The version travels in every packet — a receiver that sees the filecast magic with an unknown version reports it once and ignores the traffic, so a version-mixed LAN fails loudly instead of silently. The header layout itself is the compatibility contract: future protocol versions keep these 10 bytes.

Packet bodies

Packet	Body (after the common header)
ANNOUNCE	file_size(4) · chunk_size(4) · sha256(32) · name_len(2) · name
TRANSFER	part(4) · length(4) · data
FINISH	—
RESEND	part(4)

Transfer sequence

1. The sender broadcasts an ANNOUNCE carrying a random session id, the total file size, the chunk size, the file's SHA-256, and its name.
2. Each receiver latches that session, creates an on-disk .part file, and clears its part registry. The chunk size is taken from the announcement, so sender and receivers never disagree about part boundaries even with mismatched --mtu settings.
3. The sender splits the file into chunk-sized pieces and broadcasts each one as a TRANSFER packet at the configured rate.
4. The sender broadcasts FINISH when all chunks have been sent.
5. Each receiver scans for missing chunks and requests them with RESEND packets.
6. The sender retransmits each requested chunk.
7. Steps 5–6 repeat until every chunk is received or the TTL expires.
8. The receiver recomputes the SHA-256 of the reassembled file and only writes it out (atomically, via a temp file and rename) if the digest matches; otherwise it reports corruption and fails.

The sender reads the source file from disk when hashing for ANNOUNCE and again when sending or resending chunks. The source file must remain unchanged for the full transfer; a concurrent modification makes the transferred bytes no longer match the announced digest.

Because every TRANSFER is addressed to the broadcast/multicast group rather than to individual receivers, the cost of a transfer does not grow with the number of receivers — and a RESEND requested by one receiver repairs that part for everyone who missed it.

Protocol versioning

A packet carrying the filecast magic with any version other than 3 is dropped, and the receiver (or the sender, for RESENDs) prints a single warning naming both versions. Packets without the magic — including packets from the pre-release v1/v2 formats, which used text markers instead of this header — are silently ignored as unrelated traffic.