four-stroke 0.4.1 → 0.5.0

package/.github/workflows/ci.yml

@@ -24,3 +24,5 @@ jobs:
       - run: pnpm tsc --noEmit
 
       - run: pnpm knip
+
+      - run: pnpm test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "four-stroke",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Simple Cloudflare Worker SSR SPA framework",
   "license": "MIT",
   "repository": {

package/src/util/service-worker.ts

@@ -0,0 +1,67 @@
+// For apps whose data requests only work once a service worker at `/auth-service-worker.js`
+// Has rewritten them, adding credentials for example. A page is uncontrolled on the first
+// Visit in a browser, while the worker is still installing, and after a hard reload, and
+// Its requests then bypass the worker; these helpers make them wait until it controls the
+// Page. The worker should call `clients.claim()` on `activate` and on a `CLAIM_MESSAGE`.
+
+export const SERVICE_WORKER_URL = "/auth-service-worker.js",
+  CLAIM_MESSAGE = "claim",
+  CONTROL_TIMEOUT_MS = 10_000;
+
+export interface WorkerContainer {
+  readonly controller: unknown;
+  readonly ready: Promise<{ readonly active: { postMessage: (message: unknown) => void } | null }>;
+  register: (url: string, options: { type: "module" }) => Promise<unknown>;
+  addEventListener: (type: "controllerchange", listener: () => void) => void;
+  removeEventListener: (type: "controllerchange", listener: () => void) => void;
+}
+
+/**
+ * Resolves true once a service worker controls the page, or false when none does within
+ * `timeoutMs`, so a browser without service workers fails its requests rather than
+ * hanging. Registering is idempotent, so every app sharing the worker's scope can call
+ * this without knowing whether another app registered it first.
+ */
+export const whenControlled = async (
+  container: WorkerContainer | undefined,
+  timeoutMs = CONTROL_TIMEOUT_MS,
+): Promise<boolean> => {
+  if (!container) return false;
+  if (container.controller) return true;
+
+  let onChange: (() => void) | undefined, timer: ReturnType<typeof setTimeout> | undefined;
+  const changed = new Promise<boolean>((resolve) => {
+      onChange = () => resolve(true);
+      container.addEventListener("controllerchange", onChange);
+    }),
+    timedOut = new Promise<boolean>((resolve) => {
+      timer = setTimeout(() => resolve(false), timeoutMs);
+    }),
+    claimed = (async () => {
+      await container.register(SERVICE_WORKER_URL, { type: "module" });
+      const registration = await container.ready;
+      if (container.controller) return true;
+      // An active worker claims pages only when it activates, so one that was already
+      // Active when this page loaded is asked to claim it now.
+      registration.active?.postMessage(CLAIM_MESSAGE);
+      return changed;
+    })().catch(() => false);
+
+  try {
+    return await Promise.race([changed, claimed, timedOut]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (onChange) container.removeEventListener("controllerchange", onChange);
+  }
+};
+
+let controlled: Promise<boolean> | null = null;
+
+/** A drop-in `fetch` that waits once per page for the worker, then fetches. */
+export const controlledFetch: typeof fetch = async (input, init) => {
+  controlled ??= whenControlled(
+    typeof navigator === "undefined" ? undefined : navigator.serviceWorker,
+  );
+  if (!(await controlled)) controlled = null;
+  return fetch(input, init);
+};

package/test/service-worker.test.ts

@@ -0,0 +1,79 @@
+import { CLAIM_MESSAGE, SERVICE_WORKER_URL, whenControlled } from "../src/util/service-worker";
+
+import type { WorkerContainer } from "../src/util/service-worker";
+
+interface FakeContainer extends WorkerContainer {
+  controller: unknown;
+  messages: unknown[];
+  registered: string[];
+  listeners: number;
+  takeControl: () => void;
+}
+
+const fakeContainer = ({
+  controlled = false,
+  active = true,
+  registerFails = false,
+}: { controlled?: boolean; active?: boolean; registerFails?: boolean } = {}): FakeContainer => {
+  const listeners = new Set<() => void>(),
+    container: FakeContainer = {
+      controller: controlled ? {} : null,
+      messages: [],
+      registered: [],
+      get listeners() {
+        return listeners.size;
+      },
+      ready: Promise.resolve({
+        active: active
+          ? { postMessage: (message: unknown) => container.messages.push(message) }
+          : null,
+      }),
+      register: async (url) => {
+        if (registerFails) throw new Error("refused");
+        container.registered.push(url);
+      },
+      addEventListener: (_type, listener) => listeners.add(listener),
+      removeEventListener: (_type, listener) => listeners.delete(listener),
+      takeControl: () => {
+        container.controller = {};
+        for (const listener of listeners) listener();
+      },
+    };
+  return container;
+};
+
+describe("waiting for the auth service worker", () => {
+  it("resolves at once when the page is already controlled", async () => {
+    const container = fakeContainer({ controlled: true });
+    await expect(whenControlled(container)).resolves.toBe(true);
+    expect(container.registered).toEqual([]);
+  });
+
+  it("registers the worker and asks it to claim an uncontrolled page", async () => {
+    const container = fakeContainer(),
+      result = whenControlled(container);
+    await vi.waitFor(() => expect(container.messages).toEqual([CLAIM_MESSAGE]));
+    expect(container.registered).toEqual([SERVICE_WORKER_URL]);
+    container.takeControl();
+    await expect(result).resolves.toBe(true);
+    expect(container.listeners).toBe(0);
+  });
+
+  it("resolves when the worker takes control while it is still installing", async () => {
+    const container = fakeContainer({ active: false }),
+      result = whenControlled(container);
+    container.takeControl();
+    await expect(result).resolves.toBe(true);
+  });
+
+  it("gives up after the timeout when no worker takes control", async () => {
+    const container = fakeContainer();
+    await expect(whenControlled(container, 10)).resolves.toBe(false);
+    expect(container.listeners).toBe(0);
+  });
+
+  it("gives up at once when registration is refused or unsupported", async () => {
+    await expect(whenControlled(fakeContainer({ registerFails: true }))).resolves.toBe(false);
+    await expect(whenControlled(undefined)).resolves.toBe(false);
+  });
+});

package/tsconfig.json

@@ -3,7 +3,7 @@
     "erasableSyntaxOnly": true,
     "esModuleInterop": true,
     "isolatedModules": true,
-    "lib": ["ESNext"],
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
     "module": "ESNext",
     "moduleResolution": "bundler",
     "noUncheckedIndexedAccess": true,

package/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({ test: { globals: true } });