Use persistent storage for SW config to support browser-initiated SW terminations

Author: ljwagerfield

src/index.auth-sw.js

@@ -1,45 +1,30 @@
+/* eslint-disable no-undef */
 /**
  * Bytescale Auth Service Worker (SW)
  *
- * What is this?
- * ------------
- * This script is designed to be imported into a 'service worker' that's included in a top-level script on the user's
- * web application's domain. This script intercepts FETCH requests to add JWTs (issued by the user's application) to
- * Bytescale CDN requests via the 'Authorization-Token' request header. This allows the Bytescale CDN to authorize
- * requests using 'Authorization-Token' headers as opposed to cookies, which are blocked by some browsers (including Safari).
+ * This script should be referenced by the "serviceWorkerScript" field in the "AuthManager.beginAuthSession" method of
+ * the Bytescale JavaScript SDK to append "Authorization" headers to HTTP requests sent to the Bytescale CDN. This
+ * approach serves as an alternative to cookie-based authentication, which is incompatible with certain modern browsers.
  *
- * Installation
- * ------------
- * 1. The user must add a root-level script to their application, under their web application's domain, that includes:
- *    importScripts("https://js.bytescale.com/auth-sw/v1");
- * 2. This script MUST be hosted on the _exact domain_ your website is running on; you cannot host it from a different (sub)domain.
- *    Explanation: service workers cannot be added cross-domain. This is a restriction of the service worker API.
- * 3. This script MUST be hosted in the root folder (e.g. '/bytescale-auth-sw.js' and not '/scripts/bytescale-auth-sw.js')
- *    Explanation: service workers can only intercept HTTP requests from pages that are at the same level as, or lower than, the script's path.
- * 4. Add the 'serviceWorkerScript' field to the 'beginAuthSession' method call in your code, specifying the path to this script.
+ * Documentation:
+ * - https://www.bytescale.com/docs/types/BeginAuthSessionParams#serviceWorkerScript
  */
-
-// See: AuthSwConfigDto
-let config; // [{urlPrefix, headers, expires?}]
-
-// This is a thunk created during the "install" event and called during the first "message" event.
-let resolveInitialConfig;
-
-// Time to wait before activating to allow 'postMessage' to initialize our config -- should be near-instant as there's
-// no async calls between the 'register' and 'postMessage', so a short timeout is fine. If the timeout occurs, then the
-// new service worker will be used without any config, meaning some requests to private files will fail until
-// 'postMessage' is called by the client with the up-to-date config.
-const installTimeoutMs = 1000;
+let transientCache; // [{urlPrefix, headers, expires?}] (See: AuthSwConfigDto)
+const persistentCacheName = "bytescale-sw-config";
+const persistentCacheKey = "config";
 
 console.log(`[bytescale] Auth SW Registered`);
 
-/* eslint-disable no-undef */
 self.addEventListener("install", function (event) {
-  event.waitUntil(install());
+  // Typically service workers go: 'installing' -> 'waiting' -> 'activated'.
+  // However, we skip the 'waiting' phase as we want this service worker to be used immediately after it's installed,
+  // instead of requiring a page refresh if the browser already has an old version of the service worker installed.
+  event.waitUntil(self.skipWaiting());
 });
 
 self.addEventListener("activate", function (event) {
-  // Immediately allow the service worker to intercept "fetch" events (instead of requiring a page refresh) if this is the first time this service worker is being installed.
+  // Immediately allow the service worker to intercept "fetch" events (instead of requiring a page refresh) if this is
+  // the first time this service worker is being installed.
   event.waitUntil(self.clients.claim());
 });
 
