Emit events about file changes in Contents Manager API?

[krassowski]

Problem

Currently we use polling/infinite loops to check for file/directory status:

• frontends check for directory updates every 10 seconds
• jupyter-collaboration checks for file modifications every 1 second

This can mean that we end up hitting the Contents Manager GET too often and that users do not get updates as soon as they should. In case of out-of-band reload monitoring, this can generate many false-positive 404 logs as described in jupyterlab/jupyter-collaboration#517.

Proposed Solution

• listen to the filesystem changes
  • easy on linux with inotify (there are many Python wrappers)
  • there are good cross-platform solutions with a Python API:
    • watchdog
    • watchfiles - rust backed, in use by jupyverse
• emit events about changes in the root directory and its subdirectories to the frontend:
  • we could use jupyter-events
• add an optional method to the ContentsManager allowing to check if it supports notification events for a given directory; this is because ContentsManagers could dispatch to different sources as in HybridContentsManager
  • we may also add a dedicated REST API endpoint or instead include this information in directory response (similar to how we added hash)

Additional context

We discussed using watchdog or watchfiles in jupyter-server/jupyter_server_fileid#80 too.

[krassowski]

Since we would be adding this in a backward-compatible way with an opt-in, we could start with having just inotify wrapper that would only benefit the Linux installations; this would already be useful to all JupyterHub and enterprise deployments which are almost exclusively run on Linux machines. This would de-risk this by not requiring adding a dependency for a cross-platform support.

[davidbrochart]

I think that watchfiles is a low-risk dependency, since it tries its best at using the system's features and then falls back to polling (via the notify crate).
It has been used for several years in Jupyverse, but in the file ID service. But it makes sense to have these features in the contents service.