Better describe what DownloadProgress event actually is/does
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 327
- Forks
- 653
- PR merge metrics
- No merged PRs in 30d
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the DownloadProgress and FolderCompletion documentation and reproduce the report through GET /rest/events using two nodes and a tiny file. Compare the observed event stream with the documented behavior, then update the description to explain what DownloadProgress does for tiny files and what event clients should use; done means the behavior and fallback are unambiguous.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100