Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

18.2 KB
Raw Blame
/* PortOS service worker — offline app-shell + low-bandwidth asset caching.
 *
 * This is the modern replacement for the long-deprecated AppCache manifest.
 * It caches the built app shell (index.html) and the content-hashed JS/CSS
 * chunks so PortOS loads instantly on repeat visits, keeps working when the
 * server is briefly unreachable (flaky Tailnet links), and stops re-pulling
 * megabytes of vendor JS on every navigation over a slow connection.
 *
 * Design constraints specific to PortOS:
 *   - `/api/*`, `/socket.io/*` and `/data/*` are NEVER cached. They are
 *     real-time / large / user-specific — the app is inherently online for
 *     data, only the *shell* is made offline-capable here.
 *   - Vite emits content-hashed filenames under `/assets/`, so those are
 *     immutable and safe to serve cache-first. A new build produces new
 *     filenames (cache miss → fetched fresh), so cache-first never pins stale
 *     code. The existing build-id / stale-chunk-reload machinery
 *     (server/lib/buildId.js, client/src/utils/staleChunkReload.js) still
 *     handles the "server rebuilt while a tab was open" case.
 *   - Navigations are network-first so a fresh build is always picked up when
 *     online; the cached shell is the offline fallback only.
 *
 * Bump CACHE_VERSION to invalidate every cache (e.g. when these strategies
 * change). Changing this file's bytes is itself what triggers the browser to
 * install the updated worker.
 *
 * Offline scope (accepted limitation, by design): the install/navigation
 * precache covers the app shell + its ENTRY assets (the boot chunk, its
 * modulepreload deps, CSS). Lazy route chunks are cached on demand the first
 * time they load through the controlling SW (cache-first), so a route the user
 * has visited online works offline afterward — but a route visited ONLY during
 * the very first, pre-registration page load (before window.load registered the
 * SW) has an uncached chunk, so an offline reload of exactly that route boots
 * the shell but can't render the route until it's visited online once more.
 *
 * Closing this fully would need a build-time precache manifest (workbox /
 * vite-plugin-pwa) that enumerates every dist chunk and precaches them at
 * install. That is deliberately NOT done, because:
 *   - Precaching all chunks upfront spends first-visit bandwidth on routes the
 *     user may never open — directly contrary to this SW's low-bandwidth goal.
 *   - PortOS is single-user; the mitigation ("visit each route online once")
 *     costs the one user a single online load, not a support burden.
 *   - It would replace the dependency-free hand-rolled shell cache with a build
 *     plugin, or add a build step to emit an asset-manifest — cost the payoff
 *     doesn't justify for a one-online-load-per-route gap.
 * If the gap ever bites in practice, revisit the asset-manifest option then.
 */

const CACHE_VERSION = 'v1';
const SHELL_CACHE = `portos-shell-${CACHE_VERSION}`;
const ASSET_CACHE = `portos-assets-${CACHE_VERSION}`;
const STATIC_CACHE = `portos-static-${CACHE_VERSION}`;

// No font cache: the webfonts are self-hosted under /fonts/ (see
// src/index.css), so they are same-origin and already covered by
// STATIC_PATH_RE below. The old `portos-fonts-*` cache existed only for the
// public font CDN this no longer talks to; leaving it out of CURRENT_CACHES
// means the activate-time cleanup deletes whatever is left in it.
const CURRENT_CACHES = new Set([SHELL_CACHE, ASSET_CACHE, STATIC_CACHE]);

// Stable key the offline shell is stored under, independent of the request URL
// (every SPA navigation resolves to the same index.html on the server).
const SHELL_KEY = '/index.html';

// Last-resort HTML for a failed navigation when NEITHER the offline shell nor
// an exact-URL cache entry exists (e.g. the very first install, before the
// precache has committed, combined with a flaky-link fetch failure). A bare
// `Response.error()` here is an opaque network-error the browser can't render
// — a dead tab with no way to recover, since the SW sits upstream of React
// ever mounting. This is a minimal, dependency-free page so it needs no fetch
// of its own to render.
const OFFLINE_FALLBACK_HTML = `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>PortOS — Connection failed</title>
<style>
  body { margin: 0; display: flex; align-items: center; justify-content: center; min-height: 100vh;
    font-family: system-ui, -apple-system, sans-serif; background: #111827; color: #e5e7eb; text-align: center; }
  .box { max-width: 22rem; padding: 2rem; }
  h1 { font-size: 1.25rem; margin: 0 0 0.5rem; }
  p { color: #9ca3af; margin: 0 0 1.25rem; }
  button { font: inherit; padding: 0.6rem 1.4rem; border-radius: 0.4rem; border: none;
    background: #3b82f6; color: #fff; cursor: pointer; }
  button:hover { background: #2563eb; }
</style>
</head>
<body>
<div class="box">
  <h1>Connection failed</h1>
  <p>PortOS couldn't reach the server, and no offline copy of this page is cached yet.</p>
  <button onclick="location.reload()">Retry</button>
</div>
</body>
</html>`;

