serwist 9.0.0-preview.24

package/src/plugins/backgroundSync/QueueStore.ts

@@ -0,0 +1,160 @@
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+import { assert } from "../../utils/assert.js";
+import type { QueueStoreEntry, UnidentifiedQueueStoreEntry } from "./QueueDb.js";
+import { QueueDb } from "./QueueDb.js";
+
+/**
+ * A class to manage storing requests from a Queue in IndexedDB,
+ * indexed by their queue name for easier access.
+ *
+ * Most developers will not need to access this class directly;
+ * it is exposed for advanced use cases.
+ */
+export class QueueStore {
+  private readonly _queueName: string;
+  private readonly _queueDb: QueueDb;
+
+  /**
+   * Associates this instance with a Queue instance, so entries added can be
+   * identified by their queue name.
+   *
+   * @param queueName
+   */
+  constructor(queueName: string) {
+    this._queueName = queueName;
+    this._queueDb = new QueueDb();
+  }
+
+  /**
+   * Append an entry last in the queue.
+   *
+   * @param entry
+   */
+  async pushEntry(entry: UnidentifiedQueueStoreEntry): Promise<void> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(entry, "object", {
+        moduleName: "serwist/plugins",
+        className: "BackgroundSyncQueueStore",
+        funcName: "pushEntry",
+        paramName: "entry",
+      });
+      assert!.isType(entry.requestData, "object", {
+        moduleName: "serwist/plugins",
+        className: "BackgroundSyncQueueStore",
+        funcName: "pushEntry",
+        paramName: "entry.requestData",
+      });
+    }
+
+    // biome-ignore lint/performance/noDelete: Don't specify an ID since one is automatically generated.
+    delete entry.id;
+    entry.queueName = this._queueName;
+
+    await this._queueDb.addEntry(entry);
+  }
+
+  /**
+   * Prepend an entry first in the queue.
+   *
+   * @param entry
+   */
+  async unshiftEntry(entry: UnidentifiedQueueStoreEntry): Promise<void> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(entry, "object", {
+        moduleName: "serwist/plugins",
+        className: "BackgroundSyncQueueStore",
+        funcName: "unshiftEntry",
+        paramName: "entry",
+      });
+      assert!.isType(entry.requestData, "object", {
+        moduleName: "serwist/plugins",
+        className: "BackgroundSyncQueueStore",
+        funcName: "unshiftEntry",
+        paramName: "entry.requestData",
+      });
+    }
+
+    const firstId = await this._queueDb.getFirstEntryId();
+
+    if (firstId) {
+      // Pick an ID one less than the lowest ID in the object store.
+      entry.id = firstId - 1;
+    } else {
+      // biome-ignore lint/performance/noDelete: Let the auto-incrementor assign the ID.
+      delete entry.id;
+    }
+    entry.queueName = this._queueName;
+
+    await this._queueDb.addEntry(entry);
+  }
+
+  /**
+   * Removes and returns the last entry in the queue matching the `queueName`.
+   *
+   * @returns
+   */
+  async popEntry(): Promise<QueueStoreEntry | undefined> {
+    return this._removeEntry(await this._queueDb.getLastEntryByQueueName(this._queueName));
+  }
+
+  /**
+   * Removes and returns the first entry in the queue matching the `queueName`.
+   *
+   * @returns
+   */
+  async shiftEntry(): Promise<QueueStoreEntry | undefined> {
+    return this._removeEntry(await this._queueDb.getFirstEntryByQueueName(this._queueName));
+  }
+
+  /**
+   * Returns all entries in the store matching the `queueName`.
+   *
+   * @returns
+   */
+  async getAll(): Promise<QueueStoreEntry[]> {
+    return await this._queueDb.getAllEntriesByQueueName(this._queueName);
+  }
+
+  /**
+   * Returns the number of entries in the store matching the `queueName`.
+   *
+   * @returns
+   */
+  async size(): Promise<number> {
+    return await this._queueDb.getEntryCountByQueueName(this._queueName);
+  }
+
+  /**
+   * Deletes the entry for the given ID.
+   *
+   * WARNING: this method does not ensure the deleted entry belongs to this
+   * queue (i.e. matches the `queueName`). But this limitation is acceptable
+   * as this class is not publicly exposed. An additional check would make
+   * this method slower than it needs to be.
+   *
+   * @param id
+   */
+  async deleteEntry(id: number): Promise<void> {
+    await this._queueDb.deleteEntry(id);
+  }
+
+  /**
+   * Removes and returns the first or last entry in the queue (based on the
+   * `direction` argument) matching the `queueName`.
+   *
+   * @returns
+   * @private
+   */
+  async _removeEntry(entry?: QueueStoreEntry): Promise<QueueStoreEntry | undefined> {
+    if (entry) {
+      await this.deleteEntry(entry.id);
+    }
+    return entry;
+  }
+}

