serwist 9.0.0-preview.24

package/src/NavigationRoute.ts

@@ -0,0 +1,119 @@
+/*
+  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 { RouteHandler, RouteMatchCallbackOptions } from "./types.js";
+import { assert } from "./utils/assert.js";
+import { logger } from "./utils/logger.js";
+import { Route } from "./Route.js";
+
+export interface NavigationRouteMatchOptions {
+  /**
+   * If any of these patterns
+   * match the URL's pathname and search parameter, the route will handle the
+   * request (assuming the denylist doesn't match).
+   *
+   * @default [/./]
+   */
+  allowlist?: RegExp[];
+  /**
+   * If any of these patterns match, the route will not handle the request (even if a allowlist RegExp matches).
+   */
+  denylist?: RegExp[];
+}
+
+/**
+ * NavigationRoute makes it easy to create a `Route` that matches for browser
+ * [navigation requests](https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests).
+ *
+ * It will only match incoming Requests whose [mode](https://fetch.spec.whatwg.org/#concept-request-mode) is set to `navigate`.
+ *
+ * You can optionally only apply this route to a subset of navigation requests
+ * by using one or both of the `denylist` and `allowlist` parameters.
+ */
+export class NavigationRoute extends Route {
+  private readonly _allowlist: RegExp[];
+  private readonly _denylist: RegExp[];
+
+  /**
+   * If both `denylist` and `allowlist` are provided, the `denylist` will
+   * take precedence and the request will not match this route.
+   *
+   * The regular expressions in `allowlist` and `denylist`
+   * are matched against the concatenated
+   * [`pathname`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/pathname)
+   * and [`search`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/search)
+   * portions of the requested URL.
+   *
+   * *Note*: These RegExps may be evaluated against every destination URL during
+   * a navigation. Avoid using
+   * [complex RegExps](https://github.com/GoogleChrome/workbox/issues/3077),
+   * or else your users may see delays when navigating your site.
+   *
+   * @param handler A callback function that returns a Promise resulting in a Response.
+   * @param options
+   */
+  constructor(handler: RouteHandler, { allowlist = [/./], denylist = [] }: NavigationRouteMatchOptions = {}) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isArrayOfClass(allowlist, RegExp, {
+        moduleName: "serwist",
+        className: "NavigationRoute",
+        funcName: "constructor",
+        paramName: "options.allowlist",
+      });
+      assert!.isArrayOfClass(denylist, RegExp, {
+        moduleName: "serwist",
+        className: "NavigationRoute",
+        funcName: "constructor",
+        paramName: "options.denylist",
+      });
+    }
+
+    super((options: RouteMatchCallbackOptions) => this._match(options), handler);
+
+    this._allowlist = allowlist;
+    this._denylist = denylist;
+  }
+
+  /**
+   * Routes match handler.
+   *
+   * @param options
+   * @returns
+   * @private
+   */
+  private _match({ url, request }: RouteMatchCallbackOptions): boolean {
+    if (request && request.mode !== "navigate") {
+      return false;
+    }
+
+    const pathnameAndSearch = url.pathname + url.search;
+
+    for (const regExp of this._denylist) {
+      if (regExp.test(pathnameAndSearch)) {
+        if (process.env.NODE_ENV !== "production") {
+          logger.log(
+            `The navigation route ${pathnameAndSearch} is not being used, since the URL matches this denylist pattern: ${regExp.toString()}`,
+          );
+        }
+        return false;
+      }
+    }
+
+    if (this._allowlist.some((regExp) => regExp.test(pathnameAndSearch))) {
+      if (process.env.NODE_ENV !== "production") {
+        logger.debug(`The navigation route ${pathnameAndSearch} is being used.`);
+      }
+      return true;
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      logger.log(`The navigation route ${pathnameAndSearch} is not being used, since the URL being navigated to doesn't match the allowlist.`);
+    }
+    return false;
+  }
+}

package/src/PrecacheRoute.ts

