serwist 9.0.0-preview.24

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

@@ -0,0 +1,55 @@
+/*
+  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";
+
+/**
+ * @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/registerQuotaErrorCallback.ts

@@ -0,0 +1,34 @@
+/*
+  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 { assert } from "./utils/assert.js";
+import { logger } from "./utils/logger.js";
+import { quotaErrorCallbacks } from "./models/quotaErrorCallbacks.js";
+
+/**
+ * Adds a function to the set of quotaErrorCallbacks that will be executed if
+ * there's a quota error.
+ *
+ * @param callback
+ */
+// biome-ignore lint/complexity/noBannedTypes: Can't change Function type
+export const registerQuotaErrorCallback = (callback: Function): void => {
+  if (process.env.NODE_ENV !== "production") {
+    assert!.isType(callback, "function", {
+      moduleName: "@serwist/core",
+      funcName: "register",
+      paramName: "callback",
+    });
+  }
+
+  quotaErrorCallbacks.add(callback);
+
+  if (process.env.NODE_ENV !== "production") {
+    logger.log("Registered a callback to respond to quota errors.", callback);
+  }
+};

package/src/setCacheNameDetails.ts

@@ -0,0 +1,53 @@
+/*
+  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 { SerwistError } from "./utils/SerwistError.js";
+import { assert } from "./utils/assert.js";
+import type { PartialCacheNameDetails } from "./utils/cacheNames.js";
+import { cacheNames } from "./utils/cacheNames.js";
+
+/**
+ * Modifies the default cache names used by Serwist packages.
+ * Cache names are generated as `<prefix>-<Cache Name>-<suffix>`.
+ *
+ * @param details
+ */
+export const setCacheNameDetails = (details: PartialCacheNameDetails): void => {
+  if (process.env.NODE_ENV !== "production") {
+    for (const key of Object.keys(details)) {
+      assert!.isType(details[key], "string", {
+        moduleName: "@serwist/core",
+        funcName: "setCacheNameDetails",
+        paramName: `details.${key}`,
+      });
+    }
+
+    if (details.precache?.length === 0) {
+      throw new SerwistError("invalid-cache-name", {
+        cacheNameId: "precache",
+        value: details.precache,
+      });
+    }
+
+    if (details.runtime?.length === 0) {
+      throw new SerwistError("invalid-cache-name", {
+        cacheNameId: "runtime",
+        value: details.runtime,
+      });
+    }
+
+    if (details.googleAnalytics?.length === 0) {
+      throw new SerwistError("invalid-cache-name", {
+        cacheNameId: "googleAnalytics",
+        value: details.googleAnalytics,
+      });
+    }
+  }
+
+  cacheNames.updateDetails(details);
+};

package/src/strategies/CacheFirst.ts

