Cache Playground assets to enable offline support

README.md

@@ -131,6 +131,35 @@ PHP=7.4 npx @php-wasm/cli -v
 npx @php-wasm/cli phpcbf
 ```
 
+### Test offline support
+
+To test the offline support you need to build the website and run a local server:
+
+```bash
+PLAYGROUND_URL=http://localhost:9999 npx nx run playground-website:build:wasm-wordpress-net
+```
+
+Then you can run a local server:
+
+```bash
+php -S localhost:9999 -t dist/packages/playground/wasm-wordpress-net
+```
+
+or using Docker:
+
+```bash
+docker run --rm -p 9999:80 -v $(pwd)/dist/packages/playground/wasm-wordpress-net:/usr/share/nginx/html:ro nginx:alpine
+```
+
+#### Using the browser to test the offline support
+
+1. Open the browser and go to `http://localhost:9999`.
+2. Open the browser's developer tools.
+3. Go to the "Network" tab.
+4. Select "Offline" in the throttling dropdown menu.
+5. Refresh the page.
+
+
 ## How can I contribute?
 
 WordPress Playground is an open-source project and welcomes all contributors from code to design, and from documentation to triage. If the feature you need is missing, you are more than welcome to start a discussion, open an issue, and even propose a Pull Request to implement it.

packages/php-wasm/web-service-worker/src/initialize-service-worker.ts

@@ -178,7 +178,6 @@ export async function broadcastMessageExpectReply(message: any, scope: string) {
 }
 
 interface ServiceWorkerConfiguration {
-	cacheVersion: string;
 	handleRequest?: (event: FetchEvent) => Promise<Response> | undefined;
 }
 

packages/php-wasm/web-service-worker/tsconfig.lib.json

@@ -5,6 +5,8 @@
 		"declaration": true,
 		"types": ["node"]
 	},
-	"include": ["src/**/*.ts"],
+	"include": [
+		"src/**/*.ts",
+	],
 	"exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
 }

packages/php-wasm/web/src/lib/register-service-worker.ts

@@ -2,6 +2,7 @@ import { PHPWorker } from '@php-wasm/universal';
 import { PhpWasmError } from '@php-wasm/util';
 import { responseTo } from '@php-wasm/web-service-worker';
 import { Remote } from 'comlink';
+import { logger } from '@php-wasm/logger';
 
 export interface Client extends Remote<PHPWorker> {}
 
