Provide a way to turn off cache busting

[nickodell]

Problem

Hello, I'm a maintainer for SciPy, and I'm looking for ways to improve the caching behavior of our documentation site.

Looking through our top URLs, the 4th most commonly requested URL is https://docs.scipy.org/doc/scipy/try_examples.json.

One reason that might be happening is that in jupyterlite_sphinx.js, this file is being requested with a ?cb= parameter. This defeats any Cache-Control headers the server might be sending.

jupyterlite-sphinx/jupyterlite_sphinx/jupyterlite_sphinx.js

Line 235 in 35cf5ff

const configFileUrl = `${configFilePath}?cb=${timestamp}`;

I would like a way to control how long the client caches the content for, using a standard HTTP header such as Cache-Control.

Proposed Solution

Provide a config option that when set, causes the client to no longer use cache busting.

Alternatively, cache busting could be disabled entirely. In our configuration, this file changes maybe on the time scale of months, and it doesn't seem like constantly reloading it provides much value to the user. You could recommend to users who want the client to not cache try_examples.json to use a standard HTTP header to control the cache behavior of that client, such as Cache-Control: no-cache.

Additional context

[agriyakhetarpal]

Hi @nickodell, I can take this! Thanks for raising this issue. I don't recall why cache busting was needed, especially since the try_examples.json file on different versions of the documentation will have different URLs, so there is inherently no benefit to the caching, as you mention. There are many options to control the try_examples behaviour already, so I would be okay with adding one more to make this toggleable.

That said, I think it was most likely added because there are occasions and use cases where the try_examples.json file can change frequently, such as in the latest documentation (for example, NumPy, where we have enabled the examples with the nightly docs). This is workaround-able in two ways: i) a hard refresh by the user, or ii) setting a timestamp such that it's cached once per day or so, with Cache-Control.

In the meantime, I think we can add a Sphinx config option, and I'll have a think on what the best approach here could be.

[nickodell]

That said, I think it was most likely added because there are occasions and use cases where the try_examples.json file can change frequently, such as in the latest documentation (for example, NumPy, where we have enabled the examples with the nightly docs). This is workaround-able in two ways: i) a hard refresh by the user, or ii) setting a timestamp such that it's cached once per day or so, with Cache-Control.

For NumPy specifically, numpy.org already sets a Cache-Control value which follows your requirements. It sets two different Cache-Control values:

• The first is the GitHub Pages Cache-Control, which is set to 600 seconds. (10 minutes)

  This isn't configurable to my knowledge.

• The second is the CloudFlare Cache-Control Browser TTL, which is set to 14400 seconds. (4 hours)

In total, a stale try_examples.json could be cached for 4.167 hours, which fits your requirements.

However, I understand the broader point that you are making. Some people are hosting their docs on infrastructure where they cannot set Cache-Control, and Cache-Control is set to an unacceptably high value. For those people, cache busting is the best alternative.

This is workaround-able in two ways: i) a hard refresh by the user, or ii) setting a timestamp such that it's cached once per day or so, with Cache-Control.

I thought of another approach.

Here's some psuedocode for an idea:

step = 600 * 1000; // try_examples timeout in milliseconds
cb = Math.round(timestamp / step) * step;

This would round cb to a lower precision. That gives a middle ground between no cache busting and cache busting on every request. This would allow you to pick a sensible default, e.g. 10 minutes, that would reduce network use out of the box without breaking existing setups.

This could also be configurable, though I don't know how it would work if we need to know this value prior to the config file being loaded. You'd know that better than I.