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

package/src/routing/Router.ts

@@ -0,0 +1,432 @@
+/*
+  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 { RouteHandler, RouteHandlerCallbackOptions, RouteHandlerObject, RouteMatchCallbackOptions } from "@serwist/core";
+import { assert, SerwistError, getFriendlyURL, logger } from "@serwist/core/internal";
+
+import type { Route } from "./Route.js";
+import type { HTTPMethod } from "./utils/constants.js";
+import { defaultMethod } from "./utils/constants.js";
+import { normalizeHandler } from "./utils/normalizeHandler.js";
+
+declare const self: ServiceWorkerGlobalScope;
+
+type RequestArgs = string | [string, RequestInit?];
+
+interface CacheURLsMessageData {
+  type: string;
+  payload: {
+    urlsToCache: RequestArgs[];
+  };
+}
+
+/**
+ * The Router can be used to process a `FetchEvent` using one or more `@serwist/routing` Route(s),
+ * responding with a `Response` if a matching route exists.
+ *
+ * If no route matches a given a request, the Router will use a "default" handler if one is defined.
+ *
+ * Should the matching Route throw an error, the Router will use a "catch" handler if one is defined to
+ * gracefully deal with issues and respond with a Request.
+ *
+ * If a request matches multiple routes, the **earliest** registered route will
+ * be used to respond to the request.
+ */
+export class Router {
+  private readonly _routes: Map<HTTPMethod, Route[]>;
+  private readonly _defaultHandlerMap: Map<HTTPMethod, RouteHandlerObject>;
+  private _catchHandler?: RouteHandlerObject;
+
+  /**
+   * Initializes a new Router.
+   */
+  constructor() {
+    this._routes = new Map();
+    this._defaultHandlerMap = new Map();
+  }
+
+  /**
+   * @returns routes A `Map` of HTTP method name ('GET', etc.) to an array of all the corresponding `Route`
+   * instances that are registered.
+   */
+  get routes(): Map<HTTPMethod, Route[]> {
+    return this._routes;
+  }
+
+  /**
+   * Adds a fetch event listener to respond to events when a route matches
+   * the event's request.
+   */
+  addFetchListener(): void {
+    self.addEventListener("fetch", (event) => {
+      const { request } = event;
+      const responsePromise = this.handleRequest({ request, event });
+      if (responsePromise) {
+        event.respondWith(responsePromise);
+      }
+    });
+  }
+
+  /**
+   * Adds a message event listener for URLs to cache from the window.
+   * This is useful to cache resources loaded on the page prior to when the
+   * service worker started controlling it.
+   *
+   * The format of the message data sent from the window should be as follows.
+   * Where the `urlsToCache` array may consist of URL strings or an array of
+   * URL string + `requestInit` object (the same as you'd pass to `fetch()`).
+   *
+   * ```
+   * {
+   *   type: 'CACHE_URLS',
+   *   payload: {
+   *     urlsToCache: [
+   *       './script1.js',
+   *       './script2.js',
+   *       ['./script3.js', {mode: 'no-cors'}],
+   *     ],
+   *   },
+   * }
+   * ```
+   */
+  addCacheListener(): void {
+    self.addEventListener("message", (event) => {
+      if (event.data && event.data.type === "CACHE_URLS") {
+        const { payload }: CacheURLsMessageData = event.data;
+
+        if (process.env.NODE_ENV !== "production") {
+          logger.debug("Caching URLs from the window", payload.urlsToCache);
+        }
+
+        const requestPromises = Promise.all(
+          payload.urlsToCache.map((entry: string | [string, RequestInit?]) => {
+            if (typeof entry === "string") {
+              entry = [entry];
+            }
+
+            const request = new Request(...entry);
+            return this.handleRequest({ request, event });
+          }),
+        );
+
+        event.waitUntil(requestPromises);
+
+        // If a MessageChannel was used, reply to the message on success.
+        if (event.ports?.[0]) {
+          void requestPromises.then(() => event.ports[0].postMessage(true));
+        }
+      }
+    });
+  }
+
+  /**
+   * Apply the routing rules to a FetchEvent object to get a Response from an
+   * appropriate Route's handler.
+   *
+   * @param options
+   * @returns A promise is returned if a registered route can handle the request.
+   * If there is no matching route and there's no `defaultHandler`, `undefined`
+   * is returned.
+   */
+  handleRequest({
+    request,
+    event,
+  }: {
+    /**
+     * The request to handle.
+     */
+    request: Request;
+    /**
+     * The event that triggered the request.
+     */
+    event: ExtendableEvent;
+  }): Promise<Response> | undefined {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(request, Request, {
+        moduleName: "@serwist/routing",
+        className: "Router",
+        funcName: "handleRequest",
+        paramName: "options.request",
+      });
+    }
+
+    const url = new URL(request.url, location.href);
+    if (!url.protocol.startsWith("http")) {
+      if (process.env.NODE_ENV !== "production") {
+        logger.debug("The Serwist router only supports URLs that start with 'http'.");
+      }
+      return;
+    }
+
+    const sameOrigin = url.origin === location.origin;
+    const { params, route } = this.findMatchingRoute({
+      event,
+      request,
+      sameOrigin,
+      url,
+    });
+    let handler = route?.handler;
+
+    const debugMessages = [];
+    if (process.env.NODE_ENV !== "production") {
+      if (handler) {
+        debugMessages.push(["Found a route to handle this request:", route]);
+
+        if (params) {
+          debugMessages.push([`Passing the following params to the route's handler:`, params]);
+        }
+      }
+    }
+
+    // If we don't have a handler because there was no matching route, then
+    // fall back to defaultHandler if that's defined.
+    const method = request.method as HTTPMethod;
+    if (!handler && this._defaultHandlerMap.has(method)) {
+      if (process.env.NODE_ENV !== "production") {
+        debugMessages.push(`Failed to find a matching route. Falling back to the default handler for ${method}.`);
+      }
+      handler = this._defaultHandlerMap.get(method);
+    }
+
+    if (!handler) {
+      if (process.env.NODE_ENV !== "production") {
+        // No handler so Serwist will do nothing. If logs is set of debug
+        // i.e. verbose, we should print out this information.
+        logger.debug(`No route found for: ${getFriendlyURL(url)}`);
+      }
+      return;
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      // We have a handler, meaning Serwist is going to handle the route.
+      // print the routing details to the console.
+      logger.groupCollapsed(`Router is responding to: ${getFriendlyURL(url)}`);
+
+      for (const msg of debugMessages) {
+        if (Array.isArray(msg)) {
+          logger.log(...msg);
+        } else {
+          logger.log(msg);
+        }
+      }
+
+      logger.groupEnd();
+    }
+
+    // Wrap in try and catch in case the handle method throws a synchronous
+    // error. It should still callback to the catch handler.
+    let responsePromise: Promise<Response>;
+    try {
+      responsePromise = handler.handle({ url, request, event, params });
+    } catch (err) {
+      responsePromise = Promise.reject(err);
+    }
+
+    // Get route's catch handler, if it exists
+    const catchHandler = route?.catchHandler;
+
+    if (responsePromise instanceof Promise && (this._catchHandler || catchHandler)) {
+      responsePromise = responsePromise.catch(async (err) => {
+        // If there's a route catch handler, process that first
+        if (catchHandler) {
+          if (process.env.NODE_ENV !== "production") {
+            // Still include URL here as it will be async from the console group
+            // and may not make sense without the URL
+            logger.groupCollapsed(`Error thrown when responding to:  ${getFriendlyURL(url)}. Falling back to route's Catch Handler.`);
+            logger.error("Error thrown by:", route);
+            logger.error(err);
+            logger.groupEnd();
+          }
+
+          try {
+            return await catchHandler.handle({ url, request, event, params });
+          } catch (catchErr) {
+            if (catchErr instanceof Error) {
+              err = catchErr;
+            }
+          }
+        }
+
+        if (this._catchHandler) {
+          if (process.env.NODE_ENV !== "production") {
+            // Still include URL here as it will be async from the console group
+            // and may not make sense without the URL
+            logger.groupCollapsed(`Error thrown when responding to:  ${getFriendlyURL(url)}. Falling back to global Catch Handler.`);
+            logger.error("Error thrown by:", route);
+            logger.error(err);
+            logger.groupEnd();
+          }
+          return this._catchHandler.handle({ url, request, event });
+        }
+
+        throw err;
+      });
+    }
+
+    return responsePromise;
+  }
+
+  /**
+   * Checks a request and URL (and optionally an event) against the list of
+   * registered routes, and if there's a match, returns the corresponding
+   * route along with any params generated by the match.
+   *
+   * @param options
+   * @returns An object with `route` and `params` properties. They are populated
+   * if a matching route was found or `undefined` otherwise.
+   */
+  findMatchingRoute({ url, sameOrigin, request, event }: RouteMatchCallbackOptions): {
+    route?: Route;
+    params?: RouteHandlerCallbackOptions["params"];
+  } {
+    const routes = this._routes.get(request.method as HTTPMethod) || [];
+    for (const route of routes) {
+      let params: Promise<any> | undefined;
+      // route.match returns type any, not possible to change right now.
+      const matchResult = route.match({ url, sameOrigin, request, event });
+      if (matchResult) {
+        if (process.env.NODE_ENV !== "production") {
+          // Warn developers that using an async matchCallback is almost always
+          // not the right thing to do.
+          if (matchResult instanceof Promise) {
+            logger.warn(
+              `While routing ${getFriendlyURL(
+                url,
+              )}, an async matchCallback function was used. Please convert the following route to use a synchronous matchCallback function:`,
+              route,
+            );
+          }
+        }
+
+        // See https://github.com/GoogleChrome/workbox/issues/2079
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        params = matchResult;
+        if (Array.isArray(params) && params.length === 0) {
+          // Instead of passing an empty array in as params, use undefined.
+          params = undefined;
+        } else if (
+          matchResult.constructor === Object && // eslint-disable-line
+          Object.keys(matchResult).length === 0
+        ) {
+          // Instead of passing an empty object in as params, use undefined.
+          params = undefined;
+        } else if (typeof matchResult === "boolean") {
+          // For the boolean value true (rather than just something truth-y),
+          // don't set params.
+          // See https://github.com/GoogleChrome/workbox/pull/2134#issuecomment-513924353
+          params = undefined;
+        }
+
+        // Return early if have a match.
+        return { route, params };
+      }
+    }
+    // If no match was found above, return and empty object.
+    return {};
+  }
+
+  /**
+   * Define a default `handler` that's called when no routes explicitly
+   * match the incoming request.
+   *
+   * Each HTTP method ('GET', 'POST', etc.) gets its own default handler.
+   *
+   * Without a default handler, unmatched requests will go against the
+   * network as if there were no service worker present.
+   *
+   * @param handler A callback function that returns a Promise resulting in a Response.
+   * @param method The HTTP method to associate with this default handler. Each method
+   * has its own default. Defaults to GET.
+   */
+  setDefaultHandler(handler: RouteHandler, method: HTTPMethod = defaultMethod): void {
+    this._defaultHandlerMap.set(method, normalizeHandler(handler));
+  }
+
+  /**
+   * If a Route throws an error while handling a request, this `handler`
+   * will be called and given a chance to provide a response.
+   *
+   * @param handler A callback function that returns a Promise resulting
+   * in a Response.
+   */
+  setCatchHandler(handler: RouteHandler): void {
+    this._catchHandler = normalizeHandler(handler);
+  }
+
+  /**
+   * Registers a route with the router.
+   *
+   * @param route The route to register.
+   */
+  registerRoute(route: Route): void {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(route, "object", {
+        moduleName: "@serwist/routing",
+        className: "Router",
+        funcName: "registerRoute",
+        paramName: "route",
+      });
+
+      assert!.hasMethod(route, "match", {
+        moduleName: "@serwist/routing",
+        className: "Router",
+        funcName: "registerRoute",
+        paramName: "route",
+      });
+
+      assert!.isType(route.handler, "object", {
+        moduleName: "@serwist/routing",
+        className: "Router",
+        funcName: "registerRoute",
+        paramName: "route",
+      });
+
+      assert!.hasMethod(route.handler, "handle", {
+        moduleName: "@serwist/routing",
+        className: "Router",
+        funcName: "registerRoute",
+        paramName: "route.handler",
+      });
+
+      assert!.isType(route.method, "string", {
+        moduleName: "@serwist/routing",
+        className: "Router",
+        funcName: "registerRoute",
+        paramName: "route.method",
+      });
+    }
+
+    if (!this._routes.has(route.method)) {
+      this._routes.set(route.method, []);
+    }
+
+    // Give precedence to all of the earlier routes by adding this additional
+    // route to the end of the array.
+    this._routes.get(route.method)!.push(route);
+  }
+
+  /**
+   * Unregisters a route with the router.
+   *
+   * @param route The route to unregister.
+   */
+  unregisterRoute(route: Route): void {
+    if (!this._routes.has(route.method)) {
+      throw new SerwistError("unregister-route-but-not-found-with-method", {
+        method: route.method,
+      });
+    }
+
+    const routeIndex = this._routes.get(route.method)!.indexOf(route);
+    if (routeIndex > -1) {
+      this._routes.get(route.method)!.splice(routeIndex, 1);
+    } else {
+      throw new SerwistError("unregister-route-route-not-registered");
+    }
+  }
+}

