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

package/src/plugins/broadcastUpdate/responsesAreSame.ts

@@ -0,0 +1,48 @@
+/*
+  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 { SerwistError, logger } from "@serwist/core/internal";
+
+/**
+ * Given two responses, compares several header values to see if they are
+ * the same or not.
+ *
+ * @param firstResponse The first response.
+ * @param secondResponse The second response.
+ * @param headersToCheck A list of headers to check.
+ * @returns
+ */
+export const responsesAreSame = (firstResponse: Response, secondResponse: Response, headersToCheck: string[]): boolean => {
+  if (process.env.NODE_ENV !== "production") {
+    if (!(firstResponse instanceof Response && secondResponse instanceof Response)) {
+      throw new SerwistError("invalid-responses-are-same-args");
+    }
+  }
+
+  const atLeastOneHeaderAvailable = headersToCheck.some((header) => {
+    return firstResponse.headers.has(header) && secondResponse.headers.has(header);
+  });
+
+  if (!atLeastOneHeaderAvailable) {
+    if (process.env.NODE_ENV !== "production") {
+      logger.warn("Unable to determine where the response has been updated because none of the headers that would be checked are present.");
+      logger.debug("Attempting to compare the following: ", firstResponse, secondResponse, headersToCheck);
+    }
+
+    // Just return true, indicating the that responses are the same, since we
+    // can't determine otherwise.
+    return true;
+  }
+
+  return headersToCheck.every((header) => {
+    const headerStateComparison = firstResponse.headers.has(header) === secondResponse.headers.has(header);
+    const headerValueComparison = firstResponse.headers.get(header) === secondResponse.headers.get(header);
+
+    return headerStateComparison && headerValueComparison;
+  });
+};

package/src/plugins/broadcastUpdate/types.ts

@@ -0,0 +1,37 @@
+import type { CacheDidUpdateCallbackParam } from "@serwist/core";
+import type { CACHE_UPDATED_MESSAGE_META, CACHE_UPDATED_MESSAGE_TYPE } from "./constants.js";
+
+export interface BroadcastCacheUpdateOptions {
+  /**
+   * A list of headers that will be used to determine whether the responses
+   * differ.
+   *
+   * @default ['content-length', 'etag', 'last-modified']
+   */
+  headersToCheck?: string[];
+  /**
+   * A function whose return value
+   * will be used as the `payload` field in any cache update messages sent
+   * to the window clients.
+   * @param options
+   * @returns
+   */
+  generatePayload?: (options: CacheDidUpdateCallbackParam) => Record<string, any>;
+  /**
+   * If `true` (the default) then all open clients will receive a message. If `false`,
+   * then only the client that make the original request will be notified of the update.
+   *
+   * @default true
+   */
+  notifyAllClients?: boolean;
+}
+
+export type BroadcastPayload = Record<string, any>;
+
+export type BroadcastPayloadGenerator = (options: CacheDidUpdateCallbackParam) => BroadcastPayload;
+
+export interface BroadcastMessage {
+  type: typeof CACHE_UPDATED_MESSAGE_TYPE;
+  meta: typeof CACHE_UPDATED_MESSAGE_META;
+  payload: BroadcastPayload;
+}

package/src/plugins/cacheableResponse/CacheableResponse.ts

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

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

@@ -0,0 +1,192 @@
+/*
+  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.
+  }
+}