serwist 9.0.0-preview.24

package/src/plugins/cacheableResponse/CacheableResponse.ts

@@ -0,0 +1,144 @@
+/*
+  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 { SerwistError } from "../../utils/SerwistError.js";
+import { getFriendlyURL } from "../../utils/getFriendlyURL.js";
+import { logger } from "../../utils/logger.js";
+
+export interface CacheableResponseOptions {
+  /**
+   * One or more status codes that a `Response` can have to be considered cacheable.
+   */
+  statuses?: number[];
+  /**
+   * A mapping of header names and expected values that a `Response` can have and be
+   * considered cacheable. If multiple headers are provided, only one needs to be present.
+   */
+  headers?: HeadersInit;
+}
+
+/**
+ * Allows you to set up rules determining what status codes and/or headers need
+ * to be present in order for a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+ * to be considered cacheable.
+ */
+export class CacheableResponse {
+  private readonly _statuses?: CacheableResponseOptions["statuses"];
+  private readonly _headers?: Headers;
+
+  /**
+   * To construct a new CacheableResponse instance you must provide at least
+   * one of the `config` properties.
+   *
+   * If both `statuses` and `headers` are specified, then both conditions must
+   * be met for the `Response` to be considered cacheable.
+   *
+   * @param config
+   */
+  constructor(config: CacheableResponseOptions = {}) {
+    if (process.env.NODE_ENV !== "production") {
+      if (!(config.statuses || config.headers)) {
+        throw new SerwistError("statuses-or-headers-required", {
+          moduleName: "serwist/plugins",
+          className: "CacheableResponse",
+          funcName: "constructor",
+        });
+      }
+
+      if (config.statuses) {
+        assert!.isArray(config.statuses, {
+          moduleName: "serwist/plugins",
+          className: "CacheableResponse",
+          funcName: "constructor",
+          paramName: "config.statuses",
+        });
+      }
+
+      if (config.headers) {
+        assert!.isType(config.headers, "object", {
+          moduleName: "serwist/plugins",
+          className: "CacheableResponse",
+          funcName: "constructor",
+          paramName: "config.headers",
+        });
+      }
+    }
+
+    this._statuses = config.statuses;
+    if (config.headers) {
+      this._headers = new Headers(config.headers);
+    }
+  }
+
+  /**
+   * Checks a response to see whether it's cacheable or not.
+   *
+   * @param response The response whose cacheability is being
+   * checked.
+   * @returns `true` if the `Response` is cacheable, and `false`
+   * otherwise.
+   */
+  isResponseCacheable(response: Response): boolean {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(response, Response, {
+        moduleName: "serwist/plugins",
+        className: "CacheableResponse",
+        funcName: "isResponseCacheable",
+        paramName: "response",
+      });
+    }
+
+    let cacheable = true;
+
+    if (this._statuses) {
+      cacheable = this._statuses.includes(response.status);
+    }
+
+    if (this._headers && cacheable) {
+      for (const [headerName, headerValue] of this._headers.entries()) {
+        if (response.headers.get(headerName) !== headerValue) {
+          cacheable = false;
+          break;
+        }
+      }
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      if (!cacheable) {
+        logger.groupCollapsed(
+          `The request for '${getFriendlyURL(response.url)}' returned a response that does not meet the criteria for being cached.`,
+        );
+
+        logger.groupCollapsed("View cacheability criteria here.");
+        logger.log(`Cacheable statuses: ${JSON.stringify(this._statuses)}`);
+        logger.log(`Cacheable headers: ${JSON.stringify(this._headers, null, 2)}`);
+        logger.groupEnd();
+
+        const logFriendlyHeaders: { [key: string]: string } = {};
+        response.headers.forEach((value, key) => {
+          logFriendlyHeaders[key] = value;
+        });
+
+        logger.groupCollapsed("View response status and headers here.");
+        logger.log(`Response status: ${response.status}`);
+        logger.log(`Response headers: ${JSON.stringify(logFriendlyHeaders, null, 2)}`);
+        logger.groupEnd();
+
+        logger.groupCollapsed("View full response details here.");
+        logger.log(response.headers);
+        logger.log(response);
+        logger.groupEnd();
+
+        logger.groupEnd();
+      }
+    }
+
+    return cacheable;
+  }
+}

package/src/plugins/cacheableResponse/CacheableResponsePlugin.ts