package/src/plugins/backgroundSync/StorableRequest.ts

@@ -0,0 +1,142 @@
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+import type { MapLikeObject } from "../../types.js";
+import { assert } from "../../utils/assert.js";
+
+type SerializableProperties = "method" | "referrer" | "referrerPolicy" | "mode" | "credentials" | "cache" | "redirect" | "integrity" | "keepalive";
+
+const serializableProperties: SerializableProperties[] = [
+  "method",
+  "referrer",
+  "referrerPolicy",
+  "mode",
+  "credentials",
+  "cache",
+  "redirect",
+  "integrity",
+  "keepalive",
+];
+
+export interface RequestData extends MapLikeObject {
+  url: string;
+  headers: MapLikeObject;
+  body?: ArrayBuffer;
+}
+
+/**
+ * A class to make it easier to serialize and de-serialize requests so they
+ * can be stored in IndexedDB.
+ *
+ * Most developers will not need to access this class directly;
+ * it is exposed for advanced use cases.
+ */
+export class StorableRequest {
+  private readonly _requestData: RequestData;
+
+  /**
+   * Converts a Request object to a plain object that can be structured
+   * cloned or JSON-stringified.
+   *
+   * @param request
+   * @returns
+   */
+  static async fromRequest(request: Request): Promise<StorableRequest> {
+    const requestData: RequestData = {
+      url: request.url,
+      headers: {},
+    };
+
+    // Set the body if present.
+    if (request.method !== "GET") {
+      // Use ArrayBuffer to support non-text request bodies.
+      // NOTE: we can't use Blobs becuse Safari doesn't support storing
+      // Blobs in IndexedDB in some cases:
+      // https://github.com/dfahlander/Dexie.js/issues/618#issuecomment-398348457
+      requestData.body = await request.clone().arrayBuffer();
+    }
+
+    request.headers.forEach((value, key) => {
+      requestData.headers[key] = value;
+    });
+
+    // Add all other serializable request properties
+    for (const prop of serializableProperties) {
+      if (request[prop] !== undefined) {
+        requestData[prop] = request[prop];
+      }
+    }
+
+    return new StorableRequest(requestData);
+  }
+
+  /**
+   * Accepts an object of request data that can be used to construct a
+   * `Request` but can also be stored in IndexedDB.
+   *
+   * @param requestData An object of request data that includes the `url` plus any relevant properties of
+   * [requestInit](https://fetch.spec.whatwg.org/#requestinit).
+   */
+  constructor(requestData: RequestData) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(requestData, "object", {
+        moduleName: "serwist/plugins",
+        className: "StorableRequest",
+        funcName: "constructor",
+        paramName: "requestData",
+      });
+      assert!.isType(requestData.url, "string", {
+        moduleName: "serwist/plugins",
+        className: "StorableRequest",
+        funcName: "constructor",
+        paramName: "requestData.url",
+      });
+    }
+
+    // If the request's mode is `navigate`, convert it to `same-origin` since
+    // navigation requests can't be constructed via script.
+    if (requestData.mode === "navigate") {
+      requestData.mode = "same-origin";
+    }
+
+    this._requestData = requestData;
+  }
+
+  /**
+   * Returns a deep clone of the instances `_requestData` object.
+   *
+   * @returns
+   */
+  toObject(): RequestData {
+    const requestData = Object.assign({}, this._requestData);
+    requestData.headers = Object.assign({}, this._requestData.headers);
+    if (requestData.body) {
+      requestData.body = requestData.body.slice(0);
+    }
+
+    return requestData;
+  }
+
+  /**
+   * Converts this instance to a Request.
+   *
+   * @returns
+   */
+  toRequest(): Request {
+    return new Request(this._requestData.url, this._requestData);
+  }
+
+  /**
+   * Creates and returns a deep clone of the instance.
+   *
+   * @returns
+   */
+  clone(): StorableRequest {
+    return new StorableRequest(this.toObject());
+  }
+}

