serwist 9.1.1 → 10.0.0-preview.10

package/src/lib/extensions/precache/extension.ts

@@ -0,0 +1,306 @@
+import { parallel } from "@serwist/utils";
+import type { Serwist } from "#lib/core.js";
+import type { Extension } from "#lib/extension.js";
+import { registerRoute } from "#lib/functions/router.js";
+import { assert } from "#utils/assert.js";
+import { createCacheKey } from "#utils/createCacheKey.js";
+import { logger } from "#utils/logger.js";
+import { printCleanupDetails } from "#utils/printCleanupDetails.js";
+import { printInstallDetails } from "#utils/printInstallDetails.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { NavigationRoute } from "../../route.js";
+import type { Strategy } from "../../strategies/Strategy.js";
+import type { RouteHandlerCallback } from "../../types.js";
+import { parsePrecacheOptions } from "./options.js";
+import { PrecacheInstallReportPlugin } from "./plugin-install-report.js";
+import { PrecacheRoute, type PrecacheRouteOptions } from "./route.js";
+import type { PrecacheStrategyOptions } from "./strategy.js";
+import { PrecacheStrategy } from "./strategy.js";
+
+export interface PrecacheEntry {
+  integrity?: string;
+  url: string;
+  revision?: string | null;
+}
+
+export interface PrecacheExtensionOptions {
+  /**
+   * The cache to use for precaching.
+   */
+  cacheName?: string;
+  /**
+   * Whether outdated caches should be removed.
+   *
+   * @default false
+   */
+  cleanupOutdatedCaches?: boolean;
+  /**
+   * The number of precache requests that should be made concurrently.
+   *
+   * @default 10
+   */
+  concurrency?: number;
+  /**
+   * An URL that should point to a HTML file with which navigation requests for URLs that aren't
+   * precached will be fulfilled.
+   */
+  navigateFallback?: string;
+  /**
+   * URLs that should be allowed to use the `navigateFallback` handler.
+   */
+  navigateFallbackAllowlist?: RegExp[];
+  /**
+   * URLs that should not be allowed to use the `navigateFallback` handler. This takes precedence
+   * over `navigateFallbackAllowlist`.
+   */
+  navigateFallbackDenylist?: RegExp[];
+}
+
+export interface PrecacheOptions extends PrecacheStrategyOptions, PrecacheRouteOptions, PrecacheExtensionOptions {
+  entries: (PrecacheEntry | string)[] | undefined;
+}
+
+export class Precache implements Extension {
+  private readonly _urlsToCacheKeys: Map<string, string> = new Map();
+  private readonly _urlsToCacheModes: Map<string, "reload" | "default" | "no-store" | "no-cache" | "force-cache" | "only-if-cached"> = new Map();
+  private readonly _cacheKeysToIntegrities: Map<string, string> = new Map();
+  private readonly _strategy: Strategy;
+  private _options: PrecacheExtensionOptions;
+  private _routeOptions: PrecacheRouteOptions;
+
+  /**
+   * Create a new {@linkcode Precache} instance.
+   *
+   * @param options
+   */
+  constructor(precacheOptions: PrecacheOptions) {
+    const { entries, strategyOptions, routeOptions, extensionOptions: controllerOptions } = parsePrecacheOptions(this, precacheOptions);
+    this.addToCacheList(entries);
+    this._strategy = new PrecacheStrategy(strategyOptions);
+    this._options = controllerOptions;
+    this._routeOptions = routeOptions;
+  }
+
+  /**
+   * The strategy created by this controller and
+   * used to cache assets and respond to `fetch` events.
+   */
+  get strategy(): Strategy {
+    return this._strategy;
+  }
+
+  /**
+   * Adds items to the cache list, removing duplicates and ensuring the information is valid.
+   *
+   * @param entries Array of entries to precache.
+   */
+  addToCacheList(entries: (PrecacheEntry | string)[]): void {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isArray(entries, {
+        moduleName: "serwist",
+        className: "PrecacheController",
+        funcName: "addEntries",
+        paramName: "entries",
+      });
+    }
+
+    const urlsToWarnAbout: string[] = [];
+    for (const entry of entries) {
+      // See https://github.com/GoogleChrome/workbox/issues/2259
+      if (typeof entry === "string") {
+        urlsToWarnAbout.push(entry);
+      } else if (entry && !entry.integrity && entry.revision === undefined) {
+        urlsToWarnAbout.push(entry.url);
+      }
+
+      const { cacheKey, url } = createCacheKey(entry);
+      const cacheMode = typeof entry !== "string" && entry.revision ? "reload" : "default";
+
+      if (this._urlsToCacheKeys.has(url) && this._urlsToCacheKeys.get(url) !== cacheKey) {
+        throw new SerwistError("add-to-cache-list-conflicting-entries", {
+          firstEntry: this._urlsToCacheKeys.get(url),
+          secondEntry: cacheKey,
+        });
+      }
+
+      if (typeof entry !== "string" && entry.integrity) {
+        if (this._cacheKeysToIntegrities.has(cacheKey) && this._cacheKeysToIntegrities.get(cacheKey) !== entry.integrity) {
+          throw new SerwistError("add-to-cache-list-conflicting-integrities", {
+            url,
+          });
+        }
+        this._cacheKeysToIntegrities.set(cacheKey, entry.integrity);
+      }
+
+      this._urlsToCacheKeys.set(url, cacheKey);
+      this._urlsToCacheModes.set(url, cacheMode);
+
+      if (urlsToWarnAbout.length > 0) {
+        const warningMessage = `Serwist is precaching URLs without revision info: ${urlsToWarnAbout.join(
+          ", ",
+        )}\nThis is generally NOT safe, as you risk serving outdated assets.`;
+        if (process.env.NODE_ENV === "production") {
+          // Use console directly to display this warning without bloating
+          // bundle sizes by pulling in all of the logger codebase in prod.
+          console.warn(warningMessage);
+        } else {
+          logger.warn(warningMessage);
+        }
+      }
+    }
+  }
+
+  init({ serwist }: { serwist: Serwist }): void {
+    registerRoute(serwist, new PrecacheRoute(this, this._routeOptions));
+
+    if (this._options.navigateFallback) {
+      registerRoute(
+        serwist,
+        new NavigationRoute(this.createHandlerBoundToUrl(this._options.navigateFallback), {
+          allowlist: this._options.navigateFallbackAllowlist,
+          denylist: this._options.navigateFallbackDenylist,
+        }),
+      );
+    }
+  }
+
+  async install({ event }: { event: ExtendableEvent }): Promise<void> {
+    const installReportPlugin = new PrecacheInstallReportPlugin();
+    this._strategy.plugins.push(installReportPlugin);
+    await parallel(this._options.concurrency!, Array.from(this._urlsToCacheKeys.entries()), async ([url, cacheKey]): Promise<void> => {
+      const integrity = this._cacheKeysToIntegrities.get(cacheKey);
+      const cacheMode = this._urlsToCacheModes.get(url);
+
+      const request = new Request(url, {
+        integrity,
+        cache: cacheMode,
+        credentials: "same-origin",
+      });
+
+      await Promise.all(
+        this._strategy.handleAll({
+          event,
+          request,
+          url: new URL(request.url),
+          params: { cacheKey },
+        }),
+      );
+    });
+
+    const { updatedURLs, notUpdatedURLs } = installReportPlugin;
+
+    if (process.env.NODE_ENV !== "production") {
+      printInstallDetails(updatedURLs, notUpdatedURLs);
+    }
+  }
+
+  async activate(): Promise<void> {
+    const cache = await self.caches.open(this._strategy.cacheName);
+    const currentlyCachedRequests = await cache.keys();
+    const expectedCacheKeys = new Set(this._urlsToCacheKeys.values());
+
+    const deletedCacheRequests: string[] = [];
+
+    for (const request of currentlyCachedRequests) {
+      if (!expectedCacheKeys.has(request.url)) {
+        await cache.delete(request);
+        deletedCacheRequests.push(request.url);
+      }
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      printCleanupDetails(deletedCacheRequests);
+    }
+  }
+
+  /**
+   * Returns a mapping of a precached URL to the corresponding cache key, taking
+   * into account the revision information for the URL.
+   *
+   * @returns A URL to cache key mapping.
+   */
+  getUrlsToPrecacheKeys(): Map<string, string> {
+    return this._urlsToCacheKeys;
+  }
+
+  /**
+   * Returns a list of all the URLs that have been precached by the current
+   * service worker.
+   *
+   * @returns The precached URLs.
+   */
+  getPrecachedUrls(): string[] {
+    return [...this._urlsToCacheKeys.keys()];
+  }
+
+  /**
+   * Returns the cache key used for storing a given URL. If that URL is
+   * unversioned, like "/index.html", then the cache key will be the original
+   * URL with a search parameter appended to it.
+   *
+   * @param url A URL whose cache key you want to look up.
+   * @returns The versioned URL that corresponds to a cache key
+   * for the original URL, or undefined if that URL isn't precached.
+   */
+  getPrecacheKeyForUrl(url: string): string | undefined {
+    const urlObject = new URL(url, location.href);
+    return this._urlsToCacheKeys.get(urlObject.href);
+  }
+
+  /**
+   * @param url A cache key whose SRI you want to look up.
+   * @returns The subresource integrity associated with the cache key,
+   * or undefined if it's not set.
+   */
+  getIntegrityForPrecacheKey(cacheKey: string): string | undefined {
+    return this._cacheKeysToIntegrities.get(cacheKey);
+  }
+
+  /**
+   * This acts as a drop-in replacement for
+   * [`cache.match()`](https://developer.mozilla.org/en-US/docs/Web/API/Cache/match)
+   * with the following differences:
+   *
+   * - It knows what the name of the precache is, and only checks in that cache.
+   * - It allows you to pass in an "original" URL without versioning parameters,
+   * and it will automatically look up the correct cache key for the currently
+   * active revision of that URL.
+   *
+   * E.g., `matchPrecache('index.html')` will find the correct precached
+   * response for the currently active service worker, even if the actual cache
+   * key is `'/index.html?__WB_REVISION__=1234abcd'`.
+   *
+   * @param request The key (without revisioning parameters)
+   * to look up in the precache.
+   * @returns
+   */
+  async matchPrecache(request: string | Request): Promise<Response | undefined> {
+    const url = request instanceof Request ? request.url : request;
+    const cacheKey = this.getPrecacheKeyForUrl(url);
+    if (cacheKey) {
+      const cache = await self.caches.open(this._strategy.cacheName);
+      return cache.match(cacheKey);
+    }
+    return undefined;
+  }
+
+  /**
+   * Returns a function that looks up `url` in the precache (taking into
+   * account revision information), and returns the corresponding `Response`.
+   *
+   * @param url The precached URL which will be used to lookup the response.
+   * @return
+   */
+  createHandlerBoundToUrl(url: string): RouteHandlerCallback {
+    const cacheKey = this.getPrecacheKeyForUrl(url);
+    if (!cacheKey) {
+      throw new SerwistError("non-precached-url", { url });
+    }
+    return (options) => {
+      options.request = new Request(url);
+      options.params = { cacheKey, ...options.params };
+
+      return this._strategy.handle(options);
+    };
+  }
+}