@@ -0,0 +1,45 @@
+/*
+  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 "../../types.js";
+import type { CacheableResponseOptions } from "./CacheableResponse.js";
+import { CacheableResponse } from "./CacheableResponse.js";
+
+/**
+ * A class implementing the `cacheWillUpdate` lifecycle callback. This makes it
+ * easier to add in cacheability checks to requests made via Serwist's built-in
+ * strategies.
+ */
+export class CacheableResponsePlugin implements SerwistPlugin {
+  private readonly _cacheableResponse: CacheableResponse;
+
+  /**
+   * To construct a new CacheableResponsePlugin instance you must provide at
+   * least one of the `config` properties.
+   *
+   * If both `statuses` and `headers` are specified, then both conditions must
+   * be met for the `Response` to be considered cacheable.
+   *
+   * @param config
+   */
+  constructor(config: CacheableResponseOptions) {
+    this._cacheableResponse = new CacheableResponse(config);
+  }
+
+  /**
+   * @param options
+   * @returns
+   * @private
+   */
+  cacheWillUpdate: SerwistPlugin["cacheWillUpdate"] = async ({ response }) => {
+    if (this._cacheableResponse.isResponseCacheable(response)) {
+      return response;
+    }
+    return null;
+  };
+}

package/src/plugins/expiration/CacheExpiration.ts

@@ -0,0 +1,193 @@
+/*
+  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 { SerwistError } from "../../utils/SerwistError.js";
+import { logger } from "../../utils/logger.js";
+import { CacheTimestampsModel } from "./models/CacheTimestampsModel.js";
+
+interface CacheExpirationConfig {
+  /**
+   * The maximum number of entries to cache. Entries used the least will
+   * be removed as the maximum is reached.
+   */
+  maxEntries?: number;
+  /**
+   * The maximum age of an entry before it's treated as stale and removed.
+   */
+  maxAgeSeconds?: number;
+  /**
+   * The [`CacheQueryOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Cache/delete#Parameters)
+   * that will be used when calling `delete()` on the cache.
+   */
+  matchOptions?: CacheQueryOptions;
+}
+
+/**
+ * Allows you to expires cached responses based on age or maximum number of entries.
+ * @see https://serwist.pages.dev/docs/expiration/cache-expiration
+ */
+export class CacheExpiration {
+  private _isRunning = false;
+  private _rerunRequested = false;
+  private readonly _maxEntries?: number;
+  private readonly _maxAgeSeconds?: number;
+  private readonly _matchOptions?: CacheQueryOptions;
+  private readonly _cacheName: string;
+  private readonly _timestampModel: CacheTimestampsModel;
+
+  /**
+   * To construct a new CacheExpiration instance you must provide at least
+   * one of the `config` properties.
+   *
+   * @param cacheName Name of the cache to apply restrictions to.
+   * @param config
+   */
+  constructor(cacheName: string, config: CacheExpirationConfig = {}) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(cacheName, "string", {
+        moduleName: "serwist/plugins",
+        className: "CacheExpiration",
+        funcName: "constructor",
+        paramName: "cacheName",
+      });
+
+      if (!(config.maxEntries || config.maxAgeSeconds)) {
+        throw new SerwistError("max-entries-or-age-required", {
+          moduleName: "serwist/plugins",
+          className: "CacheExpiration",
+          funcName: "constructor",
+        });
+      }
+
+      if (config.maxEntries) {
+        assert!.isType(config.maxEntries, "number", {
+          moduleName: "serwist/plugins",
+          className: "CacheExpiration",
+          funcName: "constructor",
+          paramName: "config.maxEntries",
+        });
+      }
+
+      if (config.maxAgeSeconds) {
+        assert!.isType(config.maxAgeSeconds, "number", {
+          moduleName: "serwist/plugins",
+          className: "CacheExpiration",
+          funcName: "constructor",
+          paramName: "config.maxAgeSeconds",
+        });
+      }
+    }
+
+    this._maxEntries = config.maxEntries;
+    this._maxAgeSeconds = config.maxAgeSeconds;
+    this._matchOptions = config.matchOptions;
+    this._cacheName = cacheName;
+    this._timestampModel = new CacheTimestampsModel(cacheName);
+  }
+
+  /**
+   * Expires entries for the given cache and given criteria.
+   */
+  async expireEntries(): Promise<void> {
+    if (this._isRunning) {
+      this._rerunRequested = true;
+      return;
+    }
+    this._isRunning = true;
+
+    const minTimestamp = this._maxAgeSeconds ? Date.now() - this._maxAgeSeconds * 1000 : 0;
+
+    const urlsExpired = await this._timestampModel.expireEntries(minTimestamp, this._maxEntries);
+
+    // Delete URLs from the cache
+    const cache = await self.caches.open(this._cacheName);
+    for (const url of urlsExpired) {
+      await cache.delete(url, this._matchOptions);
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      if (urlsExpired.length > 0) {
+        logger.groupCollapsed(
+          `Expired ${urlsExpired.length} ` +
+            `${urlsExpired.length === 1 ? "entry" : "entries"} and removed ` +
+            `${urlsExpired.length === 1 ? "it" : "them"} from the ` +
+            `'${this._cacheName}' cache.`,
+        );
+        logger.log(`Expired the following ${urlsExpired.length === 1 ? "URL" : "URLs"}:`);
+        for (const url of urlsExpired) {
+          logger.log(`    ${url}`);
+        }
+        logger.groupEnd();
+      } else {
+        logger.debug("Cache expiration ran and found no entries to remove.");
+      }
+    }
+
+    this._isRunning = false;
+    if (this._rerunRequested) {
+      this._rerunRequested = false;
+      void this.expireEntries();
+    }
+  }
+
+  /**
+   * Updates the timestamp for the given URL, allowing it to be correctly
+   * tracked by the class.
+   *
+   * @param url
+   */
+  async updateTimestamp(url: string): Promise<void> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(url, "string", {
+        moduleName: "serwist/plugins",
+        className: "CacheExpiration",
+        funcName: "updateTimestamp",
+        paramName: "url",
+      });
+    }
+
+    await this._timestampModel.setTimestamp(url, Date.now());
+  }
+
+  /**
+   * Checks if a URL has expired or not before it's used.
+   *
+   * This looks the timestamp up in IndexedDB and can be slow.
+   *
+   * Note: This method does not remove an expired entry, call
+   * `expireEntries()` to remove such entries instead.
+   *
+   * @param url
+   * @returns
+   */
+  async isURLExpired(url: string): Promise<boolean> {
+    if (!this._maxAgeSeconds) {
+      if (process.env.NODE_ENV !== "production") {
+        throw new SerwistError("expired-test-without-max-age", {
+          methodName: "isURLExpired",
+          paramName: "maxAgeSeconds",
+        });
+      }
+      return false;
+    }
+    const timestamp = await this._timestampModel.getTimestamp(url);
+    const expireOlderThan = Date.now() - this._maxAgeSeconds * 1000;
+    return timestamp !== undefined ? timestamp < expireOlderThan : true;
+  }
+
+  /**
+   * Removes the IndexedDB used to keep track of cache expiration metadata.
+   */
+  async delete(): Promise<void> {
+    // Make sure we don't attempt another rerun if we're called in the middle of
+    // a cache expiration.
+    this._rerunRequested = false;
+    await this._timestampModel.expireEntries(Number.POSITIVE_INFINITY); // Expires all.
+  }
+}