package/src/plugins/broadcastUpdate/BroadcastCacheUpdate.ts

@@ -0,0 +1,161 @@
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+import type { CacheDidUpdateCallbackParam } from "../../types.js";
+import { assert } from "../../utils/assert.js";
+import { logger } from "../../utils/logger.js";
+import { resultingClientExists } from "../../utils/resultingClientExists.js";
+import { timeout } from "../../utils/timeout.js";
+import { CACHE_UPDATED_MESSAGE_META, CACHE_UPDATED_MESSAGE_TYPE, defaultHeadersToCheck, defaultNotifyAllClients } from "./constants.js";
+import { responsesAreSame } from "./responsesAreSame.js";
+import type { BroadcastCacheUpdateOptions, BroadcastMessage, BroadcastPayload, BroadcastPayloadGenerator } from "./types.js";
+
+// UA-sniff Safari: https://stackoverflow.com/questions/7944460/detect-safari-browser
+// TODO(philipwalton): remove once this Safari bug fix has been released.
+// https://bugs.webkit.org/show_bug.cgi?id=201169
+const isSafari = typeof navigator !== "undefined" && /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
+
+// Give TypeScript the correct global.
+declare let self: ServiceWorkerGlobalScope;
+/**
+ * Generates the default payload used in update messages. By default the
+ * payload includes the `cacheName` and `updatedURL` fields.
+ *
+ * @returns
+ * @private
+ */
+const defaultPayloadGenerator = (data: CacheDidUpdateCallbackParam): BroadcastPayload => {
+  return {
+    cacheName: data.cacheName,
+    updatedURL: data.request.url,
+  };
+};
+
+/**
+ * A class that uses the `postMessage()` API to inform any open windows/tabs when
+ * a cached response has been updated.
+ *
+ * For efficiency's sake, the underlying response bodies are not compared;
+ * only specific response headers are checked.
+ */
+export class BroadcastCacheUpdate {
+  private readonly _headersToCheck: string[];
+  private readonly _generatePayload: BroadcastPayloadGenerator;
+  private readonly _notifyAllClients: boolean;
+
+  /**
+   * Construct a BroadcastCacheUpdate instance with a specific `channelName` to
+   * broadcast messages on
+   *
+   * @param options
+   */
+  constructor({ generatePayload, headersToCheck, notifyAllClients }: BroadcastCacheUpdateOptions = {}) {
+    this._headersToCheck = headersToCheck || defaultHeadersToCheck;
+    this._generatePayload = generatePayload || defaultPayloadGenerator;
+    this._notifyAllClients = notifyAllClients ?? defaultNotifyAllClients;
+  }
+
+  /**
+   * Compares two responses and sends a message (via `postMessage()`) to all window clients if the
+   * responses differ. Neither of the Responses can be opaque.
+   *
+   * The message that's posted has the following format (where `payload` can
+   * be customized via the `generatePayload` option the instance is created
+   * with):
+   *
+   * ```
+   * {
+   *   type: 'CACHE_UPDATED',
+   *   meta: 'workbox-broadcast-update',
+   *   payload: {
+   *     cacheName: 'the-cache-name',
+   *     updatedURL: 'https://example.com/'
+   *   }
+   * }
+   * ```
+   *
+   * @param options
+   * @returns Resolves once the update is sent.
+   */
+  async notifyIfUpdated(options: CacheDidUpdateCallbackParam): Promise<void> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(options.cacheName, "string", {
+        moduleName: "serwist/plugins",
+        className: "BroadcastCacheUpdate",
+        funcName: "notifyIfUpdated",
+        paramName: "cacheName",
+      });
+      assert!.isInstance(options.newResponse, Response, {
+        moduleName: "serwist/plugins",
+        className: "BroadcastCacheUpdate",
+        funcName: "notifyIfUpdated",
+        paramName: "newResponse",
+      });
+      assert!.isInstance(options.request, Request, {
+        moduleName: "serwist/plugins",
+        className: "BroadcastCacheUpdate",
+        funcName: "notifyIfUpdated",
+        paramName: "request",
+      });
+    }
+
+    // Without two responses there is nothing to compare.
+    if (!options.oldResponse) {
+      return;
+    }
+
+    if (!responsesAreSame(options.oldResponse, options.newResponse, this._headersToCheck)) {
+      if (process.env.NODE_ENV !== "production") {
+        logger.log("Newer response found (and cached) for:", options.request.url);
+      }
+
+      const messageData = {
+        type: CACHE_UPDATED_MESSAGE_TYPE,
+        meta: CACHE_UPDATED_MESSAGE_META,
+        payload: this._generatePayload(options),
+      } satisfies BroadcastMessage;
+
+      // For navigation requests, wait until the new window client exists
+      // before sending the message
+      if (options.request.mode === "navigate") {
+        let resultingClientId: string | undefined;
+        if (options.event instanceof FetchEvent) {
+          resultingClientId = options.event.resultingClientId;
+        }
+
+        const resultingWin = await resultingClientExists(resultingClientId);
+
+        // Safari does not currently implement postMessage buffering and
+        // there's no good way to feature detect that, so to increase the
+        // chances of the message being delivered in Safari, we add a timeout.
+        // We also do this if `resultingClientExists()` didn't return a client,
+        // which means it timed out, so it's worth waiting a bit longer.
+        if (!resultingWin || isSafari) {
+          // 3500 is chosen because (according to CrUX data) 80% of mobile
+          // websites hit the DOMContentLoaded event in less than 3.5 seconds.
+          // And presumably sites implementing service worker are on the
+          // higher end of the performance spectrum.
+          await timeout(3500);
+        }
+      }
+
+      if (this._notifyAllClients) {
+        const windows = await self.clients.matchAll({ type: "window" });
+        for (const win of windows) {
+          win.postMessage(messageData);
+        }
+      } else {
+        // See https://github.com/GoogleChrome/workbox/issues/2895
+        if (options.event instanceof FetchEvent) {
+          const client = await self.clients.get(options.event.clientId);
+          client?.postMessage(messageData);
+        }
+      }
+    }
+  }
+}

