Documentation / Guides

Transfers and resume

A file transfer is built to survive what usually goes wrong: a connection that drops, a change from the local network to a relay, a closed laptop, a crash. This page explains how a transfer works and what it does when something fails.

Offer, accept, send #

  1. The sender offers the file: its name, its size and a fingerprint of the whole content.
  2. The receiver applies its policy for the sending device before anything is written. By default it asks you (ask). You can set a device to auto, which accepts within limits, or to deny. The limits cover the largest accepted file, the most data held for unfinished transfers, the number of waiting offers (eight by default) and the free space that must remain on the disk (1 GiB by default).
  3. An offer that nobody answers expires after 24 hours.
  4. After you accept, the sender sends the data in chunks.

File names #

The receiver never trusts the name that the sender sends. It accepts a plain file name only and defends against names that try to leave the folder, absolute paths, reserved device names and alternate data streams on Windows, trailing dots and spaces, control characters, and collisions with files that already exist. The data is first written to a hidden temporary file in the destination folder. The final name appears only after the whole file has been checked.

What "safely stored" means #

The receiver tells the sender how far it has got only when those bytes are on disk. The order is fixed: write the data, flush the file to stable storage, record the new position in the state database, and only then acknowledge. The receiver acknowledges only bytes that it has written and flushed to stable storage, as far as the operating system and the disk keep that promise. The sender treats the receiver's position as the truth: bytes it thinks it sent beyond that position are simply sent again.

Resume #

The state of a transfer does not depend on the connection. When the devices connect again, for example through the relay after the local network was lost, or after either device restarted, they set up a new encrypted connection and the sender asks to continue. The receiver answers with the position it holds, and the data continues from there. Unfinished transfers are kept for seven days after their last activity. The free space is checked again on every resume.

A transfer through a relay is cut off after the relay's session lifetime, one hour by default, and then continues by itself. See What the relay sees for what a relay observes.

The final check #

Every byte in transit is protected by the encrypted connection. In addition the receiver computes a BLAKE3 hash of the whole file while it writes, and compares it with the one in the offer. After a restart it reads the part it already has once more to continue the hash. This catches a source file that changed between two attempts, disk errors and bugs. Only after the hashes match is the file moved to its final name, in one step.

Stopping and cancelling #

easysync transfer pause <id>
easysync transfer resume <id>
easysync transfer cancel <id>

Cancelling an offer that you receive (easysync transfer reject <id>) is the answer "no": the sender is told and does not offer the file again. A cancel is normally final. Some cancel reasons are not, for example a full quota, which makes the sender wait and try again; the error codes mark which are which.