package/src/routing/registerRoute.ts

@@ -0,0 +1,33 @@
+/*
+  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 { RouteHandler, RouteMatchCallback } from "@serwist/core";
+
+import { Route } from "./Route.js";
+import type { HTTPMethod } from "./utils/constants.js";
+import { getOrCreateDefaultRouter } from "./utils/getOrCreateDefaultRouter.js";
+import { parseRoute } from "./utils/parseRoute.js";
+
+/**
+ * Registers a RegExp, string, or function with a caching
+ * strategy to a singleton Router instance.
+ *
+ * @param capture If the capture param is a `Route`, all other arguments will be ignored.
+ * @param handler A callback function that returns a Promise resulting in a Response.
+ * This parameter is required if `capture` is not a `Route` object.
+ * @param method The HTTP method to match the Route against. Defaults to GET.
+ * @returns The generated `Route`.
+ */
+export const registerRoute = (capture: RegExp | string | RouteMatchCallback | Route, handler?: RouteHandler, method?: HTTPMethod): Route => {
+  const route = parseRoute(capture, handler, method);
+
+  const defaultRouter = getOrCreateDefaultRouter();
+  defaultRouter.registerRoute(route);
+
+  return route;
+};

package/src/routing/setCatchHandler.ts

@@ -0,0 +1,22 @@
+/*
+  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 { RouteHandler } from "@serwist/core";
+
+import { getOrCreateDefaultRouter } from "./utils/getOrCreateDefaultRouter.js";
+
+/**
+ * If a Route throws an error while handling a request, this `handler`
+ * will be called and given a chance to provide a response.
+ *
+ * @param handler A callback function that returns a Promise resulting in a Response.
+ */
+export const setCatchHandler = (handler: RouteHandler): void => {
+  const defaultRouter = getOrCreateDefaultRouter();
+  defaultRouter.setCatchHandler(handler);
+};

