@serwist/sw 9.0.0-preview.17 → 9.0.0-preview.18

package/src/plugins/precaching/PrecacheFallbackPlugin.ts

@@ -0,0 +1,86 @@
+/*
+  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 { HandlerDidErrorCallbackParam, SerwistPlugin } from "@serwist/core";
+
+import type { PrecacheController } from "../../precaching/PrecacheController.js";
+import { getOrCreatePrecacheController } from "../../precaching/utils/getOrCreatePrecacheController.js";
+
+export interface PrecacheFallbackEntry {
+  /**
+   * A function that checks whether the fallback entry can be used
+   * for a request.
+   */
+  matcher: (param: HandlerDidErrorCallbackParam) => boolean;
+  /**
+   * A precached URL to be used as a fallback.
+   */
+  url: string;
+}
+
+export interface PrecacheFallbackPluginOptions {
+  /**
+   * Precached URLs to be used as the fallback
+   * if the associated strategy can't generate a response.
+   */
+  fallbackUrls: (string | PrecacheFallbackEntry)[];
+  /**
+   * An optional `PrecacheController` instance. If not provided, the default
+   * `PrecacheController` will be used.
+   */
+  precacheController?: PrecacheController;
+}
+
+/**
+ * `PrecacheFallbackPlugin` allows you to specify offline fallbacks
+ * to be used when a given strategy is unable to generate a response.
+ *
+ * It does this by intercepting the `handlerDidError` plugin callback
+ * and returning a precached response, taking the expected revision parameter
+ * into account automatically.
+ *
+ * Unless you explicitly pass in a `PrecacheController` instance to the
+ * constructor, the default instance will be used. Generally speaking, most
+ * developers will end up using the default.
+ */
+export class PrecacheFallbackPlugin implements SerwistPlugin {
+  private readonly _fallbackUrls: (string | PrecacheFallbackEntry)[];
+  private readonly _precacheController: PrecacheController;
+
+  /**
+   * Constructs a new `PrecacheFallbackPlugin` with the associated `fallbackUrls`.
+   *
+   * @param config
+   */
+  constructor({ fallbackUrls, precacheController }: PrecacheFallbackPluginOptions) {
+    this._fallbackUrls = fallbackUrls;
+    this._precacheController = precacheController || getOrCreatePrecacheController();
+  }
+
+  /**
+   * @returns The precache response for one of the fallback URLs, or `undefined` if
+   * nothing satisfies the conditions.
+   * @private
+   */
+  async handlerDidError(param: HandlerDidErrorCallbackParam) {
+    for (const fallback of this._fallbackUrls) {
+      if (typeof fallback === "string") {
+        const fallbackResponse = await this._precacheController.matchPrecache(fallback);
+        if (fallbackResponse !== undefined) {
+          return fallbackResponse;
+        }
+      } else if (fallback.matcher(param)) {
+        const fallbackResponse = await this._precacheController.matchPrecache(fallback.url);
+        if (fallbackResponse !== undefined) {
+          return fallbackResponse;
+        }
+      }
+    }
+    return undefined;
+  }
+}

package/src/plugins/rangeRequests/RangeRequestsPlugin.ts

@@ -0,0 +1,39 @@
+/*
+  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 { SerwistPlugin } from "@serwist/core";
+
+import { createPartialResponse } from "./createPartialResponse.js";
+
+/**
+ * The range request plugin makes it easy for a request with a 'Range' header to
+ * be fulfilled by a cached response.
+ *
+ * It does this by intercepting the `cachedResponseWillBeUsed` plugin callback
+ * and returning the appropriate subset of the cached response body.
+ */
+export class RangeRequestsPlugin implements SerwistPlugin {
+  /**
+   * @param options
+   * @returns If request contains a 'Range' header, then a
+   * new response with status 206 whose body is a subset of `cachedResponse` is
+   * returned. Otherwise, `cachedResponse` is returned as-is.
+   * @private
+   */
+  cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"] = async ({ request, cachedResponse }) => {
+    // Only return a sliced response if there's something valid in the cache,
+    // and there's a Range: header in the request.
+    if (cachedResponse && request.headers.has("range")) {
+      return await createPartialResponse(request, cachedResponse);
+    }
+
+    // If there was no Range: header, or if cachedResponse wasn't valid, just
+    // pass it through as-is.
+    return cachedResponse;
+  };
+}