@@ -0,0 +1,46 @@
+/*
+  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 { RouteMatchCallback, RouteMatchCallbackOptions } from "./types.js";
+import { getFriendlyURL } from "./utils/getFriendlyURL.js";
+import { logger } from "./utils/logger.js";
+import { Route } from "./Route.js";
+import type { Serwist } from "./Serwist.js";
+import type { PrecacheRouteOptions } from "./types.js";
+import { generateURLVariations } from "./utils/generateURLVariations.js";
+
+/**
+ * A subclass of `Route` that takes a `serwist.Serwist` instance and uses it to match
+ * incoming requests and handle fetching responses from the precache.
+ */
+export class PrecacheRoute extends Route {
+  /**
+   * @param serwist A `PrecacheController`
+   * instance used to both match requests and respond to fetch events.
+   * @param options Options to control how requests are matched
+   * against the list of precached URLs.
+   */
+  constructor(serwist: Serwist, options?: PrecacheRouteOptions) {
+    const match: RouteMatchCallback = ({ request }: RouteMatchCallbackOptions) => {
+      const urlsToCacheKeys = serwist.getUrlsToPrecacheKeys();
+      for (const possibleURL of generateURLVariations(request.url, options)) {
+        const cacheKey = urlsToCacheKeys.get(possibleURL);
+        if (cacheKey) {
+          const integrity = serwist.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, serwist.precacheStrategy);
+  }
+}

package/src/PrecacheStrategy.ts

@@ -0,0 +1,239 @@
+/*
+  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 { SerwistPlugin } from "./types.js";
+import { copyResponse } from "./copyResponse.js";
+import { SerwistError } from "./utils/SerwistError.js";
+import { getFriendlyURL } from "./utils/getFriendlyURL.js";
+import { logger } from "./utils/logger.js";
+import { cacheNames as privateCacheNames } from "./utils/cacheNames.js";
+import type { StrategyOptions } from "./strategies/Strategy.js";
+import { Strategy } from "./strategies/Strategy.js";
+import type { StrategyHandler } from "./strategies/StrategyHandler.js";
+
+interface PrecacheStrategyOptions extends StrategyOptions {
+  /**
+   * Whether to attempt to get the response from the network
+   * if there's a precache miss.
+   */
+  fallbackToNetwork?: boolean;
+}
+
+/**
+ * A `serwist/strategies.Strategy` implementation
+ * specifically designed to both cache and fetch precached assets.
+ *
+ * Note: an instance of this class is created automatically when creating a
+ * `PrecacheController`; it's generally not necessary to create this yourself.
+ */
+export class PrecacheStrategy extends Strategy {
+  private readonly _fallbackToNetwork: boolean;
+
+  static readonly defaultPrecacheCacheabilityPlugin: SerwistPlugin = {
+    async cacheWillUpdate({ response }) {
+      if (!response || response.status >= 400) {
+        return null;
+      }
+
+      return response;
+    },
+  };
+
+  static readonly copyRedirectedCacheableResponsesPlugin: SerwistPlugin = {
+    async cacheWillUpdate({ response }) {
+      return response.redirected ? await copyResponse(response) : response;
+    },
+  };
+
+  /**
+   * @param options
+   */
+  constructor(options: PrecacheStrategyOptions = {}) {
+    options.cacheName = privateCacheNames.getPrecacheName(options.cacheName);
+    super(options);
+
+    this._fallbackToNetwork = options.fallbackToNetwork === false ? false : true;
+
+    // Redirected responses cannot be used to satisfy a navigation request, so
+    // any redirected response must be "copied" rather than cloned, so the new
+    // response doesn't contain the `redirected` flag. See:
+    // https://bugs.chromium.org/p/chromium/issues/detail?id=669363&desc=2#c1
+    this.plugins.push(PrecacheStrategy.copyRedirectedCacheableResponsesPlugin);
+  }
+
+  /**
+   * @private
+   * @param request A request to run this strategy for.
+   * @param handler The event that triggered the request.
+   * @returns
+   */
+  async _handle(request: Request, handler: StrategyHandler): Promise<Response> {
+    const response = await handler.cacheMatch(request);
+    if (response) {
+      return response;
+    }
+
+    // If this is an `install` event for an entry that isn't already cached,
+    // then populate the cache.
+    if (handler.event && handler.event.type === "install") {
+      return await this._handleInstall(request, handler);
+    }
+
+    // Getting here means something went wrong. An entry that should have been
+    // precached wasn't found in the cache.
+    return await this._handleFetch(request, handler);
+  }
+
+  async _handleFetch(request: Request, handler: StrategyHandler): Promise<Response> {
+    let response: Response | undefined = undefined;
+    const params = (handler.params || {}) as {
+      cacheKey?: string;
+      integrity?: string;
+    };
+
+    // Fallback to the network if we're configured to do so.
+    if (this._fallbackToNetwork) {
+      if (process.env.NODE_ENV !== "production") {
+        logger.warn(`The precached response for ${getFriendlyURL(request.url)} in ${this.cacheName} was not found. Falling back to the network.`);
+      }
+
+      const integrityInManifest = params.integrity;
+      const integrityInRequest = request.integrity;
+      const noIntegrityConflict = !integrityInRequest || integrityInRequest === integrityInManifest;
+
+      // Do not add integrity if the original request is no-cors
+      // See https://github.com/GoogleChrome/workbox/issues/3096
+      response = await handler.fetch(
+        new Request(request, {
+          integrity: request.mode !== "no-cors" ? integrityInRequest || integrityInManifest : undefined,
+        }),
+      );
+
+      // It's only "safe" to repair the cache if we're using SRI to guarantee
+      // that the response matches the precache manifest's expectations,
+      // and there's either a) no integrity property in the incoming request
+      // or b) there is an integrity, and it matches the precache manifest.
+      // See https://github.com/GoogleChrome/workbox/issues/2858
+      // Also if the original request users no-cors we don't use integrity.
+      // See https://github.com/GoogleChrome/workbox/issues/3096
+      if (integrityInManifest && noIntegrityConflict && request.mode !== "no-cors") {
+        this._useDefaultCacheabilityPluginIfNeeded();
+        const wasCached = await handler.cachePut(request, response.clone());
+        if (process.env.NODE_ENV !== "production") {
+          if (wasCached) {
+            logger.log(`A response for ${getFriendlyURL(request.url)} was used to "repair" the precache.`);
+          }
+        }
+      }
+    } else {
+      // This shouldn't normally happen, but there are edge cases:
+      // https://github.com/GoogleChrome/workbox/issues/1441
+      throw new SerwistError("missing-precache-entry", {
+        cacheName: this.cacheName,
+        url: request.url,
+      });
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      const cacheKey = params.cacheKey || (await handler.getCacheKey(request, "read"));
+
+      // Serwist is going to handle the route.
+      // print the routing details to the console.
+      logger.groupCollapsed(`Precaching is responding to: ${getFriendlyURL(request.url)}`);
+      logger.log(`Serving the precached url: ${getFriendlyURL(cacheKey instanceof Request ? cacheKey.url : cacheKey)}`);
+
+      logger.groupCollapsed("View request details here.");
+      logger.log(request);
+      logger.groupEnd();
+
+      logger.groupCollapsed("View response details here.");
+      logger.log(response);
+      logger.groupEnd();
+
+      logger.groupEnd();
+    }
+
+    return response;
+  }
+
+  async _handleInstall(request: Request, handler: StrategyHandler): Promise<Response> {
+    this._useDefaultCacheabilityPluginIfNeeded();
+
+    const response = await handler.fetch(request);
+
+    // Make sure we defer cachePut() until after we know the response
+    // should be cached; see https://github.com/GoogleChrome/workbox/issues/2737
+    const wasCached = await handler.cachePut(request, response.clone());
+    if (!wasCached) {
+      // Throwing here will lead to the `install` handler failing, which
+      // we want to do if *any* of the responses aren't safe to cache.
+      throw new SerwistError("bad-precaching-response", {
+        url: request.url,
+        status: response.status,
+      });
+    }
+
+    return response;
+  }
+
+  /**
+   * This method is complex, as there a number of things to account for:
+   *
+   * The `plugins` array can be set at construction, and/or it might be added to
+   * to at any time before the strategy is used.
+   *
+   * At the time the strategy is used (i.e. during an `install` event), there
+   * needs to be at least one plugin that implements `cacheWillUpdate` in the
+   * array, other than `copyRedirectedCacheableResponsesPlugin`.
+   *
+   * - If this method is called and there are no suitable `cacheWillUpdate`
+   * plugins, we need to add `defaultPrecacheCacheabilityPlugin`.
+   *
+   * - If this method is called and there is exactly one `cacheWillUpdate`, then
+   * we don't have to do anything (this might be a previously added
+   * `defaultPrecacheCacheabilityPlugin`, or it might be a custom plugin).
+   *
+   * - If this method is called and there is more than one `cacheWillUpdate`,
+   * then we need to check if one is `defaultPrecacheCacheabilityPlugin`. If so,
+   * we need to remove it. (This situation is unlikely, but it could happen if
+   * the strategy is used multiple times, the first without a `cacheWillUpdate`,
+   * and then later on after manually adding a custom `cacheWillUpdate`.)
+   *
+   * See https://github.com/GoogleChrome/workbox/issues/2737 for more context.
+   *
+   * @private
+   */
+  _useDefaultCacheabilityPluginIfNeeded(): void {
+    let defaultPluginIndex: number | null = null;
+    let cacheWillUpdatePluginCount = 0;
+
+    for (const [index, plugin] of this.plugins.entries()) {
+      // Ignore the copy redirected plugin when determining what to do.
+      if (plugin === PrecacheStrategy.copyRedirectedCacheableResponsesPlugin) {
+        continue;
+      }
+
+      // Save the default plugin's index, in case it needs to be removed.
+      if (plugin === PrecacheStrategy.defaultPrecacheCacheabilityPlugin) {
+        defaultPluginIndex = index;
+      }
+
+      if (plugin.cacheWillUpdate) {
+        cacheWillUpdatePluginCount++;
+      }
+    }
+
+    if (cacheWillUpdatePluginCount === 0) {
+      this.plugins.push(PrecacheStrategy.defaultPrecacheCacheabilityPlugin);
+    } else if (cacheWillUpdatePluginCount > 1 && defaultPluginIndex !== null) {
+      // Only remove the default plugin; multiple custom plugins are allowed.
+      this.plugins.splice(defaultPluginIndex, 1);
+    }
+    // Nothing needs to be done if cacheWillUpdatePluginCount is 1
+  }
+}

package/src/RegExpRoute.ts

@@ -0,0 +1,74 @@
+/*
+  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 { RouteHandler, RouteMatchCallback, RouteMatchCallbackOptions } from "./types.js";
+import { assert } from "./utils/assert.js";
+import { logger } from "./utils/logger.js";
+import { Route } from "./Route.js";
+import type { HTTPMethod } from "./constants.js";
+
+/**
+ * `RegExpRoute` makes it easy to create a regular expression based on a `Route`.
+ *
+ * For same-origin requests the `RegExp` only needs to match part of the URL. For
+ * requests against third-party servers, you must define a `RegExp` that matches
+ * the start of the URL.
+ */
+export class RegExpRoute extends Route {
+  /**
+   * If the regular expression contains
+   * [capture groups](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#grouping-back-references),
+   * the captured values will be passed to the `params` argument.
+   *
+   * @param regExp The regular expression to match against URLs.
+   * @param handler A callback function that returns a Promise resulting in a Response.
+   * @param method The HTTP method to match the Route, defaults to GET.
+   * against.
+   */
+  constructor(regExp: RegExp, handler: RouteHandler, method?: HTTPMethod) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(regExp, RegExp, {
+        moduleName: "serwist",
+        className: "RegExpRoute",
+        funcName: "constructor",
+        paramName: "pattern",
+      });
+    }
+
+    const match: RouteMatchCallback = ({ url }: RouteMatchCallbackOptions) => {
+      const result = regExp.exec(url.href);
+
+      // Return immediately if there's no match.
+      if (!result) {
+        return;
+      }
+
+      // Require that the match start at the first character in the URL string
+      // if it's a cross-origin request.
+      // See https://github.com/GoogleChrome/workbox/issues/281 for the context
+      // behind this behavior.
+      if (url.origin !== location.origin && result.index !== 0) {
+        if (process.env.NODE_ENV !== "production") {
+          logger.debug(
+            `The regular expression '${regExp.toString()}' only partially matched against the cross-origin URL '${url.toString()}'. RegExpRoute's will only handle cross-origin requests if they match the entire URL.`,
+          );
+        }
+
+        return;
+      }
+
+      // If the route matches, but there aren't any capture groups defined, then
+      // this will return [], which is truthy and therefore sufficient to
+      // indicate a match.
+      // If there are capture groups, then it will return their values.
+      return result.slice(1);
+    };
+
+    super(match, handler, method);
+  }
+}

