DocsSource

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.