package/src/plugins/rangeRequests/createPartialResponse.ts

@@ -0,0 +1,92 @@
+/*
+  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, SerwistError, logger } from "@serwist/core/internal";
+
+import { calculateEffectiveBoundaries } from "./utils/calculateEffectiveBoundaries.js";
+import { parseRangeHeader } from "./utils/parseRangeHeader.js";
+
+/**
+ * Given a `Request` and `Response` objects as input, this will return a
+ * promise for a new `Response`.
+ *
+ * If the original `Response` already contains partial content (i.e. it has
+ * a status of 206), then this assumes it already fulfills the `Range:`
+ * requirements, and will return it as-is.
+ *
+ * @param request A request, which should contain a Range:
+ * header.
+ * @param originalResponse A response.
+ * @returns Either a `206 Partial Content` response, with
+ * the response body set to the slice of content specified by the request's
+ * `Range:` header, or a `416 Range Not Satisfiable` response if the
+ * conditions of the `Range:` header can't be met.
+ */
+export const createPartialResponse = async (request: Request, originalResponse: Response): Promise<Response> => {
+  try {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(request, Request, {
+        moduleName: "@serwist/range-requests",
+        funcName: "createPartialResponse",
+        paramName: "request",
+      });
+
+      assert!.isInstance(originalResponse, Response, {
+        moduleName: "@serwist/range-requests",
+        funcName: "createPartialResponse",
+        paramName: "originalResponse",
+      });
+    }
+
+    if (originalResponse.status === 206) {
+      // If we already have a 206, then just pass it through as-is;
+      // see https://github.com/GoogleChrome/workbox/issues/1720
+      return originalResponse;
+    }
+
+    const rangeHeader = request.headers.get("range");
+    if (!rangeHeader) {
+      throw new SerwistError("no-range-header");
+    }
+
+    const boundaries = parseRangeHeader(rangeHeader);
+    const originalBlob = await originalResponse.blob();
+
+    const effectiveBoundaries = calculateEffectiveBoundaries(originalBlob, boundaries.start, boundaries.end);
+
+    const slicedBlob = originalBlob.slice(effectiveBoundaries.start, effectiveBoundaries.end);
+    const slicedBlobSize = slicedBlob.size;
+
+    const slicedResponse = new Response(slicedBlob, {
+      // Status code 206 is for a Partial Content response.
+      // See https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206
+      status: 206,
+      statusText: "Partial Content",
+      headers: originalResponse.headers,
+    });
+
+    slicedResponse.headers.set("Content-Length", String(slicedBlobSize));
+    slicedResponse.headers.set("Content-Range", `bytes ${effectiveBoundaries.start}-${effectiveBoundaries.end - 1}/` + `${originalBlob.size}`);
+
+    return slicedResponse;
+  } catch (error) {
+    if (process.env.NODE_ENV !== "production") {
+      logger.warn("Unable to construct a partial response; returning a " + "416 Range Not Satisfiable response instead.");
+      logger.groupCollapsed("View details here.");
+      logger.log(error);
+      logger.log(request);
+      logger.log(originalResponse);
+      logger.groupEnd();
+    }
+
+    return new Response("", {
+      status: 416,
+      statusText: "Range Not Satisfiable",
+    });
+  }
+};

package/src/plugins/rangeRequests/utils/calculateEffectiveBoundaries.ts

