Floe Architecture Reference

This page is a technical reference for contributors and advanced self-hosters. For a plain-language overview, see How It Works.

Components

Component	Runtime	Port	Purpose
Client	Next.js 16 (React 19)	3000	Browser UI, WebRTC peer (via simple-peer)
Server	Node.js (Express 5, Socket.IO 4, ws 8)	3001	Signaling broker, TURN credential issuer
CLI	Go 1.25 (Pion WebRTC v4)	-	Headless sender/receiver
TURN relay	Cloudflare Realtime TURN (floe.one) or self-hosted coturn	3478, 5349	Relays encrypted packets when a direct path fails

File data never passes through the signaling server, and only end-to-end-encrypted packets ever transit the TURN relay. All file bytes travel over encrypted WebRTC data channels between peers.

Signaling transports

The server exposes two transports. Both share the same rooms registry (Map<roomId, [peer, peer]>) so browser-to-CLI transfers work transparently.

Transport	Path	Used by
Socket.IO	`/socket.io/`	Browser (web app)
WebSocket	`/ws`	CLI

HTTP endpoints

Method	Path	Description
`GET`	`/`	Status check. Returns `{ "status": "ok", "timestamp": "..." }`.
`GET`	`/health`	Liveness probe. Returns `{ "status": "healthy", "uptime": <seconds> }`.
`GET`	`/api/turn-credentials`	Returns ICE server list. Prefers Cloudflare Realtime TURN when `CLOUDFLARE_TURN_KEY_ID` / `CLOUDFLARE_TURN_KEY_API_TOKEN` are set, then self-hosted coturn when `TURN_SECRET` is set, otherwise Google STUN only. Rate-limited to 20 requests per IP per 60 s.
`POST`	`/api/code`	Registers a short code for a room ID. Body: `{ "roomId": "<uuid>" }`. Response: `{ "code": "word-word-word" }`. TTL: 10 minutes. Rate-limited to 60 requests per IP per 60 s (shared with `GET /api/code/:code`, configurable via `MAX_CODE_REQUESTS_PER_IP`). Returns `503` when the live-code count hits `MAX_ACTIVE_CODES` (default 10000).
`GET`	`/api/code/:code`	Resolves a short code to a room ID. Response: `{ "roomId": "<uuid>" }`. Returns 404 if expired or not found. Rate-limited to 60 requests per IP per 60 s (shared with `POST /api/code`, configurable via `MAX_CODE_REQUESTS_PER_IP`).
`GET`	`/api/stats`	Returns the all-time global transfer counter: `{ "totalBytes": <integer> }`. Served from an in-memory cache (no Redis read per request).
`POST`	`/api/stats/report`	Receiver peers report bytes after a completed transfer. Body: `{ "bytes": <positive integer> }`. Response: `{ "totalBytes": <integer> }`. Rate-limited to 60 requests per IP per 60 s; rejects values that are not positive integers or exceed `MAX_REPORT_BYTES` (default 5 TB).

TURN credentials response

On floe.one the endpoint returns short-lived Cloudflare Realtime TURN credentials (turn.cloudflare.com). For a self-hosted coturn relay, when TURN_SECRET and TURN_DOMAIN are set it returns:

[
  { "urls": "stun:turn.your-domain.com:3478" },
  { "urls": "turn:turn.your-domain.com:3478", "username": "...", "credential": "..." },
  { "urls": "turns:turn.your-domain.com:5349", "username": "...", "credential": "..." }
]

When TURN_SECRET is unset:

[
  { "urls": "stun:stun.l.google.com:19302" },
  { "urls": "stun:stun1.l.google.com:19302" }
]

For self-hosted coturn, credentials use HMAC-SHA1: username = "{expiry_unix}:floeuser", credential = base64(HMAC-SHA1(TURN_SECRET, username)). Expiry is 24 hours from issuance.

Socket.IO events (browser)

Client to server

Event	Payload	Description
`join-room`	`roomId: string`	Join a room. UUID format required.
`signal`	`{ signal, target?, roomId? }`	Forward a WebRTC signal (SDP or ICE candidate) to the other peer.
`ping`	callback function	Keepalive. Server invokes the callback immediately.

Server to client

Event	Payload	Description
`room-joined`	`{ role: "sender" \| "receiver" }`	Confirms room join and assigns role.
`user-connected`	`peerId: string`	Notifies the sender that the receiver joined.
`signal`	`{ signal, sender: peerId }`	Delivers a WebRTC signal from the other peer.
`peer-disconnected`	`{}`	The other peer left the room.
`room-full`	`{}`	Room already has two peers.
`error`	`{ message: string }`	Server error.

WebSocket messages (CLI, path `/ws`)

All messages are JSON objects with a type field.

