A sound implementation does not ask users to refresh until it works. Each phase has an input, an output, a timeout, and a terminal state. Ten thousand 4 KB files are small in bytes but expensive in metadata, state changes, hash setup, and storage transactions. The bottleneck becomes per-item overhead rather than the link.
File transfer must reconcile sender offsets, durable receiver writes, chunk integrity, and terminal state on both peers. A full progress bar may show queued bytes, not a complete usable file.
Define the system contract first
Write the following choices as reviewable rules instead of scattering them across callbacks and UI conditions. Explicit rules make scaling, compatibility, and diagnosis less dependent on guesswork.
- Send one batch manifest and acknowledge groups instead of one round trip per file.
- Offer bundling without compression for a continuous stream while preserving path and digest metadata.
- For unbundled files, use bounded concurrency and fair scheduling so small-file floods do not block control.
Small-file optimization reduces fixed overhead rather than merely enlarging chunks. Batched manifests, bounded concurrency, and indexed bundles balance speed and recoverability.
What can break that contract
An abnormal path is more than an error banner. It decides how in-flight work stops, how the peer learns the outcome, what residue remains, and whether the next operation inherits it.
- Concurrency grows with file count, opening enough reads and hash jobs to crash the browser.
- One failed bundled entry forces full retransmission, making recovery worse than individual files.
- The UI redraws every file for every chunk until rendering costs more than transfer.
How to test the contract line by line
Build golden cases from known inputs and controlled faults, then align production metrics with those results. Verification extends to production only when signals detect the same degradation early.
- Compare one large file with one hundred thousand small files of equal total bytes across CPU, transactions, and control delay.
- Corrupt one bundled entry and verify the index isolates and repairs only necessary ranges.
- Cancel one file, one batch, and the whole task, proving scope is respected.
The release standard is practical: the normal path is fast, abnormal paths converge, recovery never overrides an explicit user decision, and operators can diagnose faults from limited, privacy-safe evidence.