@ultimat3/cli 22.3.1 → 22.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.3.1",
+  "version": "22.3.2",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.3.1",
-    "@ultimat3/admin": "22.3.1",
-    "@ultimat3/ai": "22.3.1",
-    "@ultimat3/auth": "22.3.1",
-    "@ultimat3/cache": "22.3.1",
-    "@ultimat3/core": "22.3.1",
-    "@ultimat3/db": "22.3.1",
-    "@ultimat3/entity": "22.3.1",
-    "@ultimat3/flags": "22.3.1",
-    "@ultimat3/http": "22.3.1",
-    "@ultimat3/i18n": "22.3.1",
-    "@ultimat3/jobs": "22.3.1",
-    "@ultimat3/mail": "22.3.1",
-    "@ultimat3/manifest": "22.3.1",
-    "@ultimat3/mcp": "22.3.1",
-    "@ultimat3/money": "22.3.1",
-    "@ultimat3/notify": "22.3.1",
-    "@ultimat3/policy": "22.3.1",
-    "@ultimat3/pwa": "22.3.1",
-    "@ultimat3/query": "22.3.1",
-    "@ultimat3/realtime": "22.3.1",
-    "@ultimat3/render": "22.3.1",
-    "@ultimat3/schema": "22.3.1",
-    "@ultimat3/seo": "22.3.1",
-    "@ultimat3/storage": "22.3.1",
-    "@ultimat3/testing": "22.3.1",
-    "@ultimat3/time": "22.3.1",
+    "@ultimat3/action": "22.3.2",
+    "@ultimat3/admin": "22.3.2",
+    "@ultimat3/ai": "22.3.2",
+    "@ultimat3/auth": "22.3.2",
+    "@ultimat3/cache": "22.3.2",
+    "@ultimat3/core": "22.3.2",
+    "@ultimat3/db": "22.3.2",
+    "@ultimat3/entity": "22.3.2",
+    "@ultimat3/flags": "22.3.2",
+    "@ultimat3/http": "22.3.2",
+    "@ultimat3/i18n": "22.3.2",
+    "@ultimat3/jobs": "22.3.2",
+    "@ultimat3/mail": "22.3.2",
+    "@ultimat3/manifest": "22.3.2",
+    "@ultimat3/mcp": "22.3.2",
+    "@ultimat3/money": "22.3.2",
+    "@ultimat3/notify": "22.3.2",
+    "@ultimat3/policy": "22.3.2",
+    "@ultimat3/pwa": "22.3.2",
+    "@ultimat3/query": "22.3.2",
+    "@ultimat3/realtime": "22.3.2",
+    "@ultimat3/render": "22.3.2",
+    "@ultimat3/schema": "22.3.2",
+    "@ultimat3/seo": "22.3.2",
+    "@ultimat3/storage": "22.3.2",
+    "@ultimat3/testing": "22.3.2",
+    "@ultimat3/time": "22.3.2",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/revalidated-response.ts

