Better describe what DownloadProgress event actually is/does

Open
#830 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
42/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Domain
documentation

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.

Description

bug needs-triage

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.

Dominant language
Python
Stars
327
Forks
653
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from syncthing/docs

All issues in syncthing/docs

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.