function offlineFallbackResponse() {
  return new Response(OFFLINE_FALLBACK_HTML, {
    status: 503,
    statusText: 'Service Unavailable',
    headers: { 'Content-Type': 'text/html; charset=utf-8' },
  });
}

// Cap the immutable-asset cache so many rebuilds don't grow it without bound.
// Old build chunks accumulate here (their hashed names never collide); trim to
// the most-recently-added entries. Generous because a single build's chunk set
// is well under this.
const ASSET_CACHE_MAX_ENTRIES = 120;

// Same-origin static assets that are safe to serve stale-while-revalidate:
// fonts, icons, the PWA manifest, sky textures, the logo. Matched by path.
const STATIC_PATH_RE = /^\/(fonts|sky)\//;
const STATIC_FILE_RE = /^\/(manifest\.json|favicon\.(?:ico|svg)|apple-touch-icon\.png|icon-\d+\.png|portos-logo\.png)$/;

// Matches the `/assets/...` references (entry chunk + modulepreload deps + CSS)
// in the shell HTML. The set these produce is the boot JS/CSS the app can't
// start without.
const BOOT_ASSET_RE = /(?:src|href)="(\/assets\/[^"]+)"/g;

function parseBootAssetPaths(html) {
  return [...new Set([...html.matchAll(BOOT_ASSET_RE)].map((m) => m[1]))];
}

self.addEventListener('install', (event) => {
  // Adopt the new worker as soon as it's installed. Combined with network-first
  // navigations + the app's stale-chunk reload, this is safe: an open tab keeps
  // its in-memory JS, and its next navigation re-fetches the fresh shell.
  self.skipWaiting();
  event.waitUntil(
    (async () => {
      // Pre-warm the shell under the stable SHELL_KEY (NOT the request URL) so
      // the very first offline navigation — including a deep-link reload —
      // works even if the user never made an online navigation through the SW.
      // navigationHandler reads the offline fallback from SHELL_KEY, so the
      // pre-warm must write the same key (cache.add would key it by "/" and the
      // fallback would miss). Best-effort — a failure must not abort install.
      const response = await fetch(new Request('/', { cache: 'reload' })).catch(() => null);
      if (!response || !response.ok) return;
      // Precache this build's boot assets (entry chunk + modulepreload deps +
      // CSS parsed from the shell) so a FIRST-VISIT offline reload can boot: on
      // a fresh install the SW only starts controlling the page after
      // window.load, so the initial page's /assets/* were network-served and
      // never entered ASSET_CACHE. Only commit the shell once they're all
      // cached (same gate as navigationHandler) — a shell whose boot JS/CSS
      // failed to download (rolling deploy / flaky link) would load but never
      // start, so it's better to have no cached shell than a broken one.
      // trimCache derives the pinned set from the committed shell, so no
      // in-memory bookkeeping is needed here.
      const { cachedAll } = await precacheBootAssets(await response.clone().text());
      if (cachedAll) {
        const shell = await caches.open(SHELL_CACHE);
        await shell.put(SHELL_KEY, response);
        // Honor the cap: precacheBootAssets adds assets directly (bypassing
        // cacheFirst's trim), so trim here — after the shell commit, so the new
        // boot assets are pinned and only old builds' chunks are evicted.
        await trimCache(await caches.open(ASSET_CACHE), ASSET_CACHE_MAX_ENTRIES);
      }
    })()
  );
});

self.addEventListener('activate', (event) => {
  event.waitUntil(
    (async () => {
      // Enabling navigation preload (speeds up network-first navigations) and
      // pruning caches from older worker versions are independent — run them
      // concurrently so activation isn't lengthened on a slow link.
      const enablePreload = self.registration.navigationPreload
        ? self.registration.navigationPreload.enable().catch(() => {})
        : Promise.resolve();
      const cleanup = caches.keys().then((names) =>
        Promise.all(
          names
            .filter((name) => name.startsWith('portos-') && !CURRENT_CACHES.has(name))
            .map((name) => caches.delete(name))
        )
      );
      await Promise.all([enablePreload, cleanup]);
      await self.clients.claim();
    })()
  );
});