package/src/plugins/expiration/ExpirationPlugin.ts

@@ -0,0 +1,300 @@
+/*
+  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, CachedResponseWillBeUsedCallbackParam, SerwistPlugin } from "../../types.js";
+import { registerQuotaErrorCallback } from "../../registerQuotaErrorCallback.js";
+import { assert } from "../../utils/assert.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 { CacheExpiration } from "./CacheExpiration.js";
+
+export interface ExpirationPluginOptions {
+  /**
+   * The maximum number of entries to cache. Entries used the least will be removed
+   * as the maximum is reached.
+   */
+  maxEntries?: number;
+  /**
+   * The maximum number of seconds before an entry is treated as stale and removed.
+   */
+  maxAgeSeconds?: number;
+  /**
+   * Determines whether `maxAgeSeconds` should be calculated from when an
+   * entry was last fetched or when it was last used.
+   *
+   * @default "last-fetched"
+   */
+  maxAgeFrom?: "last-fetched" | "last-used";
+  /**
+   * The [`CacheQueryOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Cache/delete#Parameters)
+   * that will be used when calling `delete()` on the cache.
+   */
+  matchOptions?: CacheQueryOptions;
+  /**
+   * Whether to opt this cache into automatic deletion if the available storage quota has been exceeded.
+   */
+  purgeOnQuotaError?: boolean;
+}
+
+/**
+ * This plugin can be used in a `serwist/strategies` Strategy to regularly enforce a
+ * limit on the age and/or the number of cached requests.
+ *
+ * It can only be used with Strategy instances that have a custom `cacheName` property set.
+ * In other words, it can't be used to expire entries in strategies that use the default runtime
+ * cache name.
+ *
+ * Whenever a cached response is used or updated, this plugin will look
+ * at the associated cache and remove any old or extra responses.
+ *
+ * When using `maxAgeSeconds`, responses may be used *once* after expiring
+ * because the expiration clean up will not have occurred until *after* the
+ * cached response has been used. If the response has a "Date" header, then a lightweight expiration
+ * check is performed, and the response will not be used immediately.
+ *
+ * When using `maxEntries`, the least recently requested entry will be removed
+ * from the cache.
+ *
+ * @see https://serwist.pages.dev/docs/expiration/expiration-plugin
+ */
+export class ExpirationPlugin implements SerwistPlugin {
+  private readonly _config: ExpirationPluginOptions;
+  private _cacheExpirations: Map<string, CacheExpiration>;
+
+  /**
+   * @param config
+   */
+  constructor(config: ExpirationPluginOptions = {}) {
+    if (process.env.NODE_ENV !== "production") {
+      if (!(config.maxEntries || config.maxAgeSeconds)) {
+        throw new SerwistError("max-entries-or-age-required", {
+          moduleName: "serwist/plugins",
+          className: "ExpirationPlugin",
+          funcName: "constructor",
+        });
+      }
+
+      if (config.maxEntries) {
+        assert!.isType(config.maxEntries, "number", {
+          moduleName: "serwist/plugins",
+          className: "ExpirationPlugin",
+          funcName: "constructor",
+          paramName: "config.maxEntries",
+        });
+      }
+
+      if (config.maxAgeSeconds) {
+        assert!.isType(config.maxAgeSeconds, "number", {
+          moduleName: "serwist/plugins",
+          className: "ExpirationPlugin",
+          funcName: "constructor",
+          paramName: "config.maxAgeSeconds",
+        });
+      }
+
+      if (config.maxAgeFrom) {
+        assert!.isType(config.maxAgeFrom, "string", {
+          moduleName: "serwist/plugins",
+          className: "ExpirationPlugin",
+          funcName: "constructor",
+          paramName: "config.maxAgeFrom",
+        });
+      }
+    }
+
+    this._config = config;
+    this._cacheExpirations = new Map();
+
+    if (!this._config.maxAgeFrom) {
+      this._config.maxAgeFrom = "last-fetched";
+    }
+
+    if (this._config.purgeOnQuotaError) {
+      registerQuotaErrorCallback(() => this.deleteCacheAndMetadata());
+    }
+  }
+
+  /**
+   * A simple helper method to return a CacheExpiration instance for a given
+   * cache name.
+   *
+   * @param cacheName
+   * @returns
+   * @private
+   */
+  private _getCacheExpiration(cacheName: string): CacheExpiration {
+    if (cacheName === privateCacheNames.getRuntimeName()) {
+      throw new SerwistError("expire-custom-caches-only");
+    }
+
+    let cacheExpiration = this._cacheExpirations.get(cacheName);
+    if (!cacheExpiration) {
+      cacheExpiration = new CacheExpiration(cacheName, this._config);
+      this._cacheExpirations.set(cacheName, cacheExpiration);
+    }
+    return cacheExpiration;
+  }
+
+  /**
+   * A "lifecycle" callback that will be triggered automatically by the
+   * `serwist/strategies` handlers when a `Response` is about to be returned
+   * from a [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) to
+   * the handler. It allows the `Response` to be inspected for freshness and
+   * prevents it from being used if the `Response`'s `Date` header value is
+   * older than the configured `maxAgeSeconds`.
+   *
+   * @param options
+   * @returns `cachedResponse` if it is fresh and `null` if it is stale or
+   * not available.
+   * @private
+   */
+  cachedResponseWillBeUsed({ event, cacheName, request, cachedResponse }: CachedResponseWillBeUsedCallbackParam) {
+    if (!cachedResponse) {
+      return null;
+    }
+
+    const isFresh = this._isResponseDateFresh(cachedResponse);
+
+    // Expire entries to ensure that even if the expiration date has
+    // expired, it'll only be used once.
+    const cacheExpiration = this._getCacheExpiration(cacheName);
+
+    const isMaxAgeFromLastUsed = this._config.maxAgeFrom === "last-used";
+
+    const done = (async () => {
+      // Update the metadata for the request URL to the current timestamp.
+      // Only applies if `maxAgeFrom` is `"last-used"`, since the current
+      // lifecycle callback is `cachedResponseWillBeUsed`.
+      // This needs to be called before `expireEntries()` so as to avoid
+      // this URL being marked as expired.
+      if (isMaxAgeFromLastUsed) {
+        await cacheExpiration.updateTimestamp(request.url);
+      }
+      await cacheExpiration.expireEntries();
+    })();
+    try {
+      event.waitUntil(done);
+    } catch (error) {
+      if (process.env.NODE_ENV !== "production") {
+        if (event instanceof FetchEvent) {
+          logger.warn(`Unable to ensure service worker stays alive when updating cache entry for '${getFriendlyURL(event.request.url)}'.`);
+        }
+      }
+    }
+
+    return isFresh ? cachedResponse : null;
+  }
+
+  /**
+   * @param cachedResponse
+   * @returns
+   * @private
+   */
+  private _isResponseDateFresh(cachedResponse: Response): boolean {
+    const isMaxAgeFromLastUsed = this._config.maxAgeFrom === "last-used";
+    // If `maxAgeFrom` is `"last-used"`, the `Date` header doesn't really
+    // matter since it is about when the response was created.
+    if (isMaxAgeFromLastUsed) {
+      return true;
+    }
+    const now = Date.now();
+    if (!this._config.maxAgeSeconds) {
+      return true;
+    }
+    // Check if the `Date` header will suffice a quick expiration check.
+    // See https://github.com/GoogleChromeLabs/sw-toolbox/issues/164 for
+    // discussion.
+    const dateHeaderTimestamp = this._getDateHeaderTimestamp(cachedResponse);
+    if (dateHeaderTimestamp === null) {
+      // Unable to parse date, so assume it's fresh.
+      return true;
+    }
+    // If we have a valid headerTime, then our response is fresh if the
+    // headerTime plus maxAgeSeconds is greater than the current time.
+    return dateHeaderTimestamp >= now - this._config.maxAgeSeconds * 1000;
+  }
+
+  /**
+   * Extracts the `Date` header and parse it into an useful value.
+   *
+   * @param cachedResponse
+   * @returns
+   * @private
+   */
+  private _getDateHeaderTimestamp(cachedResponse: Response): number | null {
+    if (!cachedResponse.headers.has("date")) {
+      return null;
+    }
+
+    const dateHeader = cachedResponse.headers.get("date")!;
+    const parsedDate = new Date(dateHeader);
+    const headerTime = parsedDate.getTime();
+
+    // If the `Date` header is invalid for some reason, `parsedDate.getTime()`
+    // will return NaN.
+    if (Number.isNaN(headerTime)) {
+      return null;
+    }
+
+    return headerTime;
+  }
+
+  /**
+   * A "lifecycle" callback that will be triggered automatically by the
+   * `serwist/strategies` handlers when an entry is added to a cache.
+   *
+   * @param options
+   * @private
+   */
+  async cacheDidUpdate({ cacheName, request }: CacheDidUpdateCallbackParam) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(cacheName, "string", {
+        moduleName: "serwist/plugins",
+        className: "Plugin",
+        funcName: "cacheDidUpdate",
+        paramName: "cacheName",
+      });
+      assert!.isInstance(request, Request, {
+        moduleName: "serwist/plugins",
+        className: "Plugin",
+        funcName: "cacheDidUpdate",
+        paramName: "request",
+      });
+    }
+
+    const cacheExpiration = this._getCacheExpiration(cacheName);
+    await cacheExpiration.updateTimestamp(request.url);
+    await cacheExpiration.expireEntries();
+  }
+
+  /**
+   * Deletes the underlying `Cache` instance associated with this instance and the metadata
+   * from IndexedDB used to keep track of expiration details for each `Cache` instance.
+   *
+   * When using cache expiration, calling this method is preferable to calling
+   * `caches.delete()` directly, since this will ensure that the IndexedDB
+   * metadata is also cleanly removed and that open IndexedDB instances are deleted.
+   *
+   * Note that if you're *not* using cache expiration for a given cache, calling
+   * `caches.delete()` and passing in the cache's name should be sufficient.
+   * There is no Serwist-specific method needed for cleanup in that case.
+   */
+  async deleteCacheAndMetadata(): Promise<void> {
+    // Do this one at a time instead of all at once via `Promise.all()` to
+    // reduce the chance of inconsistency if a promise rejects.
+    for (const [cacheName, cacheExpiration] of this._cacheExpirations) {
+      await self.caches.delete(cacheName);
+      await cacheExpiration.delete();
+    }
+
+    // Reset this._cacheExpirations to its initial state.
+    this._cacheExpirations = new Map();
+  }
+}