package/src/routing/setDefaultHandler.ts

@@ -0,0 +1,25 @@
+/*
+  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 { RouteHandler } from "@serwist/core";
+
+import { getOrCreateDefaultRouter } from "./utils/getOrCreateDefaultRouter.js";
+
+/**
+ * Defines a default `handler` that's called when no routes explicitly
+ * match the incoming request.
+ *
+ * Without a default handler, unmatched requests will go against the
+ * network as if there were no service worker present.
+ *
+ * @param handler A callback function that returns a Promise resulting in a Response.
+ */
+export const setDefaultHandler = (handler: RouteHandler): void => {
+  const defaultRouter = getOrCreateDefaultRouter();
+  defaultRouter.setDefaultHandler(handler);
+};

package/src/routing/unregisterRoute.ts

@@ -0,0 +1,12 @@
+import type { Route } from "./Route.js";
+import { getOrCreateDefaultRouter } from "./utils/getOrCreateDefaultRouter.js";
+
+/**
+ * Unregisters a route from the singleton Router instance.
+ *
+ * @param route The route to unregister.
+ */
+export const unregisterRoute = (route: Route): void => {
+  const defaultRouter = getOrCreateDefaultRouter();
+  defaultRouter.unregisterRoute(route);
+};

package/src/routing/utils/constants.ts

