How ecoos3 works

ecoos3 sends files directly between two browsers using WebRTC, the same technology browsers use for video calls. This page explains what happens along the way, including the parts that don’t always work.

Both browsers exchange setup messages through the signaling server, then send file data directly to each other.Signaling serverYour browserTheir browsersetup messages onlyfile data, encrypted
The server helps the browsers find each other. It never carries the file.

Why your files don’t touch a server

Once two browsers are connected, ecoos3 opens WebRTC data channels between them. These are direct connections: packets go from one computer to the other over the internet, or over your local network if you’re both on it. File contents, file names and chat messages all travel this way. There’s no server in the data path to store or read them.

Data channels are always encrypted with DTLS, which browsers require for WebRTC. The keys are checked using fingerprints exchanged during setup, which passes through the signaling server, so as with most WebRTC apps you’re trusting that server not to tamper with setup messages.

What the signaling server actually does

Two browsers can’t connect until each knows how to reach the other, and they have no way to talk before that. The signaling server solves this. When you create or join a room, your browser opens a WebSocket to it, and the server forwards a few kinds of message between people in the same room:

  • An offer and an answer (SDP) — each side describing the connection it wants to set up.
  • ICE candidates — network addresses where each browser might be reachable.
  • Room updates — who joined and who left.

The server passes these along and doesn’t store them. It can see the room code, a random ID for each browser, the name you typed, and the network addresses inside the ICE candidates. It never sees file contents, file names or messages, because those only exist on the direct connection.

How two browsers find each other

Most computers sit behind a router that shares one public IP address between every device on the network — this is NAT, network address translation. Your computer’s own address, like 192.168.1.20, means nothing to someone outside your network.

So each browser asks a public STUN server a simple question: “what address do you see me coming from?” The answer is the public address and port your router assigned. Each browser sends its list of possible addresses to the other through the signaling server, and both start sending test packets to each other’s addresses at the same time. Each router sees outgoing traffic to the other side and lets the replies back in. This is often called hole punching, and the first pair of addresses that works becomes the connection.

If you’re both on the same network, your local addresses work directly, which is usually much faster than going out to the internet and back.

Why some networks fail

Hole punching relies on the router keeping the same public port for a connection, whoever you’re talking to. Some routers don’t: a symmetric NAT picks a new public port for every destination. The port the STUN server saw is then not the port the other browser needs, so the test packets never line up. If only one side is behind a symmetric NAT, the connection often still works; if both are, or if a firewall blocks the UDP traffic WebRTC uses, it doesn’t.

The standard fix is a TURN relay: a server that forwards the encrypted traffic between the two browsers. It still can’t read the data, but every byte passes through it, which makes it expensive to run for large files. ecoos3 doesn’t have a relay yet; relay support is planned.

When you open the app, ecoos3 runs a quick check on your network and shows a warning if it looks restrictive. It’s an estimate rather than a guarantee: whether a connection works also depends on the other person’s network.

How a file is sent

Nothing arrives until the receiver presses Accept and picks where to save the file. The sender then reads the file in 64 KB chunks and puts a small index number in front of each one. Because every chunk says where it belongs, the channel doesn’t need to deliver them in order, and the receiver writes each chunk straight to its position in the file on disk using the browser’s File System Access API. The file is never held in memory as a whole, which is why size isn’t limited by RAM.

The sender also watches how much data is waiting in the connection’s buffer and pauses when it fills up, so a fast disk doesn’t pile data on top of a slower network.

How resume works

A row of sixteen chunks. Most of the first ten have arrived; chunk 4 and chunks 10 to 15 are missing and will be requested again.chunk 0chunk 15receivedmissing — requested again on reconnect
One bit per chunk. Resuming only asks for the empty ones.

The receiver keeps a bitmap: one bit per chunk, switched on when that chunk is written. Every few seconds the bitmap is saved in the browser’s IndexedDB storage, along with the file’s name, size and where it’s being saved.

Two identifiers let a transfer be recognised later. Each browser has a random ID that stays the same between visits, and each file gets a fingerprint: a SHA-256 hash of its size together with its first and last megabyte. When the same two browsers connect again — in any room — each tells the other which unfinished transfers it has, and matching fingerprints line up.

When you click Resume, the receiver reopens its partial file (the browser asks for permission), reads the bitmap, and asks the sender for exactly the missing chunk numbers. The sender reads just those parts of the file and sends them. Before it does, it checks the file still has the same fingerprint, so an edited or replaced file isn’t mixed in. The fingerprint samples the file rather than hashing all of it, so it catches a replaced file or one whose size changed, but not an edit that only touches the middle.

Progress is only saved when both people have Save progress for resume switched on, and unfinished transfers are cleared after 30 days.

What happens if the connection drops

Once two browsers are connected, file data goes straight between them, and the signaling connection isn’t doing anything — so it closes. If the direct connection between the two browsers later fails, each one reopens a connection to the signaling server on its own and rejoins using the same room code. If that room had since been cleaned up, it’s recreated, so the original code keeps working and anyone else holding it can still join.

The two browsers then reconnect to each other, and the transfer continues from where it stopped using the bitmap described above: the receiver already knows which chunks it has, so only the missing ones are sent again. An interruption at 80% resumes at 80%.

This is automatic and separate from clicking Resume. Automatic reconnection handles a connection failing while both tabs stay open — there’s nothing to click. Resume is for after a reload, or picking up a transfer again days later, when the two browsers have to find each other from scratch.

Limits worth knowing

  • Receiving needs the File System Access API, which today means a Chromium browser.
  • Both people must be online at the same time for a transfer to progress.
  • Reconnecting isn’t instant — the browser can take a minute or so to decide a connection is dead before it tries again.
  • If a device is closed entirely, the transfer waits until it’s reopened and resumed by hand.
  • A room holds up to four people. Every pair has its own direct connection, so sending to three people splits your upload between them.
  • Each sender sends one file at a time.
  • Speed is limited by the slower of the two connections.
  • Resuming needs the same two browsers; clearing site data starts over.

Try ecoos3