@serwist/sw 9.0.0-preview.21 → 9.0.0-preview.24

package/src/plugins/cacheableResponse/CacheableResponse.ts

@@ -1,141 +0,0 @@
-/*
-  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, getFriendlyURL, logger } from "@serwist/core/internal";
-
-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/cacheable-response",
-          className: "CacheableResponse",
-          funcName: "constructor",
-        });
-      }
-
-      if (config.statuses) {
-        assert!.isArray(config.statuses, {
-          moduleName: "@serwist/cacheable-response",
-          className: "CacheableResponse",
-          funcName: "constructor",
-          paramName: "config.statuses",
-        });
-      }
-
-      if (config.headers) {
-        assert!.isType(config.headers, "object", {
-          moduleName: "@serwist/cacheable-response",
-          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/cacheable-response",
-        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

@@ -1,46 +0,0 @@
-/*
-  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 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

@@ -1,192 +0,0 @@
-/*
-  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 { 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/expiration",
-        className: "CacheExpiration",
-        funcName: "constructor",
-        paramName: "cacheName",
-      });
-
-      if (!(config.maxEntries || config.maxAgeSeconds)) {
-        throw new SerwistError("max-entries-or-age-required", {
-          moduleName: "@serwist/expiration",
-          className: "CacheExpiration",
-          funcName: "constructor",
-        });
-      }
-
-      if (config.maxEntries) {
-        assert!.isType(config.maxEntries, "number", {
-          moduleName: "@serwist/expiration",
-          className: "CacheExpiration",
-          funcName: "constructor",
-          paramName: "config.maxEntries",
-        });
-      }
-
-      if (config.maxAgeSeconds) {
-        assert!.isType(config.maxAgeSeconds, "number", {
-          moduleName: "@serwist/expiration",
-          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/expiration",
-        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

@@ -1,297 +0,0 @@
-/*
-  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 "@serwist/core";
-import { registerQuotaErrorCallback } from "@serwist/core";
-import { assert, SerwistError, getFriendlyURL, logger, privateCacheNames } from "@serwist/core/internal";
-
-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/expiration",
-          className: "ExpirationPlugin",
-          funcName: "constructor",
-        });
-      }
-
-      if (config.maxEntries) {
-        assert!.isType(config.maxEntries, "number", {
-          moduleName: "@serwist/expiration",
-          className: "ExpirationPlugin",
-          funcName: "constructor",
-          paramName: "config.maxEntries",
-        });
-      }
-
-      if (config.maxAgeSeconds) {
-        assert!.isType(config.maxAgeSeconds, "number", {
-          moduleName: "@serwist/expiration",
-          className: "ExpirationPlugin",
-          funcName: "constructor",
-          paramName: "config.maxAgeSeconds",
-        });
-      }
-
-      if (config.maxAgeFrom) {
-        assert!.isType(config.maxAgeFrom, "string", {
-          moduleName: "@serwist/expiration",
-          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/expiration",
-        className: "Plugin",
-        funcName: "cacheDidUpdate",
-        paramName: "cacheName",
-      });
-      assert!.isInstance(request, Request, {
-        moduleName: "@serwist/expiration",
-        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();
-  }
-}