@@ -0,0 +1,38 @@
+// The one answer for a public file whose URL carries NO content hash: cacheable, revalidated on
+// every use, and a 304 when the bytes have not moved. `immutable` belongs to a URL that IS its
+// content (islands, styles, `asset()` files) and to nothing else — a file served immutable under a
+// name that outlives its bytes is a file no client refreshes for a year.
+
+import type { UltimateRequest } from '@ultimat3/http';
+import { etagMatches } from './runtime-storage';
+
+/**
+ * The document's own posture (`@ultimat3/render`'s `render-static.ts`), for the same reason: the
+ * URL says nothing about the bytes, so a cache may keep them and must ask before reusing them.
+ * Written as a header rather than a `CacheHint`, which has no `must-revalidate`.
+ */
+export const REVALIDATE_CACHE_CONTROL = 'public, max-age=0, must-revalidate';
+
+/**
+ * A strong validator from the bytes — xxHash32, the function `contentHash` applies to a document,
+ * taken here over bytes because an icon is not a string. Revalidating costs a request and no body.
+ */
+export function revalidatedResponse(
+  request: UltimateRequest,
+  body: string | Uint8Array,
+  contentType: string,
+): Response {
+  // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
+  // `SharedArrayBuffer`, which `Response` does not accept — `runtime-assets.ts`'s rule, verbatim.
+  const bytes = typeof body === 'string' ? new TextEncoder().encode(body) : new Uint8Array(body);
+  const etag = `"${Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0')}"`;
+  const headers = {
+    'content-type': contentType,
+    'cache-control': REVALIDATE_CACHE_CONTROL,
+    etag,
+  };
+  if (etagMatches(request.header('if-none-match'), etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(bytes, { headers });
+}

package/src/runtime-assets.ts

@@ -20,6 +20,7 @@ import { faviconRoute } from './favicon';
 import { iconPlan, iconRenderer } from './icon-assets';
 import type { PwaArtifacts } from './pwa-artifacts';
 import { pwaManifestRoute } from './pwa-artifacts';
+import { revalidatedResponse } from './revalidated-response';
 import {
   AUTHORIZED_OBJECT_CACHE,
   assertReadableKey,
@@ -41,8 +42,10 @@ import { siteAssetTable } from './site-assets';
 export const MEDIA_BASE_PATH = '/media';
 
 /**
- * A generated icon and a content-addressed variant answer forever with the same bytes, so the
- * immutable hint is a fact about the key. It is NOT a fact about this route — see `mediaCache`.
+ * A content-addressed variant answers forever with the same bytes, so the immutable hint is a fact
+ * about the key. It is NOT a fact about this route — see `mediaCache`. The generated ICONS are not
+ * content-addressed (`/icons/icon-192.png` names a size, not bytes), so they revalidate instead —
+ * see `revalidatedResponse`.
  */
 const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
 
@@ -198,8 +201,12 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
     method: 'GET',
     path: entry.outputPath,
     meta: { name: `assets.icon.${entry.spec.filename}`, auth: 'public', tags: ['assets'] },
+    // Revalidated, never `immutable` (22.3.2): the file name is the icon's SIZE, so a new
+    // `icon.png` shipped under the same URLs and every client that had seen the old one kept it for
+    // a year. The manifest and the apple-touch links name these paths, so a hashed URL would move
+    // every document and the manifest with it; a 304 is the cheaper fix.
     handler: async (request: UltimateRequest): Promise<Response> =>
-      imageResponse(await render(plan, request.pathname), 'image/png', IMMUTABLE_IMAGE),
+      revalidatedResponse(request, await render(plan, request.pathname), 'image/png'),
   }));
   // The icons above are genuinely public — they are rendered from a file committed in the app, and
   // an install prompt fetches them before anyone has signed in. `/media` is the opposite: it serves

package/src/sw-artifacts.ts

@@ -23,10 +23,13 @@ export const SW_SCOPE = '/';
  */
 export const SW_REGISTER_PATH = '/x-sw-register.js';
 