package/src/plugins/broadcastUpdate/BroadcastUpdatePlugin.ts

@@ -0,0 +1,42 @@
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+import type { CacheDidUpdateCallbackParam, SerwistPlugin } from "../../types.js";
+import { BroadcastCacheUpdate } from "./BroadcastCacheUpdate.js";
+import type { BroadcastCacheUpdateOptions } from "./types.js";
+
+/**
+ * A class implementing the `cacheDidUpdate` lifecycle callback. It will automatically
+ * broadcast a message whenever a cached response is updated.
+ */
+export class BroadcastUpdatePlugin implements SerwistPlugin {
+  private readonly _broadcastUpdate: BroadcastCacheUpdate;
+
+  /**
+   * Construct a `serwist/plugins.BroadcastCacheUpdate` instance with
+   * the passed options and calls its `notifyIfUpdated` method whenever the
+   * plugin's `cacheDidUpdate` callback is invoked.
+   *
+   * @param options
+   */
+  constructor(options?: BroadcastCacheUpdateOptions) {
+    this._broadcastUpdate = new BroadcastCacheUpdate(options);
+  }
+
+  /**
+   * A "lifecycle" callback that will be triggered automatically by
+   * `@serwist/build.RuntimeCaching` handlers when an entry is
+   * added to a cache.
+   *
+   * @private
+   * @param options The input object to this function.
+   */
+  cacheDidUpdate(options: CacheDidUpdateCallbackParam) {
+    void this._broadcastUpdate.notifyIfUpdated(options);
+  }
+}