Client to server

`type`	Other fields	Description
`join-room`	`roomId: string`	Join a room.
`signal`	`signal, roomId: string`	Forward a WebRTC signal.
`ping`	-	Keepalive. Server responds with `{ "type": "pong" }`.

Server to client

`type`	Other fields	Description
`room-joined`	`role: "sender" \| "receiver"`	Role assignment.
`user-connected`	`id: string`	Receiver joined.
`signal`	`signal, sender: string`	WebRTC signal from the other peer.
`peer-disconnected`	-	Other peer disconnected.
`room-full`	-	Room already full.
`pong`	-	Response to client `ping`.
`error`	`message: string`	Server error.

Rate limiting

Limit	Value	Applies to
Connection rate	30 per IP per 60 s (configurable via `MAX_CONNECTIONS_PER_IP`)	Socket.IO connections and WebSocket `/ws` connections, shared
TURN credential rate	20 per IP per 60 s	`GET /api/turn-credentials`
Code endpoint rate	60 per IP per 60 s (configurable via `MAX_CODE_REQUESTS_PER_IP`)	`POST /api/code` and `GET /api/code/:code`, shared
Active code cap	10000 simultaneously-live codes (configurable via `MAX_ACTIVE_CODES`)	`POST /api/code`. Returns `503` when the registry is full.
Stats report rate	60 per IP per 60 s	`POST /api/stats/report`

Counters are tracked in memory (Map<ip, timestamp[]>) and cleaned every 60 seconds. Per-IP limits respond with 429. The active-code cap responds with 503 and applies globally, not per-IP, because it guards the size of the in-memory code registry.

Signaling flow

Sender calls POST /api/code with a UUID room ID to register a short code.
Sender joins the room via join-room. Server assigns role sender.
Sender prints the code and link and waits.
Receiver joins the same room via join-room. Server assigns role receiver and emits user-connected to the sender.
Sender creates a WebRTC offer and sends it via signal.
Receiver receives the offer, creates an answer, and sends it back via signal.
Both peers exchange ICE candidates via signal (trickle ICE).
WebRTC data channel opens. Signaling server plays no further part.

Data-channel transfer protocol

Once the WebRTC data channel is open, the sender runs the following sequence for each file. The CLI and browser use the same protocol and are fully interoperable.

Message types

Metadata (JSON, sender to receiver)

{
  "type": "metadata",
  "id": "<uuid>",
  "fileName": "photo.jpg",
  "fileSize": 6291456,
  "index": 1,
  "total": 3,
  "totalBytes": 11800000,
  "pv": 1,
  "pvMin": 1,
  "ver": "v1.6.0"
}

pv, pvMin, and ver carry the protocol version range and release string (see Protocol versioning). They were added in v1.6.0 and are absent on older peers, which are treated as protocol version 1. Ack (JSON, receiver to sender)

{
  "type": "ack",
  "id": "<uuid>",
  "offset": 0,
  "pv": 1,
  "pvMin": 1,
  "ver": "v1.6.0"
}

offset supports mid-file resume. In normal operation it is always 0. The ack carries the receiver’s own pv, pvMin, and ver so the sender can verify compatibility from its side. Binary chunks (raw bytes) Both the CLI and the browser size chunks adaptively to the connection’s negotiated maximum message size, capped at 256 KB. Chunk size is a local sender choice, not part of the wire protocol; receivers handle any size. End marker (JSON, sender to receiver)

{ "type": "end" }

Received confirmation (JSON, receiver to sender) After all files are complete, the CLI receiver sends:

{ "type": "received" }

This lets the sender exit cleanly instead of polling the SCTP buffer. Browser receivers do not send this; the sender waits for the data channel buffer to drain to zero. Incompatible (JSON, receiver to sender) Sent in place of the ack when the two peers’ protocol version ranges do not overlap (see Protocol versioning). It carries a human-readable reason plus the receiver’s own version range:

{
  "type": "incompatible",
  "reason": "Cannot transfer: your floe is too old for this peer. ...",
  "pv": 1,
  "pvMin": 1
}

The receiver sends this and aborts before creating any file, so the sender fails fast with a clear message instead of waiting for an ack that never arrives. Older senders that predate this message type ignore it safely.

Protocol versioning

The transfer protocol carries its own version, independent of the floe release version (the 1.x line). This lets peers on different releases interoperate, while still detecting a genuine breaking wire-format change cleanly.

Each peer advertises pv (the highest protocol version it speaks) and pvMin (the lowest it still supports) in its metadata and ack. Both are 1 today.
Two peers are compatible when their ranges overlap: max(localMin, remoteMin) <= min(localMax, remoteMax). They operate at the highest common version.
A peer that omits the fields (any release before v1.6.0) is treated as protocol version 1, so all existing peers stay compatible.
When the ranges do not overlap, the receiver sends an incompatible message and both sides print an actionable message: the older peer is told to run floe update, or to ask the other side to update.
ver is the human release string (for example v1.6.0). It is informational only, used for the optional peer-version note, and never gates a transfer.