package/src/Route.ts

@@ -0,0 +1,67 @@
+/*
+  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 { RouteHandler, RouteHandlerObject, RouteMatchCallback } from "./types.js";
+import { assert } from "./utils/assert.js";
+import type { HTTPMethod } from "./constants.js";
+import { defaultMethod, validMethods } from "./constants.js";
+import { normalizeHandler } from "./utils/normalizeHandler.js";
+
+/**
+ * A `Route` consists of a pair of callback functions, "match" and "handler".
+ * The "match" callback determine if a route should be used to "handle" a
+ * request by returning a non-falsy value if it can. The "handler" callback
+ * is called when there is a match and should return a Promise that resolves
+ * to a `Response`.
+ */
+export class Route {
+  handler: RouteHandlerObject;
+  match: RouteMatchCallback;
+  method: HTTPMethod;
+  catchHandler?: RouteHandlerObject;
+
+  /**
+   * Constructor for Route class.
+   *
+   * @param match A callback function that determines whether the
+   * route matches a given `fetch` event by returning a non-falsy value.
+   * @param handler A callback function that returns a Promise resolving
+   * to a Response.
+   * @param method The HTTP method to match the Route against. Defaults
+   * to GET.
+   */
+  constructor(match: RouteMatchCallback, handler: RouteHandler, method: HTTPMethod = defaultMethod) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(match, "function", {
+        moduleName: "serwist",
+        className: "Route",
+        funcName: "constructor",
+        paramName: "match",
+      });
+
+      if (method) {
+        assert!.isOneOf(method, validMethods, { paramName: "method" });
+      }
+    }
+
+    // These values are referenced directly by Router so cannot be
+    // altered by minificaton.
+    this.handler = normalizeHandler(handler);
+    this.match = match;
+    this.method = method;
+  }
+
+  /**
+   *
+   * @param handler A callback function that returns a Promise resolving
+   * to a Response.
+   */
+  setCatchHandler(handler: RouteHandler): void {
+    this.catchHandler = normalizeHandler(handler);
+  }
+}