@loopback/rest 4.0.0-alpha.8 → 5.0.1

package/src/router/routing-table.ts

@@ -1,108 +1,88 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
+// Copyright IBM Corp. 2017,2020. All Rights Reserved.
 // Node module: @loopback/rest
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
 import {
+  ControllerSpec,
   OperationObject,
   ParameterObject,
-  PathsObject,
-} from '@loopback/openapi-spec';
-import {Context, Constructor, instantiateClass} from '@loopback/context';
-import {ServerRequest} from 'http';
-import * as HttpErrors from 'http-errors';
-
+  PathObject,
+} from '@loopback/openapi-v3';
+import debugFactory from 'debug';
+import HttpErrors from 'http-errors';
+import {Request} from '../types';
 import {
-  ParsedRequest,
-  PathParameterValues,
-  OperationArgs,
-  OperationRetval,
-} from '../internal-types';
-
-import {ControllerSpec} from './metadata';
-
-import * as assert from 'assert';
-import * as url from 'url';
-const debug = require('debug')('loopback:core:routing-table');
-
-// TODO(bajtos) Refactor this code to use Trie-based lookup,
-// e.g. via wayfarer/trie or find-my-way
-// See https://github.com/strongloop/loopback-next/issues/98
-import * as pathToRegexp from 'path-to-regexp';
+  ControllerClass,
+  ControllerFactory,
+  createRoutesForController,
+} from './controller-route';
+import {ExternalExpressRoutes} from './external-express-routes';
+import {validateApiPath} from './openapi-path';
+import {RestRouter} from './rest-router';
+import {ResolvedRoute, RouteEntry} from './route-entry';
+import {TrieRouter} from './trie-router';
+
+const debug = debugFactory('loopback:rest:routing-table');
 
 /**
- * Parse the URL of the incoming request and set additional properties
- * on this request object:
- *  - `path`
- *  - `query`
- *
- * @private
- * @param request
+ * Routing table
  */