package/src/lib/extensions/precache/options.ts

@@ -0,0 +1,49 @@
+import type { Require } from "@serwist/utils";
+import { privateCacheNames } from "#index.internal";
+import type { Precache, PrecacheExtensionOptions, PrecacheOptions } from "./extension.js";
+import { PrecacheCacheKeyPlugin } from "./plugin-cache-key.js";
+import type { PrecacheRouteOptions } from "./route.js";
+import type { PrecacheStrategyOptions } from "./strategy.js";
+
+export const parsePrecacheOptions = (
+  controller: Precache,
+  {
+    entries,
+    cacheName,
+    plugins,
+    fetchOptions,
+    matchOptions,
+    fallbackToNetwork,
+    directoryIndex,
+    ignoreURLParametersMatching,
+    cleanURLs,
+    urlManipulation,
+    cleanupOutdatedCaches,
+    concurrency,
+    navigateFallback,
+    navigateFallbackAllowlist,
+    navigateFallbackDenylist,
+  }: PrecacheOptions,
+) => ({
+  entries: entries ?? [],
+  strategyOptions: {
+    cacheName: privateCacheNames.getPrecacheName(cacheName),
+    plugins: [...(plugins ?? []), new PrecacheCacheKeyPlugin({ precacheController: controller })],
+    fetchOptions,
+    matchOptions,
+    fallbackToNetwork,
+  } satisfies Require<PrecacheStrategyOptions, "cacheName" | "plugins">,
+  routeOptions: {
+    directoryIndex,
+    ignoreURLParametersMatching,
+    cleanURLs,
+    urlManipulation,
+  } satisfies PrecacheRouteOptions,
+  extensionOptions: {
+    cleanupOutdatedCaches,
+    concurrency: concurrency ?? 10,
+    navigateFallback,
+    navigateFallbackAllowlist,
+    navigateFallbackDenylist,
+  } satisfies Require<PrecacheExtensionOptions, "concurrency">,
+});