@@ -0,0 +1,58 @@
+/*
+  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, SerwistError } from "@serwist/core/internal";
+
+/**
+ * @param blob A source blob.
+ * @param start The offset to use as the start of the
+ * slice.
+ * @param end The offset to use as the end of the slice.
+ * @returns An object with `start` and `end` properties, reflecting
+ * the effective boundaries to use given the size of the blob.
+ * @private
+ */
+export const calculateEffectiveBoundaries = (blob: Blob, start?: number, end?: number): { start: number; end: number } => {
+  if (process.env.NODE_ENV !== "production") {
+    assert!.isInstance(blob, Blob, {
+      moduleName: "@serwist/range-requests",
+      funcName: "calculateEffectiveBoundaries",
+      paramName: "blob",
+    });
+  }
+
+  const blobSize = blob.size;
+
+  if ((end && end > blobSize) || (start && start < 0)) {
+    throw new SerwistError("range-not-satisfiable", {
+      size: blobSize,
+      end,
+      start,
+    });
+  }
+
+  let effectiveStart: number;
+  let effectiveEnd: number;
+
+  if (start !== undefined && end !== undefined) {
+    effectiveStart = start;
+    // Range values are inclusive, so add 1 to the value.
+    effectiveEnd = end + 1;
+  } else if (start !== undefined && end === undefined) {
+    effectiveStart = start;
+    effectiveEnd = blobSize;
+  } else if (end !== undefined && start === undefined) {
+    effectiveStart = blobSize - end;
+    effectiveEnd = blobSize;
+  }
+
+  return {
+    start: effectiveStart!,
+    end: effectiveEnd!,
+  };
+};

package/src/plugins/rangeRequests/utils/parseRangeHeader.ts

@@ -0,0 +1,54 @@
+/*
+  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, SerwistError } from "@serwist/core/internal";
+
+/**
+ * @param rangeHeader A Range: header value.
+ * @returns An object with `start` and `end` properties, reflecting
+ * the parsed value of the Range: header. If either the `start` or `end` are
+ * omitted, then `null` will be returned.
+ * @private
+ */
+export const parseRangeHeader = (
+  rangeHeader: string,
+): {
+  start?: number;
+  end?: number;
+} => {
+  if (process.env.NODE_ENV !== "production") {
+    assert!.isType(rangeHeader, "string", {
+      moduleName: "@serwist/range-requests",
+      funcName: "parseRangeHeader",
+      paramName: "rangeHeader",
+    });
+  }
+
+  const normalizedRangeHeader = rangeHeader.trim().toLowerCase();
+  if (!normalizedRangeHeader.startsWith("bytes=")) {
+    throw new SerwistError("unit-must-be-bytes", { normalizedRangeHeader });
+  }
+
+  // Specifying multiple ranges separate by commas is valid syntax, but this
+  // library only attempts to handle a single, contiguous sequence of bytes.
+  // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range#Syntax
+  if (normalizedRangeHeader.includes(",")) {
+    throw new SerwistError("single-range-only", { normalizedRangeHeader });
+  }
+
+  const rangeParts = /(\d*)-(\d*)/.exec(normalizedRangeHeader);
+  // We need either at least one of the start or end values.
+  if (!rangeParts || !(rangeParts[1] || rangeParts[2])) {
+    throw new SerwistError("invalid-range-values", { normalizedRangeHeader });
+  }
+
+  return {
+    start: rangeParts[1] === "" ? undefined : Number(rangeParts[1]),
+    end: rangeParts[2] === "" ? undefined : Number(rangeParts[2]),
+  };
+};

package/src/precaching/PrecacheController.ts

