# Performance

What Side Space feels like, measured, including what it does badly. Every number here, how it was measured and on what machine.

These are the numbers people feel: how long until a file you've never downloaded starts playing, how fast a big save goes, how quickly a folder lists. We publish what we do badly too, because that's also what we're fixing next.

> [!NOTE]
> Measured on 2026-11-15 on **one machine** with 4 cores and 15 GB of memory. The server, block gateway, database and client all ran on it and talked over loopback, so **there is no real network latency in these numbers**. They show the software's own overhead. Over a real network, add the round trips and your bandwidth.

## Results

| What | Result | Notes |
|---|---|---|
| Save a new 1 GiB file | 168 MiB/s | CLI `put`; content-defined chunks, every chunk new |
| Save it again with 1 MiB changed in the middle | 1.6 s | Only the changed chunks are sent; the time is mostly local re-hashing |
| First 64 KiB of a file never downloaded | 37 ms | Linux mount (FUSE), open and read |
| Then 64 KiB near its end | 20 ms | Fetches only the chunk it touches |
| Read all of it, cold | 240 MiB/s | Sequential, from the block gateway |
| Read it all again, cached | 536 MiB/s | From the local cache |
| List a folder of 5,000 files | 132 ms | `ls` in the mount |
| Write 500 small files into the mount | 133 files/s | Returns before uploading |
| …until all 500 are versions on the server | 4.0 s | From the first write |
| Save a 1 KiB file with the SDK | p50 22 ms, p95 27 ms | Python SDK |
| Read it back | p50 7 ms, p95 8 ms | |
| Look up a path | p50 3 ms, p95 4 ms | |
| Append a line at the end | p50 67 ms, p95 72 ms | `append_text` |

## What we do badly

- **Appending a line is 3× slower than saving the whole small file again** (67 ms against 22 ms). An append looks the file up, then the server reads the old content, adds the line and chunks it all again. For small files a whole save is faster today; an append should rewrite only the last chunk.
- **Listing the same folder again isn't faster** (141 ms the second time). The mount caches folders for only a second, so every `ls` asks the server. The client already keeps a copy of the whole tree and could answer from it, kept current by push updates.
- **Re-saving a 1 GiB file after changing 1 MiB takes 1.6 s**, nearly all of it spent reading the whole file again to hash it. The mount already knows which bytes were written and could re-hash only the chunks they touch.

## Run it yourself

From a checkout of the repository, on Linux with Docker:

```sh
scripts/dev-up.sh --native && tests/e2e/bench.sh     # BENCH_MB=2048 BENCH_FILES=10000 to scale up
```

It prints the same table and writes the raw results as JSON. Server capacity under many users (the load test) is in `docs/performance.md` in the repository.