Theme issue (or Firefox cache issue?)

[JulienPalard]

Today I'm seeing a theming issue:

It looks like cache problem, so I'm going to investigate step by step...

...damned, opening the Firefox console solved the issue (the no-cache were ticked), so we have a browser cache issue: users with the old theme in their local cache may get what I got.

I unticked the Firefox network console "disable cache" and tried all other translations to try to reproduce, and was able to reproduce it once:

The request done by my browser was:

curl 'https://docs.python.org/zh-cn/3.10/_static/pydoctheme.css' -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:88.0) Gecko/20100101 Firefox/88.0' -H 'Accept: text/css,*/*;q=0.1' -H 'Accept-Language: fr,en-US;q=0.7,en;q=0.3' --compressed -H 'DNT: 1' -H 'Connection: keep-alive' -H 'Referer: https://docs.python.org/zh-cn/3.10/library/functions.html' -H 'Sec-GPC: 1' -H 'TE: Trailers'

(Which, using curl, give the up-to-date file)

But got no response (first time I see this) it were "raced" (by the local cache?) I only see 882 B (raced) in the network pane, no more info.

According to https://support.mozilla.org/en-US/questions/1267945 this display mean the network won the race, which looks wrong because I have no response header and the css is the old one:

Also the size is too low to contain the whole css, so it looks like the network connection has started, bytes has been received, but the cache won the race and the network connection was interrupted.

Which I find strange is that when I refresh, all other components are requested by my browser, which all properly receive a "304 not modified" answer, but not the CSS itself:

[JulienPalard]

see: https://bugs.python.org/issue44103

[obulat]

This is a cache issue, and it is solved by using a hard refresh (or visiting from an incognito tab).
Usually, this is solved for me by the JS build tools :) We could manually add a version number/uuid or something like that to the name of the css file when we build the theme, so that the new version is loaded each time a theme is updated. GitHub, for example, has CSS filenames like github-230a1a8c439e974d9e793a2132759a84.css

[obulat]

Where would we add that? Build scripts?

[JulienPalard]

I'm wondering if it's better to use validation instead of fingerprinting.

From RFC 7234:

A stored response is considered "fresh", as defined in
Section 4.2, if the response can be reused without "validation"

then in 4.3.3:

A 304 (Not Modified) response status code indicates that the
stored response can be updated and reused; see Section 4.3.4.

So if we add an s-maxage=60 header for example, the intermediate caches (Fastly here) will still be able to HIT on every request, only revalidating once per minute, and the browsers will have to re-validate the CSS on almost every pageloads (and most of the time getting a 304 answer), instead of being allowed to use one from their cache.

So validation means more HTTP requests, but many with no response body (it takes 11ms on my laptop to get a 304 on a docs.python.org CSS) but no maintenance.

On the other hand, fingerprinting means less HTTP requests (we could even explicitly set s-maxage=31536000), but would require a modification of the CSS filename and the HTML, either at release time, either at build time.

An easy way to fingerprint would be to append the version in the stylesheet variable in theme.conf: python_docs_theme/theme.conf:stylesheet = pydoctheme.css?v=2021.5.

[hugovk]

Please see PR #108.