fix: inform users how to deregister the service worker (#721)

SgtPooki · lidel · web-flow · commit 573519e5bc98 · 2025-05-28T15:31:43.000-04:00
* fix: inform users how to deregister the service worker

* fix: rearrange config buttons

* Update src/pages/config.tsx

Co-authored-by: Marcin Rataj &lt;lidel@lidel.org&gt;

* Update src/components/About.tsx

Co-authored-by: Marcin Rataj &lt;lidel@lidel.org&gt;

* fix: change deregister to unregister

add test for unregistering the service worker

---------

Co-authored-by: Marcin Rataj &lt;lidel@lidel.org&gt;
diff --git a/README.md b/README.md
@@ -121,6 +121,16 @@ aiming to be a drop-in replacement for `ipfs.io`:
 
 Deploying to [production[(https://github.com/ipfs/service-worker-gateway/actions/workflows/deploy-to-production.yml) and [staging](https://github.com/ipfs/service-worker-gateway/actions/workflows/deploy-to-staging.yml) is done by manually running the deployment action and passing the release version to the action.
 
+## Manual Service Worker Deregistration
+
+In some cases, you might want to manually unregister or remove the Helia service worker from your browser. This can be useful for debugging purposes or to ensure a clean state.
+
+You can instruct the service worker to unregister itself by appending the `?ipfs-sw-unregister=true` query parameter to the URL of any page controlled by the service worker.
+
+For example, if the service worker is active for `https://example.com`, navigating to `https://example.com/?ipfs-sw-unregister=true` will cause the service worker to unregister itself and attempt to reload all controlled clients (browser tabs).
+
+This option is also available via a button on the service worker's configuration page (`#/ipfs-sw-config`).
+
 ## License
 
 This project is dual-licensed under
diff --git a/src/components/sw-ready-button.tsx b/src/components/sw-ready-button.tsx
@@ -10,13 +10,10 @@ interface ServiceWorkerReadyButtonProps extends ButtonProps {
 export const ServiceWorkerReadyButton: React.FC<ServiceWorkerReadyButtonProps> = ({ className, label, waitingLabel, ...props }) => {
   const { isServiceWorkerRegistered } = useContext(ServiceWorkerContext)
 
-  const buttonClasses = new Set(['button-reset', 'pv3', 'tc', 'bn', 'white', 'cursor-disabled', 'bg-gray'])
+  const buttonClasses = new Set(['button-reset', 'pv3', 'tc', 'bn', 'cursor-disabled', 'bg-gray'])
   if (isServiceWorkerRegistered) {
     buttonClasses.delete('bg-gray')
     buttonClasses.delete('cursor-disabled')
-    buttonClasses.add('bg-animate')
-    buttonClasses.add('bg-teal-muted')
-    buttonClasses.add('hover-bg-navy-muted')
     buttonClasses.add('pointer')
   }
 
diff --git a/src/context/service-worker-context.tsx b/src/context/service-worker-context.tsx
@@ -12,10 +12,10 @@
  * 1. The page being loaded using some /ip[fn]s/<path> url, but subdomain isolation is supported, so we need to redirect to the isolated origin
  */
 import React, { createContext, useEffect, useState } from 'react'
-import { getRedirectUrl, isDeregisterRequest } from '../lib/deregister-request.js'
 import { ensureSwScope } from '../lib/first-hit-helpers.js'
 import { uiLogger } from '../lib/logger.js'
 import { findOriginIsolationRedirect } from '../lib/path-or-subdomain.js'
+import { isUnregisterRequest } from '../lib/unregister-request.js'
 import { registerServiceWorker } from '../service-worker-utils.js'
 import type { ReactElement } from 'react'
 
@@ -42,14 +42,13 @@ export const ServiceWorkerProvider = ({ children }): ReactElement => {
       return
     }
     async function doWork (): Promise<void> {
-      if (isDeregisterRequest(window.location.href)) {
-        log.trace('deregistering service worker')
+      if (isUnregisterRequest(window.location.href)) {
+        log.trace('unregistering service worker')
         const registration = await navigator.serviceWorker.getRegistration()
         if (registration != null) {
           await registration.unregister()
-          window.location.replace(getRedirectUrl(window.location.href).href)
         } else {
-          log.error('service worker not registered, cannot deregister')
+          log.error('service worker not registered, cannot unregister')
         }
       }
 
diff --git a/src/lib/deregister-request.ts b/src/lib/deregister-request.ts
diff --git a/src/lib/unregister-request.ts b/src/lib/unregister-request.ts
@@ -0,0 +1,9 @@
+/**
+ * Check if the url includes a `ipfs-sw-unregister` parameter
+ */
+export function isUnregisterRequest (url: string): boolean {
+  const urlObj = new URL(url)
+  const result = urlObj.search.includes('ipfs-sw-unregister')
+
+  return result
+}
diff --git a/src/pages/config.tsx b/src/pages/config.tsx
@@ -250,8 +250,20 @@ const ConfigPage: FunctionComponent<ConfigPageProps> = () => {
           />
         </InputSection>
         <div className='w-100 inline-flex flex-row justify-between'>
-          <button className='e2e-config-page-button button-reset mr5 pv3 tc bg-animate hover-bg-gold pointer w-30 bn' id='reset-config' onClick={() => { void doResetConfig() }}>Reset Config</button>
-          <ServiceWorkerReadyButton className='e2e-config-page-button white w-100 pa3' id='save-config' label={isSaving ? 'Saving...' : 'Save Config'} waitingLabel='Waiting for service worker registration...' onClick={() => { void saveConfig() }} />
+          <ServiceWorkerReadyButton
+            className='e2e-config-page-button pv3 tc bg-animate hover-bg-red-muted pointer w-30 bn'
+            id='unregister-sw'
+            label='Reset Worker'
+            waitingLabel='Waiting for SW...'
+            onClick={() => {
+              const currentUrl = new URL(window.location.href)
+              currentUrl.searchParams.set('ipfs-sw-unregister', 'true')
+              window.location.href = currentUrl.href
+            }}
+            disabled={isSaving}
+          />
+          <button className='e2e-config-page-button button-reset pv3 tc bg-animate hover-bg-gold pointer w-30 bn mr5' id='reset-config' onClick={() => { void doResetConfig() }}>Reset Config</button>
+          <ServiceWorkerReadyButton className='e2e-config-page-button white w-100 pa3 bg-animate bg-teal-muted hover-bg-navy-muted' id='save-config' label={isSaving ? 'Saving...' : 'Save Config'} waitingLabel='Waiting for service worker registration...' onClick={() => { void saveConfig() }} disabled={isSaving} />
         </div>
         {error != null && <span style={{ color: 'red' }}>{error.message}</span>}
       </section>
diff --git a/src/sw.ts b/src/sw.ts
@@ -1,12 +1,12 @@
 import { getConfig } from './lib/config-db.js'
-import { getRedirectUrl, isDeregisterRequest } from './lib/deregister-request.js'
 import { getHeliaSwRedirectUrl } from './lib/first-hit-helpers.js'
 import { GenericIDB } from './lib/generic-db.js'
 import { getSubdomainParts } from './lib/get-subdomain-parts.js'
 import { getVerifiedFetch } from './lib/get-verified-fetch.js'
 import { isConfigPage } from './lib/is-config-page.js'
 import { swLogger } from './lib/logger.js'
 import { findOriginIsolationRedirect, isPathGatewayRequest, isSubdomainGatewayRequest } from './lib/path-or-subdomain.js'
+import { isUnregisterRequest } from './lib/unregister-request.js'
 import type { ConfigDb } from './lib/config-db.js'
 import type { VerifiedFetch } from '@helia/verified-fetch'
 
@@ -148,6 +148,9 @@ self.addEventListener('activate', (event) => {
    */
   event.waitUntil(self.clients.claim())
 
+  // eslint-disable-next-line no-console
+  console.info('Service Worker Gateway: To manually unregister, append "?ipfs-sw-unregister=true" to the URL, or use the button on the config page.')
+
   // Delete all caches that aren't named in CURRENT_CACHES.
   const expectedCacheNames = Object.keys(CURRENT_CACHES).map(function (key) {
     return CURRENT_CACHES[key]
@@ -191,11 +194,14 @@ self.addEventListener('fetch', (event) => {
  */
 async function requestRouting (event: FetchEvent, url: URL): Promise<boolean> {
   if (await isTimebombExpired()) {
-    log.trace('timebomb expired, deregistering service worker')
-    event.waitUntil(deregister(event, false))
+    log.trace('timebomb expired, unregistering service worker')
+    event.waitUntil(self.registration.unregister())
     return false
-  } else if (isDeregisterRequest(event.request.url)) {
-    event.waitUntil(deregister(event))
+  } else if (isUnregisterRequest(event.request.url)) {
+    event.waitUntil(self.registration.unregister())
+    event.respondWith(new Response('Service worker unregistered', {
+      status: 200
+    }))
     return false
   } else if (isConfigPageRequest(url)) {
     log.trace('config page request, ignoring ', event.request.url)
@@ -275,25 +281,6 @@ async function requestRouting (event: FetchEvent, url: URL): Promise<boolean> {
   return false
 }
 
-// potential race condition
-async function deregister (event, redirectToConfig = true): Promise<void> {
-  if (!isSubdomainRequest(event)) {
-    // if we are at the root, we need to ignore this request due to race conditions with the UI
-    return
-  }
-  await self.registration.unregister()
-  const clients = await self.clients.matchAll({ type: 'window' })
-
-  for (const client of clients) {
-    const newUrl = redirectToConfig ? getRedirectUrl(client.url) : client.url
-    try {
-      await client.navigate(newUrl)
-    } catch (e) {
-      log.error('error navigating client to ', newUrl, e)
-    }
-  }
-}
-
 function isRootRequestForContent (event: FetchEvent): boolean {
   const urlIsPreviouslyIntercepted = urlInterceptRegex.some(regex => regex.test(event.request.url))
   const isRootRequest = urlIsPreviouslyIntercepted
diff --git a/test-e2e/smoke-test.test.ts b/test-e2e/smoke-test.test.ts
@@ -83,4 +83,19 @@ test.describe('smoke test', () => {
     expect(text).toContain('504 Gateway timeout')
     expect(text).toContain('Increase the timeout in the')
   })
+
+  test('unregistering the service worker works', async ({ page, baseURL }) => {
+    await page.goto(baseURL, { waitUntil: 'networkidle' })
+    await waitForServiceWorker(page, baseURL)
+
+    // unregister the service worker and make sure the config is empty
+    await page.click('#unregister-sw')
+    await page.waitForLoadState('networkidle')
+
+    const noRegistration = await page.evaluate(async () => {
+      return await window.navigator.serviceWorker.getRegistration() === undefined
+    })
+
+    expect(noRegistration).toBe(true)
+  })
 })
