mkdocs serve --livereload hangs, forces to CTRL-C and restart

[squidfunk]

Whenever we use mkdocs serve --livereload, the livereload server blocks, as MkDocs waits for changes to files that can be reported back to the browser. This technique is known as long polling, and albeit we now have wide support for websockets which are a superior solution, it's a perfectly fine implementation for livereload functionality.

Blocking is implemented here:

mkdocs/mkdocs/livereload/__init__.py

Line 262 in 347c3a9

self._epoch_cond.wait_for(condition, timeout=self.poll_response_timeout)

However, sometimes when I navigate the site while working on it, MkDocs gets stuck in this condition and waits for changes to files. There are three ways to unblock it:

1. Change and save a file, so MkDocs rebuilds it and returns it to the browser
2. Press ESC in the browser to cancel the /livereload request
3. Wait for a minute until it times out

I'm not very familiar with the livereload implementation, but the problem seems to be that the server is occupied with waiting for the livereload request to finish hitting one of the conditions mentioned above, which prohibits the navigation from happening – see the loading indicator after navigating for the third time:

Ohne.Titel.mov

My testing shows that this problem can be solved by cancelling the pending /livereload request before navigation.

[oprypin]

Huh, some blockage does happen!

- What I observe only in Chromium:
need to have at least 2 tabs open and then in 1 of them wildly click back and forth between 2 nav items.
Either of the PRs prevents the problem: #3390 and #3391.

- What I observe in Firefox and Chromium:
just open 6 tabs and the 6th one will be blocked from the get-go.
Only #3391 prevents this problem. Matches the description that you write there as well.

And it's also really strange - the blockage is confined to 1 browser at a time, the other browser can look at the same server and work fine independently.
So I think it's not any race condition or bug in the Python code, instead it's the browser apparently giving up hope on the server that appears like it's hanging on all the connections.

[squidfunk]

Yes, the browser seems to have 10 active connections and refuses to open new ones. The only way to fix this is to free idle (= useless) connections, which I've proposed in #3391. #3390 fixes the problem when you use less than 6 tabs. The other problem with 6+ tabs was discovered and fixed later, which is why #3391 supersedes #3390. Nevertheless, I kept the old PR open to run it by you, because you seem to be not sure if it's okay to closing idle connections.

[squidfunk]

@oprypin could you share if you made progress on your evaluation whether merging #3391 is feasible? Feedback in #3391 by @ultrabug and @pawamoy, two other maintainers of this project, denotes that they, like me, don't regard it as a downside, and users can help themselves by installing a browser extension, if they want to reload inactive tabs.

Other than that, is there a timeline for 1.6.0? There're quite a lot of things to tackle, so I'd be interested when you hope to push out the next MkDocs release ☺️ I'm asking because I'm interested in opening more PRs when I encounter issues (as you wished: that I upstream work if useful to other themes), trying to push MkDocs forward as well, but for this to be effective, I wouldn't want to wait for bugfixes to be released 6 months after the initial PR 😉 That can be quite frustrating.

[squidfunk]

Addendum: if 1.6.0 is too far into the future, it might be a good idea to cut the 1.6.0 release into smaller releases.

[oprypin]

Merging #3391 is feasible. It's in 1.6.0 milestone and will definitely make it in.

Other things that are in that milestone will likely be pushed back, yes.

Yes please open pull requests for issues. They don't have to be held back by other things in the milestone, it's flexible.

That said, I'll be on vacation still for over a week and I don't see urgency in this anyway