@@ -0,0 +1,24 @@
+/*
+  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.
+*/
+
+export type HTTPMethod = "DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT";
+
+/**
+ * The default HTTP method, 'GET', used when there's no specific method
+ * configured for a route.
+ *
+ * @private
+ */
+export const defaultMethod = "GET" satisfies HTTPMethod;
+
+/**
+ * The list of valid HTTP methods associated with requests that could be routed.
+ *
+ * @private
+ */
+export const validMethods = ["DELETE", "GET", "HEAD", "PATCH", "POST", "PUT"] satisfies HTTPMethod[];

package/src/routing/utils/getOrCreateDefaultRouter.ts

@@ -0,0 +1,29 @@
+/*
+  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 { Router } from "../Router.js";
+
+let defaultRouter: Router;
+
+/**
+ * Creates a new, singleton Router instance if one does not exist. If one
+ * does already exist, that instance is returned.
+ *
+ * @private
+ * @returns
+ */
+export const getOrCreateDefaultRouter = (): Router => {
+  if (!defaultRouter) {
+    defaultRouter = new Router();
+
+    // The helpers that use the default Router assume these listeners exist.
+    defaultRouter.addFetchListener();
+    defaultRouter.addCacheListener();
+  }
+  return defaultRouter;
+};

package/src/routing/utils/normalizeHandler.ts