The constants live in cli/engine/transfer/protocol.go (ProtocolVersion, MinProtocolVersion) and client/lib/transfer/protocol.ts (PROTOCOL_VERSION, MIN_PROTOCOL_VERSION). Bump ProtocolVersion only on a breaking wire change; raise MinProtocolVersion only when deliberately dropping support for an old wire format.

Backpressure

The sender pauses when the SCTP send buffer reaches the high-water mark (8 MB) and resumes when it drains below the low-water mark (4 MB). This prevents buffer overflow on large or slow transfers.

Multi-file transfers

The four-step sequence (metadata, ack, binary chunks, end) repeats for each file in order. The receiver processes files sequentially.

Room codes

Codes are three random words joined by hyphens (e.g. olive-tiger-castle), sampled from a 288-word corpus in server/words.json using crypto.randomInt (a CSPRNG, bias-free), since the code phrase is the only secret guarding a transfer. On collision (extremely rare), a fourth word is appended. Codes expire 10 minutes after registration. The number of simultaneously-live codes is capped by MAX_ACTIVE_CODES (default 10000); POST /api/code returns 503 when the cap is reached.

Global statistics counter

The homepage shows a public, all-time counter of total bytes transferred across every Floe user. Because file data never reaches the server, the counter is fed out-of-band: after a transfer completes, the receiver reports the number of bytes it received via POST /api/stats/report. Only the receiver reports (the browser receiver and the CLI receiver), so each transfer is counted exactly once. The sender never reports, and the data-channel protocol is unchanged. The global total is viewable only in the browser (GlobalStats.tsx on the homepage, polling GET /api/stats every 10 seconds). The CLI receiver contributes to the counter but never fetches or displays it. The server keeps the running total in two places:

In-memory cache (cachedTotal). Every GET /api/stats is answered from this value, so homepage polling never incurs a Redis read.
Upstash Redis (durable). Each accepted report fires an atomic INCRBY floe:bytes_total over the Upstash REST API. On startup the server seeds cachedTotal from this key, so the total survives restarts and redeploys.

If UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are not configured, the counter runs in memory only and resets to 0 on restart. The endpoint never blocks a transfer: reports are fire-and-forget on the client, and a Redis write failure is swallowed rather than surfaced. Guardrails are deliberately lightweight. A per-IP rate limit (60 reports per 60 s) and a per-report cap (MAX_REPORT_BYTES, default 5 TB) reject abuse and implausible values, but the figure is an honest best-effort metric, not a tamper-proof audited count. The stored value is a single anonymous integer: it carries no file names, no per-transfer records, and no link to any user or IP. Opt-out: Both clients support opting out of the byte-count report. The opt-out is enforced on the receiver side before the HTTP request is made; the server has no role in it.

Browser: a “Contribute to global stats” toggle on the receiver view, persisted in localStorage['floe:report-stats']. When unchecked, the fetch to /api/stats/report and the optimistic floe:bytes-reported event are both skipped.
CLI: --no-report flag on floe receive, or FLOE_NO_STATS=1 environment variable. Both gate the report by passing an empty statsURL into ReceiveFiles, which hits the existing if serverURL == "" { return } guard in reportBytesToServer.

Getting Started

Web App

CLI

Self-Hosting

How It Works

Reference

Floe Architecture Reference

Components

Signaling transports

HTTP endpoints

TURN credentials response

Socket.IO events (browser)

Client to server

Server to client

WebSocket messages (CLI, path `/ws`)

Client to server

Server to client

Rate limiting

Signaling flow

Data-channel transfer protocol

Message types

Protocol versioning

Backpressure

Multi-file transfers

Room codes

Global statistics counter

​Components

​Signaling transports

​HTTP endpoints

​TURN credentials response

​Socket.IO events (browser)

​Client to server

​Server to client

​WebSocket messages (CLI, path /ws)

​Client to server

​Server to client

​Rate limiting

​Signaling flow

​Data-channel transfer protocol

​Message types

​Protocol versioning

​Backpressure

​Multi-file transfers

​Room codes

​Global statistics counter

Components

Signaling transports

HTTP endpoints

TURN credentials response

Socket.IO events (browser)

Client to server

Server to client

WebSocket messages (CLI, path `/ws`)

Client to server

Server to client

Rate limiting

Signaling flow

Data-channel transfer protocol

Message types

Protocol versioning

Backpressure

Multi-file transfers

Room codes

Global statistics counter