@@ -48,23 +33,53 @@ self.addEventListener("message", event => {
   // See: AuthSwSetConfigDto
   if (event.data) {
     switch (event.data.type) {
+      // Auth sessions are started/ended by calling SET_CONFIG with auth config or with 'undefined' config, respectively.
+      // We use 'undefined' to end the auth session instead of unregistering the worker, as there may be multiple tabs
+      // in the user's application, so while the user may sign out in one tab, they may remain signed in to another tab,
+      // which may subsequently send a follow-up 'SET_CONFIG' which will resume auth.
       case "SET_BYTESCALE_AUTH_CONFIG":
-        // Auth sessions are started/ended by calling SET_CONFIG with auth config or with 'undefined' config, respectively.
-        // We use 'undefined' to end the auth session instead of unregistering the worker, as there may be multiple tabs
-        // in the user's application, so while the user may sign out in one tab, they may remain signed in to another tab,
-        // which may subsequently send a follow-up 'SET_CONFIG' which will resume auth.
-        config = event.data.config;
-
-        if (resolveInitialConfig !== undefined) {
-          resolveInitialConfig();
-          resolveInitialConfig = undefined;
-        }
+        setConfig(event.data.config).then(
+          () => {},
+          e => console.error(`[bytescale] Auth SW failed to persist config.`, e)
+        );
         break;
     }
   }
 });
 
 self.addEventListener("fetch", function (event) {
+  // Faster and intercepts only the required requests.
+  // Called in almost all cases.
+  const interceptSync = config => {
+    const newRequest = interceptRequest(event, config);
+    if (newRequest !== undefined) {
+      event.respondWith(handleRequestErrors(newRequest));
+    }
+  };
+
+  // Slower and intercepts all requests (while still only rewriting the relevant requests).
+  // Called only for the initial request after this Service Worker is restarted after going idle (e.g. after 30s on Firefox/Windows).
+  const interceptAsync = async () =>
+    await handleRequestErrors(interceptRequest(event, await getConfig()) ?? event.request);
+
+  // Makes it clearer to developers that the request failed for normal reasons (not reasons caused by this script).
+  const handleRequestErrors = async request => {
+    try {
+      return await fetch(request);
+    } catch (e) {
+      throw new Error("Network request failed: see previous browser errors for the cause.");
+    }
+  };
+
+  // Optimization: avoids running async code (which necessitates intercepting all requests) when the config is already cached locally.
+  if (transientCache !== undefined) {
+    interceptSync(transientCache);
+  } else {
+    event.respondWith(interceptAsync());
+  }
+});
+
+function interceptRequest(event, config) {
   const url = event.request.url;
 
   if (config !== undefined) {
@@ -74,68 +89,53 @@ self.addEventListener("fetch", function (event) {
         if (url.startsWith(urlPrefix) && event.request.method.toUpperCase() === "GET") {
           const newHeaders = new Headers(event.request.headers);
           for (const { key, value } of headers) {
-            // Preserve existing headers in the request. This is crucial for 'fetch' requests that might already include
-            // an "Authorization" header, enabling access to certain resources. For instance, the Bytescale Dashboard
-            // uses an explicit "Authorization" header in a 'fetch' request to allow account admins to download private
-            // files. In these scenarios, it's important not to replace these headers with the global JWT managed by the
-            // AuthManager.
+            // Preserve existing headers in the request. This is crucial for 'fetch' requests that might already
+            // include an "Authorization" header, enabling access to certain resources. For instance, the Bytescale
+            // Dashboard uses an explicit "Authorization" header in a 'fetch' request to allow account admins to
+            // download private files. In these scenarios, it's important not to replace these headers with the global
+            // JWT managed by the AuthManager.
             if (!newHeaders.has(key)) {
               newHeaders.set(key, value);
             }
           }
-          const newRequest = new Request(event.request, {
+
+          return new Request(event.request, {
             mode: "cors", // Required for adding custom HTTP headers.
             headers: newHeaders
           });
-          event.respondWith(fetch(newRequest));
-
-          // Do not match on any other configs
-          return;
         }
       }
     }
   }
-});
 
-async function withTimeout(promise, ms) {
-  let timeoutHandle;
-  const timeoutPromise = new Promise((resolve, reject) => {
-    timeoutHandle = setTimeout(() => {
-      reject(new Error(`Timed out after ${ms} milliseconds`));
-    }, ms);
-  });
-
-  return Promise.race([promise, timeoutPromise]).finally(() => {
-    clearTimeout(timeoutHandle);
-  });
+  return undefined;
 }
 
-async function install() {
-  // Wait for the initial config to be received before activating this service worker.
-  // This prevents us from replacing a functional service worker (with config) with a service worker that initially
-  // has no config, and thus causes private file downloads to fail as they're temporarily not being authorized due to
-  // the new service worker being active but not having its config yet.
-  // ---
-  // Timeout is required else all subsequent 'navigator.serviceWorker.register' calls for future service workers will
-  // hang forever if the current service worker never completes its 'install' phase. Same applies to 'unregister' calls
-  // for the current service worker.
-  // ---
-  try {
-    await withTimeout(
-      new Promise(resolve => {
-        resolveInitialConfig = resolve;
-      }),
-      installTimeoutMs
-    );
-  } catch {
-    // Not a big issue: it just means the service worker will be activated with blank config, so private files won't
-    // be authorized until new config is received, which is undesirable if this service worker replaced an
-    // already-functioning service worker that was correctly configured and was authorizing requests.
-    console.warn("[bytescale] Auth SW initialization timeout.");
+async function getConfig() {
+  if (transientCache !== undefined) {
+    return transientCache;
   }
 
-  // Typically service workers go: 'installing' -> 'waiting' -> 'activated'.
-  // However, we skip the 'waiting' phase as we want this service worker to be used immediately after it's installed,
-  // instead of requiring a page refresh if the browser already has an old version of the service worker installed.
-  await self.skipWaiting();
+  const cache = await getCache();
+  const configResponse = await cache.match(persistentCacheKey);
+  if (configResponse !== undefined) {
+    const config = await configResponse.json();
+    transientCache = config;
+    return config;
+  }
+
+  return undefined;
+}
+
+async function setConfig(config) {
+  // Ensures "fetch" events can start seeing the config immediately. Persistent config is only required for when this
+  // service worker expires (after 30s on some browsers, like FireFox on Windows).
+  transientCache = config;
+
+  const cache = await getCache();
+  await cache.put(persistentCacheKey, new Response(JSON.stringify(config)));
+}
+
+function getCache() {
+  return caches.open(persistentCacheName);
 }