@@ -0,0 +1,88 @@
+/*
+  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 { Strategy } from "./Strategy.js";
+import type { StrategyHandler } from "./StrategyHandler.js";
+import { messages } from "./utils/messages.js";
+
+/**
+ * An implementation of the [cache first](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#cache_first_falling_back_to_network)
+ * request strategy.
+ *
+ * A cache first strategy is useful for assets that have been revisioned,
+ * such as URLs like `/styles/example.a8f5f1.css`, since they
+ * can be cached for long periods of time.
+ *
+ * If the network request fails, and there is no cache match, this will throw
+ * a `SerwistError` exception.
+ */
+export class CacheFirst extends Strategy {
+  /**
+   * @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 logs = [];
+
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(request, Request, {
+        moduleName: "serwist/strategies",
+        className: this.constructor.name,
+        funcName: "makeRequest",
+        paramName: "request",
+      });
+    }
+
+    let response = await handler.cacheMatch(request);
+
+    let error: Error | undefined = undefined;
+    if (!response) {
+      if (process.env.NODE_ENV !== "production") {
+        logs.push(`No response found in the '${this.cacheName}' cache. Will respond with a network request.`);
+      }
+      try {
+        response = await handler.fetchAndCachePut(request);
+      } catch (err) {
+        if (err instanceof Error) {
+          error = err;
+        }
+      }
+
+      if (process.env.NODE_ENV !== "production") {
+        if (response) {
+          logs.push("Got response from network.");
+        } else {
+          logs.push("Unable to get a response from the network.");
+        }
+      }
+    } else {
+      if (process.env.NODE_ENV !== "production") {
+        logs.push(`Found a cached response in the '${this.cacheName}' cache.`);
+      }
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      logger.groupCollapsed(messages.strategyStart(this.constructor.name, request));
+      for (const log of logs) {
+        logger.log(log);
+      }
+      messages.printFinalResponse(response);
+      logger.groupEnd();
+    }
+
+    if (!response) {
+      throw new SerwistError("no-response", { url: request.url, error });
+    }
+    return response;
+  }
+}

package/src/strategies/CacheOnly.ts

@@ -0,0 +1,59 @@
+/*
+  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 { Strategy } from "./Strategy.js";
+import type { StrategyHandler } from "./StrategyHandler.js";
+import { messages } from "./utils/messages.js";
+
+/**
+ * An implementation of the [cache only](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#cache-only)
+ * request strategy.
+ *
+ * This class is useful if you want to take advantage of any Serwist plugin.
+ *
+ * If there is no cache match, this will throw a `SerwistError` exception.
+ */
+export class CacheOnly extends Strategy {
+  /**
+   * @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> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(request, Request, {
+        moduleName: "serwist/strategies",
+        className: this.constructor.name,
+        funcName: "makeRequest",
+        paramName: "request",
+      });
+    }
+
+    const response = await handler.cacheMatch(request);
+
+    if (process.env.NODE_ENV !== "production") {
+      logger.groupCollapsed(messages.strategyStart(this.constructor.name, request));
+      if (response) {
+        logger.log(`Found a cached response in the '${this.cacheName}' cache.`);
+        messages.printFinalResponse(response);
+      } else {
+        logger.log(`No response found in the '${this.cacheName}' cache.`);
+      }
+      logger.groupEnd();
+    }
+
+    if (!response) {
+      throw new SerwistError("no-response", { url: request.url });
+    }
+    return response;
+  }
+}

package/src/strategies/NetworkFirst.ts

@@ -0,0 +1,229 @@
+/*
+  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 type { StrategyOptions } from "./Strategy.js";
+import { Strategy } from "./Strategy.js";
+import type { StrategyHandler } from "./StrategyHandler.js";
+import { cacheOkAndOpaquePlugin } from "./plugins/cacheOkAndOpaquePlugin.js";
+import { messages } from "./utils/messages.js";
+
+export interface NetworkFirstOptions extends StrategyOptions {
+  /**
+   * If set, any network requests that fail to respond within the timeout will fallback to the cache.
+   */
+  networkTimeoutSeconds?: number;
+}
+
+/**
+ * An implementation of the [network first](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#network-first-falling-back-to-cache)
+ * request strategy.
+ *
+ * By default, this strategy will cache responses with a 200 status code as
+ * well as [opaque responses](https://developer.chrome.com/docs/workbox/caching-resources-during-runtime/#opaque-responses).
+ * Opaque responses are are cross-origin requests where the response doesn't
+ * support [CORS](https://enable-cors.org/).
+ *
+ * If the network request fails, and there is no cache match, this will throw
+ * a `SerwistError` exception.
+ */
+export class NetworkFirst extends Strategy {
+  private readonly _networkTimeoutSeconds: number;
+  /**
+   * @param options
+   * This option can be used to combat
+   * "[lie-fi](https://developers.google.com/web/fundamentals/performance/poor-connectivity/#lie-fi)"
+   * scenarios.
+   */
+  constructor(options: NetworkFirstOptions = {}) {
+    super(options);
+
+    // If this instance contains no plugins with a 'cacheWillUpdate' callback,
+    // prepend the `cacheOkAndOpaquePlugin` plugin to the plugins list.
+    if (!this.plugins.some((p) => "cacheWillUpdate" in p)) {
+      this.plugins.unshift(cacheOkAndOpaquePlugin);
+    }
+
+    this._networkTimeoutSeconds = options.networkTimeoutSeconds || 0;
+    if (process.env.NODE_ENV !== "production") {
+      if (this._networkTimeoutSeconds) {
+        assert!.isType(this._networkTimeoutSeconds, "number", {
+          moduleName: "serwist/strategies",
+          className: this.constructor.name,
+          funcName: "constructor",
+          paramName: "networkTimeoutSeconds",
+        });
+      }
+    }
+  }
+
+  /**
+   * @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 logs: any[] = [];
+
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(request, Request, {
+        moduleName: "serwist/strategies",
+        className: this.constructor.name,
+        funcName: "handle",
+        paramName: "makeRequest",
+      });
+    }
+
+    const promises: Promise<Response | undefined>[] = [];
+    let timeoutId: number | undefined;
+
+    if (this._networkTimeoutSeconds) {
+      const { id, promise } = this._getTimeoutPromise({
+        request,
+        logs,
+        handler,
+      });
+      timeoutId = id;
+      promises.push(promise);
+    }
+
+    const networkPromise = this._getNetworkPromise({
+      timeoutId,
+      request,
+      logs,
+      handler,
+    });
+
+    promises.push(networkPromise);
+
+    const response = await handler.waitUntil(
+      (async () => {
+        // Promise.race() will resolve as soon as the first promise resolves.
+        return (
+          (await handler.waitUntil(Promise.race(promises))) ||
+          // If Promise.race() resolved with null, it might be due to a network
+          // timeout + a cache miss. If that were to happen, we'd rather wait until
+          // the networkPromise resolves instead of returning null.
+          // Note that it's fine to await an already-resolved promise, so we don't
+          // have to check to see if it's still "in flight".
+          (await networkPromise)
+        );
+      })(),
+    );
+
+    if (process.env.NODE_ENV !== "production") {
+      logger.groupCollapsed(messages.strategyStart(this.constructor.name, request));
+      for (const log of logs) {
+        logger.log(log);
+      }
+      messages.printFinalResponse(response);
+      logger.groupEnd();
+    }
+
+    if (!response) {
+      throw new SerwistError("no-response", { url: request.url });
+    }
+    return response;
+  }
+
+  /**
+   * @param options
+   * @returns
+   * @private
+   */
+  private _getTimeoutPromise({
+    request,
+    logs,
+    handler,
+  }: {
+    request: Request;
+    /**
+     * A reference to the logs array.
+     */
+    logs: any[];
+    handler: StrategyHandler;
+  }): { promise: Promise<Response | undefined>; id?: number } {
+    // biome-ignore lint/suspicious/noImplicitAnyLet: setTimeout is typed with Node.js's typings, so we can't use number | undefined here.
+    let timeoutId;
+    const timeoutPromise: Promise<Response | undefined> = new Promise((resolve) => {
+      const onNetworkTimeout = async () => {
+        if (process.env.NODE_ENV !== "production") {
+          logs.push(`Timing out the network response at ${this._networkTimeoutSeconds} seconds.`);
+        }
+        resolve(await handler.cacheMatch(request));
+      };
+      timeoutId = setTimeout(onNetworkTimeout, this._networkTimeoutSeconds * 1000);
+    });
+
+    return {
+      promise: timeoutPromise,
+      id: timeoutId,
+    };
+  }
+
+  /**
+   * @param options
+   * @param options.timeoutId
+   * @param options.request
+   * @param options.logs A reference to the logs Array.
+   * @param options.event
+   * @returns
+   *
+   * @private
+   */
+  async _getNetworkPromise({
+    timeoutId,
+    request,
+    logs,
+    handler,
+  }: {
+    request: Request;
+    logs: any[];
+    timeoutId?: number;
+    handler: StrategyHandler;
+  }): Promise<Response | undefined> {
+    let error: Error | undefined = undefined;
+    let response: Response | undefined = undefined;
+    try {
+      response = await handler.fetchAndCachePut(request);
+    } catch (fetchError) {
+      if (fetchError instanceof Error) {
+        error = fetchError;
+      }
+    }
+
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      if (response) {
+        logs.push("Got response from network.");
+      } else {
+        logs.push("Unable to get a response from the network. Will respond " + "with a cached response.");
+      }
+    }
+
+    if (error || !response) {
+      response = await handler.cacheMatch(request);
+
+      if (process.env.NODE_ENV !== "production") {
+        if (response) {
+          logs.push(`Found a cached response in the '${this.cacheName}' cache.`);
+        } else {
+          logs.push(`No response found in the '${this.cacheName}' cache.`);
+        }
+      }
+    }
+
+    return response;
+  }
+}

