Configurable file watcher debounce duration in live-reload mode

[ccjmne]

• Introduce -d --debounce <VALUE> flag for serve
• Document serve's --debounce flag in cli-usage.md

Let the file watcher use a configurable debounce value.

This commit preserves the (until now hard-coded) 1-second debounce value
as the default, but adds a new flag for the serve command, which lets
the user configure a debounce duration for consecutive rebuilds in watch
mode.

Closes #2937.

[ccjmne]

Something's not quite right: you shoudn't use -d0, that'd get your CPU burning up. One millisecond is fine, though.
What do you reckon is best? Setting a minimum value for the debounce flag to 1, or sneakily passing 1 along to the watcher-debouncer when the user chooses 0?

[nicolandu]

My advice would be to error, or at least warn, in the case of -d0. Silently changing configuration from what the user expects is probably not a good idea.

[ccjmne]

I like that as well, I'll get right on it.

[nicolandu]

Also, it would be good to document the flag (-d/--debounce) more thoroughly, such as by specifying its unit (milliseconds) in the docs.

[ccjmne]

Done, and done.

I looked into the reason for the excessive CPU load with --debounce 0, and it seems to be a limitation of the debouncing library: it's not made to work efficiently with 0 there—which is reasonable.

The "ideal" resolution may have been to somehow bypass using the debouncer altogether if the user passes --debounce 0, but frankly, having another dependency (the debouncing library doesn't expose its underlying "watcher)" and the extra code to handle that special case seems like too much of a maintenance burden to pay for this little of a nitpick.

My puny mammalian brain can't really feel the difference between 1ms and 0ms anyways ;)

[Keats]

The code looks fine, i'm just a bit hesitant about adding more flags to the CLI

[Keats]

In practice though, is it actually worth it to have a debounce value that small? Zola is going to rebuild the thing every few (or even just every) keystrokes which seems a bit wasteful

[ccjmne]

In practice though, is it actually worth it to have a debounce value that small? Zola is going to rebuild the thing every few (or even just every) keystrokes which seems a bit wasteful.

Hang on a second: does Zola watch as you type, not as the files are changed on disk?

Surely that can't be, without some curious integration with your text editor. Or are you actually reflecting the changes back to your filesystem as you type?
On my end, using Vim, the live-rebuild watcher definitely only reacts when I commit my buffer to the disk, though I might be missing something huge and obvious: sorry if that's the case :)

TL;DR: What I'm observing is:

1. zola serve
2. type-type-type: nothing happens
3. <Ctrl-S> (or :w, you know what I mean)
4. one second goes by, then
5. zola rebuilds and reloads

With zola serve -d1, nothing changes but the removal of step 4; but I may be missing something.

[Keats]

Surely that can't be, without some curious integration with your text editor. Or are you actually reflecting the changes back to your filesystem as you type?

No but with auto-saving editors it might happen frequently enough

[ccjmne]

No but with auto-saving editors it might happen frequently enough

Oh alright. I would presume then that the debouncing happens at that level, where the editor wouldn't save your file to disk after each keystroke.

For myself, waiting one full second after I've virtually instructed Zola to rebuild my site is a bit of an irritation.
It's probably vastly exacerbated by the fact I'm still in the "build up the theme" phase, where I tweak styles and want to iterate rapidly: I can see how authoring content needs much less reactivity :)

[nicolandu]

I just had a thought: what if we lower the debounce from 1000 ms to a lower value, say 50 or 100 ms, and ditch the complexity of an extra CLI flag?

[Keats]

I've just tried in rustrover with a 50ms debounce and I do often get multiple builds in the same second (mostly when using backspace) so that would be a lot of wasted cpu for my own usecase :/

[ccjmne]

@Keats, I think we'd all—but you primarily—benefit from understanding what is going on.

It's quite possible that you've configured something to commit changes, as you type, back to your filesystem (exceedinly?) often, apparently with some throttle or debounce: naively, I'd say that's an undesirable configuration.

Regardless, I truly don't think that your specific, undiagnosed set-up being quite curious should be the sole blocker that prevents a 3ms rebuild to take anything less than 1003ms.

--

Here's the isolated, minimal, complete, verifiable example I could prepare. You only need Docker:

1. Start with a fresh, empty distribution, install cargo, git, and some text editor, compile zola with the --debounce flag, serve the test site:

docker run --rm -it --network=host --name=zola archlinux sh
pacman -Sy --noconfirm git vim rust cargo
git clone --depth 1 --branch configurable-watcher-debounce https://github.com/ccjmne/zola
cd zola; cargo build --release
cd test_site; ../target/release/zola serve -fd1

On your local machine, navigate to localhost:1111.

2. Inside the Docker container, edit something like templates/index.html and see it work splendidly, only taking a handful of milliseconds to rebuild and republish each time you purposely write your file:

docker exec -it zola vim /zola/test_site/templates/index.html

--

Zola truly is a pretty neat tool, thank you for that!

Now if you still think that, in principle, waiting around is what is ultimately desirable for the project, that's acceptable. If you truly suspect that any (let alone a very large) debouncing is required, I'm not entirely convinced, and can't quite arrive to the same conclusion through my (admittedly modest) test.

[ccjmne]

@Keats,

My previous message sounded harsh. If you really do want to figure out what I presume is writing to your disk surprisingly (unnecessarily?) often, I'd be genuinely curious and willing to help and find out.

If you want another parir of investigative eyes, I'd be happy to try and help!