I had a question about the REST API. I am trying to write a python script that takes a path to a file and checks if it needs to be synced. My scenario is that my computer is offline and I want to check if a file needs to be synced. Does the REST API, or the protocol, support this? I tried checking data returned from the /rest/db/file endpoint but even when offline the sequence and blocksHash seem to match for the global and local data for a given file.
Can I use the fact that there are multiple versions in the “version” field?
What exactly do you mean with “needs syncing”?
If there is a newer version on another device, it’s very likely Syncthing doesn’t know about it while offline. Only if the index was already exchanged, but the contents not yet downloaded before you went offline.
You might have a newer local version which was not propagated to other devices. That won’t be visible as a difference between local and global hashes. You’ll need to check what versions are recorded locally for the other devices. That should also be possible via the API, but not for a single file: GET /rest/db/remoteneed — Syncthing documentation
I use the API to check that Devices are connected and that Folders are Up to Date. If a Device is unavailable my script reports the “Last Seen” date and time.
Thanks to everyone who responded; I’ll try to clarify:
By’ “needs syncing” I mean two scenarios:
I created a new file that hasn’t been synced ever.
I modified an existing file that already exists on other devices
By “offline” I mean no Internet access at all.
I understand that being offline means that my local Syncthing has no way of knowing the true state of the rest of my Syncthing devices. That’s why I was looking for essentially an “is this file dirty?” flag or API.
I tried @chaos suggestion but I’m not sure I did it correctly. Using curl to test, here’s what I did:
Made sure my computer was on the Internet.
Ran curl on the /rest/db/status?folder= endpoint and saw that globalFiles and localFiles were both 60.
Disconnected my computer from the network (it’s a desktop computer, I unplugged the Ethernet cable)
Created a new file
Ran curl again against the /rest/db/status endpoint and saw the both globalFiles and localFiles were now 61.
Modified a file
ran curl against the /rest/db/file endpoint and didn’t see any differences between globalFiles and localFiles.
I think maybe I don’t really understand what’s going on under the hood with Syncthing. Am I overthinking something?
Right so for your scenario, a file that is up to date locally and maybe not on other devices, you can figure that out in a couple of ways:
The /rest/db/file endpoint returns the info for the latest global version, and also the list of devices where it’s available. The devices not in the availability list don’t have the latest version (that you know about) and you can conclude they are out of sync.
The /rest/db/remoteneed endpoint returns the list of files needed by a remote device for a given folder.
Thank you very much for that info. I got my python script working and when it’s all finished maybe I’ll post about it here. What I’m doing is writing a plugin for the Micro text editor to show a file’s sync state in the status bar, so I’m also learning enough Lua (which Micro uses for plugins) to get it done. I’m doing my script in Python because the stripped down Lua that Micro ships doesn’t have any JSON processing libraries, but Python does.
@calmh Since my scenario is mainly “this computer is mostly offline” I decided to only check the availability list. I see in the Syncthing API docs that remoteneed is an expensive call, is that because Syncthing tries to communicate with the other devices?
I attached examples of what the sync status looks like in Micro - so far I’m pretty happy with it
No, this has nothing to do with communication (this information is available independently whether the device is online or not). Rather, it involves a bunch of database churn to compute this information. [Syncthing does not usually need this; syncthing usually works in a pull-fashion not a push-fashion, so a local device does not need to know which files a remote requires for sync to succeed. The way state is stored makes lookups for remote devices slightly more complex. For comparison, see the SQL statements for remote devices need vs local device need. However, I believe the performance remark was added long ago, prior to the SQLite migration, so the performance difference may be less severe these days.]
Thank you for your explanations on the API , I finished my plugin for the Micro text editor. Code is at johnwoltman/micro-syncthing-status: A plugin for the Micro text editor that provides a file's Syncthing status in the status bar. - Codeberg.org. What I ended up doing was writing a Python script that takes an absolute file path and checks it against the local Syncthing to see its status. The script prints out one line statuses (like “synced”, “unsynced”, “unknown”, etc). Whenever Micro needs to check the status it calls the Python script and puts the Syncthing status in the Micro status bar. It’s a bit barebones but it works for what I’m doing.
for that info. I got my python script working and when it’s all finished maybe I’ll post about it here. What I’m doing is writing a plugin for the Micro text editor to show a file’s sync state in the status bar, so I’m also learning enough Lua (which Micro uses for plugins) to get it done. I’m doing my script in Python because the stripped down Lua that Micro ships doesn’t have any JSON processing libraries, but Python does.
