Store WordPress site cookies in the browser instead of a custom Cookie Store (#20)

## Motivation for the change, related issues

A cookie store is needed on the web where custom Response objects may
not be assigned `Set-Cookie` headers. Otherwise, `Set-Cookie` headers
received in PHP responses are effectively discarded. But a cookie store
isn't needed for Playground CLI, and applying the same cookies to all
requests to a CLI-based server interferes with clients that want to use
other WP auth schemes.

This PR gives the browser-based PHP worker the responsibility for
maintaining a cookie store per Playground scope.

This feature was previously implemented by @brandonpayton in
[Automattic/wordpress-playground/pull/8](https://github.a8c.com/Automattic/wordpress-playground/pull/8).
We also explored using [document.cookie instead of the cookie
store](Automattic/wordpress-playground-private#21 (comment)),
but we couldn't come up with a clean implementation due to browser
restrictions.

## Implementation details

This PR makes the cookie store a browser-based PHP worker concern so it
can manage which cookie store to apply to which requests.

Originally, I wanted to make the Service Worker responsible for the
synthetic cookie store because it is responsible for all request routing
and generally sits between the browser client and the PHP "server", but
it turned out to be quite awkward because:
- the Service Worker doesn't currently know when Playground site scopes
come and go, making cleanup difficult
- Service Workers can be terminated and restarted while client tabs are
still open. This meant that we'd have to persist cookies in something
like IndexedDB, and both service worker lifetime uncertainty and
ignorance about the lifetime of site scopes made it difficult to know
when old cookie stores could be cleared.

If the cookie store is kept with the PHP worker, then the cookies will
naturally come and go as Playground sites are loaded and unloaded.

## Testing Instructions (or ideally a Blueprint)

- CI

Author: bgrgicak

packages/php-wasm/node/src/test/php-request-handler.spec.ts

@@ -3,7 +3,9 @@ import { RecommendedPHPVersion } from '@wp-playground/common';
 import { getFileNotFoundActionForWordPress } from '@wp-playground/wordpress';
 import { loadNodeRuntime } from '..';
 import {
+	CookieStore,
 	FileNotFoundGetActionCallback,
+	HttpCookieStore,
 	PHP,
 	PHPRequestHandler,
 	PHPResponse,
@@ -765,3 +767,98 @@ describe('PHPRequestHandler – Loopback call', () => {
 		expect(response.text).toEqual('Starting: Ran second.php! Done');
 	});
 });
+
+describe('PHPRequestHandler – Cookie store', () => {
+	const prepareHandler = async (cookieStore?: CookieStore | false) => {
+		const handler = new PHPRequestHandler({
+			documentRoot: '/',
+			phpFactory: async () =>
+				new PHP(await loadNodeRuntime(RecommendedPHPVersion)),
+			maxPhpInstances: 1,
+			cookieStore,
+		});
+		const php = await handler.getPrimaryPhp();
+		php.writeFile(
+			'/set-cookie.php',
+			`<?php setcookie("my-cookie", "where-is-my-cookie", time() + 3600, "/");`
+		);
+		php.writeFile('/get-cookie.php', `<?php echo json_encode($_COOKIE);`);
+		return handler;
+	};
+	it('should persist cookies internally when not defining a strategy', async () => {
+		const handler = await prepareHandler();
+
+		// Cookies return in the response
+		let response = await handler.request({
+			url: '/set-cookie.php',
+		});
+		const cookies = response.headers['set-cookie'];
+		expect(cookies).toHaveLength(1);
+		expect(cookies[0]).toMatch(
+			/my-cookie=where-is-my-cookie; expires=.*; Max-Age=3600; path=\//
+		);
+
+		// Cookies are persisted internally in the request handler.
+		// Note that we are not passing cookies in the header of the response.
+		response = await handler.request({
+			url: '/get-cookie.php',
+		});
+		expect(response.text).toEqual(
+			JSON.stringify({ 'my-cookie': 'where-is-my-cookie' })
+		);
+	});
+
+	it('should persist cookies internally with the HttpCookieStore', async () => {
+		const handler = await prepareHandler(new HttpCookieStore());
+
+		// Cookies return in the response
+		let response = await handler.request({
+			url: '/set-cookie.php',
+		});
+		const cookies = response.headers['set-cookie'];
+		expect(cookies).toHaveLength(1);
+		expect(cookies[0]).toMatch(
+			/my-cookie=where-is-my-cookie; expires=.*; Max-Age=3600; path=\//
+		);
+
+		// Cookies are persisted internally in the request handler.
+		// Note that we are not passing cookies in the header of the response.
+		response = await handler.request({
+			url: '/get-cookie.php',
+		});
+		expect(response.text).toEqual(
+			JSON.stringify({ 'my-cookie': 'where-is-my-cookie' })
+		);
+	});
+
+	it('should not persist cookies internally when the cookie store is false', async () => {
+		const handler = await prepareHandler(false);
+
+		// Cookies return in the response
+		let response = await handler.request({
+			url: '/set-cookie.php',
+		});
+		const cookies = response.headers['set-cookie'];
+		expect(cookies).toHaveLength(1);
+		expect(cookies[0]).toMatch(
+			/my-cookie=where-is-my-cookie; expires=.*; Max-Age=3600; path=\//
+		);
+
+		// No cookies are persisted internally.
+		// Note that we are not passing cookies in the header of the response.
+		response = await handler.request({
+			url: '/get-cookie.php',
+		});
+		expect(response.text).toEqual(JSON.stringify([]));
+
+		// Cookies are available in the PHP environment when passed in the
+		// request.
+		response = await handler.request({
+			url: '/get-cookie.php',
+			headers: { Cookie: 'my-cookie=where-is-my-cookie' },
+		});
+		expect(response.text).toEqual(
+			JSON.stringify({ 'my-cookie': 'where-is-my-cookie' })
+		);
+	});
+});

packages/php-wasm/universal/src/lib/http-cookie-store.ts

@@ -1,9 +1,9 @@
 import { logger } from '@php-wasm/logger';
-
+import { CookieStore } from './php-request-handler';
 /**
  * @public
  */
-export class HttpCookieStore {
+export class HttpCookieStore implements CookieStore {
 	cookies: Record<string, string> = {};
 
 	rememberCookiesFromResponseHeaders(headers: Record<string, string[]>) {

packages/php-wasm/universal/src/lib/index.ts

@@ -61,6 +61,7 @@ export type {
 	FileNotFoundToInternalRedirect,
 	FileNotFoundToResponse,
 	FileNotFoundAction,
+	CookieStore,
 } from './php-request-handler';
 export { rotatePHPRuntime } from './rotate-php-runtime';
 export { writeFiles } from './write-files';

packages/php-wasm/universal/src/lib/php-request-handler.ts

@@ -42,6 +42,24 @@ export type FileNotFoundGetActionCallback = (
 	relativePath: string
 ) => FileNotFoundAction;
 
+/**
+ * Interface for cookie storage implementations.
+ * This allows different cookie handling strategies to be used with the PHP request handler.
+ */
+export interface CookieStore {
+	/**
+	 * Processes and stores cookies from response headers
+	 * @param headers Response headers containing Set-Cookie directives
+	 */
+	rememberCookiesFromResponseHeaders(headers: Record<string, string[]>): void;
+
+	/**
+	 * Gets the cookie header string for the next request
+	 * @returns Formatted cookie header string
+	 */
+	getCookieRequestHeader(): string;
+}
+
 interface BaseConfiguration {
 	/**
 	 * The directory in the PHP filesystem where the server will look
@@ -95,7 +113,9 @@ export type PHPRequestHandlerConfiguration = BaseConfiguration &
 				 */
 				maxPhpInstances?: number;
 		  }
-	);
+	) & {
+		cookieStore?: CookieStore | false;
+	};
 
 /**
  * Handles HTTP requests using PHP runtime as a backend.
@@ -159,7 +179,7 @@ export class PHPRequestHandler {
 	#HOST: string;
 	#PATHNAME: string;
 	#ABSOLUTE_URL: string;
-	#cookieStore: HttpCookieStore;
+	#cookieStore: CookieStore | false;
 	rewriteRules: RewriteRule[];
 	processManager: PHPProcessManager;
 	getFileNotFoundAction: FileNotFoundGetActionCallback;
@@ -198,7 +218,11 @@ export class PHPRequestHandler {
 				maxPhpInstances: config.maxPhpInstances,
 			});
 		}
-		this.#cookieStore = new HttpCookieStore();
+
+		this.#cookieStore =
+			config.cookieStore === undefined
+				? new HttpCookieStore()
+				: config.cookieStore;
 		this.#DOCROOT = documentRoot;
 
 		const url = new URL(absoluteUrl);
@@ -490,8 +514,10 @@ export class PHPRequestHandler {
 		const headers: Record<string, string> = {
 			host: this.#HOST,
 			...normalizeHeaders(request.headers || {}),
-			cookie: this.#cookieStore.getCookieRequestHeader(),
 		};
+		if (this.#cookieStore) {
+			headers['cookie'] = this.#cookieStore.getCookieRequestHeader();
+		}
 
 		let body = request.body;
 		if (typeof body === 'object' && !(body instanceof Uint8Array)) {
@@ -520,9 +546,11 @@ export class PHPRequestHandler {
 				scriptPath,
 				headers,
 			});
-			this.#cookieStore.rememberCookiesFromResponseHeaders(
-				response.headers
-			);
+			if (this.#cookieStore) {
+				this.#cookieStore.rememberCookiesFromResponseHeaders(
+					response.headers
+				);
+			}
 			return response;
 		} catch (error) {
 			const executionError = error as PHPExecutionFailureError;

packages/playground/cli/src/run-cli.ts

@@ -281,6 +281,7 @@ export async function runCLI(args: RunCLIArgs): Promise<RunCLIServer> {
 						}
 					},
 				},
+				cookieStore: false,
 			});
 			logger.log(`Booted!`);
 

packages/playground/website/src/lib/state/redux/slice-sites.ts

@@ -316,10 +316,11 @@ export const selectSitesLoaded = createSelector(
 			state.sites.opfsSitesLoadingState,
 		(state: { sites: ReturnType<typeof sitesSlice.reducer> }) =>
 			state.sites.firstTemporarySiteCreated,
+		(state) => selectActiveSite(state),
 	],
-	(opfsSitesLoadingState, firstTemporarySiteCreated) =>
+	(opfsSitesLoadingState, firstTemporarySiteCreated, activeSite) =>
 		['loaded', 'error'].includes(opfsSitesLoadingState) &&
-		firstTemporarySiteCreated
+		(activeSite?.metadata.storage !== 'none' || firstTemporarySiteCreated)
 );
 
 export default sitesSlice.reducer;

packages/playground/wordpress/src/boot.ts

@@ -1,4 +1,5 @@
 import {
+	CookieStore,
 	FileNotFoundAction,
 	FileNotFoundGetActionCallback,
 	FileTree,
@@ -92,6 +93,22 @@ export interface BootOptions {
 	 * given request URI.
 	 */
 	getFileNotFoundAction?: FileNotFoundGetActionCallback;
+
+	/**
+	 * The CookieStore instance to use.
+	 *
+	 * If not provided, Playground will use the HttpCookieStore by default.
+	 * The HttpCookieStore persists cookies in an internal store and includes
+	 * them in following requests.
+	 *
+	 * If you don't want Playground to handle cookies, set the cookie store
+	 * to `false`. This is useful for the Node version of Playground, where
+	 * cookies can be handled by the browser.
+	 *
+	 * You can also provide a custom CookieStore implementation by implementing
+	 * the CookieStore interface.
+	 */
+	cookieStore?: CookieStore | false;
 }
 
 /**
@@ -180,6 +197,7 @@ export async function bootWordPress(options: BootOptions) {
 		rewriteRules: wordPressRewriteRules,
 		getFileNotFoundAction:
 			options.getFileNotFoundAction ?? getFileNotFoundActionForWordPress,
+		cookieStore: options.cookieStore,
 	});
 
 	const php = await requestHandler.getPrimaryPhp();