@qtoggle/qui 1.20.0-alpha.2 → 1.20.0-alpha.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qtoggle/qui",
   "description": "A JavaScript UI library with batteries included.",
-  "version": "1.20.0-alpha.2",
+  "version": "1.20.0-alpha.3",
   "author": {
     "name": "Calin Crisan",
     "email": "ccrisan@gmail.com"

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qui-server"
-version = "1.20.0-alpha.2"
+version = "1.20.0-alpha.3"
 description = "A fully fledged qToggle implementation written in Python"
 authors = [
     {name = "Calin Crisan", email = "ccrisan@gmail.com"},

package/qui/__init__.py

@@ -5,7 +5,7 @@ import secrets
 
 from typing import Any
 
-from . import settings
+from . import constants, settings
 
 
 logger = logging.getLogger(__name__)
@@ -89,7 +89,11 @@ def configure(
     if not settings.package_name:
         settings.package_name = re.sub(r"[^a-zA-Z_0-9]", "", settings.name)
 
-    if settings.debug:
+    if settings.debug or constants.NON_RELEASE_VERSION_RE.match(version):
+        # A long-lived cache on static assets is only safe because the build hash changes whenever the content does.
+        # Deriving it from a version the release pipeline never stamped would make it one constant shared by every
+        # build from source, freezing whatever a browser happened to fetch first. Fall back to a per-process hash, so
+        # that restarting the server is enough to invalidate it.
         settings.build_hash = secrets.token_hex()[:16]
 
     else:

package/qui/constants.py

@@ -1 +1,9 @@
+import re
+
+
 BASE_PREFIX_HEADER = "X-Forwarded-Path"
+
+# Matches a version the release pipeline never stamped: an all-zero version, or the literal placeholder word. Spelled
+# as a pattern rather than as plain strings on purpose -- the release tooling rewrites those exact literals wherever
+# they appear in the source, which would quietly turn this into a test against the real version.
+NON_RELEASE_VERSION_RE = re.compile(r"^(?:0(?:\.0)+|unknown[-_]version)$")

package/qui/templates/qui.html

@@ -36,8 +36,8 @@
                                    background_color|urlquote }}&description={{
                                    description|urlquote }}&h={{ build_hash }}">
         {% endif %}
-        <link rel="icon" href="{{ static_url }}/img/launcher-icon-32.png">
-        <link rel="apple-touch-icon" href="{{ static_url }}/img/launcher-icon-32.png">
+        <link rel="icon" href="{{ static_url }}/img/launcher-icon-32.png?h={{ build_hash }}">
+        <link rel="apple-touch-icon" href="{{ static_url }}/img/launcher-icon-32.png?h={{ build_hash }}">
 
         {% block _meta %}
             <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

package/qui/web/tornado.py

@@ -103,6 +103,27 @@ class JSModuleMapperStaticFileHandler(StaticFileHandler):
         return False
 
 
+class CachedStaticFileHandler(StaticFileHandler):
+    # A year, rather than Tornado's ten. Long enough that nothing revalidates in practice, short enough to bound the
+    # damage should a build ever be shipped under a build hash that has already been served.
+    CACHE_MAX_AGE = 365 * 24 * 3600
+
+    def get_cache_time(self, path: str, modified: Any, mime_type: str) -> int:
+        # Tornado grants its long max-age only to requests carrying a "v" argument, while QUI stamps every asset URL
+        # with "h" instead, so by default nothing here is ever cacheable. Honour "h", but only when it matches the hash
+        # this process is currently serving: a URL left over from an earlier build names content we can no longer
+        # vouch for, and must keep revalidating.
+        if self.get_argument("h", None) == settings.build_hash:
+            return self.CACHE_MAX_AGE
+
+        return super().get_cache_time(path, modified, mime_type)
+
+    def set_extra_headers(self, path: str) -> None:
+        # The URL names an exact build, so there is nothing to revalidate even when the user reloads the page.
+        if self.get_argument("h", None) == settings.build_hash:
+            self.set_header("Cache-Control", f"max-age={self.CACHE_MAX_AGE}, immutable")
+
+
 class RedirectFrontendHandler(RequestHandler):
     def get(self) -> None:
         base_prefix = self.request.headers.get(constants.BASE_PREFIX_HEADER, "/")
@@ -192,7 +213,7 @@ def make_routing_table() -> list[URLSpec]:
         spec_list.append(
             URLSpec(
                 rf"^{static_url}/(.*)$",
-                StaticFileHandler,
+                CachedStaticFileHandler,
                 {"path": frontend_path},
                 name="static",
             )