-export function parseRequestUrl(request: ServerRequest): ParsedRequest {
-  // TODO(bajtos) The following parsing can be skipped when the router
-  // is mounted on an express app
-  const parsedRequest = request as ParsedRequest;
-  const parsedUrl = url.parse(parsedRequest.url, true);
-  parsedRequest.path = parsedUrl.pathname || '/';
-  parsedRequest.query = parsedUrl.query;
-  return parsedRequest;
-}
-
-// tslint:disable-next-line:no-any
-export type ControllerClass = Constructor<any>;
-
 export class RoutingTable {
-  private readonly _routes: RouteEntry[] = [];
-
-  registerController(controller: ControllerClass, spec: ControllerSpec) {
-    assert(
-      typeof spec === 'object' && !!spec,
-      'API specification must be a non-null object',
+  constructor(
+    private readonly _router: RestRouter = new TrieRouter(),
+    private _externalRoutes?: ExternalExpressRoutes,
+  ) {}
+
+  /**
+   * Register a controller as the route
+   * @param spec
+   * @param controllerCtor
+   * @param controllerFactory
+   */
+  registerController<T>(
+    spec: ControllerSpec,
+    controllerCtor: ControllerClass<T>,
+    controllerFactory?: ControllerFactory<T>,
+  ) {
+    const routes = createRoutesForController(
+      spec,
+      controllerCtor,
+      controllerFactory,
     );
-    if (!spec.paths || !Object.keys(spec.paths).length) {
-      return;
-    }
-
-    debug('Registering Controller with API', spec);
-
-    const basePath = spec.basePath || '/';
-    for (const p in spec.paths) {
-      for (const verb in spec.paths[p]) {
-        const opSpec: OperationObject = spec.paths[p][verb];
-        const fullPath = RoutingTable.joinPath(basePath, p);
-        const route = new ControllerRoute(verb, fullPath, opSpec, controller);
-        this.registerRoute(route);
-      }
+    for (const route of routes) {
+      this.registerRoute(route);
     }
   }
 
-  static joinPath(basePath: string, path: string) {
-    const fullPath = [basePath, path]
-      .join('/') // Join by /
-      .replace(/(\/){2,}/g, '/') // Remove extra /
-      .replace(/\/$/, '') // Remove trailing /
-      .replace(/^(\/)?/, '/'); // Add leading /
-    return fullPath;
-  }
-
+  /**
+   * Register a route
+   * @param route - A route entry
+   */
   registerRoute(route: RouteEntry) {
     // TODO(bajtos) handle the case where opSpec.parameters contains $ref
     // See https://github.com/strongloop/loopback-next/issues/435
-    debug(
-      'Registering route %s %s -> %s(%s)',
-      route.verb,
-      route.path,
-      route.describe(),
-      describeOperationParameters(route.spec),
-    );
-    this._routes.push(route);
+    /* istanbul ignore if */
+    if (debug.enabled) {
+      debug(
+        'Registering route %s %s -> %s(%s)',
+        route.verb.toUpperCase(),
+        route.path,
+        route.describe(),
+        describeOperationParameters(route.spec),
+      );
+    }
+
+    validateApiPath(route.path);
+
+    this._router.add(route);
   }
 
-  describeApiPaths(): PathsObject {
-    const paths: PathsObject = {};
+  describeApiPaths(): PathObject {
+    const paths: PathObject = {};
 
-    for (const route of this._routes) {
+    for (const route of this._router.list()) {
+      if (route.spec['x-visibility'] === 'undocumented') continue;
       if (!paths[route.path]) {
         paths[route.path] = {};
       }
@@ -113,215 +93,39 @@ export class RoutingTable {
     return paths;
   }
 
-  find(request: ParsedRequest): ResolvedRoute {
-    for (const entry of this._routes) {
-      const match = entry.match(request);
-      if (match) return match;
-    }
+  /**
+   * Map a request to a route
+   * @param request
+   */
+  find(request: Request): ResolvedRoute {
+    debug('Finding route for %s %s', request.method, request.path);
 
-    throw new HttpErrors.NotFound(
-      `Endpoint "${request.method} ${request.path}" not found.`,
-    );
-  }
-}
-
-export interface RouteEntry {
-  readonly verb: string;
-  readonly path: string;
-  readonly spec: OperationObject;
+    const found = this._router.find(request);
 
-  match(request: ParsedRequest): ResolvedRoute | undefined;
-
-  updateBindings(requestContext: Context): void;
-  invokeHandler(
-    requestContext: Context,
-    args: OperationArgs,
-  ): Promise<OperationRetval>;
-
-  describe(): string;
-}
-
-export interface ResolvedRoute extends RouteEntry {
-  readonly pathParams: PathParameterValues;
-}
-
-export abstract class BaseRoute implements RouteEntry {
-  public readonly verb: string;
-  private readonly _keys: pathToRegexp.Key[] = [];
-  private readonly _pathRegexp: RegExp;
-
-  constructor(
-    verb: string,
-    public readonly path: string,
-    public readonly spec: OperationObject,
-  ) {
-    this.verb = verb.toLowerCase();
-
-    // In Swagger, path parameters are wrapped in `{}`.
-    // In Express.js, path parameters are prefixed with `:`
-    path = path.replace(/{([^}]*)}(\/|$)/g, ':$1$2');
-    this._pathRegexp = pathToRegexp(path, this._keys, {
-      strict: false,
-      end: true,
-    });
-  }
-
-  match(request: ParsedRequest): ResolvedRoute | undefined {
-    debug('trying endpoint', this);
-    if (this.verb !== request.method!.toLowerCase()) {
-      debug(' -> verb mismatch');
-      return undefined;
+    if (found) {
+      debug('Route matched: %j', found);
+      return found;
     }
 
-    const match = this._pathRegexp.exec(request.path);
-    if (!match) {
-      debug(' -> path mismatch');
-      return undefined;
-    }
-
-    const pathParams = this._buildPathParams(match);
-    debug(' -> found with params: %j', pathParams);
-
-    return createResolvedRoute(this, pathParams);
-  }
-
-  abstract updateBindings(requestContext: Context): void;
-
-  abstract invokeHandler(
-    requestContext: Context,
-    args: OperationArgs,
-  ): Promise<OperationRetval>;
-
-  describe(): string {
-    return `"${this.verb} ${this.path}"`;
-  }
-
-  private _buildPathParams(pathMatch: RegExpExecArray): PathParameterValues {
-    const pathParams = Object.create(null);
-    for (const ix in this._keys) {
-      const key = this._keys[ix];
-      const matchIndex = +ix + 1;
-      pathParams[key.name] = pathMatch[matchIndex];
-    }
-    return pathParams;
-  }
-}
-
-export function createResolvedRoute(
-  route: RouteEntry,
-  pathParams: PathParameterValues,
-): ResolvedRoute {
-  return Object.create(route, {
-    pathParams: {
-      writable: false,
-      value: pathParams,
-    },
-  });
-}
-
-export class Route extends BaseRoute {
-  constructor(
-    verb: string,
-    path: string,
-    public readonly spec: OperationObject,
-    protected readonly _handler: Function,
-  ) {
-    super(verb, path, spec);
-  }
-
-  describe(): string {
-    return this._handler.name || super.describe();
-  }
-
-  updateBindings(requestContext: Context) {
-    // no-op
-  }
-
-  async invokeHandler(
-    requestContext: Context,
-    args: OperationArgs,
-  ): Promise<OperationRetval> {
-    return await this._handler(...args);
-  }
-}
-
-type ControllerInstance = {[opName: string]: Function};
-
-export class ControllerRoute extends BaseRoute {
-  protected readonly _methodName: string;
-
-  constructor(
-    verb: string,
-    path: string,
-    spec: OperationObject,
-    protected readonly _controllerCtor: ControllerClass,
-    methodName?: string,
-  ) {
-    super(
-      verb,
-      path,
-      // Add x-controller-name and x-operation-name if not present
-      Object.assign(
-        {
-          'x-controller-name': _controllerCtor.name,
-          'x-operation-name': methodName,
-        },
-        spec,
-      ),
-    );
-
-    if (!methodName) {
-      methodName = this.spec['x-operation-name'];
-    }
-
-    if (!methodName) {
-      throw new Error(
-        'methodName must be provided either via the ControllerRoute argument ' +
-          'or via "x-operation-name" extension field in OpenAPI spec. ' +
-          `Operation: "${verb} ${path}" ` +
-          `Controller: ${this._controllerCtor.name}.`,
+    if (this._externalRoutes) {
+      debug(
+        'No API route found for %s %s, trying to find an external Express route',
+        request.method,
+        request.path,
       );
-    }
 
-    this._methodName = methodName;
-  }
-
-  describe(): string {
-    return `${this._controllerCtor.name}.${this._methodName}`;
-  }
-
-  updateBindings(requestContext: Context) {
-    const ctor = this._controllerCtor;
-    requestContext.bind('controller.current.ctor').to(ctor);
-    requestContext.bind('controller.current.operation').to(this._methodName);
-  }
-
-  async invokeHandler(
-    requestContext: Context,
-    args: OperationArgs,
-  ): Promise<OperationRetval> {
-    const controller = await this._createControllerInstance(requestContext);
-    if (typeof controller[this._methodName] !== 'function') {
-      throw new HttpErrors.NotFound(
-        `Controller method not found: ${this.describe()}`,
-      );
+      return this._externalRoutes.find(request);
     }
-    return await controller[this._methodName](...args);
-  }
 
-  private async _createControllerInstance(
-    requestContext: Context,
-  ): Promise<ControllerInstance> {
-    const valueOrPromise = instantiateClass(
-      this._controllerCtor,
-      requestContext,
+    debug('No route found for %s %s', request.method, request.path);
+    throw new HttpErrors.NotFound(
+      `Endpoint "${request.method} ${request.path}" not found.`,
     );
-    return (await Promise.resolve(valueOrPromise)) as ControllerInstance;
   }
 }
 
 function describeOperationParameters(opSpec: OperationObject) {
   return ((opSpec.parameters as ParameterObject[]) || [])
-    .map(p => p.name)
+    .map(p => p?.name || '')
     .join(', ');
 }

package/src/router/trie-router.ts

@@ -0,0 +1,57 @@
+// Copyright IBM Corp. 2018,2019. All Rights Reserved.
+// Node module: @loopback/rest
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {inject} from '@loopback/context';
+import {inspect} from 'util';
+import {RestBindings} from '../keys';
+import {RestRouterOptions} from './rest-router';
+import {createResolvedRoute, ResolvedRoute, RouteEntry} from './route-entry';
+import {BaseRouter} from './router-base';
+import {Trie} from './trie';
+
+const debug = require('debug')('loopback:rest:router:trie');
+
+/**
+ * Router implementation based on trie
+ */
+export class TrieRouter extends BaseRouter {
+  private trie = new Trie<RouteEntry>();
+
+  constructor(
+    @inject(RestBindings.ROUTER_OPTIONS, {optional: true})
+    options?: RestRouterOptions,
+  ) {
+    super(options);
+  }
+
+  protected addRouteWithPathVars(route: RouteEntry) {
+    // Add the route to the trie
+    const key = this.getKeyForRoute(route);
+    this.trie.create(key, route);
+  }
+
+  protected findRouteWithPathVars(
+    verb: string,
+    path: string,
+  ): ResolvedRoute | undefined {
+    const key = this.getKey(verb, path);
+
+    const found = this.trie.match(key);
+    debug('Route matched: %j', found);
+
+    if (found) {
+      const route = found.node.value!;
+      if (route) {
+        debug('Route found: %s', inspect(route, {depth: 5}));
+        return createResolvedRoute(route, found.params ?? {});
+      }
+    }
+    return undefined;
+  }
+
+  protected listRoutesWithPathVars() {
+    return this.trie.list().map(n => n.value);
+  }
+}

package/src/router/trie.ts

@@ -0,0 +1,233 @@
+// Copyright IBM Corp. 2018,2019. All Rights Reserved.
+// Node module: @loopback/rest
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {Key, pathToRegexp} from 'path-to-regexp';
+import {PathParameterValues} from '../types';
+import {toExpressPath} from './openapi-path';
+
+/**
+ * A Node in the trie
+ */
+export interface Node<T> {
+  /**
+   * Key of the node
+   */
+  key: string;
+  /**
+   * Value of the node
+   */
+  value?: T;
+  /**
+   * Children of the node
+   */
+  readonly children: {[key: string]: Node<T>};
+
+  /**
+   * Regular expression for the template
+   */
+  regexp?: RegExp;
+  /**
+   * Names of the node if it contains named parameters
+   */
+  names?: string[];
+}
+
+export type NodeWithValue<T> = Node<T> & {value: T};
+
+export interface ResolvedNode<T> {
+  node: Node<T>;
+  params?: PathParameterValues;
+}
+
+/**
+ * An implementation of trie for routes. The key hierarchy is built with parts
+ * of the route path delimited by `/`
+ */
+export class Trie<T> {
+  readonly root: Node<T> = {key: '', children: {}};
+
+  /**
+   * Create a node for a given path template
+   * @param pathTemplate - The path template,
+   * @param value - Value of the route
+   */
+  create(routeTemplate: string, value: T) {
+    const keys = routeTemplate.split('/').filter(Boolean);
+    return createNode(keys, 0, value, this.root);
+  }
+
+  /**
+   * Match a route path against the trie
+   * @param path - The route path, such as `/customers/c01`
+   */
+  match(
+    path: string,
+  ): (ResolvedNode<T> & {node: NodeWithValue<T>}) | undefined {
+    const keys = path.split('/').filter(Boolean);
+    const params = {};
+    const resolved = search(keys, 0, params, this.root);
+    if (resolved == null || !isNodeWithValue(resolved.node)) return undefined;
+    return {
+      node: resolved.node,
+      params: resolved.params,
+    };
+  }
+
+  /**
+   * List all nodes with value of the trie
+   */
+  list(): NodeWithValue<T>[] {
+    const nodes: NodeWithValue<T>[] = [];
+    traverse(this.root, node => {
+      nodes.push(node);
+    });
+    return nodes;
+  }
+}
+
+function isNodeWithValue<T>(node: Node<T>): node is NodeWithValue<T> {
+  return node.value != null;
+}
+
+/**
+ * Use depth-first preorder traversal to list all nodes with values
+ * @param root - Root node
+ * @param visitor - A function to process nodes with values
+ */
+function traverse<T>(root: Node<T>, visitor: (node: NodeWithValue<T>) => void) {
+  if (isNodeWithValue(root)) visitor(root);
+  for (const k in root.children) {
+    traverse(root.children[k], visitor);
+  }
+}
+
+/**
+ * Match the given key to one or more children of the parent node
+ * @param key - Key
+ * @param parent - Parent node
+ */
+function matchChildren<T>(key: string, parent: Node<T>): ResolvedNode<T>[] {
+  const resolvedNodes: ResolvedNode<T>[] = [];
+  // Match key literal first
+  let child = parent.children[key];
+  if (child) {
+    resolvedNodes.push({
+      node: child,
+    });
+    return resolvedNodes;
+  }
+
+  // Match templates
+  for (const k in parent.children) {
+    child = parent.children[k];
+    if (!child.names || !child.regexp) continue;
+    const match = child.regexp.exec(key);
+    if (match) {
+      const resolved: ResolvedNode<T> = {params: {}, node: child};
+      let i = 0;
+      for (const n of child.names) {
+        const val = match[++i];
+        resolved.params![n] = decodeURIComponent(val);
+      }
+      resolvedNodes.push(resolved);
+    }
+  }
+  return resolvedNodes;
+}
+
+/**
+ * Search a sub list of keys against the parent node
+ * @param keys - An array of keys
+ * @param index - Starting index of the key list
+ * @param params - An object to receive resolved parameter values
+ * @param parent - Parent node
+ */
+function search<T>(
+  keys: string[],
+  index: number,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  params: {[name: string]: any},
+  parent: Node<T>,
+): ResolvedNode<T> | undefined {
+  const key = keys[index];
+  const resolved: ResolvedNode<T> = {node: parent, params};
+  if (key === undefined) return resolved;
+
+  const children = matchChildren(key, parent);
+  if (children.length === 0) return undefined;
+  // There might be multiple matches, such as `/users/{id}` and `/users/{userId}`
+  for (const child of children) {
+    const result = search(keys, index + 1, params, child.node);
+    if (result && isNodeWithValue(result.node)) {
+      Object.assign(params, child.params);
+      return result;
+    }
+  }
+  // no matches found
+  return undefined;
+}
+
+/**
+ * Create a node for a sub list of keys against the parent node
+ * @param keys - An array of keys
+ * @param index - Starting index of the key list
+ * @param value - Value of the node
+ * @param parent - Parent node
+ */
+function createNode<T>(
+  keys: string[],
+  index: number,
+  value: T,
+  parent: Node<T>,
+): Node<T> {
+  const key = keys[index];
+  if (key === undefined) return parent;
+
+  const isLast = keys.length - 1 === index;
+  let child = parent.children[key];
+  if (child != null) {
+    // Found an existing node
+    if (isLast) {
+      if (child.value == null) {
+        child.value = value;
+      } else {
+        if (child.value !== value) {
+          throw new Error(
+            'Duplicate key found with different value: ' + keys.join('/'),
+          );
+        }
+      }
+    }
+    return createNode(keys, index + 1, value, child);
+  }
+
+  /**
+   * Build a new node
+   */
+  child = {
+    children: {},
+    key: key,
+  };
+
+  if (isLast) {
+    child.value = value;
+  }
+
+  // Check if the key has variables such as `{var}`
+  const path = toExpressPath(key);
+  const params: Key[] = [];
+  const re = pathToRegexp(path, params);
+
+  if (params.length) {
+    child.names = params.map(p => `${p.name}`);
+    child.regexp = re;
+  }
+
+  // Add the node to the parent
+  parent.children[key] = child;
+
+  // Create nodes for rest of the keys
+  return createNode(keys, index + 1, value, child);
+}