Do you want to notify your programs to reload when a file is updated? Maybe also need to limit the trigger frequency? That is what SyncthingHook does.
This project adds hook function to Syncthing (open source file synchronization program), but works as a standalone program. The basic principle is to constantly request the Syncthing API to get the latest events and perform specified actions. So SynchingHook is compatible with Syncthing on any platform, and can even listen to remote service.
Features:
- Single executable file, which is very easy to deploy.
- Supports many kinds of event, including Syncthing native event and extra event.
- Supports multiple filters depending on the kind of event.
- Download the executable file from the release page.
- Copy the example config file and write your version.
- Run it with profile:
./SyncthingHook --profile /path/to/config.yaml
SyncthingHook relies on configuration file (profile), which specifies events of interest and corresponding actions. You must specify the path of profile by one of the following ways (highest to lowest priority):
- Command line argument:
--profile /path/to/profile - Environment variable:
STHOOK_PROFILE=/path/to/profile
Please refer to config/config.example.sthook.yaml for the format of profile. The detailed specification is also given
through conofig/sthook.schema.json (json-schema).
The priority of different configuration methods from high to low is as follows:
- Command line arguments
- Environment variables
- Profile
The value of the high-priority configuration method will override the configuration elsewhere, even if its value is empty "".
⚠️ Warning: do not configure other items expect those listed below by command line arguments or environment as it may lead to undefined behavior and fail at any time!
Some items in profile can be configured by command line arguments or environment variables. The following table lists all of them:
| Config Item | Command Line Argument | Environment Variable |
|---|---|---|
| syncthing.url | --syncthing.url |
STHOOK_SYNCTHING_URL |
| syncthing.apikey | --syncthing.apikey |
STHOOK_SYNCTHING_APIKEY |
For example：
./sthook --syncthing.url http://localhost:8384 --syncthing.apikey aaabbbccc| Event | Description |
|---|---|
| st:ConfigSaved | Syncthing doc |
| st:DeviceConnected | Syncthing doc |
| st:DeviceDisconnected | Syncthing doc |
| st:DeviceDiscovered | Syncthing doc |
| st:DevicePaused | Syncthing doc |
| st:DeviceResumed | Syncthing doc |
| st:DownloadProgress | Syncthing doc |
| st:Failure | Syncthing doc |
| st:FolderCompletion | Syncthing doc |
| st:FolderErrors | Syncthing doc |
| st:FolderPaused | Syncthing doc |
| st:FolderResumed | Syncthing doc |
| st:FolderScanProgress | Syncthing doc |
| st:FolderSummary | Syncthing doc |
| st:FolderWatchStateChanged | Syncthing doc |
| st:ItemFinished | Syncthing doc |
| st:ItemStarted | Syncthing doc |
| st:ListenAddressesChanged | Syncthing doc |
| st:LocalChangeDetected | Syncthing doc |
| st:LocalIndexUpdated | Syncthing doc |
| st:LoginAttempt | Syncthing doc |
| st:PendingDevicesChanged | Syncthing doc |
| st:PendingFoldersChanged | Syncthing doc |
| st:RemoteChangeDetected | Syncthing doc |
| st:RemoteDownloadProgress | Syncthing doc |
| st:RemoteIndexUpdated | Syncthing doc |
| st:Starting | Syncthing doc |
| st:StartupComplete | Syncthing doc |
| st:StateChanged | Syncthing doc |
| ex:LocalFolderContentChangeDetected | Based on st:LocalChangeDetected, with file path matcher. |
Unless otherwise noted, the following parameters apply to all events:
| Name | Type | Default | Description |
|---|---|---|---|
| tolerance | int64 | 0 | How long to wait before triggering this event (ms). Typically used to get only the latest event. 0 means no waiting. |
| cooldown | int64 | 0 | The maximum frequency in millisecond that this event can be triggered. 0 indicates no limitation. |
Example:
hooks:
- event-type: "st:FolderCompletion"
parameter:
tolerance: 500
cooldown: 3000This event based on st:LocalChangeDetected. It will be triggered only when the folder id equals the given one and the
file belongs to the given path (equal or subdirectory). Path pattern / matches all events.
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
| st-folder | string | Folder-id in Syncthing. Cannot be omitted. | |
| path | string | / |
Path to the target directory, must start with /. |
The only action type currently supported is exec. However, since it can run any command, you may do whatever you
want (e.g. run a python script).
Example:
action:
type: "exec"
cmd: [ "python", "do.py" ]
# cmd: [ "python do.py" ] BAD!Please note:
- The first element of
cmdmust be the program, which means you can't put parameters in it. - SyncthingHook won't wait for the command to return. So it may execute the command (triggered by next event) while the previous one is still running.