File transfer
Chat messages can drop the oldest one to protect a slow reader; a file
transfer can't — dropping even one chunk ruins the file. So a transfer never
rides the chat pubsub path. Instead the sender copies bytes live to
whoever currently has file/recv open, with blocking backpressure, and the
server never buffers more than a small in-flight window (never the whole
file, and never to disk).
Two modes, fixed by audience size — no opt-in flag
Opening file/send claims an audience of currently-waiting receivers (those
who already have file/recv open), and which mode applies is decided purely
by how many members the channel has:
- ≤ 2 members (a private pair): strict 1:1. Claims exactly one receiver. No chunk timeout — the lone receiver sets the pace, so a slow reader just makes the transfer take longer rather than getting dropped.
- ≥ 3 members (the public channel, or any 3+ room): synchronized broadcast. Claims every currently-waiting receiver. Paced by the slowest; a receiver that stalls past a timeout is dropped so the rest can finish.
Rendezvous
Opening file/send blocks until at least one receiver is ready — this is
the rendezvous, so cat f > send naturally waits. Check who's ready first
with file/members rather than guessing:
# receiver (waits for a sender)
cat /var/tbase/everyone/file/recv > got.pdf
# sender (check file/members first, then send)
cat report.pdf > /var/tbase/everyone/file/send
There's a 2-minute safety-floor timeout on the rendezvous itself — a sender
that opens send with nobody listening at all eventually gives up rather
than hanging forever — but it's a floor, not a countdown you're expected to
race against; the ordinary flow is to watch file/members and fire once an
audience is present.
Late joiners miss the transfer. A receiver that opens file/recv after
the sender has already claimed its audience isn't included — claiming
removes receivers from the waiting set, so a transfer's audience is fixed
the moment the sender's send open returns.
Drop behavior (broadcast only)
In broadcast mode, if a receiver stalls too long accepting a single chunk
(30 seconds by default), it's dropped from the transfer so the rest can
finish. That receiver's read reports EIO (a truncated file), not a clean
EOF — so a cat ... > out on the dropped side clearly fails rather than
silently producing a partial file that looks complete. A timeout event
is posted to the channel so a bot doesn't have to poll for it.
The 1:1 path has no such timeout at all: its one receiver is the pace.
Events
Three signals ride the ordinary message path — persisted to history and
fanned out live to all three streams, exactly like a chat message:
| Event | When |
|---|---|
recv |
Someone opens file/recv and is ready to receive (readiness, not completion) |
file |
A transfer completes and moved at least one byte |
timeout |
A broadcast receiver was dropped for stalling |
Bots can watch the message stream for these instead of polling
file/members.
Why the transfer ends on Release, not Flush
A shell's cat f > send issues an intermediate dup-close (Flush) on the
file descriptor before writing a single byte, as part of wiring up the
redirect. If the transfer ended there, every subsequent write would fail
with a broken-pipe error and the receiver would get an empty file. The
transfer only actually ends on Release — the final close of the last file
descriptor — which is the only close that genuinely means "the writer is
done."
Backpressure
Each receiver has a small, bounded in-flight chunk queue (4 chunks). A sender's write blocks once a receiver's queue is full — that blocking is the backpressure that keeps the server from ever buffering more than a bounded slice of the file in memory. Raw file bytes are never sanitized — sanitization is a chat-message concept, not a file-transfer one.