// Allow the page to trigger an immediate takeover (e.g. an "update ready"
// prompt) without a full reload race.
self.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'SKIP_WAITING') self.skipWaiting();
});

self.addEventListener('fetch', (event) => {
  const { request } = event;

  // Only GET is cacheable; everything else (POST/PUT/socket upgrades) passes
  // straight through to the network.
  if (request.method !== 'GET') return;

  let url;
  try {
    url = new URL(request.url);
  } catch {
    return; // Malformed URL — let the browser handle it.
  }

  // Never touch cross-origin requests. Nothing the app loads is cross-origin
  // any more now that the webfonts are self-hosted, so this is a hard bail
  // rather than a branch on the way to one.
  if (url.origin !== self.location.origin) return;

  // Never cache dynamic / real-time / large-media routes. Let them hit the
  // network directly (also preserves HTTP Range for /data media).
  if (
    url.pathname.startsWith('/api/') ||
    url.pathname.startsWith('/socket.io/') ||
    url.pathname.startsWith('/data/')
  ) {
    return;
  }

  // SPA navigations: network-first, fall back to the cached shell offline.
  if (request.mode === 'navigate') {
    // Arm the SW-lifetime promise SYNCHRONOUSLY, here in the fetch dispatch —
    // the only point event.waitUntil() is guaranteed valid. navigationHandler
    // resolves `signalCachingDone` once its background shell/asset caching
    // settles, so the worker stays alive long enough to update the offline
    // shell after a rebuild even though the response is returned first.
    let signalCachingDone;
    event.waitUntil(new Promise((resolve) => { signalCachingDone = resolve; }));
    event.respondWith(navigationHandler(event, signalCachingDone));
    return;
  }

  // Content-hashed, immutable build output: cache-first.
  if (url.pathname.startsWith('/assets/')) {
    event.respondWith(cacheFirst(request, ASSET_CACHE, ASSET_CACHE_MAX_ENTRIES));
    return;
  }

  // Static public assets (icons, fonts, manifest, textures): stale-while-revalidate.
  if (STATIC_PATH_RE.test(url.pathname) || STATIC_FILE_RE.test(url.pathname)) {
    event.respondWith(staleWhileRevalidate(request, STATIC_CACHE));
    return;
  }

  // Anything else same-origin: try network, fall back to any cached copy.
  event.respondWith(networkFallingBackToCache(request));
});

// --- strategies ---------------------------------------------------------

async function navigationHandler(event, onCachingSettled) {
  try {
    // Prefer the browser's navigation-preload response when available.
    const preload = await event.preloadResponse;
    const response = preload || (await fetch(event.request));
    if (response && response.ok) {
      // Update the offline shell + boot assets in the BACKGROUND (kept alive by
      // the lifetime promise armed in the fetch listener) so the navigation
      // response isn't delayed. Cache access lives INSIDE the background task,
      // not on the online path — a Cache Storage failure (storage disabled /
      // partitioned in some privacy modes) must not fail an otherwise-fine
      // online navigation; it just skips caching. Only REPLACE the known-good
      // shell once this build's boot assets are all cached — so a half-
      // downloaded deploy (new HTML fetched, its hashed assets not yet
      // downloaded) can't strand the offline fallback on a shell whose assets
      // are unavailable. trimCache re-derives the pinned set from whichever
      // shell is committed, so old assets stay pinned until the new shell
      // actually takes over.
      const toCache = response.clone();
      (async () => {
        const { cachedAll } = await precacheBootAssets(await toCache.clone().text());
        if (cachedAll) {
          const shell = await caches.open(SHELL_CACHE);
          await shell.put(SHELL_KEY, toCache);
          // Trim here too: on a new-build navigation, precacheBootAssets adds
          // the boot assets directly (bypassing cacheFirst's trim), so the cap
          // would otherwise be unenforced for a user who only visits the shell
          // across upgrades. Trim AFTER the commit so the new boot assets are
          // pinned and only stale chunks are evicted.
          await trimCache(await caches.open(ASSET_CACHE), ASSET_CACHE_MAX_ENTRIES);
        }
      })().catch(() => {}).finally(onCachingSettled);
    } else {
      onCachingSettled();
    }
    return response;
  } catch {
    onCachingSettled();
    // Offline (or the network fetch failed): serve the cached shell. Guard the
    // cache access so a Cache Storage failure degrades to a plain network error
    // rather than throwing out of the handler.
    const cached = await caches.open(SHELL_CACHE).then((c) => c.match(SHELL_KEY)).catch(() => null);
    if (cached) return cached;
    // Last resort: whatever we have for this exact navigation URL.
    const exact = await caches.match(event.request).catch(() => null);
    if (exact) return exact;
    // Nothing cached at all — render an actionable page instead of an opaque
    // network-error response.
    return offlineFallbackResponse();
  }
}