package/src/plugins/broadcastUpdate/constants.ts

@@ -0,0 +1,12 @@
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+export const CACHE_UPDATED_MESSAGE_TYPE = "CACHE_UPDATED";
+export const CACHE_UPDATED_MESSAGE_META = "serwist-broadcast-update";
+export const defaultNotifyAllClients = true;
+export const defaultHeadersToCheck = ["content-length", "etag", "last-modified"];

package/src/plugins/broadcastUpdate/responsesAreSame.ts

@@ -0,0 +1,49 @@
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+import { SerwistError } from "../../utils/SerwistError.js";
+import { logger } from "../../utils/logger.js";
+
+/**
+ * Given two responses, compares several header values to see if they are
+ * the same or not.
+ *
+ * @param firstResponse The first response.
+ * @param secondResponse The second response.
+ * @param headersToCheck A list of headers to check.
+ * @returns
+ */
+export const responsesAreSame = (firstResponse: Response, secondResponse: Response, headersToCheck: string[]): boolean => {
+  if (process.env.NODE_ENV !== "production") {
+    if (!(firstResponse instanceof Response && secondResponse instanceof Response)) {
+      throw new SerwistError("invalid-responses-are-same-args");
+    }
+  }
+
+  const atLeastOneHeaderAvailable = headersToCheck.some((header) => {
+    return firstResponse.headers.has(header) && secondResponse.headers.has(header);
+  });
+
+  if (!atLeastOneHeaderAvailable) {
+    if (process.env.NODE_ENV !== "production") {
+      logger.warn("Unable to determine where the response has been updated because none of the headers that would be checked are present.");
+      logger.debug("Attempting to compare the following: ", firstResponse, secondResponse, headersToCheck);
+    }
+
+    // Just return true, indicating the that responses are the same, since we
+    // can't determine otherwise.
+    return true;
+  }
+
+  return headersToCheck.every((header) => {
+    const headerStateComparison = firstResponse.headers.has(header) === secondResponse.headers.has(header);
+    const headerValueComparison = firstResponse.headers.get(header) === secondResponse.headers.get(header);
+
+    return headerStateComparison && headerValueComparison;
+  });
+};

package/src/plugins/broadcastUpdate/types.ts

@@ -0,0 +1,37 @@
+import type { CacheDidUpdateCallbackParam } from "../../types.js";
+import type { CACHE_UPDATED_MESSAGE_META, CACHE_UPDATED_MESSAGE_TYPE } from "./constants.js";
+
+export interface BroadcastCacheUpdateOptions {
+  /**
+   * A list of headers that will be used to determine whether the responses
+   * differ.
+   *
+   * @default ['content-length', 'etag', 'last-modified']
+   */
+  headersToCheck?: string[];
+  /**
+   * A function whose return value
+   * will be used as the `payload` field in any cache update messages sent
+   * to the window clients.
+   * @param options
+   * @returns
+   */
+  generatePayload?: (options: CacheDidUpdateCallbackParam) => Record<string, any>;
+  /**
+   * If `true` (the default) then all open clients will receive a message. If `false`,
+   * then only the client that make the original request will be notified of the update.
+   *
+   * @default true
+   */
+  notifyAllClients?: boolean;
+}
+
+export type BroadcastPayload = Record<string, any>;
+
+export type BroadcastPayloadGenerator = (options: CacheDidUpdateCallbackParam) => BroadcastPayload;
+
+export interface BroadcastMessage {
+  type: typeof CACHE_UPDATED_MESSAGE_TYPE;
+  meta: typeof CACHE_UPDATED_MESSAGE_META;
+  payload: BroadcastPayload;
+}