Better describe what DownloadProgress event actually is/does

[mackinleysmith]

Hey there! Syncthing is really an amazing piece of software and I am loving the experience of working with it. I am a Go programmer and would be happy to contribute if necessary.

Something I have noticed that is causing issues for me is that the event stream does not seem to behave as the documentation would indicate when it comes to tiny files. The docs for the DownloadProgress event state:

Files/folders appearing in the event data imply that the download has been started for that file/folder, where disappearing implies that the downloads have been finished or failed for that file/folder. There is always a last event emitted with no data, which implies all downloads have finished/failed.

This is definitely the case for reasonably sized files, however, I've noticed that if I add a file that is just a few bytes (think just typing "hello" into a text file and saving it), no DownloadProgress event is fired at all. The file synchronizes just fine, but I have yet to uncover any way for my application to become aware of these tiny files other than perhaps polling the filesystem, which is what I was hoping to let Syncthing do for me.

This is on Syncthing 1.25.0 but also observed in 1.23 and 1.24. I'm running the official Docker image on Mac.

Is there some other event that I should subscribe to? I thought a bit about watching the FolderCompletion event, but contrary to what's stated in the docs, it only seems to fire for remote devices, never local.

Steps to reproduce: just set up two nodes and write a small file, then check GET /rest/events.

[calmh]

Yeah, the implications in the docs are incorrect; it's never worked precisely like that. What it actually is is a periodic snapshot of files downloading at the time the event is fired; many files may be completely processed in between such updates. You need to look at it in correlation with ItemStarted and ItemFinished, or maybe the *IndexUpdated event, to get a complete picture of what's going on.

[mackinleysmith]

Aha! That appears to be exactly what I needed. Should we perhaps update the docs to be a bit more descriptive?

[calmh]

Yes.