Watchman can watch an array of source paths and ping file system events to an API of your choice. Configuration attributes are defined in ~/watchman.yml.

Running Watchman

1. From Terminal, run watchman sync
2. From another Terminal, run watchman worker

Configuration YAML

This YAML is automatically created in the ~ directory. It holds all the configuration attributes for Watchman.

Attributes

source: Array of all paths Watchman should monitor
regexes: Array of all regexes Watchman should abide by (These regexes are matched with the filepath)
endpoints: Hash of each file/folder action which should ping to an API endpoint

Default File

  source:
    - /home/users/skcript
  regexes:
    - "([a-zA-Z0-9_ -/]*)/home/(\\w+)/uploads/"
  endpoints:
    file_create: "http://localhost/api/v2/files/create"
    folder_create: "http://localhost/api/v2/folders/create"
    file_move: "http://localhost/api/v2/files/move"
    folder_move: "http://localhost/api/v2/folders/move"
    file_destroy: "http://localhost/api/v2/files/destroy"
    folder_destroy: "http://localhost/api/v2/folders/destroy"

Extending

Watchman can ratelimit and selectively prevent your API calls for each file
system event. These are managed in watchman/extension.py. Each function defined
in extension.py takes path (where the file system event occurred) as input.

Ratelimiting

Watchman can ratelimit your API calls based on a unique string at 100 calls
per second.

The unique string is used to group your API calls. Modify the ratelimit()
function in watchman/extension.py to enable this. By default it returns the
root directory of the path Watchman is watching.

For example, if you are monitoring /uploads folder which has directories for
each user, like,

• /uploads/user1
• /uploads/user2
• /uploads/user3

Modify ratelimit() to return the username from the path. This way you can
ratelimit API calls based on each user.

Preventing

Watchman can selectively prevent API calls from being triggered by simply
returning a boolean for each path. Modify the prevent() function in
watchman/extension.py to enable this.

By default prevent() returns False and does not prevent any API calls.

Running Watchman as a Service

Watchman can be run as a service in your production environments. Currently,
only Linux environments are supported.

1. Download watchman_sync and watchman_worker to your in /etc/init.d folder
2. Create folder /var/run/watchman to store pids file
3. Create a /tmp if it is not present already
4. Give appropriate permissions to /var/run/watchman and /tmp (to whichever user Watchman is running from)

To start the service

  service watchman_sync start
  service watchman_worker start

To stop the service

  service watchman_sync stop
  service watchman_worker stop

To restart the service

  service watchman_sync restart
  service watchman_worker restart

Logs

All Watchman logs are maintained at /tmp/watchman.log