package/src/strategies/NetworkOnly.ts

@@ -0,0 +1,98 @@
+/*
+  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 { timeout } from "../utils/timeout.js";
+import type { StrategyOptions } from "./Strategy.js";
+import { Strategy } from "./Strategy.js";
+import type { StrategyHandler } from "./StrategyHandler.js";
+import { messages } from "./utils/messages.js";
+
+export interface NetworkOnlyOptions extends Omit<StrategyOptions, "cacheName" | "matchOptions"> {
+  /**
+   * If set, any network requests that fail to respond within the timeout will result in a network error.
+   */
+  networkTimeoutSeconds?: number;
+}
+
+/**
+ * An implementation of the [network only](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#network-only)
+ * request strategy.
+ *
+ * This class is useful if you want to take advantage of any Serwist plugin.
+ *
+ * If the network request fails, this will throw a `SerwistError` exception.
+ */
+export class NetworkOnly extends Strategy {
+  private readonly _networkTimeoutSeconds: number;
+
+  /**
+   * @param options
+   */
+  constructor(options: NetworkOnlyOptions = {}) {
+    super(options);
+
+    this._networkTimeoutSeconds = options.networkTimeoutSeconds || 0;
+  }
+
+  /**
+   * @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> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(request, Request, {
+        moduleName: "serwist/strategies",
+        className: this.constructor.name,
+        funcName: "_handle",
+        paramName: "request",
+      });
+    }
+
+    let error: Error | undefined = undefined;
+    let response: Response | undefined;
+
+    try {
+      const promises: Promise<Response | undefined>[] = [handler.fetch(request)];
+
+      if (this._networkTimeoutSeconds) {
+        const timeoutPromise = timeout(this._networkTimeoutSeconds * 1000) as Promise<undefined>;
+        promises.push(timeoutPromise);
+      }
+
+      response = await Promise.race(promises);
+      if (!response) {
+        throw new Error(`Timed out the network response after ${this._networkTimeoutSeconds} seconds.`);
+      }
+    } catch (err) {
+      if (err instanceof Error) {
+        error = err;
+      }
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      logger.groupCollapsed(messages.strategyStart(this.constructor.name, request));
+      if (response) {
+        logger.log("Got response from network.");
+      } else {
+        logger.log("Unable to get a response from the network.");
+      }
+      messages.printFinalResponse(response);
+      logger.groupEnd();
+    }
+
+    if (!response) {
+      throw new SerwistError("no-response", { url: request.url, error });
+    }
+    return response;
+  }
+}