@@ -0,0 +1,40 @@
+/*
+  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 { RouteHandler, RouteHandlerObject } from "@serwist/core";
+import { assert } from "@serwist/core/internal";
+
+/**
+ * @param handler Either a function, or an object with a
+ * 'handle' method.
+ * @returns An object with a handle method.
+ *
+ * @private
+ */
+export const normalizeHandler = (handler: RouteHandler): RouteHandlerObject => {
+  if (handler && typeof handler === "object") {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.hasMethod(handler, "handle", {
+        moduleName: "@serwist/routing",
+        className: "Route",
+        funcName: "constructor",
+        paramName: "handler",
+      });
+    }
+    return handler;
+  }
+  if (process.env.NODE_ENV !== "production") {
+    assert!.isType(handler, "function", {
+      moduleName: "@serwist/routing",
+      className: "Route",
+      funcName: "constructor",
+      paramName: "handler",
+    });
+  }
+  return { handle: handler };
+};

package/src/routing/utils/parseRoute.ts

@@ -0,0 +1,67 @@
+import type { RouteHandler, RouteMatchCallback } from "@serwist/core";
+import { SerwistError, logger } from "@serwist/core/internal";
+
+import { RegExpRoute } from "../RegExpRoute.js";
+import { Route } from "../Route.js";
+import type { HTTPMethod } from "./constants.js";
+
+export const parseRoute = (capture: RegExp | string | RouteMatchCallback | Route, handler?: RouteHandler, method?: HTTPMethod): Route => {
+  let route: Route;
+
+  if (typeof capture === "string") {
+    const captureUrl = new URL(capture, location.href);
+
+    if (process.env.NODE_ENV !== "production") {
+      if (!(capture.startsWith("/") || capture.startsWith("http"))) {
+        throw new SerwistError("invalid-string", {
+          moduleName: "@serwist/routing",
+          funcName: "registerRoute",
+          paramName: "capture",
+        });
+      }
+
+      // We want to check if Express-style wildcards are in the pathname only.
+      // TODO: Remove this log message in v4.
+      const valueToCheck = capture.startsWith("http") ? captureUrl.pathname : capture;
+
+      // See https://github.com/pillarjs/path-to-regexp#parameters
+      const wildcards = "[*:?+]";
+      if (new RegExp(`${wildcards}`).exec(valueToCheck)) {
+        logger.debug(
+          `The '$capture' parameter contains an Express-style wildcard character (${wildcards}). Strings are now always interpreted as exact matches; use a RegExp for partial or wildcard matches.`,
+        );
+      }
+    }
+
+    const matchCallback: RouteMatchCallback = ({ url }) => {
+      if (process.env.NODE_ENV !== "production") {
+        if (url.pathname === captureUrl.pathname && url.origin !== captureUrl.origin) {
+          logger.debug(
+            `${capture} only partially matches the cross-origin URL ${url.toString()}. This route will only handle cross-origin requests if they match the entire URL.`,
+          );
+        }
+      }
+
+      return url.href === captureUrl.href;
+    };
+
+    // If `capture` is a string then `handler` and `method` must be present.
+    route = new Route(matchCallback, handler!, method);
+  } else if (capture instanceof RegExp) {
+    // If `capture` is a `RegExp` then `handler` and `method` must be present.
+    route = new RegExpRoute(capture, handler!, method);
+  } else if (typeof capture === "function") {
+    // If `capture` is a function then `handler` and `method` must be present.
+    route = new Route(capture, handler!, method);
+  } else if (capture instanceof Route) {
+    route = capture;
+  } else {
+    throw new SerwistError("unsupported-route-type", {
+      moduleName: "@serwist/routing",
+      funcName: "registerRoute",
+      paramName: "capture",
+    });
+  }
+
+  return route;
+};