@@ -0,0 +1,332 @@
+/*
+  Copyright 2019 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 { RouteHandlerCallback, SerwistPlugin } from "@serwist/core";
+import { assert, SerwistError, logger, privateCacheNames, waitUntil } from "@serwist/core/internal";
+import { parallel } from "@serwist/utils";
+import type { Strategy } from "../strategies/Strategy.js";
+import { PrecacheStrategy } from "./PrecacheStrategy.js";
+import type { CleanupResult, InstallResult, PrecacheEntry } from "./types.js";
+import { PrecacheCacheKeyPlugin } from "./utils/PrecacheCacheKeyPlugin.js";
+import { PrecacheInstallReportPlugin } from "./utils/PrecacheInstallReportPlugin.js";
+import { createCacheKey } from "./utils/createCacheKey.js";
+import { printCleanupDetails } from "./utils/printCleanupDetails.js";
+import { printInstallDetails } from "./utils/printInstallDetails.js";
+
+// Give TypeScript the correct global.
+declare const self: ServiceWorkerGlobalScope;
+
+interface PrecacheControllerOptions {
+  /**
+   * The cache to use for precaching.
+   */
+  cacheName?: string;
+  /**
+   * Plugins to use when precaching as well as responding to fetch
+   * events for precached assets.
+   */
+  plugins?: SerwistPlugin[];
+  /**
+   * Whether to attempt to get the response from the network if there's
+   * a precache miss.
+   */
+  fallbackToNetwork?: boolean;
+  /**
+   * A number of how many precache requests should be made concurrently.
+   *
+   * @default 1
+   */
+  concurrentPrecaching?: number;
+}
+
+/**
+ * Performs efficient precaching of assets.
+ */
+export class PrecacheController {
+  private _installAndActiveListenersAdded?: boolean;
+  private _concurrentPrecaching: number;
+  private readonly _strategy: Strategy;
+  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();
+
+  /**
+   * Create a new PrecacheController.
+   *
+   * @param options
+   */
+  constructor({ cacheName, plugins = [], fallbackToNetwork = true, concurrentPrecaching = 1 }: PrecacheControllerOptions = {}) {
+    this._concurrentPrecaching = concurrentPrecaching;
+    this._strategy = new PrecacheStrategy({
+      cacheName: privateCacheNames.getPrecacheName(cacheName),
+      plugins: [...plugins, new PrecacheCacheKeyPlugin({ precacheController: this })],
+      fallbackToNetwork,
+    });
+    // Bind the install and activate methods to the instance.
+    this.install = this.install.bind(this);
+    this.activate = this.activate.bind(this);
+  }
+
+  /**
+   * 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 precache list, removing any duplicates and
+   * stores the files in the precache cache when the service
+   * worker installs.
+   *
+   * This method can be called multiple times.
+   *
+   * @param entries Array of entries to precache.
+   */
+  precache(entries: (PrecacheEntry | string)[]): void {
+    this.addToCacheList(entries);
+
+    if (!this._installAndActiveListenersAdded) {
+      self.addEventListener("install", this.install);
+      self.addEventListener("activate", this.activate);
+      this._installAndActiveListenersAdded = true;
+    }
+  }
+
+  /**
+   * This method will add items to the precache 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/precaching",
+        className: "PrecacheController",
+        funcName: "addToCacheList",
+        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. Learn more at https://bit.ly/wb-precache`;
+        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);
+        }
+      }
+    }
+  }
+
+  /**
+   * Precaches new and updated assets. Call this method from the service worker
+   * install event.
+   *
+   * Note: this method calls `event.waitUntil()` for you, so you do not need
+   * to call it yourself in your event handlers.
+   *
+   * @param event
+   * @returns
+   */
+  install(event: ExtendableEvent): Promise<InstallResult> {
+    return waitUntil<InstallResult>(event, async () => {
+      const installReportPlugin = new PrecacheInstallReportPlugin();
+      this.strategy.plugins.push(installReportPlugin);
+
+      await parallel(this._concurrentPrecaching, 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);
+      }
+
+      return { updatedURLs, notUpdatedURLs };
+    });
+  }
+
+  /**
+   * Deletes assets that are no longer present in the current precache manifest.
+   * Call this method from the service worker activate event.
+   *
+   * Note: this method calls `event.waitUntil()` for you, so you do not need
+   * to call it yourself in your event handlers.
+   *
+   * @param event
+   * @returns
+   */
+  activate(event: ExtendableEvent): Promise<CleanupResult> {
+    return waitUntil<CleanupResult>(event, async () => {
+      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);
+      }
+
+      return { 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.
+   */
+  getURLsToCacheKeys(): 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.
+   */
+  getCachedURLs(): 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.
+   */
+  getCacheKeyForURL(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.
+   */
+  getIntegrityForCacheKey(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.getCacheKeyForURL(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.getCacheKeyForURL(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);
+    };
+  }
+}