@@ -65,7 +66,15 @@ export async function registerServiceWorker(scope: string, scriptUrl: string) {
 
 	// Check if there's a new service worker available and, if so, enqueue
 	// the update:
-	await registration.update();
+	try {
+		await registration.update();
+	} catch (e) {
+		// registration.update() throws if it can't reach the server.
+		// We're swallowing the error to keep the app working in offline mode
+		// or when playground.wordpress.net is down. We can be sure we have a functional
+		// service worker at this point because sw.register() succeeded.
+		logger.error('Failed to update service worker.', e);
+	}
 
 	// Proxy the service worker messages to the web worker:
 	navigator.serviceWorker.addEventListener(

packages/playground/client/vite.config.ts

@@ -6,6 +6,8 @@ import { join } from 'path';
 import ignoreWasmImports from '../ignore-wasm-imports';
 // eslint-disable-next-line @nx/enforce-module-boundaries
 import { viteTsConfigPaths } from '../../vite-extensions/vite-ts-config-paths';
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { buildVersionPlugin } from '../../vite-extensions/vite-build-version';
 
 export default defineConfig({
 	cacheDir: '../../../node_modules/.vite/playground-client',
@@ -18,6 +20,13 @@ export default defineConfig({
 			tsconfigPath: join(__dirname, 'tsconfig.lib.json'),
 		}),
 		ignoreWasmImports(),
+
+		// @wp-playground/client doesn't actually use the remote-config virtual module,
+		// @wp-playground/remote package does.
+		// @wp-playground/client imports a few things from @wp-playground/remote and,
+		// even though it doesn't involve the remote-config virtual module, the bundler
+		// still needs to know what to do when it sees `import from "virtual:remote-config"`.
+		buildVersionPlugin('remote-config'),
 	],
 
 	// Configuration for building your library.

packages/playground/remote/service-worker.ts

@@ -2,7 +2,7 @@
 
 declare const self: ServiceWorkerGlobalScope;
 
-import { getURLScope, removeURLScope } from '@php-wasm/scopes';
+import { getURLScope, isURLScoped, removeURLScope } from '@php-wasm/scopes';
 import { applyRewriteRules } from '@php-wasm/universal';
 import {
 	awaitReply,
@@ -14,7 +14,7 @@ import {
 import { wordPressRewriteRules } from '@wp-playground/wordpress';
 import { reportServiceWorkerMetrics } from '@php-wasm/logger';
 
-import { buildVersion } from 'virtual:remote-config';
+import { OfflineModeCache } from './src/lib/offline-mode-cache';
 
 if (!(self as any).document) {
 	// Workaround: vite translates import.meta.url
@@ -25,10 +25,101 @@ if (!(self as any).document) {
 	self.document = {};
 }
 
+/**
+ * Ensures the very first Playground load is controlled by this service worker.
+ *
+ * This is necessary because service workers don't control any pages loaded
+ * before they are activated. This includes the page that actually registers
+ * the service worker. You need to reload it before `navigator.serviceWorker.controller`
+ * is set and the fetch() requests are intercepted here.
+ *
+ * However, the initial Playground load already downloads a few large assets,
+ * like a 12MB wordpress-static.zip file. We need to cache them these requests.
+ * Otherwise they'll be fetched again on the next page load.
+ *
+ * client.claim() only affects pages loaded before the initial servie worker
+ * registration. It shouldn't have unwanted side effects in our case. All these
+ * pages would get controlled eventually anyway.
+ *
+ * See:
+ * * The service worker lifecycle https://web.dev/articles/service-worker-lifecycle
+ * * Clients.claim() docs https://developer.mozilla.org/en-US/docs/Web/API/Clients/claim
+ */
+self.addEventListener('activate', function (event) {
+	event.waitUntil(self.clients.claim());
+});
+
+/**
+ * Handle fetch() caching:
+ *
+ * * Put the initial fetch response in the cache
+ * * Serve the subsequent requests from the cache
+ */
+self.addEventListener('fetch', (event) => {
+	const url = new URL(event.request.url);
+
+	/**
+	 * Don't cache requests to the service worker script itself.
+	 */
+	if (url.pathname.startsWith(self.location.pathname)) {
+		return;
+	}
+
+	/**
+	 * Don't cache requests to scoped URLs or if the referrer URL is scoped.
+	 *
+	 * These requests are made to the PHP Worker Thread and are not static assets.
+	 */
+	if (isURLScoped(url)) {
+		return;
+	}
+
+	let referrerUrl;
+	try {
+		referrerUrl = new URL(event.request.referrer);
+	} catch (e) {
+		// ignore
+	}
+
+	if (referrerUrl && isURLScoped(referrerUrl)) {
+		return;
+	}
+
+	/**
+	 * Respond with cached assets if available.
+	 * If the asset is not cached, fetch it from the network and cache it.
+	 */
+	event.respondWith(
+		cachePromise.then((cache) => cache.cachedFetch(event.request))
+	);
+});
+
 reportServiceWorkerMetrics(self);
 
+const cachePromise = OfflineModeCache.getInstance().then((cache) => {
+	/**
+	 * For offline mode to work we need to cache all required assets.
+	 *
+	 * These assets are listed in the `/assets-required-for-offline-mode.json` file
+	 * and contain JavaScript, CSS, and other assets required to load the site without
+	 * making any network requests.
+	 */
+	cache.cacheOfflineModeAssets();
+
+	/**
+	 * Remove outdated files from the cache.
+	 *
+	 * We cache data based on `buildVersion` which is updated whenever Playground is built.
+	 * So when a new version of Playground is deployed, the service worker will remove the old cache and cache the new assets.
+	 *
+	 * If your build version doesn't change while developing locally check `buildVersionPlugin` for more details on how it's generated.
+	 */
+	cache.removeOutdatedFiles();
+
+	return cache;
+});
+
 initializeServiceWorker({
-	cacheVersion: buildVersion,
 	handleRequest(event) {
 		const fullUrl = new URL(event.request.url);
 		let scope = getURLScope(fullUrl);

packages/playground/remote/src/lib/boot-playground-remote.ts

@@ -208,10 +208,19 @@ export async function bootPlaygroundRemote() {
 
 		/**
 		 * Download WordPress assets.
+		 * @see backfillStaticFilesRemovedFromMinifiedBuild in the worker-thread.ts
 		 */
 		async backfillStaticFilesRemovedFromMinifiedBuild() {
 			await phpApi.backfillStaticFilesRemovedFromMinifiedBuild();
 		},
+
+		/**
+		 * Checks whether we have the missing WordPress assets readily
+		 * available in the request cache.
+		 */
+		async hasCachedStaticFilesRemovedFromMinifiedBuild() {
+			return await phpApi.hasCachedStaticFilesRemovedFromMinifiedBuild();
+		},
 	};
 
 	await phpApi.isConnected();
@@ -244,30 +253,43 @@ export async function bootPlaygroundRemote() {
 	}
 
 	/**
-	 * When WordPress is loaded from a minified bundle, some assets are removed to reduce the bundle size.
-	 * This function backfills the missing assets. If WordPress is loaded from a non-minified bundle,
-	 * we don't need to backfill because the assets are already included.
+	 * When we're running WordPress from a minified bundle, we're missing some static assets.
+	 * The section below backfills them if needed. It doesn't do anything if the assets are already
+	 * in place, or when WordPress is loaded from a non-minified bundle.
+	 *
+	 * Minified bundles are shipped without most static assets to reduce the bundle size and
+	 * the loading time. When WordPress loads for the first time, the browser parses all the
+	 * <script src="">, <link href="">, etc. tags and fetches the missing assets from the server.
 	 *
-	 * If the browser is online we download the WordPress assets asynchronously to speed up the boot process.
-	 * Missing assets will be fetched on demand from the Playground server until they are downloaded.
+	 * Unfortunately, fetching these assets on demand wouldn't work in an offline mode.
 	 *
-	 * If the browser is offline, we await the backfill or WordPress assets
-	 * from cache to ensure Playground is fully functional before boot finishes.
+	 * Below we're downloading a zipped bundle of the missing assets.
 	 */
-	if (window.navigator.onLine) {
+	if (await webApi.hasCachedStaticFilesRemovedFromMinifiedBuild()) {
+		/**
+		 * If we already have the static assets in the cache, the backfilling only
+		 * involves unzipping the archive. This is fast. Let's do it before the first
+		 * render.
+		 *
+		 * Why?
+		 *
+		 * Because otherwise the initial offline page render would lack CSS.
+		 * Without the static assets in /wordpress/wp-content, the browser would
+		 * attempt to fetch them from the server. However, we're in an offline mode
+		 * so nothing would be fetched.
+		 */
+		await webApi.backfillStaticFilesRemovedFromMinifiedBuild();
+	} else {
+		/**
+		 * If we don't have the static assets in the cache, we need to fetch them.
+		 *
+		 * Let's wait for the initial page load before we start the backfilling.
+		 * The static assets are 12MB+ in size. Starting the download before
+		 * Playground is loaded would noticeably delay the first paint.
+		 */
 		wpFrame.addEventListener('load', () => {
 			webApi.backfillStaticFilesRemovedFromMinifiedBuild();
 		});
-	} else {
-		// Note this will run even if the static files are already in place, e.g. when running
-		// a non-minified build or an offline site. It doesn't seem like a big problem worth introducing
-		// a new API method like `webApi.needsBackfillingStaticFilesRemovedFromMinifiedBuild().
-		webApi.setProgress({
-			caption: 'Downloading WordPress assets',
-			isIndefinite: false,
-			visible: true,
-		});
-		await webApi.backfillStaticFilesRemovedFromMinifiedBuild();
 	}
 
 	/*