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

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.4",
   "author": {
     "name": "Calin Crisan",
     "email": "ccrisan@gmail.com"
@@ -12,6 +12,7 @@
   "keywords": [],
   "license": "Apache-2.0",
   "dependencies": {
+    "@babel/runtime": "^7.29.7",
     "jquery": "^3",
     "jquery-mousewheel": "*",
     "jquery-ui": "^1",
@@ -22,6 +23,7 @@
     "@babel/core": "^7.27.0",
     "@babel/eslint-parser": "^7.27.0",
     "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/plugin-transform-runtime": "^7.29.7",
     "@babel/preset-env": "^7.27.0",
     "babel-loader": "^8",
     "css-loader": "^3",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qui-server"
-version = "1.20.0-alpha.2"
+version = "1.20.0-alpha.4"
 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/manifest.json

@@ -7,18 +7,18 @@
     {% if theme_color -%}"theme_color": "{{ theme_color }}",{%- endif %}
     {% if background_color -%}"background_color": "{{ background_color }}",{%- endif %}
     "icons": [
-        {"src": "{{ static_url }}/img/launcher-icon-16.png",  "sizes": "16x16",   "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-32.png",  "sizes": "32x32",   "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-36.png",  "sizes": "36x36",   "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-48.png",  "sizes": "48x48",   "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-64.png",  "sizes": "64x64",   "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-72.png",  "sizes": "72x72",   "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-96.png",  "sizes": "96x96",   "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-144.png", "sizes": "144x144", "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-192.png", "sizes": "192x192", "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-256.png", "sizes": "256x256", "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-384.png", "sizes": "384x384", "type": "image/png"},
-        {"src": "{{ static_url }}/img/launcher-icon-512.png", "sizes": "512x512", "type": "image/png"}
+        {"src": "{{ static_url }}/img/launcher-icon-16.png?h={{ build_hash }}",  "sizes": "16x16",   "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-32.png?h={{ build_hash }}",  "sizes": "32x32",   "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-36.png?h={{ build_hash }}",  "sizes": "36x36",   "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-48.png?h={{ build_hash }}",  "sizes": "48x48",   "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-64.png?h={{ build_hash }}",  "sizes": "64x64",   "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-72.png?h={{ build_hash }}",  "sizes": "72x72",   "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-96.png?h={{ build_hash }}",  "sizes": "96x96",   "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-144.png?h={{ build_hash }}", "sizes": "144x144", "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-192.png?h={{ build_hash }}", "sizes": "192x192", "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-256.png?h={{ build_hash }}", "sizes": "256x256", "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-384.png?h={{ build_hash }}", "sizes": "384x384", "type": "image/png"},
+        {"src": "{{ static_url }}/img/launcher-icon-512.png?h={{ build_hash }}", "sizes": "512x512", "type": "image/png"}
     ],
     "start_url": ".",
     "display": "standalone"

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/templates/service-worker.js

@@ -99,7 +99,9 @@ function sendClientMessage(message, uncontrolled = false) {
 }
 
 function shouldCacheRequest(request) {
-    return request.url.match(cacheURLRegex) && (request.method === 'GET')
+    /* Match on the path alone. Every asset URL carries a ?h=<build hash> query, which an extension pattern anchored
+     * at the end of the string would never match. */
+    return new URL(request.url).pathname.match(cacheURLRegex) && (request.method === 'GET')
 }
 
 function shouldCacheResponse(response) {
@@ -113,19 +115,21 @@ self.addEventListener('activate', function (event) {
 
     function deleteCache(name) {
         logDebug(`deleting cache ${name}`)
-        caches.delete(name)
+        return caches.delete(name)
     }
 
     event.waitUntil(
-        /* Become available to all pages */
-        self.clients.claim().then(function () {
-            /* Clear all caches starting with our app name */
+        Promise.all([
+            /* Become available to all pages */
+            self.clients.claim(),
+            /* Clear the caches left behind by other builds -- but not the one this build is about to fill, whose
+             * name also starts with the app name */
             caches.keys().then(function (cacheNames) {
                 return Promise.all(cacheNames
-                                   .filter(name => name.startsWith(`${appName}-`))
+                                   .filter(name => name.startsWith(`${appName}-`) && name !== cacheName)
                                    .map(name => deleteCache(name)))
             })
-        })
+        ])
     )
 })
 
@@ -138,8 +142,9 @@ self.addEventListener('fetch', function (event) {
     }
 
     let url = event.request.url
-    /* Ensure URL has build hash */
-    if (!url.includes('?h=') && !url.includes('&h=')) {
+    let requestedHash = new URL(url).searchParams.get('h')
+    if (requestedHash == null) {
+        /* Ensure URL has build hash */
         if (url.includes('?')) {
             url += `&h=${buildHash}`
         }
@@ -147,6 +152,12 @@ self.addEventListener('fetch', function (event) {
             url += `?h=${buildHash}`
         }
     }
+    else if (requestedHash !== buildHash) {
+        /* A URL left over from another build, most likely requested by a page that was already open when this worker
+         * took over. Send it to the network untouched rather than filling this build's cache with a key that nothing
+         * is going to ask for again. */
+        return
+    }
 
     let request = new Request(url, event.request)
 

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",
             )

package/webpack/webpack-common.js

@@ -211,8 +211,24 @@ function makeJSRule({type, appFullPath}) {
             {
                 loader: 'babel-loader',
                 options: {
-                    presets: ['@babel/preset-env'],
-                    plugins: ['@babel/plugin-proposal-class-properties']
+                    /* The entry is a <script type="module"> with no nomodule fallback, so a browser that cannot run
+                     * ES modules never gets this far. Targeting them is the honest floor -- and it is the floor the
+                     * markup already enforces, so it drops no browser that could previously run the app.
+                     *
+                     * Set here rather than in a .browserslistrc because the build compiles QUI's own sources from a
+                     * sibling checkout outside the app's tree, where browserslist config resolution would depend on
+                     * the working directory, and because it keeps one source of truth for both repos. */
+                    presets: [['@babel/preset-env', {targets: {esmodules: true}}]],
+                    plugins: [
+                        '@babel/plugin-proposal-class-properties',
+                        /* Import the remaining helpers from a shared runtime rather than inlining a copy of
+                         * each into every module that needs one. useESModules defaults to false, which would pull
+                         * the CommonJS builds of those helpers and cost webpack its tree shaking and module
+                         * concatenation across them; "auto" takes the answer from the bundler's own declared
+                         * capability instead of asserting it here. (Babel 8 drops the option and always
+                         * auto-detects, so it comes out again with that upgrade.) */
+                        ['@babel/plugin-transform-runtime', {useESModules: 'auto'}]
+                    ]
                 }
             }
         ]