+/** How long a returning tab waits between two `sw.js` update checks — five minutes. */
+export const SW_UPDATE_INTERVAL_MS = 300_000;
+
 export interface ServiceWorkerArtifacts {
   /** `sw.js`, deterministic for identical input. */
   readonly source: string;
-  /** `x-sw-register.js`, the four lines that install it. */
+  /** `x-sw-register.js`, the lines that install it and look for its successor. */
   readonly register: string;
   /** The `<script src>` tag, appended to `PwaArtifacts.head` by every surface that serves it. */
   readonly head: string;
@@ -133,25 +136,42 @@ const staticAssets = (
     .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
 
 /**
- * Four lines, and every one of them earns it. `load` because registration competes with the page's
- * own first paint for the same network. `scope: '/'` stated rather than inferred, so a change to
- * where the file is served is a build-time refusal (`assertScope`) instead of a worker that
- * silently controls a subdirectory. The `catch` because a registration that throws in a browser
- * with service workers disabled — an incognito profile, an enterprise policy — must not take an
- * otherwise working page down with it.
+ * The registration, and every line of it earns its bytes. `load` because registration competes with
+ * the page's own first paint for the same network. `scope: '/'` stated rather than inferred, so a
+ * change to where the file is served is a build-time refusal (`assertScope`) instead of a worker
+ * that silently controls a subdirectory. The `catch` because a registration that throws in a
+ * browser with service workers disabled — an incognito profile, an enterprise policy — must not
+ * take an otherwise working page down with it.
+ *
+ * `registration.update()` when a hidden tab comes back, at most once per `SW_UPDATE_INTERVAL_MS`
+ * (22.3.2). A browser checks for a new `sw.js` on a NAVIGATION; a tab left open for days makes
+ * none, so the new worker was found only on the click that was already answered by the old one. The
+ * throttle keeps an alt-tabbing reader from re-downloading the worker on every focus, and the
+ * swallowed rejection is the offline case. It never posts `skip-waiting` and never reloads: the
+ * worker skips waiting itself (`@ultimat3/pwa`'s install block), and a reload under a reader who is
+ * typing is the one thing an update must not do — the next navigation gets the new HTML.
  *
  * EXPORTED because a static export has to put these bytes on disk BEFORE it renders, not after.
  * The file is named by every document and weighed by `measureDocumentJs`, and it used to be
  * written last, beside `sw.js` — so the measurement read a file that did not exist yet on a clean
  * output directory, and the PREVIOUS build's copy on a reused one. `sw.js` still comes last, for
  * the reason its own comment gives (its precache manifest is built from the rendered documents'
- * content hashes); this half depends on nothing but two constants, so it can and must come first.
+ * content hashes); this half depends on nothing but constants, so it can and must come first.
  */
 export const serviceWorkerRegistration = (): string =>
   `if ('serviceWorker' in navigator) {
   addEventListener('load', function () {
     navigator.serviceWorker
       .register(${JSON.stringify(SERVICE_WORKER_PATH)}, { scope: ${JSON.stringify(SW_SCOPE)} })
+      .then(function (registration) {
+        var checked = Date.now();
+        document.addEventListener('visibilitychange', function () {
+          if (document.visibilityState !== 'visible') return;
+          if (Date.now() - checked < ${SW_UPDATE_INTERVAL_MS}) return;
+          checked = Date.now();
+          registration.update().catch(function () {});
+        });
+      })
       .catch(function (error) { console.warn('service worker registration failed', error); });
   });
 }

package/src/sw-routes.ts

@@ -2,8 +2,9 @@
 // Split from the emitter because mounting is HTTP and generation is a build: `prerender.ts` writes
 // both artifacts as files and mounts nothing, and it must not have to import a route table to do it.
 
-import type { CacheHint, Route } from '@ultimat3/http';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
+import { revalidatedResponse } from './revalidated-response';
 import type { ServiceWorkerArtifacts } from './sw-artifacts';
 import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts';
 
@@ -15,9 +16,6 @@ import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts'
  */
 const SW_CACHE: CacheHint = { mode: 'private', maxAgeSeconds: 0 };
 
-/** Content-addressed in neither path, so the register script gets the favicon's hour. */
-const REGISTER_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
-
 /** `/sw.js` and `/x-sw-register.js`, mounted by `x dev` and by the container alike. */
 export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly Route[] => [
   {
@@ -42,12 +40,11 @@ export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly
     method: 'GET',
     path: SW_REGISTER_PATH,
     meta: { name: 'pwa.serviceWorkerRegister', auth: 'public' },
-    handler: () =>
-      applyCacheHeaders(
-        new Response(artifacts.register, {
-          headers: { 'content-type': 'text/javascript; charset=utf-8' },
-        }),
-        REGISTER_CACHE,
-      ),
+    // Revalidated on every load, never an hour (22.3.2). The URL carries no content hash — it is
+    // named by every document, so hashing it would re-render them all for a four-line script — and
+    // at `max-age=3600` a changed register script reached a returning visitor up to an hour late.
+    // A strong ETag makes the check a 304. Still an EXTERNAL script: see `SW_REGISTER_PATH`.
+    handler: (request: UltimateRequest) =>
+      revalidatedResponse(request, artifacts.register, 'text/javascript; charset=utf-8'),
   },
 ];