// Parse the shell HTML's `/assets/...` references (entry chunk + its
// modulepreload deps + CSS) and warm them into ASSET_CACHE. Returns the
// referenced `urls` plus `cachedAll` — true iff every referenced asset is now
// cached — which the caller uses to gate replacing a known-good offline shell.
async function precacheBootAssets(html) {
  const urls = parseBootAssetPaths(html);
  // Parsing NO boot assets from a real shell means we can't verify it's
  // bootable offline (e.g. a future non-root Vite `base` the `/assets/` matcher
  // wouldn't recognize) — fail the gate rather than commit a shell we can't
  // confirm. A real Vite build always references at least the entry chunk.
  if (!urls.length) return { urls, cachedAll: false };
  const cache = await caches.open(ASSET_CACHE);
  const results = await Promise.all(urls.map(async (url) => {
    if (await cache.match(url)) return true;
    const r = await fetch(url).catch(() => null);
    if (r && r.ok) {
      await cache.put(url, r);
      return true;
    }
    return false;
  }));
  return { urls, cachedAll: results.every(Boolean) };
}

// The boot-asset paths referenced by the currently-cached offline shell, read
// back from Cache Storage (durable — unaffected by the SW global being torn
// down between events). Empty when no shell is cached yet.
async function cachedShellBootAssets() {
  const shell = await caches.open(SHELL_CACHE);
  const cached = await shell.match(SHELL_KEY);
  if (!cached) return new Set();
  return new Set(parseBootAssetPaths(await cached.text()));
}

async function cacheFirst(request, cacheName, maxEntries) {
  const cache = await caches.open(cacheName);
  const cached = await cache.match(request);
  if (cached) return cached;
  const response = await fetch(request);
  // Every caller is same-origin now (the cross-origin font hosts are gone —
  // the webfonts are self-hosted), so responses are always inspectable and
  // `ok` is the whole test; an opaque response can no longer reach here.
  if (response && response.ok) {
    await cache.put(request, response.clone());
    if (maxEntries) trimCache(cache, maxEntries);
  }
  return response;
}

async function staleWhileRevalidate(request, cacheName) {
  const cache = await caches.open(cacheName);
  const cached = await cache.match(request);
  const network = fetch(request)
    .then((response) => {
      if (response && response.ok) cache.put(request, response.clone()).catch(() => {});
      return response;
    })
    .catch(() => null);
  return cached || (await network) || Response.error();
}

async function networkFallingBackToCache(request) {
  try {
    return await fetch(request);
  } catch {
    const cached = await caches.match(request);
    if (cached) return cached;
    return Response.error();
  }
}

// Trim a cache to its N most-recently-added entries (cache.keys() preserves
// insertion order, so the oldest are at the front). Takes an already-open
// cache handle. Fire-and-forget; only enumerates on the rare over-cap put.
//
// The current shell's boot assets are NEVER evicted, even though they're the
// oldest insertions: the shell can't start without them, so trimming them would
// break a later offline reload. The pinned set is derived FROM the cached shell
// on each trim (not an in-memory variable) so it survives the SW being
// discarded between events and can never disagree with the committed shell.
// Trim only the runtime chunks (lazy route splits, old builds' assets),
// oldest-first.
async function trimCache(cache, maxEntries) {
  const keys = await cache.keys();
  if (keys.length <= maxEntries) return;
  const pinned = await cachedShellBootAssets();
  const trimmable = keys.filter((req) => !pinned.has(new URL(req.url).pathname));
  const excess = trimmable.slice(0, keys.length - maxEntries);
  await Promise.all(excess.map((key) => cache.delete(key)));
}