package/src/{legacy/utils/PrecacheCacheKeyPlugin.ts → lib/extensions/precache/plugin-cache-key.ts}

@@ -5,9 +5,8 @@
   license that can be found in the LICENSE file or at
   https://opensource.org/licenses/MIT.
 */
-
-import type { SerwistPlugin, SerwistPluginCallbackParam } from "../../types.js";
-import type { PrecacheController } from "../PrecacheController.js";
+import type { StrategyPlugin, StrategyPluginCallbackParam } from "#lib/types.js";
+import type { Precache } from "./extension.js";
 
 /**
  * A plugin, designed to be used with PrecacheController, to translate URLs into
@@ -15,17 +14,17 @@ import type { PrecacheController } from "../PrecacheController.js";
  *
  * @private
  */
-export class PrecacheCacheKeyPlugin implements SerwistPlugin {
-  private readonly _precacheController: PrecacheController;
+export class PrecacheCacheKeyPlugin implements StrategyPlugin {
+  private readonly _precacheController: Precache;
 
-  constructor({ precacheController }: { precacheController: PrecacheController }) {
+  constructor({ precacheController }: { precacheController: Precache }) {
     this._precacheController = precacheController;
   }
 
-  cacheKeyWillBeUsed: SerwistPlugin["cacheKeyWillBeUsed"] = async ({ request, params }: SerwistPluginCallbackParam["cacheKeyWillBeUsed"]) => {
+  cacheKeyWillBeUsed: StrategyPlugin["cacheKeyWillBeUsed"] = async ({ request, params }: StrategyPluginCallbackParam["cacheKeyWillBeUsed"]) => {
     // Params is type any, can't change right now.
     /* eslint-disable */
-    const cacheKey = params?.cacheKey || this._precacheController.getCacheKeyForURL(request.url);
+    const cacheKey = params?.cacheKey || this._precacheController.getPrecacheKeyForUrl(request.url);
     /* eslint-enable */
 
     return cacheKey ? new Request(cacheKey, { headers: request.headers }) : request;

package/src/lib/{precaching/PrecacheFallbackPlugin.ts → extensions/precache/plugin-fallback.ts}

@@ -5,9 +5,9 @@
   license that can be found in the LICENSE file or at
   https://opensource.org/licenses/MIT.
 */
-
-import type { Serwist } from "../../Serwist.js";
-import type { HandlerDidErrorCallbackParam, SerwistPlugin } from "../../types.js";
+import type { Serwist } from "#lib/core.js";
+import { handleRequest } from "#lib/functions/router.js";
+import type { HandlerDidErrorCallbackParam, StrategyPlugin } from "#lib/types.js";
 
 export interface PrecacheFallbackEntry {
   /**
@@ -41,7 +41,7 @@ export interface PrecacheFallbackPluginOptions {
  * and returning a precached response, taking the expected revision parameter
  * into account automatically.
  */
-export class PrecacheFallbackPlugin implements SerwistPlugin {
+export class PrecacheFallbackPlugin implements StrategyPlugin {
   private readonly _fallbackUrls: (string | PrecacheFallbackEntry)[];
   private readonly _serwist: Serwist;
 
@@ -52,6 +52,7 @@ export class PrecacheFallbackPlugin implements SerwistPlugin {
    */
   constructor({ fallbackUrls, serwist }: PrecacheFallbackPluginOptions) {
     this._fallbackUrls = fallbackUrls;
+    // TODO(ducanhgh): remove in v11.
     this._serwist = serwist;
   }
 
@@ -63,14 +64,24 @@ export class PrecacheFallbackPlugin implements SerwistPlugin {
   async handlerDidError(param: HandlerDidErrorCallbackParam) {
     for (const fallback of this._fallbackUrls) {
       if (typeof fallback === "string") {
-        const fallbackResponse = await this._serwist.matchPrecache(fallback);
+        const fallbackResponse = handleRequest(this._serwist, {
+          request: new Request(fallback, {
+            credentials: "same-origin",
+          }),
+          event: param.event,
+        });
         if (fallbackResponse !== undefined) {
-          return fallbackResponse;
+          return await fallbackResponse;
         }
       } else if (fallback.matcher(param)) {
-        const fallbackResponse = await this._serwist.matchPrecache(fallback.url);
+        const fallbackResponse = handleRequest(this._serwist, {
+          request: new Request(fallback.url, {
+            credentials: "same-origin",
+          }),
+          event: param.event,
+        });
         if (fallbackResponse !== undefined) {
-          return fallbackResponse;
+          return await fallbackResponse;
         }
       }
     }

package/src/{utils/PrecacheInstallReportPlugin.ts → lib/extensions/precache/plugin-install-report.ts}

@@ -6,7 +6,7 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { SerwistPlugin, SerwistPluginCallbackParam } from "../types.js";
+import type { StrategyPlugin, StrategyPluginCallbackParam } from "#lib/types.js";
 
 /**
  * A plugin designed to determine the number of assets that were updated (or not updated)
@@ -14,22 +14,22 @@ import type { SerwistPlugin, SerwistPluginCallbackParam } from "../types.js";
  *
  * @private
  */
-export class PrecacheInstallReportPlugin implements SerwistPlugin {
+export class PrecacheInstallReportPlugin implements StrategyPlugin {
   updatedURLs: string[] = [];
   notUpdatedURLs: string[] = [];
 
-  handlerWillStart: SerwistPlugin["handlerWillStart"] = async ({ request, state }: SerwistPluginCallbackParam["handlerWillStart"]) => {
+  handlerWillStart: StrategyPlugin["handlerWillStart"] = async ({ request, state }: StrategyPluginCallbackParam["handlerWillStart"]) => {
     // TODO: `state` should never be undefined...
     if (state) {
       state.originalRequest = request;
     }
   };
 
-  cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"] = async ({
+  cachedResponseWillBeUsed: StrategyPlugin["cachedResponseWillBeUsed"] = async ({
     event,
     state,
     cachedResponse,
-  }: SerwistPluginCallbackParam["cachedResponseWillBeUsed"]) => {
+  }: StrategyPluginCallbackParam["cachedResponseWillBeUsed"]) => {
     if (event.type === "install") {
       if (state?.originalRequest && state.originalRequest instanceof Request) {
         // TODO: `state` should never be undefined...

package/src/lib/extensions/precache/route.ts

@@ -0,0 +1,72 @@
+/*
+  Copyright 2020 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 { Serwist } from "#lib/core.js";
+import { generateURLVariations } from "#utils/generateURLVariations.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
+import { Route } from "../../route.js";
+import type { RouteMatchCallback, RouteMatchCallbackOptions, UrlManipulation } from "../../types.js";
+import type { Precache } from "./extension.js";
+
+export interface PrecacheRouteOptions {
+  /**
+   * Tells Serwist to check the precache for an entry whose URL is the request URL appended
+   * with the specified value. Only applies if the request URL ends with "/".
+   *
+   * @default "index.html"
+   */
+  directoryIndex?: string | null;
+  /**
+   * An array of `RegExp` objects matching search params that should be removed when looking
+   * for a precache match.
+   */
+  ignoreURLParametersMatching?: RegExp[];
+  /**
+   * Tells Serwist to check the precache for an entry whose URL is the request URL appended
+   * with ".html".
+   *
+   * @default true
+   */
+  cleanURLs?: boolean;
+  /**
+   * A function that should take a URL and return an array of alternative URLs that should
+   * be checked for precache matches.
+   */
+  urlManipulation?: UrlManipulation;
+}
+
+/**
+ * A subclass of {@linkcode Route} that takes a {@linkcode Serwist} instance and uses it to match
+ * incoming requests and handle fetching responses from the precache.
+ */
+export class PrecacheRoute extends Route {
+  /**
+   * @param precache A {@linkcode Precache} instance.
+   * @param options Options to control how requests are matched
+   * against the list of precached URLs.
+   */
+  constructor(precache: Precache, options?: PrecacheRouteOptions) {
+    const match: RouteMatchCallback = ({ request }: RouteMatchCallbackOptions) => {
+      const urlsToCacheKeys = precache.getUrlsToPrecacheKeys();
+      for (const possibleURL of generateURLVariations(request.url, options)) {
+        const cacheKey = urlsToCacheKeys.get(possibleURL);
+        if (cacheKey) {
+          const integrity = precache.getIntegrityForPrecacheKey(cacheKey);
+          return { cacheKey, integrity };
+        }
+      }
+      if (process.env.NODE_ENV !== "production") {
+        logger.debug(`Precaching did not find a match for ${getFriendlyURL(request.url)}.`);
+      }
+      return;
+    };
+
+    super(match, precache.strategy);
+  }
+}

package/src/lib/{strategies/PrecacheStrategy.ts → extensions/precache/strategy.ts}

@@ -6,16 +6,16 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { copyResponse } from "../../copyResponse.js";
-import type { SerwistPlugin } from "../../types.js";
-import { SerwistError } from "../../utils/SerwistError.js";
-import { cacheNames as privateCacheNames } from "../../utils/cacheNames.js";
-import { getFriendlyURL } from "../../utils/getFriendlyURL.js";
-import { logger } from "../../utils/logger.js";
-import type { Serwist } from "../../Serwist.js";
-import type { StrategyOptions } from "./Strategy.js";
-import { Strategy } from "./Strategy.js";
-import type { StrategyHandler } from "./StrategyHandler.js";
+import type { Serwist } from "#lib/core.js";
+import type { StrategyPlugin } from "#lib/types.js";
+import { copyResponse } from "#lib/utils.js";
+import { cacheNames as privateCacheNames } from "#utils/cacheNames.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import type { StrategyOptions } from "../../strategies/Strategy.js";
+import { Strategy } from "../../strategies/Strategy.js";
+import type { StrategyHandler } from "../../strategies/StrategyHandler.js";
 
 export interface PrecacheStrategyOptions extends StrategyOptions {
   /**
@@ -39,7 +39,7 @@ export interface PrecacheStrategyOptions extends StrategyOptions {
 export class PrecacheStrategy extends Strategy {
   private readonly _fallbackToNetwork: boolean;
 
-  static readonly defaultPrecacheCacheabilityPlugin: SerwistPlugin = {
+  static readonly defaultPrecacheCacheabilityPlugin: StrategyPlugin = {
     async cacheWillUpdate({ response }) {
       if (!response || response.status >= 400) {
         return null;
@@ -49,7 +49,7 @@ export class PrecacheStrategy extends Strategy {
     },
   };
 
-  static readonly copyRedirectedCacheableResponsesPlugin: SerwistPlugin = {
+  static readonly copyRedirectedCacheableResponsesPlugin: StrategyPlugin = {
     async cacheWillUpdate({ response }) {
       return response.redirected ? await copyResponse(response) : response;
     },